Item Synchronization Collaboration

The Item Synchronization Collaboration synchronizes item information in compliance with UCCnet standards. It is used to maintain the consistency of a supplier's item information in UCCnet and to ensure that the information is kept current with the most recent data in the supplier's application. The supplier can also communicate new or changed item information to subscribing trading partners in UCCnet.

The Item Synchronization Collaboration accomplishes these tasks through a set of component collaboration templates:

UCCnet_ItemSync collaboration template
An object based on the UCCnet_ItemSync collaboration template performs processing to add, update, delist, or withdraw an item in response to events that occur in an Enterprise Resource Planning (ERP) application. A process flow is initiated in the collaboration object when it receives a triggering business object, containing the data for the event, from a connector for the ERP application. The collaboration object checks that fields required by UCCnet to contain information are not NULL. It also updates relational tables that track audit log entries, trading partners, and all published items. See the Solution Development Guide for more information about these tables.

UCCnet_requestWorklist collaboration template
An object based on the UCCnet_requestWorklist collaboration template sends query commands to UCCnet, via the iSoft Peer-to-Peer Agent and iSoftConnector or JTextISoftConnector.

These requests obtain the notifications necessary for completing the communication initiated by a UCCnet_ItemSync collaboration object. A UCCnet_requestWorklist collaboration object is triggered when it receives a UCCnetGBO_envelope business object from the JTextRWLConnector. The JTextRWLConnector sends this triggering business object after it polls an input file folder and discovers an XML message that contains a UCCnet worklist query command. (The mechanism by which the UCCnet worklist query command is placed in the input file folder is independent of the collaboration template, and must be set up by the user.)

Note:
The term "connector" used throughout this document refers to the runtime portion of an adapter. References to specific connectors are related to specific adapters, as follows:
  • "EmailConnector" refers specifically to the runtime component of an Adapter for e-Mail.
  • "iSoftConnector" refers specifically to the runtime component of an Adapter for iSoft.
  • "JTextISoftConnector" refers specifically to the runtime component of an adapter based on an Adapter for JText.
  • "JTextRWLConnector" refers specifically to the runtime component of an adapter based on an Adapter for JText.

If you are exchanging messages with UCCnet through an AS2/EDIINT interface protocol, use an iSoftConnector. If you are exchanging messages through the UCCnet Command Line Utility (CLU) or testing your installation, use a JTextISoftConnector.

UCCnet_processWorklist collaboration template
An object based on the UCCnet_processWorklist collaboration template processes the notifications that a UCCnet_requestWorklist collaboration object requested from UCCnet. This collaboration object is triggered when it receives a UCCnetGBO_envelope business object from an AS2 channel connector.
Note:
"AS2 channel connector" refers to an iSoftConnector or JTextISoftConnector, depending on the protocol used to exchange messages.

Notify_by_eMail collaboration template
An object based on the Notify_by_eMail collaboration template is used by a UCCnet_processWorklist collaboration object to pass communications to configured email addresses.

UCCnetXSD_CIN_Dispatcher collaboration template
An object based on the UCCnetXSD_CIN_Dispatcher collaboration object fulfills one of the following two tasks:

This collaboration template is used only if you are implementing a solution with the schema-based XML definition. Because objects based on this template can receive a triggering object from one of two collaboration objects, you must create two collaboration objects from this template.

ItemCommandRouter collaboration template
An object based on the ItemCommandRouter collaboration template is used to process ItemBasic business objects received from objects based on the ItemSync collaboration template. It processes an object in one of two ways:

This collaboration template is used only if you are implementing a solution with the schema-based XML definition.

To synchronize critical information throughout the item life cycle, the following business objects are used:

ItemBasic business object
This business object is used to trigger UCCnet_ItemSync, ItemCommandRouter, and UCCnetXSD_CIN_Dispatcher collaboration objects. It contains data attributes that are common across all the logical organizations that use the item data. A UCCnet_ItemSync collaboration object uses the ItemBasic business object to compare the data it contains with the local information stored about items processed by the solution and about trading partners who are sources or targets of retail item data. An ItemCommandRouter collaboration object uses the ItemBasic business object to determine how to route the data the business object holds. A UCCnetXSD_CIN_Dispatcher collaboration object uses the ItemBasic business object to build CatalogueItemNotification messages to send to trading partners.

