To set up triggering

Before you set up triggering, you must specify the requirements/design. Consider what must happen and when. For example, if a new sales order is created in LN, application X must be notified. Or, if a specific status field receives the value Active, application Y must be notified.

In addition, you must make clear what information must be communicated. In other words, what must be the content of the event message? For example, only an order number or other attributes from an order such as an order date or Sold-to Business Partner (customer) ID.

Choose how to implement the triggering, for example, by means of Exchange or by means of an application customization. In addition, you must define the action to be carried out.

While you specify these settings, you must consider performance-related questions. For example, how long must the process take before the target application is notified of an event? How frequently will events occur?

Subsequently, you can perform the actual implementation.

In the application, add a piece of code that generates an event message and invokes a trigger. You can attach this code, for example, to a library or to a program script.

For detailed information, refer to the specifications of these libraries.

For example:

$ explode6.2 odatrgevent

/mybse/application/myvrc/odatrg/otrgevent

$ bic_info6.2 -eu /mybse/application/myvrc/odatrg/otrgevent

This command shows the documentation of the event handling functions.

This method provides the prototypes, including the function name and type and parameters and their types, of the functions in the library, a description of the functions and their input and output, and the preconditions and post-conditions.

The following is an example that shows how you can create an event from an application customization and to execute a trigger:

#pragma used dll odatrgevent    |event handling functions
#pragma used dll odatrgapi  |triggering api

#define CHECK_RETURN(retval)    if retval <> 0 then
^                                 ... |implementation depending|on context
^                               endif

long    my.event                |XML event used for triggering
long    retl                    |return value to be checked
string  exception.message(512) mb   |message if an error occurs
string  exception.details(512) mb   |details on exception message

if curr.inventory.on.hand < threshold.value and prev.inventory.on.hand >= threshold.value
then
    |low inventory, invoke trigger
    retl = datrgevent.simpleevent.create("Inventory", "LowInventory", my.event)
    CHECK_RETURN(retl)
    retl = datrgevent.simpleevent.set.value(my.event, "item", curr.item)
    CHECK_RETURN(retl)
    retl = datrgevent.simpleevent.set.value(my.event, "warehouse", curr.warehouse)
    CHECK_RETURN(retl)
    retl = datrgevent.simpleevent.set.value(my.event, "inventoryOnHand", 
                        curr.inventory.on.hand)
    CHECK_RETURN(retl)
    retl = datrgevent.simpleevent.set.old.value(my.event, "inventoryOnHand", 
                        prev.inventory.on.hand)
    CHECK_RETURN(retl)
    retl = datrgapi.trigger.do("mytrigger", my.event, exception.message, exception.details)
    CHECK_RETURN(retl)
endif

The simple event functions are offered to create events that consist of only one component. Specifying a class name (entity), event type (action), and the attribute name and value for each attribute is sufficient. In addition, if desired, you can also add the previous attribute value. Other event functions are available to create more complex events, such as multilevel events that consist of header and line components. For more information, refer to Chapter 3, "Event handling."

To use Exchange-based triggering, you must define an exchange scheme, including ASCII file and fields, batch, table relations (export), and field relations (export). In case of triggering, the ASCII file and fields might not be relevant in the sense that no physical ASCII files are created. However, these files and fields are relevant because they define the contents of the event. The ASCII file represents the object (or component) and the fields represent the attributes included in the event.

The mapping of the event, and the event’s required attributes, to the table and columns must be made clear. If a one-to-one mapping exists between columns and required attributes for the trigger, the exchange scheme can largely be generated as described in the following procedure. If required, you can add constant or calculated values to the output. Note that for calculated/transformed values, scripting is required.

After the exchange setup is complete, you can run the Create Export Programs (daxch0228m000) session to create a runtime program that implements the settings as defined in exchange scheme.

For more information on Exchange, refer to the Web Help.

The exchange scheme must be based on audit. Therefore you must generate an audit configuration for the tables in the exchange scheme. Use the Generate Audit Configuration (daxch1201m000) session for this. For more information on Audit Management, refer to the Web Help.

After you set up the exchange scheme and the triggers, you must define the relation between the two. In other words, one or more triggers must be linked to the exchange scheme. To link these triggers, you must use the Export Triggers (daxch0135m000). For details on this session, refer to the Web Help.

If a complete data set must be published regardless of what data was created, deleted, or changed, you can use a full exchange export.

