Modifying collaboration objects

This section describes how to modify a collaboration object. You might have to modify the port bindings or properties of a collaboration object for the following reasons:

To modify a collaboration object, double-click the collaboration object in the Collaboration Objects folder either in the Integration Component Libraries folder or in the User Projects folder in System Manager.

Collaboration object views

There are two view representations for collaboration objects: graphical view and tree view. The following sections describe them and their benefits.

Collaboration object graphical view

The collaboration object graphical view is the view shown by default after creating a new collaboration object. As shown in Figure 38, the graphical view represents the collaboration object with an icon in the center of the view and with icons representing each port in the collaboration radiating outward. This view is useful to demonstrate the "flow" of the business process: you can drag-and-drop ports around the view pane to position them in places that suggest the directionality of the collaboration communication. For instance, you can position the port that receives the triggering business object on the left-hand side of the pane and position the port that sends the business object to the destination application on the right-hand side of the pane.

Note:
There is no way for the system to be able to automatically display the ports that receive triggering business objects on one side and the ports that send business objects to destination applications on another side. The developer of a collaboration template determines the naming and function of its ports and there is no way for the system to know the role a developer had in mind for a particular port. You should read the documentation for a collaboration template and then reposition the ports in the graphical view of any collaboration objects based on the template in a way that best facilitates your use of the tools.

Figure 38. Collaboration object graphical view


Collaboration object tree view

You can switch to the collaboration object tree view from the graphical view by clicking the Tree View tab. As shown in Figure 39, the tree view represents the collaboration object with an icon at the top of a hierarchical tree and represents the ports with icons branching underneath it. Although this view does not suggest the "flow" of the business process very well, it presents the ports and their bound components in a very orderly manner, making it easier to find a particular port that you might need to reconfigure. This can be particularly helpful with collaboration objects based on templates that have many ports, which can appear very confusing in the graphical view. You cannot rearrange the icons in the collaboration object tree view.

Figure 39. Collaboration object tree view


Binding collaboration object ports

Collaboration ports are the interfaces through which collaborations send and receive business objects. You bind collaboration object ports to different components to configure them to exchange the type of business object supported by the port.

You can bind collaboration object ports when creating the collaboration object initially by using the wizard as described in Creating a collaboration object. You can also edit the port bindings after creating the collaboration object. To edit the port bindings in the graphical view, either double-click the icon for a port or right-click the icon for a port and choose Bind Port from the context menu. To edit the port bindings in the tree view, right-click the icon for a port and choose Bind Port from the context menu.

To bind a collaboration port to an internal component such as a connector or the port of another collaboration object, leave the radio button labeled Internal in the Type pane enabled and see Configuring internal port bindings.

To bind a collaboration port to an external programmatic entity such as a web servlet, enable the radio button labeled External in the Type pane and see Configuring external port bindings.

Configuring internal port bindings

To bind a collaboration port to a connector or to the port of another collaboration object, do the following:

  1. Enable the radio button labeled Internal in the Type pane of the port configuration dialog.
  2. Select the appropriate component type, either Connector or Collaboration in the Bind With pane.
  3. Select the specific component from the list.
  4. Click OK.

Figure 40 shows the port configuration dialog with an internal binding type.

Figure 40. Configuring internal collaboration object ports


Only the components that support the type of business object definition shown in the Business Object Definition field are listed in the dialog. If you do not see a component you expect to see listed then it is either not of the specified type (and you should change the Bind With radio button), or the component does not support the business object definition. If the Bind With radio button is set to the proper component type and the component you expect to see is not shown, then modify the definition for the particular component to add support for the business object definition and then launch the port configuration dialog afterwards.

You must bind all of the ports of a collaboration object to start it, so a collaboration object cannot run until you have bound all of its ports.

Some collaboration templates have ports defined that support an optional course of business logic. For instance, many collaboration templates are designed so that they can attempt to retrieve the entity that might have just been created in the destination application to ensure that the operation was successful. This sort of behavior is frequently optional and configurable through the collaboration-specific properties of the collaboration. All of the ports of a collaboration object must be bound to a component for it to start, as mentioned earlier, so even if you do not intend to take advantage of the optional behavior you must configure ports that might exist only to support it. In this case, just add support for the business object definition to an unused component (such as the PortConnector) and be sure to configure the collaboration properties to not use the optional functionality.

