Designer defined Application Events and its delivery

Application Events are triggered when something happens in Maymyo. This something is designed by you. It should be a business event that is of importance to your users, for example whenever a payment more than X amount is made.

An Event will have an Access Key and up to 5 Attributes values, defined by the Designer. The Key is mandatory but you can always use the ALL-ROWS wildcard to make it redundant. The Access Key allows your Registrants to register with different Attribute Values, eg if your Access Key is by Business Unit, then a Registrant can register for an Event with different Attribute values for each Business Unit.

The end result of an Event is a Message sent to interested Registrants. This is what is meant by Delivery. It works on a Publisher-Subscriber basis, where the Publisher is Maymyo (through the Event that the Designer raised) and the Subscribers are Registrants who register their interest in an Event for a set of Key and Attribute values.

The Event Access Key and Attribute values (ie the actual values associated with an actual event incident) is compared with the Registrants’ Access Key and Attribute values. If they do not match, then no Message will be sent to the Registrant. This allows Registrants to be informed only when certain Attribute are above a specific value, usually monetary in nature.

The Message can also be linked to an Action URL that the Registrant can click to see details of the event (in her Dashboard). Our Business Rule events have Action URLs that allows the Recipient to see the details of the transaction Selection.

How the Message is delivered to the Registrant depends on the Message Type defined for the Application Event. It can be queued to the Dashboard, sent as an Alert and emailed or sms’ed to mobile phones. See Messaging and Alerts.

A Maymyo Event example

In Maymyo, all Business Rules will trigger an Application Event whenever an Authorisation is requested (by a User who does not have sufficient permission).

In our Billing module, we have the Billing Entry transaction. A User may enter Debit or Credit Bills against a Party. For Credit Bills, we have a Business Rule CREDIT-BILL-RULE which controls who can enter Credit Bills and up to what amount. A Business Rule can trigger an Application Event using the same Access Key and Attribute values whenever an Authorisation request is raised. (This means that no event is triggered if a user has sufficient permission to perform the transaction).

The Access Key for this Business Rule is the Business Unit Code of the Party being billed. The 1st Attribute is the Billing Type Code used (eg Trade Discount, Cash Discount etc) and the 2nd Attribute is the Billing Amount (absolute amount in Functional Currency). The 1st Attribute uses the IN operator (set membership) while the 2nd uses “<”, ie less than.

In tandem with this, we also have a special User called Trivial User. Whatever Access and Attribute values granted to this special User is also granted to everybody. This means that Maymyo should allow everyone to enter Credit Bills that the Trivial User can enter and no Application Events will be triggered. This allows you to define a lower threshold to Business Rules and Events below which every one is given permission automatically.

The Access Key allows you to control different Attribute values for different Business Units. For example, for HeadQuarters, its Users can enter Credit Bill Amounts up to 10k without restriction (by using the Trivial User, see below). Only Finance Managers can enter up to 100k. Then in the other Branches, you want to set these amounts to 5k and 50k respectively. You should define the following Access List :-

  1. Define Access List against the Trivial User in “Maintain User Profiles” as follows :-

    • Access Key HQ with Attribute 1 ALL-ROWS and Attribute 2 10k
    • Access Key ALL-ROWS with Attribute 1 ALL-ROWS and Attribute 2 5k This applies to all other Branches except HQ.
  2. Define Access List for Application Role “Finance Manager” in “Maintain Application Roles” as follows :-

    • Access Key HQ with Attribute 1 ALL-ROWS and Attribute 2 100k
    • Access Key ALL-ROWS with Attribute 1 ALL-ROWS and Attribute 2 50k This applies to all other Branches except HQ.
  3. Define Access list for General Manager, Finance user in “Maintain User Profiles” :-

    • Access Key ALL-ROWS with Attribute 1 ALL-ROWS and Attribute 2 ALL-ROWS

No 1 above will apply to all Users except those with the “Finance Manager” Role while No 2 will apply to the latter only. You should always define a super-user (ie General Manager) for every Business Rule otherwise transactions above 50k (or 100k for HQ) cannot be performed at all.

If you are the Chief Operating Officer, you may want to know if there are any Credit Bills above 100k being approved. You can register your interest in the CREDIT-BILL-EVENT with the following :-

  • Access Key ALL-ROWS with Attribute 1 ALL-ROWS and Attribute 2 of 100k

Whenever a CREDIT-BILL-EVENT is triggered, it will go through all the interested Registrants and send a Message to those whose Access and Attribute conditions matches. There could be other Registrants with different Attribute values who may or may not be sent Messages.

