Building a sample alias file

The following figure shows a publishing page with a single table asset that has been populated with the Name property of child items and the Description property of an attached form from each child item.

Example result – table asset populated with child item names and form descriptions

This example starts with a simple product structure containing a parent item with two direct child items. Each child item has an attached form. This scenario is shown in the following figure.

Sample product structure

To populate the table asset with data, you must assign a binding to the table asset. The binding used is ProductPartList & Name and ProductPartList & FormDescription, as shown in the following figure.

Publish Bind dialog box

You can find the sample alias file that was used to create this example (ProjectTcPublishSystemAlias.xml), as well as the PLM XML code generated by the selected transfer mode (tcm_export.xml) in the Sample directory of your installation. This must be installed separately. If you do not have a Sample directory, contact your Teamcenter administrator.

In the example, the second binding involves the Description property of a form attached to the child item. The default alias file does not provide a definition for attaching the Description field of a form to a child item so you must modify this alias file.

In the following figure, notice the new FormDescription alias entry.

Expanded ProductPartList alias showing FormDescription entry

This new entry is created by adding a new top level alias definition into the alias file. The following code shows excerpts from the DefaultTcPublishSystemAlias.xml file. The line shown in bold print results in the new entry in the Bind dialog box shown in the figure. The statements in italics refer to other alias definitions.

Copy

    <!--#########Product part list information addresses the first level parts list of an 
occurrence it will return only the child occurrences of the first level occurrence selected.
                 #################-->
<Alias name="ProductPartList" assetType="8" toolTip="product data" 
     qualifier="2" accumulate="Quantity">
&OCC-ATTR-DEF;
</Alias>
<!-- properties that you want to see on an occurrence. 
Entity definition is used to avoid lot of typing-->
     <!ENTITY OCC-ATTR-DEF "
        <Alias name='ID' default='No ID'/>
        <Alias name='Description' default='No description'/>
        <Alias name='Name' default='no name'/>
        <Alias name='Rev' default='A'/>
        <Alias name='Transform' default='Identity'/>
        <Alias name='RevSubType' default='ItemRevision'/>
        <Alias name='LogicalID' default='Logical Identity'/>
        <Alias name='SequenceNumber' default='No find#'/>
        <Alias name='Quantity' default='1'/>
        <Alias name='ParentName' default='No parent'/>
        <Alias name='Type' default='No type'/>
        &FORM-MASTER-ATTR-DEF;
        &ICO-ATTR-DEF;
     ">
  <!ENTITY FORM-MASTER-ATTR-DEF "
        <Alias name='project_id' default='cannot get project_id'/>
        <Alias name='previous_item_id' default='cannot get previous itemid'/>
        <Alias name='item_comment' default='cannot get comment'/>
        <Alias name='serial_number' default='cannot get serial_number'/>
        <Alias name='UserData1' default='cannot get user_data_1'/>
        <Alias name='UserData2' default='cannot get user_data_2'/>
        <Alias name='UserData3' default='cannot get user_data_3'/>  
        <Alias name='rev_project_id' default='cannot get project_id'/>
        <Alias name='rev_previous_item_id' default='cannot get previous itemid'/>
        <Alias name='rev_item_comment' default='cannot get comment'/>
        <Alias name='rev_serial_number' default='cannot get serial_number'/>
        <Alias name='rev_UserData1' default='cannot get user_data_1'/>
        <Alias name='rev_UserData2' default='cannot get user_data_2'/>
        <Alias name='rev_UserData3' default='cannot get user_data_3'/>           
        <Alias name='FormDescription' default='No description'/>
      ">

For the new alias definition to traverse the PLM XML file, another edit is necessary. The following entry shows the traversal performed by the new alias definition. This entry is added to the section of the alias file.

Copy

<Alias name='FormDescription'>
    <Path>*:AssociatedAttachment[@role='IMAN_specification']:@associatedAttachmentRefs</Path>
    <Path>*:Form:@attachmentRef</Path>
    <Xpath>Description</Xpath>
</Alias>

To determine what to add and how the traversal works, reference the PLM XML file generated by the example and found in the Samples directory.

