Messaging and Alerts

Messaging is intended for developer use. Messaging is asynchronous in nature, ie the message needs to be delivered to the recipient out of band. Synchronous messaging is very familiar to the user. We do it all the time, eg every time we raise a validation error when an invalid value is entered in an input field of a form.

An Alert is the same as a Message, just that its Message Type has a Delivery Method of ‘A’ and its delivery is segregated from normal messages.

Message and Alert delivery

Messages to the users usually comes from the Task Queue, Output Queue, Workflow engine, Application Events or Reminder Events. When a user submits a task, eg a report, to the Task Queue she will immediately regain control of her session and can continue with another transaction. So there is no way we can send an in band message to her. Later when the Task Queue has completed her report, it will send a message to her Message Queue, which can be retrieved from her Dashboard.

Messaging in the Dashboard

In the Dashboard above, a user will know whether she has Alerts or Messages pending her attention by looking at the counts at the bottom left of the page. If the count is above 0, then she can double-click the count field and an Alert (or Message) tab will be launched. The Dashboard will refresh the counts at regular intervals. Double-clicking when the count is 0 has no effect.

Alternatively, she can also double-click on the Message or Alert icons in the vertical Toolbar next to “Your Menus”. She can allow the mouse to hover on each icon to display the tooltip on what each is for. The messaging icon uses the envelope symbol.

Check my Messages or Alerts

The top part of this page allows the user to search for specific messages or alerts. This is useful when there are a lot of messages accumulated for her attention.

Dismissing Messages and Alerts

Messages and Alerts will always be pending action from the recipient and will only stop displaying after one of the actions below has been taken. There are 3 types of actions :-

1. View only - user should click on the “Act” checkbox(es) and the click the “Post” button. However, you can specify a “Expiry Days” for its Message Type to automatically purge view messages.
2. Reply - these needs a reply value to be entered before clicking the checkbox as above. Sometimes, the reply value is a Drop-down list to be selected, usually a Yes/No choice.
3. Action - some messages or alerts requires the user to click on the “Act” button which will launch another tab for further action by the user. An example is when the message is an Authorisation request for a Business Rule.

When a new Alert arrives (or whenever the User logs in and there are pending alerts (which are awaiting action)), then a message will be displayed at the bottom right of the Dashboard. We have decided not to deliver alerts via pop-up windows because from past experience, we find that they annoy the users.

External Delivery

The same Message or Alert can also be delivered to the recipient via sms and/or email. This is controlled by its Message Type. This is in addition to delivery via the Dashboard.

Before you can send email, you must define your SMTP Server and user account details in the Application Registry. Please update the following Registry Keys :-

1. SMTP-SERVER : hostname of your Simple Mail Transport Protocol server, eg smtp.mymail.org
2. SMTP-PORT : Your SMTP host listens for connections using this TCP Port, usually 25.
3. SMTP-USERNAME : Your user account name with your SMTP host, usually your email address.
4. SMTP-PASSWORD : Your DES encrypted password to log in to your SMTP host. You need to use our bin/des_engine.py to encrypt your password.

Encrypting your SMTP account password for updating to the Application Registry. From the shell or Command Prompt:

$ python
>>> from bin.des_engine import des_engine
>>> des = des_engine()
>>> des.encrypt('MYPASSWORD')
>>> 'c6d37916e59c1eb35f54d234317349cc'

Copy and paste the last line (without the quotes) and update to the Application Registry. Test your email connection by running “email_conn.py” on the command line.

As for sending sms, we use Skype only. We do not forsee a high volume of sms. However if your application needs to send a higher volume of sms than us, then you can write your own using the API provided your sms service provider, best if it is a python API. Please look at our bin/skype_conn.py as a guide. You need to install Skype on the same server where Maymyo Daemons are running, sign up for an account and buy some credit. You must login to Skype before you start the daemons.

When Maymyo is installed, sending of sms is turned off by default. You can turn it back on by editing snippets/daemon.tab and changing the last parameter to “N”:

# Deliver Messages in MessageQueue (whose MessageType has external
# delivery method specified) by sms and/or email.
# skype (for sms) and smtp server must be connected to App Server and
# its parameters defined in AppRegistry.
# Parameters: P1 = Y/N to disable sending sms
msgr|Y|messenger.py|Y|06:00:00|01:00:00|1|Y

Using Messaging in your programs

Maintain Message Type

Maintain Message Types

