Invoke a Service

Use this operation to trigger an existing MEP service for an end user.

When you inject a message into MEP, 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. For information, see Including variables in the request.

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.

Quick facts

Making a Request

Definition

POST https://servicemanager.openmarket.com/service/v1/invokeService/<serviceId>

URL example

https://servicemanager.openmarket.com/service/v1/invokeService/F9E8D7C6B5A4

Query parameters

Parameters must be URL encoded.

Header fields

You must provide your authentication details using Basic authentication in the header. You should also specify that the content-type is JSON. For example:

POST /service/v1/invokeService/F9E8D7C6B5A4 HTTP/1.1
Host: servicemanager.openmarket.com
Content-Type: application/json
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

Request body

The request body must be well-formatted JSON that includes the end user's contact details and, optionally, any variables you wish to set. The request body should not exceed 8,000 bytes.

The variables object

The variables object lets you set one or more variables at the same time as the service is invoked. Variables are defined in this operation using scope, key and value properties.

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 (see example below).

Note that when creating a variable:

• You can specify variables with the following scope:
  • Session scopes: request, session
  • User scopes: user, userservice, userservicecoll
• You can only specify custom variables in the request. Built-in variables cannot be altered.
• There is a set of reserved words that you cannot use as variable keys.
• Keys can only use a specific set of characters.

Issues with the variable scope, key and value are validated when using this operation, and you will receive an error if there is a problem. For further details, see Including variables in the request.

JSON schema

{
"endUser": {
   "phoneNumber": <number>,
   "mobileOperatorId": <Id>
   },
"variables": {
   "<scope>": {
      "<key>": "<value>",
      "<key>": "<value>"
      },
   "<scope>": {
      "<key>": "<value>",
      "<key>": "<value>"
      }
   }
}

Example

{
"endUser": {
   "phoneNumber": "12515550123",
   "mobileOperatorId": 383
   },
"variables": {
   "session": {
      "seatLocation": "aisle",
      "seatClass": "first",
      "flightNumber": 49,
      "flightAirline": "AwesomeAirways"
   },
   "user": {
      "frequentFlyerAccountNumber": "MJHF787679"
      }
   }
}

Properties in the endUser object

Properties/values in the variables object

Response from OpenMarket

Accepted requests

OpenMarket responds to a successful request with a status code of 202.

Note: The API will accept requests with any correctly formatted service ID (and request header/body). The API does not validate whether the customer account you have used can access the specified service ID. Services that the account cannot access are not triggered.

The response header contains an X-Request-Id. This uniquely identifies the request in OpenMarket reporting and with our support team. Please include this ID in any request to OpenMarket Support where referencing an issue with a specific invoke service request.

HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 16:14:43 GMT
Server: Apache-Coyote/1.1
X-Request-Id: 7EYYG-EF3XM-5LSQ5-ILR73
Transfer-Encoding: chunked

Rejected requests

If your request is rejected then the body of the response will contain a JSON that identifies the issue. It will also include an X-Request-Id in the header.

HTTP/1.1 400 Bad Request
Date: Tue, 15 Mar 2016 11:48:56 GMT
Server: Apache-Coyote/1.1
Connection: close
Transfer-Encoding: chunked
X-Request-Id: 7EYYG-EF3XM-5LSQ5-ILR73
Content-Type: application/json

{ 
"error" : {
   "code":12002, 
   "description":"Invalid JSON in the payload. Value for '<variable>' is an invalid length. Values must be less than 4096 characters"
   } 
}

The response will include following data.

Testing your integration

You can use the OpenMarket Customer Integration Environment (CIE) to test your integration. See Testing Your Invoke Service Integration.

Troubleshooting

My request was accepted, but my service wasn't invoked

The API will accept requests with any correctly formatted service ID (and request header/body). The API cannot validate whether the customer account you have used can access the specified service ID. Services that the account cannot access are not triggered. This includes service IDs for services that are disabled or don't exist.

You may wish to set the account as a Services Manager, as service managers can access all service collections associated with the customer account, including any new services. We would also recommend testing that each service is correctly triggered.

Response error codes

These error messages are returned in the response body when there was a problem with receiving the request.