In the binding, ProductPartsList & FormDescription was selected. Find the Alias and AliasAlternate sections for ProductPartsList in the alias file. The following code section shows the relevant lines from the generated PLM XML file. All PLM XML files have a traverseRootRef entry like this:

Copy

<Header id="id1" traverseRootRefs="#id3" transferContext="tcm_export"></Header>

#id3 is the start node for the traversal. The transferContext transfer mode is used to generate this PLM XML code.

The start node is AssociatedAttachment.

Look through the alias file in the ProductPartsList section for all alias definitions that have a primary object specifying an AssociatedAttachment node. The following code contains the first one:

Copy

<!--#########Starting at a structure context as a root to a top level item#################-->
    <AliasAlternate name="ProductPartList">
        <Path>AssociatedAttachment:AssociatedAttachment[@role='contents']:@childRefs</Path>
        <Path>AssociatedAttachment:*:@attachmentRef</Path>
        <Path depth="1..1">*:*:@occurrenceRefs</Path>
        &OCC-ATTR;       
        &FORM–MASTER-ATTR;
        &ICO-ATTR;
    </AliasAlternate>

The traversal tries each alias rule that has a primary object matching the start node and traverses through each path statement until it gets to the Xpath statements. If any Path statement fails during the traversal, the traversal tries the next matching alias statement. The first Path statement is:

Copy

<Path>AssociatedAttachment:AssociatedAttachment[@role='contents']:@childRefs</Path>

This statement causes the traversal to proceed to AssociatedAttachment nodes with role=contents via the childRefs attribute in the PLM XML file. The PLM XML statement childRef attribute is:

Copy

childRefs="#id4 #id72">

Therefore, the traversal moves to PLM XML nodes with id4 and id72, if they match the role=contents condition. The PLM XML node containing id4 is:

Copy

<AssociatedAttachment id="id4" attachmentRef="#id9" role="contents">

The next Path statement in the alias definition is:

Copy

<Path>AssociatedAttachment:*:@attachmentRef</Path>

This Path statement indicates that the system expected AssociatedAttachment nodes as results from the last statement. If it did not, this alias definition would fail at this point.

The current Path statement tells the system to use the attachmentRef and return whatever is there. The * symbol is a wildcard indicating that any node is sufficient. Consequently, the traversal proceeds to the node containing #id9.

Copy

<Occurrence id="id9" instancedRef="#id43" associatedAttachmentRefs="#id45 #id46 #id49 #id67" 
     occurrenceRefs="id12 id32">
<ApplicationRef application="Teamcenter" label="SIEhslreBrSpAA/ScFh8BEQBrSpAA"></ApplicationRef>
<UserData id="id10" type="AttributesInContext">
<UserValue value="" title="AO_ID"></UserValue>
<UserValue value="" title="SequenceNumber"></UserValue>
<UserValue value="" title="OccurrenceName"></UserValue>
<UserValue value="" title="Quantity"></UserValue></UserData>
<Transform id="id8">1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1</Transform></Occurrence>

Node 9 is an occurrence.

The next Path statement is:

Copy

<Path depth="1..1">*:*:@occurrenceRefs</Path>

This Path statement tells the system to go to the nodes referenced by the occurenceRefs attribute. Again, the * wildcard is used, so the traversal picks up whatever node is contained in the PLM XML. The first node ID is #12.

Copy

<Occurrence id="id12" instancedRef="#id14" associatedAttachmentRefs="#id19 #id22 #id25 #id30" 
     parentRef="#id9">

This node is also an occurrence. The first line contains all the relevant reference information.

The next statement in the alias definition is:

Copy

&OCC-ATTR;

This is a macro statement that implies that the traversal expects to be on an occurrence node at this point and is getting ready to traverse its attributes.

At this point, the traversal again encounters alias names as shown for OCC-ATTR, ID, Description, Name, and so on.

