Customization Examples

Advanced Customization > Windchill ESI Customization > ERP Connector Customization > Windchill ESI Services Customization Scenarios > Customization Examples

The examples in this section focus only on what needs to happen in ESI services in order for newly added attributes to appear in the ESI RPC response. For examples that cover other customization options, see the ERP Connector Customization Examples section.

Publish a part with an additional attribute

The additional attribute could be a modeled or a soft attribute, or it could be an IBA. Let the attribute be named standardPrice. Perform the following steps in order that this attribute gets sent with the ESI response:

1. Add standardPrice to WTPart either as a soft attribute using the Type and Attribute Management UI, or as an IBA. Alternatively, it could be added as a soft attribute on a soft type extension of WTPart, or as a modeled attribute (in which case, the Windchill ESI preference “Part Class” should be edited so that it points to the fully qualified name of the WTPart extension class).

2. Create a copy of the ESI response meta information file and modify its contents as outlined below:

<esi:Map id="ESINewPart">
<esi:attributeMapping sourceAttribute="obid">ObjectID</esi:attributeMapping>
…
<esi:attributeMapping sourceAttribute="iterationInfo.identifier.iterationId">Iteration</esi:attributeMapping>
<esi:attributeMapping sourceAttribute="PreviousVersion">PreviousVersion</esi:attributeMapping>
…
<esi:attributeMapping sourceAttribute="standardPrice">StandardPrice</esi:attributeMapping>
</esi:Map>

<esi:MapInformation id="ESIPartInfo">
<esi:typedef>wt.part.WTPart</esi:typedef>
<esi:elementMetaName>Part</esi:elementMetaName>
<esi:keyAttribute>Number</esi:keyAttribute>
…
<esi:mapRef>ESINewPart</esi:mapRef>
</esi:MapInformation>

As can be seen from the portions shown highlighted above, the Map and the MapInformation elements (that have “ESIPart” and “ESIPartInfo” as values for their id attribute) require changes. The Map element has its id attribute set to a modified value, and has a new attributeMapping element added for the attribute standardPrice. Also, the mapRef element of the relevant MapInformation element has its value set to the modified value of the id attribute of the Map element.

Any change to the Map element must be accompanied by a change to the value of its id attribute. Also, if adding a new attribute (such as standardPrice) results in a new extension of WTPart, the fully qualified name of that type should be provided as value for the typedef element of the MapInformation element. For more information, Modify the ESI response meta information file.

3. Using the Manage Distribution UI (that appears under Site > Utilitiesor Organization > Utilities), bring up the Edit Distribution Target UI for the distribution target to which to publish the part. Set the ESI Response Meta Information File Path field to point to the file that was modified in step 2. Save the distribution target by clicking OK. Associate the edited target to the part being published, if it is not already associated.

Publishing the part now (with the attribute standardPrice set to the required value) should cause the newly added attribute, viz., StandardPrice to be sent with the ESI response for the distribution target that was edited in step 3. If the part were published for the first time, a child XML element <StandardPrice> will appear within the <Part> element in the <AddedParts> section of the response. Clearly, the above described use case simply calls for modifying the response meta information file, and in that sense does not require any customization.

• The position of the <StandardPrice> element within the <Part> element in the response would depend on where in the Map element (of the response meta information file) the new entry is added. For example, if it is added as the last entry in the Map element as illustrated in the above example, <StandardPrice> would appear as the last child element within the <Part> element in the response.

• When publishing a soft type (or a modeled) extension of a WTPart, the ESI response meta information file would require changes (as described in step ii above) only if there is a need to publish a different set of attributes for the extension as compared to the WTPart object. See section Points to note while modifying the ESI response information file for more information.

Publish a part with extra information

One may sometimes want to send extra information in the <Part> element in the ESI response, that does not reside on the WTPart object as an attribute – for e.g., a child XML element called <IsAssembly> that tells whether or not the given part is an assembly. The following steps need to be performed in order that this child element appears in the ESI response:

1. Create a copy of the ESI response meta information file and modify its contents as outlined below:

<esi:Map id="ESINewPart">
<esi:attributeMapping sourceAttribute="obid">ObjectID</esi:attributeMapping>
…
<esi:attributeMapping sourceAttribute="isAssembly">IsAssembly</esi:attributeMapping>
</esi:Map>
<esi:MapInformation id="ESIPartInfo">
<esi:typedef>wt.part.WTPart</esi:typedef>
<esi:elementMetaName>Part</esi:elementMetaName>
<esi:keyAttribute>Number</esi:keyAttribute>
…
<esi:mapRef>ESINewPart</esi:mapRef>
</esi:MapInformation>

