Administration

The following services are included in this functional area:

Data Privacy

The following services are included in this functional area:

Data Privacy Download Service

Get Personally Identifiable Information

This section describes the Data Privacy Access service for Merchandising and Sales Audit.

Business Overview

This query service provides access to data stored in Merchandising and Sales Audit that contains personally identifiable information.

Service Type

GET

ReST URL
https://rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace>/RetailAppsDataPrivServicesRESTApp/rest/privatedata/<entityName>?customer_id={entityName}::{entityType}::{entityId}::{fullName}:: {phone}::{email}
Accept

  • application/json

  • application/xml

Query Parameters

  • customer_id (required): The customer ID string containing the parameters to be used in looking up data. The format of this string is as follows:

    • {entity name}::{entity type}::{entity id}::{full name}::{phone}::{email}

Path Parameters
Parameter Description

Entity Name

The query group type for which data is to be retrieved.

The available group types for Merchandising are:

  • BUYER (Buyer)

  • MERCHANT (Merchant)

  • STORE (Store)

  • WAREHOUSE (Warehouse)

  • SUPPLIER (Supplier)

  • PARTNER (Partner)

  • OUTLOC (Outside Location)

  • ORDER CUSTOMER (Merchandising Customer)

The available group types for Sales Audit are:

  • EMPLOYEE (Employee)

  • CUSTOMER (Customer)

Note: The supported entity names can also be retrieved by accessing the below URL either in the browser or through a REST client like Postman, cURL and so on: 

https://rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace/RetailAppsDataPrivServicesRESTApp/rest/privatedata/config/access

Sample Response:

{
  "types": [
    "PARTNER",
    "OUTLOC",
    "WAREHOUSE",
    "getPersonalInfo",
    "EMPLOYEE",
    "raf",
    "STORE",
    "BUYER",
    "CUSTOMER",
    "SUPPLIER",
    "MERCHANT",
    "ORDER_CUSTOMER"
  ]
}

In the above response, getPersonalInfo and raf are only for internal consumption and not to be used. The ones that are permitted are the other entity names.

Entity Type

In case of Merchandising, this parameter is used if the entity name is PARTNER or OUTLOC. The value here should indicate the type of partner or outside location being queried. Valid values for this input can be found on the Codes table for each type:

  • Partner Types = PTNR

  • Outside Location Types = LOCT

In case of Sales Audit, this parameter is used if the entity name is CUSTOMER. The value here should indicate the type of customer being queried. Valid values for this input can be found on the Codes table where code type is CIDT. (Customer Types)

Entity ID

The ID of the entity being queried.

For example, the supplier ID (in Merchandising) or employee ID (in Sales Audit).

Full Name

The full name to be searched for the selected entity.

Phone

The phone number to be searched for the selected entity.

Email

The email to be searched for the selected entity.
Default Response

The response will return all instances of the data being searched that occur in the requested entity. For example, if the entity requested was BUYER, all instances where the buyer, name, and phone match the data sent will be returned. If any of these parameters are not sent (for example, email), then it will not be used as part of the search. The following data is included in the response:

Parameter Description

Entity Name

For Merchandising:

  • BUYER (Buyer)

  • MERCHANT (Merchant)

  • STORE (Store)

  • WAREHOUSE (Warehouse)

  • SUPPLIER (Supplier)

  • PARTNER (Partner)

  • OUTLOC (Outside Location)

  • ORDER CUSTOMER (Merchandising Customer)

For Sales Audit:

  • EMPLOYEE (Employee)

  • CUSTOMER (Customer)

Entity Type

In the case of Merchandising, if the entity name is PARTNER or OUTLOC, the value here indicates the type of partner or outside location. Valid values can be found on the Codes table for each type:

  • Partner Types = PTNR

  • Outside Location Types = LOCT

For other entity types, this will be null.

In the case of Sales Audit, if the entity name is CUSTOMER, the value here indicates the type of customer. Valid values can be found on the Codes table where code type is CIDT. For other entity types, this will be null.

Entity ID

The ID of the entity where the data was found.

Full Name

The name associated with the entity.

Phone

The phone number associated with the entity.

Fax

The fax number associated with the entity.

Telex

The telex number associated with the entity.

Pager

The pager number associated with the entity.

Email

The email address associated with the entity.
Sample Response
{
  "Buyer Information": {
    "list": [],
      "Get Buyer Information": {
        "list": [      
          [
            {
              "ENTITY_NAME": "BUYER",
              "ENTITY_TYPE": "null",
              "ENTITY_ID": "1002",
              "FULL_NAME": "Matt Wilsman",
              "PHONE": "6125251034",
              "FAX": "6125259800",
              "TELEX": "null",
              "PAGER": "null",
              "EMAIL": "test.abd.com"
            }
          ]
        ]
      }
    }
  }
}
Response Codes and Error Messages

  • 200 - Success

  • 400 - Bad Request - for the following situations:

    • Customer ID does not match the required format.

    • Invalid input type

    • Missing customer ID

    • Invalid JSON Format

  • 500 - Internal Server Errors - for all other types of errors (for example, configuration errors, SQL errors, and so on).

Success Payloads

  • When Accept=application/json, this API will return data in JSON format

  • When Accept=application/xml, this API will return data formatted as an HTML page

The below table gives a sample of URLs for invoking the GET service for the different entity names.

Note:

  • The entity ID should be replaced with the appropriate valid ID based on the customer environment.

  • The sample response formats shown here are with using a REST client like PostMan and with the Header Accept value set to application/json

Entity Name Reference URL Sample Response

BUYER

 
https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace/RetailAppsDataPrivServicesRESTApp/rest/privatedata/BUYER?customer_id=BUYER::3933::::
 
{
  "Buyer Information": {
   "list": [],
   "Get Buyer Information": {
     "list": [
          [
            {
             "ENTITY_NAME": "BUYER",
             "ENTITY_TYPE": "null",
             "ENTITY_ID": "3933",
             "FULL_NAME": "RMS_Buyer",
             "PHONE": "999-888-7777",
             "FAX": "666-555-4444",
             "TELEX": "null",
             "PAGER": "null",
             "EMAIL": "null"
            }
          ]
         ]
      }
    }
}

MERCHANT

 https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace /RetailAppsDataPrivServicesRESTApp/rest/privatedata/MERCHANT?customer_id=MERCHANT::2114:::: 
{
  "Merchant Information": {
   "list": [],
   "Get Merchant Information": {
     "list": [
          [
            {
              "ENTITY_NAME": "MERCHANT",
              "ENTITY_TYPE": "null",
              "ENTITY_ID": "2114",
              "FULL_NAME": "DC Merchandiser_2114",
              "PHONE": "999-666-5555",
              "FAX": "999-888-2222",
              "TELEX": "null",
              "PAGER": "null",
              "EMAIL": "null"
            }
          ]
         ]
    }
  }
}

STORE

 
https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace/RetailAppsDataPrivServicesRESTApp/rest/privatedata/STORE?customer_id=STORE::7143876752::::::
 
{
  "Store Information": {
    "list": [],
    "Get Store Information": {
      "list": [
        [
          {
            "ENTITY_NAME": "STORE",
            "ENTITY_TYPE": "null",
            "ENTITY_ID": "7143876752",
            "FULL_NAME": "Scott",
            "PHONE": "763-888-4455",
            "FAX": "1-763-959-4477",
            "TELEX": "null",
            "PAGER": "null",
            "EMAIL": "Oracle@Automail.com"
          },
          {
            "ENTITY_NAME": "ADDRESS",
            "ENTITY_TYPE": "null",
            "ENTITY_ID": "50003",
            "FULL_NAME": "Oracle",
            "PHONE": "111",
            "FAX": "111",
            "TELEX": "null",
            "PAGER": "null",
            "EMAIL": "John.Doe@Oracle.com"
          },
          {
            "ENTITY_NAME": "ADDRESS",
            "ENTITY_TYPE": "null",
            "ENTITY_ID": "50004",
            "FULL_NAME": "Oracle",
            "PHONE": "111",
            "FAX": "111",
            "TELEX": "null",
            "PAGER": "null",
            "EMAIL": "John.Doe@Oracle.com"
          }
        ]
      ]
    }
  }
}

WAREHOUSE

 
https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace /RetailAppsDataPrivServicesRESTApp/rest/privatedata/WAREHOUSE?customer_id=WAREHOUSE::9993::
 
{
  "Warehouse Information": {
    "list": [],
    "Get Warehouse Information": {
      "list": [
        [
          {
            "ENTITY_NAME": "WAREHOUSE",
            "ENTITY_TYPE": "null",
            "ENTITY_ID": "9993",
            "FULL_NAME": "null",
            "PHONE": "null",
            "FAX": "null",
            "TELEX": "null",
            "PAGER": "null",
            "EMAIL": "Eric@manhattan.com"
          }
        ]
      ]
    }
  }
}

SUPPLIER

 
https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace/RetailAppsDataPrivServicesRESTApp/rest/privatedata/SUPPLIER?customer_id=SUPPLIER::2001::::::
 
