REST Transaction History API
The Transaction History API provides a REST service for querying the OLAP Transaction History table in a secure and efficient manner.
Security
To access the Transaction History REST endpoint the caller needs to be authenticated using HTTP Basic Authentication. The authenticated user will need an user account on the Journey Manager server and this account will need to be active and have access to the Management Console module.
To be authorized to call the service the user account will also need the Management Console permission 'REST Transaction History API'.
You will also need to be either an administrator with global access or be associated with an organization to access its transaction
records.
URL Endpoint
The REST Transaction History API URL endpoint is as follows:
``` https://Service API
This section provides a description all the REST Transaction History API operations including:
GET Transaction History
This API supports a single GET method, but provides a great deal of flexibility through a query builder API. Key features of this API include:
- filter criteria - to select individual transactions or return filtered transaction records
- output formats - to specify JSON or CSV output results
- fetch limits and offsets - enabling you to page through very large sets of transaction history records
- columns filter - to specify only the column values you want to see
URL Format
GET https://<tm server>/manager/secure/rest/transaction-history/v1/
Request Parameters
The table below shows the set of request parameters can be used as additional search criteria. If multiple parameters are specified, all of them are applied to the result set.
| Parameter | Description |
|---|---|
| abandonmentFormStatus | filters on the abandonment form status of an abandoned transaction at abandonment time [ Assigned, Opened, Saved, Submitted ] |
| clientCode | filters on the organization code. Note this column is not indexed and using clientOid will be more efficient. |
| clientOid | filters on the organization client OID primary key |
| dwhPublishStatus |
filters on data warehouse publish status, which can be set via the PUT operation This allows you to retrieve only values that you haven't previously retrieved and marked as published (via PUT) Possible values: null (to retrieve only unpublished values), Completed (to retrieve only previously published values) |
| endDate |
only transactions requested before the specified time_request end date will be included (format: yyyy-MM-dd)For example the follow query parameters � &startDate=2016-01-01&endDate=2016-06-30 �
includes transaction between 1st January 2016 and 30th June 2016.
|
| formCode | filters on the form code. Note this column is not indexed and using formOid will be more efficient. |
| formOid | filters on the form OID primary key |
| formStatus |
filters on the form status of the submission [ Completed, Abandoned ] |
| formVersionNumber | filters on the form version number (e.g. "1.0") of the transaction |
| portalName | filters on the form space (portal) associated with the transaction |
| receiptNumber | filters on the transaction receipt number |
| referer | filters on the transaction referer using a like "%referer%" where clause |
| startDate |
only transactions requested equal to or after the specified time_request end date will be included (format: yyyy-MM-dd).For example the follow query parameters � &startDate=2016-01-01&endDate=2016-06-30 �
includes transaction between 1st January 2016 and 30th June 2016.
|
| submitKey | filters on the transaction submit key (GUID). Please note this column is not indexed. |
| submissionOid | filters on the transaction submission OID primary key. Please note this column is not indexed. |
| trackingCode | filters on the transaction tracking code, also known as the tracking number |
| trackingNumber | filters on the transaction tracking number, also known as the tracking code |
| userAgentDeviceType | filters on the User Agent Device Type [ Desktop, Tablet, Mobile ] |
| userAgentBrowserType | filters on the User Agent Browser Type |
| userAgentBrowserVersion | filters on the User Agent Browser Version |
| userAgentOsType | filters on the User Agent OS Type |
| userAgentOsVersion | filters on the User Agent OS Version |
| fetchLimit |
the maximum number of transactions to return (range 1 - 100K). Will default to 1000 if a valid value was not provided. For example: � &fetchLimit=10000
|
| fetchOffset |
the query fetch offset in rows. Use the fetch offset to page through very large result sets. For example: � &fetchLimit=10000&fetchOffset=20000 � will return the next 10K, after the 20K record offset
|
| format | specify the output format [ JSON, CSV ], if not specified a JSON array will be returned |
| columns | specify the columns to return in a comma separated format, e.g. � &columns=[form_code, form_status, time_request]
|
GET Example 1
The GET example below uses the filter criteria:
-
formCode=FTX-CCA� - filter to include only transactions with the form code "FTX-CCA" -
formStatus=Completed� - filter to include only transactions with the form status of "Completed" -
fetchLimit=1� - filter to only return 1 records
GET https://transact.maguire.com/manager/secure/rest/transaction-history/v1/?formCode=FTX-CCA&formStatus=Completed&fetchLimit=1
200 Response
[
{
"attachment_count": 0,
"attachments_total_size": 0,
"authenticated_flag": false,
"client_code": "maguire",
"client_name": "Maguire",
"client_oid": 1,
"content_length": "19163",
"duration_client_response": 9,
"duration_render": 253,
"duration_total": 671,
"far_data_version": "4.3.0sp2",
"field_worker_flag": false,
"form_code": "FTX-CCA",
"form_name": "Credit Card Application",
"form_oid": 2,
"form_status": "Completed",
"form_version_number": "3.0",
"ip_address": "127.0.0.1",
"pdf_submit_flag": false,
"portal_name": "Maguire",
"receipt_number": "FTX-CCA-2",
"receipt_render_duration": 3497,
"referer": "http://localhost:9080/manager/admin/form/form-search.htm?_wid=1101",
"request_cookie": "JSESSIONID=Swc8R3ul6lbq8JvwCOTHajRD",
"request_key": "618124c328c44eb376dd2f7a32e4081c",
"request_log_count": 1,
"request_url": "http://localhost:9080/maguire/servlet/SmartForm.html",
"revision_number": 5,
"submission_oid": 10,
"submit_key": "1725c033d977b52bea9aef934cd63a58",
"submitted_offline_flag": false,
"task_flag": false,
"time_form_completed": "2016-02-16T12:35+1100",
"time_request": "2016-02-16T12:35+1100",
"time_submission": "2016-02-16T12:35+1100",
"time_to_submit_sec": 17,
"tracking_number": "GD4ZFB",
"transaction_history_oid": 4,
"user_agent": "Mozilla/5.0 (Windows NT 10.0; WOW64; rv:44.0) Gecko/20100101 Firefox/44.0",
"user_agent_browser_type": "Firefox",
"user_agent_browser_version": "44",
"user_agent_device_type": "Desktop",
"user_agent_os_type": "Windows",
"user_agent_os_version": "10"
}
]
GET Example 2
The GET example below uses the filter criteria:
-
formCode=FTX-CCA� - filter to include only transactions with the form code "FTX-CCA" -
fetchLimit=10� - filter to only return 10 records -
format=CSV� - output format CSV -
columns=[form_name,form_version_number,portal_name,submission_oid,tracking_number]� - only include columns [form_name, form_version_number, portal_name, submission_oid, tracking_number]
GET https://transact.maguire.com/manager/secure/rest/transaction-history/v1/?formCode=FTX-CCA&fetchLimit=10&format=CSV&columns=[form_name,form_version_number,portal_name,submission_oid,tracking_number]
200 Response
"form_name","form_version_number","portal_name","submission_oid","tracking_number"
"Credit Card Application","3.0","Maguire",10,"GD4ZFB"
"Credit Card Application","3.0","Maguire",13,"7T5QJF"
"Credit Card Application","3.0","Maguire",27,"RC93C9"
"Credit Card Application","3.0","Maguire",612,"Y3RZZL"
"Credit Card Application","3.0","Maguire",617,"GTS32H"
"Credit Card Application","3.0","Maguire",716,"GC2HNB"
"Credit Card Application","3.0","Maguire",719,"9P8W56"
"Credit Card Application","3.0","Maguire",720,"VGLHKW"
"Credit Card Application","3.0","Maguire",721,"TP2G7P"
"Credit Card Application","3.0","Maguire",722,"DTD65S"
PUT Confirm Published
Confirm multiple transaction history records as published to your data warehouse. Once records have been marked as published,
they can be excluded from future GET requests using the dwhPublishStatus parameter.
PUT Request
PUT /manager/secure/rest/transaction-history/v1/ HTTP/1.1
Host: https://<TM server>/
Content-Type: application/json
{
"transactionHistoryOid": [ <transaction history oid 1>, <transaction history oid 2>, ...]
}
For example:
PUT /manager/secure/rest/transaction-history/v1/ HTTP/1.1
Host: https://transact.maguire.com
Content-Type: application/json
{
"transactionHistoryOid": [ 2303, 2304, 2305, 2305, 2307, 2308, 2309, 2311, 2312, 2313, 2314 ]
}
The number list of transactionHistoroyOid values must be specified and contain at least one value.
Journey Manager will find all transaction history entries with these OIDs and set their data warehouse publish status to "Completed" and the publish time to the current date time.
PUT Example
In this example we will get the list of transaction history entries that have not yet been marked as published (call 1), mark some of them as published (call 2), and again retrieve the now smaller set of unpublished transaction history entries (call 3).
Finally, we will get the list of previously published entries.
Call 1: GET request prior to PUT
GET https://transact.maguire.com/manager/secure/rest/transaction-history/v1/?dwhPublishFlag=null
Call 1: 200 Response
The result of this call has been heavily edited for brevity. For our purposes, it is enough to show which records are returned.
``` [ { "receipt_number": "FTX-CCA-2", "submission_oid": 10, "transaction_history_oid": 1, ... }, { "receipt_number": "COA-11", "submission_oid": 11, "transaction_history_oid": 2, ... }, { "receipt_number": "NN1434-6", "submission_oid": 15, "transaction_history_oid": 3, ... }, { "receipt_number": "NN1434-7", "submission_oid": 17, "transaction_history_oid": 4, ... } ]```Call 2: PUT to mark records 1 and 2 as published
PUT /manager/secure/rest/transaction-history/v1/ HTTP/1.1
Host: https://transact.maguire.com
Content-Type: application/json
{
"transactionHistoryOid": [1, 2]
}
Call 2: 200 Response
{
"result": "success"
}
Call 3: Same GET request after PUT
GET https://transact.maguire.com/manager/secure/rest/transaction-history/v1/?dwhPublishFlag=null
Call 3: 200 Response
The result of this call has been heavily edited for brevity. For our purposes, it is enough to show which records are returned.
Note how records that we marked as published in the PUT call are not returned because of the dwhPublishFlag=null URL parameter.
You can always get the full list of records by omitting the dwhPublishFlag URL parameter altogether.
Call 4: GET request for previously published records
GET https://transact.maguire.com/manager/secure/rest/transaction-history/v1/?dwhPublishFlag=Completed
Call 4: 200 Response
The result of this call has been heavily edited for brevity. For our purposes, it is enough to show which records are returned.
Note how only records that we marked as published in the PUT call are returned because of the dwhPublishFlag=Completed URL parameter. These records also have the publish status and date set.