Create URL endpoint
The purpose of the Create URL is to create a service instance. This endpoint is called when the app is dragged from the Widget panel into the Email Message Designer (for Template services).
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
{
"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"
}
App's response to the Create URL request
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);
}
Note: Both AMS and the app should save service instances and be in sync.
Sample Payload
{
"successful": true,
"content": null,
"errorMessage": null
}