17 AI Foundation Web Services
This chapter provides an overview of the AI Foundation Web Services. For additional details about any interfaces, see Oracle Retail Insights Cloud Service Suite/Oracle Retail Analytics and Planning Cloud Services Data Interface.
AI Foundation Web Services
AI Foundation web services provide access to DB-bound configurations when a direct connection to the database is not desirable or possible; intra-day and ad-hoc access to certain application outputs is also provided. AI Foundation web services are REST-based; it is assumed that you are familiar with basic REST principles (such as the usage of HTTP verbs). AI Foundation web services provide access to a subset of application and output data, but do not fully mirror the user interface or export and import features of the backend. They are not a replacement for bulk data export, which must be done on a schedule as part of batch processing. However, access to the configuration can be used during implementation and upgrade periods, and AC and ASO export web services can serve as a means of obtaining incremental update data from a specified point in time (driven by a query parameter) as a means of intra-day processing.
All services support the query parameter contentType and the HTTP header Content-Type, with the supported values application/json and application/xml. The query parameter takes precedence; if no content type is supplied, then application/json serves as the default.
The AC and ASO export services have a dateMask query parameter that must adhere to the Java java.text.SimpleDateFormat rules (for example, dateMask=yyyyMMdd&exportDate=20151012). All date parameters must be sent in this format, and output dates and timestamps are returned according to this format.
The json/XML structure follows the corresponding DB table and view while being converted to the Java standard. That is, underscores are removed, camel case is used, and first letter is lowercase. For example, the RSE_CONFIG APPL_CODE column is returned as applCode. All data is returned as type string.
Authentication and Authorization
Basic authentication is used, so you may use any client software that supports it. Authorization is done for ADF-LDAP (OID) mapped roles, and only administrator roles are used (that is, the calling user must be in a duty that is mapped to the roles in Table 17-1).
Table 17-1 Mapped Administrator Roles
Service | Role | Mapped Role |
---|---|---|
DT |
DemandTransferenceRole |
ANALYTIC_EXPERT_JOB |
CDT |
CustomerDecisionTreeRole |
ANALYTIC_EXPERT_JOB |
AC |
StoreClusterAdvancedRole |
CLUSTERING_ADMINISTRATOR_JOB |
ASO |
Administrator |
SPACE_ADMINISTRATOR_JOB |
CS |
CustomerSegmentAdvancedRole |
CUSTOMER_SEGMENT_ADMINISTRATOR_JOB |
Summary of Web Services
This section provides a summary of web services.
Access to RSE_CONFIG Table
Fetch Config Data
GET on /rase/resources/rse/parameters returns all RSE_CONFIG entries a specific user has access to (that is, all applCode RSE entries plus corresponding application entries). For example, if a user is in the ASO Administrator role, then the applCode SO will be returned as well. Here is a list of the fields:
-
applCode
-
paramName
-
paramValue
-
configurableFlg.
-
efere
Fetch One Entry
GET on applCode,paramName. For example, /rase/resources/rse/parameters/RSE,PRIMARY_LANGUAGE_CODE returns a particular entry if the user has access to it.
Create an Entry
POST to /rase/resources/rse/parameters with a form having a single field called "content" and a value having the appropriate new parameter data in content type as specified by query parameter and header, if the user has access to it. The structure of the content must match what is returned by GET.
Update an Entry
PUT to applCode,paramName. For example, /rase/resources/rse/parameters/RSE, LOC_HIER_TYPE, with the form having fields called paramName, paramValue, efere, and configurableFlg, along with appropriate values, if the user has access to it.
Batch Update Entries
PUT to /rase/resources/rse/parameters with a form having a single field called "content" and a value having appropriate parameter data in the content type as specified by the query parameter and header. Note that if the user does not have access to a particular entry, it will be skipped. The structure of the content must match what is returned by GET.
Access to RSE_CONFIG_CODE Table
Fetch Data for an Entry
GET on applCode,paramName, paramCode. For example, /rase/resources/rse/parameters/DT,SIM_DISPLAY_CODE_PCT,2 returns data, if user has access to it.
-
applCode
-
paramName
-
paramCode
-
paramValue
-
configurableFlg
-
efere
Create an Entry
POST to applCode,paramName,paramCode. For example, /rase/resources/rse/parameters/DT,SIM_DISPLAY_CODE_PCT,2} with a form having a single field named "content" and a value having appropriate new parameter data in the content type as specified by query parameter and header, if the user has access to it. The structure of the content must match what is returned by GET.
Update an Entry
PUT to applCode,paramName, paramCode, For example, /rase/resources/rse/parameters/DT,SIM_DISPLAY_CODE_PCT,2 with form having a single field named "content" and a value having appropriate parameter data in the content type as specified by query parameter / header, if user has access to it.The structure of the content must match what is returned by GET.
Delete an Entry
DELETE to applCode,paramName, paramCode. For example, /rase/resources/rse/parameters/DT,SIM_DISPLAY_CODE_PCT,2, if the user has access to it.
Advanced Clustering Export
This section describes Advanced Clustering export.
Get Clusters
This service is based on rsestrclst.csv.
GET on /rase/resources/cis/export/cluster.
Parameters (in addition to dateMask and contentType) are all joined by logical AND:
Table 17-2 Advanced Clustering Export Parameters
Name | gType | Required | Query Logic for Corresponding Column if Parameter is Provided |
---|---|---|---|
exportedDt |
Date |
Required |
Greater than or equal to this value |
effStartDt |
Date |
Required |
Greater than or equal to this value |
effEndDt |
Date |
Required |
Less than or equal to this value |
prodHierTypeExtKey |
String |
Required |
Equal to this value [] |
prodExtKey |
String |
Required |
Equal to this value |
locExtKey |
String |
Required |
Equal to this value |
locHierTypeExtKey |
String |
Required |
Equal to this value |
Customer Segment Export
This section describes Customer Segment export.
Get Segments
This service is based on rsestrclst.csv.
GET on /rase/resources/cis/export/segment.
Parameters (in addition to dateMask and contentType) are all joined by logical AND:
Table 17-3 Customer Segment Export Parameters
Name | Type | Query Logic for Corresponding Column if Parameter is Provided |
---|---|---|
exportedDt |
Date |
Greater than or equal to this value |
effStartDt |
Date |
Greater than or equal to this value |
effEndDt |
Date |
Less than or equal to this value |
prodExtKey |
String |
Equal to this value |
AIF Integration with ORCE (Customer Engagement)
This integration enables the application to send approved customer segments into Oracle Retail Customer Engagement (ORCE). Whenever customer segments are approved for merchandise, location in the application, a web service call is made to ORCE in order to save segments, along with its members and relevant attributes.
Credential Store
You can use the Manage Credential Stores screen, shown in Figure 17-1, to maintain ORCE credentials in the application.
Enter the following information into Manage Credential Stores:
Table 17-4 Manage Credential Stores Information
Field | Description |
---|---|
Username |
Credential username created by ORCE to enable integration |
Password |
Credential password (at least one character) created by ORCE to enable integration |
Confirm Password |
Confirm password |
Description |
Credential store used for Customer Segment integration with Oracle Customer Engagement |
Configuration
The following configuration must be updated for integration. By default, ORCE integration is disabled.
Table 17-5 Configuration
Configuration | Description |
---|---|
CUST_SEG_WS_RELATE_FLG |
Flag to identify whether to publish customer segment to customer engagement. (Y/N) |
CUST_SEG_WS_RELATE_ORGID |
ORGID is the 3-letter ID provided by Oracle Customer Engagement to create and implement an authentication key. (REL) |
CUST_SEG_ATTR_WS_RELATE_FLG |
Flag to identify whether to publish customer segment attribute to customer engagement. (Y/N) |
CUST_SEG_RELATE_HOSTNAME |
URL host name to publish customer segment to customer engagement. This should be same as the CN name in the certificate. |
CUST_SEG_RELATE_PORT |
Port number to publish customer segment to customer engagement. |
CUST_SEG_REL_SEGSERV_VERSION |
Segment service version to use for publishing customer segment to customer engagement. (format vX_0 - v3_0) |
CUST_SEG_REL_PROXY_HOSTNAME |
Proxy host name to publish customer segment to customer engagement. |
CUST_SEG_REL_HTTP_PROXY_PORT |
HTTP proxy port number to publish customer segment to customer engagement. |
CUST_SEG_REL_HTTPS_PROXY_PORT |
HTTPS proxy port number to publish customer segment to customer engagement. |
CUST_SEG_REL_BATCH_SIZE |
Number of customers to add in batches after customer segment to customer engagement is published. |
ASO Exports
This section describes ASO exports.
AIP/Replenishment Results
This service is based on so_assort_aiprepl_int.csv.
GET on /rase/resources/so/export/soAssortAipreplInt
Parameters (in addition to dateMask and contentType) are all joined by logical OR:
Table 17-6 AIP/Replenishment Results Parameters
Name | Type | Query Logic for Corresponding Column if Parameter is Provided |
---|---|---|
assortmentSetId |
String |
Equal to this value |
exportedDt |
Date |
Greater than or equal to this value |
Output Aggregated Across Approved Runs
This service is based on so_assort_cm_int.csv.
GET on /rase/resources/so/export/soAssortCmInt.
Parameters (in addition to dateMask and contentType) are all joined by logical OR:
Table 17-7 Output Aggregated Across Approved Runs Parameters
Name | Type | Query Logic for Corresponding Column if Parameter is Provided |
---|---|---|
assortmentSetId |
String |
Equal to this value |
exportedDt |
Date |
Greater than or equal to this value |
Assortment Result Details
This service is based on so_assort_int.csv.
GET on /rase/resources/so/export/soAssortInt.
Parameters (in addition to dateMask and contentType) are all joined by logical OR:
Table 17-8 Assortment Results Details Parameters
Name | Type | Query Logic for Corresponding Column if Parameter is Provided |
---|---|---|
assortmentSetId |
String |
Equal to this value |
exportedDt |
Date |
Greater than or equal to this value |
Cross Reference Between Planograms and Finalized Assortments
This service is based on planogram_assortment.csv.
GET on /rase/resources/so/export/planogramAssortment.
Parameters (in addition to dateMask and contentType) all joined by logical OR:
Table 17-9 Cross Reference Between Planograms and Finalized Assortments Parameters
Name | Type | Query Logic for Corresponding Column if Parameter is Provided |
---|---|---|
pogKey |
String |
Equal to this value |
exportDate |
Date |
Greater than or equal to this value |
POG Header
This service is based on planogram.csv.
GET on /rase/resources/so/export/planogram.
Parameters (in addition to dateMask and contentType) all joined by logical OR:
Table 17-10 POG Header Parameters
Name | Type | Query Logic for Corresponding Column if Parameter is Provided |
---|---|---|
pogKey |
String |
Equal to this value |
exportDate |
Date |
Greater than or equal to this value |
POG Equipment Components
This service is based on equipment.csv.
GET on /rase/resources/so/export/equipment.
Parameters (in addition to dateMask and contentType) are all joined by logical OR:
Table 17-11 POG Equipment Components Parameters
Name | Type | Query Logic for Corresponding Column if Parameter is Provided |
---|---|---|
pogKey |
String |
Equal to this value |
exportDate |
Date |
Greater than or equal to this value |
POG/Stores Cross Reference
This service is based on planogram_store.csv.
GET on /rase/resources/so/export/planogramStore.
Parameters (in addition to dateMask and contentType) are all joined by logical OR:
Table 17-12 POG/Stores Cross Reference Parameters
Name | Type | Query Logic for Corresponding Column if Parameter is Provided |
---|---|---|
pogKey |
String |
Equal to this value |
storeKey |
String |
Equal to this value |
exportDate |
Date |
Greater than or equal to this value |
Finalized Assortment Product Hierarchies
This service is based on product_hierarchy.csv.
GET on /rase/resources/so/export/productHierarchy.
Parameters (in addition to dateMask and contentType) are all joined by logical OR:
Table 17-13 Finalized Assortment Product Hierarchies Parameters
Name | Type | Query Logic for Corresponding Column if Parameter is Provided |
---|---|---|
exportDate |
Date |
Greater than or equal to this value |
Finalized Assortment Products
This service is based on product_position.csv.
GET on /rase/resources/so/export/productPosition.
Parameters (in addition to dateMask and contentType) are all joined by logical OR:
Table 17-14 Finalized Assortment Products Parameters
Name | Type | Query Logic for Corresponding Column if Parameter is Provided |
---|---|---|
pogKey |
String |
Equal to this value |
skuKey |
String |
Equal to this value |
exportDate |
Date |
Greater than or equal to this value |
Product Display Style Information
This service is based on sku_details.csv.
GET on /rase/resources/so/export/skuDetails.
Parameters (in addition to dateMask and contentType) are all joined by logical OR:
Table 17-15 Product Display Style Information Parameters
Name | Type | Query Logic for Corresponding Column if Parameter is Provided |
---|---|---|
skuKey |
String |
Equal to this value |
skuName |
String |
Equal to this value |
effectiveDate |
Date |
Greater than or equal to this value |
expiryDate |
Date |
Greater than or equal to this value |
exportDate |
Date |
Greater than or equal to this value |
Retail Science Integration with XStore
Retail Science integrates with XStore; as part of this integration, XCenter broadcasts real time sales data with multiple transactions in one XML file to Retail Science. Retail Science, on receiving data, saves real time sales transactions, any price modifiers like promotions, price overrides, and returns in the database, which can be used as real time sales data for reporting.
This section provides the information necessary to send messages contained in version 1.0 of the POSLOG Services API. Information can be obtained using the Web Service Description Language (WSDL) in conjunction with a Simple Object Access Protocol (SOAP), XML Schema, and various methods contained in the classes of the API to provide the web service described below.
Endpoint
The URL for the WSDL is:
https://<host>:<port>/rasews/poslog/v1/PoslogStrReceiverApiService?wsdl, where <host> is the name or address of the server. For a cloud installation, <port> the default port number is 443.
The URL for the WSDL is: Retail Science SOAP endpoint is:https://<host>:<port>/rasews/poslog/v1/PoslogStrReceiverApiService This endpoint should be configured in the XCenter for Generic Poslog String broadcaster. For further details, see the XCenter configuration.
Authentication
Retail Science supports Basic Authentication integration with XCenter over https, using a username and password. XCenter integration with Retail Science relies on SSL to do the encryption of the username/password configuration. After a user is defined in Retail Science, XCenter must be configured with the userid/password, and Xcenter will use Base64-encoding and include it as part of the Http authorization header when invoking the SOAP service. XCenter service requests must be authenticated with a valid user/password combination and roles. Failure to provide a valid authorization header will result in a 403 - Forbiddenresponse.The user must have following role set up: POSLOGS_SERVICE_JOB - Point of Sales broadcast listener role to enable integration between Retail Science and Oracle XStore.
Retail Science and Retail Insight Integration
Retail Science internally triggers job LOAD_POSLOG_DATA_ADHOC; this job is predefined in Retail Process Orchestration and Monitoring (POM). As part of the configuration verification, ensure that LOAD_POSLOG_DATA_ADHOC is defined in POM.
Configuration
This section describes the configuration.
POM Server Detail Configuration
To ensure AIF application to Retail Insights integration configuration is correct, verify RSE_CONFIG configuration for POM Server details.Select Control & Tactical Center > Strategy & Policy ManagementFilter APPL_CODE as "RSE" and PARAM_NAME as "RSE_POM_HOST". Determine if the value set as part of the deployment is correct. If the host is not correct, update the entries.
Figure 17-2 Edit Value
POM Server Credentials
Select Control & Tactical Center > Manage Credential Store to provide POM ReST endpoints credentials for Basic Authentication. All the POM ReST endpoints use Basic Authentication, with the same credentials as those used to log into the POM application. See Figure 17-3 to provide credentials.
Figure 17-3 POM Server Credentials
Once the configuration is complete, AIF applications will start triggering jobs for Retail Insights.