EAI Software Components Customizations
XML (eXtensible Markup Language) Schemas
This section describes how to customize XML schemas.Windchill ESI defines all Windchill ESI schemas via XSDs (eXtensible Schema Definition). XSDs were chosen over DTD (Document Type Definition), due to their semantic richness, scalability, and extensibility advantages. Customizers may want to customize XML schemas to add or change attributes that are being sent to SAP or to modify existing PRC calls.
EAI Software Components Schemas:
Data Model Schemas (CBO and ESIResponse): Change these schemas to add or change attributes coming from Windchill PDMLink.
Internal EAI Schemas (ESIResultService, ESIErrorHandling, ESILogging): Should only be changed if the core architecture of the solution is being changed. Otherwise, these would not be modified as part of a standard implementation.
Windchill Communication Schemas (ESIPostResult, ESIResponse): Modify these schemas if the communication between Windchill PDMLink and the EAI software components needs to be modified. This includes updating an RPC or adding a new one. Here are some example scenarios:
• Scenario 1: Add a new attribute to an object
◦ Description: Update the GetPart RPC to return a new attribute. This will result in an extra attribute being sent from Windchill to the EAI software components for a part.
◦ Customization Steps for EAI software components: Modify the ESIResponse schema to include this new attribute (The CBO would also need to be modified if this parameter is to be passed to the ERP system)
• Scenario 2: Add a new flag to the RPC
◦ Description: Update the GetPart RPC to include a new flag called Iteration to send iteration information if this flag is set to true. Out-of-the-box, the GetPart RPC only has two flags: Alternates and Documents.
◦ Customization Steps for EAI software components: Modify the ESIResponse and CBO schemas to account for the iteration information that may get sent from Windchill.
• Scenario 3: Add a new RPC
◦ Description: Add a new RPC called GetDocumentStructure to be able to query for document structures.
◦ Customization Steps for EAI software components: Modify the ESIResponse and CBO schemas to account for document structures that may get sent from Windchill.
 |
(i) All of the above would require updating process definitions in TIBCO BusinessWorks.
(ii) By GetPart RPC is meant the I*E task in <Windchill>\tasks\com\ptc\windchill\esi\part\GetPart.xml. However, out-of-the-box, ESI services invoke the getPart() API of class StandardESIService rather than the said I*E task. Thus, updating the GetPart RPC for scenarios 1 and 2 above would require creating an extension of class StandardESIService (or of class ESIWTPartRenderer) and providing an overridden version of the getPart() API as appropriate. Also, a new attribute (that specifies whether or not iteration information needs to be sent) should be added to the type ESISAPTarget in order that scenario 2 is catered to. See the section titled Query RPC Classes and Methods in the Windchill Enterprise Systems Integration Open API Guide for more information on the GetXXX RPCs and the corresponding StandardESIService APIs.
(iii) Although ESI services do not make use of any of the GetXXX RPCs out-of-the- box, they are still available for use and can be invoked if needed.
|
Flow of Windchill Interaction Schemas
An interaction with Windchill includes certain schemas that are sent back and forth over JMS. These schemas are utilized in the following order:
|
Schema
|
Description
|
|---|---|
|
ESIResponse
|
When a user initiates a publication request, Windchill generates a Response message and sends it to the EAI software components. This message contains the data that is published to SAP by the EAI software components.
|
|
ESIPostResult
|
When the EAI software components process data, they send a PostResult message back to Windchill for each business object in each organization that was processed with a success or failure flag. This allows Windchill to track which objects were successfully published and which require a resubmit.
|
|
ESIResultResponse
|
This is Windchill’s confirmation to the EAI software components that the transaction has completed and that its status has been recorded successfully in Windchill.
|
Tag Naming Conventions
Tags within Windchill ESI XML follow leading-capitalization notation, in which words are concatenated together and the first letter of each is capitalized, for example, PartNumber.
It is recommended for maximum clarity that XML tag names be given names that are as descriptive as possible. However, shorter names may be given to tags when the parent node or context of the tag is clear. For example, a <Number> tag within a Part structure should be taken as the Part Number. If the Number belongs to a child of another object, such as a Document Link, then the field would require at a minimum the string "DocumentNumber." It is recommended that in this case a more descriptive name be given to the field, such as "AssociatedDocumentNumber."
For more information see Section EAI Software Components Naming Standards – Naming Standards
SOAP Guidelines
SOAP is the XML RPC protocol that is used to communicate between the EAI software components and Windchill. Most JMS communications are SOAP-encoded.
All XML in the document outside the <arguments> tags must remain static. The XML structure inside these tags may be modified if the RPC in Windchill is modified equivalently.
ESIResponse, ESIResultResponse
All XML in the document outside the <COLLECTION> tags must remain static. The XML structure inside these tags may be modified if the RPC in Windchill is modified equivalently.
The COLLECTION object in the Response and all its child structures use HTML notation for their "<" and ">" – "<" and ">" respectively. Info*Engine creates well-formed XML documents; however, for security purposes, the JAX-M SOAP classes assume that any XML-reserved characters (" < ‘ > &) are to be converted to the corresponding XML entities (""," "<," etc.). Thus the body of the Response contains the HTML notation for these characters.
How to edit and import schemas
Schemas may be edited using any text editor, such as Windows Notepad, or XML editor, such as TIBCO TurboXML.
To view the main CBO schema, the schemas need to be extracted from BusinessWorks. CBO schemas are located in the /SharedConfigurations/ESISchemas/EAIMiddlewareSchemas folder. Since the CBO is made up of many referencing schemas, all of the referenced schemas must be loaded in order to view the high level objects.
1. Click on the Source Tab of each schema, copy the contents and paste them into a text editor. Save the file as the schema name that appears in BusinessWorks with a .xsd extension.
2. Each of the structures can be opened in Turbo XML.
3. When viewing a higher level object - one that references other schemas - Turbo XML prompts for the location of the referenced schemas. Browse to the location and click OK. This prompting continues until all the referenced schemas have been located.
Consider the following:
• Some of the schemas reference another schema more than once. For example, the BOM schema references the ObjectHeader and Effectivity schemas more than once. In this case, Turbo XML will generate a warning message that says "This element type has been defined more than once. The declaration can be ignored."
• When looking at a schema that references another schema, the referenced schema will appear in BW with a warning icon next to the element. This simply indicates that the element is locked and thus, you cannot modify the element. You can unlock the element by right clicking on the lock and selecting unlock. This will now allow you to modify the referenced schema as well. Refer to the TurboXML documentation for more information.
• It is strongly recommended that the CBO be modified using the UserArea schemas that have been created for each object as explained in the following section. Modifying the main CBO schema can lead to fatal errors.
To import a schema into BusinessWorks, add a "Schema Definition" activity to the repository. In the Source tab of the activity, choose "Load Schema." TIBCO BusinessWorks validates the XML at the time it is imported to the repository.