Delivery REST API
The Delivery REST API provides a REST service for performing transaction data delivery integration with other systems. You can use this service to retrieve a rich set of transaction data from remote Journey Manager servers in a secure and efficient manner.
Delivery transaction data includes:
- form XML
- PDF receipt document
- form transaction metadata
- uploaded file attachments (optional)
- Excel XML data extract (optional)
note
It is recommended that the Delivery REST API be used in preference to the earlier SOAP Web Service delivery service, as it enables faster integration development, provides a richer data model, and is more efficient.
Getting started
This section discusses how to get started using the Delivery REST API.
Security
To access the Delivery service REST endpoint, the caller needs to be authenticated using HTTP Basic Authentication. The authenticated user needs a user account on the Journey Manager server, and this account needs to be Active and have access to the Management Console module.
To be authorized to call the service, the user account also needs the Management Console permission Rest Delivery Service API. A standard Journey Manager role REST Delivery is provided which includes this permission; assign the user account this role.
Delivery channel
To make form transactions available for delivery via the REST Delivery service, you need to create a REST Service delivery channel for the form's organization and associate your form with this delivery channel.
An organization can have multiple REST Service delivery channels defined, one for each form, or they can have a single REST Service delivery channel which is configured as the default channel for the Organization. If a delivery channel is configured as the default channel, then any forms that don't have a delivery channel configured will use the default channel.
You should think of REST Service delivery channels as separate queues from which you can get completed transactions.
Endpoint URL
The Delivery REST API endpoint URL is provided as a link in the Delivery Channel configuration screen.
The general format of this URL is:
https://<JM_SERVER>/manager/secure/rest/delivery/v1/<ORG_CODE>/<CHANNEL_NAME>/
Test call
Once you have completed these steps, you can call the Delivery service URL directly using your browser; for example:
https://forms.mycorp.com/manager/secure/rest/delivery/v1/maguire/rest-service/
Once you have answered the basic authentication challenge, you should see a JSON response like the one below. You can use this test call as a 'ping' to check the REST service delivery channel is available.
{
"Ready": [],
"In Progress": [],
"Error": []
}
The above data, returned in a 200 OK response, indicates that there are no submissions ready for delivery, in progress, or in error.
If you receive a 200 OK status with an empty JSON array as shown below, this indicates the REST service delivery channel you are calling has been disabled
in the Journey Manager console.
[]
Performing delivery
The REST Delivery service provide a queue-based delivery integration model which supports High Availability (HA) integration without having to do a lot of state management work with the integration clients. The basic calling pattern is:
- Get a transaction item from the delivery queue.
- Download transaction data; for example, XML, PDF, or file attachments.
- Confirm transaction delivery.
By using a queue based model, you can have multiple HA integration clients running, pulling down transactions from the same delivery queue. If one of the clients fails, then other clients can continue to process transactions.
Call sequence
A sequence diagram for the REST delivery call is shown below.
POST next
The first REST operation to perform is to fetch the next transaction ready for delivery by making a POST request. For example:
POST http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/next/
This operation returns a transaction from the delivery channel queue, and changes its Delivery Status to "In Progress". This call returns a JSON response containing the transaction meta data. An example of this data is shown below.
{
"id": 30,
"trackingCode": "TVKC6R",
"receiptNumber": "FTX-CCA-1",
"submitKey": "c0e695fac9941801fe9cb5572150d21f",
"formCode": "FTX-CCA",
"formName": "Credit Card Application",
"formVersion": "1.0",
"clientCode": "maguire",
"clientName": "Maguire",
"portal": "Maguire",
"fieldWorkerFlag": false,
"testMode": false,
"contactEmailAddress": "[email protected]",
"formStatus": "Completed",
"timeRequest": "2015-02-06T15:41:25+11:00",
"timeSubmission": "2015-02-06T15:41:46+11:00",
"timeLastUserActivity": "2015-02-06T15:42:20+11:00",
"timeFormCompleted": "2015-02-06T15:41:46+11:00",
"ipAddress": "127.0.0.1",
"requestCookie": "JSESSIONID=SpOSp+hJFvw8cdI30CJj-S6j; A983-2928-2398-3419=",
"referer": "http://www.google.com",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64; rv:35.0) Gecko/20100101 Firefox/35.0",
"userAgentBrowser": "Firefox 35",
"userAgentBrowserType": "Firefox",
"userAgentBrowserVersion": "35",
"userAgentDeviceType": "Desktop",
"userAgentOs": "Windows 8.1",
"userAgentOsType": "Windows",
"userAgentOsVersion": "8.1",
"dataValidationStatus": "Error",
"dataValidationMessage": "Payment calculation error. Submitted payment amount $1.00, while calculated payment amount $1260.59.",
"dataExtracts": {
"First Name": "Jeff",
"Last Name": "Johnson",
"Email": "[email protected]"
},
"deliveryStatus": "In Progress",
"deliveryMethod": "REST Service",
"deliveryMessage": "Delivered via 'REST Service' REST Service to rest-delivery from remote address 127.0.0.1",
"deliveryChannel": "REST Service",
"deliveryTime": "2015-02-06T15:43:32+11:00",
"dataDeleted": false,
"xmlURL": "http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/form.xml",
"receiptURL": "http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/receipt.pdf",
"extractURL": "http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/extract.xls",
"attachments": [
{
"id": 15,
"attachmentName": "Pay Slip",
"requiredFlag": false,
"fileName": "Greenbook_Final.pdf",
"fileSize": 1852554,
"fileURL": "http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/15/Greenbook_Final.pdf",
"contentType": "application/pdf",
"timeUploaded": "2015-02-06T17:12:34+11:00"
},
{
"id": 16,
"attachmentName": "Employment Contract",
"requiredFlag": false,
"fileName": "AQR001113Solution Design.docx",
"fileSize": 3297658,
"fileURL": "http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/16/AQR001113Solution Design.docx",
"contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.template",
"timeUploaded": "2015-02-06T17:12:38+11:00"
}
]
}
Once a transaction has been taken from the queue using the POST Next operation, it is no longer available on the queue. The Next operation is the only operation that removes a transaction from the queue.
If a transaction that has been removed from the queue is not confirmed as being processed by a POST Confirmation request within a specified time period, it is returned to the "Ready" status. This time period is configured in the Journey Manager Delivery Channel configuration property REST Retry Delivery Period.
GET data
Using the transaction metadata, the client application now downloads the associated transaction data using the URLs contained in the transaction metadata. Examples of these transaction data URLs are illustrated below.
{
"id": 30,
...
"xmlURL": "http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/form.xml",
"receiptURL": "http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/receipt.pdf",
"extractURL": "http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/extract.xls",
"attachments": [
{
"id": 15,
"attachmentName": "Pay Slip",
"requiredFlag": false,
"fileName": "Greenbook_Final.pdf",
"fileSize": 1852554,
"fileURL": "http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/15/Greenbook_Final.pdf",
"contentType": "application/pdf",
"timeUploaded": "2015-02-06T17:12:34+11:00"
},
{
"id": 16,
"attachmentName": "Employment Contract",
"requiredFlag": false,
"fileName": "AQR001113Solution Design.docx",
"fileSize": 3297658,
"fileURL": "http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/16/AQR001113Solution-Design.docx",
"contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.template",
"timeUploaded": "2015-02-06T17:12:38+11:00"
}
]}
From this transaction metadata, we can see that we need to make the following transaction data download requests:
GET http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/form.xml
GET http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/receipt.pdf
GET http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/extract.xls
GET http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/15/Greenbook_Final.pdf
GET http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/16/AQR001113Solution-Design.docx
Clients that support HTTP compression should set the HTTP header "Accept-Encoding: gzip". The Journey Manager REST service compresses (gzip) all responses that are suitable for compression to improve network performance. Content that is not compressed includes PDF, image, video and audio content.
POST confirmation
Once all the transaction data has been downloaded and safely saved, the client must POST a delivery confirmation JSON message to the server confirming the transaction data has been successfully delivered. The confirmation URL is derived from the delivery channel endpoint URL with the addition of the transaction submission id, which is contained in the top level "id" property of the transaction metadata.
{
"id": 30,
...
}
POST http://localhost:9080/manager/secure/rest/delivery/v1/maguire/rest-service/30/
The JSON confirmation message posted to the server must contain SHA-256 hex encoded hash values of the form XML data and any file attachments. The attachments' IDs are specified in the transaction metadata attachments array. These attachment IDs correspond to the Journey Manager server Attachment IDs.
{
"xmlSHA256": "bd2f85644beffdd101be4137c68269627bbb935d8cd231ab2e5c505eabff72c6",
"attachments": [
{
"id": 15,
"fileSHA256": "3b80d18bc78aad01c50efbad9355a48a6907bdb850b96fc919570209e8cfc4c4"
},
{
"id": 16,
"fileSHA256": "553a417def543b52bcc786f1e2b79dbfd958348c94f689e8d85181aacd039a61"
}
],
"deleteData": true,
"processingStatus": "Your application is being processed"
}
To calculate the SHA-256 hex encoded values there are a variety of open source libraries available. Below is a simple Java function that creates a SHA-256 data hash and hex-encodes the value.
// Hexidecimal characters for encoding.
private static final char[] HEXADECIMAL = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f' };
public static String toSHA256Hash(byte[] bytes) {
if (bytes == null) {
throw new IllegalArgumentException("Null bytes parameter");
}
try {
MessageDigest md = MessageDigest.getInstance("SHA-256");
md.update(bytes);
byte[] binaryData = md.digest();
// Hex encode data SHA-256 digest
char[] buffer = new char[64];
for (int i = 0; i < 32; i++) {
int low = (binaryData[i] & 0x0f);
int high = ((binaryData[i] & 0xf0) >> 4);
buffer[i * 2] = HEXADECIMAL[high];
buffer[i * 2 + 1] = HEXADECIMAL[low];
}
return new String(buffer);
} catch (Exception e) {
throw new RuntimeException(e);
}
}
Client failure recovery
If a client fails while processing a delivery (for example, it has taken a transaction off the queue, which is now in the "In Progress" delivery state but hasn't completed the delivery), then this transaction is not available for other clients to pick up from the queue again. To enable retrying a delivery, the REST Service Delivery Channel supports configuration of a delivery retry timeout, after which any "In Progress" transactions are automatically returned to the "Ready" state so they are available again on the delivery queue.
To set the delivery retry timeout:
- Login to the Journey Manager console.
- Select Forms > Organizations, then select your organization from the list.
- Select the Delivery Channels tab, and select the delivery channel from the list.
- Enter a value for the REST retry Delivery Period, and click Save.
Service operations
The Delivery REST API provides the following operations.