TDEVT:TDOMS Event System
TD/OMS Event System
The TD/OMS event system can be used to trigger external programs based on an event in TD/OMS. For example, after a task is created, the user wants to run a program.
Events
In TD/OMS, Events are the result of User actions. For example, when you create a Task, TD/OMS will automatically create an Event and send it to the TD/OMS Event Manager. The Event Manager will deliver it to interested Event Subscribers. You can also register and send your own events.
Below we explain the basic concepts and then follow up with a "how-to".
Topics
In TD/OMS enter GO OMSEXCP or STRTOPM to find the Topic Maintenance function.
As with other event systems, we are going to use the topic system. The topic is a slash ('/') separated list of subjects to discriminate different topics.
For example:
task/add
This topic is in the domain task and the action is "add".
comment/task/reply
This topic is in the domain task comments and the action is "reply".
Every possible topic will be documented on this page.
Keys
Every topic is associated with a corresponding key in JSON format, e.g.:
{"APPC":"DEMO", "TASK":"T0123"}
Every key will be documented with the topic.
Subscribers
To create Subscribers you can use the STRSUBM command or find it on the OMSEvent menu.
Subscribers are programs that are called when an event with a specific topic occurs.
Subscription to a topic can be done in a qualified fashion that will only call the Subscriber on a specific topic, e.g:
task/add -> Event Handler
or in a generic fashion that will call the Subscriber for any topic in a specific realm, e.g.:
task/* -> Subscriber is called on task events comment/task/* -> Subscriber is called on task comment events * -> Subscriber is called on all events
Subscriber Commands
There are two ways to execute commands. The first is to enter any command like CALL, QSHELL, or any other valid command.
There is also a special command called RUNEVTOMS. This command can be used to call an event program. An event program has exactly two parameters.
Event Manager
The Event Manager is a service running in the TD/OMS subsystem that is in charge of calling the Subscribers. It checks the event file for unprocessed entries and calls all registered subscribers sequentially.
You can start the event manager like this:
- STROMSSRV *EVENTMANAGER
You can check if the Event Manager is running:
- STSOMSSRV *EVENTMANAGER
To stop the event manager:
- ENDOMSSRV *EVENTMANAGER
Event Cycle
- The Event Manager Checks for new Events every 30 seconds.
- The event is created in OMEVT with all attributes
- For every Subscriber listening to the event one event record is created in OMSBE with status *OPEN
- While there are *OPEN events
- The event dispatcher reads the subscribers for the event
- For each Subscriber
- The action is performed (e.g. call or web call)
- The OMSBE is updated to log this call
Guaranteed Delivery
Delivery is guaranteed. This means that TD/OMS will always call the subscriber. It is not possible to miss an event. However, when events are delivered asynchronously it means that there is no immediate call of the event when it happens. It can be called any time after the event has happened which could possibly be minutes after the event has happened. If the Event Manager is not active, it could even be the next day.
Therefore, Subscribers must be aware that the action could have been undone after the event was sent and before the Subscriber was called. E.g.
solution/connect -> Object connected to a task
can be immediately followed by
solution/disconnect -> Object disconnected from a task
The Subscriber on the former topic must be aware that the situation can be undone before it is called.
Synchronous or Asynchronous
You have the option to let your Subscribers fire Sync or Async by the Event Manager. When the Subscriber is called Synchronised, you have to be careful not to get caught in a recursion loop. For example, if you subscribe to a 'task/change' event and as a result, you change the task with the TASK API (OMQCHGFI) then your Subscriber is called again. If this is your intention then you must make sure that your Subscriber is called from a named activation group.
In the case of an Async call, you don't have recursion problems, but you could still get caught in a never-ending loop. If this happens, stop the Event Manager and remove your Subscriber Events using the STRSUBM function and use option 12 and option 12.
Event Provider
Event providers will create events in the topic form. Every TD/OMS API will create events. We also have an API available to hook into the event system by creating your own topics.
The CLI API to send an event is OMQCHGEV. You can also bind the OMEVENT service program.
Before you can send an event you have to create the topic and attach a Subscriber to that topic.
Data Model
The following tables make up the event system:
- OMTOP Topics
- This table contains all possible Topics with the description of the Topic. A Topic has the following form 'subject{/subject}/action'. E.g.
task/addorrequest/task/connect. An Event is associated with a Topic. Before an Event can be sent, its Topic must be defined in this table. The payload or Key that will be associated with the Event is described in this table. - OMEVT Events
- This table contains all the Events that happened. Events are only stored when there are subscribers listening to the event, or when events are forced (see API)
- OMSUB Subscribers
- These are the actions associated with a qualified or generic Topic. An action can be a program call, or a web call.
- OMSBE Subscriber Events
- This table will register the result of the call to the Subscriber for the specific event.
Event API
To hook into the Event System, several APIs are available.
OMQCHGEV Event API
The Event API can be used to send an Event. Events are only stored when a Subscriber is interested in its Topic. However, if you want to always store the Event, you can pass the FORCE(*YES) flag.
See the online help of the command for more information or see the wiki help.
OMQRTVEK Event Key API
The Retrieve Event Key API can be used to extract information from the Event Key. The Event Key is passed to the Event Exit Program.
See the online help of the command for more information or see the wiki help.
Event Exit Program
As an Event Exit Program you can use the RUNEVTOMS command in a Subscriber. The program you specify in the command will be passed two parameters. The Topic and the Event Key. You can use the OMQRTVEK API to extract information from the key.
An example of an Event Program is stored in member RUNEVTOMSC in the QUSRSRC library.
OMQRTVEK Event Key API
The Retrieve Event Key API can be used to extract information from the Event Key. The Event Key is passed to the Event Exit Program.
See the command's online help (F1) for more information or see the wiki help.
How To
This part of the manual explains how to create a subscriber that listens to an Event.
The use case is that we want to receive a message in the QSYSOPR queue whenever someone changes a Task (Fix).
Selecting the Topic
First, we want to enter Topic Maintenance to find the topic we want to listen to. Topic Maintenance has a filter that can help you find the correct topic.
To enter topic maintenance, use the STRTOPM command, or find the Topic Maintenance option on the Exception Management menu: STROMS, Option 3, Option 21.
The topic we want to use is 'task/change'. Use option 5 in front of that topic to figure out what data is supplied in the Event Key:
The key contains the application code in field APPC and the task in field TASK.
Please note that you can also use the Topic Maintenance system to create your own topics.
Creating the Subscriber
To enter subscriber maintenance, use the STRSUBM command, or find the Event Subscriber Maintenance option on the Exception Management menu: STROMS, Option 3, Option 21.
Press F6 to add a new Subscriber.
OMS034 Subscribers Maintenance 25-09-22
OMS03401 Maintain Subscriber 14:01:31
------------------------------------------------------------------------------
ADD
Subscriber id ..........: *NEXT
Description ............: Send a message when a task changes
System indicator .......: 0 0=User, 1=System
Disable indicator ......: 0 0=No, 1=Yes
Command string .........:
SNDMSG MSG('Task &TASK was changed in application &APPC.') TOUSR(*SYSOPR)
-----------------------------------------------------------------------------
F3=Exit F4=Prompt F5=Refresh F12=Cancel
Please note that we can use the &TASK and &APPC variables because TASK and APPC are part of the Event Key for the task/change topic we will use.
Since the Task is in the Application and Task context, also all fields from the Application and Task table are available. Press the F1 key on the Command String field to determine which other parameters can be used. See a list of context-sensitive variables in the back of this manual.
Attaching the Topic
Press Enter and F5 to refresh the screen and use option 12 to work with the subscriber topics.
Press F6 to add the 'task/change' topic
OMS036 Subscriber Topics Maintenance 25-09-22
OMS03601 Maintain Subscriber Topic 14:11:58
-----------------------------------------------------------------------------
ADD
Subscriber .............: Send a message when a task changes (2)
Subscriber topic id ....: 2
Topic ..................: task/change
Synchronized ...........: 0 0=No, 1=Yes
Description ............: Send when a task was changed
-----------------------------------------------------------------------------
F3=Exit F5=Refresh F12=Cancel
Press Enter, and you are done.
Synchronous and Asynchronous Event Handling
The Synchronized field in the screen above determines if the Subscriber is fired while the event happens or at a later stage.
It is generally not advised to use Synchronized events unless you really have a good reason. Using synchronized events may slow down the system because they are executed when it happens.
Asynchronous events will be processed in the background by our Event Manager.
Attaching the Event filter
Press Enter and F5 to refresh the screen and use option 8 to work with the filters.
Press F6 to add the event filter.
OMS058 Event Filters Maintenance 17-08-23
OMS05804 Maintain Event Filter 07:27:38
------------------------------------------------------------------------------
ADD
Subscriber .............: Send a message when a task changes (2)
Topic ..................: task/change (2)
Variable ...............: &APPC
Value ..................: KE.*
Description
The subscriber event will be processed when the application code starts with KE
-------------------------------------------------------------------------------
F3=Exit F5=Refresh F12=Cancel
Press Enter, and you are done.
The filter can be any variable from the payload and the test is a regular expression. For example, the task/add topic can have a filter like this:
Variable Value &APPC KE.*
This means that the event subscriber will only fire if the application code of the task starts with KE.
Note: When there is more than one filter, all filters must be matched to process the event subscriber.
Starting the Event Manager
To start the event manager, execute the following command:
STROMSSRV *EVENTMANAGER
It is advised to start the Event Manager every time the TD/OMS subsystem is started. You can add this to the job scheduler or change to the OMQOMSTRUP program (source is in QUSRSRC. Copy it to a different location before you change it).
Triggering the Event
Now open a Task (Fix). Change it (e.g., change the description) and see that the message will appear in the QSYSOPR queue within 30 seconds (30 seconds is the Event Manager polling interval).
Context Variables
Based on the context of the topic, table substitution variables can be used.
Command string substitution parameters
The command string that is entered in the user option can contain substitution variables. Currently the following variables can be used.
Fields from Application Database
| &APAPPL | Application code |
| &APAPNM | Application name |
| &APERPR | Request manager |
| &APDMPL | Dump library |
| &APGL4N | 4-GL Name |
| &APSRCI | Check source indicator |
| &APCRLS | Release |
| &APCERR | Request number |
| &APIERR | Increment |
| &APCFIX | Fix number |
| &APIFIX | Increment |
| &APCNVS | Data conversion scope |
| &APCATT | Attribute conversion type |
| &APCATS | Attribute conv. scope |
| &APCAUT | Authorisation conv. type |
| &APCAUS | Authorisation conv. scope |
| &APCJOT | Journal conversion type |
| &APCJOS | Journal conversion scope |
| &APMODC | Module code |
| &APDRVC | Derivation code |
| &APMTPC | Message 2 programmer code |
| &APFBLC | Fall back library |
| &APFJBD | Fast JOBD |
| &APFJBL | Fast JOBD library |
| &APSJBD | Slow JOBD |
| &APSJBL | Slow JOBD library |
| &APPATH | Path code |
Fields from Component database (objects)
| &OBAPPL | Application code |
| &OBENVC | Environment code |
| &OBOBJC | Object code |
| &OBOBJL | Object library |
| &OBOBJT | Object type |
| &OBOBJA | Object attribute |
| &OBOBJD | Object description |
| &OBSRCF | Source file |
| &OBSRCL | Source library |
| &OBSRCM | Source member |
| &OBSRCS | Sources belong to object |
| &OBSRCX | Source Change date |
| &OBOBJX | Object Source change date |
| &OBOMOD | Object modified |
| &OBOCRT | User which created object |
| &OBFIXN | Fix number |
| &OBUSDF | User defined |
| &OBEXCI | May not exist indicator |
| &OBOCLS | Object class |
| &OBVRSN | Version number |
| &OBMODN | Modification number |
| &OBCHGX | Object Change date |
| &OBIOBC | IFS object code |
| &OBIDRC | IFS Directory code |
| &OBGLMC | 4-GL Model code |
| &OBGLLC | 4-GL Library code |
| &OBGLK2 | 4-GL Additional key 2 |
| &OBGLK3 | 4-GL Additional key 3 |
| &OBGLK4 | 4-GL Additional key 4 |
| &OBGLK5 | 4-GL Additional key 5 |
| &OBGL4N | 4-GL Name |
| &OBGLMD | 4-GL Model description |
| &OBROTC | Route Code |
| &OBPTHX | Path Extension code |
| &OBELBC | Extended Library Code |
| &OBIOBC | IFS Object Name |
| &OBIDRC | IFS Directory name ending with '/' |
Fields from Object Detail database (members & messages)
| &DTMBRC | Member code |
| &DTMBRA | Member attribute (MBSEU) |
| &DTMBRD | Member text |
| &DTFIXN | Fix number |
| &DTOMOD | Object modified |
| &DTUSDF | User defined |
| &DTEXCI | May not exist indicator |
| &DTAPPL | Application code |
| &DTVRSN | Version number |
| &DTMODN | Modification number |
Fields from Solution database
| &SOAPPL | Application code |
| &SOFIXN | Fix number |
| &SOOBJC | Object code |
| &SOOBJT | Object type |
| &SOOBJA | Object attribute |
| &SOMBRC | Member code |
| &SOOBJL | Object library |
| &SOOCLS | Object class |
| &SOENVC | Environment code |
| &SOSRCP | Source Processing |
| &SOVRSB | Version number |
| &SOMODB | Modification number |
| &SOVRSN | Version number |
| &SOMODN | Modification number |
| &SOOVRC | Override code |
| &SOSOLT | Solution type |
| &SOSTAT | Status |
| &SOROTC | Route Code |
| &SOELBC | Extended Library Code |
| &SOPTHX | Path Extension |
Fields from Task database
| &FIAPPL | Application code |
| &FIFIXN | Fix number |
| &FIFIXT | Fix type |
| &FIRLSN | Release |
| &FIDEXN | Development exit count |
| &FIREAC | Reason code |
| &FIFIXS | Fix status |
| &FIPRIN | Priority numeric |
| &FIPGMR | Programmer |
| &FIESDT | Expected start date |
| &FIRSDT | Realized start date |
| &FIECDT | Expected completion date |
| &FIRCDT | Realized completion date |
| &FIEDDT | Expected dev. end date |
| &FIRDDT | Realized dev. end date |
| &FIEPHN | Expected number of hours |
| &FIERHN | Realized number of hours |
| &FISHFD | Short fix description |
| &FINACN | Number of ratification grps |
| &FIACCN | Ratification count |
| &FIREJI | Rejected indicator |
| &FIFREE | Free user space |
| &FIPATH | Path code |
Fields from Request database
| &REAPPL | Application code |
| &REREQN | Request number |
| &REERRT | Request type |
| &REENVC | Environment code |
| &REREAC | Reason code |
| &REPRIN | Priority numeric |
| &REUSID | User i.d., or user class |
| &READDR | User address, distribution |
| &REUSRI | Distributed user i.d. |
| &RETELN | Telephone number |
| &REWCDT | Requested completion date |
| &RERCDT | Realized completion date |
| &REINDT | Income date |
| &REINTM | Income time |
| &RESHED | Short request description |
| &RENACN | Number of ratification grps |
| &REACCN | Ratification count |
| &REREJI | Rejected indicator |
| &REFREE | Free user space |