RTLog Generator On-Premise

Installation

Run Xstore Office Jetty or Tomcat installer to install RTLog Generator. Copy the rtlog-generator.war file to the installation directory for the installer to detect the war file and copy it to the server’s wabapps directory.

Refer to Oracle Retail Xstore Suite Implementation and Security Guide for information on Jetty and Tomcat Xstore Office installers.

The installer does not copy RTLog generator’s configuration zip file. Follow the steps in the next Configuration section to manually configure RTLog generator.

Configuration

The RTLog Generator application is shipped with a configuration .zip file (rtlog-gen-config.zip) which should be used to externally configure and extend the RTLog Generator's functionality.

Note:

Bounce the Jetty or Tomcat server after making any configuration level changes.

Starting from release 20.0, the RTLog generator is shipped with one rtlog-generator-config.zip, which is used to integrate with Sales Audit and ReSA On-premise.

To set up the external configuration features:

Extract the configuration file's content into the C:\<rtlog-generator-config> directory if installing on Microsoft Windows or /usr/local/<rtlog-generator-config> on Linux OS. These directories are the default locations where the RTLog Generator application will look for the configuration files. These default locations can be overridden/changed by using one of the following ways:
- Pass a JVM argument to the server startup script and bounce the server: -DRTLOG-GENERATOR_CONFIG=C:/<custom_directory>/
  
  For Jetty, specify the JVM argument in the wrapper.conf file under <JettyServer>/bin directory.
  
  Example:
  wrapper.java.additional.16=-DRTLOG-GENERATOR_CONFIG=C:/rtlog-generator-config-2
  For Tomcat, specify the JVM argument in catalina.sh or catalina.bat under <TomcatServer>/bin directory.
  
  Example:
  JAVA_OPTS="$JAVA_OPTS -DRTLOG-GENERATOR_CONFIG=C:/rtlog-generator-config-2"
- Specify the context-param field in the RTLog Generator WAR file. This requires opening up the WAR file and making the required changes. Update the web.xml file as shown in the following example:
  <context-param> <param-name>rtlog.generator.config.home</param-name> <param-value>C:/<custom_directory>/</param-value> </context-param>
  
  Figure 6-1 Example of context-param Field Update
Once the configuration file is extracted to the configured directory, verify the following files:
- rtlogconfig.properties:
  
  This file contains the following properties (key value pairs):
  - processingDir: This directory path specifies the location that RTLog Generator will use to build its RTLog files as it receives data from Xstore Office. This directory needs to be created manually. In a cluster environment, the directory must be shared by all the instances in the cluster.
  - resaFileDropDir: This directory path specifies the destination for the RTLog files this system is producing. It should be configured to the location where Sales Audit is looking to receive the RTLog files. This directory needs to be created manually. In a cluster environment, the directory must be shared by all the instances in the cluster.
  - clusterNodeNumber: This property should only be enabled when running in a clustered environment. For more information, see the Running Multiple RTLog Generator instances in a Cluster section.
  - deliveryTarget: This property specifies the RTLog delivery target. The two possible values are resa-cs or resa-onprem. If resa-cs is specified, the RTLog files generated are in format compatible with Sales Audit; otherwise the files generated are in format compatible with ReSA On-premise.
  - spring.profiles.active: This property is by default commented out. Uncomment it in the following two scenarios.
    1. Enable FTS delivery of RTLog files.
      
      Set it to “fts,archive” without quotes to send RTLog files to ReSA CFS object storage through FTS (File Transfer Service).
      
      Set it to “fts,zip,archive” without quotes to send RTLog zip files to ReSA CFS object storage through FTS (File Transfer Service).
    2. Set it to “zip” without quotes to zip up RTLog files placed in the directory specified by property “resaFileDropDir”.
  Following is an example of the properties. No spring.profiles.active property is specified in this case.
```
processingDir = C:/RTLogGen/Output/Store/RTLOGS 
resaFileDropDir = C:/RTLogGen/Output/ReSA 
clusterNodeNumber = 1
deliveryTarget = resa-cs
-OR- 
deliveryTarget = resa-onprem
```
  Following is another example to enable zipping of RTLog files.