UCCnetGBO_envelope business object
When a UCCnet_processWorklist collaboration object exchanges data with an AS2 channel connector, the data must be mapped between the business object used by the connector and the UCCnetGBO_envelope business object used by the collaboration object. This business object is used as follows:

The UCCnetGBO_envelope business object is the result of one of the following processes:

These maps simply deposit default values in the XMLDeclaration and DocType attributes so these values are in place when the resulting business object is processed by the collaboration objects.

UCCnetDTD_envelope business object
This business object is the result of an ItemBasic business object being converted by an AS2 channel connector when the DTD XML definition type is used. Unlike the UCCnetGBO_envelope business object, it does not contain default values for the XMLDeclaration and DocType attributes. Before this business object is processed by the collaboration objects included with the solution, it must first be transformed into a UCCnetGBO_envelope business object by passing through the UCCnetDTD_envelope_to_UCCnetGBO_envelope map.

UCCnetXSD_envelope business object
This business object is the result of an ItemBasic business object being converted by an AS2 channel connector when the XSD XML definition type is used. Unlike the UCCnetGBO_envelope business object, it does not contain default values for the XMLDeclaration and DocType attributes. Before this business object is processed by the collaboration objects included with the solution, it must first be transformed into a UCCnetGBO_envelope business object by passing through the UCCnetXSD_envelope_to_UCCnetGBO_envelope map.

Collaboration object setup

The following sections include information on each collaboration template's ports and setup procedures for collaboration objects created from the collaboration templates:

Port information for the UCCnet_ItemSync collaboration template

The following table provides information about the UCCnet_ItemSync collaboration template's ports. Use the ItemBasic business object for all ports.

Note:
Because every port must be bound, bind the unused port to the PortConnector. Doing so indicates that the port is unused without causing the collaboration object to provide additional functionality.

Table 1. UCCnet_ItemSync collaboration template's ports
Port name Bound to Function Verbs used
DestinationAppRetrieve PortConnector This port is currently unused. None
From Source application's connector Receives the triggering ItemBasic business object. Create

Update

To AS2 channel connector Passes the processed ItemBasic business object to the AS2 channel connector, which sends the data to the iSoft Peer-to-Peer Agent, which sends the command to UCCnet. Create

Port information for the UCCnet_requestWorklist collaboration template

The following table provides information about the UCCnet_requestWorklist collaboration template's ports. Use the UCCnetGBO_envelope business object for all ports.

Note:
Because every port must be bound, bind the unused port to the PortConnector. Doing so indicates that the port is unused without causing the collaboration object to provide additional functionality.

Table 2. UCCnet_requestWorklist collaboration template's ports
Port name Bound to Function Verbs used
DestinationAppRetrieve PortConnector This port is currently unused. None
From JTextRWLConnector Receives the input UCCnetGBO_envelope business object. Create
To AS2 channel connector Passes the processed UCCnetGBO_envelope business object to the AS2 channel connector, which transmits the data to the iSoft Peer-to-Peer Agent, which sends the command to UCCnet. None

Port information for the UCCnet_processWorklist collaboration template

The following table provides information about the UCCnet_processWorklist collaboration templates's ports. Bind the From, NEW_ITEM_PUBLICATION_REQUEST, ITEM_ADD_CHANGE, and INITIAL_ITEM_LOAD_REQUEST ports to the AS2 channel connector. Bind all the other ports to their respective collaboration objects based on the Notify_by_eMail collaboration template. Use the UCCnetGBO_envelope business object for all ports except for the CIN_DISPATCHER and DestinationAppRetrieve ports, which use the ItemBasic business object.