{
  "Supplier Information": {
   "list": [],
   "Get Supplier Information": {
     "list": [
          [
            {
              "ENTITY_NAME": "SUPPLIER",
              "ENTITY_TYPE": "null",
              "ENTITY_ID": "2001",
              "FULL_NAME": "James Moriarty",
              "PHONE": "6128059160",
              "FAX": "null",
              "TELEX": "null",
              "PAGER": "null",
              "EMAIL": "null"
            },
            {
              "ENTITY_NAME": "ADDRESS",
              "ENTITY_TYPE": "null",
              "ENTITY_ID": "105001",
              "FULL_NAME": "null",
              "PHONE": "null",
              "FAX": "null",
              "TELEX": "null",
              "PAGER": "null",
              "EMAIL": "null"
            },
            {
              "ENTITY_NAME": "ADDRESS",
              "ENTITY_TYPE": "null",
              "ENTITY_ID": "105002",
              "FULL_NAME": "null",
              "PHONE": "null",
              "FAX": "null",
              "TELEX": "null",
              "PAGER": "null",
              "EMAIL": "null"
            },
            {
              "ENTITY_NAME": "ADDRESS",
              "ENTITY_TYPE": "null",
              "ENTITY_ID": "105003",
              "FULL_NAME": "null",
              "PHONE": "null",
              "FAX": "null",
              "TELEX": "null",
              "PAGER": "null",
              "EMAIL": "null"
            },
            {
              "ENTITY_NAME": "ADDRESS",
              "ENTITY_TYPE": "null",
              "ENTITY_ID": "105004",
              "FULL_NAME": "null",
              "PHONE": "null",
              "FAX": "null",
              "TELEX": "null",
              "PAGER": "null",
              "EMAIL": "null"
            }
          ]
        ]
     }
  }
}

PARTNER

 
https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace /RetailAppsDataPrivServicesRESTApp/rest/privatedata/PARTNER?customer_id=PARTNER::::464694358::::::
 
{
  "Partner Information": {
    "list": [],
    "Get Partner Information": {
      "list": [
        [
          {
            "ENTITY_NAME": "PARTNER",
            "ENTITY_TYPE": "BK",
            "ENTITY_ID": "464694358",
            "FULL_NAME": "XXXXX",
            "PHONE": "XXXXX",
            "FAX": "null",
            "TELEX": "null",
            "PAGER": "null",
            "EMAIL": "null"
          },
          {
            "ENTITY_NAME": "ADDRESS",
            "ENTITY_TYPE": "null",
            "ENTITY_ID": "270001",
            "FULL_NAME": "B",
            "PHONE": "123-654-8888",
            "FAX": "123-654-9999",
            "TELEX": "null",
            "PAGER": "null",
            "EMAIL": "oracle@automail.com"
          },
          {
            "ENTITY_NAME": "ADDRESS",
            "ENTITY_TYPE": "null",
            "ENTITY_ID": "270002",
            "FULL_NAME": "P",
            "PHONE": "123-654-8888",
            "FAX": "123-654-9999",
            "TELEX": "null",
            "PAGER": "null",
            "EMAIL": "oracle@automail.com"
          },
          {
            "ENTITY_NAME": "ADDRESS",
            "ENTITY_TYPE": "null",
            "ENTITY_ID": "270003",
            "FULL_NAME": "null",
            "PHONE": "null",
            "FAX": "null",
            "TELEX": "null",
            "PAGER": "null",
            "EMAIL": "null"
          }
        ]
      ]
    }
  }
}

OUTLOC

 
https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace /RetailAppsDataPrivServicesRESTApp/rest/privatedata/OUTLOC?customer_id=OUTLOC::::97285::::::
 
{
  "Out Loc Information": {
    "list": [],
    "Get OutLoc Information": {
      "list": [
        [
          {
            "ENTITY_NAME": "OUTLOC",
            "ENTITY_TYPE": "RL",
            "ENTITY_ID": "97285",
            "FULL_NAME": "Alexandar Hamilton",
            "PHONE": "56565-22-22",
            "FAX": "56565-22-22",
            "TELEX": "56565-22-22",
            "PAGER": "null",
            "EMAIL": "alloy.automation@oracle.com"
          }
        ]
      ]
    }
  }
}

ORDER_CUSTOMER

 
https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace /RetailAppsDataPrivServicesRESTApp/rest/privatedata/ORDER_CUSTOMER?customer_id=ORDER_CUSTOMER::90003::::
 
{
  "Order Customer Information": {
    "list": [],
    "Order Customer Information": {
      "list": [
        [
          {
            "ENTITY_NAME": "ORDER_CUSTOMER",
            "ENTITY_TYPE": "null",
            "ENTITY_ID": "90003",
            "FULL_NAME": "John Scott",
            "PHONE": "1800800800",
            "FAX": "null",
            "TELEX": "null",
            "PAGER": "null",
            "EMAIL": "null"
          }
        ]
      ]
    }
  }
}

EMPLOYEE

 
 https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace /RetailAppsDataPrivServicesRESTApp/rest/privatedata/EMPLOYEE?customer_id=EMPLOYEE::SAMMYSMITH::::::
 
{
  "Employeee Information": {
    "list": [],
    "Employeee Information": {
      "list": [
        [
          {
            "ENTITY_NAME": "EMPLOYEE",
            "ENTITY_TYPE": "null",
            "ENTITY_ID": "SAMMYSMITH",
            "FULL_NAME": "PS",
            "PHONE": "990-888-8989",
            "FAX": "null",
            "TELEX": "null",
            "PAGER": "null",
            "EMAIL": "PS@GMAIL.COM"
          }
        ]
      ]
    }
  }
}

CUSTOMER

 
https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace/RetailAppsDataPrivServicesRESTApp/rest/privatedata/CUSTOMER?customer_id=CUSTOMER::CUSTID::1234567::::::
 
{
  "Customer Information": {
    "list": [],
    "Customer Information": {
      "list": [
        [
          {
            "ENTITY_NAME": "CUSTOMER",
            "ENTITY_TYPE": "CUSTID",
            "ENTITY_ID": "1234567",
            "FULL_NAME": "alice",
            "PHONE": "876543",
            "FAX": "null",
            "TELEX": "null",
            "PAGER": "null",
            "EMAIL": "lice@gmail.com"
          }
        ]
      ]
    }
  }
}

Data Privacy Upload Service

Delete Personally Identifiable Information

This section describes the Data Privacy Forget service for Merchandising and Sales Audit.

Business Overview

This service supports updating personal information stored in Merchandising and Sales Audit. When the service is invoked with mask strings as inputs, it overwrites the fields with mask strings, which effectively removes the personal information from the system.

Service Type

DELETE

ReST URL
https://<host:port>/RetailAppsDataPrivServicesRESTApp/rest/privatedata/<updateEntityName>?customer_id={entityName}::{entityType}::{entityId}::{fullName}:: {phone}::{fax}::{telex}::{pager}::{email}::{addr1}::{addr2}::{addr3}::{county}::{city}::{state}::{countryId}::{postalCode}
Accept

  • application/json

  • application/xml

Query Parameters

  • customer_id (required): The customer ID string containing the parameters to be used in updating data. The format of this string is as follows:

    • {entityName}::{entityType}::{entityId}::{fullName}::{phone}::{fax}::{telex}::{pager}::{email}::{addr1}::{addr2}::{addr3}::{county}::{city}::{state}::{countryId}::{postalCode}

Path Parameters
Parameter Description

Update Entity Name

The update group type for which data is to be updated.

The available group types for Merchandising are:

  • updateAddressInformation

  • updateOrderCustomerInformation

  • updateSupplierInformation

  • updateOutLocInformation

  • updateBuyerInformation

  • updateMerchantInformation

  • updateStoreInformation

  • updateWarehouseInformation

  • updatePartnerInformation

The available group types for Sales Audit are:

  • updateEmployeeInformation

  • updateCustomerInformation

Note: To view the supported forget PII data types, the below URL can be invoked with a GET request 

https://rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace/RetailAppsDataPrivServicesRESTApp/rest/privatedata/config/forget

Entity Name

(required)

The group type for which data is to be updated.

The available group types for Merchandising are:

  • BUYER (Buyer)

  • MERCHANT (Merchant)

  • STORE (Store)

  • WAREHOUSE (Warehouse)

  • SUPPLIER (Supplier)

  • PARTNER (Partner)

  • OUTLOC (Outside Location)

  • ORDER CUSTOMER (Merchandising Customer)

The available group types for Sales Audit are:

  • EMPLOYEE (Employee)

  • CUSTOMER (Customer)

Entity Type

In case of Merchandising, this parameter is used if the entity name is PARTNER or OUTLOC. The value here should indicate the type of partner or outside location. Valid values for this input can be found on the Codes table for each type:

  • Partner Types = PTNR

  • Outside Location Types = LOCT

