Let us take a few examples to understand how Instruction Files work in Documentum.
Let us walk through a very simple example where content is created from a simple template XML file and later an XML element is removed from the template file. The existing content is updated via a simple Instruction File using the <delete-element>
instruction.
Original_Template.xml
) and its associated Rules file (Original_TemplateRules.xml
) as per the following structure:Template File Original_Template.xml
:
<?xml version="1.0" encoding="UTF-8"?> <PRODUCTINFO> <NAME/> <SHORTDESC/> <COST/> <PRODUCTTYPE/> </PRODUCTINFO> <?xml version="1.0" encoding="UTF-8"?> <rules> <tagcontent tag_name="NAME"> <textline instruction="Please enter a name" label="Product name:" required="Y"> </textline> </tagcontent> <tagcontent tag_name="SHORTDESC"> <content instruction="please provide a short description for product" label="Product Description:" lines="5"> </content> </tagcontent> <tagcontent tag_name="COST"> <textline instruction="Please enter cost in dollars" label="Cost:"> </textline> </tagcontent> <tagcontent tag_name="PRODUCTTYPE"> <choice instruction="Please choose a type" label="Product Type:" values="Type A,Type B,Type C"> </choice> </tagcontent> </rules>
Original_Template.xml
and provide names to them (refer to figures 17.2 and 17.3). For example: Testing1_Original_Template.xml
and Testing2_Original_Template.xml
.You can view the XML structure of the created content from File | Export in Web Publisher, and export the content XML files on the local machine accessing Web Publisher.
Following are the content XML files for the content created above. These have been created from the template file Original_Template.xml
version 1.0:
Testing1_Original_Template.xml
:
<?xml version="1.0" encoding="UTF-8"?> <PRODUCTINFO> <NAME>Prod A</NAME> <SHORTDESC> <p> This is of type A </p> </SHORTDESC> <COST>$ 120</COST> <PRODUCTTYPE>Type A</PRODUCTTYPE> </PRODUCTINFO> <?xml version="1.0" encoding="UTF-8"?> <PRODUCTINFO> <NAME>Prod B</NAME> <SHORTDESC> <p> This is of type B </p> </SHORTDESC> <COST>$ 175</COST> <PRODUCTTYPE>Type B</PRODUCTTYPE> </PRODUCTINFO>
<COST/>
XML element.Following is the template file (version 2.0) Original_Template.xml
after modification.
<?xml version="1.0" encoding="UTF-8"?> <PRODUCTINFO> <NAME/> <SHORTDESC/> <PRODUCTTYPE/> </PRODUCTINFO>
Delete_Element_Instruction.xml
) that updates content XML files by removing their contained <COST>
XML element.The following Instruction File (Delete_Element_Instruction.xml
) can be used in such a scenario:
<?xml version="1.0" encoding="UTF-8"?> <instructions xmlns ="http://www.documentum.com/wp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.documentum.com/wp instructions.xsd"> <delete-element> <path>/PRODUCTINFO</path> <nodename>COST</nodename> <comments>Deleting COST element</comments> </delete-element> </instructions>
<delete-element>:
Instruction File element to delete an existing XML element<path>:
XPath expression to identify the path where the XML element to be deleted currently exists<nodename>:
Name of the target node (XML element) to be deleted<comments>:
Optional comments stating the purpose of the Instruction File Delete_Element_Instruction.xml
Instruction File by choosing File | Import as shown in figures 17.4 and 17.5. Original_Template.xml
under Site Manager | Templates. Choose the modified template file Original_Template.xml
and click on the View | Versions option as shown in figure 17.6.After choosing version 1.0, click the Where Used button shown at the top right-hand side as shown in figure 17.7. All content files created from the selected version of the template file are shown.
Choose the content file(s) to be updated by the Instruction File and click the Update Content button at the top right-hand corner, as shown in figure 17.8.
We have chosen only the Testing1_Original_Template.xml
content file.
Delete_Element_Instruction.xml
. Finally click on OK.Example: When you update XML Content Task using the Delete_Element_Instruction.xml
Instructions File, the UPDATE_XMLCONTENT_1126683079171
log file is created in the WcmLog
folder.
Testing1_Original_Template.xml
after the Instruction File has been applied as shown in figure 17.11. You can see that the version of the Testing1_Original_Template.xml
file is now 1.1 (as opposed to its version 1.0 before the Instruction File was applied). Choose the file and click on File | Export to export the updated content file to your client machine.Updated content file Testing1_Original_Template.xml
:
<?xml version="1.0" encoding="UTF-8"?> <PRODUCTINFO> <NAME>Prod A</NAME> <SHORTDESC> <p> This is of type A </p> </SHORTDESC> <PRODUCTTYPE>Type A</PRODUCTTYPE> </PRODUCTINFO>
Notice the absence of the <COST>
XML element from this content file.
The other content file (Testing2_Original_Template.xml
) is still in version 1.0 since it was not updated via the Instruction File.
If you edit the content Testing1_Original_Template.xml
using Web Publisher editor, the Cost: field will not be shown as per the updated template structure. Figure 17.12 shows the updated content file without the Cost field, as seen in Web Publisher editor.
Opening the other content file Testing2_Original_Template.xml
in Web Publisher editor will still show the Cost: field as per the older version of template file.
This was a simple example to delete an existing XML element from a content file. Let us now go ahead and take up some more examples so that we can understand the power of Instruction Files in a better fashion.
Let us take an example where content is created from a simple template XML file and then a new XML element is added to the template file. The existing content is updated via an Instruction File using the <insert-element>
instruction.
Original_Template.xml
) and its associated Rules file (Original_TemplateRules.xml
) as per the following structure:Updated Template file Original_Template.xml
:
<?xml version="1.0" encoding="UTF-8"?>
<PRODUCTINFO>
<NAME/>
<SHORTDESC/>
<PRODUCTTYPE/>
<PRICEINFO/>
</PRODUCTINFO>
Note that we have added a new <PRICEINFO>
XML element to the template file.
Updated Rules file Original_TemplateRules.xml
:
<?xml version="1.0" encoding="UTF-8"?>
<rules>
<tagcontent tag_name="NAME">
<textline instruction="Please enter a name" label="Product name:" required="Y">
</textline>
</tagcontent>
<tagcontent tag_name="SHORTDESC">
<content instruction="please provide a short description for product" label="Product Description:" lines="5">
</content>
</tagcontent>
<tagcontent tag_name="COST">
<textline instruction="Please enter cost in dollars" label="Cost:">
</textline>
</tagcontent>
<tagcontent tag_name="PRODUCTTYPE">
<choice instruction="Please choose a type" label="Product Type:" values="Type A,Type B,Type C">
</choice>
</tagcontent>
<tagcontent tag_name="PRICEINFO">
<textline charlength="50" instruction="Please enter a price for the product" abel="Enter price:">
</textline>
</tagcontent>
</rules>
Add_Element_Instruction.xml
) that updates content XML files by adding a new <PRICEINFO>
XML element.The following Instruction file (Add_Element_Instruction.xml
) can be used in such a scenario:
<?xml version="1.0" encoding="UTF-8"?> <instructions xmlns ="http://www.documentum.com/wp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.documentum.com/wp instructions.xsd"> <insert-element> <path>/PRODUCTINFO</path> <nodename>PRICEINFO</nodename> <value>$ 100</value> <comments>testing insert element PRICEINFO</comments> </insert-element> </instructions>
Anatomy of the above Instruction File:
<insert-element>:
Instruction File element to add an XML element to an XML content file<path>:
XPath expression to identify the path where the XML element to be inserted/added currently exists<nodename>:
Name of the target node (XML element) to be inserted<value>:
Text value of the XML element to be set<comments>:
Optional comments stating the purpose of the Instruction File Add_Element_Instruction.xml
Instruction File by choosing the File | Import option. Complete all the steps described in the previous example. Testing1_Original_Template.xml
with the Instruction File Add_Element_Instruction.xml
. You can verify that the version of the Testing1_Original_Template.xml
file has been updated.Choose the file and click on File | Export to export the updated content file on your client machine.
Here is the updated content file Testing1_Original_Template.xml
after the Add_Element_Instruction.xml
Instruction File has been applied:
<?xml version="1.0" encoding="UTF-8"?>
<PRODUCTINFO>
<NAME>Prod A</NAME>
<SHORTDESC>
<p>
This is of type A
</p>
</SHORTDESC>
<PRODUCTTYPE>Type A</PRODUCTTYPE>
<PRICEINFO>$ 100</PRICEINFO>
</PRODUCTINFO>
Notice that the <PRICEINFO>
XML element has been added in this content file with the value $ 100
.
The other content file (Testing2_Original_Template.xml
) is still in version 1.0 since it was not updated via the Instruction File.
If you edit the content Testing1_Original_Template.xml
using Web Publisher editor, the Enter price: field will be shown as per the updated template structure (refer to figure 17.14).
Let us now take an example where content is created from a simple template XML file and then the value of an XML element in content files is to be updated. The existing content is updated via an Instruction File using the <update-element-value>
instruction.
Update_Element_Value_Instruction.xml
that updates content XML files by updating the value of their <PRICEINFO>
XML element.The following Instruction File (Update_Element_Value_Instruction.xml
) can be used in such a scenario:
<?xml version="1.0" encoding="UTF-8"?> <instructions xmlns ="http://www.documentum.com/wp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.documentum.com/wp instructions.xsd"> <update-element-value> <path>/PRODUCTINFO</path> <nodename>PRICEINFO</nodename> <value>Price Not available</value> <comments>Updating the value of PRICEINFO element</comments> </update-element-value> </instructions>
Anatomy of this Instruction File:
<update-element-value>:
Instruction File element to set a new text value for the specified XML element in an XML content file<path>:
XPath expression to identify the path where the XML element to be updated currently exists<nodename>:
Name of the target node (XML element) whose value needs to be updated<value>:
The new text value that needs to be set for the XML element in question<comments>:
Optional comments stating the purpose of the Instruction File Update_Element_Value_Instruction.xml
Instruction File by choosing the File | Import option. Complete all the steps as described in the first example. Testing1_Original_Template.xml
with the Instruction File Update_Element_Value_Instruction.xml
. You can verify that the version of the Testing1_Original_Template.xml
file has been updated.The updated content file Testing1_Original_Template.xml
after Update_Element_Value_Instruction.xml
Instruction File has been applied:
<?xml version="1.0" encoding="UTF-8"?> <PRODUCTINFO> <NAME>Prod A</NAME> <SHORTDESC> <p> This is of type A </p> </SHORTDESC> <PRODUCTTYPE>Type A</PRODUCTTYPE> <PRICEINFO> Price Not available </PRICEINFO> </PRODUCTINFO>
Notice that the value of the <PRICEINFO>
XML element has been updated in this content file with the value Price Not available
.
The other content file (Testing2_Original_Template.xml
) is still in version 1.0 since it was not updated via the Instruction File.
If you edit the content Testing1_Original_Template.xml
using Web Publisher editor, the Enter price: field will be shown as per the updated template structure (refer to figure 17.15).
This should give you all a fairly good understanding of Instruction Files and their usage scenarios. For a comprehensive understanding of Instruction Files, go through the Documentum Web Publisher Administration guide.
3.15.219.174