7 RTLog Generator Cloud
This chapter describes the RTLog Generator component of Xstore Office Cloud. The RTLog Generator Cloud application can be used with both the cloud or on premise Merchanding/Pricing applications.
RTLog Generator Cloud
This chapter describes how configure the RTLog Generator application deployed on cloud.
The RTLog Generator on cloud is a Java and XML based web application that exposes a Spring-JAXWS implemented SOAP web service and JAXRS implemented REST web services. It is usually deployed alongside the other Xstore Office Cloud applications.
Configuration
The RTLog Generator cloud application can be configured in the following way.
Customize the RTLog Generator's mapping and format configuration via REST services.
Note:
For more information on how to customize the RTLog Generator, see the Configuration section in RTLog Generator On-Premise and the Retail Xstore - RTLog Generator Extension Guidelines (Doc ID 2174095.1) on https://support.oracle.com.
Integration
This section describes the RTlog Generator Cloud integration.
Updating Mapping Configuration
RTLog Generator Cloud application provides REST services to retrieve,
update and delete the RTLogMappingConfig.xml
file.
All the three services point to the URL at
https://<hostname>/rtlog-generator/rest/config/file/v1/RTLogMappingConfig
If RTLog generator is deployed on cloud, its mapping configuration
file RTLogMappingConfig.xml
is not accessible to
a user. To customize the mapping, restful APIs are provided to upload
a customized RTLogMappingConfig.xml
to override the
default out-of-box one.
Table 7-1 REST Services related to the RTLogMappingConfig.xml
HTTP Protocol | Security Protocol | Response Type | Description |
---|---|---|---|
GET |
OAuth2 |
application/xml |
Returns the active RTLogMappingConfig.xml file. If the customer has not uploaded a customized configuration xml file yet, provides a copy of the default mapping configuration XML file that is provided with the deployment. |
PUT |
OAuth2 |
application/json |
Customer submits the updated RTLogMappingConfig.xml file as the request body. Returns JSON that contains the number of bytes in the uploaded XML file. |
DELETE |
OAuth2 |
No content |
If the customer has uploaded a configuration XML file previously, it will be deleted and HTTP 200 status is returned. If there is no customized RTLogMappingConfig.xml file active yet, HTTP 204 status is returned. The default RTLogMappingConfig.xml that is part of the deployment will resume being the active mapping configuration. |
The examples below show how to retrieve and update the RTLogMappingConfig.xml.
Example 7-1 Get active RTLogMappingConfig.xml - Get Current RTLog Mapping Configuration
$ curl -H "Authorization: Bearer <token>" https://<rlog-generator-host>/rtlog-generator/rest/config/file/v1/RTLogMappingConfig" > RTLogMappingConfig.xml
Example 7-2 Update RTLogMappingConfig.xml - Update the RTLog Mapping Configuration
$ curl -H "Authorization: Bearer <token>" -X PUT -T "/path/to/mapping/file" https://<rlog-generator-host>/rtlog-generator/rest/config/file/v1/RTLogMappingConfig"
Similar to the example above, using the -X option with the value
of DELETE
will delete any customer uploaded mapping
configuration XML file.
Updating Format Configuration
RTLog Generator Cloud application provides REST services to retrieve, update and delete the RTLogFormatConfig.xml file. All the three services point to the URL at:
https://<hostname>/rtlog-generator/rest/config/file/v1/RTLogFormatConfig
If RTLog generator is deployed on cloud, its format configuration file RTLogFormatConfig.xml is not accessible to a user. A format configuration file defines the Sales Audit RTLog format, and in most cases is not up for customizations. However RTLogFormatConfig.xml file can be customized when:
-
Customization has been done to Sales Audit to accept an enhanced RTLog format with additional fields
-
A retailer has to integrate with an earlier version of Sales Audit which is not supported out of box, and it accepts a slightly different older RTLog format.
Table 7-2 REST Services related to the RTLogFormatConfig.xml
HTTP Protocol | Security Protocol | Response Type | Description |
---|---|---|---|
GET |
OAuth2 |
application/xml |
Returns the active RTLogFormatConfig.xml file. If the customer has not uploaded a customized configuration xml file yet, provides a copy of the default mapping configuration XML file that is provided with the deployment. |
PUT |
OAuth2 |
application/json |
Customer submits the updated RTLogFormatConfig.xml file as the request body. Returns JSON that contains the number of bytes in the uploaded XML file. |
DELETE |
OAuth2 |
No content |
If the customer has uploaded a configuration XML file previously, it will be deleted and HTTP 200 status is returned. If there is no customized RTLogFormatConfig.xml file active yet, HTTP 204 status is returned. The default RTLogMappingConfig.xml that is part of the deployment will resume being the active mapping configuration. |
The examples below show how to retrieve and update the RTLogFormatConfig.xml.
Example 7-3 Get active RTLogFormatConfig.xml - Get Current RTLog Format Configuration
$ curl -H "Authorization: Bearer <token>" https://<rlog-generator-host>/rtlog-generator/rest/config/file/v1/RTLogFormatConf ig" > RTLogFormatConfig.xml
Example 7-4 Update RTLogFormatConfig.xml - Update the RTLog Format Configuration
$ curl -H "Authorization: Bearer <token>" -X PUT -T "/path/to/format/file" https://<rlog-generator-host>/rtlog-generator/rest/config/file/v1/RTLogFormatConf ig"
Similar to the example above, using the -X option with the value of DELETE will delete any customer uploaded format configuration XML file.
Retrieving Published RTLog Files
RTLog Generator Cloud application provides three mechanisms to retrieve the published RTLog files.
-
FTS (File Transfer Service) provides a way to deliver RTLog files to Sales Audit deployed as part of RMFCS v21.0 and later. By default it delivers RTLog files in compressed format (zip files). A deployment option is provided to turn off the compression. It puts RTLog files to object storage for Sales Audit to import. This service is not available for Sales Audit deployed in RMFCS v19.x.
A service request has to be filed by a retailer to setup RTLog Generator Cloud to use FTS.
FTS_ENDPOINTURL is made available to the RTLog Generator Cloud deployment team by the Merchandising team.
Note:
The RTLog Generator supports two forms of RMS FTS endpoints.
-
RMS Platform FTS wrapper API: This API is the new FTS endpoint supported in RMS. The customer is advised to use this endpoint for FTS integration. Its URL takes the following format: https://xxxx/xxxx/RmsPlatformServices/services/private/FTSWrapper
-
RMS FTS API (deprecated): This API is deprecated but still supported in RMS. The customer is advised to switch to use the new platform FTS wrapper API. The deprecated API may no longer be available in RMS in the future. Its URL takes the following format: https://xxxx/xxxx/RmsReSTServices/services/private/fts
-
-
SFTP service provides a way to transfer RTLog files. This method is commonly used to post RTLog files to Sales Audit deployed on RMFCS v19. By default it delivers RTLog files in compressed format (zip files). A deployment option is provided to turn off the compression.
A service request has to be filed by a retailer to setup RTLog Generator Cloud to use SFTP.
-
SFTP host and path are made available to the RTLog Generator Cloud deployment team by the retailer.
-
SFTP connectivity utilizes public/private key based authentication. Once the key pair is generated, the public key has to be added to the SFTP server. If the SFTP server is hosted by Merchandising Cloud, the public key will be accessible to Merchandising Cloud deployment team to add to the SFTP server; if the SFTP server is hosted on premise, the public key will be handed over to the retailer to add to the SFTP server.
-
-
REST service provides a way to download RTLog files in compressed format (zip files). This is the default delivery method. The REST service endpoint URL is
https://<hostname>/rtlog-generator/rest/rtlog/files/v1/published
Table 7-3 REST Services to download RTLog Files
HTTP Protocoal | Security Protocol | Response Type | Description |
---|---|---|---|
GET |
OAuth2 |
application/octet -stream |
Returns the oldest RTLog zip file stream, if available. The content-disposition response header contains the name of the attached zip file. If no zip file is available, a HTTP 204 no content is returned. |
Example 7-5 Get Published RTLogs - OAuth2 token request
$ curl -O -J -H "Authorization: Bearer <token>" "https://<rlog-generator-host>/rtlog-generator/rest/rtlog/files/v1/published"
It is recommended to have a programmable approach to acquire the OAuth2 token and utilizing the token to download the available published RTLog files compared to the command line tools shown as examples above.
Security Configuration
RTLog Generator's web services are secured by requiring HTTPS protocol for transport layer security and require OAuth2 authentication for application level security. All of the Xoffice applications on cloud including the RTLog Generator have a valid OAuth Client (Application) registered with a specific tenant of the Oracle Identity Cloud Service.
OAuth2 authentication is a two-step process.
-
Acquire a valid OAuth2 Bearer token using the IDCS Client Credentials.
-
Provide the token value in the HTTP Authorization header for all of the web service requests until the token's validity is expired.
Acquiring IDCS Token
In order to acquire a valid IDCS token, the following information is needed beforehand.
-
IDCS tenant host information to build the URL for requesting a token
-
https://<IDCS_TENANT_HOST>/oauth2/v1/token
-
-
ClientID
andClientSecret
for the RTLog Generator Client App (that is Sales Audit). -
A command line utility or any software that can make HTTP requests with the ability to setup specific header values
-
"curl" in Linux environments
-
-
Access to a command/utility to encode the credentials in base64 format.
-
"base64" command in Linux environments
-
"certutil" command in Windows environments
-
The following example shows how to request a token using the curl command line tool in a Linux environment. Ensure to replace the clientID
, clientSecret
and IDCS_TENANT_HOST
with the appropriate values.
Example 7-6 Request IDCS Oauth2 Token - OAuth2 Token Request
$ curl -i -H "Authorization: Basic $(echo -n clientID:clientSecret | base64)" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" https://<IDCS_TENANT_HOST>/oauth2/v1/token -d "grant_type=client_credentials&scope=urn:opc:idm:__myscopes__"
You may generate Base64 encoded text of the "clientID:clientSecret"
ahead of the request and use it directly in the curl command for the Basic Authorization header value. The following example shows the response that contains the token.
Example 7-7 IDCS Oauth2 Token Response - OAuth2 Token Response
{"access_token": "<oauth2_token>", "token_type": "Bearer", "expires_in": 3600 }
The response above shows the token value and the expiration time in seconds. Usually, the token is a sequence of random characters of varying length up to a maximum of 16K.
Provide IDCS Authentication
The following example shows how to provide the OAuth2 token while communicating with RTLog Generator REST services. The following example shows how to request the current active RTLogMappingConfig.xml file. Please make sure to replace the "<token>"
with a valid OAuth2 token acquired in the last step and provide the correct RTLog Generator Host value.
Example 7-8 Provide Oauth2 Token - Provide OAuth2 Token for REST Services
$ curl -i -H "Authorization: Bearer <token>" "https://<rlog-generator-host>/rtlog-generator/rest/config/file/v1/RTLogMappingConfig"