In case of Sales Audit, this parameter is used if the entity name is CUSTOMER. The value here should indicate the type of customer. Valid values for this input can be found on the Codes table where code type is CIDT (Customer Types).

Entity ID

(required)

The ID of the entity to be updated.

For example, the supplier ID (in Merchandising) or employee ID (in Sales Audit).

Full Name

The value to update the full name with. If the value is null and this is a required field in the entity, XXXXX will be used.

Phone

The value to update the phone number with. If the value is null and this is a required field in the entity, XXXXX will be used.

Fax

The value to update the fax number with.

Telex

The value to update the telex number with.

Pager

The value to update the pager number with.

Email

The value to update the email address with.

Addr1

The value to update the address 1 with.

Addr2

The value to update the address 2 with.

Addr3

The value to update the address 3 with.

County

The value to update the county with.

City

The value to update the city with.

State

The value to update the state with.

Country

The value to update the country with.

Postal Code

The value to update the postal code with.
Default Response

This service only returns a response code to signify if the request is successful or not. If no record is updated, the service returns an error.

Response Codes and Error Messages

  • 200 - Success

  • 400 - Bad Request - for the following situations:

    • Customer ID does not match the required format

    • Invalid input type

    • Missing customer ID

    • Invalid JSON Format

  • 500 - Internal Server Errors - for all other types of errors (for example, configuration errors, SQL errors, and so on).

Success Payloads

N/A

The below section depicts the sample URL for Delete API for PII (Personally Identifiable Information) for the various entity names.

Entity Name Reference URL

BUYER

https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace/RetailAppsDataPrivServicesRESTApp/rest/privatedata/updateBuyerInformation?customer_id=BUYER::3933::::::

SUPPLIER

https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace/RetailAppsDataPrivServicesRESTApp/rest/privatedata/updateSupplierInformation?customer_id=SUPPLIER::2001::::::

MERCHANT

https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace /RetailAppsDataPrivServicesRESTApp/rest/privatedata/updateMerchantInformation?customer_id=MERCHANT::2114::::

STORE

https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace/RetailAppsDataPrivServicesRESTApp/rest/privatedata/updateStoreInformation?customer_id=STORE::7143876752::::::

WAREHOUSE

https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace /RetailAppsDataPrivServicesRESTApp/rest/privatedata/updateWarehouseInformation?customer_id=WAREHOUSE::9993::

PARTNER

https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace /RetailAppsDataPrivServicesRESTApp/rest/privatedata/updatePartnerInformation?customer_id=PARTNER::::464694358::::::

OUTLOC

https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace /RetailAppsDataPrivServicesRESTApp/rest/privatedata/updateOutLocInformation?customer_id=OUTLOC::::97285::::::

CUSTOMER

https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace/RetailAppsDataPrivServicesRESTApp/rest/privatedata/CUSTOMER?customer_id=CUSTOMER::CUSTID::1234567::::::

ORDER_CUSTOMER

https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace /RetailAppsDataPrivServicesRESTApp/rest/privatedata/updateOrderCustomerInformation?customer_id=ORDER_CUSTOMER::90003::::

EMPLOYEE

https:// rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace /RetailAppsDataPrivServicesRESTApp/rest/privatedata/updateEmployeeInformation?customer_id=EMPLOYEE::SAMMYSMITH::::::

Security Pre-requisites/Considerations for accessing Data Privacy ReST Services

The preferred access method for these services is through Oauth2–based security. For OAuth credential configuration, see the section titled OAuth for REST Service Authentication in this document.

In the rare event of using basic Auth for accessing these services, ensure the user accessing these services has the necessary IDCS groups associated as listed below:

  • For Production environments,

    • DATAPRIV_ADMINISTRATOR_REST_API_ROLE

    • DATA_PRIVACY_ADMINISTRATOR_JOB

  • For Non-Prod environments,

    • DATAPRIV_ADMINISTRATOR_REST_API_ROLE_PREPROD

    • DATA_PRIVACY_ADMINISTRATOR_JOB_PREPROD

Operations

The following services are included in this functional area:

Background Job Configuration Upload Service

The following services are included in this functional area:

Get Batch Run Status Services
Endpoints
/MerchIntegrations/services/administration/operations/batchRunStatus
Functional Area

Administration - Operations

Business Overview

This service returns the current running status of the nightly batch. During the nightly batch window, certain REST services may be unavailable either for the entire duration or for a portion of the night, especially when inventory or costing batch flows are in progress. This API enables clients to monitor the status of batch processes, allowing them to optimize their service calls by pausing or resuming dependent REST services accordingly.

Service Type

GET

ReST URL
 /MerchIntegrations/services/administration/operations/batchRunStatus
Output
Name Data Type Description

batchRunningInd

String

This field indicates whether Nightly batch jobs are running. It is set to Y at the beginning of the Merchandising nightly batch cycle and set to N at the end of the cycle.

inventoryBatchRunningInd

String

This field indicates whether inventory batch jobs are running. Valid values are Y or N.

costingBatchRunningInd

String

This field indicates whether costing batch jobs are running. Valid values are Y or N.

Sample Response Message

{
  "batchRunningInd": "N",
  "inventoryBatchRunningInd": "N",
  "costingBatchRunningInd": "N"
}
Table Impact
TABLE SELECT INSERT UPDATE DELETE

RMS_BATCH_STATUS

Yes

No

No

No
Update Background Job Configuration

This section describes the Background Process Configuration.

Business Overview

This service is used to update the configuration for each background jobs in Merchandising.

Service Type

Post

ReST URL

processes/update/process_config/execution

Input Parameters
Parameter Name Required Description

JobName

Yes

Job Name

numThreads

No

Maximum number of threads the job will execute

numDataToProcess

No

Number of records a jobs will process each run.

commitMaxCtr

No

Max number of records processed before a commit is issued.

archiveInd

No

This field will be used to determine if associated tables for this job needs to be archived to history or not.
Output

N/A

Table Impact
TABLE SELECT INSERT UPDATE DELETE

B8D_PROCESS_CONFIG

No

No

Yes

No

JOB_AUDIT_LOGS

No

Yes

No

No

JOB_AUDIT_PAYLOAD

No

Yes

No

No

BI Publisher Report URL Download Service

The following services are included in this functional area:

Get BI Publisher Report URL
Functional Area

Administration - Operations

Business Overview

This service is used by Oracle Retail Financial Integration (RFI) to retrieve the URL of a BI Publisher report from Merchandising or Sales Audit that can be invoked from the PeopleSoft Financials General Ledger based on a particular journal entry. The report URL that will be returned will be different based on the ID sent in the service call. Based on that ID, Merchandising will determine if it was a Merchandising, Sales Audit, or Invoice Matching ID and return a URL for the appropriate report. 

The possible reports for Merchandising and Sales Audit are:

  • GL Fixed Deal Data Report

  • GL Item level Data Report

  • GL Item Rollup Daily Data Report

  • GL Item Rollup Monthly Data Report

  • GL Sales Audit Data Report

Also, for Invoice Matching, one of the following reports might be returned:

  • Merchandise Invoice Document Report

  • Non-Merchandise Invoice Document Report

  • Credit Note Document Report

  • Credit Memo Cost Document Report

  • Credit Memo Quantity Document Report

  • Debit Memo Cost Document Report

  • Debit Memo Quantity Document Report

  • Debit Memo VAT Document Report

  • Receipt Write Off Document Report

For cloud service implementations, this configuration should be done if you are working with PeopleSoft Financials. For on premise implementations, you may need to configure this in the RETAIL_SERVICE_REPORT_URL table. For cloud service implementations, this configuration can be done by the Oracle Cloud Operations team.

The report is similar functionality to the Drill Forward and Drill Back functionality available in the Merchandising Transaction Data and Fixed Deal pages and the Sales Audit General Ledger Transaction page. See also Get Drill Back Forward URL Service for more on the APIs that support this functionality.

Service Type

POST

ReST URL
MerchIntegrations/services/administration/operations/biPublisherReport/url/get
Input Payload Details

Table 5-2 Get - Object. See list of elements for detail

Element Name Required Data Type Description

reportReferenceKey

Yes

String (32)

Holds the unique reference trace ID that is used to match to the report URL.

Sample Input Message

{
  "reportReferenceKey": "String"
}
Response Code: 200 (Success)

Table 5-3 GetResponse - Object. See list of elements for detail

Element Name Required Data Type Description

reportReferenceKey

Yes

String (32)

Holds the unique reference trace ID that is used to match to the report URL.

reportUrl

Yes

String (256)

Contains the report URL with parameters for financial integration.

Sample Response Message

{
  "reportReferenceKey": "String",
  "reportUrl": "String"
}
Response Code: 400 (Error)

In case of error, the following standard error response will be returned. The element "validationErrors" will be present when input payload or input parameters are not as per the schema definition of this service. The element "businessError" will be present if the payload passes schema validation but exception is caught while processing business logic.

Sample Error Message

