Evaluation and Maintenance of Instance Linkages

Use

The instance linkage describes the assignment of a receiver instance to a particular combination of object type, object key, and event. This linkage defined by the receiver instance itself using a function module provided.

An instance linkage is always defined at event receiver runtime.

Integration

From a technical point of view, an instance linkage is an enhanced type linkage in which the reaction to the event is only produced if the event is derived from a particular object. This object is specified in the instance linkage using its object key.

In an instance linkage the unique ID of a receiver instance (receiver ID) is specified. This receiver ID is written to the event container by the event manager and forwarded to the event receiver when the receiver function module is called.

The general part of the instance linkage is the same as a type linkage that uses the entry WORKITEM or EVENTITEM as receiver type. There can be several instance linkages for one type linkage of this kind. When an event occurs for which a type linkage of this kind exists, the event manager carries out the following steps:

The event manager checks whether the object type, object key, and event in the instance linkage agree with the event parameters of the created event.

If this is the case, the ID of the receiver instance (receiver ID) is entered into the event container from the instance linkage.
If a check function module is entered in the general part, it is called. If its execution terminates with an exception, the linkage is not executed.
The receiver function module specified in the general part is called with the parameters event, receiver type, and event container.
If the instance linkage was produced, it is then deleted. The associated general part (the associated type linkage) remains since it can still be used by other instance linkages.

Note

The linkage logic does not allow an actual receiver instance to wait for an event whose triggering object is not yet known. The key of the triggering object must also always be known for an instance linkage.

This problem occurs when an object is created in a work item by an asynchronous method and this is reported to the workflow system by an event. The work item, as an actual receiver instance, is to wait for an event whose triggering object is not yet known when the instance linkage is defined for the work item.

Under these circumstances, the workflow system automatically deploys the workflow requester via which a relationship can be created between the unknown object and the work item. But the event must be created by a status change, a

Change Document or by the function module SWE_EVENT_CREATE_FOR_UPD_TASK. More information:

Creation of Events by Calling a Function Module.

Features

Instance linkage data

The instance linkage data is displayed in two parts. These are the general part and the specific part. The general part contains the information about the event and the reaction to the occurrence of the event. The part is the same as a type linkage with specific receiver types. The specific part contains information about the object that creates the event.

When an instance linkage is deleted, the general part is not deleted.

General part

The general part applies to all instance linkages that are of the same receiver type and wait for the same event. The following data is in the general part:

Object type and event ID

Note

Object type and event must be defined in the Business Object Repository.
Receiver type

WORKITEM (for terminating events) or EVENTITEM (for wait steps)
Receiver function module

SWW_WI_COMP_EVENT_RECEIVE (for temrinating events) or SWW_EI_EVENT_RECEIVE (for wait steps)

Specification of a check function module is optional. For more information about the other fields, see

Evaluating and Maintaining Type Linkages

Specific part

There is the following data for each instance linkage:

Object type and event ID
Receiver type

Note

This information is the same as that in the associated general part.
Object Key

Concatenated key of the object that creates the event.
Receiver ID

ID or instance of a receiver. For Business Workflow instance linkages, this is the work item ID of the work item waiting for the event.

Displaying instance linkages

For the purpose of troubleshooting and error analysis, it may be useful to display the instance linkages entered. The information is displayed in two parts. When the view "instance linkages" is called, all general parts of existing instance linkages are displayed. This provides an overview of the object type-event combinations for which instance linkages exist. To view the data that is specific to an instance linkage, select a line and open the node Object Data.

Defining your own instance linkages

You only have to define your own instance linkages if you use event control within your own separate developments.

The instance linkages can be maintained using the following function modules:

SWE_EVENT_REC_INST_ENTER

You can insert new instance linkages using the parameters of this function module.
SWE_EVENT_REC_INST_DELETE

You can delete an instance linkage using this function module.
SWE_EVENT_REC_INST_DELETE_ID

You can delete all instance linkages for a receiver using this function module.

If you create new instance linkages, ensure that you delete them again when they are no longer expected.

You should also delete the associated general parts of the instance linkage (type linkage entries). Ensure that there are no (more) instance linkages for this general part.

Activities

To display and maintain the instance linkages, choose Start of the navigation path Tools Next navigation step Business Workflow Development Administration Event Manager Instance Linkages End of the navigation path .