When you want to use the Messaging mechanism in your programs, the first thing is to add a new Message Type. Give your Message Type a unique code. Then in the Delivery Method you have to choose how the message is to be delivered to the recipient, either “Queue” or “Alert”. The former is a normal message. Then the “Required Action” specifies how the recipient acts on the message. “Expiry Days” applies to how many days View messages are kept before they are purged from the recipients’ queue. So View Only messages should not be important messages as they can be purged without the recipient ever seeing them. Reply and Action messages are never purged until the recipient has acted on them.

“External Delivery Method” tells us whether you want the message to be sent via email and/ or sms to the recipient.

“Reply Choices” applies only to Reply messages, ie when the recipient must enter a Reply Value against the message. For example, selecting the YESNO-CHOICES will force the recipient to confirm the contents of the message. You can create your own Choices. Please refer to TODO.

Finally, “Action URL” refers to Action messages, when you want the message to directly launch a program (with parameters values you saved earlier with the message) so that the recipient can take action immediately without going through the Menu. A GET request will be formed using this URL plus its parameter values.

Using our standard Message Types

If your messages are not Action or need special Reply values, then you can choose to use our standard Message Types :-

• VIEW-NORMAL : view only message that is purged after 10 days
• REPLY-YESNO : reply Yes/No message
• ALERT-VIEW : view only alerts that is purged after 10 days
• ALERT-YESNO : reply Yes/No alert
• ALERT-SMS : alert that will also be sent as sms, purged after 10 days
• ALERT-EMAIL : alert that will also be sent as email, purged after 10 days
• ALERT-BOTH : alert that will also be sent as sms and email, purged after 10 days

Maintain Message Templates

If your program is sending email messages, then you may want to format a longer message that can use field values from your model instance (only one allowed per template, but we allow you to use its related fields, eg “fk.fk_field”). Which model instance to use is completely up to you.

Using our Reminder Events as an example, we generate reminders against a model whose status has not changed after a time interval (from its initial date and time). We expect the recipient to be a user in the same model instance. In this case we can construct a message using the fields of this model instance. An example would be to generate reminders from the Message Queue model whose Action messages has not been acted on after 14 days.

You can use these tokens in your message template :-

1. Model instance field values using #field1# or #fk.fk_field#, where fk is the Foreign Key field. The enclosing # is required.
2. Function calls using the fields as parameters, @package.module.function(#field1#,#field2#,’literal1’)@. Your function must start from your package and module that can be found in PYTHONPATH. The enclosing @ is required.

We will replace the tokens with the actual field values using infra.objects.app_tokens.replace_token_values.

Sending Messages in your programs

You will need to import our send_message function:

from infra.objects.message_type import send_message

If you are using a Message Template, then you need to prepare the message:

from infra.objects.app_token import replace_token_values
....
message_text = replace_token_values(your_model_instance, message_template.message_text)
external_message = replace_token_values(your_model_instance, message_template.external_message)

Then send the message to the recipient by:

# Send message to recipient
msg_que = send_message(recipient=recipient, message_text=message_text,
    sender=your_model_name, message_type=your_message_type,
    sender_instance=str(your_model_instance.id), external_message=external_message)

If you are not using Message Template, then omit the previous block and also the external_message parameter for send_message. The sender and sender_instance is for the recipient to figure out who sent the message. You can replace sender with a user instance and leave the sender_instance blank if using a user as the sender.

send_message will return back the Message Queue instance created (to send the message to the recipient). recipient must be a valid User instance.

Sending Action Messages

If your Message Type is an Action, then you may need to pass in a python list of parameter values using the action_parameters parameter to send_message. We allow only scalar types like int, float or str. If you pass in dates or datetimes, stringify them first to ISO format and let your action program convert them back to dates or datetimes.

The “Act” button in “Check your Messages” will append these as GET parameters to the action url.

Sending Messages to external recipients

You can send sms or email to external recipients, ie people who are not users of Maymyo. After getting a Message Queue instance (in msg_que variable in the above example), call its add_recipient method:

msg_que.add_recipient(contact_reference='mobile_or_email', email_mode='Cc')

The contact_reference should be a mobile phone number if sending by sms or email address if otherwise. You cannot send both sms and email (actually if you want to do that, then call add_recipient twice).

The email_mode applies only if sending email. If can be To (default if you do not pass in this parameter), Cc or Bcc.

It is up to you how to prepare a list of external recipients. It may be a list of Contact Persons for a Customer. Have a look at our Reminder Events for an example on how to get external recipients dynamically from related model instances.