.. _msg_alert: ==================== 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. .. image:: ../_static/install/dashboard.png 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. .. image:: ../_static/msg_alert/my_msg.png 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 :- #. 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. #. 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. #. 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 :- #. SMTP-SERVER : hostname of your Simple Mail Transport Protocol server, eg smtp.mymail.org #. SMTP-PORT : Your SMTP host listens for connections using this TCP Port, usually 25. #. SMTP-USERNAME : Your user account name with your SMTP host, usually your email address. #. 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 ^^^^^^^^^^^^^^^^^^^^^ .. image:: ../_static/msg_alert/msg_type.png 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. .. _std_msg_type: 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 :- #. Model instance field values using *#field1#* or *#fk.fk_field#*, where *fk* is the Foreign Key field. The enclosing # is required. #. 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.