Record definitions
This topic explains the concept of a record definition within the AMS app framework.
In this topic:
A record definition is the data transfer object (DTO) that describes the fields the CX product should transmit when the service is executed. A user configuring a service must configure their field mappings, so that the app can send the correct data during app execution.
What is a record definition?
The record definition is essentially a set of input and output parameters. For each input, the app will return a specific output. These inputs and outputs defines the configuration for the service as set by the marketer.
For example, when configuring a service, the configuration UI must present the user with options to map product fields to app fields. This way, the app knows what to do with the data. In example, a CITY_ field in the product must be mapped to something like a City variable in the app so that the app can perform some operation with it.
Here's an example of an app service's configuration user interface:
After a user has selected their field mappings and clicked save, here's an example of the response the app sends to AMS, with a record definition.
Example
{
"httpStatusCode": 200,
"payload": null,
"recordDefinition": {
"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
}, {
"name": "MP_COUNTRY",
"dataType": "Text",
"width": 50,
"unique": true,
"required": true,
"readOnly": null,
"minimumValue": null,
"maximumValue": null,
"possibleValues": null,
"format": null,
"resources": null
}, {
"name": "MP_CITY",
"dataType": "Text",
"width": 50,
"unique": true,
"required": true,
"readOnly": null,
"minimumValue": null,
"maximumValue": null,
"possibleValues": null,
"format": null,
"resources": null
}, {
"name": "MP_TEMPERATURE_UNIT",
"dataType": "Text",
"width": 50,
"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
}, {
"name": "MP_TEMPERATURE_MAX",
"dataType": "Float",
"width": 500,
"unique": null,
"required": null,
"readOnly": null,
"minimumValue": null,
"maximumValue": null,
"possibleValues": null,
"format": null,
"resources": null
}, {
"name": "MP_TEMPERATURE_MIN",
"dataType": "Float",
"width": 500,
"unique": null,
"required": null,
"readOnly": null,
"minimumValue": null,
"maximumValue": null,
"possibleValues": null,
"format": null,
"resources": null
}, {
"name": "MP_MAIN",
"dataType": "Text",
"width": 500,
"unique": null,
"required": null,
"readOnly": null,
"minimumValue": null,
"maximumValue": null,
"possibleValues": null,
"format": null,
"resources": null
}, {
"name": "MP_HUMIDITY",
"dataType": "Float",
"width": 500,
"unique": null,
"required": null,
"readOnly": null,
"minimumValue": null,
"maximumValue": null,
"possibleValues": null,
"format": null,
"resources": null
}]
},
"requestId": "save",
"configurationStatus": "CONFIGURED"
}
As you can see, the record definition defines a list of field mappings that the app uses to configure the app for invocation. During invocation, the field mappings will be used to exchange data between the app and product.
What is a valid record definition?
Record definitions consist of required fields, and fields that are defined by the product through the product's Field Metadata Endpoint.
Special Fields
There are special record definition fields (input/output parameters) that must be sent with every service instance configuration:
- appcloud_row_correlation_id
Used to uniquely identify which request is tied to which response. For example, if there are 1000 invocations to the application with a City or Country field and 1000 responses with a Temperature or Humidity field, the appcloud_row_correlation_id allows the product to determine which invocation received which response. Part of the inputParameters.
- appcloud_row_status
- appcloud_row_errormessage
appcloud_row_status and appcloud_row_errormessage are used to allow the application to respond with the status of a invocation. They are part of the outputParameters.
Product Defined Fields
The product's field metadata endpoint returns a valid entity schema during service instance configuration, and defines the accepted inputParameters and outputParameters that can be used in a record definition for a particular service instance. The app can use a subset of these parameters to create the record definition for the service instance. In the example above, record definition fields COUNTRY_, CITY_, and HUMIDITY are all examples of schemas returned by the field metadata endpoint.
When are record definitions used?
You'll see record definitions during 2 interactions in the lifecycle of a service:
- Service creation
- Service save configuration
Service creation
When AMS calls an app service's create URL endpoint to create a service instance, the app can respond in two ways:
-
Respond with an empty response
See an example of the endpoint implementation
When AMS calls an app service's create URL, respond to AMS with 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); } -
Respond with a default record definition
See an example of the endpoint implementation
When AMS calls an app service's create URL, respond to AMS with 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); }
Service save configuration
During the service save configuration process, when AMS call's the service's save configuration URL endpoint, the app should send back the configuration status along with the record definition.