```
processingDir = C:/RTLogGen/Output/Store/RTLOGS 
resaFileDropDir = C:/RTLogGen/Output/ReSA 
clusterNodeNumber = 1
deliveryTarget = resa-cs
-OR- 
deliveryTarget = resa-onprem
spring.profiles.active = zip
```
  Additional properties and configuration have to be specified if FTS delivery of RTLog files is enabled. Skip this section if it is not enabled.
  - cloud.fts.endpointUrl: This property specifies the ReSA FTS endpoint URL to deliver the RTLog files to.
  Note:
  
  RTLog Generator supports two forms of RMS FTS endpoints.
  1. 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
  2. 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
  To invoke ReSA FTS endpoint URL secured in Oauth, IDCS client ID, secrete, and scope are required. They are captured in Xcenter DB. The following properties must be specified for RTLog generator to request them through Xcenter on premise REST APIs.
  - xcenter.protocol: http or https
  - xcenter.host: Xcenter on premise host name
  - xcenter.port: Xcenter on premise port
  - xcenter.db.user: encrypted basic auth username for Xcenter on premise REST apis
  - xcenter.db.pwd: encrypted basic auth password for Xcenter on premise REST apis
  - dtv.location.organizationId: Xcenter organization id to request for IDCS client id/secret/scope
  - dtv.CustomerId: customer ID used in decryption of username and password
  - dtv.CustomerId.salt: salt used in decryption of username and password
  Following is an example rtlogconfig.properties with FTS delivery enabled.
```
processingDir = C:/RTLogGen/Output/Store/RTLOGS 
resaFileDropDir = C:/RTLogGen/Output/ReSA 
clusterNodeNumber = 1
deliveryTarget = resa-cs
spring.profiles.active = fts,zip,archive
-OR- 
spring.profiles.active = fts,archive
cloud.fts.endpointUrl=https://xxxx/xxxx/RmsPlatformServices/services/private/ 
FTSWrapper
xcenter.protocol=https
xcenter.host=<xcenter onprem host>
xcenter.port=<xcenter onprem port>
xcenter.db.user=<encrypted xcenter onprem basic auth username>
xcenter.db.pwd=<encrypted xcenter onprem basic auth passowrd>
dtv.location.organizationId=1000
dtv.CustomerId=xxx
dtv.CustomerId.salt=xxxx
```
  Cipher Keys: for rtlog-generator to decrypt xcenter.db.user and xcenter.db.pwd, cipher keys must be copied from xcenter-config/res/keys to rtlog-generator-config/res/keys. This includes all key files of the following naming patterns.
  
  – config.cip
  
  – config.*.cip (for example config.2022-02-07.cip)
  
  Truststore: certificate to communicate to Xcenter must be placed in .truststore file under rtlog-generator/res/ssl
- Multiple log4jx.xml files: These files configure the logging levels for the RTLog Generator application.
  - rtlog-generator-log4j2.xml
  - rtlog-generator-log4j2-loggers.xml
  - rtlog-generator-log4j2-appenders.xml
- spring-scheduler.xml:
  
  It is the most commonly modified file in the RTLog Generator application. It is used to configure the scheduled interval for publishing the RTLog files. In the case of trickle polling, the default interval should be 15 minutes, however, keeping a larger interval (at least greater than or equal to 15 minutes) is recommended as configuring with a smaller interval might affect the performance.
  
  Figure 6-2 spring-scheduler.xml Example

Customization ouf of box configuration

To customize RTLogMappingConfig.xml and RTLogFormatConfig.xml, you can obtain your out-of-box version in the rtlog-generator.war file under WEB-INF\classes\resa-cs for Sales Audit integrations (deliveryTarget = resa_cs) or WEB-INF\classes\resa-onprem for ReSA On-premise integrations (deliveryTarget = resa_onprem).

Customized copies of RTLogMappingConfig.xml and RTLogFormatConfig.xml are placed in the configuration directory defaulting to C:\<rtlog-generator-config> on Microsoft Windows or /usr/local/<rtlog-generator-config> on Linux OS.

RTLogFormatConfig.xml:

This file specifies the format of the RTLog record as specified by Sales Audit. You can modify this file.

RTLogMappingConfig.xml:

The RTLog Generator application relies heavily on the XML-based mapping which provides 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:

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>

Note:

For more information on how to customize the RTLog Generator, see the Retail Xstore - RTLog Generator Extension Guidelines (Doc ID 2174095.1) on https://support.oracle.com.

Deployment

If Xstore Office installer is not used to lay down RTLog Generator, or re-deployment is necessary, follow the steps below to deploy or redeploy the application.

Stop the Jetty or Tomcat server.
Copy the rtlog-generator.war file to the webapps directory under Jetty or Tomcat server.
Start the Jetty or Tomcat server.

