Function documentationEvaluation and Maintenance of Instance Linkages Locate this document in the navigation structure

 

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.

Note Note

When events are used in SAP Business Workflow (as triggering and terminating events, for wait steps), the workflow system defines the linkages required.

The workflow system defines an instance linkage when work items wait for an event. This can apply to the following work item types:

  • Dialog work items (type W) and background work items (type B) (when an asynchronous object method is executed, the system must always wait for an event)

  • Wait step work item (type E)

  • Work queue work item (type A)

End of the note.

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.

This graphic is explained in the accompanying text.

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:

  1. 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.

  2. 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.

  3. The receiver function module specified in the general part is called with the parameters event, receiver type, and event container.

  4. 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 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 the function module SWE_EVENT_CREATE_FOR_UPD_TASK for this. More information:

Creation of Events by Calling a Function Module.

End of the note.

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 Note

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

    End of the note.
  • Receiver type

    Receiver type WORKITEM (for terminating events) or EVENTITEM (for wait steps)

  • Receiver function module

    Receiver type SWW_WI_COMP_EVENT_RECEIVE (for terminating 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 Note

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

    End of the note.
  • 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.

Caution Caution

The instance linkages required for the wait steps and the terminating events of an activity in the workflow definition are entered automatically by the workflow system. Do not change these entries.

End of the caution.
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   Tools   Business Workflow   Development   Administration   Event Manager   Instance Linkages  .