Create URL endpoint

The purpose of the Create URL is to create a service instance. Using Oracle Responsys Action services as an example, the workflow resembles:

A marketer drags an App Activity stage onto a canvas and selects a service.

Responsys calls AMS, and AMS calls the service's Create URL endpoint to create a service on that canvas.

Service Create URL endpoint

AMS calls the service's Create URL endpoint with the following request.

Service URL

<service-baseUrl><service-createUrl>

Request Method

POST

Request Header

Authorization: Bearer <JWT>

Content-Type=application/json

Bearer Token

JWT claims

When AMS is 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. Issuer is AMS
sub The subject of the token. Set to the app's associated product uuid.
aud The audience of the token. The App's Token Key.
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.
jti The unique identifier for the JWT token. Set to a random UUID
o.a.p.ctenantId The tenant Id. Set to the id of the tenant as identified by the product
o.a.p.cproductUUID The product UUID. Set to the product's UUID.
o.a.p.cproductName The product name. Set to the product's name.
o.a.p.csourceRequest The source of the request. Set to the product's UUID.
o.a.p.cdestinationId The destination Id. Set to the app's token key (found in app details)
o.a.p.cdestinationUrl The destination URL. Set to the service instance creation URL (the service's base URL + the service's create URL. These URLs are found in service details.

Signature

Signed with an app's token secret.

Sample request

POST <service-base-url><service-create-url>
Authorization: Bearer<JWT>
{
  "status": "CREATED",
  "assetId": null,
  "assetType": null,
  "uuid": "4420fa19-e8f6-4cdf-9754-d876dea3002f",
  "secret": "c4321e9f-19a7-48b2-9796-c21142c709c9-fb24667dde63-4b6a-99af-10b23122a6d0",
  "recordDefinition": null,
  "applicationServiceInstall": {
    "uuid": "40fe3760-a487-4e89-8cf5-2d3e06977623",
    "name": "Demo transform service for developer's test",
    "description": "Demo transform service for developer's         test",
    "invokeUrl": "https://b3a3ba42.ngrok.io/CX-app-demo-1.0/rest/1.0/services/1/invoke",
    "smallLogo": "https://www.iconexperience.com/_img/o_collection_png/green_dark_grey/48x48/plain/delivery_truck.png",
    "mediumLogo": "https://www.iconexperience.com/_img/o_collection_png/green_dark_grey/128x128/plain/delivery_truck.png",
    "largeLogo": "https://www.iconexperience.com/_img/o_collection_png/green_dark_grey/256x256/plain/delivery_truck.png",
    "maxBatchSize": 200,
    "application": {
      "uuid": "b95d7bea-0154-47b8-81ca-ea4e35e784a9",
      "name": "Demo App",
      "description": "It is a demo app",
      "baseUrl": "https://oap.p01.elqqa01.com/awesome-app",
      "statusUrl": "/status",
      "installUrl": "/install",
      "configureUrl": "/configure",
      "uninstallUrl": "/uninstall",
      "saveConfigurationUrl": "/save",
      "smallLogo": "https://images.martechadvisor.com/images/uploads/product_logos/Oracle%20Responsys.jpeg",
      "mediumLogo": "https://images.martechadvisor.com/images/uploads/product_logos/Oracle%20Responsys.jpeg",
      "largeLogo": "https://images.martechadvisor.com/images/uploads/product_logos/Oracle%20Responsys.jpeg",
      "status": "UP",
      "providerUuid": "9dbda2d4-e9ac-4aab-8886-be0402a662cb"
    },
    "serviceType": {
      "name": "ACTIVITY",
      "externalName": "Activity",
      "description": "This service will ingest data and send it to an external service or process it to return back a status or modified data"
    },
    "installUuid": "05860261-2f24-4639-ae38-3616306e3f2d",
    "productName": "Responsys",
    "providerName": "ResponsysApps",
    "status": "UP"
  }
}
{
  "status": "CREATED",
  "assetId": null,
  "assetType": null,
  "uuid": "4420fa19-e8f6-4cdf-9754-d876dea3002f",
  "secret": "c4321e9f-19a7-48b2-9796-c21142c709c9-fb24667dde63-4b6a-99af-10b23122a6d0",
  "recordDefinition": null,
  "applicationServiceInstall": {
    "uuid": "40fe3760-a487-4e89-8cf5-2d3e06977623",
    "name": "Sample Template Service",
    "description": "A sample service used for testing",
    "invokeUrl": "https://b3a3ba42.ngrok.io/CX-app-demo-1.0/rest/1.0/services/1/invoke",
    "smallLogo": "https://www.iconexperience.com/_img/o_collection_png/green_dark_grey/48x48/plain/delivery_truck.png",
    "mediumLogo": "https://www.iconexperience.com/_img/o_collection_png/green_dark_grey/128x128/plain/delivery_truck.png",
    "largeLogo": "https://www.iconexperience.com/_img/o_collection_png/green_dark_grey/256x256/plain/delivery_truck.png",
    "maxBatchSize": 200,
    "application": {
      "uuid": "b95d7bea-0154-47b8-81ca-ea4e35e784a9",
      "name": "Demo App",
      "description": "It is a demo app",
      "baseUrl": "https://oap.p01.elqqa01.com/awesome-app",
      "statusUrl": "/status",
      "installUrl": "/install",
      "configureUrl": "/configure",
      "uninstallUrl": "/uninstall",
      "saveConfigurationUrl": "/save",
      "smallLogo": "https://images.martechadvisor.com/images/uploads/product_logos/Oracle%20Responsys.jpeg",
      "mediumLogo": "https://images.martechadvisor.com/images/uploads/product_logos/Oracle%20Responsys.jpeg",
      "largeLogo": "https://images.martechadvisor.com/images/uploads/product_logos/Oracle%20Responsys.jpeg",
      "status": "UP",
      "providerUuid": "9dbda2d4-e9ac-4aab-8886-be0402a662cb",
      "serviceType": {
        "name": "TEMPLATE",
        "externalName": "Activity",
        "description": "This service appears in the Email Message Designer"
      },
      "installUuid": "05860261-2f24-4639-ae38-3616306e3f2d",
      "productName": "Responsys",
      "providerName": "ResponsysApps",
      "status": "UP"
    }
  }

Tip: The JWT Token in the Authorization Header is generated by following the AMS to App token generation. For more information about this call, including authentication details, see the endpoint API reference.

Sample response in case of success

RESPONSE NOTES

  • If the app is up, the app creates an instance and responds with success or failure
  • If the app is not up, the app does not respond
{
    "id": "4420fa19-e8f6-4cdf-9754-d876dea3002f",
    "serviceId": "40fe3760-a487-4e89-8cf5-2d3e06977623",
    "status": "CREATED",
    "name": "Demo transform service for developer's test",
    "iconUrl": "https://www.iconexperience.com/_img/o_collection_png/green_dark_grey/48x48/plain/delivery_truck.png"
}

Responsys expects to receive a data transfer object (DTO) describing the record definition. If the app responds back to AMS with a 2xx response status code, the service is created.

Note: If the app is intending to set a status and provide an error message per record, the app is expected to include at a minimum these parameters as they are required for setting a record's status and providing error detail when needed:

  • inputParameters

    • appcloud_row_correlation_id

  • outputParameters

    • appcloud_row_correlation_id
    • appcloud_row_status
    • appcloud_row_errormessage

App's response to the Create URL request

The service's Create URL endpoint may either send back an empty response or a default Record Definition.

The service's Create URL endpoint can send back an empty response.

Responding with an empty response

Here is an example implementation if the app wants to respond with an empty response.

Sample code for an empty response
@RequestMapping(value = "/create", method = RequestMethod.POST)
@ResponseStatus(HttpStatus.CREATED)
public ResponseEntity addServiceInstance(@RequestBody ServiceInstance serviceInstance) {
     if (serviceInstance == null) {
         throw new IllegalArgumentException("Empty Service Instance");
     }
     serviceInstanceService.addEntity(serviceInstance);
     return new ResponseEntity<EmptyJsonResponseDTO>(new EmptyJsonResponseDTO(), HttpStatus.OK);
}

Responding with a default record definition

If the app wants to respond with a default record definition, here is an example implementation.

Sample code for a default record definition
@RequestMapping(value = "/create", method = RequestMethod.POST)
@ResponseStatus(HttpStatus.CREATED)
public ResponseEntity addServiceInstance(@RequestBody ServiceInstance serviceInstance) {
   if (serviceInstance == null) {
       throw new IllegalArgumentException("Empty Service Instance");
   }
 
   serviceInstanceService.addEntity(serviceInstance);
   RecordDefinitionDTO recordDefinition = RecordDefinitionDTO.createDefaultDefinition(); //optional.
   return new ResponseEntity<RecordDefinitionDTO>(recordDefinition, HttpStatus.OK);
}

Note: Both AMS and the app should save service instances and be in sync.

Sample Payload
{
  "successful": true,
  "content": null,
  "errorMessage": null
}
Sample JSON payload for a record definition

If responding with a record definition, the record definition must resemble the following. See Record definitions for more information.

{
    "inputParameters": [
        {
            "name": "appcloud_row_correlation_id",
            "dataType": "Text",
            "width": 40,
            "unique": true,
            "required": true,
            "readOnly": null,
            "minimumValue": null,
            "maximumValue": null,
            "possibleValues": null,
            "format": null,
            "resources": null
        }
    ],
    "outputParameters": [
        {
            "name": "appcloud_row_correlation_id",
            "dataType": "Text",
            "width": 40,
            "unique": true,
            "required": true,
            "readOnly": null,
            "minimumValue": null,
            "maximumValue": null,
            "possibleValues": null,
            "format": null,
            "resources": null
        },
        {
            "name": "appcloud_row_status",
            "dataType": "Text",
            "width": 10,
            "unique": null,
            "required": true,
            "readOnly": null,
            "minimumValue": null,
            "maximumValue": null,
            "possibleValues": [
                "success",
                "warning",
                "failure"
            ],
            "format": null,
            "resources": null
        },
        {
            "name": "appcloud_row_errormessage",
            "dataType": "Text",
            "width": 5120,
            "unique": null,
            "required": null,
            "readOnly": null,
            "minimumValue": null,
            "maximumValue": null,
            "possibleValues": null,
            "format": null,
            "resources": null
        }
    ]
}

Learn more

Developing Apps for CX Apps

Service Invocation