Creating an sms notification template

In the ELMA directory, there is the folder UserConfig/Notifications, which stores XML files that describe system notification templates (fig. 1). Notifications are sent to users via ELMA Messages section and via email. Each file contains several notification templates, corresponding to certain events in ELMA.

Fig. 1. UserConfig / Notifications folder with system notification templates.

To create an SMS notification template:

  1. Copy the template of the notification on the event, on which you want to notify users in an SMS notification, to an XML file with a new name.
  2. Make changes to this file:
    • after the Notification tag in the message template, add <Channels>SMS</Channels>. This line defines that this notification must be sent only via SMS.
    • review the SMS notification template; it should not be too long. Adjust it if necessary.
  3. Save the file.

The template specifies the ELMA event, therefore, if SMS notifications are enabled, the system knows to which event to respond with an SMS.

Example: creating an SMS notification about a new calendar event

To learn more about creating notification templates, read this article.

As an example, let's create an SMS notification about the system event "New calendar event": each time a new calendar event is created in ELMA and a certain user participates in it, the user will receive a notification.

Go to the folder C://ELMA3-[Edition]/UserConfig/Notifications. Templates of notifications, related to the calendar, are in the file Calendar.CalendarEvent.xml (fig. 2)

Fig. 2. Calendar.CalendarEvent.xml file in the folder C://Program Files/ELMA3-Express/UserConfig/Notifications.

Open this file in any text editor, find the template of the notification about a new calendar event (fig. 3) and copy it to a new XML file with a new SMS template name, e.g. Calendar.CalendarEventSms.xml (fig. 4).

                                                                                                

Fig. 3. A fragment of the Calendar.CalendarEvent.xml file.

XML code from the figure above (attention! this is not the entire code, only the required tags are highlighted):

<?xml version="1.0" encoding="utf-8"?>
<Notifications description="Оповещения о событиях календаря​" version="3.0.0.2700">
  <Partial Name="CalendarEventFields">
    {PropertyRow({$New.Subject})}
    {PropertyRow({$New.Place})}
                              ......................
  <Default>
    <Filter>
      <Event>IEntityActionHandler.ActionExecuted</Event>
      <Object>EleWise.ELMA.Calendar.Models.CalendarEvent</Object>
    </Filter>
    <RecipientSet Name="ConfirmParticipation">
      <ConfirmParticipationRecipient>{$New}</ConfirmParticipationRecipient>
    </RecipientSet>
    <RecipientSet>
      <User>{$New.CreationAuthor}</User>
      <ParticipantRecipients>{$New}</ParticipantRecipients>
      <InformToRecipients>{$New}</InformToRecipients>
    </RecipientSet>
    <URL>
      /Calendar/Event/View/{$New.Id}
    </URL>
                               ......................
  <Notification Name="Create">
    <Filter>
      <Action>Create</Action>
      <Condition>
        {$New.TemplateEvent}=NULL
      </Condition>
    </Filter>
    <Subject>
      ({SR(’Новое событие’)}{If {$RecipientSet}=’ConfirmParticipation’}. {SR(’Необходимо подтверждение участия’)}{end if}) {$New.Subject}
    </Subject>
    <ShortMessage>
    {If {$RecipientSet}=’ConfirmParticipation’}{SR(’!!!НЕОБХОДИМО ПОДТВЕРДИТЬ ВАШЕ УЧАСТИЕ В ДАННОМ СОБЫТИИ!!!’)}{end if}
    {TableStart()}
    {$New.Description}
    {PropertyFullRow({$New.Attachments};’’)}
    {ExtensionZone(’EleWise.ELMA.Calendar.Models.CalendarEvent-DefaultShortMessage-AfterAttachments’)}
    {TableEnd()}
  </ShortMessage>
    <FullMessage>
    {If {$RecipientSet}=’ConfirmParticipation’}{SR(’!!!НЕОБХОДИМО ПОДТВЕРДИТЬ ВАШЕ УЧАСТИЕ В ДАННОМ СОБЫТИИ!!!’)}{end if}
    {TableStart()}
    {Partial(’CalendarEventFields’)}
    {PropertyFullRow({$New.Attachments};’’)}
    {ExtensionZone(’EleWise.ELMA.Calendar.Models.CalendarEvent-DefaultFullMessage-AfterAttachments’)}
    {TableEnd()}
  </FullMessage>
  </Notification>
                               .......................
                                                                      
Fig. 4. New SMS template file Calendar.CalendarEventSms.xml in the folder.

Create a template of a new SMS notification:

After <Notification Name="Create"> add <Channels>SMS</Channels> (fig. 5).

