One of the most frequent problems faced in a running Documentum is changes made to templates. At any given point of time, there is a certain amount of content created from a template file. If, owing to some business needs, the structure of this template file needs to change, what happens to the existing content that has already been made using the older version of the template?
Would the template still function well? Would the new template structure be reflected automatically in the existing content? Would you have to re-create all the existing content all over again so it conforms to the updated template structure?
Extremely pertinent questions—the short answer is: No! Documentum developers anticipated such situations and have included Instruction Files in Web Publisher to help you update the structure of existing content as per the updated template file.
Let's consider a small example.
Imagine a template file that content creators use to create a Frequently Asked Questions (FAQ) section for their website. The template has the following fields in the editor:
- A repeating block allowing multiple values to be entered for the template fields
- Question field
- Answer field
Let us assume the content creators create content based on the above template structure, providing values for multiple question-answer sets. However, after a certain time, the business team realizes that they need to tag the questions according to their relevance while creating the content. In short, they want to classify questions as Very important, Important, and Medium while creating content from the same template.
The only two approaches we can take in such a situation are:
- Make a separate template by including all required fields such as Question, Answer, and Relevance Order, and re-create all existing content using this new template.
- Modify the existing template by introducing a third field called Relevance Order and manually edit/update all the existing content.
In general, most business users resort to the second approach because of the following reasons:
- It saves them the overhead of maintaining two versions of the same template.
- It saves them the effort of re-creating content all over again.
Web Publisher Instruction Files helps us achieve this by providing configurable XML elements that update the existing XML content files as per the updated template structure without us having to manually edit/update existing content files.
Instruction Files can perform a wide array of functions on existing XML content files such as those shown in figure 17.1.
|
Function performed |
Instruction File element |
|---|---|
|
Insert new XML element |
|
|
Delete an existing XML element |
|
|
Insert an attribute to XML element |
|
|
Delete an attribute from XML element |
|
|
Update the value of an existing XML element |
|
The Documentum developer site provides a wizard tool for creating Instruction Files. Please visit the following URL for further details:
http://customernet.documentum.com/developer/tippage.htm
You can download this tool and follow the instructions mentioned in the Instruction File Builder PDF to avoid creating the Instruction Files manually.
Note
Note that the Instruction Files in this book have been created using standard text/XML editors and not the Instruction File Builder tool.
It is worth mentioning a few limitations of Instruction Files before jumping into the specifics of their usage.
In order to update the value of an existing XML element, the <update-element-value> Instruction File element is used. The prerequisite, however, is that the XML element that is being updated should not contain any child element(s).
For example, if <update-element-value> is used to update a <BOOK> XML element, then the <BOOK> element should not have any child elements. The following <BOOK> element cannot be updated:
<BOOK> <AUTHOR></AUTHOR> </BOOK>
On similar lines, <update-element-value> works fine if and only if the XML element being updated is not empty. In short, it has some text existing in the element (which might include white spaces). The following <BOOK> element cannot be updated:
<BOOK></BOOK>
However, the following XML element is a valid candidate for <update-element-value>:
<BOOK>ABC</BOOK>
For those conversant with XML/XSL, relative path does not work with Instruction Files. The XML Path Language (XPath) // (double slash) expression fails while working with Instruction Files and should not be used as a rule.
An XML file cannot be updated with an Instruction File in the following conditions:
- If the XML file is in the Staging state of its lifecycle
- If the XML file is in a checked-out state
- If the XML file is a part of a Change Set
An Instruction File always versions a file (i.e. provides a new version number to an XML file) even if the instructions do not make any changes to the structure of the XML file in question. Also, the files are placed in the WIP state of their lifecycle.
For example, let's take a scenario where the <delete-attribute> instruction is used in an Instruction File to remove the attribute bookname from an XML element <BOOK>.
If the <BOOK> XML element does not contain any attribute by the name bookname, the instruction <delete-attribute> still works on the <BOOK> XML element, and when it does not find any attribute by the name bookname, it still saves the XML file as a new version.