Note that when registering for an Event, if an Attribute is a numeric value, we will always toggle the operator used for the underlying Business Rule, ie when checking permission to the Business Rule we will use the “<” operator but when registering interest to an Event we will toggle it to “>=”. This is controlled by the “Toggle Event” flags in “Maintain Application Events”.

The mode of delivery of the Messages depends on the Event’s Message Type. When not defined, we will fall back on the Application default, which is to send a queued message to the Dashboard.

How to register your interest in an Event

../_images/event_reg.png

Maintain Application Events

You must first have access to the “Maintain Application Events” program in the “Maintain Infrastructure Master Files” menu. The Registrant must also have access to the specific Application Event, either directly through her User Profile or indirectly through her Application Role(s). You can check which fields are the Access and Attribute values in the “Maintain Application Events” Access List tab.

The “Event Registers” tab allows you to add users who are interested to be informed of an Event. Select a user in the “Registrant” field, then enter the Access Key and the Attribute values and scroll to the right-most part of the page to enter the “Starting On” date and time when the registration takes effect. The “Ending On” date and time allows registrations for a short period of time, after which the Registrant will no longer be informed.

As mentioned earlier, the operator for numeric Attributes are toggled for registrations. If you were to click on the “Event” tab, you will see that we have checked the “Toggle Event 2” checkbox. So even though the “2nd Value Name” in the “Access List” tab says “< Billing Amount”, the “<” operator is used only for checking access to the Application Event. When the Event is triggered, we will decide to send a Message to the Registrant using the “Toggle Event X” checkboxes.

How to program a new Event

To create a new Application Event, you must first decide how it should be triggered and which fields to use as Access Key and Attribute values. Your Event will usually be associated with a Business Transaction, an Application wide event (eg an End of Day task that looks for customers whose overdue amounts has exceeded X days) or possibly an application error event, eg when an automatically uploaded file cannot be found in its usual directory by a certain time. You can see that it can be anything at all.

So, first step is to create a new Application Event in “Maintain Application Events”. You should also maintain the Access List to your Application Event. This will control who can register for your Event.

Next, decide on how the Message will be delivered to Registrants. You can use our default Message Types or if your Message has an “Action URL” to allow the Registrant to view details of the event, then create a new Message Type. What parameters to be passed to the Action URL is decided by you, when you call our “trigger_event” function. The parameters will be passed as GET parameters (ie appended to the Action URL). The Action URL is usually relative to where your serving Maymyo, ie no need the hostname and port part. See our BILL_ENTRY Message Type.

Note

Action URL should be a view program coded by you. Please read django’s documentation on views and URLs to learn how to create new view programs.

Finally, in your code, call our trigger_event function:

from infra.objects.app_event import trigger_event
from infra.objects.app_resource import prepare_access_params
....
your program code....
....
params = prepare_access_params([access_key_value, attribute_1_value, attribute_2_value,...])
action_params = [your_event_id]
rsr = trigger_event(app_event, user, event_message, params, action_params)
if rsr.return_status == 'E':
    # raise your own error
....
rest of your program
....

The parameters that you pass in to trigger_event are:-

  1. app_event - ApplicationEvent instance that you created. Usually you would perform a get using its unique resource_code.
  2. user - the User instance who triggered the event, eg if a business transaction, then the user who started it. If Application wide event in a Scheduled Job, then the Job Owner or Rostered User.
  3. event_message - a text message describing the event, eg _(“Customer %(customer_name)s has overdue Bills of %(overdue_amount)d more than %(overdue_days)d days”). Notice the “_” which is our alias for ugettext to support internationalisation. You should do the same if your application is internationalised.
  4. params - this is a dictionary of the Access Key and Attribute actual values (ie actual field values of the event). You call prepare_access_params with a list of the actual field values to prepare the dict. The Access Key and Attributes must match what you defined for your Application Event.
  5. action_params - if your Event’s Message Type uses an “Action URL” to allow the Registrant to view details of the Event, then you should supply the parameter values as a list. This parameter is optional.

rsr is the ReturnStatusRecord returned by trigger_event. It is a class with return_status, return_messages list and return_values list. It is our standard way of returning from a non-trivial function call.

The triggering of an event will immediately broadcast the event to all Registrants. If the values of the Access Key and Attributes matches for a Registrant then she will be sent a Message.

Do not forget to add Registrants to your Event. See previous section.