H Data Sync
This appendix describes the data sync functionality that provides the ability to share customer and transaction information from ORCE to any third-party application. When enabled, any changes made in CE to customer data (added/updated/deleted/merged) either through the UI, APIs, or the batch import process, or to any transactional data imported are stored in a pending queue. A scheduled job will process this pending data by moving it into a progress queue, converting the data to a REST API message and sending a POST request to a configured url.
Configuration
To configure the data sync functionality, log into CE and navigate to the Data Sync category in System Configuration.
|
DataSyncEnabled |
To enable the data sync functionality set this to true or Yes, otherwise set to false/No. |
|
DataSyncApiUrl |
The url of the REST endpoint where the data is to be sent. |
|
DataSyncTokenUrl |
The url of an OAuth2 token provider for authentication to the Api. |
|
DataSyncCredentialMapName |
The name for the credential store map, default is set to ce_credentials. |
|
DataSyncCredentialKeyName |
The key name for the data sync client Id and secret credentials to be stored in the credential map. |
Uploading the client ID and secret credentials to the credential store can be done directly using the enterprise manager or using the CE user interface as follows:
-
Log into the CE application and navigate to Job Management > Job Search.
-
Click Create Schedule Job; this will open the Job configuration wizard.
-
In the task configuration step, select the Data Sync Task and add it to the task list.
-
In the data sync task panel, enter the Client ID and Secret and click Save to store the settings in the credential map. The Save button is enabled when both the Client ID and the Secret have been entered.
Figure H-1 Data Sync Panel
Click Send Sample Message in order to send a test message to the third-party application configured in the DataSyncApiUrl using the saved credentials. It is recommended to test the configuration and connectivity using this feature before setting up the job.
Note:
The ability to save the client ID and secret credentials is available to users with the system admin role. The send sample message is visible to users with system admin or system config and job admin roles.
Note:
The credentials will only be saved if the CredentialAccessPermission is set to read, write and update in the enterprise manager security policy.
Pending Queues
If the data sync functionality is enabled, performing the following web service actions triggers inserts into the DATA_SYNC_CUST_PENDING_QUEUE table. The OBJ_NAME will be set to Customer and the UNIQUE_ID will be the customer ID of the customer being created, updated, or deleted. In the case of a new or updated record, the Customer object will be stored in the JSON_OBJECT field. If the action results in a customer record being deleted, the JSON_Object field will be null.
The following Web Service methods trigger updates to the pending queue:
Table H-1 Web Services Methods
| API Service | Method | Action | JSON Object |
|---|---|---|---|
|
Card |
resetCardExpirationDate |
UPDATE |
Customer |
|
Card |
updateCardToCustomerAssociations |
UPDATE |
Customer |
|
Customer |
addOrDeleteCustomerFranchisees |
UPDATE |
Customer |
|
Customer |
addOrUpdateCustomer |
CREATE UPDATE |
Customer |
|
Customer |
addOrUpdateCustomerNote |
UPDATE |
Customer |
|
Customer |
associateCardToCustomer |
UPDATE |
Customer |
|
Customer |
deleteCustomer |
DELETE |
Null |
|
Customer |
mergeCustomers |
DELETE CREATE |
Null Customer |
|
Customer |
updateAssociateAssignment |
UPDATE |
Customer |
|
PosLog |
postTransaction |
UPDATE |
Customer |
|
Segment |
addCustomerToSegment |
UPDATE |
Customer |
|
Segment |
removeCustomerFromSegment |
UPDATE |
Customer |
|
SVC Transaction |
activateInstrument |
UPDATE |
Customer |
|
SVC Transaction |
deactivateInstrument |
UPDATE |
Customer |
|
SVC Transaction |
generateCard |
UPDATE |
Customer |
|
SVC Transaction |
generateMultipleCards |
UPDATE |
Customer |
|
SVC Transaction |
replace |
UPDATE |
Customer |
|
SVC Transaction |
unblockTenderAccount |
UPDATE |
Customer |
In the case of mergeCustomers, the customer IDs of the customers merged together will be recorded with the DELETE_FLAG set, and the new merged customer will be recorded with the CREATE_FLAG set.On deletion of a customer (either via the web services, delete customer job, user interface or merge job) all records related to the customer in the pending and in progress queues will also be deleted. The following batch import types trigger updates to the customer pending queue:
Table H-2 Batch Import Types
| Entity | Request Type | Action | JSON Object |
|---|---|---|---|
|
Customer |
Customer (Action=Add) |
CREATE |
Customer |
|
Customer |
Customer (Action=AddorUpdate) |
CREATE UPDATE |
Customer Customer |
|
Customer |
Customer (Action=Delete) |
DELETE |
Null |
|
Customer |
Customer (Action=Merge), existing customers are flagged as deleted, new merged customer is created. |
DELETE CREATE |
Null Customer |
|
PosLogType |
Transaction |
UPDATE |
Customer |
|
Stored Value |
ActivateInstrumentRequest |
UPDATE |
Customer |
|
Stored Value |
DeactivateInstrumentRequest |
UPDATE |
Customer |
The following scheduled tasks trigger updates to the customer pending queue:
-
Delete Inactive Segment
-
Unstratified Segment
-
Stratified Segment
-
Delete Segments
-
Dynamic Promotion
-
Franchisee Assignment
-
Generate Offer
The following web service methods result in an insert into the transaction pending queue DATA_SYNC_TRN_PENDING_QUEUE. The OBJ_NAME will be set to Transaction and the unique_ID will be the retail transaction id of the posted transaction.
Table H-3 Web Service Method
| API Service | Method | Action | JSON Object |
|---|---|---|---|
|
PosLog |
postTransaction |
CREATE |
Transaction |
The following Batch Import files will trigger updates to the customer pending queue:
Table H-4 Batch Import File
| Entity | Request Type | Action | JSON Object |
|---|---|---|---|
|
PosLogType |
Transaction |
CREATE |
Customer |
Data Sync Job
The data sync job checks and processes any items in the progress queue first, then moves records in batches from the pending queues into the progress queue. Once the transfer of each batch is complete, the records will be removed from the respective pending queue.
A HTTP POST request is created for each record in the progress queue and sent to the external application using the URL configured in the DataSyncApiUrl configuration setting. The message are formatted as follows..
Table H-5 Data Sync Job
| Object Type | Method | Type | Action | Payload |
|---|---|---|---|---|
|
Customer |
CREATE |
CUSTOMER |
CUSTOMERCRE |
CustomerResponseType |
|
Custome |
UPDATE |
CUSTOMER |
CUSTOMERMOD |
CustomerResponseType |
|
Customer |
DELETE |
CUSTOMER |
CUSTOMERDEL |
customerID |
|
Transaction |
CREATE |
POSTRN |
POSTRNCRE |
TransactionType |
For a description of the CustomerResponseType class, see Introduction
For a description of the TransactionType class, see Poslog Services, Version 3.2.
If a response code of 200 is received from each request, it will be regarded as the message has been sent and received successfully. If any other response occurs, the data sync job will fail.
When implementing a REST service to receive the requests generated by the data sync job, the following must be considered:
-
The Request will be a POST method with CONTENT-TYPE: application/json
-
Authentication protocol: Oauth 2.0
-
SSL/TSL protocol: TLS v1.2
Request Body Examples
An example request from the Send Sample Message feature:
{
"messages": [
{
"action": "CUSTOMERCRE",
"payload": "Test message",
"type": "CUSTOMER",
"uniqueId": "0"
}
]
}
The "payload" field will either hold Customer or Transaction Data dependant on the "type" field (type = POSTRN will send a Transaction payload, type=CUSTOMER will send a Customer payload).
An example of a POSTRN type, transaction request body:
{
"messages": [
{
"action": "CUSTOMERMOD",
"payload": "{\"customerID\":\"2142\",\"signupDate\":\"2020-12-02\",\"retailStoreID\":\"99999\",\"firstPurchaseDate\":null,\"lastPurchaseDate\":null,\"validation\":{\"validFlag\":\"true\"},\"orgName\":null,\"custOrgTypcode\":null,\"employeeID\":null,\"businessName\":null,\"customerClass\":\"SYSTEM CLASS\",\"source\":\"Relate\",\"prospect\":false,\"customerOwnerID\":null,\"householdKey\":\"\",\"customerNumber\":null,\"customerReference\":null,\"lastUpdateInfo\":null,\"affiliation\":[{\"retailStoreID\":null}],\"entityInformation\":{\"individual\":{\"suffix\":null,\"sortingName\":null,\"nickName\":null,\"salutation\":null,\"name\":{\"name\":[{\"location\":\"FIRST\",\"value\":\"Vzxcv\"},{\"location\":\"MIDDLE\",\"value\":null},{\"location\":\"LAST\",\"value\":null}]},\"contactInformation\":{\"address\":[],\"telephone\":[],\"email\":[]},\"personalSummary\":{\"genderType\":null,\"birthDate\":null,\"anniversary\":null,\"maritalStatusCode\":null,\"ethnicity\":null,\"rent\":false,\"languageCode\":\"en\"},\"socioEconomicProfile\":{\"annualIncomeAmount\":null,\"netWorth\":null,\"highestEducationalLevelName\":\"\"},\"lifetimeActivitySummary\":{\"totalReturnsAmount\":\"0\",\"totalSalesAmount\":\"0\",\"totalTransactionCount\":\"0\",\"totalItemsSoldCount\":\"0\",\"totalItemsReturnedCount\":\"0\"},\"yearToDateActivitySummary\":{\"yearToDateReturnsAmount\":\"0\",\"yearToDateSalesAmount\":\"0\",\"yearToDateTransactionCount\":\"0\",\"yearToDateItemsSoldCount\":\"0\",\"yearToDateItemsReturnedCount\":\"0\"}}},\"alternateKey\":[],\"customAttribute\":[],\"customerNotes\":{\"customerNote\":[]},\"eligiblePromotionDeals\":{\"promotionDealId\":[]},\"customerSegments\":{\"segment\":[]},\"customerCards\":{\"instrument\":[]},\"associateAssignments\":null,\"personalPreferences\":{\"contactPreference\":[{\"contactType\":\"MAIL\",\"permission\":\"true\"},{\"contactType\":\"PHONE\",\"permission\":\"true\"},{\"contactType\":\"FAX\",\"permission\":\"true\"},{\"contactType\":\"EMAIL\",\"permission\":\"true\"}]},\"franchisees\":{\"franchisee\":[{\"franchiseeId\":2,\"franchiseeName\":\"<FRANCHISEE NAME> \"},{\"franchiseeId\":8,\"franchiseeName\":\"<FRANCHISEE NAME>\"},{\"franchiseeId\":6,\"franchiseeName\":\"<FRANCHISEE NAME>\"},{\"franchiseeId\":1,\"franchiseeName\":\"<FRANCHISEE NAME>\"}]}}",
"type": "CUSTOMER",
"uniqueId": "26764466"
}
]
}
An example of a CUSTOMER type request body:
{
"messages": [
{
"action": "POSTRNCRE",
"payload": "{\"retailTransactionId\":\"99901000022017110710000100\",\"organizationId\":1,\"beginDatetime\":\"2017-11-07T12:54:22+0530\",\"businessDate\":\"2017-11-07\",\"originalBusinessDate\":\"2017-11-07\",\"customerId\":\"2147\",\"voidFlag\":false,\"customerKey\":null,\"endDatetime\":\"2017-11-07T12:54:49+0530\",\"currencyTypeCode\":\"USD\",\"orgCurrencyTypeCode\":\"USD\",\"currencyExchangeRate\":1,\"keyedOfflineFlag\":false,\"notes\":null,\"operatorId\":\"101\",\"customerOrganizationId\":null,\"customerOrganizationKey\":null,\"postedFlag\":false,\"retailLocationId\":\"99901\",\"nonPhysicalItemTotal\":0,\"subtotal\":1325.00,\"taxTotal\":79.50,\"total\":77.50,\"markdownTotal\":0,\"costOfGoodsSoldTotal\":77.00,\"transactionReasonCode\":null,\"transactionSequence\":10000100,\"transactionStatusCode\":\"DELIVERED\",\"transactionTypeCode\":\"TRANSACTION\",\"workstationId\":2,\"linkedTransactionId\":null,\"createDate\":\"2020-12-02\",\"createUserId\":null,\"updateDate\":null,\"updateUserId\":null,\"lineItems\":[{\"lineItemSequence\":1,\"beginDateTimestamp\":\"2017-11-07T12:54:44+0530\",\"endDateTimestamp\":\"2017-11-07T12:54:44+0530\",\"lineItemStatusCode\":null,\"lineItemTLogSequence\":1,\"lineItemTypeCode\":\"Sale\",\"notes\":null,\"voidFlag\":false,\"voidLineItemReasonCode\":null,\"custId\":\"2147\",\"createDate\":null,\"createUserId\":null,\"updateDate\":null,\"updateUserId\":null,\"lineItemModifiers\":[{\"lineItemSequence\":1,\"lineItemModifierSequence\":0,\"voidFlag\":false,\"custId\":\"2147\",\"createDate\":null,\"createUserId\":null,\"updateDate\":null,\"updateUserId\":null}]},{\"lineItemSequence\":2,\"beginDateTimestamp\":\"2017-11-07T12:54:47+0530\",\"endDateTimestamp\":\"2017-11-07T12:54:48+0530\",\"lineItemStatusCode\":null,\"lineItemTLogSequence\":2,\"lineItemTypeCode\":\"Tender\",\"notes\":null,\"voidFlag\":false,\"voidLineItemReasonCode\":null,\"custId\":\"2147\",\"createDate\":null,\"createUserId\":null,\"updateDate\":null,\"updateUserId\":null,\"lineItemModifiers\":[]},{\"lineItemSequence\":3,\"beginDateTimestamp\":\"2017-11-07T12:54:44+0530\",\"endDateTimestamp\":\"2017-11-07T12:54:44+0530\",\"lineItemStatusCode\":null,\"lineItemTLogSequence\":3,\"lineItemTypeCode\":\"Tax\",\"notes\":null,\"voidFlag\":false,\"voidLineItemReasonCode\":null,\"custId\":\"2147\",\"createDate\":null,\"createUserId\":null,\"updateDate\":null,\"updateUserId\":null,\"lineItemModifiers\":[]}],\"transactionProperties\":[]}",
"type": "POSTRN",
"uniqueId": "26764581"
}
]
}