No specific setup is required for timer-based triggering. You must define the trigger as described in "To define a trigger," later in this chapter. Subsequently, you can start the process as described in "Runtime tasks," later in this chapter.

In the Triggering module, you must define the trigger, including the trigger’s conditions and actions, as required. You can create triggers in the Triggers (datrg1100m000) session. This session contains a configuration interface that enables you to generate the condition and action logic. Note that you can use the same trigger for multiple types of events, and even from multiple sources.

If applicable, you can define conditions for the trigger. A condition limits the number of events for which a trigger action is performed. You can define conditions by means of the Configure Trigger Conditions (datrg1110m000) session. In this session, you can create or update conditions on class, event type, or attribute value.

If the functionality available in this session is insufficient for the condition you want to create, you can attach a script that contains complex conditions. For details, refer to the "Configure attached condition script" online manual topic.

If you define a trigger, the runtime program is automatically generated. The program is also regenerated automatically when you change the trigger, or the trigger’s conditions or action. In addition, you can click Generate Program in the Triggers (datrg1100m000) session to regenerate the runtime program.

At runtime, the following happens: The triggering module offers an interface to initiate a trigger. Input in that case is an XML structure describing the event. The user can call this interface from the Exchange module, from an application, or from the Start Triggering via Job Timer (datrg1200m000) session. If you do not invoke this interface from an application or exchange process, the process checks whether an action is defined for the specified trigger and runs the corresponding trigger function.

For the trigger itself: no further action is required. The trigger is passive. Therefore, the trigger simply waits until one of the trigger sources invokes the trigger. If the trigger does not act as desired, you can debug the trigger. For more information, refer to the Triggers (datrg1100m000) session online Help.

For application-based triggering, no action is required at runtime either. The trigger invocation is included in the application logic, therefore, the trigger invocation will be performed automatically when the corresponding application state is reached.

To use exchange-based triggering, the export process must be running regularly. You can add the Export Data (on a Regular Basis) (daxch0234m000) session to a job that runs according to a calendar or a predefined time interval.

This job ensures that the exchange scheme regularly picks up the changes from the audit trail or the data from the database tables and invokes the corresponding triggers. For details, refer to the Exchange online Help.

Bear in mind that in practice, the time interval must not be shorter than the time the export process requires to be completed successfully. If a small interval, such as one minute or a few minutes, is required, check beforehand whether the selected interval is feasible. Note that the duration of the export process depends heavily on the amount of changes or data to be processed and the trigger action defined.

You must run all normal management activities required to run an exchange scheme. For example, occasionally, you might want to clean up data produced by the export process. Exchange offers logging facilities to check whether the process is running successfully.

If you use the audit mechanism to detect change events, the audit trail must be cleaned up regularly, if the data is no longer required.

Finally, note that the audit setup impacts performance. If the system sizing is correct and the audit is configured properly, the impact will be minimal, because the overhead is usually not greater than a few percent. Locating the audit data on a disk that is not a potential bottleneck is strongly advised. In addition, you can deploy disk striping to improve performance.

Run the Start Triggering via Job Timer (datrg1200m000) session to regularly generate a predefined event. Refer to the Web Help for details.

Finally, the application that receives the event will require attention. For example, this application must clean up received files after processing.

The following limitations apply to Exchange-based triggering.

If you use events from Exchange, the triggers will be defined at table level rather than at Business Object level. Information from other tables can be included (scripting options are available), however, this requires programming. Note, however, that if the primary key of the object is the only attribute that is required, the same event can be generated from multiple tables. For example, a change on an order header and a change on an order line can both result in the same event, if required.

An example of an event that cannot be defined without programming a so-called condition script in the exchange scheme is as follows: "Initiate an approval process if the quantity of an order line is changed and the status of the order header is Open".

If a row is created in or deleted from a table, the event generated by the Exchange export includes all ASCII fields as defined. However, if a row is changed, by default only the primary key fields and the changed fields will be included.

For example, if you handle events on or order line consisting of an order number, line number, item, quantity and price, if the price is changed, the item and quantity will not be available in the event. You must take this into account when you define the trigger and when you process the event in the application that finally receives trigger. A trigger condition on quantity will only be met if the quantity is available; in other words, if the row is created or deleted, or if the quantity value is changed.

To change this default behavior, you must change the audit type of the table fields in your exchange scheme’s audit profile.