See section Modify the ESI Response Meta Information File for more information on how to modify the contents of the ESI response meta information file.

2. Create an extension of the class com.ptc.windchill.esi.esipart.ESIWTPartRenderer and override the adjustPartElement() method as follows:

protected Element adjustPartElement( Element element, String group, WTPart part, Eff[] effs, Collection targets )
throws ESIRendererException { boolean isAssem;
try {
isAssem = new BOMUtility().isBom(part);
}
catch(WTException wte) {
ESILogger.debug("Exception while invoking isBom() for part: " + part.getNumber());
throw new ESIRendererException(wte);
}

Att att = element.getAtt(“IsAssembly”);

if(att != null && (att.getValue() == null || att.getValue().toString().trim().equals(“”)))
{
att.setValue(String.valueOf(isAssem));
}

return element;
}

3. Using the Manage Distribution UI (that appears under Site > Utilitiesor Organization > Utilities), bring up the Edit Distribution Target UI for the distribution target to which to publish the part. Set the ESI Response Meta Information File Path field to point to the file that was modified in step 1. Save the distribution target by clicking OK. Associate the edited target to the part being published, if it is not already associated.

4. Open the file <Windchill>\codebase\com\ptc\windchill\esi\conf\esi.service.properties.xconf and look for the following entry:

Edit the above entry so that the serviceClass attribute has the fully qualified name of the extension of ESIWTPartRenderer (that was created in step 2)) as its value. See Customization Points for more information.

5. Run the command xconfmanager –p from the Windchill shell so that the change made in step 4 is propagated appropriately. Re-start the MethodServer.

Publishing the part now would result in the <IsAssembly> element getting sent with the ESI response. Observe that this use case calls for customizing the part renderer, since it requires sending information that does not reside as an attribute on a WTPart object, meaning it cannot be fetched using the Query-Objects webject.

Publish an assembly with an added attribute on the header part

This example would require following the same set of steps as those described in section “Publish a part with an additional attribute”, except that the Map and MapInformation elements of the response meta information file referenced in step 2 would be for a BOM header. In other words, the Map element having the value BOMHeader for its id attribute would carry a new attributeMapping element; also, the id attribute of the Map element would carry a modified value (such as NewBOMHeader) and the mapRef element of the relevant MapInformation element would carry this modified value. Also, when publishing the assembly for the first time, a new child XML element (corresponding to the added attribute) would appear in the <BOMHeader> element in the <AddedBOMs> section of the response.

Publish an assembly with extra information

Again, this example would require following the same set of steps as those described in section “Publish a part with extra information”, except that the Map and MapInformation elements of the response meta information file referenced in step 1 would be the ones with values BOMHeader and BOMHeaderInfo respectively. Also, the Java class to be extended would be com.ptc.windchill.esi.bom.ESIBOMHeaderRenderer and the method to override would be the following:

protected Element adjustElement( Element element, String group, WTPart part, Eff[] effs, Collection targets) throws ESIRendererException

Also, the ESI service property entry to edit would be:

Edit the above entry so that the serviceClass attribute has the fully qualified name of the extension of ESIBOMHeaderRenderer. Propagate this property the usual way and re-start the MethodServer.

Publishing the assembly now would result in the required extra information getting sent with the ESI response. This would appear as a newly added child XML element in the <BOMHeader> element of the ESI response.

Publish an assembly with an added attribute on WTPartUsageLink

This example considers publishing a soft attribute that is added to the WTPartUsageLink object that links the assembly part to a certain part master. Let the soft attribute be named color. Perform the following steps in order that this attribute gets sent with the ESI response:

• Add color as a soft attribute on WTPartUsageLink, using the Type and Attribute Management UI the usual way.

• Create a copy of the ESI response meta information file and modify its contents as outlined below:

<esi:Map id="NewBOMComponent">
<esi:attributeMapping sourceAttribute="PartMasterID">ObjectID</esi:attributeMapping>
…
<esi:attributeMapping sourceAttribute="PartUsageLink.ComponentId">ComponentId</esi:attributeMapping>
<esi:attributeMapping sourceAttribute="xxxx">IsChildPhantom</esi:attributeMapping>
…
<esi:attributeMapping sourceAttribute="color">Color</esi:attributeMapping>
</esi:Map>

