| # To set up triggering Overview Preparations 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. Overview of the actual implementation The process to implement triggering consists of the following steps: Configure a trigger source, such as an exchange scheme or an application customization. For more information, refer to "To set up a trigger source," later in this chapter. Define the trigger, including the conditions and action. For more information, refer to "To define a trigger," later in this chapter. Test the trigger: start the required processes and manage the processes at runtime. For more information, refer to "Runtime tasks," later in this chapter. To set up a trigger source Trigger sources As described previously, you can generate an event in multiple ways, including the following: Application-based: Customize Infor LN to generate trigger events. Exchange-based: Use the Exchange module to collect the changed database rows or a complete set of database rows from one or more tables. Timer-based: Generate an event regularly according to a time interval or calendar. Application-based triggering 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. The following two APIs are available to attach this code: API functions to create events are available in the datrgevent library. The API function to invoke a trigger is available in the datrgapi library. For detailed information, refer to the specifications of these libraries. Note You can retrieve the library specifications from the library objects. At operating-system level, use explode6.2 to locate the library object, and subsequently use bic_info6.2 with the -eu options. 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." Exchange-based triggering (changes) 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. You can easily set up an exchange scheme in the following way: In the Exchange Schemes (daxch0501m000) session, create the main entity and define the exchange scheme attributes. In the Exchange Schemes (daxch0501m000) session, on the Specific menu, click ASCII Files to start the ASCII Files (daxch0102m000) session. While you use a table code for the ASCII file, create a new ASCII file. You can leave the Definition File field empty. If multiple tables are required, create multiple entries. On the Specific menu, click Create ASCII Files... to start the Create ASCII File Fields and Relations (daxch0203m000) session. Choose the required range of ASCII files. Make sure the following check boxes are selected: Create Based on Table Definitions Create Batch. Enter the code and description of the batch to be created in the fields that correspond to the check box. Create Export Relations Start the process, which now generates the required exchange scheme contents. Remove any unwanted fields by deleting the corresponding rows from the Field Relations (Export) session and from the ASCII File Fields (daxch0503m000) session. 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. Exchange-based triggering (full export) If a complete data set must be published regardless of what data was created, deleted, or changed, you can use a full exchange export. In this case, the setup is the same as described in "Exchange-based triggering (changes)," later in this chapter, with the following exceptions: The exchange scheme must not be based on audit. No audit setup is required. Timer-based triggering 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. To define a trigger 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. In addition, you must define an action for the trigger. The type of action that you must define depends on the action template that you select for the trigger: A Fan Out Action Use this action template if the trigger must invoke multiple actions (subsequent triggers) in parallel. An XML File Action Contains the settings in case the trigger must act by creating a file containing the event. If the user interface functionality is insufficient to meet the requirements, the user can implement a specific configuration by attaching code (a script) that implements the trigger action. For details, refer to the "Configure attached action 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. Runtime tasks Overview 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. The following subsections describe how to manage the process at runtime. Trigger management 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. Note If a trigger does not exist, this will not be reported as an error. For example, assume that an application can run in multiple companies and only from one company must something be done upon a trigger. In this case, the same application can run if the trigger is only defined in one company. Application-based triggering 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. Exchange-based triggering 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. Timer-based triggering Run the Start Triggering via Job Timer (datrg1200m000) session to regularly generate a predefined event. Refer to the Web Help for details. Target application Finally, the application that receives the event will require attention. For example, this application must clean up received files after processing. Exchange-specific limitations The following limitations apply to Exchange-based triggering. Table vs. business object level 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". Unchanged table fields 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. Two audit types exist: Always: The field is logged each time when the content of the field, or the content of any other audited field, changes. This is the default setting for all primary key fields. Changed: The field is logged only when the content of the field itself changes. This is the default setting for all fields that do not belong to the primary key. To make sure that a table field is always logged in the audit trail, you must change the field’s audit type to "Always". To do so, take the following steps: Start the Audit Profiles (ttaud3110m000) session and select the audit profile that belongs to your exchange schema (the audit profile that you generated through the Generate Audit Configuration (daxch1201m000) session). Click Table Settings by Profile on the Specific menu. The Audit Tables by Profile (ttaud3120m000) session is started. A list of tables is displayed. Select the table for which you want to change the audit settings, and click Audit Fields by Table on the Specific menu. The Audit Fields by Table (ttaud3125m000) session is started. In this session you can change the audit type per table field. You can select the desired audit type (for example,. "Always") from the list. Run the Create Runtime Audit Definitions (ttaud3200s000) session to generate new runtime audit definitions. You can start this session via the Specific menu in the Audit Profiles (ttaud3110m000) session. Restart your virtual machine (bshell). Note For details about Audit Management, refer to the Web Help and to the Infor Enterprise Server Technical Manual (U8172 US). Event types Only events that can be defined in terms of a change in persistent data can be handled. The event must be described in terms of the following: Tables Event type (action): Create Change Delete Attribute values. Examples of events that can be generated from Exchange based on audit include the following: A new Item row is added. The quantity of an item row changes. The quantity of an item row is increased. Note that you cannot configure this condition directly in the triggering user interface. However, to configure this condition, you can customize the generated triggering implementation function, as described in the "Configure attached condition script" online manual topic. An item row with item group Hardware is created, changed, or deleted. However, as described previously, if an item row is changed, but the item group is not changed, the event will not meet the condition. Examples of events that cannot be generated from Exchange include the following: An item row is changed by means of the abcde1234m000 session An item row is change by user john. Miscellaneous Exchange-specific limitations From Exchange, no (multiline) texts are included in the XML event. You can include text numbers. Events from Exchange use the ASCII file/field names as component/attribute names. This implies that the events will have a maximum of eight characters. Dates will be formatted according to the date format specified in the Exchange scheme properties in the Exchange Schemes (daxch0501m000) session, and/or ASCII file format properties in the ASCII File Fields (daxch0503m000) session. For enumerated constants, you must use the constant’s numeric value instead of the constant’s name. For example, in a trigger condition, you must use tdsls400.corg = 3 instead of tdsls400.corg = tdsls.corg.eop. No multibyte conversion is performed on multibyte string values stored in the XML event. |