Service Invoke URL endpoint

This endpoint is invoked by a product. This topic explains the invocation request, see Service Invocation for full details about the invocation process.

REQUEST NOTES:

  • There are two invocation flows:

    1. Invocation with data

      An invocation with data is done when the request body contains data. Data is provided within dataset.

    2. Invocation without data

      An invocation without data is performed when the request body does not contain data within dataset. In this scenario, the size of data will be provided, and an endpoint (productExportEndpoint) will need to be provided for the app to retrieve the data.

  • Three endpoints can be provided as part of the invoke:

    • productExportEndpoint: Used to fetch pages of data from a product into an app based on the maxPullPageSize. The maxPullPageSize parameter determines the largest pagination size provided by the productExportEndpoint. Should be a GET. Is omitted if the invoke is done with data.
    • productImportEndpoint: Used to push results back into a product by the app based on the maxPushBatchSize. The maxPushBatchSize determines the largest amount of records to push per batch to the productImportEndpoint. Should be a POST or a PUT. Is omitted if product is not interested in the results. Learn more

    • onCompletionCallbackEndpoint: Used to inform a product that the app has completed the invoke. This is optional and should be either a PATCH, PUT, or a POST.

      Note: During invocation for “Invoke without data” and “Invoke with data (small batch) flow", to support high concurrency and to ensure data processing, there is a delay of 15-20 minutes after the app sends back the “onCompletionCallbackEndpoint” request before enactments are moved to the next stage in the Responsys program.

Service URL

<service-baseUrl><service-invokeUrl>

These URLs are registered with AMS when creating a service.

Request Method

POST

Request Header

Authorization: Bearer <JWT>

Content-Type=application/json

Bearer Token

JWT Claims

In the case where it is a product making the request to the app, the key and value pairs bear the following meanings:

Key Value Definition Context
iss The issuer of the token. The product's UUID.
aud The audience of the token. Set to the instance UUID.
exp The date and time the token will expire, expressed as a Unix timestamp. Must be after the current date/time. Set to 60 seconds after the JWT was created.
iat The date and time the JWT was issued, expressed as a Unix timestamp. Set to the current time.
o.a.p.ctenantId The id of the tenant. The id of the tenant.

Signature

Signed with the app's install secret.

Sample JWT Payload

{
 "iss": "f866f138-0e2d-fd88-aa61-e8d21c7dbfee",
 "aud": "6ea036bb-8cfb-46c5-a826-d001d3a0349b",
 "exp": 1506964515000,
 "iat": 1506964485000,
 "o.a.p.ctenantId": "6607"
}

Sample Request Body

REQUEST NOTES:

  • The recordDefinition is defined by your app. See Record definitions for more information.

Invocation with data

{
 "instanceContext": {
  "appId": "38281836-4bb4-2cdb-6006-592a98d02da1",
  "appVersion": null,
  "installId": "a28b7df0-2a16-26e1-08e4-a302199208d9",
  "instanceId": "6ea036bb-8cfb-46c5-a826-d001d3a0349b",
  "serviceId": "13023bae-8350-f75f-d953-f7a96d6928b6",
  "tenantId": "6607",
  "productId": "78ffbba2-cf29-a607-c611-3f05e9199a39",
  "maxPushBatchSize": 1000,
  "secret": "c4321e9f-19a7-48b2-9796-c21142c709c9-fb24667d-de63-4b6a-99af-10b23122a6d0",
  "recordDefinition": {
   "inputParameters": [...],
   "outputParameters": [...]
  },
  "maxBatchSize": 1000
 },
 "dataSet": {
  "id": "my-test-data-set",
  "rows": [
   ["72a50e37-4dbc-4c97-bb4e-366dd4dcce6d", "Canada", "Toronto"]
  ],
  "size": null
 },
 "productExportEndpoint": null,
 "productImportEndpoint": {
  "url": "http://localhost:10000/data",
  "method": "POST",
  "headers": {}
 },
 "onCompletionCallbackEndpoint": {
  "url": "http://localhost:10000/feedback",
  "method": "POST",
  "headers": {}
 },
 "maxPullPageSize": 5,
 "maxPushBatchSize": 5
}

Sample Response body in case of success

RESPONSE NOTES:

  • In the case the invoke was successful, successful will be set to true.
  • After a successful invocation, an invocationId is produced by the app and should be unique. This gets passed to the product so it can determine which result comes from which invocation Id. The actual data for the invocation result is sent directly from the app to the products's productImportEndpoint. This happens asynchronously and independent of AMS. Learn more.

When a service instance is executed or invoked, apps will respond with a JSON payload that resembles the following.

{
  "successful": true,
  "content": {
    "invocationId": "64a9e8a1-e3cd-4bb4-a4b0-93d55832f90d",
    "instanceId": "6ea036bb-8cfb-46c5-a826-d001d3a0349b"
  },
  "errorMessage": null
}
Property Description
successful A boolean value.
content A mixed type, usually an object or an array.
errorMessage A string which provides details into an issue such as a "401 Unauthorized". When successful is true, errorMessage will be null.

Invocation without data

{
 "instanceContext": {
  "appId": "38281836-4bb4-2cdb-6006-592a98d02da1",
  "appVersion": null,
  "installId": "a28b7df0-2a16-26e1-08e4-a302199208d9",
  "instanceId": "6ea036bb-8cfb-46c5-a826-d001d3a0349b",
  "serviceId": "13023bae-8350-f75f-d953-f7a96d6928b6",
  "tenantId": "6607",
  "productId": "78ffbba2-cf29-a607-c611-3f05e9199a39",
  "maxPushBatchSize": 1000,
  "secret": "c4321e9f-19a7-48b2-9796-c21142c709c9-fb24667d-de63-4b6a-99af-10b23122a6d0",
  "recordDefinition": {
   "inputParameters": [...],
   "outputParameters": [...]
  },
  "maxBatchSize": 1000
 },
 "dataSet": {
  "id": "my-test-data-set",
  "rows": null,
  "size": 6
 },
 "productExportEndpoint": {
  "url": "http://localhost:10001/data",
  "method": "GET",
  "headers": {}
 },
 "productImportEndpoint": {
  "url": "http://localhost:10001/data",
  "method": "POST",
  "headers": {}
 },
 "onCompletionCallbackEndpoint": {
  "url": "http://localhost:10001/feedback",
  "method": "PATCH",
  "headers": {}
 },
 "maxPullPageSize": 5,
 "maxPushBatchSize": 5
}

Sample Response body in case of success

RESPONSE NOTES:

  • In the case the invoke was successful, successful will be set to true.
  • After a successful invocation, an invocationId is produced by the app and should be unique. This gets passed to the product so it can determine which result comes from which invocation Id. The actual data for the invocation result is sent directly from the app to the products's productImportEndpoint. This happens asynchronously and independent of AMS. Learn more.

When a service instance is executed or invoked, apps will respond with a JSON payload that resembles the following.

{
  "successful": true,
  "content": {
    "invocationId": "64a9e8a1-e3cd-4bb4-a4b0-93d55832f90d",
    "instanceId": "6ea036bb-8cfb-46c5-a826-d001d3a0349b"
  },
  "errorMessage": null
}
Property Description
successful A boolean value.
content A mixed type, usually an object or an array.
errorMessage A string which provides details into an issue such as a "401 Unauthorized". When successful is true, errorMessage will be null.

Learn more

Endpoint reference