Event Based API Calls

This document describes the concept of using events as a trigger point to call an M3 API. The trigger to the M3 APIs is performed through a user defined API call including the selected event information as a list of parameters sent with the API call. The function can call any inbound M3 API transaction.

Follow these steps

  1. In 'Event Subscription. Open' (CMS045) add a subscription to the M3 table to be used for the API call. The name of the M3 table is used as the event name and M3 as a publisher.
  2. The subscription must be activated for event based API calls and must also be set as active.

    Define the API call

  3. The definition of the API call is performed in 'Event Based API Calls. Open' (CMS041)

    When API should be called

    Define when the API should be called using filters where logical expressions like "Value changed", "Equal to" etc for specific fields can be used.

    Any M3 inbound transaction can be used except replies from the API. Only error messages from the API are stored in the related log.

    From both a performance and volume perspective, it is important that filters are defined correctly and thoroughly tested in an environment with fewer transactions than a production environment. Since a normal M3 environment generates several hundred events per second, poorly defined filters can quickly generate massive amounts of alert messages. Warning messages are created if filters are used for LMTS (Time stamp) or CHNO (Change number), or if there are no filters with condition 7='Changed value'.

    Post definition steps

  4. Once the alert has been defined, the corresponding autojob must be restarted before the updated subscriptions become active in the Event Hub and the new definitions updated to cache.

    Restart the autojob in 'Subsystem. Open' (MNS050) and select related option 'Job in subsystem' (Option 11) for the autojob subsystem (normally named ASJ).

  5. Find the autojob CMS913 (Event subscription - event log) in the list.
  6. End it and once stopped, start it again.

Troubleshooting

An error log is connected to the API call. Erroneous calls or error messages back from the API are logged with the primary key of the event as well as the function that triggered the original event. Based on this information the action resulting in the event can be reprocessed or the API re-triggered when the problem has been corrected.

An alternate way to troubleshoot is to turn on the concept log for the autojob in the server view, or admin pages in a cloud environment. Once activated, generate a new event and then view the concept log written to the autojob log. Every validation performed within the autojob is written to the log as a readable text.

The actual call to the API is performed from a standard batch program, CMS326 (Manage fix programs/job driver), which then maintains the communication with the API and updates the log file. From an autojob perspective, the call to the API is just a "fire and forget" type and does not wait for any reply from the receiver.

Related topics