| Oracle® Retail Xstore Suite 18.0/Merchandising 16.0.2 Implementation Guide Release 18.0 E99047-05 |
|
 Previous |
 Next |
| Oracle® Retail Xstore Suite 18.0/Merchandising 16.0.2 Implementation Guide Release 18.0 E99047-05 |
|
Previous |
Next |
This chapter describes the RTLog Generator on 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 distributed as a web archive along with a configuration zip file ready to be deployed on an Oracle WebLogic 12c server. It is usually deployed alongside the other Xstore office cloud applications.
The RTLog Generator on cloud can be integrated with a ReSA application deployed either on-premises or on cloud.
The RTLog Generator cloud application can be configured in the following way.
Customize the RTLog Generator's mapping configuration via REST services.
|
Note: For more information on how to customize the RTLog Generator, see the Retail Xstor- RTLog Generator Extension Guidelines (Doc ID 2174095.1) onhttps://support.oracle.com. |
The RTLog Generator application relies heavily on the XML-based mapping specified in the RTLogMappingConfig.xml file to provide extensibility and a way to maintain/upgrade features for the application. This file can be used to override all the field values for either mapping strategy.
The following elements of the mapping XML file can be customized:
FieldMapperThenValueMapping:
The RecordValue attribute values as shown in the following example can be changed:
<MAP sourceField="tenderId" targetRecord="TransactionHeaderTotal" targetField="ReferenceNumber1" mappingStrategyOrder="FieldMapperThenValueMapping" fieldMapper="trnHeaderTotalMapper"> <VALUE_MAPPINGS handleNotFound="success"> <VALUE_MAPPING sourceValue="GIFT_CERTIFICATE" RecordValue="GIFTCERT" /> <VALUE_MAPPING sourceValue="HOUSE_ACCOUNT" RecordValue="HACCNT" /> <VALUE_MAPPING sourceValue="ISSUE_STORE_CREDIT" RecordValue="ISTCRDT" /> <VALUE_MAPPING sourceValue="ISSUE_MERCHANDISE_CREDIT_CARD" RecordValue="IMCCARD" /> <VALUE_MAPPING sourceValue="ISSUE_XPAY_GIFT_CARD" RecordValue="IXPAYGC" /> <!--For e.g above given value can be changed as shown here.--> <VALUE_MAPPING sourceValue="ISSUE_XPAY_GIFT_CARD" RecordValue="SAMPLE_ IXPAYGC" /> <VALUE_MAPPING sourceValue="MALL_CERTIFICATE" RecordValue="MALLCERT" /> <VALUE_MAPPING sourceValue="MERCHANDISE_CREDIT_CARD" RecordValue="MCCARD" /> <VALUE_MAPPING sourceValue="PAYPAL" RecordValue="PAYPAL" /> <VALUE_MAPPING sourceValue="COUPON" RecordValue="QPON" /> <VALUE_MAPPING sourceValue="ROOM_CHARGE" RecordValue="ROOMCHAG" /> <VALUE_MAPPING sourceValue="RELOAD_XPAY_GIFT_CARD" RecordValue="RXPAYGC" /> <VALUE_MAPPING sourceValue="RELOAD_MERCHANDISE_CREDIT_CARD" RecordValue="RMCCARD" /> <VALUE_MAPPING sourceValue="STORE_CREDIT" RecordValue="STCRDT" /> <VALUE_MAPPING sourceValue="XPAY_GIFT_CARD" RecordValue="XPAYGC" /> </VALUE_MAPPINGS> </MAP>
No mappingStrategyOrder and fieldMapper attributes are defined:
The RecordValue attribute values shown in the following example can be changed or a new value can be added:
<MAP sourceField="reason" targetRecord="TransactionHeader" targetField="ReasonCode"> <VALUE_MAPPINGS handleNotFound="nextMapping"> <VALUE_MAPPING sourceValue="PI1" RecordValue="PI1"/> <VALUE_MAPPING sourceValue="PI2" RecordValue="PI2"/> <VALUE_MAPPING sourceValue="PI3" RecordValue="PI3"/> <VALUE_MAPPING sourceValue="PO1" RecordValue="PO1"/> <VALUE_MAPPING sourceValue="PO2" RecordValue="PO2"/> <VALUE_MAPPING sourceValue="PO3" RecordValue="PO3"/> <VALUE_MAPPING sourceValue="PO4" RecordValue="PO4"/> <VALUE_MAPPING sourceValue="PO5" RecordValue="PO5"/> <VALUE_MAPPING sourceValue="SAMPLE" RecordValue="SAMPLE_VALUE"/> </VALUE_MAPPINGS> </MAP>
This section describes the RTlog Generator Cloud integration.
RTLog Generator Cloud application provides three REST services to retrieve, update and delete RTLogMappingConfig.xml file. All the three services point to the URL at
https://<hostname>/rtlog-generator/rest/config/file/v1/RTLogMappingConfig
A new property configUploadDir is added to rtlogconfig.properties.
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. This directory specifies the upload directory to host the customized mapping file. In a cluster environment with multiple RTLogGen nodes, all nodes must be configured to point to the same config upload directory on shared file system. This is to ensure that once a mapping file is uploaded, it is visible to all the nodes.
#### #### (uncomment and configure this if and only if you are setting up a cluster of RTLogGen nodes on cloud) #### ####configUploadDir = /somewhere/rtlogconfig_upload
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 hasn't 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.
RTLog Generator Cloud application's ability to provide a mechanism to retrieve the published RTLog files varies depending on the type of ReSA application that it is integrated with.
For ReSA on cloud, SFTP process is used to transfer the files
For ReSA on-premises, REST service provides the way to download the files
ReSA on Cloud:
SFTP credentials to connect to the ReSA application's SFTP directory on cloud are made available to the RTLog Generator Cloud deployment team.
SFTP connectivity utilizes public/private key based authentication.
Cloud Application Management is responsible for SFTP credentials rotation.
ReSA on-premises:
RTLog Generator provides a REST service to download the published RTLog files in compressed format (zip files).
OAuth2 token is required for communicating with the REST web service.
Returns a zip file if one available on the published RTLog files directory.
Content type of the response will be application/octet-stream
Content-disposition response header will contain the name of the attached zip file
Returns HTTP 204 code when no zip files are available for download.
The following example shows how to retrieve the published RTLog files using curl.
Example 7-3 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.
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. The ReSA application is required to do the same in order to communicate with the RTLog Generator application via REST web services.
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.
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 and ClientSecret for the RTLog Generator Client App (that is ReSA application).
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-4 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-5 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.
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.