{
  "status": "ERROR",
  "message": "Error found in validation of input payload",
  "validationErrors": [
    {
      "error": "must be one of Y, N",
      "field": "createRecord.arg0.approveInd",
      "inputValue": "X"
    }
  ],
  "businessError": [
    "Error message"
  ]
}

Calendar Download Service

The following services are included in this functional area:

Get 4-5-4 Calendar
Endpoints

/MerchIntegrations/services/administration/operations/calendar

Functional Area

Administration – Operations

Business Overview

This service retrieves 4-5-4 calendar details. This service takes an optional query parameter of year to retrieve details for that year

Service Type

GET

ReST URL
/MerchIntegrations/services/administration/operations/calendar? year=[year]
Input Parameters
Parameter Name Required Data Type Description

year

No

Number

Year. Retrieve calendar for a specific year
Output – Calendar
Name Data Type Description

year

String

Contains the year. The 4-5-4 year begins on the first day of the first 4-5-4 month regardless of when the calendar year begins.

month

String

Contains the number ranging from 1 to 12 which indicates the 4-5-4 month.

noOfWeeks

Number

Indicates whether there are 4 or 5 calendar weeks in the 4-5-4 month.

firstDay

Date

Contains the first day of the 4-5-4 month in YYYY-MM-DD format

Example JSON output:

[{
    "year": 2022,
    "month": 1,
    "noOfWeeks": 4,
    "firstDay": "2022-01-02"
  },
  {
    "year": 2022,
    "month": 2,
    "noOfWeeks": 4,
    "firstDay": "2022-01-30"
 }]
Table Impact
TABLE SELECT INSERT UPDATE DELETE

CALENDAR

Yes

No

No

No

Codes and Descriptions Download Service

The following services are included in this functional area:

Get Codes and Descriptions
Business Overview

Code Detail service allows user to retrieve code details for a selected code and code type.

Service Type

GET

ReST URL
CodeDetail/codeDetails?code={ }&codeType={ }
Input Parameters
Parameter Name Required Description Valid values

Code

Yes

Code

NA

Code Type

Yes

Code Type

NA
Output

RestCodeDetailRecRDO

Parameter Name Data Type

codeDesc

String

requiredInd

String

codeSeq

BigDecimal

codeType

String

codeTypeDesc

String

code

String

JSON Structure

{
  "codeDesc": null,
  "requiredInd": null,
  "codeSeq": null,
  "codeType": null,
  "codeTypeDesc": null,
  "code": null,
  "links": [],
  "hyperMediaContent": {
    "linkRDO": []
  }
}
Table Impact
TABLE SELECT INSERT UPDATE DELETE

CODE_HEAD

Yes

No

No

No

CODE_DETAIL

Yes

No

No

No

JOB_AUDIT_LOGS

No

Yes

No

No

JOB_AUDIT_PAYLOAD

No

Yes

No

No
Get Codes and Descriptions for All or Provided Code Type
Endpoints

/MerchIntegrations/services/administration/operations/codes

Functional Area

Administration – Operations

Business Overview

This service returns full dataset of code and code detail. This service supports pagination and the page size of each response is controlled by the query paramter 'limit'. This service optionally takes code type as input for returning the code details for a single code type.

Service Type

GET

ReST URL
/MerchIntegrations/services/administration/operations/codes? offsetkey={offsetkey}&limit={limit}&codeType=[codeType]
Input Payload Details

Table 5-4 Input Parameters for MerchIntegrations/services/administration/operations/codes

Parameter Name Required Data Type Description

offsetkey

No

String

Offset Key. Valid Value is code type

limit

No

Number

Pagination limit. Default Value is 1000.

codeType

No

String

Code Type. Searches for a specific code type
Response Code: 200 (Success)

Table 5-5 Output – Code

Name Data Type Description

codeType

String

This field contains the code type which will serve as a grouping mechanism for the multiple codes.

description

String

This field will contain the description of the code type.

Details

Collection

Code details

Table 5-6 Output – Code Details

Name Data Type Description

code

String

This field contains the code used in the application.

codeDescription

String

This field contains the description associated with the code and code type.

sequence

Number

This is a number used to order the elements so that they appear consistently when using to populate a list or display in user interface.

usedInd

String

Indicate if the code is in use or not. Records set to N will not display as possible options for users. Valid value Y or N

Table 5-7 Elements in JSON Output

Elements Description

items

The first element is named as items and contains a number of child elements. Each child element corresponds to a row in the result set generated by the query.

hasMore

This is dependent on limit value. If the total rows are more than then limit defined then hasMore will be set to true else false.

limit

This is used to limit the rows to control the paging of result data. Based on the limit, next and previous links are displayed.

For example: If the limit is set to 25, internal it tries to fetch 26 rows. If 26th row exists then 25 rows are returned along with a "next" link else no links would be added to the JSON response.

links

“self” : This contains URI pointing to current page.

“next”: This contains URI pointing to the next page of results.

Example JSON output:

{
  "items": [
    {
      "codeType": "LOC",
      "description": "Location",
      "details": [
        {
          "code": "W",
          "codeDescription": "Warehouse",
          "sequence": "2",
          "usedInd": "Y"
        },
        {
          "code": "S",
          "codeDescription": "Store",
          "sequence": "1",
          "usedInd": "Y"
        }
      ]
    }
  ],
  "hasMore": true,
  "limit": 1,
  "count": 1,
  "links": [
    {
      "href": "http://Server:port/MerchIntegrations/services/administration/operations/codes?offsetkey=LOB&limit=1",
      "rel": "self"
    },
    {
      "href": "http:// Server:port /MerchIntegrations/services/administration/operations/codes?offsetkey=LOC&limit=1",
      "rel": "next"
    }
  ]
}
Table Impact
TABLE SELECT INSERT UPDATE DELETE

CODE_HEAD

Yes

No

No

No

CODE_DETAIL

Yes

No

No

No

External Reference Service

The following services are included in this functional area:

Manage External Cross Reference Identifier
Functional Area

Administration - Operations

Business Overview

This is a helper service to bulk update the external reference ID column of a few selected tables that can be used during a migration activity, like financial integration migration. This only supports the following entities: Supplier, Partner, Payment Terms, Freight Terms, Organization Unit, and Language. This service allows the client to publish the Merchandising internal entity ID and its corresponding external reference ID and this service will update the external_ref_id column in the table. This service does basic validation that the Merchandising entity ID is valid and exists in the corresponding table. For the external reference ID field, there is no validation and it expects the caller to pass in the correct value. If the external reference ID is left blank in the request, it will be nulled out in the table.

Service Type

PUT

ReST URL
MerchIntegrations/services/administration/operations/externalCrossReference/manage
Input Payload Details

Table 5-8 Manage - Object. See list of elements for detail

Element Name Required Data Type Description
items Yes Collection of Object References a collection of mapping of merchandising identifier to external reference id.

Table 5-9 Items - Object. See list of elements for detail

Element Name Required Data Type Description
entityType Yes String (20) This holds the type of entities for which the external reference id will be maintained. The valid values are 'SUPPLIER', 'PARTNER', 'PAYMENT_TERMS', 'FREIGHT_TERMS', 'ORG_UNIT', 'LANGUAGE'.
entityId Yes String (50) Based on the entity type, this should hold the value of an existing merchandising identifier in the corresponding table for the entity. If this identifier is not present in the entity table, it will result in error. While this field takes a generic String input, this will be validated based on the identifier in the specific entity table. Example for SUPPLIER, this attribute should be numeric and up to 10 digit long.
externalReferenceId No String (50) The external Reference id that should be attached to the merchandising identifier in the column external_ref_id. There is no validation for this attribute, and it will save as is. If this field is null, it will be saved as null.

Table 5-10 ManageError - Object. See list of elements for detail

Element Name Required Data Type Description
entityType Yes String (20) This holds the entity type that was provided in the input.
entityId Yes String (50) This holds the merchandising entity identifier provided in the input.
externalReferenceId No String (50) This holds the external reference id provided in the input.
message Yes String (2000) This holds a concatenated list of error message if there were business validation error against this record.

Sample Input Message

{
  "items": [
    {
      "entityType": "PAYMENT_TERMS",
      "entityId": "22",
      "externalReferenceId": "15 Net (terms date + 15)"
    }
  ]
}
Response Code: 200 (Success)

Response Code: 400 (Error)

In case of error, the following standard error response will be returned. The element validationErrors will be present when input payload or input parameters do not match the schema definition for this service. The element businessError will be present if the payload passes schema validation but an exception is caught while processing the business logic.

Table 5-11 ManageError - Object. See list of elements for detail

Element Name Required Data Type Description
entityType Yes String (20) This holds the entity type that was provided in the input.
entityId Yes String (50) This holds the merchandising entity identifier provided in the input.
externalReferenceId No String (50) This holds the external reference id provided in the input.
message Yes String (2000) This holds a concatenated list of error message if there were business validation error against this record.

Sample Error Message

