3 Setup Xstore Office Cloud Service
This chapter describes how to set up Xstore Office Cloud Service.
Post Provisioning Steps
After the environments are provisioned, customers can perform the following requests from the Xadmin UI:
Adding additional Org IDs
Adding Additional Organization IDs
By default Xstore Office Cloud Service is setup with a default organization ID. If you want to setup additional organization IDs or do not want to use the default organization ID, see the Organization Management section in the Oracle Retail Xstore Office Cloud Service User Guide, for more information about how to add an organization ID.
Note:
Org IDs cannot be changed, only added.
After the environments are provisioned, customers can file a service requests (SR) through the Oracle Ticketing System Service Requests for the following operations:
Updating Merchandise Hierarchy Level Labels
Configuring RTLog Generator
Integrating Oracle Retail Xstore Office Cloud Service (XOCS) with
-
Omnichannel Cloud Data Service (OCDS),
-
Merchandising Foundational Cloud Services (MFCS),
-
Oracle Retail Order Broker (OROB),
-
Oracle Retail Customer Engagement (ORCE),
-
Oracle Retail XBRi
Integrating Oracle Retail Xstore Office Cloud Service (XOCS) with External Applications
Creating Merchandise Hierarchy Level Labels
Merchandise Hierarchy Levels
The desired Merchandise Hierarchy Levels must be established before item creation/dataloading and enabling some integrations. For viewing and modifying each organization's Merchandise Hierarchy Level configuration, see the Oracle Retail Xstore Office Cloud Service User Guide.
Configuring RTLog Generator
RTLog generator for integration with Sales Audit (ReSA) through flat files is installed with default configurations during provisioning.
Customers need to submit an SR to update the configuration of the rtlog generation and specify if they want to integrate with ReSA CLOUD (through FTS or SFTP), or ReSA ON-PREMISES (through REST API)
The SR should contain the following information:
-
Environment where this change needs to be made (DEV (or UAT)/Stage/Prod)
-
RTLog Generator RESA integration type (Delivery Target): (ReSA CLOUD or ReSA ON-PREMISES)
-
RTLog Generator Data Transfer Protocol (Deploy Type): REST or SFTP or FTS
-
If the Data Transfer Protocol is REST, no additional info is required. Customers are responsible to call REST API provided by RTLog generator to download RTLog files and upload them to Sales Audit (ReSA). Do not confuse this option as the one to integrate with ReSA through direct REST calls.
-
If the Data Transfer Protocol is SFTP, then:
-
RESA SFTP Host: SFTP Host name (CLOUD only)
-
RESA SFTP User: SFTP username (CLOUD only)
-
RESA SFTP working directory: SFTP working directory (CLOUD only)
-
-
If the Data Transfer Protocol is FTS, then:
-
FTS Endpoint url: FTS Endpoint URL
-
Note:
Important
Customers need to submit an SR to update the configuration of the rtlog generation and specify if they want to integrate with ReSA CLOUD (through SFTP or FTS), or ReSA ON-PREMISES (through REST API).
Integrating XOCS with OCDS, MFCS, OROB, ORCE, XBRi
Integrating with OCDS, MFCS, OROB, ORCE and XBRi although done through Xadmin UI (refer to the Oracle Retail Xstore Office Cloud Service User Guide) requires that the retailer submits an SR for Oracle Cloud networking to allow the OCDS, OROB, ORCE, XBRi endpoints/(https or sftp) to egress out the Oracle outbound proxy.
The SR should contain the following information. Please refer to Allowlisting External URLs that Integrate with Oracle Retail Xstore Office Cloud Service (Doc ID 2772905.1):
-
Environment where this change needs to be made (DEV (or UAT)/Stage/Prod). Please provide the URL of the environment.
-
Indicate the Cloud Service with which to integrate along with the https or sftp endpoint details.
Integrating XOCS with External Applications
Integrating with External Applications although done through the Xadmin UI (refer to the Oracle Retail Xstore Office Cloud Service User Guide) requires that the retailer submits an SR for Oracle Cloud networking to allow the External Application endpoints (https or sftp) to egress out the Oracle outbound proxy.
The SR should contain the following information. Please refer to Allowlisting External URLs that Integrate with Oracle Retail Xstore Office Cloud Service (Doc ID 2772905.1)
-
Environment where this change needs to be made (DEV (or UAT)/Stage/Prod). Please provide the URL of the environment.
-
Indicate the External Application’s (https or sftp) endpoint details.
Environments
A fully provisioned account has both a production environment and a staging environment. No one other than Oracle Cloud Operations (CloudOps) personnel can have direct access to any of the cloud environments.
Implementation teams access Xstore Office Cloud Service through the Xadmin UI or through REST web service APIs. See the Oracle Retail Xstore Suite Services Guide and the Oracle Retail Xstore Office Cloud Service User Guide for detailed information on features available in Xstore Office Cloud Service.
The figure below shows the integration data flows and the corresponding webservices APIs that are available in Xstore Office Cloud Service.
Figure 3-1 Xstore Office Cloud Service Integration Data Flow
![Xstore Office Cloud Service Integration Data Flow Xstore Office Cloud Service Integration Data Flow](img/int_model.png)
As you can see from the diagram in above Xstore Office Cloud Service does not have its own SFTP server.
Xstore Office Cloud Service does not use a WebDAV server for file deployments and pospoll uploads.
To get data from/upload data to XOCS the retailer will need to use the REST APIs documented in the Oracle Retail Xstore Suite Services Guide (My Oracle Support Doc ID: 1994467.1). The guide has details on invoking the File Rest API to PUT/GET/DELETE and view listing of the files in containers.
Another thing worth mentioning is that XOCS environments are provisioned with empty Xcenter and Replication databases and minimum required data in Xadmin database.
It will be responsibility of the retail/SI partner teams to load data in XOCS. Refer to Data Seeding on how to load data in XOCS.
UI Access
At the time of provisioning, the client is provided with an administrative user account (Delegated Customer Admin) on all cloud environments. Each user on the system, including anyone involved with the implementation requiring access to the system, must be provided with an individual account on the service. Accounts can be requested from the Customer Admin on the account. See User Setup for more details.
Web Service Access and Usage
In order to invoke the REST APIs provided by XOCS you first need to setup an OAuth Client.
Follow the instructions in the Oracle Retail Xstore Office Cloud Service Security Guide to create an OAuth Client. Specifically the "Xstore Office Setup App".
Example with curl
https://docs.oracle.com/en/industries/retail/index.html
See the Xcenter Endpoints section of the Oracle Retail Xstore Suite Services Guide (My Oracle Support Doc ID: 1994467.1) for details and examples on invoking the File Rest API to PUT/GET/DELETE and view listing of the files in containers.
Data Seeding
After the environments are provisioned the retailer/SI partners will need to load data in Xstore Office Cloud Service.
The data types are generally loaded either through OCDS or MFCS (when using Oracle Merchandising and Pricing cloud Services), REST APIs or Xadmin UI (not recommended).
Organization Hierarchy is the first data set that needs to be loaded in Xstore Office Cloud Service. Organization Hierarchy is required in order for the primary Xadmin user to be able to assign roles for other Xadmin users for specific organizations.
Organization Hierarchy
The provisioning process or Adding Additional Organization IDs should have set up the merchant's organization IDs.
Further creation of the hierarchy can be done via Xadmin UI, uploaded via REST (.mnt and/or .xload file format), or imported through integration OCDS/MFCS.
See the Oracle Retail Xstore Office Cloud Service User Guide on more information about managing the organization hierarchy through Xadmin UI:
See the Web Service Access and Usage section for information on how to create an OAuth client and invoke the REST APIs.
Note:
At least the top level node (*:*) for an organization needs to be setup via one of the methods mentioned above.
Organization Hierarchy is required even when XOCS is integrated with OCDS, even though the integration with OCDS is expected to bring the entire organization hierarchy data into Xstore Office Cloud Service.
Once the organization hierarchy is loaded you can:
-
Configure the integrations and/or configure the broadcasters (refer to the Setup Integrations section in this document)
-
Setup users (refer to the User Setup section in this document)
-
Continue to load the other data (tax location, retail stores, items, departments and so on). Refer to the Other Retail Data section below.
Other Retail Data
This section describes other retail data.
Tax Location
Before loading the retail stores, tax location data set will have to be loaded via a data load file (.mnt, .xload) or through REST API.
See the example below for a sample of a Tax Location:
<Header line_count="13" download_id="123" application_date="2018-11-06"
/> INSERT~XML_PERSISTABLES~<ConfigData><dao name="TaxLocation" cmd="INSERT_OR_
UPDATE|UPDATE"><fld id="OrganizationId" val="10"/><fld id="TaxLocationId"
val="TL-1000"/><fld id="CreateDate" val="1525803068534"/><fld id="CreateUserId"
val="XADMIN"/><fld id="UpdateDate" val="1541542977883"/><fld id="UpdateUserId"
val="XADMIN"/><fld id="OrgCode" val="*"/><fld id="OrgValue" val="*"/><fld
id="Description" val="Ohio Tax Location"/><fld id="Name" val="Ohio
Tax Location"/><originDS>Local</originDS></dao></ConfigData> INSERT~XML_PERSISTABLES~<ConfigData><dao
name="TaxLocation" cmd="INSERT_OR_ UPDATE|UPDATE"><fld id="OrganizationId"
val="10"/><fld id="TaxLocationId" val="TL-2000"/><fld id="CreateDate"
val="1525803068538"/><fld id="CreateUserId" val="XADMIN"/><fld id="UpdateDate"
val="1541542977883"/><fld id="UpdateUserId" val="XADMIN"/><fld id="OrgCode"
val="*"/><fld id="OrgValue" val="*"/><fld id="Description" val="Illinois
Tax Location"/><fld id="Name" val="Illinois Tax Location"/><originDS>Local</originDS></dao></ConfigData>
INSERT~XML_PERSISTABLES~<ConfigData><dao name="TaxLocation" cmd="INSERT_OR_
UPDATE|UPDATE"><fld id="OrganizationId" val="10"/><fld id="TaxLocationId"
val="TL-AT"/><fld id="CreateDate" val="1525803068540"/><fld id="CreateUserId"
val="XADMIN"/><fld id="UpdateDate" val="1541542977883"/><fld id="UpdateUserId"
val="XADMIN"/><fld id="OrgCode" val="*"/><fld id="OrgValue" val="*"/><fld
id="Description" val="AT Tax Location"/><fld id="Name" val="AT Tax
Location"/><originDS>Local</originDS></dao></ConfigData> INSERT~XML_PERSISTABLES~<ConfigData><dao
name="TaxLocation" cmd="INSERT_OR_ UPDATE|UPDATE"><fld id="OrganizationId"
val="10"/><fld id="TaxLocationId" val="TL-BR_SP"/><fld id="CreateDate"
val="1525803068559"/><fld id="CreateUserId" val="XADMIN"/><fld id="UpdateDate"
val="1541542977883"/><fld id="UpdateUserId" val="XADMIN"/><fld id="OrgCode"
val="*"/><fld id="OrgValue" val="*"/><fld
id="Description" val="Brazil State - SAO PAULO"/><fld id="Name" val="Brazil
State
- SAO PAULO"/><originDS>Local</originDS></dao></ConfigData> INSERT~XML_PERSISTABLES~<ConfigData><dao
name="TaxLocation" cmd="INSERT_OR_ UPDATE|UPDATE"><fld id="OrganizationId"
val="10"/><fld id="TaxLocationId" val="TL-DE"/><fld id="CreateDate"
val="1525803068542"/><fld id="CreateUserId" val="XADMIN"/><fld id="UpdateDate"
val="1541542977883"/><fld id="UpdateUserId" val="XADMIN"/><fld id="OrgCode"
val="*"/><fld id="OrgValue" val="*"/><fld id="Description" val="DE
Tax Location"/><fld id="Name" val="DE Tax Location"/><originDS>Local</originDS></dao></ConfigData>
INSERT~XML_PERSISTABLES~<ConfigData><dao name="TaxLocation" cmd="INSERT_OR_
UPDATE|UPDATE"><fld id="OrganizationId" val="10"/><fld id="TaxLocationId"
val="TL-ES"/><fld id="CreateDate" val="1525803068543"/><fld id="CreateUserId"
val="XADMIN"/><fld id="UpdateDate" val="1541542977883"/><fld id="UpdateUserId"
val="XADMIN"/><fld id="OrgCode" val="*"/><fld id="OrgValue" val="*"/><fld
id="Description" val="ES Tax Location"/><fld id="Name" val="ES Tax
Location"/><originDS>Local</originDS></dao></ConfigData>
INSERT~XML_PERSISTABLES~<ConfigData><dao name="TaxLocation" cmd="INSERT_OR_
UPDATE|UPDATE"><fld id="OrganizationId" val="10"/><fld id="TaxLocationId"
val="TL-FR"/><fld id="CreateDate" val="1525803068545"/><fld id="CreateUserId"
val="XADMIN"/><fld id="UpdateDate" val="1541542977883"/><fld id="UpdateUserId"
val="XADMIN"/><fld id="OrgCode" val="*"/><fld id="OrgValue" val="*"/><fld
id="Description" val="FR Tax Location"/><fld id="Name" val="FR Tax
Location"/><originDS>Local</originDS></dao></ConfigData> INSERT~XML_PERSISTABLES~<ConfigData><dao
name="TaxLocation" cmd="INSERT_OR_ UPDATE|UPDATE"><fld id="OrganizationId"
val="10"/><fld id="TaxLocationId" val="TL-GB"/><fld id="CreateDate"
val="1525803068547"/><fld id="CreateUserId" val="XADMIN"/><fld id="UpdateDate"
val="1541542977883"/><fld id="UpdateUserId" val="XADMIN"/><fld id="OrgCode"
val="*"/><fld id="OrgValue" val="*"/><fld id="Description" val="GB
Tax Location"/><fld id="Name" val="GB Tax Location"/><originDS>Local</originDS></dao></ConfigData>
INSERT~XML_PERSISTABLES~<ConfigData><dao name="TaxLocation" cmd="INSERT_OR_
UPDATE|UPDATE"><fld id="OrganizationId" val="10"/><fld id="TaxLocationId"
val="TL-IT"/><fld id="CreateDate" val="1525803068549"/><fld id="CreateUserId"
val="XADMIN"/><fld id="UpdateDate" val="1541542977883"/><fld id="UpdateUserId"
val="XADMIN"/><fld id="OrgCode" val="*"/><fld id="OrgValue" val="*"/><fld
id="Description" val="IT Tax Location"/><fld id="Name" val="IT Tax
Location"/><originDS>Local</originDS></dao></ConfigData> INSERT~XML_PERSISTABLES~<ConfigData><dao
name="TaxLocation" cmd="INSERT_OR_ UPDATE|UPDATE"><fld id="OrganizationId"
val="10"/><fld id="TaxLocationId" val="TL-MX"/><fld id="CreateDate"
val="1525803068555"/><fld id="CreateUserId" val="XADMIN"/><fld id="UpdateDate"
val="1541542977883"/><fld id="UpdateUserId" val="XADMIN"/><fld id="OrgCode"
val="*"/><fld id="OrgValue" val="*"/><fld id="Description" val="MX
Tax Location"/><fld id="Name" val="MX Tax Location"/><originDS>Local</originDS></dao></ConfigData>
INSERT~XML_PERSISTABLES~<ConfigData><dao name="TaxLocation" cmd="INSERT_OR_
UPDATE|UPDATE"><fld id="OrganizationId" val="10"/><fld id="TaxLocationId"
val="TL-NL"/><fld id="CreateDate" val="1525803068551"/><fld id="CreateUserId"
val="XADMIN"/><fld id="UpdateDate" val="1541542977883"/><fld id="UpdateUserId"
val="XADMIN"/><fld id="OrgCode" val="*"/><fld id="OrgValue" val="*"/><fld
id="Description" val="NL Tax Location"/><fld id="Name" val="NL Tax
Location"/><originDS>Local</originDS></dao></ConfigData> INSERT~XML_PERSISTABLES~<ConfigData><dao
name="TaxLocation" cmd="INSERT_OR_ UPDATE|UPDATE"><fld id="OrganizationId"
val="10"/><fld id="TaxLocationId" val="TL-PT"/><fld id="CreateDate"
val="1525803068553"/><fld id="CreateUserId" val="XADMIN"/><fld id="UpdateDate"
val="1541542977883"/><fld id="UpdateUserId" val="XADMIN"/><fld id="OrgCode"
val="*"/><fld id="OrgValue" val="*"/><fld id="Description" val="PT
Tax Location"/><fld id="Name" val="PT Tax Location"/><originDS>Local</originDS></dao></ConfigData>
INSERT~XML_PERSISTABLES~<ConfigData><dao name="TaxLocation" cmd="INSERT_OR_
UPDATE|UPDATE"><fld id="OrganizationId" val="10"/><fld id="TaxLocationId"
val="TL-SE"/><fld id="CreateDate" val="1525803068557"/><fld id="CreateUserId"
val="XADMIN"/><fld id="UpdateDate" val="1541542977883"/><fld id="UpdateUserId"
val="XADMIN"/><fld id="OrgCode" val="*"/><fld id="OrgValue" val="*"/><fld
id="Description" val="SE Tax Location"/><fld id="Name" val="SE Tax
Location"/><originDS>Local</originDS></dao></ConfigData>
If integrations to Oracle Retail Merchandise Cloud Service have been set up, data will be loaded through OCDS/MFCS. See the Oracle Retail Xstore Suite/Merchandising Suite Implementation Guide for more information.
Retail Stores
Stores can be created either through Xadmin UI, upload via REST (.mnt, .xload) or through integrations with OCDS or MFCS. See the Oracle Retail Xstore Office Cloud Service User Guide on more information about managing retail stores through Xadmin UI.
Other Foundation Data
Item, Merchandise Hierarchy, and so on can be loaded via the Xadmin UI, file upload via REST (.mnt, .xload files), or through integrations with OCDS or MFCS (these integrations will retrieve the data, create .mnt files and schedule deployments for .mnt files to be processed by data loader at stores).
Report Organizer
Flash Sales reports displayed in the Xadmin UI require the existence of rpt_organizer records. Creation of records in Xcenter’s rpt_organizer table are the responsibility of the Retailer.
To populate the rpt_organizer table a mnt file can be created and uploaded to Xstore Office Cloud Service for each organization. See the Oracle Retail Xstore Point of Service Host Interface Guide for details about creating an mnt file with content similar to the following:
<Header line_count="5" destination="XCENTER_ONLY" />
INSERT|REPORT_ORGANIZER|FLASH_SALES|SALES|GROSSSALES|10
INSERT|REPORT_ORGANIZER|FLASH_SALES|SALES|NETSALES|20
INSERT|REPORT_ORGANIZER|FLASH_SALES|SALES|RETURNS|30
INSERT|REPORT_ORGANIZER|FLASH_SALES|SALES|DISCOUNTS|40
INSERT|REPORT_ORGANIZER|FLASH_SALES|SALES|TOTALTAX|50
Data Loading
Data can be deployed to the Xcenter database (and stores) by using the REST web service to put a file in the "autodeploy" directory. Review the details of the service in the Oracle Retail Xstore Suite Services Guide from the online documentation. For more information about the "autodeploy" feature, see the Oracle Retail Xstore Office Cloud Service User Guide on how to Automatically Deploy Data Manager Changes and Data Manager Automatic Deployment Time.
Call this service via REST like PUT:
https://<host>:<port>/<tenancy_id>/xcenter/rest/DEFAULT/20/file/autodeploy/1000/mydatafile.mnt
where <tenancy_id> references the prod, stage or dev (or uat) environment.
See the Web Service Access and Usage section for information on how to create an OAuth client and invoke the REST APIs.
User Setup
A Customer Administration User will be created as part of the Xstore Office Cloud Service provisioning process. Before end users can access the Xstore Office Cloud Service application it is necessary to create and provision users. This includes provisioning access to the system, assigning organizations, a role and org nodes to each user to control what functionality will be available to them.
Upload an org hierarchy .mnt file(s) by invoking the File Resource REST API before trying to setup users. Details on the File Resource REST API are in the Oracle Retail Xstore Suite Services Guide. Details on the credentials needed for invoking any REST API is in the Oracle Retail Xstore Office Cloud Service Security Guide.
Users can be created via the Identity Cloud Service (IDCS) or the Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) UI. Refer to the Oracle Cloud Administering Oracle Identity Cloud Service Guide on the steps how to create users via the Identity Cloud Service (IDCS) UI. Refer to the Oracle Cloud Infrastructure Documentation on the steps how to create users.
The ability to add and edit users through the Xadmin UI is no longer available. The users are synchronized from IDCS or OCI (IAM) at a configurable interval. The Xadmin UI still supports the ability to assign locales, organizations, roles and organization nodes to a user (see the Oracle Retail Xstore Office Cloud Service User Guide).
User Roles and Security
User roles, role groups, and security configurations in general are administered through the Xadmin User Management UI (see the Oracle Retail Xstore Office Cloud Services User Guide).
Setup Integrations
Integrations can be configured through the Xadmin UI.
Refer to the Integrations chapter in this document for more information.
Setup Xstore Registers for Xstore Office Cloud Service
Any Xstore register that communicates with Xstore Office Cloud Service must first be enrolled in IDCS or OCI IAM via Xstore Office Cloud Service. This can be done either via Xadmin On-Premise or Xenvironment. Refer to the Oracle Retail Xstore Office Cloud Service Security Guide about the steps to be followed for Cloud Enrollment of Xstore Clients.