The WrapperFoundation collaboration template is a tool that makes it easy to develop user-defined wrapper collaborations that adhere to InterChange Server Express standards. A wrapper collaboration is a collaboration that handles the verification or synchronization of a business object for another collaboration. The calling collaboration sends a top-level business object that is referenced on its own triggering business object to the wrapper collaboration.
For example, the SalesOrderProcessing collaboration synchronizes the generic Order business object. Generic Order contains references to a generic Customer business object, which represents the customer making the order. Moreover, generic Order contains an array of generic OrderLineItem business objects. Each OrderLineItem references a generic Item business object, which represents the items ordered.
To modularize collaboration logic in such a situation, InterChange Server Express provides separate collaboration templates to process generic Order and the generic business objects that it references. For instance, InterChange Server Express provides the following templates to process an Order business object that references Customer and Item business objects:
Separating business object processing into different, specific collaborations not only enhances the reusability of each collaboration template, but also prevents two collaborations from modifying the same data at the same time. For more information, see Problems in concurrent processing.
To maintain consistency across all synchronization and access collaborations, InterChange Server Express builds the templates for these collaborations from the CollaborationFoundation template. To maintain consistency across all wrapper collaborations, all wrapper collaboration templates are built from the WrapperFoundation template. You can use WrapperFoundation to develop your own wrapper collaborations.
A wrapper collaboration object generated from the WrapperFoundation template can verify the existence of its triggering business object in the destination application or facilitate its synchronization. This section contains the following topics:
When a wrapper collaboration receives its reference-valued triggering business object with the Exists verb, it verifies the existence of its triggering business object by retrieving it from the destination application. The wrapper collaboration uses the Retrieve verb for this verification.
If the verification succeeds, the wrapper collaboration returns a success status to its calling collaboration.
If the verification fails, the wrapper collaboration's behavior depends on the setting of its CONTINUE_WITH_WARNING configuration property.
For more information and an illustration of the verification process, see the user guide for the particular wrapper collaboration you are using.
When a wrapper collaboration receives its reference-valued triggering business object with the Sync verb, it facilitates the synchronization of the business object. It does so by retrieving all values from the source application and sending the full-valued business object with the Create verb to the appropriate synchronization collaboration.
If the synchronization collaboration succeeds in creating the business object in the destination application, the wrapper collaboration returns a success status to its calling collaboration.
If the synchronization collaboration fails to create the business object in the destination application, the wrapper collaboration's behavior depends on the setting of its CONTINUE_WITH_WARNING configuration property.
To prevent the called synchronization collaboration from attempting to create an existing object and returning a failure status to the wrapper collaboration, use the following settings for the synchronization collaboration:
For more information and an illustration of the synchronization process, see the user guide for the wrapper collaboration template you are using.
Perform the following tasks when you want to use the WrapperFoundation template:
Figure 12 illustrates WrapperFoundation's ports. The tables that follow the figure provide information about each port.
Table 16 lists the features of the WrapperFoundation template's DestinationAppRetrieve port.
Port feature | Value |
---|---|
Business Object | Business object for which the wrapper collaboration is named. For example, CustomerWrapper sends a reference-valued Customer business object. This business object defaults to Controller. |
Verbs Used | Retrieve |
Purpose | Retrieves the business object from the destination application |
Bound To | Destination application's connector |
Table 17 lists the features of the WrapperFoundation template's From port.
Port feature | Value |
---|---|
Business Object | Business object for which the wrapper collaboration is named. For example, CustomerWrapper is triggered by a Customer business object. The default value is Controller. |
Verbs Used | Sync, Exists |
Purpose | Receives the triggering business object from the calling collaboration |
Bound To | The ToBusObjWrapper port of the calling collaboration |
Table 18 lists the features of the WrapperFoundation template's SourceApp port.
Port feature | Value |
---|---|
Business Object | Business object for which the wrapper collaboration is named. For example, CustomerWrapper retrieves a Customer business object from the source application. The business object defaults to Controller. |
Verbs Used | Retrieve |
Purpose | Retrieves the triggering business object from the source application. |
Bound To | Source application's connector |
Table 19 lists the features of the WrapperFoundation template's To port.
Port feature | Value |
---|---|
Business Object | Business object for which the wrapper collaboration is named. For example, CustomerWrapper sends a reference-valued Customer business object. This business object defaults to Controller. |
Verbs Used | Create |
Purpose | Sends a business object out of the collaboration. Usually used to send a full-valued business object to the relevant synchronization collaboration, |
Bound To | The From port of the collaboration that synchronizes or subscribes to the business object |
CustomerPartnerWrapper and ItemWrapper provide examples of InterChange Server Express collaborations that were built from WrapperFoundation and were modified to meet specific needs. This section describes those modifications as examples of ways you can modify the WrapperFoundation template.
Because different applications use CustomerPartner data in significantly different ways, CustomerPartnerWrapper handles its business object's keys in a unique way. Some applications require CustomerPartner to contain the identifier of its associated Customer object as well as its own identifier. Other applications do not require the Customer object's identifier and do not provide that identifier when sending the business object to the InterChange Server Express business integration system.
If a collaboration receives a CustomerPartner business object from a system that does not provide the Customer identifier, but must synchronize the object to a system that does require the identifier, the collaboration must obtain the additional data and provide it to the destination application. For this reason, CustomerPartnerWrapper does not use the command provided by WrapperFoundation to set the business object's keys:
SourceAppBusObj.setKeys(triggeringBusObj);
Instead of using the above command, which WrapperFoundation provides in the Sync scenario's Retrieve from Source node, CustomerPartnerWrapper gets the values for the key in the following two separate statements:
SourceAppBusObj.set("ObjectId", triggeringBusObj.getString("ObjectID")); SourceAppBusObj.set("AdditionalKey", triggeringBusObj.getString("AdditionalKey"));
Also located in the Sync scenario's Retrieve from Source node, these statements use both the ObjectId and the AdditionalKey attributes as the potential key.
In the Sync scenario's Prepare Object for Sync Collaboration node, WrapperFoundation contains the following code:
ToBusObj =(SourceAppBusObj).duplicate(); ToBusObj.setKeys(triggeringBusObj);
In the equivalent node, CustomerPartnerWrapper uses two separate statements to set the key for ToBusObj:
ToBusObj =(SourceAppBusObj).duplicate(); ToBusObj.set("ObjectId", triggeringBusObj.getString("ObjectId")); ToBusObj.set("AdditionalKey", triggeringBusObj.getString("AdditionalKey"));
Table 15 lists the four different types of generic item business objects delivered with InterChange Server Express. It is assumed that you are planning to define your own types of generic item business objects to meet the specific needs of your environment. Therefore, the ItemSync collaboration was designed to be easily extended to handle user-defined triggering and prerequisite item business objects. For more information, refer to the user's guide for the ItemSync collaboration.
Because ItemWrapper can be triggered by any type of generic Item business object, the collaboration must first determine the type of business object that triggered it. Therefore, ItemWrapper's Scenario Definitions for both the Verify and Sync scenarios contain the following statement, which is not found in other wrapper collaboration templates:
BusObj getItemFlvrBusObj = new BusObj(triggeringBusObj.getType());
The above statement creates a business object unique to ItemWrapper (getItemFlvrBusObj). This statement also gets the type of the triggering business object and uses it to set the type of the business object used in ItemWrapper's verification and synchronization scenarios.
All wrapper collaborations create a DestinationAppBusObj and a SourceAppBusObj business object in the Declarations section of the collaboration's Template Definition. The type of these business objects is the same as that of the triggering business object. Whereas other wrapper collaborations use DestinationAppBusObj and SourceAppBusObj to retrieve data from the destination and source applications, ItemWrapper uses getItemFlvrBusObj. Before retrieving the item from the destination application in the Verify scenario or from the source application in the Sync scenario, ItemWrapper uses the key values of triggeringBusObj to set the keys of getItemFlvrBusObj, as follows:
getItemFlvrBusObj.setKeys(triggeringBusObj);
In the Sync scenario, ItemWrapper uses the values in getItemFlvrBusObj to create the business object that it sends to the destination, as follows:
toItemFlvrBusObj = getItemFlvrBusObj.duplicate(); //toItemFlvrRef.copy(getItemFlvrRef); toItemFlvrBusObj.setKeys(triggeringBusObj);
A standard wrapper collaboration, such as ContactWrapper, creates a ToBusObj, which it instantiates from SourceAppBusObj. The following example illustrates this creation and instantiation:
ToBusObj =(SourceAppBusObj).duplicate(); ToBusObj.setKeys(triggeringBusObj);
Because ItemWrapper does not use the standard FromBusObj, the collaboration's code comments out the code in the Initialize Variables node of both the Verify and Sync scenarios.
You can extend WrapperFoundation to contain additional ports, properties, processing logic, and messages. For more information, see Extending CollaborationFoundation.