{
  "status": "ERROR",
  "message": "Error found in validation of input payload",
  "validationErrors": [
    {
      "error": "must be one of Y, N",
      "field": "createRecord.arg0.approveInd",
      "inputValue": "X"
    }
  ],
  "businessError": [
    {
      "entityType": "SUPPLIER",
      "entityId": "1001",
      "externalReferenceId": "15 Net (terms date + 15)",
      "message": "Payment Terms identifier does not exist in Merchandising. Input entity identifier: 22;"
    }
  ]
}

POM End of Week Signal Download Service

The following services are included in this functional area:

Get POM End of Week Signal Detail
Business Overview

This service is used to determine whether the Vdate is an End of Week Date or Not.

If Vdate is at EOW, it returns 'Y', else 'N'.

Service Type

Get

ReST URL

EowRunSignal/EowRunSignalDetail

Input Parameters

N/A

Output

RestEowRDO

Parameter Name Data Type

eow

Char('Y' or 'N')

JSON Structure

{
   "eow": "N",
   "links": [],
   "hyperMediaContent": {
      "linkRDO": []
   }
}
Table Impact
TABLE SELECT INSERT UPDATE DELETE

PERIOD

Yes

No

No

No

SYSTEM_VARIABLES

Yes

No

No

No

Service Status Download Service

Get ReST Service Status
Functional Area

Administration - Operations

Business Overview

This service allows the querying of the status of ReST web service call using an X-Correlation-ID. The correlation id that was included in the request HTTP header can be used as the input, or if one was not passed one in the original request, the one from the response HTTP header can be used as the input. This service will return all the entries in service_metrics table against that correlation ID. The response support pagination and if there are multiple pages of response, use the next link to call subsequent pages. This service additionally checks the input correlation ID against the request_id field to handle the scenario where the x_correlation_id is null in the service_metrics table because it was not included in request HTTP header.

An additional query parameter of includePayload, supports a value of yes ('Y') or no ('N') can be used to retrieve the request and response payload for that request. In the case of a service error (response code of 300 or greater) the response payload will be included irrespective of includePayload parameter.

Service Metrics
  • Merchandising ReST Service framework keeps a log of every service call in the service_metrics table. When the service request is received at the application server, it makes an entry to service_metrics table using a unique request ID and the time of the call. Once the service request has been processed and the response is ready to be served back, the application server updates the service metrics table to capture the run time and response code.
  • The application server optionally saves the payload in service_payload table. The payloads are only captured for POST, PUT or DELETE service calls. The payload for GET service calls are captured if service call had an error (response code is 300 or greater) or while running in debugging mode.
  • The service metrics and payload entry are held for short period and get purged after configurable (default 3 months) purge window.
X-Correlation-ID
  • Merchandising ReST Service framework supports a custom HTTP Header named as X-Correlation-ID and it is recommended to include this in every ReST web service call for traceability purpose.
  • The request X-Correlation-ID is copied and is returned in the Response HTTP Header X-Correlation-ID field. This is also captured in the service_metrics table against that request.
  • In the case where, X-Correlation-ID was not included in the request header, the internally generated unique request ID is populated in the Response HTTP Header X-Correlation-ID field. The response X-Correlation-ID should be logged if one is not passed in the request.
  • It is recommended that a unique X-Correlation-ID is always passed as part of every request (including retry) to trace each unique call. The validation for unique value is not enforced.
  • A log of X-Correlation-IDs should be maintained for traceability purpose and troubleshooting exceptions.
Service Type

GET

ReST URL
MerchIntegrations/services/administration/operations/restService/status
Input Parameters
Parameter Name Required Data Type Description
limit No Number (6) Pagination limit. Default Value is 1000
offsetkey No String Offset Key. Valid Value is RequestId
xCorrelationId Yes String (36) X-Correlation-ID to search for required service call. This is a required parameter.
includePayload No String (1) Indicate if request and response payload should be included in the response. Valid value is ‘Y’ or ‘N’. Defaults to ‘N’ if not provided
include No String Fields to include - comma separated (Example items.name,items.address.city)
exclude No String Fields to exclude - comma separated (Example items.address.contactFax,items.customFlexAttribute)
Response Code: 200 (Success)
Element Name Required Data Type Description
items No Collection of Object References a collection of rest service call details

Table 5-12 Items - Object. See list of elements for detail

Element Name Required Data Type Description
requestId Yes String (36) This field contains unique Request id.
xCorrelationId Yes String (36) This field contains the X-Correlation_ID in the response http header. If the client passed a X-Correlation_ID in the request HTTP Header, the same is returned or else a generated uuid (captured in request_id) is returned back
Method Yes String(10) Contains the HTTP Method like GET, PUT, POST, DELETE.
Path Yes String(255) Contains the Rest Service path.
responseCode No String(10) This field contains the HTTP Code for the response. This will hold a value after the server processed the request and responded back. Example 200, 400, 500
requestTimestamp Yes Timestamp This field hold the timestamp in UTC when the request was received by the server.
responseTimestamp No Timestamp This field hold the timestamp in UTC when the request processing completes and server is ready to transmit the response back.
durationMillisecond No Number(12,0) This field contains the millisecond to process the request. This is populated after server completes the request.
requestSizeByte No Number(12,0) This field contains the bytes in request payload.
responseSizeByte No Number(12,0) his field contains the bytes in the response payload. This is populated after server completes the request.
clientName Yes String(255) This field contains the oAuth Client name used to make the request
serviceUrl Yes String(2000) This field the complete path for the service call
requestPayload No CLOB This field contains the request payload if query parameter of includePayload is set to Y.
responsePayload No CLOB This field contains the response payload if query parameter of includePayload is set to Y or there was an exception in the request and the response code is 300 or greater.

Sample Response Message

{
  "items": [
    {
      "requestId": "6ccc5287-a078-4aae-b697-9ade58d70bd1",
      "xCorrelationId": "034b9672-4818-40b4-916d-210a21e0de84",
      "method": "POST",
      "path": "/MerchIntegrations/services/foundation/item",
      "responseCode": "200",
      "requestTimestamp": "2024-05-12T04:20:31.996Z",
      "responseTimestamp": "2024-05-12T04:20:31.996Z",
      "durationMillisecond": 450,
      "requestSizeByte": 720,
      "responseSizeByte": 18240,
      "clientName": "xocs_client",
      "serviceUrl": "https://<server>/MerchIntegrations/services/administration/operations/restService/status?xCorrelationId=36c6b984-8e16-4efb-b73f-5984357c1d72",
      "requestPayload": "{}",
      "responsePayload": "{}"
    }
  ],
  "hasMore": true,
  "limit": 1000,
  "count": 1,
  "links": [
    {
      "href": "https://<server>:<port>/Application/services/resources?limit=1000",
      "rel": "self"
    }
  ]
}

Virtual Date Download Service

The following services are included in this functional area:

Get Current Virtual Date in Date Format
Business Overview

Deprecated in v23.1.401.0: Scheduled for Removal in 2 Years. Use RmsReSTServices/services/private/Common/vDate

This service retrieves the Merchandising virtual business date (vdate).

Service Type

GET

ReST URL
Vdate/vdateDetail
Input Parameters

N/A

Output

Table 5-13 RestVdateRecRDO

Parameter Name Data Type
vdate Date

JSON Structure

[
  {
    "vdate": null,
    "links": [],
    "hyperMediaContent": {
      "linkRDO": []
    }
  }
]
Table Impact
TABLE SELECT INSERT UPDATE DELETE
PERIOD Yes No No No
JOB_AUDIT_LOGS No Yes No No
JOB_AUDIT_PAYLOAD No Yes No No
Get Current Virtual Date in Long and Date Format
Business Overview

Retrieve Merchandising Vdate.

Service Type

GET

ReST URL
/Common/vDate
Input Parameters

N/A

Output

Table 5-14 Vdate in Long and Date Format

Parameter Name Data Type

Vdate

Long

Vdate

Date

JSON Structure

{
   "vdateDisplay": "01-Jul-2019",
   "vdate": 1561939200000,
   "links": [],
   "hyperMediaContent": {
      "linkRDO": []
   }
}
Table Impact
TABLE SELECT INSERT UPDATE DELETE

PERIOD

Yes

No

No

No

JOB_AUDIT_LOGS

No

Yes

No

No

JOB_AUDIT_PAYLOAD

No

Yes

No

No

Webhook Configuration Download Service

Get Webhook Configuration and Status

Functional Area

Administration - Operations

Business Overview

This service retrieves the configured Webhook Listeners and any unused credential names. The response contains three types of information:

  • Webhook Configurations: Provides details about the current webhook configuration, including the listener URL and interval seconds. This information is retrieved from the webhook_config table.
  • Current Status: Indicates the current status of the webhook, including the since timestamp to be used in the next call and an estimate of when the next heartbeat or polling process will be triggered. If the most recent heartbeat encountered a failure, the error message will be included. This information is retrieved from the webhook_status table.
  • Metrics Summary for today and yesterday: Included only if the query parameter includeMetrics is set to Y. The metrics summary is at day level and is limited to the current day (starting from midnight GMT) and yesterday (GMT timezone) and provides total counts of webhook calls and heartbeats triggered on the day, along with the number of successful calls. It additionally contains detailed activity log message of the last webhook and heartbeat processes executed for the day to assist with troubleshooting if webhook publish is unsuccessful. This data is retrieved from the webhook_metrics table. Note: The number of rows in this table can grow very large over time and fetching the metrics summary will be a performance-intensive operation and service may take additional time compared to a call with includeMetrics = N.