Remember that the binding specified was ProductPartsList & FormDescription. The traversal started at the ProductPartsList node and arrived at this point. Now, it must find an alias name matching FormDescription to find any additional XML traversal rules to use. Going through the OCC-ATTR statement, the traversal cannot find any alias names that match FormDescription because the edit was not added to that entry. Therefore, the traversal continues on to the next entry in the original alias definition.

Copy

<!ENTITY OCC-ATTR "
   <Alias name='ID'>
      <Path>*:*:@instancedRef</Path>
      <Path>*:*:@masterRef</Path>
      <Xpath>@catalogueId|@productId</Xpath>
   </Alias>
   <Alias name='Description'>
      <Path>*:*:@instancedRef</Path>
      <Xpath>Description</Xpath>
   </Alias>
        
   <Alias name='Name'>
      <Path>*:*:@instancedRef</Path>
      <Xpath>@name</Xpath>
   </Alias>
        …  many more Occurrence attribute Alias Names
      ">

The next alias rule is:

Copy

&FORM-MASTER-ATTR;

The traversal looks in the alias file for this macro and starts traversing through the macro looking for an alias named FormDescription. The traversal finds the newly added alias as follows:

Copy

<Alias name='FormDescription'>
   <Path>*:AssociatedAttachment[@role='IMAN_specification']:@associatedAttachmentRefs</Path>
   <Path>*:Form:@attachmentRef</Path>
   <Xpath>Description</Xpath>
</Alias>

Remember that the last node collected was:

Copy

<Occurrence id="id12" instancedRef="#id14" associatedAttachmentRefs="#id19 #id22 #id25 #id30" 
     parentRef="#id9">

Now the first Path statement in the current alias rule is this:

Copy

<Path>*:AssociatedAttachment[@role='IMAN_specification']:@associatedAttachmentRefs</Path>

This means the traversal is looking for AssociatedAttachment nodes with an IMAN_specification role. This should be available through the AssociatedAttachmentRefs statement. In this case, the only node that matches these criteria is the one with #id22 shown here.

Copy

<AssociatedAttachment id="id22" attachmentRef="#id23" role="IMAN_specification">

The next alias rule is:

Copy

<Path>*:Form:@attachmentRef</Path>

This means that using the attachmentRef attribute, the traversal expects to move to a form. #id23 indicates the node for which the traversal needs to search.

Copy

<Form id="id23" name="ATestForm" accessRefs="#id15" subType="OfficeDocForm" 
     subClass="OfficeDocForm">
<Description>ChildItem 1 Description</Description>
<ApplicationRef version="SYNhstU9BrSpAA" application="Teamcenter" 
     label="SYNhstU9BrSpAA"></ApplicationRef>
<UserData id="id24" type="FormAttributes">
<UserValue value="" title="Title"></UserValue>
<UserValue value="" title="Subject"></UserValue>
<UserValue value="" title="Author"></UserValue>
<UserValue value="" title="Manager"></UserValue>
<UserValue value="" title="Company"></UserValue>
<UserValue value="" title="Category"></UserValue>
<UserValue value="" title="Keywords"></UserValue>
<UserValue value="" title="Comments"></UserValue>
<UserValue value="" title="Client"></UserValue>
<UserValue value="" title="Project"></UserValue>
<UserValue value="" title="Purpose"></UserValue></UserData></Form>

This shows that #id23 is a form.

At this point, the traversal has successfully executed all the Path statements and ends with a final destination node. The next statement in the alias rule is:

Copy

<Xpath>Description</Xpath>

The Xpath statements describe what information to take from the resulting node to use in the publishing page. In the example, the property originally sought was the Description property of the form attached to the ChildItem item. This Xpath statement says to return the data for the Description entry for the current node. Looking at the PLM XML, this is:

Copy

<Description>ChildItem 1 Description</Description>

Looking at the populated publishing page in the figure entitled Example result – table asset populated with child item names and form descriptions, you see the same description in the FormDescription column for ChildItem 1. This accomplishes the goal of the example.

The Path statements are used to traverse from the start node to the final node. The Xpath statements are used to extract information from the final node. There are potentially several valid paths from the start node to the final node in the PLM XML. You need to determine any valid set of path statements to reach the final node.