Before You Begin
Making Invoke Service Requests
You can use the invoke service operation for any kind of integration where you want an external system, such as a website or CRM system, to initiate a MEP service for a specific end user.
You can test your integration using the OpenMarket Customer Integration Environment (CIE). The primary purpose of testing is to ensure that your requests will validate. To test invocation of your MEP service, you will need to use your test mobile devices.
Note: The Invoke Service operation supports the same basic functionality as the Inject Message operation. The primary differences between the two are that Invoke Service provides enhanced security and high availability capabilities. If you are an existing customer using the Inject Message operation, contact your OpenMarket account manager to determine the migration effort. If you are a new customer, you may want to contact your account manager to determine which operation best fits your needs.
Before we begin
Before beginning, you'll need a MEP account provisioned. Once provisioned, log into MEP and make sure in the MEP user account that you have the following settings:
- Main Roles
- Either Services Manager, Service User or Service Viewer. We recommend setting the account as Service Manager, as service managers can access all service collections and services.
- Other Roles
- Invoke Service API role
OpenMarket rejects messages from accounts that are not provisioned with the above.
The account will also need access to the Service Collection that contains the triggered service. However, the API will accept requests with any correctly formatted service ID (and request header/body). It cannot validate whether the customer account you have used can access the specified service ID.
Retrieve a service ID
Invoke service requests must include an ID for a service. To obtain a service ID:
- Navigate to the Services tab.
- Expand the Service Collection that contains the desired service. The "ID" column shows the service ID of each service.
Invoke a service
(Operation: Invoke a Service)
This example request invokes a MEP service for a fictional US number, and sets both user and session variables.
1. Create a text file for the POST body
Create a text file called invoke-service.txt and copy in the example below. If desired, you can change the example US phone number "12515550130" to one that you can receive messages on; otherwise you can test the operation using the example, as the example is a fictional number and will not reach an end user. Make sure that you include the country code so that the number is in international format (e.g. 44 for the UK or 1 for the US). Don't add a "+" character.
{
"endUser": {
"phoneNumber": 12515550130,
"mobileOperatorId": 383
},
"variables": {
"session": {
"seatLocation": "aisle",
"seatClass": "first",
"flightNumber": 49,
"flightAirline": "AwesomeAirways"
},
"user": {
"frequentFlyerAccountNumber": "MJHF787679"
}
}
}2. Use cURL to send the message
Make a request using the following sample cURL. You'll need to:
- Ensure you're in the same folder/directory as the text file
- Replace the accountid:password with your OpenMarket account ID and password (note that this is sent using Basic authentication).
- Change the example service ID F9E8D7C6B5A4 to your own service ID
curl -X POST -H "Content-Type: application/json" --user accountid:password --data-binary @invoke-service.txt --dump-header response.txt https://servicemanager.openmarket.com/service/v1/invokeService/F9E8D7C6B5A4
If your request is successful, OpenMarket will return a synchronous response, with an HTTP status code of 202. In this example, the response is found in the file response.txt.
HTTP/1.1 202 Accepted
Content-Length: 0
X-Request-Id: 7EYYG-EF3XM-5LSQ5-ILR73The X-Request-ID uniquely identifies the request in OpenMarket reporting and with our support team.
Including variables in the request
When you invoke a service with this operation, you can set variables related to both the session and the end user. This enables you to create or update custom variables with each request.
This feature acts much the same as if you are creating or updating a variable at the beginning of the service using a Set Variable handler. The variables are set before the message is routed and are accessible immediately within the triggered service.
You can send an expression as part of the variable's value, as long as the expression doesn't require an initial value that hasn't been defined (for example, you can't set a self-referential expression). With variables, you can update only custom variables (not built-in variables) and you must avoid reserved words.
You can specify variables with the following scope:
- Session scopes: request and session
- User scopes: user, userservice, and userservicecoll
The Variables object
You can include variables in the request body using the variables object. The properties inside this object are scope, key and value.
This object is optional. If you do include the object, then you must include at least one variable (you cannot leave the object empty). You can specify each scope just once, but include multiple keys for the scope, for example:
"variables": {
"session": {
"seatLocation": "aisle",
"seatClass": "first",
"flightNumber": 49,
"flightAirline": "AwesomeAirways"
},
"user": {
"frequentFlyerAccountNumber": "MJHF787679"
}For full details on the request body, see Invoke a Service.
Identifier variables set with the API
The following identifiers may be automatically created or updated with each successful request:
- user.identifiers.msisdn — the phoneNumber property in the request.
- user.id — this is an MEP generated ID that is unique to each end user (as identified by the phone number in this API).
- user.identifiers.msisdn.network — the mobileOperatorId property in the request. If the number is for a landline or is not provided in the request, and MEP does not know the mobile operator from previous interactions, then this is set to "UNKNOWN".
Note that you cannot set the user.identifiers.email variable in this request.
How variables are validated
The variable scope and key are both validated when using this API and you will receive an error if there is a problem. The scope and key are validated for the following issues:
- A scope property is invalid (e.g. "userz").
- The same scope is specified multiple times in the request.
- A key property uses a character outside of the defined list of accepted characters, or the character length of the key is too long or too short.
- A key property is a reserved word.
- A key is specified multiple times within a scope.
- A specified variable (scope.key) is a built-in variable.
With the variable value, this API checks for the following issues and will send an error if found:
- A value property uses a character outside of the defined list of accepted characters.
- The character length of a value is too long. If your value is an expression, then the API checks the character count of the expression, not the eventual evaluated expression. For example, if your value is a PIN you are generating using an EL function: ${af:generatePin(6,true)} then the value will be counted as 25 characters, rather than the evaluated expression (which is 6 character PIN).
When checking a value, this API cannot determine if there is an issue with how the value is processed in the service. For example, it cannot check whether any expressions in the value are self-referential or that an expression is formatted correctly.
Issues with the scope, key or value return a 400 HTTP response code with an OpenMarket error code of 12002.