Content Management > PTC Server connection Document Bursting > Assigning PTC Server Properties
  
Assigning PTC Server Properties
In a document-type-specific burst configuration file, the dmsmetadata element is the last child of the createarg element. The dmsmetadata element contains the metadatarule and twowaymetadatarule elements. These elements enable you to use XML attributes or content as values for PTC Server property fields and to use PTC Server property fields as the values for XML attributes or content. You can use both PTC Server global attributes and system attributes for metadata assignment rules. For both one-way and two-way metadata rules, you must use file-based attributes for the associated PTC Server property. If you do not use a file-based attribute, the metadata rule will fail with an error.
Make sure that property assignment rules do not conflict with other PTC Server connection automatic metadata updates. For example, the PTC server might have a template for newly created objects that assigns object property values. Having multiple property update mechanisms might yield unexpected results.
Note that the PTC Server IBA PTC_DD_EXTENDED_DOC_TYPE is reserved for internal use by Arbortext. Do not use this global attribute in any metadata assignment rules contained in your document-type-specific burst configuration file. If you use this global attribute in a metadata assignment rule, your settings will be overwritten in a future release of Arbortext Editor.
Note also that if there is an error during the bursting process in passing the XML attribute values for a graphic object to the PTC Server properties, that graphic object is still added to the PTC Server. In this case, the PTC Server connection writes an error to the burst log, if enabled, or to the Arbortext Editor message window.
Using PTC Server System Attributes
You can use system attributes for metadata assignment rules. If you use PTC Sever system attributes, you must use a name for the system attribute in your burst configuration file that the PTC Server connection recognizes. The following table covers the supported PTC server system attributes, the required name for the system attributes in the burst configuration file, and the level of access. System attributes that are read-only can only be used in a twowaymetadatarule burst configuration file rule where the mode is toxml.
Supported PTC Server System Attributes
System Attribute Name
Burst Configuration File Name
Access Level
CMS Object Logical ID
IO_ATTR_LOGICAL_ID
read-only
Check In Comment
WC_COMMENT_ATTR
read-only
Created By
WC_CREATEDBY_ATTR
read-only
Created On
WC_CREATEDON_ATTR
read-only
Has Dependents
WC_HAS_DEPENDENTS_ATTR
read-only
Last Modified
WC_LASTUPDATEDON_ATTR
read-only
Is Latest On Latest
WC_LATEST_ON_LATEST_VERSION_ATTR
read-only
Is Latest
WC_LATEST_VERSION_ATTR
read-only
Lifecycle State
WC_LIFECYCLE_ATTR
read-only
Modified By
WC_LASTUPDATEDBY_ATTR
read-only
Lockable
WC_LOCKABLE_ATTR
read-only
Locked Status
WC_LOCKED_STATUS_ATTR
read-only
Checked Out By
WC_LOCKEDBY_ATTR
read-only
CMS Object Modified
WC_MODIFIED_STATUS_ATTR
read-only
Name
WC_NAME_ATTR
read and write
Number
WC_NUMBER_ATTR
read-only
Is Out Of Date
WC_OUT_OF_DATE_ATTR
read-only
Shared Status Display
WC_SHARED_STATUS_ATTR
read-only
CMS Object Read Only
WC_READ_ONLY_ATTR
read-only
Subtype (Soft Type) ID
WC_SOFTTYPE_ID_ATTR
read-only
Target Folder Name
WC_TARGET_FOLDER_ATTR
read-only
Version
WC_VERSION_ATTR
read-only
Note that the burst configuration file name is case insensitive. The data type for PTC Server system attributes must be string.
Using Security Labels
You can use the dmsmetadata element to update PTC Server security labels. Both one-way and two-way metadata assignment rules treat passing a Security Label value from an XML document to a PTC Server property differently from PTC Server global attributes. A Security Label value is only assigned to a PTC Server property when a new document is initially uploaded to the PTC Server. Security labels will not be updated when that document is subsequently checked into the PTC Server. You must use the PTC Server HTML interface to update security labels after a document is uploaded. For two-way metadata rules, passing values from the PTC server to an XML document works as usual.
References to security label names in metadata rules must match the value of the name attribute on the SecurityLabel element in the security label XML configuration file on the PTC Server. Values for security labels in a document must match the value of the name attribute on the SecurityLabelValue element in the configuration file. If these values do not match, any associated metadata assignment rules will fail.
References to security labels must also have the prefix SL:: prepended to the name of the security label. This flags the value as a security label for the PTC Server. For example, if the name of the security label is EXPORT_CONTROL, the name for that security label in the burst configuration file must be SL::EXPORT_CONTROL.
In the following example, the EXPORT_CONTROL security label is assigned the value of the book element’s role attribute when the document is initially burst into the PTC Server. Similarly, the CORPORATE_PROPRIETARY security label is assigned the value of the book element’s status attribute when the document is initially burst. However, the CORPORATE_PROPRIETARY security label is associated with a two-way metadata rule. If someone uses the PTC Server HTML interface to update that security label, then the new value for the security label will be passed to the status attribute in the XML document the next time that the document is checked out or updated in Arbortext Editor.
<dmsmetadata>
<twowaymetadatarule sourcetype="text" bndryelemname="book"
metadataelemname="book" attrname="status"
metadata="SL::CORPORATE_PROPRIETARY" mode="twoway"/>
<metadatarule sourcetype="text" elementname="book"
metadata="SL::EXPORT_CONTROL"
expr="@role"/>
</dmsmetadata>
For more information about security labels, refer to the Windchill Security Labels Configuration and Implementation Guide.
Using One-Way Metadata
The metadatarule element enables you to use XML attributes or content to serve as values for PTC Server property fields. When such mappings exist, the XML attribute values will be copied from the source XML document to the PTC Server object properties. Each mapping entry requires an XPath expression and the name of the PTC Server object property. Property assignment rules can be specified by element name, source type, or both.
The metadatarule element has the following attributes:
Attributes of the metadatarule Element
Attribute Name
Description
Default Value
Required?
elementname
Name of the element to use for a property assignment rule.
None
No
sourcetype
Document source type to use for a property assignment rule. Allowed types are text or graphic.
None
No
metadata
The Name of the PTC Server Property field shown on the PTC Server's Attribute Definition Manager tab.
None
Yes
select-multiple
Not currently used.
None
No
expr
XPath expression to locate the source of the property value in the XML document.
None
Yes
Property assignment rules function as follows:
If the element name is not specified, the rule applies to all elements of the given type.
For example:
<dmsmetadata>
<metadatarule sourcetype="graphic"
metadata="scale"
expr="@scale"/>
</dmsmetadata>
If the sourcetype is set to text, an elementname should be specified. Note that you might experience performance issues if an elementname is not specified, so it is suggested you specify an elementname.
For example:
<dmsmetadata>
<metadatarule sourcetype="text"
elementname=”topic”
metadata="role"
expr="@role"/>
</dmsmetadata>
If the source type is not specified, a source type of text is assumed and an elementname should be specified.
Graphic property assignment rules are evaluated using the graphic tag as the context node for the XPath expression.
Graphic properties are only set during the initial import of a graphic. If you check out the parent object, modify the dependant graphic element, and check the parent back in, the properties on the graphic object are not updated.
Only one rule is executed for each PTC Server object property on each new object. If an element rule and source type rule both apply and specify the same PTC Server object property, the element rule is used.
In the following example, the inline property will be set to yes for inlinegraphic elements and to no for all other graphic elements:
<dmsmetadata>
<metadatarule sourcetype="graphic"
metadata="inline"
expr="’no’"/>
<metadatarule sourcetype="graphic"
elementname=”inlinegraphic”
metadata="inline "
expr="’yes’"/>
</dmsmetadata>
Rules specifying an elementname take precedence over rules that do not specify an elementname.
If conflicting property assignment rules are specified, the last rule listed in the burst configuration file is used.
The content of the XML attribute is converted to the data type of the associated PTC Server property. Depending on the data type, the content of the XML attribute needs to be in a specific format to support the conversion. For all data types besides string, leading and trailing spaces are ignored. The following data types are supported:
string
No conversion is necessary for the string data type. Leading and trailing spaces are retained.
integer number
For the integer number data type, the XML content must be all decimal digits. An exception is that first character in the attribute can be an ASCII minus sign ( - ) or plus sign ( + ) to indicate a negative value. Following are some examples of integer numbers:
20
-5
real number
For the real number data type, the XML content must be a real number. Following are some examples of real numbers:
+1
-1
1.61803399
6.022e23
boolean
For the boolean number data type, if the content of the XML attribute is true or false (case insensitive), then that value is stored in the associated PTC Server property.
date & time
For the date & time data type, the content of the XML attribute must be consistent with the format a particular locale uses to represent date and time values as a string. The locale is based on the default locale of the JRE used by Arbortext Editor. The result of the conversion will be a time and date in the following format:
Apr 21, 2000 12:05:00 PM
The PTC Server connection supports the full XPath 1.0 specification for specifying property values. This allows combinations of element content, attribute values, and static text. XPath expressions are evaluated to strings. If multiple elements or attributes match, the first occurrence is returned. This is consistent with the XPath specification.
Following is an example of burst configuration file syntax that stores the value of the authcode attribute in the authorization object property:
<dmsmetadata>
<metadatarule elementname="chapter"
metadata="authorization"
expr="@authcode"/>
</dmsmetadata>
Using Two-Way Metadata
The twowaymetadatarule element enables you to either use PTC Server property fields as the value for an XML element or attribute or to have the exchange of values work in both directions. In the latter case, the value of a PTC Server property field is used as the value for an XML element or attribute when a document is checked out or opened in Arbortext Editor for viewing without being checked out. When a new document is initially added to the repository or an existing document is checked into the repository, then the value of the XML element or attribute is used for the PTC Server property field. Note that the element or attribute associated with a two-way metadata rule must already exist in the XML document and have a value assigned. If you want to use an XML attribute value to clear the value of a PTC Server property field, the attribute value can be a blank space.
Before you can use two-way metadata, you must enable it in the atidefaults.bcf system-wide burst configuration file. In that file, set the createdefaults element's twowaymetadata attribute to on to enable two-way metadata.
The twowaymetadatarule element has the following attributes:
Attributes of the twowaymetadatarule Element
Attribute Name
Description
Default Value
Required?
bndryelemname
The bursting object boundary XML element
None
No
metadataelemname
Name of the XML element to use for a property assignment rule
None
Yes
attrname
Name of the XML attribute to use for a property assignment rule
None
No
sourcetype
Document source type to use for a property assignment rule (currently, only the text type is supported)
text
No
metadata
The Name of the PTC Server Property field shown on the PTC Server's Attribute Definition Manager tab.
None
Yes
mode
The mode for the property assignment rule – supported modes are twoway (update the value on both document check out and check in) and toxml (update the value only on document check out)
twoway
No
ruletype
The number of attributes the rule uses – supported values are oneattr (one attribute) or twoattr (two attributes).
oneattr
No
matchattrname
For a ruletype that uses twoattr, the name of the attribute for which the value identifies a metadata property. The property’s value is contained in the attrname attribute.
None
No
matchattrvalue
For a ruletype that uses twoattr, the metadata property. The matchattrvalue appears in the matchattrname attribute. The property's value is contained in the attrname attribute.
None
No
Property assignment rules function as follows:
Both metadataelemname and metadata must be specified.
Only one rule is executed for each PTC Server object property on each new object. If an element rule (metadataelemname) and source type rule (sourcetype) both apply and specify the same PTC Server object property, the element rule is used.
If conflicting property assignment rules are specified, the last rule listed in the burst configuration file is used.
If both a metadatarule and a twowaymetadatarule with the mode attribute set to twoway specify the same PTC Server object property, the twowaymetadatarule is used.
The same PTC Server object property can be assigned to multiple XML elements and attributes. In this case, it is recommended that you develop a single twowaymetadatarule with the mode attribute set to twoway and then set the metadata for the other rules associated with this property. The other mode attributes should be set to toxml. Multiple twoway mappings can cause rule conflicts that are resolved by selecting one rule.
For example:
<dmsmetadata>
<twowaymetadatarule bndryelemname="book"
metadataelemname="copyright"
metadata="copyrightYear"
mode="twoway"/>
<twowaymetadatarule bndryelemname="chapter"
metadataelemname="chapter"
attrname=”copyright”
metadata="copyrightYear"
mode="toxml"/>
</dmsmetadata>
If an error occurs during the evaluation of a rule where the mode attribute is set to toxml, the associated check out is not canceled. However, the user receives an error message.
If a target element has both text and child elements, all of the text in the element is replaced with the value from the specified PTC Server property. The new text precedes the child elements.
For example, suppose you have the following two-way metadata rule that extracts the content of the metadata XML element and assigns it to a PTC Server property named topic_metadata:
<twowaymetadatarule bndryelemname="topic"
metadataelemname="metadata"
metadata="topic_metadata"
mode="twoway"/>
You import the following document:
<topic>
<metadata>
some values
<othermeta>Other values<othermeta>
some more values
</metadata>
</topic>
The topic_metadata PTC Server property will be assigned the following value:
some values some more values
Note that the content of the child element is ignored. Suppose you change the value of the topic_metadata property to Updated values in the PTC Server. The next time the XML document is checked out, it will have the following content:
<topic>
<metadata>
Updated values
<othermeta>Other values</othermeta>
</metadata>
</topic>
Note that the replacement text is placed before any child elements.
For a single PTC Server object, the combination of the metadataelemname, matchattrname, and matchattrvalue attributes uniquely identifies a metadata property. The property's value is stored in the attrname attribute. When the ruletype is twoattr, the twowaymetadarule attributes matchattrname, matchattrvalue, and attrname are all required. 
When assigning XML content values to PTC Server object properties, the single attribute ruletype (value set to oneattr) has higher priority than the two attribute ruletype (value set to twoattr. When rules of both types specify the same target PTC Server property, the two attribute rule is ignored. When multiple rules of the same ruletype specify the same target PTC Server property, the last rule in the burst configuration file has precedence.
When updating XML content from PTC Server property values, there is no conflict between the single and two attribute ruletype. A single PTC Server property can be assigned to multiple XML content locations. When multiple rules of the same ruletype specify the same XML content location for different PTC Server properties, the last rule in the burst configuration file has precedence.
The supported data types for passing attribute values from an XML attribute to a PTC Server property are the same as those supported for the metadatarule element. The following data types are supported for passing a value from a PTC Server property to an XML attribute:
string
No conversion is necessary for the string data type.
integer number
For the integer number data type, the content of the PTC Server property is converted to a base 10 string representation of the integer number.
real number
For the real number data type, the content of the PTC Server property is converted to a base 10 string representation of the real number.
boolean
For the boolean number data type, the content of the PTC Server property is converted to either the string true or false.
date & time
For the date & time data type, the content of the PTC Server property is converted into a locale-specific date and time string. The locale is based on the default locale of the JRE used by Arbortext Editor.
Following is an example of burst configuration file syntax that sets up a two-way metadata relationship between the projectStatus PTC Server property in the repository and the status element in the XML document. When a document is checked out or opened in Arbortext Editor for viewing without being checked out, the value of the status element is replaced with the value of the projectStatus property. When a document is created or checked in, the value of the projectStatus property is replaced with the value of the status element.
<dmsmetadata>
<twowaymetadatarule bndryelemname="book"
metadataelemname="status"
metadata="projectStatus"
sourcetype="text"/>
</dmsmetadata>
* 
Passing values from PTC Server object properties to an XML document requires that Arbortext Editor load, modify, and save the document object. During this process, Arbortext Editor does not validate the document against its document type. If invalid XML is passed from an object property to the XML document, the document will have completeness errors. Be sure to test your burst configuration for this case before deploying it.
Also, checking a document in and out using the PTC Server HTML interface does not process the two-way metadata,
Following is an example of a two-way metadata rule where the ruletype uses the twoattr value. In this case, the rule uses the DITA document type’s othermeta element containing the following values:
<metadata>
<othermeta content="high" name="security"/>
</metadata>
For this DITA markup, the following two-way metadata rule specifies that for topic objects, the repository’s Security property should be assigned the value high:
<twowaymetadatarule bndryelemname="topic"
ruletype="twoattr"
metadataelemname="othermeta"
matchattrname="name"
matchattrvalue="security"
attrname="content"
metadata="Security"/>