Example Services Using EL

Simple example to count the number of times a service is triggered

To count the number of times that a service has been triggered using a self-referencing variable called service.Count:

1. Add a Set Variable handler at the beginning of the service.
2. In the handler properties, set:
   • Scope: service
   • Key: Count
   • Value: ${service.Count + 1}
   • Initial value on creation: 1

The Initial value on creation field is set to 1, so the first time the handler is processed, the service.Count value becomes 1. The next time the handler is processed, the expression ${service.Count + 1} is used to determine the variable’s new value — which will be 2.

Weather data service using the Get External Data handler

In this example, the "ACME" company has a simple weather information service that replies to end user SMS messages with information about the current weather. The service uses the Get External Data handler to retrieve weather information from the ACME platform.

The next diagram shows the layout that the service will follow.

The purpose of each handler is as follows:

The external server provides the weather data using the following XML format:

<?xml version="1.0"?>
<entry>
   <temperature>14C</temperature>
   <outlook>cloudy</outlook>
</entry>

When brought into MEP, the temperature and outlook data is accessible as variables:

${scope['entry.temperature']}
${scope['entry.outlook']}

Creating the service

1. Create a new custom service
   

   This particular service does not use one of the built-in service templates, so you will need to use a custom service. Select a service collection that you want to create the new service in.

2. Add the Get External Data handler

   Add your first handler to the service. This handler retrieves the weather information from a data source outside of MEP. This could be a system under your control, or an interface to a third-party service. To create this handler:

   1. Select the Get External Data handler.
   2. Specify the URL where MEP can contact the external server — for example, http://weather.yourserver.com/getweather.
   3. Select the Get External Data handler.

   4. Specify session as the scope for the handler.

      This sets the scope of the variables generated from the incoming XML. For the majority of services it is best to set this to session.

      You now have a Get External Data handler set up as the starting handler for the service. If an end user text message is routed to this service, data will be fetched from an external server and subsequent handlers will be able to access it as EL variables.

3. Add a Send SMS handler (delivers the weather information to the end user)
   This handler references the two variables:

   ${session['entry.temperature']} 

   ${session['entry.outlook']} 

   1. Select the Send SMS handler.

   2. In the message field, enter the following:

      The temperature now is ${session['entry.temperature']} and the outlook is ${session['entry.outlook']}.

   3. Specify the other details required for the handler, such as the SMS account.

   4. Connect this handler to the "success" outcome for the previous handler. The end user receives an SMS similar to this:

      The temperature now is 14C and the outlook is cloudy.

4. Add another Send SMS handler (responds to the user if there is no data available)

   This handler sends an SMS if the external data source is unavailable or does not return a valid response.

   1. Select the Send SMS handler.

   2. In the message field, enter the following:

      Sorry, weather information is currently not available.

   3. Specify the other details required for the handler, such as the SMS account.

      Connect this handler to the "failure" outcome for the previous handler.

5. Route an appropriate keyword to the service from the Routing tab.

   The service is now complete.

Promotional service for first 500 respondents

In this example the ACME Gym has sent an SMS with an offer of a month’s free membership. To win, respondents must be one of the first 500 users to text in the keyword GYM. In the service shown below, MEP counts the end users and sends the free membership SMS to the first 500 end users. This SMS contains a MEP generated unique PIN so that respondents can claim their prize. The PIN for each user is also sent to ACME’s external database.

The next diagram shows the layout the service will take (from the point where an end user has texted in GYM):

The purpose of each handler is as follows:

Creating the service

1. Create a new custom service

   This particular service does not use one of the built-in service templates, so you will need to use a custom service. Select a service collection that you want to create the new service in.

2. Add a Set Variables handler (1) to count the number of times the service is triggered

   This handler creates a new variable called numberofusers. When a new message is received, the handler adds 1 to the value of the expression. To create this handler:

   1. Set the scope to: Service

      By using the service scope, we ensure that the service has only one instance of the variable.

   2. Set the key to a unique name; e.g.: numberofusers
   3. Set the value to a self-referential expression: ${service.numberofusers+1}

   4. Since the value is self-referential, there needs to be a starting value (the initial value). Set this to: 1

      In this service, the variable is created the first time that the service is triggered. Alternatively we could enter the variable manually in the Service Variables screen for the service (in which case, you do not need to set an initial value in this handler).

3. Add a Branch on Expression handler to check whether the user is in the first 500

   This handler uses an expression to check whether the value of the numberofusers variable is lower than or equal to 500. Add a handler under the first handler, with the expression:
   

   ${service.numberofusers <= 500}
   

   It will return a Boolean value of ‘true’ or ‘false’, which the handler then can branch from—if the statement is correct (that the service.numberofusers is less than or equal to 500) then the value is true.

4. Add a Set Variable handler (2) on the "true" branch to generate a PIN

   This handler uses an expression to generate a PIN for each successful respondent. This is the first handler on the ‘true’ branch. To create this handler:

   1. Set the scope to: userservice
      By using the userservice scope, we ensure that each user has one instance of the variable that is only accessible from this service. This allows multiple services to use userservice.pin with no danger of the values conflicting.
   2. Set the key to: pin
   3. Set the value to: ${af:generatePin(10,false)}
      This expression uses the generatePin function to create a 10 digit long pin. There is no need to set an initial value on creation for this expression.

5. Add a Send SMS handler (1) onto the previous handler to send the PIN to the user
   This handler uses an expression to sends the PIN to the end user. In the message field for the handler, add a message similar to this:

   Congratulations, you've won free membership for a month! Just bring this text message to one of our gyms to claim: ${userservice.pin}

6. Add an HTTP Poke handler onto the previous handler to send the PIN to your platform

   This handler uses an HTTP poke to send the PIN, the date and time, and the mobile number of the end user to an external database; in this case, acme.example.com/poke.cgi. All these values are identified using expressions. In the handler, enter the URL and parameters; e.g.:
   

   https://acme.example.com/poke.cgi?msisdn=${user.identifiers.msisdn}&pin=${userservice.pin}&time=${session.initialMessage.date}
   

   The expressions used in this example are:

   • ${user.identifiers.msisdn} : The mobile number of the end user (a built-in variable).
   • ${userservice.pin} : The PIN for this user.
   • ${session.initialMessage.date} : The system date and time (a built-in variable).

7. Add a Send SMS handler (2) on the "false" branch to send a sorry message

   This handler sends an SMS message to end users who were not in the first 500 respondents. Add this handler on the "false" branch of the Branch on Expression handler. Add an appropriate sorry message to send.

Viewing the numberofusers value

You can use the GUI to view the number of times the numberofusers variable has been incremented. To view the value for the variable, click the Variables on the Edit Service page. This opens the Service Variables page for the service. The number of times the service has been accessed will match the number of times the variable was incremented.