Table 3. UCCnet_processWorklist collaboration template's ports
Port name Bound to Function Verbs used
From AS2 channel connector A UCCnetGBO_envelope business object is passed in on this port. Create
NEW_ITEM_PUBLICATION_REQUEST AS2 channel connector A UCCnetGBO_envelope business object is passed out on this port. Create
ITEM_ADD_CHANGE AS2 channel connector A UCCnetGBO_envelope business object is passed out on this port. Create
INITIAL_ITEM_LOAD_REQUEST AS2 channel connector A UCCnetGBO_envelope business object is passed out on this port. Create
UNKNOWN_RESPONSE UCCnet_processWorklist_UNKNOWN_RESPONSEObject A UCCnetGBO_envelope business object is passed out on this port. Create
AUTHORIZATION_RESPONSES UCCnet_processWorklist_AUTHORIZATION_RESPONSESObject A UCCnetGBO_envelope business object is passed out on this port. Create
DEAD_LETTER_PUB_RECEIPT UCCnet_processWorklist_DEAD_LETTER_PUB_RECEIPTObject A UCCnetGBO_envelope business object is passed out on this port. Create
CATEGORY_ADD_CHANGE UCCnet_processWorklist_CATEGORY_ADD_CHANGEObject A UCCnetGBO_envelope business object is passed out on this port. Create
UNKNOWN_MESSAGES UCCnet_processWorklist_UNKNOWN_MESSAGESObject A UCCnetGBO_envelope business object is passed out on this port. Create
SIMPLE_RESPONSE UCCnet_processWorklist_SIMPLE_RESPONSEObject A UCCnetGBO_envelope business object is passed out on this port. Create
CATALOGUE_ITEM_CONFIRMATION UCCnet_processWorklist_CATALOGUE_ITEM_CONFIRMATIONObject A UCCnetGBO_envelope business object is passed out on this port. Create
CIN_DISPATCHER UCCnetXSD_CIN_Dispatcher_forICRObject or UCCnetXSD_CIN_Dispatcher_forPWLObject An ItemBasic business object is passed out on this port. Update
DestinationAppRetrieve A collaboration object or application that will provide the appropriate ItemBasic business object An ItemBasic business object with key information is passed out on this port. The retrieved ItemBasic business object is returned through the same port. Retrieve

Port information for the Notify_by_eMail collaboration template

The following table provides information about the Notify_by_eMail collaboration template's port. Use the UCCnetGBO_envelope business object for the port.

Table 4. Notify_by_eMail collaboration template's port
Port name Bound to Function Verbs used
From UCCnet_processWorklist collaboration object A UCCnetGBO_envelope business object is passed in on this port. The business object is incorporated into an email message and sent out to configured email recipients. Create

Port information for the UCCnetXSD_CIN_Dispatcher collaboration template

The following table provides information about the UCCnetXSD_CIN_Dispatcher collaboration template's ports.

Note:
Because every port must be bound, bind the unused port to the PortConnector. Doing so indicates that the port is unused without causing the collaboration object to provide additional functionality.

Table 5. UCCnetXSD_CIN_Dispatcher collaboration template's ports
Port name Bound to Function Verbs used
DestinationAppRetrieve PortConnector This port is currently not used. None
To AS2 channel connector A UCCnetGBO_envelope business object is passed out on this port. None
From ItemCommandRouterObject Receives an ItemBasic business object on this port. Create

Update

Port information for the ItemCommandRouter collaboration template

The following table provides information about the ItemCommandRouter collaboration template's ports.

Table 6. ItemCommandRouter collaboration template's ports
Port name Bound to Function Verbs used
From UCCnet_ItemSyncObject Receives an ItemBasic business object. Create

Update

TO_RCIR AS2 channel connector ItemBasic business object is passed out on this port. None
TO_CIN UCCnetXSD_CIN_Dispatcher_forICR_Obj ItemBasic business object is passed out on this port. None

Setting up a collaboration object

To set up any collaboration template supplied with the Item Synchronization Collaboration, as a standalone collaboration object, complete the following steps:

  1. Create the collaboration object.
  2. Bind the ports as described in Port information for the UCCnet_ItemSync collaboration template, Port information for the UCCnet_requestWorklist collaboration template, Port information for the UCCnet_processWorklist collaboration template, Port information for the Notify_by_eMail collaboration template, Port information for the UCCnetXSD_CIN_Dispatcher collaboration template, or Port information for the ItemCommandRouter collaboration template.
  3. Set the Configuration properties for the collaboration object.

Collaboration template processes

The following sections illustrate the process logic for the collaboration templates included with the WebSphere Business Integration Express for Item Synchronization:

Overall process logic

The supplied collaboration templates work together to handle workflows in systems using UCCnet XSDs or DTDs.

The XSD-based workflows include the following:

The DTD-based workflows include the following:

At the highest level, business data received from an ERP application (typically a supplier) is sent to the AS2 channel connector. This connector transforms the business object into an XML format that can be handled by the iSoft Peer-to-Peer Agent (in a WebSphere MQ message). The iSoft Peer-to-Peer Agent then sends the data to UCCnet. Detailed descriptions of the workflows exist in the Solution Development Guide.

Standard process logic

The UCCnet_ItemSync collaboration template uses the following standard processes for collaboration templates:

The UCCnet_requestWorklist, UCCnet_processWorklist, Notify_by_eMail, UCCnetXSD_CIN_Dispatcher, and ItemCommandRouter collaboration templates do not use standard processes.

Configuration properties

The following sections describe configuration properties for the collaboration templates included with the WebSphere Business Integration Express for Item Synchronization Collaboration:

Standard properties

The UCCnet_ItemSync collaboration template uses the following standard configuration properties for collaboration templates:

The UCCnet_requestWorklist, UCCnet_processWorklist, Notify_by_eMail, UCCnetXSD_CIN_Dispatcher, and ItemCommandRouter collaboration templates do not use standard configuration properties.

Properties specific to the UCCnet_ItemSync collaboration template

In addition to its standard configuration properties, this collaboration template has the following configuration properties.

Table 7. Configuration properties specific to the UCCnet_ItemSync collaboration template
Property name Property description Required
GtinDB_USER The user ID used to connect to the database containing the PROCESSED_GTIN and trading_partner tables. Yes
GtinDB_PASSWORD The password for the GtinDB_USER. Yes
JDBC_DRIVER Pointer to the driver code used to connect to the database containing the PROCESSED_GTIN and trading_partner tables. Only if the ICS does not register the driver in the Java(TM) Virtual Machine (JVM). The Microsoft(R) SQL driver, for example, is already registered in the JVM by the ICS and does not need to be specified.
JDBC_URL The JDBC URL corresponding to the JDBC_DRIVER specified. Yes
SEND_EMAIL_TO Defines the email address to which problems detected during execution of collaboration object processing are sent. This entry is for ICS administrators. Do not confuse this property with the Email notification address field, which is configured from the Collaboration General Properties tab when creating a collaboration object. No. Requires the EmailConnector to run if email is entered. The SEND_EMAIL property must be set also.
AUDITLOG_INSTANCE_NAME Identifies the tag in the UCCnet section within the InterchangeServer.cfg file under which other tags needed for audit logging are contained. The default value is UCCnet. This value must be correct for the CSIAuditLogger class to find the database information to make audit log entries. Yes
SUPPLIER_NAME The name of the partner that is synchronizing item information with UCCnet. This value is logged in audit entries. A sample entry is SAP. No

Properties specific to the UCCnet_requestWorklist collaboration template

This collaboration template has the following configuration properties.

Table 8. Configuration properties specific to the UCCnet_requestWorklist collaboration template
Property name Property description Required
DTD_URL Sets the value for the DocType line in outgoing XML. The default value is:
DOCTYPE envelope SYSTEM 
 "http://www.uccnet.net/  \
 xmlschema/2.2/Envelope.dtd"
 

For schema support, this value should be left blank.

No, unless the default value is incorrect for the environment to which the XML messages are being sent.
SET_UNIQUE_IDS Controls whether unique IDs (messageIdentifier and uniqueCreateorIdentification) are set in the output XML messages. Possible values for this property are:
  • ALL (the default value -- set all three unique IDs)
  • NONE
  • BLANK (set unique ID only if it is blank in the input)
No, unless the default value needs to be changed.

Properties specific to the UCCnet_processWorklist collaboration template

This collaboration template has the following configuration properties.