<esi:MapInformation id="BOMComponentInfo">
<esi:typedef>wt.part.WTPartUsageLink</esi:typedef>
...
<esi:mapRef>NewBOMComponent</esi:mapRef>
</esi:MapInformation>

As can be seen from the portions shown highlighted above, the Map and the MapInformation elements (that have BOMComponent and BOMComponentInfo as values for their id attribute) require changes. The Map element has its id attribute set to a modified value, and has a new attributeMapping element added for the attribute color. Also, the mapRef element of the relevant MapInformation element has its value set to the modified value of the id attribute of the Map element.

• Using the Manage Distribution UI (that appears under Site > Utilitiesor Organization > Utilities), bring up the Edit Distribution Target UI for the distribution target to which to publish the assembly. Set the ESI Response Meta Information File Path field to point to the file that was modified in step 2. Save the distribution target by clicking OK. Associate the edited target to the assembly (and its component parts) being published, if it is not already associated.

Publishing the assembly now (with the attribute color set to the required value on each of its components) should cause the newly added attribute, viz., Color to be sent with the ESI response. If the assembly were published for the first time, a child XML element <Color> will appear within the <BOMComponent> element in the <AddedBOMComponents> section of the response. Clearly, the above described use case simply calls for modifying the response meta information file, and in that sense does not require any customization.

The position of the <Color> element within the <BOMComponent> element in the ESI response would depend on where in the Map element of the response meta information file the new entry is added.

Publish an assembly with added information on the component part

It may sometimes be necessary to send some extra information in the <BOMComponent> element in the ESI response - for e.g., a child element <IsEndItem> that tells whether or not the given component part is an end item. This may be achieved by performing the following steps:

1. Create a copy of the response meta information file and modify its contents as outlined below:

<esi:Map id="NewBOMComponent">
<esi:attributeMapping sourceAttribute="PartMasterID">ObjectID</esi:attributeMapping>
…
<esi:attributeMapping sourceAttribute="PartUsageLink.ComponentId">ComponentId</esi:attributeMapping>
<esi:attributeMapping sourceAttribute="xxxx">IsChildPhantom</esi:attributeMapping>
…
<esi:attributeMapping sourceAttribute="isEndItem">IsEndItem</esi:attributeMapping>
</esi:Map>

<esi:MapInformation id="BOMComponentInfo">
<esi:typedef>wt.part.WTPartUsageLink</esi:typedef>
...
<esi:mapRef>NewBOMComponent</esi:mapRef>
</esi:MapInformation>

2. Create an extension of the class ESIBOMComponentRenderer and override the method adjustElement(Element, String, PartUsageInfo, Collection) as follows:

protected Element adjustElement(Element elem, String group, PartUsageInfo pui, Collection targets )

throws ESIRendererException { Att att = elem.getAtt(“IsEndItem”);
if(att != null && (att.getValue() == null || att.getValue().toString().trim().equals(NULL_STRING)))
{
boolean endItem = pui.getUses().isEndItem();
String endItemAsStr = String.valueOf(endItem);

att.setValue(endItemAsStr);
}

return elem;
}

3. Using the Manage Distribution UI (that appears under Site > Utilitiesor Organization > Utilities), bring up the Edit Distribution Target UI for the distribution target to which to publish the assembly. Set the ESI Response Meta Information File Path field to point to the file that was modified in step 1. Save the distribution target by clicking OK. Associate the edited target to the assembly (and its component parts) being published, if it is not already associated.

4. Open the file <Windchill>\codebase\com\ptc\windchill\esi\conf\esi.service.properties.xconf and look for the following entry:

Edit the above entry so that the serviceClass attribute has the fully qualified name of the extension of ESIBOMComponentRenderer (that was created in step 2) as its value.

5. Run the command xconfmanager –p from the Windchill shell so that the change made in step 4 is propagated appropriately. Re-start the MethodServer.

Publishing the assembly now would result in the <IsEndItem> element getting sent with the ESI response. Observe that this use case calls for customizing the BOM component renderer, since it requires sending information that does not reside as an attribute on a WTPartUsageLink object, meaning it cannot be fetched using the Query-Objects webject.

Publish an assembly with a usage different from what may be set on the assembly part iteration