Configuring external port bindings

To bind a collaboration port to a connector or to the port of another collaboration object, do the following:

  1. Enable the radio button labeled External in the Type pane of the port configuration dialog.
  2. In the Configure As pane, select the Incoming radio button if business object requests are received by the port, or select the Outgoing radio button if business object responses are sent out of the port.
  3. Do one of the following to associate the desired components with the port:
  4. Click OK.

Figure 41 shows the port configuration dialog with an external binding type.

Figure 41. Configuring external collaboration object ports


For more information on implementing integrations with external programmatic entities, see the Access Development Guide.

Configuring collaboration object general properties

Collaboration general properties are properties that belong to all collaboration objects, regardless of how the developer designed the template upon which the objects are based. They affect the behavior of the collaboration object in the system as a whole.

To modify a collaboration object's general properties, do the following:

  1. Access the collaboration object Properties dialog by doing one of the following:
  2. Set the property to the desired value. For a description of each property and their possible values, see Table 15 and the sections that follow.
  3. Click OK.


Table 15. Collaboration object general properties

Property name Possible values
Create from template Read-only name of the template upon which the collaboration object is based
Effective transaction level None, Minimal Effort, Best Effort, or Stringent
Minimum transaction level None, Minimal Effort, Best Effort, or Stringent, depending on the design of the collaboration template
System trace level 0 - No Tracing,
1 - Collaboration operations,
2 - And collaboration events,
3 - And state transactions,
4 - And incoming/outgoing messages,
5 - And detailed message contents
Collaboration trace level 0 through 5
Email notification address any valid e-mail alias
Pause when critical error occurs checked or unchecked
Maximum number of concurrent events 0 through 9999
Persist service call in transit state checked or unchecked
Recovery mode Always or Deferred
Implicit database transaction checked or unchecked
Max event capacity an integral value between 1 and 2147483647
Blocking type checked or unchecked

Create from template

This read-only text field displays the name of the collaboration template on which the collaboration object is based.

Effective transaction level

The effective transaction level is a range between the highest maximum transaction level of all collaboration objects and the lowest maximum transaction level of all connectors that are bound to the object.

You can lower the effective transaction level of a collaboration if you need to bind to a connector that does not support a certain transaction level.

To change the effective transaction level, choose the desired value from the Effective transaction level drop-down list and then click OK.

Note:
You cannot bind objects whose transaction levels are incompatible. If you need to bind such objects to a collaboration, you must adjust the supported transaction levels accordingly.

Minimum transaction level

The minimum transaction level specifies the lowest transaction level of the collaboration template and any collaboration objects based on it.

For instance, if the developer of the collaboration template specified a minimum transaction level of Best Effort for the template, then all objects based on the template must operate at Best Effort or Stringent. As described in the section on Effective transaction level, all components bound to the collaboration object must support its effective transaction level. The minimum transaction level is, then, a way for the collaboration template developer to dictate the lowest transaction level at which the entire interface in which collaboration objects based on the template will execute.

The Minimum transaction level field is read-only when configuring a collaboration object; it can only be changed in the collaboration template.

For more information about making changes to collaboration templates, see the Collaboration Development Guide.

System trace level

You can configure collaboration objects so that information about the execution of the collaboration is reported in the server output. To do so, select the desired value in the System trace level drop-down menu. Table 16 describes the different levels and the types of information reported at each:


Table 16. System trace levels

System trace level Reported information
0 - No Tracing

No information is traced at this level
1 - Collaboration operations

Traces the receipt of business objects from connectors and the starting of scenarios
2 - And collaboration events

Prints messages for level 1, as well as the start and completion of each scenario, including both forward execution and rollback
3 - And state transactions

Prints messages for levels 1 and 2, as well as the execution of each scenario decision block or action node
4 - And incoming/outgoing messages

Prints messages for levels 1 through 3, as well as the sending and receipt of each business object by each scenario
5 - And detailed message contents Prints messages for levels 1 through 4, as well as printing the structure of the business object being processed, with the value of each attribute