Apart from the notification template, copy the following to the new file Calendar.CalendarEventSms.xml:

  • copy the first two lines from the file Calendar.CalendarEvent.xml (fig. 3), and close the Notification tag at the end of the file (fig. 5).

Inside the tag <Notification Name="Create"> insert the following from the parent file Calendar.CalendarEvent.xml:                                                                                                                                   

<RecipientSet>
      <User>{$New.CreationAuthor}</User>
      <ParticipantRecipients>{$New}</ParticipantRecipients>
      <InformToRecipients>{$New}</InformToRecipients>
</RecipientSet>
- defines the event recipient,
<URL>
        /Calendar/Event/View/{$New.Id}
</URL>
- link to the event.

Inside the Filter tag, which is inside the <Notification Name="Create"> tag, insert two lines from the parent file from the Filter tag, which is inside the Default tag (fig. 3).

Fig. 5. The content of the file Calendar.CalendarEventSms.xml.

Edit the SMS notification template. It should be short and include:
    "Subject" - the text in the Subject tag and
    "Short Message" - the text in the ShortMessage tag.
"Full Message" - the text in the FullMessage tag should be deleted, it is required only for system notifications, which are sent to users in ELMA or via email.         

You can also delete the following fragment from the short message:

because it creates a table, which is required only for the notifications, sent in ELMA or via email.

Let's change the text "!!!НЕОБХОДИМО ПОДТВЕРДИТЬ ВАШЕ УЧАСТИЕ В ДАННОМ СОБЫТИИ!!!" to "Please confirm that you participate in the event".

As the result you have the following template:                                                            

Fig. 6. The content of the file Calendar.CalendarEventSms.xml.

Code of the XML file:

<?xml version="1.0" encoding="utf-8"?>
<Notifications description="Notifications about calendar events" version="3.0.0.2700">
    <Notification Name="Create">
        <Channels>SMS</Channels>
    <RecipientSet>
      <User>{$New.CreationAuthor}</User>
      <ParticipantRecipients>{$New}</ParticipantRecipients>
      <InformToRecipients>{$New}</InformToRecipients>
    </RecipientSet>
    <URL>
      /Calendar/Event/View/{$New.Id}
    </URL>
    <Filter>
      <Event>IEntityActionHandler.ActionExecuted</Event>
      <Object>EleWise.ELMA.Calendar.Models.CalendarEvent</Object>
      <Action>Create</Action>
      <Condition>
        {$New.TemplateEvent}=NULL
      </Condition>
    </Filter>
    <Subject>
      ({SR(’New event’)}{If {$RecipientSet}=’ConfirmParticipation’}. {SR(’Confirm participation’)}{end if}) {$New.Subject}
    </Subject>
    <ShortMessage>
      {If {$RecipientSet}=’ConfirmParticipation’}{SR(’Please confirm that you participate in the event’)}{end if}
   </ShortMessage>
   </Notification>
</Notification>
 

The SMS notification text is generated from the three tags: <Subject> <URL> <ShortMessage>; the order of these tags in the template does not matter.

Function {StringCut(text;length)}

You can use the {StringCut(text;length)} function in SMS notification templates - it trims the text to the required number of characters.

Fig. 7 shows an example of using this function in a template of an SMS notification about a new high priority task. The function trims the task subject to 40 characters so that the SMS was not too long.                                  

Fig. 7. A template of an SMS notification about a new high priority task.

Code of the XML file:

<?xml version="1.0" encoding="utf-8"?>
<Notifications description="Notifications about tasks" version="3.0.0.2700">
 
    <Default>
        <Channels>SMS</Channels>
     <Filter>
      <Event>IEntityActionHandler.ActionExecuted</Event>
      <Object>EleWise.ELMA.Tasks.Models.Task</Object>
     </Filter>    
     <RecipientSet>
      <User>{$New.Executor}</User>
     </RecipientSet>
     <URL>
      /Tasks/Task/Execute/{$New.Id}
     </URL>
     <Subject>
      {StringCut({$New.Subject};40)}
     </Subject>
     <ShortMessage>
      {GetUserShortName({$New.CreationAuthor})
     </ShortMessage>
     <ObjectId>{$New.Id}</ObjectId>
    </Default>
    <Notification Name="Create">
     <Filter>
      <Condition>
        ({$New.Priority}=’High’)and(({$Action.Name}=’Create’)and({$New.Status.Value}&lt;&gt;’112ea757-36f7-4859-b0d3-6cc0f5a04705’)or({$Action.Name}=’Activate’))and({$New.IsTemplate}=’false’)
      </Condition>
     </Filter>
    </Notification>
    <Notification Name="Redirect">
     <Filter>
      <Action>Redirect</Action>
      <Condition>
        {$New.Priority}=’High’
      </Condition>
     </Filter>
    </Notification>
</Notification>