Evaluating Publish Rules
The following sections describe the events and logic for evaluation of Publish Rules.
Events that Trigger Publish Rules Evaluation
As described in
Enabling Publish Rules, Publish Rules Evaluation is triggered by the following events:
• Check-in of the EPMDocument.
• Scheduled publishing of the EPMDocument.
• User selection of the New Representation action on the EPMDocument’s Representations List (or its associated WTPart’s Representations List).
• A publish job resulting from any other event, such as from a manual republish, republish on change, or workflow initiated.
Evaluating Publish Rules Logic
This section describes the logic of Publish Rules evaluation and includes fragments of Publish Rules files. Unless otherwise stated, the evaluation process uses case-sensitive string comparisons.
The Publish Rules file is a well-formed XML document, with <rules> being its root element.
Keep in mind that this section attempts to provide a high-level overview of the evaluation process. Many of the details you need to successfully construct your own Publish Rule files are in the sections that follow. See also
Examples of Publish Rules XML Files.
|
|
Parameters and values in the publish rules file are case sensitive.
|
Step 1: Matching <authoring-application>
The <rules> element must have one <authoring-application> child for each authoring application specified in the WVS Property publish.usesPublishRules.
For example, to specify Arbortext and Creo Parametric as authoring applications, these commands would be used:
In general, the concept is:
Publish Rules Evaluation searches for the <authoring-application> element with a ‘name’ attribute matching the EPMDocument’s Authoring Application. If a match is not found, no Publish Jobs are generated; otherwise, evaluation proceeds to Step 2.
Step 2: Matching <epm-number>
Evaluation continues by searching the children of the <authoring-application> element matched in Step 1 for an <epm-number> element whose ‘number’ attribute matches the EPMDocument’s Number.
|
|
<authoring-application> elements can have children other than <epm-number> elements; those elements are ignored in this step even if they appear in the Publish Rules XML file before <epm-number> elements.
|
<authoring-application name=”MY_AUTH_APP”>
<epm-number number=”1111”>
*
*
*
</epm-number>
<epm-number number=”2222”>
*
*
*
</epm-number>
</authoring-application>
If a match is found, the matched <epm-number> element becomes the root for searching for <publish> elements, which is described in Step 8; otherwise, evaluation proceeds to Step 3.
Step 3: Matching <epm-iba> with ‘value’ attribute present
Evaluation continues by searching the children of the <authoring-application> element matched in Step 1 for an <epm-iba> element corresponding to a global attribute Name/Value pair within the EPMDocument.
|
|
The ‘value’ attribute of <epm-iba> is an optional attribute; Step 3 only considers those <epm-iba> elements whose ‘value’ attribute is present. What happens when no ‘value’ attribute is present is discussed in Step 4.
|
<authoring-application name=”MY_AUTH_APP”>
<epm-iba iba=”IBA_NAME_1” value=”IBA_VALUE_1”>
*
*
*
</epm-iba>
<epm-iba iba=”IBA_NAME_2” value=”IBA_VALUE_2”>
*
*
*
</epm-iba>
</authoring-application>
If a match is found, the matched <epm-iba> element becomes the root for searching for <publish> elements, which are described in Step 8; otherwise, evaluation proceeds to Step 4.
Step 4: Matching <epm-iba> without ‘value’ attribute present
Evaluation continues by searching the children of the <authoring-application> element matched in Step 1 for a <epm-iba> element whose ‘iba’ attribute matches to a global attribute name within the EPMDocument.
|
|
The ‘value’ attribute of <epm-iba> is an optional attribute; Step 4 only considers those <epm-iba> elements whose ‘value’ attribute is not present. The <epm-iba> elements that meet this criterion are considered in the order they appear in the Publish Rules XML file.
|
<authoring-application name=”MY_AUTH_APP”>
<epm-iba iba=”IBA_NAME_1”>
*
*
*
</epm-iba>
<epm-iba iba=”IBA_NAME_2”>
*
*
*
</epm-iba>
</authoring-application>
If a match is found, the matched <epm-iba> element becomes the root for searching for <publish> elements, which are described in Step 8; otherwise, evaluation proceeds to Step 5.
Step 5: Matching <epm-type>
Evaluation continues by searching the children of the <authoring-application> element matched in Step 1 for an <epm-type> element with a ‘type’ attribute matching the EPMDocument’s Object Type. The value of the ‘type’ attribute is the EPMDocument’s Internal Name. Internal names are defined in the WindchillType and Attribute Management utility.
In order for global attributes to be set during processing, you first must define the global attribute for the type in the
Type and Attribute Management utility. See
Working with the Type and Attribute Management Utility for details.
<authoring-application name=”MY_AUTH_APP”>
<epm-type type=”MyLogicalId”>
*
*
*
</epm-type>
<epm-type type=”AnotherLogicalId”>
*
*
*
</epm-type>
</authoring-application>
If a match is found, the matched <epm-type> element becomes the root for searching for <publish> elements, which are described in Step 8; otherwise, evaluation proceeds to Step 6.
Step 6: Fall-through matching
If evaluation has not found a search root in any of the previous steps, the <authoring-application> element becomes the root for searching for <publish> elements. Publish elements are described in Step 8.
Here is an example of fall-through publishing:
<authoring-application name=”MY_AUTH_APP”>
<epm-number number=”1111”>
*
*
*
</epm-number>
<epm-type type=”MyInternalName”>
*
*
*
</epm-type>
<!-- Begin: Fall-through search root -->
*
*
*
<!-- End: Fall-through search root -->
</authoring-application>
In this example, if the EPMDocument’s number is not 1111 or does not have the internal name "MyInternalName", the search root becomes the <authoring-application> (as noted between the Begin and End comment lines above).
|
|
Using the fall-through matching is not a recommended practice, since you lose control of the ability to bypass publishing on any EPMDocuments for a particular authoring application. Fall-through matching is useful when testing Publish Rules, allowing you to focus only on matching the <authoring-application>.
|
Step 7: Matching <structure-type>
Evaluation continues in Step 7 by searching the children of the <authoring-application> element matched in Step 1 for a <structure-type> element whose
type attribute matches to the type of structure being published. The value of the
type attribute can be
epm,
part,
epm_plus_parts,
part_and_epm,
epm_wc_structure,
epm_wc_structure, or
type_based_object_structure. Steps 2 through 6 determine a root for searching for <publish> elements. This root can be an <epm-number>, <epm-iba>, <epm-type>, or <authoring-application> element.
If a match is found, the matched <structure-type> element becomes the root for searching for <publish> elements; otherwise, the <authoring-application> element becomes the root for searching for <publish> elements. In this case, the <authoring-application> element can be thought of as the “fall through” condition described in Step 6. Searching for <publish> elements is described in the next step.
Step 8: Matching <publish>
Steps 2 through 6 determine a root for searching for <publish> elements. This root can be an <epm-number>, <epm-iba>, <epm-type>, or <authoring-application> element.
A Publish Job is created for each <publish> element child of the root whose ‘on’ attribute matches the event that caused Publish Rules Evaluation to be invoked. If no <publish> elements are matched, no Publish Jobs are created.
For each match, the attributes of the matched <publish> element are processed. The possible attributes are as follows:
• on - The possible ‘on’ values correlate to the triggers described at the very beginning of this section. They are “checkin”, “schedule”, “create-representation”, and “unknown-source”. (A fifth trigger, called “manual-post”, is described later in this document. See
Manual Post Publishing for details.) In the example above, there are three "on" values: two for checkin and one for schedule. If the trigger for Publish Rules evaluation was due to a checkin of an EPMDocument, two publish jobs would be created. If the trigger was due to a scheduled job of an EPMDocument, one publish job would be created. If the trigger was due to the manual
New Representation wizard from the user interface, no publish jobs would be created.
• output - If an ‘output’ attribute is present (as shown in the third <publish> line above), it is part of the information in the Publish Job that can be used by the Worker. The use of this attribute is not valid for all Workers.
• param-set - If a ‘param-set’ attribute is present, the Publish Rules XML file is searched for a <param-set> element with a ‘name’ attribute matching the value of the ‘param-set’ attribute. Step 9 describes the processing of a matched <param-set> element. In the example above, the param-set value is "SET1".
• param-set-ref -If a <param-set-ref...> sub-element is present in a <publish on=...> element block, the Publish Rules XML file is searched for a <param-set...> element with a ‘name’ attribute matching the value of the param-set-ref “name” attribute. Multiple <param-set-ref...> sub-element can be added, each referencing different param-set definitions in the same XML file, to invoke multiple post-publishing delegates for the single <publish on=...> element block.
• overlay-recipe-file – If an ‘overlay-recipe-file’ attribute is present (as displayed in the fourth <publish> line above), the
Visualization Configuration Administration UI is searched for a file matching the RECIPE_FILE_NAME value and if found, this file is sent to the Worker along with the other file for the Publish Job. Worker then uses this overlay recipe file for generating the representation or viewable.
|
|
If an overlay recipe file with the specified name does not exist, the Publishing Job fails. In such case, either remove the attribute 'overlay-recipe-file' from the Publish Rule if not necessary or enter the correct file name.
|
Step 9 describes the processing of a matched <param-set-ref> element.
Step 9: Processing <param-set-ref>
Use the <param-set-ref> sub-element within a single <publish on=...> element block to reference multiple <param-set> element definitions in the same XML file, for example, for configuring post-publishing of different Additional File Types to create a separate WTDDocument object for each file type, using the AdditionalFilesPostPublishDelegate.
For an illustration of the syntax, see the out-of-the-box PublishRules-AdditionalFiles.xml file that resides in <Windchill>/codebase/com/ptc/wvs/server/xml.
Step 10: Processing <param-set>
<param-set> elements can appear anywhere between the <rules> tags within the Publish Rules XML file. It is often useful to reference the same <param-set> element from several <publish> elements. The children of a <param-set> element contain information that is part of the Publish Job. The information is contained in the following elements:
post-publish – These elements are used to pass necessary information to the PostPublishDelegate. For more information, see
Post-Publishing.
iba – These elements are also used to pass optional information to the PostPublishDelegate. For more information, see
Post-Publishing.
In order for global attributes to be set during processing, you first must define the global attribute for the type in the
Type and Attribute Management utility. Since the Publish Rules reside in an XML file that contains strings, you need to be aware of how you represent non-string values to pass to the post-publishing delegate. See
Working with the Type and Attribute Management Utility for details.
The following is a list of supported global attribute types and an example value for each global attribute:
<iba name="com.ptc.MyTypeBoolean">Yes</iba>
<iba name="com.ptc.MyTypeDateTime">2007-07-13 11:12:32</iba>
<iba name="com.ptc.MyTypeInteger">36</iba>
<iba name="com.ptc.MyTypeRealNumber">0.12321345</iba>
<iba name="com.ptc.MyTypeRealUnitsArea">25 m**2</iba>
<iba name="com.ptc.MyTypeString">string test</iba>
<iba name="com.ptc.MyTypeURL">http://www.ptc.com (PTC)</iba>
worker – This element is used to pass extra information to the Worker if the Worker supports it. The worker is determined by the authoring application of the EPMDocument that is being used during the evaluation.
These elements have an identical structure; each has a ‘name’ attribute to identify the parameter and the text content of the element is the parameter’s value.
A <param-set> element can have any number of <worker>, <post-publish>, and <iba> elements; however, unlike most of the other evaluation steps, the order of appearance is important. When Step 8 matches a <publish> element, the evaluation process constructs an internal table for each element, for example, a table for <worker>, a table for <post-publish>, and a table for <iba>. The children of the <param-set> element are retrieved in the order they appear in the file.
As each child is processed, the tables are populated with name/value pairs. Parameter names must be unique within each table, but are not required to be unique across tables. (For example, you can have the same <post-publish> name and <iba> name, but you cannot have two <post-publish> names be the same.)
When a child is processed, if its parameter identifier was previously encountered, its table entry is updated with a new parameter value, thus replacing previously encountered values for the same name.
A <param-set> element can also have <include> element children. The <include> element adds the parameters associated with a specified <param-set> to the tables. This is akin to calling a subroutine.
In the above fragment, if the SET1 <param-set> was referenced in the Publish Rules file, the <post-publish> parameter ‘name’ has the value ‘From SET1’ because the <include> element in SET1 appears before the <post-publish> element. If the elements were reversed, the value would be ‘From COMMON’.
The <include> element effectively allows <param-set> elements to be chained together. After the entire chain is processed, processing proceeds to Step 11.
Step 11: Substitution of text values
After the <param-set> elements have been processed and the parameter tables of Step 9 have been populated, the parameter values in the tables are scanned for Substitution Keys. A Substitution Key is a predefined sequence of characters (always beginning with an opening brace and ending with a closing brace) which, when encountered, is replaced with information shown in the table below.
|
Substitution Key
|
Data Substituted
|
|
{AUTHORING_APP}
|
Source EPMDocument's Authoring Application
|
|
{EPM_NAME}
|
Source EPMDocument's Name
|
|
{EPM_NUMBER}
|
Source EPMDocument's Number
|
|
{EPM_TYPE}
|
Source EPMDocument's Type
|
|
{OUTPUT_TYPE}
|
Value of 'output' attribute of <publish> element
|
|
{PARAM_SET_NAME}
|
Value of 'param-set' attribute of <publish> element
|
|
{PARAM_SET_REF_NAME}
|
Value of 'param-set-ref' attribute of <publish> element
|
|
{ADDITIONAL_FILE_PRIMARY_BASENAME}
|
Primary additional file's base name without the file extension
|
|
{ADDITIONAL_FILE_PRIMARY_EXTENSION}
|
Primary additional file's file extension
|
|
{ADDITIONAL_FILE_SECONDARY_BASENAME}
|
Secondary additional file's base name without the file extension. If there are multiple secondary files, then one is chosen randomly for this name.
|
|
{ADDITIONAL_FILE_SECONDARY_EXTENSION}
|
Secondary additional file's file extension. If there are multiple secondary files, then one is chosen randomly for this name.
|
For example, if the following elements were encountered in a <param-set>:
<post-publish name=”name”>{EPM_NUMBER} authored by
{AUTHORING_APP}</post-publish>
The name of the target Object would be something like the following. (In this example, the number of the EPMDocument is 000047.)
000047 authored by MY_AUTH_APP
Once all substitutions have been made, the parameter tables are associated with the Publish Job and evaluation returns to Step 8 to search for additional <publish> elements.
Step 12: Evaluation Complete
After the Publish Rules are evaluated, you will have zero to many publish jobs for a single EPMDocument. Additionally, you may have defined post-publishing and worker-specific parameters for some or all of the publish jobs that were created.
A successful publish job results in a Representation. Then, based on the Publish Rules, you can define post-publishing behavior.