Table 9. Configuration properties specific to the UCCnet_processWorklist collaboration template
Property name Property description Required
DB_USER The user of the database associated with the WebSphere Business Integration Express for Item Synchronization system. Yes
DB_PASSWORD The password for the DB_USER. Yes
JDBC_DRIVER Pointer to the driver code used to connect to the database associated with the WebSphere Business Integration Express system. Only if the ICS does not register the driver in the JVM. The Microsoft SQL driver, for example, is already registered in the JVM by the ICS and does not need to be specified.
JDBC_URL The JDBC URL corresponding to the JDBC_DRIVER specified. Yes
SEND_EMAIL_TO Defines the email address to which problems detected during execution of collaboration object processing are sent. This entry is for ICS administrators. Do not confuse this property with the Email notification address field, which is configured from the Collaboration General Properties tab when creating a collaboration object. No. Requires the EmailConnector and a valid entry in this field to send email. If this field is left blank, no email is sent.
AUDITLOG_INSTANCE_NAME Identifies the tag in the UCCnet section within the InterchangeServer.cfg file under which other tags needed for audit logging are contained. The default value is UCCnet. This value must be correct for the CSIAuditLogger class to find the database information to make audit log entries. Yes
SUPPLIER_NAME The name of the partner that is synchronizing item information with UCCnet. This value is logged in audit entries. A sample entry is SAP. No
DTD_URL Sets the value for the DocType line in outgoing XML. The default value is:
DOCTYPE envelope SYSTEM 
 "http://www.uccnet.net/  \
 xmlschema/2.2/Envelope.dtd"
 

For schema support, this value should be left blank.

No, unless the default value is incorrect for the environment to which the XML messages are being sent.
AUTO_RESPOND Controls whether an automatic response is sent to UCCnet. The default value is: YES. No, unless the default value needs to be changed.

Properties specific to the Notify_by_eMail collaboration template

This collaboration template has the following configuration properties.

Table 10. Configuration properties specific to the Notify_by_eMail collaboration template
Property name Property description Required
DOCTYPE Sets the value for the DocType line in outgoing XML. The default value is:
DOCTYPE envelope SYSTEM 
 "http://www.uccnet.net/  \
 xmlschema/2.2/Envelope.dtd/"
 

For schema support, this value should be left blank.

No, unless the default value is incorrect for the environment to which the XML messages are being sent.
EMAIL_NOTIFICATION _RCPTS Email address of the recipients. Yes
EMAIL_SUBJECT Subject line of the email. This value can contain variables into which the collaboration object substitutes data from the business object dynamically. Variables to be substituted must be enclosed in the prefix characters ${ and the suffix character } (for example, ${variable_name}). Note: These characters might have to be changed to meet National Language requirements. Type text using the following escape codes:
  • ${getRoot} -- substitutes the entire triggering business object.
  • ${getDate} -- substitutes the current date and time.
  • ${getName} -- substitutes the name of the triggering business object.
  • ${getVerb} -- substitutes the verb of the triggering business object.
  • ${attribute} -- substitutes the value of the named attribute from the triggering business object. If the value for the variable_name does not match one of the specific values above, the collaboration object interprets it as the name of a business object attribute.

If the first character of the string for this value is an @ sign, the collaboration object loads the text from a filename following the @ sign.

See the Solution development guide for information about how the solution handles sending email and for a sample value for this property.

Yes
EMAIL_MESSAGE Body of the email. The processing of this field uses the same variables as the EMAIL_SUBJECT property. It also processes values beginning with the @ sign in the same manner. For example, in the following, the first character of the string is an @ sign, so the collaboration object loads the text from the filename following the @ sign:
@c:\IBM\WebSphereICS\UCCnet\collaborations\eMail\  \
 UCCnet_processWorklist_AUTHORIZATION_RESPONSES.mail  
 
Yes

Properties specific to the UCCnetXSD_CIN_Dispatcher collaboration template

In addition to its standard configuration properties, this collaboration template has the following configuration properties.

Table 11. Configuration properties specific to the UCCnetXSD_CIN_Dispatcher collaboration template
Property name Property description Required
CIN_DISPATCHER_GLN_FILE The fully qualified name of the file that holds the GLNs of trading partners subscribed to each category code. Default:
C:\gln_subsc.txt
 
Yes
TO_UCCNETGBO_PROCESSING_MAP Identifies the name of the map to use when mapping the application specific CWItemBasic business object to a general business object. This value should be set to CWItemBasic_to_UCCnetXSD_envelope_notifyCommand_CatalogueItem. Yes

Properties specific to the ItemCommandRouter collaboration template

This collaboration template uses no standard or collaboration-template specific configuration properties.

For related information, see the following:

Copyright IBM Corp. 1997, 2003