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.
There are two view representations for collaboration objects: graphical view and tree view. The following sections describe them and their benefits.
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.
Figure 38. Collaboration object graphical 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
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.
To bind a collaboration port to a connector or to the port of another collaboration object, do the following:
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.
To bind a collaboration port to a connector or to the port of another collaboration object, do the following:
When presented with the Business Object Type dialog, either select the Source Business Object or Destination Business Object radio button, depending on whether the business object you drag-and-dropped is a source or destination object in the map that transforms it.
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.
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:
Table 13. 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 |
This read-only text field displays the name of the collaboration template on which the collaboration object is based.
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.
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.
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 14 describes the different levels and the types of information reported at each:
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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:
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.