Collaboration trace level

Collaboration developers can code collaboration templates with template-specific tracing. While system tracing (described in System trace level) offers tracing information about the collaboration runtime in general, collaboration tracing provides information about the specific collaboration; for instance:

To set the collaboration trace level, select the desired value in the range of 0 through 5 in the Collaboration trace level drop-down menu.

To find out what kind of information is reported at the different trace levels for a particular collaboration, reference the documentation for that collaboration template.

For more information about making changes to collaboration templates to implement collaboration tracing, see the Collaboration Development Guide.

Email notification address

You can configure a collaboration object so that e-mail notifications are sent in the event of errors related to that specific object. This facilitates interface-specific administration if that is desired. For instance, a site might have one administrator responsible for errors related to InterChange Server Express itself, another administrator specifically for a customer account synchronization interface, and another administrator specifically for an order processing interface.

Type the SMTP-compliant e-mail addresses to which you want error notifications sent into the Email notification address field. You can type multiple addresses as long as they are separated by commas. For more information on enabling the system to send e-mail notifications, see Configuring e-mail notification properties using System Manager and the System Administration Guide.

Many collaboration templates feature greater configurability with regard to when e-mail notifications are sent, above and beyond the setting of the value of the Email notification address field. The level of configurability depends entirely on the design of the collaboration template, so reference the documentation for the specific collaboration template for information on how it approaches e-mail notification.

Pause when critical error occurs

Errors can occur that prevent a collaboration from having its business object requests processed by connectors to which it sends those requests. Some such errors are:

If these types of errors occur, the collaboration sends the request to the connector but then the flow fails because of the problem. This happens for any request sent until the problem is resolved, and can result in a large number of failed flows for the interface if the transaction volume is high and the error persists for a significant amount of time.

You can configure a collaboration object so that it stops sending requests to a connector after a request fails due to a critical error. To do so, enable the Pause when critical error occurs checkbox.

For more information on critical errors, a collaboration object's response to them, and the functionality of this feature, see the System Administration Guide.

Maximum number of concurrent events

You can configure collaboration objects to process multiple event-triggered flows concurrently, which can improve throughput for the interface. To do so, set the Maximum number of concurrent events drop-down menu to the number of events between 0 and 9999 that you want the collaboration object to process concurrently.

To truly receive the benefit of this collaboration ability you must also configure other components that participate in the interface to behave similarly. For more information, see Implementing concurrent processing of event-triggered flows.

Persist service call in transit state

It is possible for an error to occur after a collaboration has sent a business object request to any destination connectors to which it is bound and before it has received a response from them as to whether or not they successfully processed the request in their respective applications. If the connectors were unable to process the request then it needs to be processed again when the error is resolved. If the connectors were able to successfully process the request, though, and are in the process of sending InterChange Server Express a notification of that successful processing when the error occurs then InterChange Server Express would not receive the notification. The last record of the state of the request would indicate that the request still needs to be processed. As a result of this inaccurate state record the request would be processed a second time, resulting in duplicate data.

To guard against this complication when configuring non-transactional collaborations you can enable the Persist service call in transit state checkbox. This causes InterChange Server Express to persist any business object requests that are in transit to destination applications when an error occurs. The requests are not sent when the system recovers, reducing the risk of the request being processed twice in the destination applications. You can then use Flow Manager to examine the requests and can investigate the destination applications to determine whether or not the requests were processed successfully before the error occurred. You should discard any requests that were processed successfully and resubmit any that were not processed successfully.

There are also programmatic measures that can be taken to handle these types of transport-related failures. For more information, refer to the information on handling service call transport exceptions in the Collaboration Development Guide.

Recovery mode

In previous releases, if a fatal system error occurred then all flows being processed at the time of failure would be recovered when the system was restarted. The flows were all read from persistent storage and resubmitted for processing. If there were many such flows, the system memory could actually be consumed entirely by the act of retrieving the events into memory, possibly resulting in another fatal system error related to lack of sufficient memory. Furthermore, you could not effectively manage the system with the tools until InterChange Server Express had completed its recovery processing.

