Webservice Integration Configuration

Xstore Office: Direct Service Integration Communication

Configuration of the direct service integration involves self-service activities on both sides of the configuration. For Merchandising and POM configurations required for direct service integration from Merchandising and Pricing, see the sections Merchandising Configuration and POM Configuration below.

Note:

When these services are initialized, some services need a few hours for initial data processing before they can be used. It is recommended to enable these services a day in advance before Xstore Office starts subscribing

For Merchandising and POM configurations required for direct service integration from Merchandising and Pricing, see the sections Merchandising Configuration and POM Configuration below.

Merchandising Configuration

To enable direct service integration, Oracle Retail Xstore Suite needs to be selected to have service based integration in the Integration section of System Options screen in Merchandising. For more information on System Options, refer to the Oracle Retail Merchandising Foundation Cloud Service Implementation Guide.

POM Configuration

These services are operationalized by background processes that can be enabled and configured for running frequency in the Batch Administration screen of POM. For more information on these batch jobs, refer to the Oracle Retail Merchandising Foundation Cloud Service Operations Guide.

Xstore Office Configuration

The direct service integration is set up through the Xadmin Integration Management feature and are stored in the Xstore Office database.

Table 4-1 RMFCS Connection Configuration

Fields Description

Fields	Description
`Endpoint URL`	A URL describing protocol, host name, port and namespace of the Merchandising and Pricing Web Services. Example: `https://XXX.XXXXXX.XX-XXXX-X.ocs.oraclecloud.com/rgbu-XXX-XXXX-XXXX-mfcs`
`Merchandising Chain ID(s)`	A comma separated list of the chain ids in Merchandising containing stores in the Xstore Organization.
`Oracle Retail Pricing Cloud Service`	Choice of V1 or V2 RPCS APIs for regular price change, clearance, and promotion integrations.

Endpoint URL

A URL describing protocol, host name, port and namespace of the Merchandising and Pricing Web Services.

Example: https://XXX.XXXXXX.XX-XXXX-X.ocs.oraclecloud.com/rgbu-XXX-XXXX-XXXX-mfcs

Merchandising Chain ID(s)

A comma separated list of the chain ids in Merchandising containing stores in the Xstore Organization.

Oracle Retail Pricing Cloud Service

Choice of V1 or V2 RPCS APIs for regular price change, clearance, and promotion integrations.

Xstore Office: OCDS Integration Communication

Xstore Office requests changes to Merchandising and Pricing data in OCDS by calling the REST web services.

The properties for the OCDS integration are set up through the Xadmin Integration Management feature and are stored in the Xstore Office Cloud Service database.

Table 4-2 OCDS Connection Configuration

Fields	Description
`Endpoint URL`	A URL describing protocol, host name, and port of the OCDS Web Services. Example: `https://XXX-XXXX-ribcs-rics.oracleindustry.com`
Service Path Prefix	The root service path for OCDS. Example: `/ords/ocds/omnichannel`
`OCDS Chain ID(s)`	A comma separated list of the chain ids in the Merchandising system containing stores in the Xstore Organization.
`Username`	The username used to authenticate web service communication with OCDS.
`Password`	The password used to authenticate web service communication with OCDS.

Xstore Office: Additional OCDS/MFCS Configuration Options

Xadmin Integration Management feature includes the flowing configuration options which appear in the configuration wizard for both OCDS and MFCS configurations.

Table 4-3 Additional OCDS/MFCS Configuration Options

Setting	Description
Timeout Connect	Number of seconds to wait for connection.
Timeout Read	Number of seconds to wait for completion of response data.
Enabled Data Types	The types of data to be requested by Xstore Office. Once data starts flowing this selection should not be changed. Typically all data types are enabled unless not using VAT or (very uncommon) price/promotion.
Retain Job History	The number of days to retain Job History data in the Xadmin database.
Scheduled Job Interval Minutes	This is the frequency with which Xadmin requests data from OCDS/MFCS. The value should be greater than or equal to 30 minutes.
On Demand Job Interval Minutes	This is the maximum amount of time that will elapse between when an on-demand job is created and is executed. The value should be greater than or equal to 5 minutes.
Orphan Data Protection Offset Seconds	This is the minimum amount of time data must age before it can be visible to Xstore Office. The offset helps to prevent related-data from becoming orphaned due to system latency. The value should be greater than or equal to 30 seconds.
Records Per Request Limit	This specifies the number of records to request in webservice calls. If no limit is defined then MFCS/OCDS will determine the maximum number of records.
Retail Location: Till Accountability	This specifies if Retail Locations/Stores created from data are to use Till Accountability or not.
Retail Location: Default Locale	This specifies the Locale to use in Retail Locations created from data when a LANG_ISO_CODE is not defined for a location. This setting defines the value assigned to a Retail Location in the Xstore database if the store was not assigned a Locale in Merchandising
Item: Tax Group ID for non-taxable Items	This specifies the Tax Group ID assigned to non-taxable items created from MFCS/OCDS data.
Item: Include future date to determine VAT code with the greatest active date	This specifies if future date should be included to determine VAT code with the greatest active date.
VAT Rounding Code	Specifies how the system will round when calculating the tax amount.
VAT Rounding Digits	Specifies how many decimal places to round to when calculating the tax amount. The minimum rounding digit is 0 and the maximum rounding digit is 10.
VAT Rounding at Transaction Level	Specifies the ability to round at transaction level when calculating the tax amount. When the calculated tax will be rounded at the transaction level. When unchecked, the calculated tax is rounded at the line item level.

