The first major update of 2021 to DoX CMS added a WebDav-based option to edit content with an external editor The instructions for how to set up the network drive are available in our user manual. However, DoX CMS also includes many features such as variables, tags, and element classes which are not automatically supported by external editors. In this article, I will introduce the basics for how to integrate the oXygen XML editor with DoX CMS, Depending on the needs of our customers, I will likely eventually do the same for at least Adobe FrameMaker. Further development on this feature will make the process easier, though, as we already know the next steps to improve on when integrating external editors.
Both tags and element classes can be included by adding them as classes for profiling or conditioning text. You can place variables by writing their identifiers as part of the text yourself. This has always been an option in DoX CMS as well. Internal links are yet another feature where it must be clarified how they must be done due to the restrictions imposed by oXygen‘s interface. Once I have clarified the proper methods, I will touch upon some features of oXygen which will break the files as well as the remaining tasks related to support for external editors, which we will finish as soon as possible.
Tags and Element Classes

For now, support for both tags and element classes must be set up manually in the settings for oXygen. As such, we recommend that you prepare the whole set of required tags and element classes in advance. You reduce the need to add individual tags or element classes later as well as the risk of forgetting to add a new class created by someone else to your personal settings later when you do this. Unlike DoX CMS which is browser-based, each installation of an external editor must be set up separately in a manner coordinated by the users.
The foundation for integrating both these features lies in ‘Profiling Settings’ which you can find in the top toolbar under DITA > Profiling/Conditioning Text. Alternatively, you can enter the same menu through Options > Preferences after which you must navigate to the following menu: Editor > Edit Modes > Author > Profiling/Conditional Text > Attributes and Condition Sets.
Once you are in the correct menu, click on ‘New’ under ‘Profiling Attributes’. This will let you add new classes which correspond to the markup for tags and element classes in DoX CMS.
Define ‘Document type’ as ‘*DITA*’. The two asterisks are both mandatory. When you do this, the values that you add can be designated for use in content which uses a DITA schema. More details on this are provided below.
For‘Attribute name’, you must use the proper internal identifier in DoX CMS for the class in question. Each category of tags is its own class in this respect. Element classes have their own identifier.
The identifier for categories of tags is ‘data-doxattribute-category’ wherein you must replace ‘category’ with the (hidden) identifier of the tag used for the category itself. You can find tags and the identifiers for their categories in the Tags menu in DoX CMS, when you select the relevamt tag and use the Details command. For example, a category called ‘Manual’ would usually have the full identifier ‘data-doxattribute-Manual’. The two exceptions for when the (hidden) identifier differs from the name of the tag are that the name has been edited at some point or the two were purposefully differentiated when the tag was first specified. In such instances, you must check the proper identifier in the manner specified above.
The identifer for element classes that you must use for ‘Attribute name’ is always the same: ‘doxelementclass’. In their case, all further differentiation is based on the different values for this class.
If you so desire, you may use a different value ‘Display Name’ than the name in DoX CMS. We strongly recommend that you use a uniform naming scheme between the two systems, though, and to name categories something like ‘Tag: Category’ where you replace ‘category’ with the name of the relevat category of tags such as ‘Manual’.
Once you have added a class, you must add its possible values in the same menu by clicking on ‘New’ below the table of possible values. As above, you must use the identifier for a given tag or element class in the ‘Value’field. In the case of element classes, their name and identifier are identical. Thus, you can use the name of an element class in the system directly. You can find the identifiers for tags in their Details-menu in the manner explained above. You can add any name for the value in its ‘Label’ field but we continue to recommend that you use the same naming scheme across systems. You can also add a brief description in the ‘Description’ field.
After you have added all the tags in a tqag category or all available element classes as the values for a class, you can confirm the details of this attribute. The correct choice for instances with multiple values from the same class is the default option, ‘Multiple values separated by <space>’, as it corresponds to how DoX CMS functions in this respect.
Repeat the steps specified above for each category of tags in your company’s copy of DoX CMS and its element classes. Afterwards, add a new profiling condition set which includes them all. To do this, click on ‘New’ below ‘Profiling Condition Sets’.
Name the profiling condition set however you like and select ‘*DITA*’ as the value for its ‘Document Type’ field, too. Then you must click the selection fields related to each class to include them in the set. As you select a class, you also select each of its possible values. You can remove some values from use by separately removing this selection for them.
Once this process is finished and you select the profiling condition set that you assembled to be used, you may add values for the attributes that it contains to elements as usual. In other words, you can for example click on a part of a document with the right mouse button and select the command ‘Edit Profiling Attributes’. By selecting the tags or element classes from the set that shows when you do this, you add them to the element in question.
Variables
It is considerably simpler to use variables. All you need do is to write their identifiers directly as part of the text.
The identifier for a variable is its name inside two pairs of curly brackets. For example, using a variable of any kind with the name ‘Product ID’ would involve you writing ‘{{Product ID}}’ in the text. You must use the exact name of the variable: this is inclusive of both spacing and capitalization.
Remember that you can also use the system variables in DoX CMS in this manner. Further details on them are available in our user manual. This is a group of pre-defined variables which add a value from within the system’s database in the specified position, such as the title of the publication or its revision number.
Internal Links
Usually, you would use the ‘Link’ command to add links in oXygen. Should you try to do this for other topics or the elements in them, though, the link format would use the full file name of the topic in question. Meanwhile, DoX CMS only recognizes links which use the identifiers for topics rather than their file names.
To bypass this problem, you must instead first add an empty xref element from oXygen‘s list of elements. Once it has been added, you can change its DITA properties directly. This enables you to write the href value for it yourself. You can still first use the ‘Link’feature and then directly edit the href value for the link in the same manner. If you do this, it will add redundant extra steps to adding links, as you will first need to specify a suitable intermediate value for each.
What You Cannot Do
As a program, oXygen includes many features without a direct implementation in the internal editor for DoX CMS. When you try to open content with parts that are incompatible with DoX CMS in this editor, you will either receive an error message or the content will simply not open at all. This section warns you of the things that you cannot do in oXygen to content in DoX CMS.
The greatest issues are caused by additional features such as highlighting content or adding comments to it. Both of these features in oXygenwill prevent you from opening the content in DoX CMS, because they leave behind code that the internal editor cannot read. DoX CMS also contains the options to add inline comments and review comments but both of these features apply a logic different from the comments that you can add in oXygen. There are undoubtedly other similar functions and thus, if some content refuses to open in DoX CMS, you must browse through it to make sure whether one of these functions has been used.
The next biggest source of problems are types of elements that are not compatible with DoX CMS. Should you add elements from full DITA which DoX CMS does not support, you will instead receive an error message that replaces said part of the document when you open such a topic in it. Saving at this point will make this change permanent. In either case, these contents are thus unusable, if the topics will ever be opened in DoX CMS for further editing. This is why you must not use them despite oXygen allowing their use. If you must use additional elements that are not supported by DoX CMS already, you can send a request to our support. Because we will comprehensively update the editor as soon as possible, any such additions are not likely to be immediate. However, we do take note of such requests and strive to include features that our customers need such as the ability to include mathematical equations in the updated editor.
The final (permanent) issue are properties that you cannot use in DoX CMS‘s menus for an element’s DITA attributes. DoX CMS limits the number of available properties by design, since text effects, for instance, should involve no need for the majority of the additional properties that DITA allows. This makes the user experience considerably less cumbersome. This also means that the system does not register any additional properties beyond its pre-determined capacity. Such additional properties will not result in lost content but the sustem will ignore and erase them, if you ever save that content in DoX CMS. There are some rare exceptions to this. For example, if the property itself is available for said type of element but its available values have been restricted in DoX CMS, other values will still work. Note elements can have types which the menu in DoX CMS does not contain such as ‘tip’, for instance.
Development of the Network Drive
In its current form, the WebDav network drive is not a comprehensive solution for integrating external editors. You could make the process of adding the classes in DoX CMS more automated, for one. Implementing this change is on our to-do list in addition to several other related features. These forms of further development that is underway are explained below.
The additional classes can be imported direcly from a DITAVAL file, which can be generated automatically based on the current state of your company’s copy of DoX CMS. This file will be made part of the WebDav environment, which will enable importing it to oXygen and make updates to the classifications only a matter or applying the updated DITAVAL file. The method that was introduced above is still needed for the time being, though, if a user will use the oXygen XML-editor as their editor of choice.
The WebDav network drive does not currently include the attachment files in your company’s copy of DoX CMS, either. As such, an external editor cannot find them for its preview of the content. This ought to be a simple change that we will implement as soon as possible.
If users come across any further issues with compatibility, we will respond to them. In such situations, contact our support to resolve the matter.