CollaborationFoundation template

The CollaborationFoundation collaboration template is a tool that facilitates the development of user-defined collaborations that perform functions such as the following:

The following sections provide additional information about the CollaborationFoundation template:

CollaborationFoundation features

A collaboration object generated from the CollaborationFoundation template can perform a Create, Retrieve, Delete, or Update action on a business object in the destination application that corresponds to the collaboration's triggering business object.

Handling the triggering business object

Behavior of the Retrieve verb

CollaborationFoundation is designed to enable the triggering business object to use the Retrieve verb. If the collaboration is bound to a source connector that makes a synchronous request, the triggering business object's values are returned to the source connector as soon as the collaboration completes its processing. The values are returned as if the business object's values had been passed by reference.

This template provides the standard properties shown in Table 9; these properties affect the behavior of business flows.

Table 9. CollaborationFoundation standard properties for business flow
Standard property Description
CONVERT_CREATE Configures a collaboration object to convert the verb sent to the destination from Create to Update if the triggering business object already exists in the destination application.
CONVERT_UPDATE Configures a collaboration object to convert the Update verb to the Create verb if the business object does not already exist in the destination application.
USE_RETRIEVE Configures a collaboration object to retrieve its triggering business object from the destination application before it synchronizes data. This property is useful when performing compensation processing and when setting the verb based on whether the business object already exists in the destination application.
ADDITIONAL_RETRIEVE Configures a collaboration object to retrieve the business object from the destination application after it synchronizes data. This property is useful when the source application requires a full-valued business object to be returned from the destination application, but the destination application's connector does not return a complete business object after creating or updating its data.

Figure 8 shows the main business flow for a collaboration when the USE_RETRIEVE property evaluates to false.

Figure 8. CollaborationFoundation main business-process flow
The figure is a detailed flowchart of how a CollaborationFoundation collaboration creates a business object. The process starts with a triggering business object and shows how information is copied into a new business object, if required. If the verb is retrieve, the collaboration uses the retrieve process to get the already existing business object. Also shown in the flowchart is how the collaboration sends the resulting business object to the destination. If required, the collaboration will perform additional retrieves.
Filtering data in the triggering business object

You can configure a collaboration object to filter data in specified attributes of the triggering business object. You can use the results of the filtering to determine whether the collaboration needs to synchronize a triggering business object with specific data. The template provides the following four properties for filtering data:

For information on adding additional properties that can specify multiple filtering attributes, see the description of the 1_FILTER_ATTRIBUTE property in Appendix. Standard Collaboration information. In addition, Figure 93 illustrates the collaboration's filtering behavior.

To filter on a second attribute, the CollaborationFoundation template provides the following set of properties:

To filter on multiple attributes, provide a set of filter properties for each property. Provide a unique number for each set of properties. In other words, the filter properties for the third attribute can use 3_ as the prefix. Although the prefix must be different for each set of attributes, the property names themselves must be identical to those shown above.

Error handling

CollaborationFoundation provides standard properties for error handling. Table 10 describes these properties.

Table 10. Standard properties for error handling
Error-handling property Description
INFORMATIONAL_EXCEPTION Specifies whether a collaboration object must end successfully and send the exception to a trace, or end in failure and raise an exception to be logged.
SEND_EMAIL Specifies whether a collaboration object sends email to a specified address when an exception occurs, regardless of the value of INFORMATIONAL_EXCEPTION.

E-mail process for error handling illustrates the collaboration's email process for error handling.

For both of the error-handling properties, you can specify the behavior for all exceptions or for a smaller set of comma-delimited message numbers. The message numbers correspond to those in the collaboration's message file (collaborations\messages\CollaborationFoundation.txt).

Using the CollaborationFoundation template

Perform the following tasks to use the CollaborationFoundation template:

  1. Copy the entire CollaborationFoundation template to your development area.
  2. Rename the collaboration template to reflect the collaboration you are building.
  3. Within Process Designer Express, use the Ports and Triggering Events tab of the Template Definitions window to change the type of the existing ports (DestinationAppRetrieve, To, From) to assign the appropriate business objects to them. For more information, see CollaborationFoundation ports.
  4. Create additional sets of filter properties if you want your collaboration to filter more than one business object attribute.

    InterChange Server Express provides a set of configuration properties that enable you to include or exclude business objects from synchronization based on specified values in a specified attribute. If you want to filter synchronization based on values in more than one attribute, you must create an additional set of the configuration properties for each attribute you want to evaluate. For more information, see Standard properties for collaboration templates.

  5. If necessary, create additional collaboration functionality by adding code to the Additional Processing subdiagrams. These sub diagrams have no functionality in the CollaborationFoundation template. They exist to enable easy customization of the collaboration.
  6. Save the collaboration template and compile it.

CollaborationFoundation ports

Figure 9 illustrates CollaborationFoundation's ports. The tables that follow provide information about each port.

Figure 9. CollaborationFoundation collaboration ports

The DestinationAppRetrieve port

Table 11 lists the features of the CollaborationFoundation's DestinationAppRetrieve port.

Table 11. Port features (DestinationAppRetrieve port)
Port feature Value
Business Object A reference-valued BusObj. The default value is Controller.
Verbs Used Retrieve
Compensating Verbs None
Purpose Retrieves the full-valued business object from the destination and uses it to set the verb.
Bound To Destination application's connector
Configuration Property USE_RETRIEVE

The To port

Table 12 lists the features of the CollaborationFoundation's To port.

Table 12. Port features (To port)
Port feature Value
Business Object A full-valued BusObj. The default value is Controller.
Verbs Used Create, Update, or Delete
Compensating Verbs None
Purpose Sends a business object out of the collaboration. Often the collaboration sends a copy of the triggering business object through this port to the destination.
Bound To Destination application's connector or another collaboration (for additional processing)
Configuration Property None

The From port

Table 13 lists the features of the CollaborationFoundation's From port.

Table 13. Port features (From port)
Port feature Value
Business Object triggeringBusObj (the default value is Controller)
Verbs Used Create, Retrieve, Update, or Delete
Compensating Verbs None
Purpose Receives the triggering business object
Bound To Source application or a calling collaboration
Configuration Property None

Copyright IBM Corp. 2004, 2005