ERP Connector Customization Options
Background
As mentioned in the ERP Connector Customizations section, the following options exist for customizing ERP Connector viz.,
1. Using a distribution target extension and
2. Using a custom Info*Engine task for delivering the response message to the required destination.
Apart from these, ESI services and Windchill may be customized as mentioned in the Windchill ESI Services Customizations and Windchill Customizations sections respectively, thereby catering to additional customization scenarios.
This section describes the default I*E tasks that are used for delivering the ESI response to destinations that are supported out-of-the-box viz., File, FTP and Email type distribution targets.
Info*Engine Tasks
ERP Connector uses certain Info*Engine tasks for delivering the ESI response to the relevant distribution targets, and for invoking the PostResult RPC as appropriate. The following sections describe the tasks that are used out-of-the-box. See the Configurable Options section for information on the input parameters that get passed to the task.
 |
Each of the I*E tasks in ExportTo<XXX>.xml invokes the PostResult RPC by executing the task in <Windchill>/tasks/com/ptc/windchill/esi/export/ParseAndProcessResult.xml.
|
ExportToFile
This task makes use of the custom webject named Write-To-File. Given the content, it creates a file whose name and location are determined by the values in the webject parameters FILE_NAME and PATH respectively.
• Webject Parameters:
Parameter: FILE_NAME
Description: The name of the file to create. This parameter is obtained by concatenating the value of the ERP Connector preference ESI Response File Prefix the name of the organization associated with the primary business object being exported and the idNumber attribute of the underlying ESI transaction, obtained from the task parameter transaction. An underscore (‘_’) character is used as a separator between the concatenated tokens and a file extension of .xml or .jar is used, depending on whether the data is exported in ESI XML or PLM format respectively.
|
|
The task makes use of the ESIUtility API getResponseFileName() for fetching the file name.
|
Parameter
: PATH
Description: The path to the location where the file needs to be created. This parameter is obtained from the distribution target attribute Path.
Parameter: CONTENT
Description: The data (ESI response in the XML form) to be written to the file. This is obtained from the VDB associated with the task. This parameter is needed only when the GROUP_IN parameter is not specified.
|
|
This parameter has relevance only when exporting data in the ESI XML format.
|
Parameter: XSL_URL
Description: URL for the XSL stylesheet to apply to the XML data before writing to the file. This is fetched from the distribution target attribute XSL_URL.
Parameter: XSL_DBUSER
Description: User name to be used to access the XSL stylesheet. This parameter is required if the XSL_PASSWD parameter is specified. It is fetched from the distribution target attribute XSL_DBUser.
Parameter: XSL_PASSWD
Description: Password to be used to access the XSL stylesheet. It is fetched from the distribution target attribute XSL_Password.
Parameter: XSL_PARAM
Description: XSL parameters to be used while applying the stylesheet to the XML data. It is fetched from the distribution target attribute XSL_Parameters.
Note: The parameters XSL_URL, XSL_DBUSER, XSL_PASSWD and XSL_PARAM are relevant only when exporting data in the ESI XML format.
Parameter: GROUP_IN
Description: Name of the input Info*Engine group that holds the IeCollection object representing the ESI response message, the primary business object and the distribution target that the data is being exported to. These are held in Att objects named CONTENT, PRIMARY_OBJECT and DISTRIBUTION_TARGET
respectively. This parameter is needed only if the CONTENT parameter is not specified (for e.g., when exporting the data in PLM format).
Default value: input.
Parameter: GROUP_OUT
Description: Name of the output Info*Engine group to be created upon executing the task.
Default value: output.
ExportToFTP
This task makes use of the custom webject named Write-To-Ftp. Given the content, it creates a file whose name and FTP location are determined by the values in the webject parameters FILE_NAME and FTP_URL respectively.
◦ Webject Parameters:
Parameter: FILE_NAME
Description: The name of the file to create at the specified FTP location. This parameter is obtained by concatenating the value of the ERP Connector preference ESI Response File Prefix, the name of the organization associated with the primary business object being exported and the idNumber attribute of the underlying ESI transaction, obtained from the task parameter transaction. An underscore (‘_’) character is used as a separator between the concatenated tokens and a file extension of .xml or .jar is used, depending on whether the data is exported in ESI XML or PLM format respectively.
|
|
The task makes use of the ESIUtility API getResponseFileName() for fetching the file name.
|
Parameter: FTP_URL
Description: The URL to the FTP server consisting of a username and a password for the server, among other attributes. If username and password are not provided, anonymous login is used. The URL is built using the distribution target attributes FTP_UserID, FTP_Password, FTP_Host, FTP_Port and FTP_Path.
Parameter: FTP_MODE
Description: Mode of transfer associated with the FTP operation. This could take the following values:
ASCII (or a) - for text content.
BINARY (or i) - for binary/image files.
Parameter: CONTENT
Description: The data (ESI response in XML form) to be written to the file at the specified FTP location. It is obtained from the VDB associated with the task. This parameter is needed only when the GROUP_IN parameter is not specified.
1. A value may optionally be specified for the parameter SOURCE_FILE – in such a case, the value specified for CONTENT will be ignored, but the contents of the specified file will be uploaded to the FTP location.
2. The CONTENT parameter has relevance only when exporting data in the ESI XML format.
Parameter: SOURCE_FILE
Description: Path to a file whose contents are to be uploaded to the FTP server. If this parameter is not specified, the value in the CONTENT parameter (or the value of the Att named CONTENT in the GROUP_IN parameter) will be written to a file under <Windchill>/temp (by invoking the writeToFile(task : Task) API), and its contents will then be uploaded to the FTP location.
|
|
The writeToFile(task : Task) API is same as the one invoked by the Write- To-File webject for delivering the ESI response to a File target.
|
Parameter: XSL_URL
Description: URL for the XSL stylesheet to apply to the XML data before writing to the FTP location. This parameter is fetched from the distribution target attribute XSL_URL.
Parameter: XSL_DBUSER
Description: User name to be used to access the XSL stylesheet. This parameter is required if the XSL_PASSWD parameter is specified. It is fetched from the distribution target attribute XSL_DBUser.
Parameter: XSL_PASSWD
Description: Password to be used to access the XSL stylesheet. It is fetched from the distribution target attribute XSL_Password.
Parameter: XSL_PARAM
Description: XSL parameters to be used while applying the stylesheet to the XML data. It is fetched from the distribution target attribute XSL_Parameters.
|
|
The parameters XSL_URL, XSL_DBUSER, XSL_PASSWD and XSL_PARAM are ignored if SOURCE_FILE was specified for the webject. or when exporting data in PLM format.
|
Parameter: GROUP_IN
Description: Name of the input Info*Engine group that holds the IeCollection object representing the ESI response message, the primary business object and the distribution target that the data is being exported to. These are held in Att objects named CONTENT, PRIMARY_OBJECT and DISTRIBUTION_TARGET respectively. This parameter is needed only if the CONTENT parameter is not specified (for e.g., when exporting the data in PLM format).
Default value: input.
|
|
A value may optionally be specified for the parameter SOURCE_FILE – in such a case, the value specified for GROUP_IN will be ignored, but the contents of the specified file will be uploaded to the FTP location.
|
Parameter: GROUP_OUT
Description: Name of the output Info*Engine group to be created upon executing the task.
Default value: output.
ExportToSMTP
This task makes use of the message webject named Send-Mail. Given the content, it sends the ESI response to the email addresses provided.
|
|
See the Info*Engine User's Guide for more information on the Send-Mail webject.
|
Note:
• Webject Parameters:
Parameter: MAIL_SERVER
Description: The internet domain name of the SMTP server to which the content will be sent for routing to the recipients. It is fetched from the distribution target attribute EmailHost. If this attribute is not specified on the distribution target, the parameter is fetched from the Windchill property wt.mail.mailhost.
Description: The address (or a comma separated list of addresses) to which the email should be sent. It is fetched from the distribution target attribute To.
Parameter: CC
Description: The address (or a comma separated list of addresses) to which the email should be sent as a carbon copy. If username and password are not provided, anonymous login is used. The parameter is fetched from the distribution target attribute Cc.
Parameter: BCC
Description: The address (or a comma separated list of addresses) to which the email should be sent as a blind carbon copy. If username and password are not provided, anonymous login is used. The parameter is fetched from the distribution target attribute Bcc.
Parameter: FROM
Description: The e-mail address of the originator of the message. It is fetched from the distribution target attribute From. If this attribute is not specified on the distribution target, the parameter is fetched from the Windchill property wt.mail.from.
Parameter: REPLY_TO
Description: The e-mail address (or a comma separated list of addresses) to which replies should be sent. It is fetched from the distribution target attribute ReplyTo.
Parameter: SUBJECT
Description: The subject header of the message being sent. It is obtained by adding the string "ESI Release for Transaction ID " as a prefix to the idNumber attribute of the underlying transaction, which in turn is obtained from the task parameter transaction.
Parameter: CONTENT
Description: The data (ESI response in XML form) to be sent to the destination address (or addresses). It is fetched from the VDB associated with the task.
|
|
1. The above description is applicable only when exporting the data in ESI XML format. When exporting in PLM format, the CONTENT parameter is simplyset to the following message – "See the attachment for the output."
2. When exporting the data in ESI XML format, the e-mail that is sent to the destination address holds the ESI response message not only as its body but as an attachment as well. However, when using the PLM format, the e-mail holds the message mentioned in (1) as its body, and the output jar file as an attachment.
|
Parameter: XSL_URL
Description: URL for the XSL stylesheet to apply to the XML data before sending to the specified address (or addresses).
Parameter: XSL_DBUSER
Description: User name to be used to access the XSL stylesheet. This parameter is required if the XSL_PASSWD parameter is specified.
Parameter: XSL_PASSWD
Description: Password to be used to access the XSL stylesheet.
Parameter: XSL_PARAM
Description: XSL parameters to be used while applying the stylesheet to the XML data.
Note: The parameters XSL_URL, XSL_DBUSER, XSL_PASSWD and XSL_PARAM are relevant only when exporting data in the ESI XML format.
Parameter: GROUP_OUT
Description: Name of the output Info*Engine group to be created upon executing the task.
Default value: output.
ParseAndProcessResult
As mentioned in the Configurable Options section, each of the tasks in ExportTo<XXX>.xml invokes the task in ParseAndProcessResult.xml if either
1. the relevant webject could be executed successfully and the ERP Connector preference Enable Post Result has a value Yes or
2. an error was encountered while executing the webject.
As for the task in ParseAndProcessResult.xml, it invokes the PostResult RPC by executing the I*E task specified by the ERP Connector preference ESIPostResultMethod. When processing a given ESI transaction, the PostResult RPC is invoked once for every sub- transaction and once for the transaction. This in turn is repeated for every destination, considering that there will be as many ESI transactions in a release as there are destinations.
The following parameters are passed to the task in ParseAndProcessResult.xml:
|
Parameter Name
|
Description
|
|---|---|
|
supporting-adapter
|
Name of the Windchill adapter instance. This is used as the INSTANCE parameter while executing the PostResult RPC using the Apply-Service webject.
|
|
target
|
The ESITarget object that the ESI response message is being sent to.
|
|
response
|
The ESI response message in XML form.
|
|
successful
|
A true is passed for this parameter if the ESI response could be delivered successfully; otherwise, a false.
|
|
msg
|
A message that is used for setting the message attribute on the sub-transaction or the transaction.
|
|
objectID
|
UFID of the primary business object that was released.
|
|
type
|
String representing the type of the primary business object – for e.g., "com.ptc.windchill.esi.Part". It is used for setting the releaseClass attribute on the sub- transaction.
|
|
transactionID
|
idNumber attribute of the ESITransaction object that represents the underlying transaction.
|
|
username
|
Name of the Windchill user that released the object.
|
|
|
By default, the task in ParseAndProcessResult.xml invokes the task in <Windchill>/tasks/com/ptc/windchill/esi/releaseResult/PostResult.xml. Also, it applies the style-sheet in <Windchill>/tasks/com/ptc/windchill/esi/lite/GetPostResultInfoForTarget.xsl on the ESI response message, to fetch certain arguments to the PostResult RPC for a sub-transaction. See the Windchill Enterprise Systems Integration Open Application Programming Interface Guide for more information on the PostResult RPC and the parameters that are passed to it.
|
Configurable Options
ERP Connector preferences control certain configurable options for ERP Connector distribution targets.
The options are:
◦ Specifies the prefix to be used for file names containing the ESI response. For example, the name of the file that is written to a file target (or that is sent as an attachment to an Email target) is obtained by concatenating the value of this preference the name of the organization associated with the primary business object being exported and to the idNumber attribute of the underlying ESI transaction, together, using the underscore (‘_’) character as a separator.
Preference name: ESI Response File Prefix
Default value: ESIResponse_
◦ Defines whether or not the generated ESI response message should be cached. When this preference is set to Yes, the generated ESI response is cached at a location specified by another preference. The cached file has the same name as the one containing the normal ESI response.
Preference name: Enable Response Cache
Default value: Yes
• Defines the path to the location where a cached version of the ESI response is created. This preference assumes significance only when the preference Enable Response Cache has a value Yes.
Preference name: ESI Response Cache Location
Default value: <Windchill>/logs/esicache
Typical Customizations
A few customization scenarios that may be achieved with ERP Connector are listed below:
◦ Send the ESI response in XML form to a target type other than file, FTP or Email – for example, to a JMS queue. This would require having to create a soft type distribution target extension and defining its attributes as appropriate. A custom Info*Engine task that invokes a custom webject (i.e., of type EXT) needs to be authored as well.
◦ Deliver the ESI response to any of the available target types (file, FTP or Email) using a custom Info*Engine task.
◦ Customize ESI services to generate the ESI response in a custom format. For example, the ESI response meta information file may be modified in a variety of ways to achieve this. Also, when using a custom target, custom versions of the getDestinationId() and getPlantName() APIs may be used. See the Windchill ESI Services Customizations section for the various options that are available for customizing ESI services.
|
|
Modifying the contents of the ESI response meta information file will have no impact whatsoever on the format of the ESI response message when exporting the data in PLMformat.
|