Service Type

GET

ReST URL
MerchIntegrations/services/administration/operations/webhooks
Input Parameters
Parameter Name Required Data Type Description
limit No Number (6) Pagination limit. Default Value is 1000
offsetkey No String Offset Key. Valid Value is combination of credential name and service
service No String (100) Service Name to retrieve details for a particular service
includeMetrics No String (1) A value of Y will result in the service fetching metrics summary for today and yesterday along with the log of most recent call. Valid value Y or N.
include No String Fields to include - comma separated (Example items.name,items.address.city)
exclude No String Fields to exclude - comma separated (Example items.address.contactFax,items.customFlexAttribute)
Response Code: 200 (Success)
Element Name Required Data Type Description
items No Collection of Object References a collection of webhook listener details.

Table 5-15 Items - Object. See list of elements for detail

Element Name Required Data Type Description
credentialName Yes String (100) This field contains the Credential name.
credentialType Yes String (30) This field contains the Credential type.
service No String (100) This field contains the service name.
listenerUrl No String (255) This field contains the listener URL.
enabled No String (1) This field indicates if the service is enabled. Default is 'Y'. Valid values is 'Y' or 'N'.
intervalSeconds No Number (6,0) This field contains the frequency in seconds webhook will poll for new events. Default is 900 seconds.
includePayload No String (1) This field indicates if data should be included in the webhook call. Default is 'N'. Valid values is 'Y' or 'N'.
pageLimit No Number (6,0) This field contains the number of records within a payload during pagination and is used to control the message size. Default is 1000.
HeartbeatIntervalHours No Number(2,0) This field frequency in hours on which heartbeat will be pinged to listener. Default is 6 hours.
sinceTimestamp No Date-Time This field hold the configured since-timestamp for this API.
status No Object This node hold the summary view for the webhook activity since midnight (UTC) today. This will be populated based on query parameter
metrics No Object List This node hold the summary view for the webhook activity since midnight (UTC) today. This will be only populated if query parameter includeMetrics is Y. This node hold the summary view of webhook activities at day level since midnight (UTC) yesterday and can hold upto two entries - one for today and one for yesterday. The record for today or yesterday is populated only if some webhook or heartbeat activity happened for the day.

Table 5-16 status - Object. See list of elements for detail

Element Name Required Data Type Description
nextPollTime No Date-Time This field holds the timestamp when the next internal polling to check for delta change is due.
nextPollSinceTimestamp No Date-Time This field holds the since-timestamp that will be used in the next internal poll. This field is updated after every successful publish and holds the pointer of the last successful publish.
nextPollOffsetKey No String This field holds a value only when multi-page publish is in progress. During a multi-page publish, this helps to identify the key of the last record of the last page published. After the last page is published, it is reset to blank.
nextHeartbeatTime No Date-Time This field holds the timestamp when the heartbeat is due. One the heartbeat is due, before any subsequent webhook publish, an heartbeat will be fired.
heartbeatError No String This field will hold the error message if the previous heartbeat was a failure.

Table 5-17 metrics - Object. See list of elements for detail

Element Name Required Data Type Description
Date No Date-Time This field holds either today or yesterday date for which the subsequent metrics information is applicable.
count No Number This field contains the number of calls (excluding heartbeat) made to the listener for the date
countSuccess No Number This field contains the number of successful calls (excluding heartbeat) made to the listener for the date
lastPublishTime No Date-Time This field holds the timestamp when the webhook engine initiated the last publish for the date.
lastPublishActivityLog No String This field holds the log messages when the webhook engine initiated the last publish call for the date.
countHeartbeat No Number This field contains the number of heartbeat calls made to the listener for the date
countSuccessHeartbeat No Number This field contains the number of successful heartbeat calls made to the listener for the date
lastHeartbeatTime No Date-Time This field holds the timestamp when the webhook engine initiated the last heartbeat call for the date.
lastHeartbeatActivityLog No String This field holds the log messages when the webhook engine initiated the last heartbeat call for the date.

Sample Response Message

{
  "items": [
    {
      "credentialName": "APP1",
      "credentialType": "OAUTH",
      "service": "foundation/item",
      "listenerUrl": "https://apigateway.myretailer.com/webhook/mfcs/item",
      "enabled": "N",
      "intervalSeconds": 900,
      "includePayload": "N",
      "pageLimit": 1000,
      "heartbeatIntervalHours": 6,
      "sinceTimestamp": "1970-01-01T00:00:00.000Z",
      "status": {
        "nextPollTime": "2025-01-01T10:00:00.000Z",
        "nextPollSinceTimestamp": "2025-01-01T04:27:47.801Z",
        "nextPollOffsetKey": "",
        "nextHeartbeatTime": "2025-01-01T12:25:00.000Z",
        "heartbeatError": ""
      },
      "metrics": [{
        "date": "2025-01-01T00:00:00.000Z ",
        "count": 7,
        "countSuccess": 6,
        "lastPublishTime": "2025-01-01T03:27:47.801Z",
        "lastPublishActivityLog": "<Timestamp>: Calling url for payload...",
        "countHeartbeat": 3,
        "countSuccessHeartbeat": 3,
        "lastHeartbeatTime": "2025-01-01T06:25:00.000Z",
        "lastHeartbeatActivityLog": "<Timestamp>: Calling url for heartbeat..."
      }]
    }  
  ],
  "hasMore": true,
  "limit": 1000,
  "count": 1,
  "links": [
    {
      "href": "https://<server>:<port>/Application/services/resources?limit=1000",
      "rel": "self"
    }
  ]
}

Webhook Configuration Upload Service

Manage Webhook Credential

Functional Area

Administration - Operations

Business Overview

This service maintains credentials for the Webhooks listener and allows for setting up new credentials, along with updating or deleting existing credentials. Credentials must be set up in advance of webhook listener setup. A credential cannot be deleted if it is attached to a listener.

The credentials are securely stored in OCI S3. The supported credentials are Basic Auth, oAuth2 (Client Credentials) and API key (Request Parameter - X-API-Key). Based on the type of credential, the corresponding field should be provided. In case of oAuth, the URL to retrieve the oAuth token should be allowlisted and should have a publicly trusted SSL/TLS certificate.

Service Type

PUT

ReST URL
MerchIntegrations/services/administration/operations/webhook/credential/manage
Input Payload Details

Table 5-18 Manage - Object. See list of elements for detail

Element Name Required Data Type Description

credentialName

Yes

String (100)

Unique Credential name for storing credential details for webhook listener endpoint.

credentialType

No

String (30)

Type of credential supported by listener. Valid options are OAUTH, BASICAUTH or APIKEY

username

No

String (100)

Contains the username for basic auth credential

password

No

String (100)

Contains the password for basic auth credential

apikey

No

String (2000)

Contains apikey. API Key will be passed in Request Parameter X-API-Key

oauthClientId

No

String (255)

Contains the client id for Oauth - Client Credential authentication

oauthClientSecret

No

String (255)

Contains the client secret for Oauth - Client Credential authentication

oauthTokenUrl

No

String (255)

Contains the oAuth Token URL for Oauth - Client Credential authentication

oauthScope

No

String (255)

Contains the scope for Oauth - Client Credential authentication. Scope is optional.

heartbeatIntervalHours

No

Number (2)

Controls the frequency in which heartbeat will be published to the listener URL

deleteInd

No

String (1)

Pass a value of Y to delete the credential. To delete a credential, none of the listener should be using this credential. Supported values as Y or N. The default if left blank is N.

Sample Input Message

{
  "credentialName": "APP_DEV1",
  "credentialType": "OAUTH",
  "username": "",
  "password": "",
  "apikey": "",
  "oauthClientId": "oracle_mfcs_client_dev1",
  "oauthClientSecret": "6c2c0acb-88a1-4067-865b-5eb75b2989c3",
  "oauthTokenUrl": "https://iam-6c2c0acb.iamprovider.com:443/oauth2/v1/token",
  "oauthScope": "mfcs-webhook-dev1",
  "deleteInd": ""
}
Response Code: 200 (Success)

Sample Response Message

{
  "status": "SUCCESS",
  "message": "Create record was successful"
}
Response Code: 400 (Error)

In case of error, the following standard error response will be returned. The element validationErrors is present when the input payload or input parameters do not match the schema definition for this service.

Sample Error Message

{
  "status": "ERROR",
  "message": "Error found in validation of input payload",
  "validationErrors": [
    {
      "error": "must be one of Y, N",
      "field": "createRecord.arg0.approveInd",
      "inputValue": "X"
    }
  ]
}
Manage Webhooks

Functional Area

Administration - Operations

Business Overview