Running Multiple RTLog Generator Instances in a Cluster

In a cluster setup, each RTLog Generator instance must specify its own unique cluster node number in the property clusterNodeNumber in rtlogconfig.properties under its external configuration directory.

To meet this requirement for a vertical cluster, multiple RTLog Generator instances on a same physical machine must not share one default external configuration directory at C:\rtlog-generator-config or /usr/local/rtlog-generator-config. Each instance must specify its own external configuration directory. For more information on how to override the default external configuration directory, see the Configuration section.

Security Configuration

The RTLog Generator application is secured by leveraging two levels of security:

Container level security: Basic HTTP authentication by setting up the security realm in Jetty or Tomcat. To configure this security, see "Container Level Security".
Transport level security: SOAP requests are sent over the secured protocol (HTTPS) by configuring the keystore/truststore in the Jetty or Tomcat server and importing the public certificate into Xstore Office's (client) truststore. Transport level security is configured by Xstore Office installer. No additional work is required.

Container Level Security

This section describes the Container Level Security.

Jetty

Go to <JettyServer>/etc directory. Open file jetty-xcenter.xml in a text editor.

Locate “Configure Xcener User Realm” section under the following heading.

<!-- =========================================================== -->
<!-- Configure Xcenter User Realm -->
<!-- =========================================================== -->

Add the highlighted section to introduce user realm myrealm for RTLog Generator. It should be inserted after the existing section (unhighlighted) for user realm Xcenter Dtx.

  <Call name="addBean">
    <Arg>
      <New class="org.eclipse.jetty.security.jaas.JAASLoginService">
        <Set name="name">Xcenter Dtx</Set>
        <Set name="LoginModuleName">xcenterLoginModule</Set>
        <Set name="roleClassNames">
          <Array type="java.lang.String">
            <Item>oracle.retail.xstore.passwd.jaas.SimpleRole</Item>
          </Array>
        </Set>
      </New>
    </Arg>
  </Call>
  <Call name="addBean">
    <Arg>
      <New class="org.eclipse.jetty.security.jaas.JAASLoginService">
        <Set name="name">myrealm</Set>
        <Set name="LoginModuleName">xcenterLoginModule</Set>
        <Set name="roleClassNames">
          <Array type="java.lang.String">
            <Item>oracle.retail.xstore.passwd.jaas.SimpleRole</Item>
          </Array>
        </Set>
      </New>
    </Arg>
  </Call>

Under the same directory, open file passwds in a text editor. The file contains username/password used for RTLog Generator basic auth. The password must be hashed. Follow the steps below to hash the password and setup a user.
- Open a command prompt in <JettyServer>/lib directory.
- Run java -cp dtv-password.jar oracle.retail.xstore.passwd.impl.Ssha2Hasher.
- Type in the password you want RTLog Generator to accept and press enter
- Collect the line of text from the console.
- Add it in a new line to passwds containing the following format.
```
the desired username>:<the output collected in last
        step>:92464520400:0:0:RTLogUserGroup
```
  The following is an example with rtloguser as the username.
```
rtloguser:{SHA512}ac5a43e1282ba165c357ec6b9e4a935bd20a3a6d4abe9c76e48bbd650d29378d47678e23d82c983b437cd4b39151841c8f08948700b4e2c2f69978143d55f513$a539daf2a1c165b7$100000:92464520400:0:0:RTLogUserGroup
```

Tomcat

Go to <TomcatServer>/conf directory. Open the tomcat-users.xml file in a text editor.
Add a new line to define RTLogUserGroup role in the tomcat-users.xml file.
```
<role rolename="RTLogUserGroup"/>
```
The file contains username/password used for RTLog Generator basic auth. The password must be hashed. Follow the steps below to hash the password and setup a user.
- Open a command prompt in the <TomcatServer>/bin directory.
- Run ./digest.sh -a SHA-512 -e UTF-8 -i 1000 -s 64 <the password you want to use>
- Collect the portion of the resulting output following <the password you want to use>:
- Add a new line to the tomcat-users.xml file containing the following format:
```
<user username="<the desired username>" password="<the
        output collected in last step>" roles="RTLogUserGroup"/>
```
  The following is an example with rtloguser as the username.
```
<role rolename="RTLogUserGroup"/> 
<user username="rtloguser" password="<password>" roles="RTLogUserGroup"/>
```

6 RTLog Generator On-Premise