Implementing a Conref Push Mechanism in DITA

As a part of a DITAToo DITA CMS implementation for a customer, we were helping their documentation team to build information architecture and find out how DITAToo can support their processes. One of the challenges they were facing was handling content variations for OEM partners.

The company sells their products in the US, Europe, and some Asian countries. Most of the sales in the US are done directly, while European and Asian sales are done through local OEM partners. The documentation contains a fair amount of warnings and cautions that vary depending on the geographic area where the product is sold due to local regulations.

Basically, each OEM partner has their own set of such warnings which is specific just for this particular region. Local warnings should either replace the warnings suitable for the US or appear in addition to the US-specific warnings.

This could be easily done by conditionalizing the content, but because of legal and administrative reasons, the company didn’t want to deal with local warnings. Instead, they wanted the OEM partners to compile the documentation with local warnings somehow pushed into the original content. The company wanted OEM partners to compile the documentation for local markets on their own anyway, so it was just a logical step into this direction.

A solution that we offered them was based on the conref push mechanism introduced by DITA 1.2. We agreed that whenever there is a warning to be replaced, the company’s authors will assign an ID to this warning and share this ID with all the OEM partners. For example (we are under the NDA and are not allowed to use the actual content in examples):


<task id=”task_1″>
<title>Replacing a Light Bulb</title>
<note id=”replace_bulb_note”>Make sure the power is turned off</note>


Then the OEM partner’s authors (who already know the ID of the warning to be replaced) create a topic that contained the warning to be pushed and replace the note. For example:


<concept id=”concept_1″>
<title>Local Notes</title>
<note conaction=”pushreplace” conref=”Replacing_bulb.dita#task_1/replace_bulb_note”>To replace a light bulb, you must have a license issued by an authorized government institute.</note>

Now the partner needs to add a topicref to the topic with the local warning to the map and set the @processing-role attribute of the topicref to “resource-only“. During the publishing, the local note replaces the original note.

OEM partners received a user account in DITAToo with limited access permissions. Limited permissions mean that an OEM partner:

  • Has access to the content created by the company in the read-only mode.
  • Can upload topics with local warnings to a certain folder assigned to this partner so that each partner can see only their own notes, but not the topics uploaded by other partners.
  • Can assemble their own projects from the content created by the company and add the topic with the local warnings to the project. Each partner can see only their own projects, but not projects created by other partners.
  • Can publish the project.

 This has provided a solution to the customer’s needs. By the way, when implementing DITA and DITAToo for this customer, we’ve gotten ideas on a plenty of new features that we can add so a lot of new things are about to come!

Stay tuned!

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Post Navigation