This service is used to register and manage webhook listeners. To register a listener, the credential for the listener should be set up first using the Manage Webhook Credential service. 

Webhook Overview

The listener URL should be an allowlisted https ReST endpoint supporting THE POST method and having publicly trusted SSL/TLS certificate. a Webhook can be configured for THE Publish API and THE name of the service should match with the value in THE merchapi_name column from the merchapi_config table. Once a webhook is successfully registered, it is added to the server threadpool after a short interval and, thereafter, runs based on the configured interval.

Three types of publish are available:

  • HEARTBEAT - The frequency (in hours) of this can be defined using the field heartbeatIntervalHours. A ping call is made to the listener endpoint to validate the connectivity, credential, and to ensure that the webhook server is up and running. If the heartbeat call fails, the webhook call with the event or payload is put on hold until the heartbeat connectivity is established. Once the heartbeat connectivity is established, the event or payload publish starts.

  • EVENT - A webhook call of type Event indicates to the listener that there are one or more functional data packets that have been created or updated since the last webhook call, and the listener should poll the Publish API to publish the change. A webhook of type Event is the default webhook configuration and should be the preferred configuration to keep the data traffic through the webhook to a minimum. If the field includePayload is left blank or is set to N, this indicates that the webhook is configured for event publishing.

  • PAYLOAD - A webhook of type Payload includes the data as part of the webhook publish. The data is published in JSON format and is enclosed in the attribute named payload. To enable payload publish, set the value of includePayload to Y. The payload supports pagination to keep the individual message size in control. Use the field pageLimit to define the number of records included in the call. If pageLimit is not defined, it is set to 1000. For a payload publish, the server posts each subsequent page immediately upon receiving the success response from the client for the previous page.

The processing of a webhook is asynchronous. Using a background micro batch engine, the webhook server checks for new events in merchapi json tables for changes. The frequency at which the server polls the merchapi json table is configured using the field intervalSeconds. Every <interval> seconds, the server polls the table to check for new entries and, if there are updates, it makes a webhook call to the listener URL to publish the event or payload depending on the webhook configuration. If there are no new entries, it does not make an empty webhook call.

To keep track of the records that have been published, and have the subsequent webhook publish only include the newer records since the last call, the timestamp of the webhook pool is persisted by the server and is named the since timestamp. When the webhook is registered for the first time, the since timestamp is defaulted to Unix time zero (1970) unless a since timestamp was provided as part of the registration. The server polls the json table to check for newer entries having timestamp greater than since timestamp.  

  • For a webhook of type Event, the since timestamp is included in the publish to inform the listener that there are records having a timestamp greater than the since timestamp and they should poll the Publish API using a query parameter of since timestamp. 

  • For a webhook of type Payload, the server internally calls the Publish API with the since timestamp and using before as the current server time and the configured pagination limit. The server redirects the response from the Publish API to the webhook listener. Depending on the number of records and the pagination size, more than one call can be made to the listener URL. Once the last page is published, the server replaces the since timestamp with the server time when the first poll is performed. Subsequent polling uses the new since timestamp to check for newer entries.

  • If there are no new entries, the value of since timestamp is not changed and this value can be seen as a the timestamp when the last publish of type Event or Payload was made.

The since timestamp is available as part of webhook configuration and this can be updated for existing webhooks. This can be useful to request a full download or to replay all changes since, for example, last week for data corruption scenarios.

Enable/Disable The flag Enabled takes a value of Y or N, and can be used to activate or deactivate a webhook. If the webhook is disabled, it pauses all polls and even heartbeat calls to the listener. Once the webhook is enabled, it starts polling using the since timestamp of the last publish.

Query Parameter This optional field enables Dynamic Payload Filtering, allowing clients to fetch selective fields or exclude fields based on the listener application's needs. Several webhook-supported APIs accept a query parameter of include or exclude, with values representing JSON field names using dot notation (for example, include=items.item,items.status,itemDescription). When provided, this query parameter is appended to the internal service call URL when fetching the payload. The only supported query parameters through webhooks are include and exclude, and it is recommended to test the query parameter values before configuring them in a webhook.

Update Webhook Configuration

To update the configuration of a webhook listener, include the fields that need to be updated and their values will be replaced. The fields left blank will not be changed. A configuration change can have an impact on the current publish process (multi-page payload publish).

  • Listener URL change will be applied immediately. A change of listener causes a heartbeat to be fired and, once the heartbeat is successful, subsequent calls are published to the new URL. If the change happened in between pagination publishes, the remaining pages are published to the new URL. A listener change is a major change and, if the intention for the new listener URL is to get the entire dataset or to start with a particular date and time, adjust the since timestamp accordingly to get the complete/required payload.

  • A change of credential takes effect immediately. A change of credential causes a heartbeat check to be fired before the next event or payload publish.

  • Since Timestamp change is applied immediately. This will terminate any in-progress pagination call and publish will restart with the new since timestamp. 

  • Page limit change takes effect immediately for the subsequent page publish. In case of an in-progress pagination publish, the remaining pages publish happens with the new page limit.

  • Interval second change takes effect a few minutes after the webhook engine syncs up with update configuration.

  • Disable webhook - This takes effect immediately and may pause a pagination call in between. The remaining pagination pages are published when the webhook is enabled. Enabling of the webhook takes few minutes for the server engine to include this webhook in its thread pool. 

  • A change of heartbeat interval hour takes effect after the next heartbeat is fired. 

  • IncludePayload - This change takes effect immediately and stops any pagination call. It uses the currently active since timestamp to check for changes, unless the since timestamp was also updated as part of the update request.

  • Query Parameter change will take into effect immediately for the subsequent page publish. To remove a previously set query parameter, provide blank spaces.
Delete Webhook

To delete a registered webhook, set the flag deleteInd to Y. That immediately stops subsequent calls and purges all configurations for the webhook.

Service Type

PUT

ReST URL
MerchIntegrations/services/administration/operations/webhooks/manage
Input Payload Details

Table 5-19 Manage - Object. See list of elements for detail

Element Name Required Data Type Description

collectionSize

Yes

Number (4)

Number of items in the collection.

items

Yes

Collection of Object

References a collection of webhook listeners

Table 5-20 Items - Object. See list of elements for detail

Element Name Required Data Type Description

service

Yes

String (100)

Service name for which webhook listener has to be configured. The service name should match with merchapi_name in merchapi_config table. On the api's having the json_table column populated are eligible for webhook.

credentialName

No

String (100)

Registered credential name that was setup using the Manage Webhook Credential service. For update, this can be left blank.

listenerUrl

No

String (255)

A whitelisted listener endpoint which is running a post service to consume the webhook call and returns 200 for success.

includePayload

No

String (1)

Indicates if the webhook publish will contain the data or just the event. Takes a value of Y or N. A value of blank is defaulted to N during initail registration. In case of update of already registered webhook, leave it blank to keep the value unchanged.

intervalSeconds

No

Number (6)

Defines the polling seconds for the webhook server to poll to json table for new events. This value is in seconds.

pageLimit

No

Number (6)

If the webhook is registered to include payload, this defines the maximum number of records in one publish call. If the number of records to be published are greater than page limit, additional pagination call will be made to publish the entire data set. Default value is 1000.

sinceTimestamp

No

date-time

Allows the listener to define if the publish should include events that happens after a particular time. This also allows for replaying already published daata/event by setting this to a earlier time.

enabled

No

String (1)

Takes a value of Y (default if null) or N. If the webhook is disabled, it will pause polling and publish of webhook (inlcuding heartbeat)

heartbeatIntervalHours

No

Number (2)

Controls the frequency in which heartbeat will be published to the listener URL

deleteInd

No

String (1)

Use this to delete an existing listener by setting the value as Y. the default if left blank is N.
queryParameter No String (2000) This field can be used to apply API-supported query parameter of include or exclude when an internal service is invoked to fetch a payload. It is highly recommended to test the query parameter by calling the GET APIs to avoid unexpected errors at runtime. To remove an earlier provided query paramter value, submit the value with an empty space.

Table 5-21 ManageError - Object. See list of elements for detail

Element Name Required Data Type Description

service

Yes

String (100)

Service name for which the registration failed

errorMessage

Yes

String (2000)

Error message

Sample Input Message

{
  "collectionSize": 1,
  "items": [
    {
      "service": "foundation/item",
      "credentialName": "APP_DEV1",
      "listenerUrl": "https://apigateway.myretailer.com/webhook/mfcs/item",
      "includePayload": null,
      "intervalSeconds": 900,
      "pageLimit": 1000,
      "sinceTimestamp": "2001-12-31T23:59:59.123Z",
      "enabled": null,
      "heartbeatIntervalHours": 6,
      "deleteInd": null,
      "queryParameter": "include\u003ditems.item,items.status"
    }
  ]
}
Response Code: 200 (Success)
Response Code: 400 (Error)

In case of error, the following standard error response will be returned. The element validationErrors will be present when input payload or input parameters do not match the schema definition for this service. The element businessError will be present if the payload passes schema validation but an exception is caught while processing the business logic.