Merchandising Chain to Xstore Organization Mapping

The Xstore Suite provides the opportunity to organize data by Organization, where centralized and store-level data can be isolated according to a retail organization structure. The Merchandising Cloud Services supports the use of one or more Chains, where a chain can be used to group various store formats.

The Integration in the On Premise and Cloud Xstore Office requires that at least one Merchandising Chain be mapped to an Xstore Organization. This configuration must not be changed once the mapping is established.

Oracle Retail Pricing Cloud Service Version

The Xstore Suite gives a customer the choice of using V1 or V2 RPCS APIs for regular price change, clearance, and promotion integrations. V1 is deprecated. V2 is backward compatible and serves as the default for new integrations. Existing integrations will continue to use V1 until the customer decides to switch through Xadmin integration UI.

V2 provides additional support for

Promotion Distribution Rule, see the Promotions section for more details

Integration Database Tables

There are three database tables in the Xadmin database that are exclusively used for integration with Merchandising and Pricing for both integration methods described in this document. See the Oracle® Retail Xstore Point-of-Service Software Database Dictionary for complete details on these tables.

Table 4-4 Integration Database Tables

Table Name	Description
OCDS_JOB_HISTORY	When enabled in Xadmin, an integration job is executed by scheduled-interval or on-demand, to detect foundation data changes in integration service and extract them out into .mnt files. An entry in this table records the status, start/end time and other information of a job executed.
OCDS_ON_DEMAND	An entry in this table represents an on-demand job request. On-demand jobs can be system generated (as in the case of new store detection), or user generated (from the Xadmin UI).
OCDS_SUBTASK_DETAILS	An integration job executes a list of subtasks. Each subtask represents a foundation data area to detect and extract out changes. The table defines metadata for all subtasks. For a scheduled job, each and every active subtask is executed. For an on-demand job, a subset of subtasks specified for the job is executed.

The only table that requires seed data is the OCDS_SUBTASK_DETAILS; the other two tables will populate during operations of the integrations.

Enabling and Disabling Data Types

Retailers can determine the types of data requested from the integration service by Xstore Office. For example, if VAT information is not needed, then the integration can be configured to prevent requests for VAT data.

In Xstore Office Service's Integration Manager, use the Configure tab when completing the wizard UI to establish the integration.

Migration to MFCS

By default on the initial run of the MFCS integration’s scheduled job, Xstore Office will request all data from the source system that has changed since the Unix epoch (January 1st, 1970 at 00:00:00 UTC). Use of the Unix epoch effectively means: “request all data changes since the beginning of time”. Alternatively, a more recent point in time can be configured when creating a new MFCS integration in Xadmin’s Integration Manager.

Migration: OCDS to MFCS

Two steps can be taken to avoid a requesting a full-refresh of MFCS data, and the replacement of all OCDS data, when a newly created MFCS integration’s first scheduled job is run.

Select “Preserve job history records” when deleting the OCDS integration.
Set the Data Retrieval Start Date and Start Time on the Configure tab when defining the MFCS integration to the point in time that ensures that Xstore Office will request MFCS data that primarily is not already duplicated by data pulled from OCDS. To assist in determined the optimal point in time, the UI fields is populated with the last time the OCDS integration successfully ran a schedule job (if step #1 was used).

Migration: Non OCDS Merchandsing System to MFCS

Retailers with an existing enterprise populated from an old merchandising/pricing system may prefer the integration with the new system begin from a much more recent point in time. Set the Data Retrieval Start Date and Start Time on the Configure tab when defining the MFCS integration to the point in time that ensures that Xstore Office will request MFCS data that primarily isn’t already duplicated by data pulled from the old system.

Purging on Full Refresh

The MFCS/OCDS integration can generate (purge) and deploy mnt files containing instructions to delete merchandising and pricing data in two use-cases:

When a scheduled job has no job history.
When an on-demand job is requested from Xadmin’s Data Publisher feature.

Select the desired Purge Integration Data checkboxes in Integration Manager’s Configure tab when defining the integration to enable the generation of purge files.

Download: Immediate vs Store Close

The OCDS_SUBTASK_DETAILS table includes the column DOWNLOAD_TIME, which specifies when .mnt files should be downloaded for data loading at the store. The column contains null for those Subtasks that only populate the Xcenter database. The out-of-the-box seed data is configured so that only Pricing data will flow to the store immediately.

"NOT ON FILE" Items

The integration has been designed to not import items that represent an Xstore “NOT ON FILE" item. The integration compares Item Ids of item records in the Xstore Office database having the type code “NOT_ON_FILE" with item records in REST responses from the integration system so that it can skip records having the same item ID as an Xstore “NOT ON FILE" item.