It is possible to defer recovery for a collaboration object by setting the Recovery mode drop-down menu to the value Deferred. If you configure a collaboration object for deferred recovery in this manner, any flows that are in progress at the time of a fatal system error are treated as failed flows and are not recovered immediately when the system is restarted. The administrator can then use Flow Manager to resubmit the flows after the system has restarted and any desired administrative actions have been taken prior to the recovery efforts.

Important:
For some interfaces it is important that event be processed in the order in which they are received. If event sequencing is not important to the integrity of an interface then you can implement deferred recovery without regard to the order in which failed or new flows are processed. If event sequencing is important, however, and you need to implement deferred recovery then you must document and follow administrative procedures to ensure that event sequencing is maintained. For instance, the administrator must make sure that the collaboration does not receive and process new flows when the system is restarted before the failed flows are resolved. They can do this managing the startup or polling of the source connector agents that would send new events to the collaboration in question.

The need for deferred recovery has been mitigated by optimized recovery measures. Rather than reading the entire business object data for in-progress transactions into memory, the server only reads enough information in memory to locate the business object in persistent storage. Although deferred recovery is still available, you may not require it because of the optimized recovery approach.

Implicit database transaction

If the collaboration template upon which the collaboration object you are configuring is based implements transactional database logic then you need to configure the collaboration object for either implicit or explicit transaction bracketing. If the collaboration was developed so that the transaction semantics are handled explicitly by the code written by the developer then you should leave the Implicit database transaction checkbox cleared. If the collaboration was not developed with explicit management of the database transactions, however, then you should enable the Implicit database transaction checkbox.

For more information about implicit and explicit transaction bracketing, see the Collaboration Development Guide.

Max event capacity

As business objects are received by InterChange Server Express they are queued in memory for processing. It is possible for interfaces that have a very high volume of transactions and a low rate of processing to have so many business objects queue up that InterChange Server Express experiences a fatal out-of-memory error.

You can mitigate the risk of out-of-memory errors by configuring a maximum event capacity for a collaboration object. To do so, set the Max event capacity field to a value that specifies the maximum number of events you want queued for a collaboration object. The system will not queue more events than the number configured for this property in memory; depending on how you configure the Blocking type property of the collaboration object, the system then responds differently to the receipt of new business objects for the collaboration.

The valid range of values for this property is from 1 to 2147483647.

For more information on the Blocking type property, see Blocking type.

For more information on flow control properties of connector definitions, and on how to use Connector Configurator to modify connector definitions, see Configuring connectors.

For more information on system properties related to flow control, see the System Administration Guide.

Blocking type

Use the Blocking type property in conjunction with the Max event capacity property to regulate the flow of business objects to a collaboration.

If you enable the Blocking Type checkbox when configuring a collaboration object and the number of events in the collaboration's in-memory queue equals the number specified for its Max event capacity property, then the connector controller responsible for sending business objects to the collaboration will cease to do so. When the number of events in the collaboration's queue is no longer equal to the number specified for its Max event capacity property, then the connector controller will resume sending events to the collaboration.

If you leave the Blocking Type checkbox cleared when configuring a collaboration object and the number of events in the collaboration's in-memory queue equals the number specified for its Max event capacity property, then new events submitted to the collaboration by the connector controller are stored persistently in the database. The events are then read from the database into memory as the events currently in the collaboration's queue are processed.

For more information on the Max event capacity property, see Max event capacity.

For more information on system properties related to flow control, see the System Administration Guide

Configuring collaboration-specific properties

Collaboration developers can design collaboration templates so that they have their own individual properties that can then be used to affect the business process logic executed at runtime. This provides a very flexible architecture so that collaboration templates can be customized to implementation-specific requirements.

To modify a collaboration object's template-specific properties, do the following:

  1. Access the Properties dialog for the collaboration object by doing one of the following:
  2. Type the desired value in the Value field for the property listed in the Property name field.
  3. Click OK.

For information about the properties specific to a collaboration template and their valid values, see the documentation for the collaboration template.

For information on adding properties to a template or modifying the usage of existing properties in a collaboration template, see the Collaboration Development Guide.

Copyright IBM Corp. 2004