Table 5-22 ManageError - Object. See list of elements for detail

Element Name Required Data Type Description

service

Yes

String (100)

Service name for which the registration failed

errorMessage

Yes

String (2000)

Error message

Sample Error Message

{
  "status": "ERROR",
  "message": "Error found in validation of input payload",
  "validationErrors": [
    {
      "error": "must be one of Y, N",
      "field": "createRecord.arg0.approveInd",
      "inputValue": "X"
    }
  ],
  "businessError": [
    {
      "service": "foundation/items/manage",
      "errorMessage": "Invalid API"
    }
  ]
}

System Options

The following services are included in this functional area:

System Options Download Service

The following services are included in this functional area:

Get Functional System Options
Business Overview

Retrieve Merchandising's Functional Config Options.

Service Type

GET

ReST URL
/Common/FuncSysOps
Input Parameters

N/A

Output

Table 5-23 FunctionalConfigRDO

Parameter Name Data Type

importInd

String

orgUnitInd

String

supplierSitesInd

String

contractInd

String

elcInd

String

JSON Structure:

"{
    ""links"": [],
    ""importInd"": ""Y"",
    ""orgUnitInd"": ""Y"",
    ""supplierSitesInd"": ""Y"",
    ""contractInd"": ""Y"",
    ""elcInd"": ""Y"",
    ""hyperMediaContent"": {
        ""linkRDO"": []
    }
Table Impact
TABLE SELECT INSERT UPDATE DELETE

FUNCTIONAL_CONFIG_OPTIONS

Yes

No

No

No

JOB_AUDIT_LOGS

No

Yes

No

No

JOB_AUDIT_PAYLOAD

No

Yes

No

No
Get Inventory Movement System Options
Business Overview

Retrieve Merchandising's Inventory Movement Unit Options.

Service Type

GET

ReST URL
/Common/InvMovSysOps
Input Parameters

N/A

Output

Table 5-24 InvMoveUnitOptRDO

Parameter Name Data Type

allocMethod

String

applyProfPresStock

String

autoRcvStore

String

closeOpenShipDays

BigDecimal

costMoney

BigDecimal

costOutStorage

BigDecimal

costOutStorageMeas

String

costOutStorageUom

String

costWhStorage

BigDecimal

costWhStorageMeas

String

costWhStorageUom

String

defaultAllocChrgInd

String

defaultOrderType

String

defaultSizeProfile

String

deptLevelTransfers

String

distributionRule

String

duplicateReceivingInd

String

increaseTsfQtyInd

String

intercompanyTransferBasis

String

invHistLevel

String

locActivityInd

String

locDlvryInd

String

lookAheadDays

BigDecimal

maxWeeksSupply

BigDecimal

ordWorksheetCleanUpDelay

BigDecimal

racRtvTsfInd

BigDecimal

rejectStoreOrdInd

String

replOrderDays

String

rtvNadLeadTime

BigDecimal

rtvUnitCostInd

BigDecimal

shipRcvStore

String

shipRcvWh

String

storageType

String

storePackCompRcvInd

String

wfDefaultWh

String

targetRoi

BigDecimal

tsfAutoCloseStore

BigDecimal

tsfAutoCloseWh

String

tsfCloseOverdue

String

simForceCloseInd

String

tsfForceCloseInd

String

tsfOverReceiptInd

String

tsfMdStoreToStoreSndRcv

String

tsfMdStoreToWhSndRcv

String

tsfMdWhToStoreSndRcv

String

tsfMdWhToWhSndRcv

String

tsfPriceExceedWacInd

String

ssAutoCloseDays

String

wsAutoCloseDays

BigDecimal

swAutoCloseDays

BigDecimal

wwAutoCloseDays

BigDecimal

wfOrderLeadDays

BigDecimal

whCrossLinkInd

BigDecimal

wrongStReceiptInd

String

JSON Structure:

{
    "links": [],
    "allocMethod": "P",
    "applyProfPresStock": "N",
    "autoRcvStore": "Y",
    "closeOpenShipDays": 3,
    "costMoney": 7.5,
    "costOutStorage": 1.5,
    "costOutStorageMeas": "P",
    "costOutStorageUom": null,
    "costWhStorage": 1.5,
    "costWhStorageMeas": "P",
    "costWhStorageUom": null,
    "defaultAllocChrgInd": "Y",
    "defaultOrderType": "WAVE",
    "defaultSizeProfile": "N",
    "deptLevelTransfers": "Y",
    "distributionRule": "PRORAT",
    "duplicateReceivingInd": "N",
    "increaseTsfQtyInd": "N",
    "intercompanyTransferBasis": "T",
    "invHistLevel": "A",
    "locActivityInd": "Y",
    "locDlvryInd": "Y",
    "lookAheadDays": 7,
    "maxScalingIterations": null,
    "maxWeeksSupply": 5,
    "ordWorksheetCleanUpDelay": 1,
    "racRtvTsfInd": "A",
    "rejectStoreOrdInd": "N",
    "replOrderDays": 3,
    "rtvNadLeadTime": 1,
    "rtvUnitCostInd": "A",
    "shipRcvStore": "Y",
    "shipRcvWh": "Y",
    "storageType": "W",
    "storePackCompRcvInd": "Y",
    "wfDefaultWh": 1212,
    "targetRoi": 7,
    "tsfAutoCloseStore": "Y",
    "tsfAutoCloseWh": "Y",
    "tsfCloseOverdue": "Y",
    "simForceCloseInd": "NL",
    "tsfForceCloseInd": "SL",
    "tsfOverReceiptInd": "NL",
    "tsfMdStoreToStoreSndRcv": "S",
    "tsfMdStoreToWhSndRcv": "S",
    "tsfMdWhToStoreSndRcv": "S",
    "tsfMdWhToWhSndRcv": "S",
    "tsfPriceExceedWacInd": "Y",
    "ssAutoCloseDays": 1,
    "wsAutoCloseDays": 1,
    "swAutoCloseDays": 1,
    "wwAutoCloseDays": 1,
    "wfOrderLeadDays": null,
    "whCrossLinkInd": "Y",
    "wrongStReceiptInd": "Y",
    "hyperMediaContent": {
        "linkRDO": []
    }
}
Table Impact
TABLE SELECT INSERT UPDATE DELETE

INV_MOVE_UNIT_OPTIONS

Yes

No

No

No

JOB_AUDIT_LOGS

No

Yes

No

No

JOB_AUDIT_PAYLOAD

No

Yes

No

No
Get Procurement System Options
Business Overview

Retrieve Merchandising's Procurement Unit Options.

Service Type

GET

ReST URL
/Common/POSysOps
Input Parameters

N/A

Output

ProcurementUnitOptionsRDO

Parameter Name Data Type

backpostRcaRuaInd

String

calcNegativeIncome

String

copyPoCurrRate

String

costLevel

String

creditMemoLevel

String

dealAgePriority

String

dealLeadDays

BigDecimal

dealTypePriority

String

deptLevelOrders

String

ediCostOverrideInd

String

expiryDelayPreIssue

BigDecimal

genConsignmentInvcFreq

String

genConInvcItmSupLocInd

String

latestShipDays

BigDecimal

ordApprCloseDelay

BigDecimal

ordApprAmtCode

String

ordAutoClosePartRcvdInd

String

ordPartRcvdCloseDelay

BigDecimal

orderBeforeDays

BigDecimal

orderExchInd

String

otbSystemInd

String

rcvCostAdjType

String

reclassApprOrderInd

String

redistFactor

BigDecimal

softContractInd

String

wacRecalcAdjInd

String

JSON Structure:

{
    "links": [],
    "backpostRcaRuaInd": "N",
    "billToLoc": "1000",
    "calcNegativeIncome": "N",
    "copyPoCurrRate": null,
    "costLevel": "DNN",
    "creditMemoLevel": "D",
    "dealAgePriority": "O",
    "dealLeadDays": 1,
    "dealTypePriority": "P",
    "deptLevelOrders": "N",
    "ediCostOverrideInd": "Y",
    "expiryDelayPreIssue": 30,
    "genConsignmentInvcFreq": "M",
    "genConInvcItmSupLocInd": "I",
    "latestShipDays": 30,
    "ordApprCloseDelay": 1,
    "ordApprAmtCode": "C",
    "ordAutoClosePartRcvdInd": "N",
    "ordPartRcvdCloseDelay": 1,
    "orderBeforeDays": 5,
    "orderExchInd": "N",
    "otbSystemInd": "N",
    "rcvCostAdjType": "F",
    "reclassApprOrderInd": "Y",
    "redistFactor": 2,
    "softContractInd": "Y",
    "wacRecalcAdjInd": "N",
    "hyperMediaContent": {
        "linkRDO": []
    }
}
Table Impact
TABLE SELECT INSERT UPDATE DELETE

PROCUREMENT_UNIT_OPTIONS

Yes

No

No

No

JOB_AUDIT_LOGS

No

Yes

No

No

JOB_AUDIT_PAYLOAD

No

Yes

No

No