The usage value that is set on an assembly part iteration using the BOM Transformer can be overridden when publishing the assembly. This requires performing the following steps:

1. Set the Windchill ESI preference View To Distribution Target Mappings to a value that relates a Windchill view to the distribution target that the assembly is being published to. For example, if the assembly was created in the Design view and is to be published to a distribution target having the value 00001 for its Number attribute, the preference may be set to Design:00001.

2. Set the Windchill ESI preference View To BOM Type Mappings to a value that relates a Windchill view to the required BOM usage value. For example, if the assembly is to be published as an Engineering one, the preference may be set to Design:Engineering.

The said preferences may be set either for Site or for an organization, depending on whether the assembly resides in Site or within an organization.

3. Associate the distribution target with number 00001 to the assembly in question and release the assembly.

If the attribute Default for Context has a value Yes for the distribution target, the settings described in (i) will ensure that the target is automatically associated to the assembly part.

The above will result in the assembly being sent as an Engineering one, as can be seen from the content of the Usage element in the ESI response for the released assembly. It is important to keep in mind that the value sent thus will override any other BOM Usage value that may have been set on the assembly part iteration using the BOM Transformer.

Publish an Assembly with a Deleted BOM Component Containing Custom Attributes

This section outlines the steps to preserve custom attribute values while deleting BOM components from the database. These steps are applicable to the following types of links:

• wt.mpm.rawmaterial.RawMaterialLink

• wt.mpm.coproduce.CoProduceMemberLink

• wt.mpm.coproduce.CoProduceUsageLink

When sending a raw material, co-produce member, or co-produce usage link, in the ESI response, identify the custom (soft) attributes to be sent with their original values in a deleted BOM component element.

Add such attributes within the esi:Map id="BOMComponent" element or in an equivalent custom element within the ESIResponseMetaInfo.xml file.

The XML attribute, storeInSnapshotForTypes is added within the same element. storeInSnapshotForTypes supports only one or more of the three types of the links i.e., wt.mpm.rawmaterial.RawMaterialLink, wt.mpm.coproduce.CoProduceMemberLink, and wt.mpm.coproduce.CoProduceUsageLink.

For example, assume that the TestAttr IBA of type String is added to the type wt.mpm.rawmaterial.RawMaterialLink and SortAttr IBA of type String is added to the types wt.mpm.coproduce.CoProduceMemberLink and wt.mpm.coproduce.CoProduceUsageLink.

To include the original values of TestAttr and SortAttr in the ESI response when sending them in the deleted BOM component element, add the following element entries in the ESIResponseMetaInfo.xml file under the esi:Map id="BOMComponent" group element.

It is recommended to update the id attribute of the BOMComponent map when its content is updated.

<esi:Map id="BOMComponent">
<esi:attributeMapping sourceAttribute="TestAttr" storeInSnapshotForTypes="wt.mpm.rawmaterial.RawMaterialLink">TestAttr</esi:attributeMapping>
<esi:attributeMapping sourceAttribute="SortAttr" storeInSnapshotForTypes="wt.mpm.coproduce.CoProduceMemberLink,wt.mpm.coproduce.CoProduceUsageLink">SortAttr</esi:attributeMapping>
</esi:Map>

The XML configuration changes are not applicable to the already published BOM structures with soft attributes on the specified links. The configuration changes are applicable only to unpublished BOM structures.

Selectively Rendering Incremental Changes for Documents

The preference Publish Only Incremental Changes to Document Associations defines whether to publish only incremental changes to document associations for parts, process plans, sequences, operations and resources. To control publishing of incremental changes to document associations for specified objects, without considering the preference setting, create an extension of class com.ptc.windchill.esi.esidoc.ESIDocumentsRenderer and override the method isIncrementalDocAssociationsPublishEnabled as follows:

public boolean isIncrementalDocAssociationsPublishEnabled(RevisionControlled currentObject) {
boolean flag = true;
if (!(MPMLinkFacade.isMPMLinkInstance(MPMLinkFacade.MPMLinkClass.MPMPROCESSPLAN, currentObject))) {
flag = ESIProperties.getProperty(DOCUMENT_LINK_DELTA_FLAG, true, (WTContained) currentObject);
} else {
flag = false;
}
return flag;
}

In the above example, incremental changes to document associations for process plans are published in the ESI response even if the preference is set to false.

Was this helpful?