Xstore Suite-1702 - Implementation Guide

Oracle® Retail Xstore Suite
Implementation and Security Guide

Release 17.0.2
F11643-07
October 2019
Note: In the examples below, the company name and details and
user details represent a fictitious sample. Any similarity to actual
company details is purely coincidental and not intended in any
manner.
The passwords contained in this document are for example

purposes only and it is strongly recommended that you do not use
these examples in a live environment.
Oracle® Retail Xstore Suite, Implementation and Security Guide, Release 17.0.2
F11643-07
Copyright © 2019, Oracle and/or its affiliates. All rights reserved.
Primary Author: Alan Smithee
This software and related documentation are provided under a license agreement containing
restrictions on use and disclosure and are protected by intellectual property laws. Except as
expressly permitted in your license agreement or allowed by law, you may not use, copy,
reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or
display any part, in any form, or by any means. Reverse engineering, disassembly, or
decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be
error-free. If you find any errors, please report them to us in writing.
If this software or related documentation is delivered to the U.S. Government or anyone licensing
it on behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated
software, any programs installed on the hardware, and/or documentation, delivered to U.S.
Government end users are “commercial computer software” pursuant to the applicable Federal
Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication,
disclosure, modification, and adaptation of the programs, including any operating system,
integrated software, any programs installed on the hardware, and/or documentation, shall be
subject to license terms and license restrictions applicable to the programs. No other rights are
granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management
applications. It is not developed or intended for use in any inherently dangerous applications,
including applications that may create a risk of personal injury. If you use this software or
hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe,
backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its
affiliates disclaim any liability for any damages caused by use of this software or hardware in
dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be
trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC
trademarks are used under license and are trademarks or registered trademarks of SPARC
International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or
registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open
Group.
This software or hardware and documentation may provide access to or information about
content, products, and services from third parties. Oracle Corporation and its affiliates are not
responsible for and expressly disclaim all warranties of any kind with respect to third-party
content, products, and services unless otherwise set forth in an applicable agreement between you
and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or
damages incurred due to your access to or use of third-party content, products, or services, except
as set forth in an applicable agreement between you and Oracle.
Value-Added Reseller (VAR) Language
Oracle Retail VAR Applications
The following restrictions and provisions only apply to the programs referred to in this section
and licensed to you. You acknowledge that the programs may contain third party software (VAR
applications) licensed to Oracle. Depending upon your product and its version number, the VAR
applications may include:
(i) the MicroStrategy Components developed and licensed by MicroStrategy Services
Corporation (MicroStrategy) of McLean, Virginia to Oracle and imbedded in the MicroStrategy
for Oracle Retail Data Warehouse and MicroStrategy for Oracle Retail Planning & Optimization
applications.
(ii) the Wavelink component developed and licensed by Wavelink Corporation (Wavelink) of
Kirkland, Washington, to Oracle and imbedded in Oracle Retail Mobile Store Inventory
Management.
(iii) the software component known as Access Via™ licensed by Access Via of Seattle,
Washington, and imbedded in Oracle Retail Signs and Oracle Retail Labels and Tags.
(iv) the software component known as Adobe Flex™ licensed by Adobe Systems Incorporated of
San Jose, California, and imbedded in Oracle Retail Promotion Planning & Optimization
application.
You acknowledge and confirm that Oracle grants you use of only the object code of the VAR
Applications. Oracle will not deliver source code to the VAR Applications to you.
Notwithstanding any other term or condition of the agreement and this ordering document, you
shall not cause or permit alteration of any VAR Applications. For purposes of this section,
"alteration" refers to all alterations, translations, upgrades, enhancements, customizations or
modifications of all or any portion of the VAR Applications including all reconfigurations,
reassembly or reverse assembly, re-engineering or reverse engineering and recompilations or
reverse compilations of the VAR Applications or any derivatives of the VAR Applications. You
acknowledge that it shall be a breach of the agreement to utilize the relationship, and/or
confidential information of the VAR Applications for purposes of competitive discovery.
The VAR Applications contain trade secrets of Oracle and Oracle's licensors and Customer shall
not attempt, cause, or permit the alteration, decompilation, reverse engineering, disassembly or
other reduction of the VAR Applications to a human perceivable form. Oracle reserves the right
to replace, with functional equivalent software, any of the VAR Applications in future releases of
the applicable program.
iii
Contents
1 Send Us Your Comments..............................................................1-xx
1 Preface...........................................................................................1-xxi
Audience..................................................................................................................... 1-xxi
Documentation Accessibility ................................................................................. 1-xxi
Access to Oracle Support................................................................................... 1-xxi
Related Documents ................................................................................................. 1-xxi
Customer Support..................................................................................................... 1-xxi
Review Patch Documentation ...............................................................................1-xxii
Oracle Retail Documentation on the Oracle Technology Network...............1-xxii
Conventions ..............................................................................................................1-xxii
1 Getting Started.................................................................................1-1
Who Should Use This Guide..................................................................................... 1-1
Xstore Point of Service Suite Components and Modules.................................... 1-2
Xstore Point of Service .......................................................................................... 1-3
PA-DSS Validation ......................................................................................... 1-3
Xenvironment......................................................................................................... 1-3
DataLoader ............................................................................................................. 1-3
GenKeys .................................................................................................................. 1-3
Xcenter..................................................................................................................... 1-3
Xadmin .................................................................................................................... 1-4
EFTLink................................................................................................................... 1-4
InstallX .................................................................................................................... 1-4
WebLogic ................................................................................................................ 1-4
Jetty .......................................................................................................................... 1-4
Apache Tomcat ...................................................................................................... 1-4
JRE............................................................................................................................ 1-4
Xstore Point of Service Mobile............................................................................. 1-4
Oracle Retail Xstore Settlement ........................................................................... 1-5
Web Server.............................................................................................................. 1-5
Real-Time Product Integration with Xstore Point of Service.............................. 1-5
2 Prerequisites for Installing Xstore Office ......................................2-1

System Requirements ................................................................................................. 2-1
Supported Web Browsers..................................................................................... 2-2
Backup and Recovery............................................................................................ 2-2
Install Web Server ....................................................................................................... 2-2
Xstore Office Installation .zip File ........................................................................... 2-3
<root_directory>..................................................................................................... 2-3
artifacts............................................................................................................. 2-3
RTLog-Generator............................................................................................ 2-3
iv
jetty-X.X.X-OS-installer-YY.jar ..................................................................... 2-3
tomcat-X.X.X-OS-installer-YY.jar ................................................................. 2-3
Installation File Directories ........................................................................... 2-3
Installation File Directories .................................................................................. 2-4
oraclepdb_install,upgrade ............................................................................ 2-4
oracle_install,upgrade ................................................................................... 2-4
mssql_install,upgrade.................................................................................... 2-4
mssql-unicode_install, upgrade ................................................................... 2-4
Office Installation .zip Files.................................................................................. 2-4
OracleRetailXstoreOffice_X_X_X_X_CCC_V_V_V.zip............................. 2-4
OracleRetailXstoreCommon_X_X_X_X_X_CCC_V_V_V.zip .................. 2-5
Java ................................................................................................................................. 2-5
Java Runtime Environment (JRE)........................................................................ 2-5
Java Development Kit (JDK) ................................................................................ 2-6
Enable Unlimited Java Encryption .............................................................. 2-6
Create JRE Package................................................................................................ 2-6
Database ........................................................................................................................ 2-8
Oracle ...................................................................................................................... 2-8
Installation Directory ..................................................................................... 2-8
OPEN_CURSORS Setup for Oracle ............................................................. 2-8
MS SQL Server ....................................................................................................... 2-8
Creating Databases................................................................................................ 2-8
TLS Certificates............................................................................................................ 2-8
WebLogic....................................................................................................................... 2-9
Tomcat or Jetty ............................................................................................................. 2-9
Jetty & Tomcat Memory Values .......................................................................... 2-9
64-bit OS and JDK........................................................................................... 2-9
3 Install Xstore Office .........................................................................3-1

Overview ....................................................................................................................... 3-1
Xstore Office Installation ........................................................................................... 3-1
Install GenKeys and String Encrypter Utility.................................................... 3-1
Create Cipher Key Files ........................................................................................ 3-2
Generate Rotating Keys for All Keys Except Debit/Credit....................... 3-2
Xstore Office Database Scripts.................................................................................. 3-3
Xstore Office Database Scripts............................................................................. 3-3
Install an Application Server: WebLogic, Jetty, or Tomcat ................................. 3-5
Prerequisites for Application Server Installation.............................................. 3-5
Pre-Installation Configuration............................................................................. 3-6
xcenter.properties Sample.......................................................................... 3-11
Install WebLogic .................................................................................................. 3-16
Prepare WebLogic Files ............................................................................... 3-17
Enable Only Strong Cipher Suites ............................................................. 3-17
Enable Secure Cookies ................................................................................. 3-18
v
Configure WebLogic Server........................................................................ 3-18
Configure Datasources ................................................................................ 3-21
Edit Batch File or Shell Script ..................................................................... 3-23
Install Jetty ............................................................................................................ 3-25
Install Apache Tomcat ........................................................................................ 3-28
Loading Profil Group/Element Configurations .............................................. 3-31
Install Xstore Office DataLoader ............................................................................ 3-31
GUI Mode Installation ........................................................................................ 3-31
To Load Xadmin User Records via DataLoader (Optional)................... 3-32
Install Xstore Office POS Log Generator.............................................................. 3-32
Retrieve Files through SFTP.................................................................................... 3-33
4 Prerequisites for Installing Xstore Point of Service .....................4-1

System Requirements ................................................................................................. 4-1
Hardware Requirements ...................................................................................... 4-1
Lead Register................................................................................................... 4-1
Non-Lead Register ......................................................................................... 4-1
Backup and Recovery............................................................................................ 4-1
Geolocation and Device Identifiers..................................................................... 4-2
Supported Software............................................................................................... 4-2
Supported Peripherals .......................................................................................... 4-3
Xstore Point of Service Mobile............................................................................. 4-4
Supported Barcode Formats ......................................................................... 4-5
Workstation 310 and 610 Supported Peripherals ...................................... 4-5
Supported Payment Processors........................................................................... 4-6
Synchronized System Clocks ............................................................................... 4-6
Workstation 620 and 650 Systems with Oracle Databases .............................. 4-6
Install Web Server ....................................................................................................... 4-8
Create and Apply Customer Overlay....................................................................... 4-8
Xstore Point of Service Installation .zip File .......................................................... 4-8
<root_directory>..................................................................................................... 4-9
artifacts............................................................................................................. 4-9
Point-of-Service Installation .zip Files ................................................................ 4-9
OracleRetailXstorePointofService_X_X_X_X_CCC_V_V_V.zip............ 4-10
OracleRetailXstoreCommon_X_X_X_X_X_CCC_V_V_V.zip ................ 4-10
Java ............................................................................................................................... 4-10
Java Virtual Machine........................................................................................... 4-11
vi
Java Runtime Environment (JRE)...................................................................... 4-11
Create JRE Package.............................................................................................. 4-11
Database ...................................................................................................................... 4-12
Oracle .................................................................................................................... 4-12
Microsoft SQL Server .......................................................................................... 4-12
TLS Certificates.......................................................................................................... 4-12
Xstore Point of Service Mobile................................................................................ 4-13
Install Xstore Mobile on Windows 10............................................................... 4-13
Set Screen Resolution (Windows 10 Only) ...................................................... 4-14
Build an Xstore Point of Service Mobile Client Application (iOS Only) ..... 4-15
Prerequisites.................................................................................................. 4-15
Create a New Xcode Project........................................................................ 4-15
Add XstoreMobile.framework to the Project ........................................... 4-16
Import Properties from XstoreMobile.framework Project ..................... 4-17
Update Icons and Launch Images.............................................................. 4-17
Configure Build Settings ............................................................................. 4-18
Set the Application’s Main Entry Point..................................................... 4-18
Configure your Apple Developer Provisioning Profiles........................ 4-18
Configure Verifone Support ....................................................................... 4-18
Configure Zebra or Symbol Support ......................................................... 4-20
Archive the Application .............................................................................. 4-23
Extract the Jetty Password Obfuscation Utility (Xstore Point of Service Mobile and
Xservices)..................................................................................................................... 4-25
Linux Pre-installation Procedures for Xenvironment......................................... 4-25
Linux Integration with APG Network Cash Drawer.......................................... 4-26
5 Install Xstore Point of Service ........................................................5-1

Overview ....................................................................................................................... 5-1
InstallX Modes of Operation - Overview................................................................ 5-2
Silent Mode............................................................................................................. 5-2
GUI Mode ............................................................................................................... 5-2
Xstore Point of Service Installer: File Naming Conventions ........................... 5-2
Where... ............................................................................................................ 5-2
Xstore Point of Service Installation.......................................................................... 5-3
Install GenKeys String Encrypter Utility ........................................................... 5-3
Create Cipher Key Files ........................................................................................ 5-4
Generate Rotating Keys for All Keys Except Debit/Credit....................... 5-4
Generate Rotating Keys for Debit/Credit.................................................... 5-5
Install Xstore Point of Service ................................................................................... 5-6
Before you install Xstore Point of Service... ....................................................... 5-6
Installation Procedure........................................................................................... 5-7
Install RTLog Generator........................................................................................... 5-18
Enable Store Inventory Management (SIM) in Xstore Point of Service ......... 5-18
Configure Xstore Point of Service for Retail Extension Module .................. 5-19
vii
Configure Xstore Point of Service for Address Verification Service............ 5-19
Enable Networked Cash Drawers..................................................................... 5-21
Install Xservices ......................................................................................................... 5-22
Login Configuration............................................................................................ 5-27
Install Xenvironment ................................................................................................ 5-28
Install Certificates for Xenvironment-Xstore Point of Service Communication5-
31
Configure Xenvironment for Thin Client............................................................. 5-31
Run Xenvironment as a Service......................................................................... 5-32
Windows........................................................................................................ 5-32
Linux (systemd) ............................................................................................ 5-33
Linux (init.d) ................................................................................................. 5-34
Xstore Point of Service Mobile Installation on Device ...................................... 5-36
iOS.......................................................................................................................... 5-36
Android................................................................................................................. 5-37
Create and Install SSL Certificates............................................................. 5-37
Install and Configure DataWedge ............................................................. 5-38
Configure Xstore Point of Service Mobile........................................................ 5-39
Configure Xstore Point of Service Mobile ................................................ 5-40
Additional Configuration............................................................................ 5-40
Functional Settings ....................................................................................... 5-42
Security Settings ........................................................................................... 5-42
Integrate with Xcommerce ................................................................................. 5-42
Writing Your Xcommerce Application ..................................................... 5-42
6 About Implementing the Xstore Suite............................................6-1

What you need to do... ................................................................................................ 6-1
First, answer a few questions about your store operations............................. 6-1
Next, scope out your technical landscape.......................................................... 6-1
Xstore Point of Service System Configuration .................................................. 6-1
Store and Home Office Connectivity.................................................................. 6-2
Corporate Server Applications ............................................................................ 6-2
Authorization Software and Setup Options ...................................................... 6-2
Xenvironment Setup Options .............................................................................. 6-2
Finally, consider the enterprise flow .................................................................. 6-2
Installation Requirements ......................................................................................... 6-3
Prerequisites and Assumptions........................................................................... 6-3
Database and Operating System Configurations.............................................. 6-3
Database Platforms: General Considerations............................................. 6-3
Operating Systems: General Considerations.............................................. 6-4
Xstore Point of Service: Installation Types & Tasks............................................. 6-5
Communication Ports ................................................................................................. 6-7
Oracle Retail Xstore Point-of-Service, Lane Checkout User Interface
viii
Communication Ports ................................................................................................. 6-8
7 Xstore Suite Data Architecture.......................................................7-1

Primary Data Source Configuration......................................................................... 7-1
Lead Register as store primary data source diagram....................................... 7-2
Store Server serves as store primary data source diagram ............................. 7-2
8 Upgrading Xstore Suite Components............................................8-1

Overview ....................................................................................................................... 8-1
Xstore Point of Service Installation .zip File .......................................................... 8-2
<root_directory>..................................................................................................... 8-2
artifacts............................................................................................................. 8-2
Point-of-Service Installation .zip Files ................................................................ 8-3
OracleRetailXstorePointofService_X_X_X_X_X_CCC_V_V_V.zip ......... 8-3
OracleRetailXstoreCommon_X_X_X_X_X_CCC_V_V_V.zip .................. 8-3
Update/Upgrade Instructions in this section ......................................................... 8-4
Java Runtime Environment (JRE)........................................................................ 8-4
Xstore Point of Service .......................................................................................... 8-4
Oracle Retail Xstore Office ................................................................................... 8-4
DataLoader ............................................................................................................. 8-4
POS Log Generator................................................................................................ 8-4
Xenvironment......................................................................................................... 8-4
Xstore Point of Service Installer: File Naming Conventions ........................... 8-4
Xstore Point of Service Upgrade - Manual Application....................................... 8-5
Xstore Point of Service Upgrade - Using Xenvironment...................................... 8-5
Oracle Retail Xstore Office Upgrade........................................................................ 8-5
WebLogic ................................................................................................................ 8-5
Jetty or Tomcat ....................................................................................................... 8-5
Dataloader Upgrade .................................................................................................... 8-6
POS Log Generator Upgrade ..................................................................................... 8-6
Xservices Upgrade ....................................................................................................... 8-7
Upgrading Xenvironment .......................................................................................... 8-7
9 Internationalization..........................................................................9-1
Translation .................................................................................................................... 9-1
Localization................................................................................................................... 9-2
Configuration Accelerators........................................................................................ 9-2
ix
Multi-Keystroke Character Entry ............................................................................. 9-2
Fiscalization .................................................................................................................. 9-2
Features ................................................................................................................... 9-3
A String Encrypter Utility................................................................... A-1

Running the Encrypter............................................................................................... A-1
B Public Key Certificates................................................................... B-1

Introduction ..................................................................................................................B-1
OpenSSL & Keytool Utility .......................................................................................B-2
Where To Find OpenSSL & Sun’s Keytool Utility ............................................ B-2
Add OpenSSL & Keytool Utility to the System Path (Windows)................... B-2
Certificate File Directories .................................................................................... B-3
Windows.......................................................................................................... B-3
Linux ................................................................................................................ B-3
Create a Certificate Authority.............................................................................. B-4
openssl.cnf ....................................................................................................... B-4
cacert.pem........................................................................................................ B-6
Certificate Management Strategy Detail ............................................................ B-8
Validation ............................................................................................................... B-8
Certificate Authority-Signed Certificates: Oracle Retail Xstore Office ............B-9
Customer Responsibility: Oracle Retail Xstore Office...................................... B-9
What you need to know before creating certificates................................. B-9
To create and deploy Certificate Authority-Signed Certificates ............. B-9
The instructions in steps 4 and 5 should be followed by the Certificate
Authority ....................................................................................................... B-11
The following instructions should be followed by the Certificate Authority
B-11
Integrator’s Responsibility: Xstore Office ............................................................B-13
Certificate Authority-Signed Certificates: Xservices ..........................................B-14
Customer Responsibility: Xservices.................................................................. B-14
What you need to know before creating certificates............................... B-14
To create and deploy Certificate Authority-Signed Certificates for Xservices
B-14
Certificate Authority-Signed Certificates: Apache .............................................B-17
Customer Responsibility: Apache..................................................................... B-17
To create and deploy Certificate Authority-Signed Certificates for ApacheB-
17
The instructions in this step should be followed by the Certificate Authority.
B-19
Integrator’s Responsibility: Web Server........................................................... B-19
Certificate Authority-Signed Certificates: Xstore Point of Service Mobile ...B-20
The instructions in steps 4 and 5 should be followed by the Certificate Authority
x
B-21
The instructions in this step should be followed by the Certificate AuthorityB-22
Install the Certificate on Android ..................................................................... B-23
Self-Signed Certificates: Oracle Retail Xstore Office.........................................B-23
Customer Responsibility: Oracle Retail Xstore Office.................................... B-23
Suggested certificate rotation strategy ...................................................... B-23
To create and deploy Self-Signed Certificates.......................................... B-24
Integrator’s Responsibility: Xstore Office ............................................................B-25
Self-Signed Certificates: Xservices.........................................................................B-26
Customer Responsibility: Xservices.................................................................. B-26
To create and deploy Self-Signed Certificates for Xservices.................. B-27
Self-Signed Certificates: Apache ............................................................................B-28
Customer Responsibility: Apache..................................................................... B-28
To create and deploy Self-Signed Certificates for Apache ..................... B-28
Integrator’s Responsibility: Web Server........................................................... B-30
Self-Signed Certificates for Xstore Point of Service Mobile.............................B-30
Install the Certificate on Android ..................................................................... B-32
Xenvironment Certificates .......................................................................................B-32
Generating and Importing the Key File (Windows)....................................... B-32
To create and deploy certificates for Xenvironment ............................... B-32
Digital Signatures......................................................................................................B-33
Digital Signatures - Windows............................................................................ B-34
Linux Instructions......................................................................................................B-37
Generating and Importing the Key File (Linux) ............................................. B-37
Installing OpenSSL in Linux .............................................................................. B-37
Generating the Key File in Linux ...................................................................... B-37
Importing the Key File in Linux ........................................................................ B-38
Digital Signatures - Linux .................................................................................. B-39
Annual Distribution Requirements.......................................................................B-41
Overview .............................................................................................................. B-41
Self-Signed Certificates................................................................................ B-41
Certificate Authority-Signed Certificates ................................................. B-42
Annual Key Rotation: Certificate Authority-Signed Certificates ....................B-43
For Xstore Point of Service and Xstore Office Application Server ............... B-43
For Xservices ........................................................................................................ B-45
For Apache............................................................................................................ B-48
Annual Key Rotation: Self-Signed Certificates ...................................................B-49
For Xstore Point of Service and Xstore Office Application Server ............... B-49
For Xservices ........................................................................................................ B-51
xi
For Apache............................................................................................................ B-52
Why Certificates Are Used.......................................................................................B-53
Types of Certificate Management ..........................................................................B-53
Certificate Authority ........................................................................................... B-53
Self-Signed Certificates ....................................................................................... B-54
Where Certificates Are Used ...................................................................................B-55
Xstore Point of Service to Xstore Office Application Server ......................... B-55
Xstore Point of Service to Xenvironment ......................................................... B-55
JMX console .......................................................................................................... B-55
Xenvironment and Xstore Office to Web Server............................................. B-55
Annual Requirements...............................................................................................B-55
Choosing a Certificate Management Strategy......................................................B-56
Certificates signed by a CA ................................................................................ B-56
Self-signed Certificates ....................................................................................... B-56
Certificates suspected to be compromised ...................................................... B-56
Terms used in this section........................................................................................B-56
C About Xstore Suite GenKeys......................................................... C-1

Overview .......................................................................................................................C-1
About Encryption Key Expiration - Credit Ciphers Only ...................................C-2
Key Types Overview...................................................................................................C-2
Cipher Health Codes...................................................................................................C-3
Open Format Export ....................................................................................................C-4
Working with Data Encrypted Using Xstore Point of Service ............................C-5
Generate Key 1 .......................................................................................................C-5
Console.............................................................................................................C-5
ciphers.csv Contents ......................................................................................C-5
ccenc.2015-01-01.cip Contents ......................................................................C-5
Deploy Key 1 ..........................................................................................................C-6
ttr_credit_debit_tndr_lineitm.acct_nbr Contents ......................................C-6
Generate Key 2 .......................................................................................................C-6
Console.............................................................................................................C-6
ciphers.csv Contents ......................................................................................C-6
ccenc.2015-02-01.cip Contents ......................................................................C-7
Deploy Key 2 ..........................................................................................................C-7
Identifying the Key for Decryption.....................................................................C-7
Console Cipher Details...............................................................................................C-7
For example: ...........................................................................................................C-8
Rotating Key-Encryption-Key ...................................................................................C-9
Creating a Public/Private Key Pair .........................................................................C-10
Import a Public Key Generated by Another System .........................................C-10
Configure the Public Key.........................................................................................C-11
Example.................................................................................................................C-11
xii
D PCI Best Practices: Implementation & Configuration ................. D-1
PCI Implementation Best Practices ......................................................................... D-1
About CISP Compliance...................................................................................... D-1
About the PCI Data Security Standard.............................................................. D-2
Audience......................................................................................................... D-2
What the reader should already know....................................................... D-2
How this appendix is organized ................................................................. D-2
PCI Best Practices Revision History................................................................... D-2
Overview of the Cardholder Data Environment ............................................. D-3
Cardholder Data Flow Diagram......................................................................... D-4
PCI Data Security Standard ...................................................................................... D-5
Build and Maintain a Secure Network .............................................................. D-5
Protect Cardholder Data...................................................................................... D-5
Maintain a Vulnerability Management Program............................................. D-5
Implement Strong Access Control Measures ................................................... D-5
Regularly Monitor and Test Networks ............................................................. D-5
Maintain an Information Security Policy .......................................................... D-5
Achieving PCI Compliance....................................................................................... D-6
Build and Maintain a Secure Network .............................................................. D-6
Requirement 1: Install and maintain a firewall configuration to protect
cardholder data.............................................................................................. D-6
Requirement 2: Do not use vendor-supplied defaults for system passwords
and other security parameters..................................................................... D-7
Protect Cardholder Data.................................................................................... D-10
Requirement 3: Protect stored cardholder data ...................................... D-10
Requirement 4: Encrypt transmission of cardholder data across open, public
networks ....................................................................................................... D-13
Maintain a Vulnerability Management Program........................................... D-14
Requirement 5: Use and regularly update anti-virus software or programs
D-14
Requirement 6: Develop and maintain secure systems and applicationsD-14
Implement Strong Access Control Measures ................................................. D-15
Requirement 7: Restrict access to cardholder data by business need to know
D-15
Requirement 8: Assign a unique ID to each person with computer accessD-
15
Requirement 9: Restrict physical access to cardholder data ................. D-17
Regularly Monitor and Test Networks ........................................................... D-18
Requirement 10: Track and monitor all access to network resources and
cardholder data............................................................................................ D-18
Requirement 11: Regularly test security systems and processes........ D-18
Maintain an Information Security Policy ........................................................ D-19
Requirement 12: Maintain a policy that addresses information security for all
personnel ...................................................................................................... D-19
Credit Card Security Installation Checklist ........................................................ D-20
xiii
Password Management............................................................................................ D-21
Remote Access..................................................................................................... D-21
Windows .............................................................................................................. D-21
Employees with Access to Xstore Point of Service Applications ................ D-21
Database Users.................................................................................................... D-22
Xstore Point of Service Versioning Methodology.............................................. D-22
PCI Configuration Best Practices........................................................................... D-22
Clear virtual memory on shutdown ................................................................ D-23
Removal Historical Sensitive Authentication Data ....................................... D-23
Ensure the register has a firewall in place ...................................................... D-23
Windows 7, Windows 8, Windows 10, Windows Vista, Server 2008, Server
2008 R2, PosReady 7, and So On ............................................................... D-24
Change Operating System Shell ....................................................................... D-24
Disable Task Manager........................................................................................ D-25
Disable Sensitive Buttons on Windows Security Screen............................... D-26
Disable Fast User Switching.............................................................................. D-26
Disable UAC (User Account Control) on Windows Vista, 7, 8, 2k8, & 2k8R2D-26
Disable Command Prompt Support in Safe Mode ........................................ D-27
Configure Automatic OS Login........................................................................ D-27
Disable System Restore...................................................................................... D-28
Install Encryption Cipher File........................................................................... D-28
Review and Confirm Receipt Masking............................................................ D-28
PCI Compliant Delivery of Updates................................................................ D-29
PCI Compliant Remote Access ......................................................................... D-29
Verify User Logins Are Complex and Changed on a Regular Basis........... D-30
Operating System ........................................................................................ D-30
Encrypt the pagefile.sys file .............................................................................. D-30
Disable Complete Memory Dump................................................................... D-31
Enable Database & Operating System Audit Logging.................................. D-31
Delete expired certificates and keys................................................................. D-32
To delete an old certificate ......................................................................... D-32
To delete an old key .................................................................................... D-33
Database Communication Encryption.................................................................. D-34
Oracle ................................................................................................................... D-34
SQL Server ........................................................................................................... D-35
Turning off Database Communication Encryption ....................................... D-35
Oracle ............................................................................................................ D-35
SQL Server.................................................................................................... D-36
Data Privacy ............................................................................................................... D-36
Data Privacy Application Programming Interface Tool ............................... D-36
End User Access and Other Requests (Data Access) ............................. D-36
Data Removal............................................................................................... D-37
Anonymization ............................................................................................ D-39
Customer Consent....................................................................................... D-40
Enabling Data Privacy ....................................................................................... D-40
xiv
E Base OS and DB Configuration..................................................... E-1
Base Operating System Configurations .................................................................. E-1
Base Software Installation Configurations............................................................. E-2
Prerequisites ........................................................................................................... E-2
F Xstore Office Broadcaster System.................................................F-1

Overview ....................................................................................................................... F-1
Generic Broadcasters................................................................................................... F-2
Supported PosLog Data Formats .............................................................................. F-2
Object Format ......................................................................................................... F-2
Raw XML String Format....................................................................................... F-3
Subset Format......................................................................................................... F-3
Currently Available Broadcasters............................................................................. F-3
Customer Engagement Cloud Service Broadcaster Considerations.............. F-4
XBR Broadcaster Considerations......................................................................... F-4
The Broadcaster Database Table............................................................................... F-5
trn_poslog_work_item Table ............................................................................... F-5
service_id Field ............................................................................................... F-6
work_status Field ........................................................................................... F-6
Broadcaster Configuration ......................................................................................... F-7
Getting Started ....................................................................................................... F-7
Optional Parameters For Broadcasters................................................................... F-10
Customer Engagement Cloud Service Broadcaster............................................. F-11
XBR Broadcaster......................................................................................................... F-13
Order Management System Cloud Service Broadcaster .................................... F-16
Generic Object Broadcaster ..................................................................................... F-18
Generic String Broadcaster ...................................................................................... F-20
Retail Sales Audit Broadcaster................................................................................ F-22
Broadcaster Configuration for a Multiple-instance (Cluster) Installation..... F-24
Multiple Broadcaster Configuration................................................................. F-24
Customer Engagement Cloud Service Example...................................... F-24
Generic Poslog Object Broadcaster Example............................................ F-25
Jaxws Broadcaster Configuration...................................................................... F-26
Broadcaster Processing ............................................................................................. F-26
Monitoring Broadcaster Status................................................................................ F-27
Periodic Maintenance of the trn_poslog_work_item Table .............................. F-27
Testing and Debugging ............................................................................................ F-28
Developer’s Notes...................................................................................................... F-28
Developing a Custom Broadcaster.................................................................... F-28
Raw XML String Format..................................................................................... F-28
XML Schema Definition Defined Object Format ............................................ F-28
xv
G Replication ...................................................................................... G-1
Overview ...................................................................................................................... G-1
Replication System Objectives:........................................................................... G-1
Replication Design Overview .................................................................................. G-2
Re-sequencing Publisher .......................................................................................... G-2
How data is re-sequenced ................................................................................... G-2
Saving data to the Xstore Office database......................................................... G-3
Sending data to the Broadcaster......................................................................... G-3
Soft ordering - what can be expected? ....................................................... G-3
Soft ordering - why is it important? ........................................................... G-3
Running Multiple Xstore Office Instances in a Cluster...................................... G-4
xcenter.properties Settings........................................................................................ G-4
cluster.processes.enabled .................................................................................... G-4
replication.publisher.resequencing_delay.seconds ......................................... G-5
replication.publisher.polling_interval.milliseconds........................................ G-5
replication.publisher.threads_per_orgid .......................................................... G-5
dtv.xcrepl.db.driver.............................................................................................. G-5
dtv.xcrepl.db.url ................................................................................................... G-5
dtv.xcrepl.db.user................................................................................................. G-5
dtv.xcrepl.db.password ....................................................................................... G-5
Xstore Office Replication Database ........................................................................ G-5
rpl_replication_data Table .................................................................................. G-6
Periodic Maintenance of the rpl_replication_data Table......................... G-8
Monitoring the Replication Processes ........................................................ G-8
Replication GUI - Oracle Retail Xstore Office ...................................................... G-8
H Tips & Troubleshooting ................................................................. H-1

Restoring the Windows Shell................................................................................... H-1
Opening a Command Prompt in a Location.......................................................... H-2
Xstore Point of Service Email ................................................................................... H-3
e-Receipts ............................................................................................................... H-3
Example.................................................................................................................. H-3
I Uninstall Procedures........................................................................I-1
Uninstalling Jetty.......................................................................................................... I-1
Uninstalling Apache Tomcat...................................................................................... I-1
J Store Inventory Management Integration......................................J-1

Overview ........................................................................................................................ J-1
Integration using a Web Service................................................................................ J-2
Store Inventory Management Server................................................................... J-3
Store Inventory Management DB......................................................................... J-3
xvi
Item Disposition...................................................................................................... J-3
Error Handling........................................................................................................ J-3
Logging .................................................................................................................... J-4
K Installation Order ............................................................................ K-1

Enterprise Installation Order ................................................................................... K-1
L Revision History ..............................................................................L-1

Revision History 17.0.2, Revision 07 ........................................................................ L-1
Revision History 17.0, Revision 06 ........................................................................... L-4
Revision History 16.0.1, Revision 02 ...................................................................... L-10
Revision History 16.0.0.1, Revision 11 ................................................................... L-10
Revision History 16.0.0.1 .......................................................................................... L-11
Revision History 16.0, Revision 15 ......................................................................... L-11
xvii
Revision History 16.0 ................................................................................................ L-13
Revision History 15.0 ................................................................................................ L-17
Revision History 7.1, Doc Version 02..................................................................... L-18
Revision History 7.1 .................................................................................................. L-18
Implementation and Security Guide i-xviii

i-xix Implementation and Security Guide
Send Us Your Comments
Oracle Retail Xstore Suite Implementation and Security Guide, release 17.0.2.
Oracle welcomes customers' comments and suggestions on the quality and usefulness of
this document.
Your feedback is important, and helps us to best meet your needs as a user of our
products. For example:
• Are the implementation steps correct and complete?
• Did you understand the context of the procedures?
• Did you find any errors in the information?
• Does the structure of the information help you with your tasks?
• Do you need different information or graphics? If so, where, and in what format?
• Are the examples correct? Do you need more examples?
If you find any errors or have any other suggestions for improvement, then please tell us
your name, the name of the company who has licensed our products, the title and part
number of the documentation and the chapter, section, and page number (if available).
Note: Before sending us your comments, you might like to check that
you have the latest version of the document and if any concerns are
already addressed. To do this, access the Online Documentation
available on the Oracle Technology Network Web site. It contains the
most current Documentation Library plus all documents revised or
released recently.
Send your comments to us using the electronic mail address: retail-doc_us@oracle.com

Please give your name, address, electronic mail address, and telephone number
(optional).
If you need assistance with Oracle software, then please contact your support
representative or Oracle Support Services.
If you require training or instruction in using Oracle software, then please contact your
Oracle local office and inquire about our Oracle University offerings. A list of Oracle
offices is available on our Web site at www.oracle.com
xx
Preface
The Implementation and Security Guide describes the requirements and procedures to
install and configure this Oracle Retail Xstore Suite release.
Audience
This Implementation and Security Guide is for the following audiences:
• System administrators and operations personnel
• Database administrators
• System analysts and programmers
• Integrators and implementation staff personnel
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility
Program website at http://www.oracle.com/pls/topic/
lookup?ctx=acc&id=docacc.
Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For
information, visit http://www.oracle.com/pls/topic/
lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/
lookup?ctx=acc&id=trs if you are hearing impaired.
Related Documents
For more information, see the following documents in the Xstore Suite 17.0.2
documentation set:
• Xstore Suite Release Notes
Customer Support
To contact Oracle Customer Support, access My Oracle Support at the following URL:
https://support.oracle.com
When contacting Customer Support, please provide the following:
• Product version and program/module name
• Functional and technical description of the problem (include business impact)
• Detailed step-by-step instructions to re-create
• Exact error message received
• Screen shots of each step you take
xxi
Review Patch Documentation
Review Patch Documentation

When you install the application for the first time, you install either a base release (for
example, 17.0.2) or a later patch release (for example, 17.0.2.1). If you are installing the
base release or additional patch releases, read the documentation for all releases that
have occurred since the base release before you begin installation. Documentation for
patch releases can contain critical information related to the base release, as well as
information about code changes since the base release.
Improved Process for Oracle Retail Documentation

Corrections
To more quickly address critical corrections to Oracle Retail documentation content,
Oracle Retail documentation may be republished whenever a critical correction is
needed. For critical corrections, the republication of an Oracle Retail document may at
times not be attached to a numbered software release; instead, the Oracle Retail
document will simply be replaced on the Oracle Technology Network Web site, or, in the
case of Data Models, to the applicable My Oracle Support Documentation container
where they reside.
This process will prevent delays in making critical corrections available to customers.
For the customer, it means that before you begin installation, you must verify that you
have the most recent version of the Oracle Retail documentation set. Oracle Retail
documentation is available on the Oracle Technology Network at the following URL:
http://www.oracle.com/technetwork/documentation/oracle-retail-100266.html
An updated version of the applicable Oracle Retail document is indicated by Oracle part
number, as well as print date (month and year). An updated version uses the same part
number, with a higher-numbered suffix. For example, part number E123456-02 is an
updated version of a document with part number E123456-01.
If a more recent version of a document is available, that version supersedes all previous
versions.
Oracle Retail Documentation on the Oracle Technology

Network
Documentation is packaged with each Oracle Retail product release. Oracle Retail
product documentation is also available on the following Web site:
http://www.oracle.com/technology/documentation/oracle_retail.html
(Data Model documents are not available through Oracle Technology Network. These
documents are packaged with released code, or you can obtain them through My Oracle
Support.)
Documentation should be available on this Web site within a month after a product
release.
Conventions
The following text conventions are used in this document:
xxii
Conventions
Convention Meaning
boldface Boldface type indicates graphical user interface elements associated
with an action, or terms defined in text or the glossary.
italic Italic type indicates book titles, emphasis, or placeholder variables for
which you supply particular values.
monospace Monospace type indicates commands within a paragraph, URLs, code
in examples, text that appears on the screen, or text that you enter.
xxiii
1
Getting Started
The Xstore Point of Service Implementation and Security Guide provides general
information about Xstore Point of Service product architecture, the technical landscape,
the enterprise flow for your store systems, and the procedures and instructions
necessary to install or upgrade Xstore Point of Service and its components using InstallX.
Detailed instructions for creating public key certificates for use within a managed
network, specifically for use with Xstore Point of Service, Oracle Retail, Oracle Retail
Xstore Office, and Oracle Retail Xenvironment are also included in this guide.
Important: This document is intended only as a guide for a typical

installation. Since installations will differ from customer to customer, it
is up to the person performing the installation to know when and how
to deviate from this guide.
Who Should Use This Guide

This guide is intended for anyone responsible for Xstore Point of Service installation,
configuration, or updates.
Anyone using this guide should have a working knowledge of XML, the network system
being used and, depending upon the environment and system you are using, Oracle or
SQL Server database, and the Windows or the Linux operating system.
Getting Started 1-1

Xstore Point of Service Suite Components and Modules

For a better understanding of the Xstore Point of Service suite components and where
they are used (store-level or corporate-level), this table lists each component, where it is
used, and whether it is a required component or an optional module. A link to
additional information about each component is also provided.
Table 1-1: Xstore Point of Service Suite Component Use Matrix
Component Store Corporate Additional Information
Required Components
Xstore Point of “Xstore Point of Service”

Service 
Xenvironment  “Xenvironment”
DataLoader   “DataLoader”
Xcenter “Xcenter”
(Oracle Retail 
Xstore Office)
GenKeys  “GenKeys”
Application “WebLogic”
Server
 “Jetty”
“Apache Tomcat”
JRE   “JRE”
Database Oracle
 
SQL Server
Optional Components
Xstore Point of “Xstore Point of Service Mobile”

Service Mobile 
Oracle Retail “Oracle Retail Xstore Settlement”

Xstore 
Settlement
Xadmin “Xadmin”
(Oracle Retail 
Xstore Office)
EFTLink   “EFTLink”
Oracle Retail Speak with your Oracle product representative for

Xstore   information about this product.
Payment
Web Server Required for deployments from Oracle Retail

 Xstore Office.
“Web Server”
1-2 Implementation and Security Guide

Xstore Point of Service

Xstore Point of Service is a Java-based POS application that uses industry standard Java
SE, Java EE, and other open-source technologies. It has a rich feature set that is highly
configurable using XML and SQL, and is easily extended with Java coding. Its open
architecture provides many interfacing and integration options.
PA-DSS Validation
Xstore Point of Service 17.0.2 is not eligible for PA-DSS validation because it relies on
third-party PA-DSS application that resides on the Pinpad terminal for storing,
processing or transmission of cardholder data. This is done through EFTLink (for more
information, see EFTLink). Additionally, Xstore Point of Service 17.0.2 does not permit
manual input of card data.
Xenvironment
The Xenvironment application manages register-to-register direct communication and
nightly processing. Xenvironment also prevents user access to the standard PC desktop
by replacing the operating system's default shell interface.
The Xenvironment application is installed on a POS register and provides a
communication link between the lead and non-lead registers. An internal messaging
framework enables Xenvironment to send messages between the Xenvironment engine
and the Xenvironment GUI, and between a lead register and non-lead registers. The
messaging framework also allows messages to be sent back and forth between
Xenvironment and the Xstore Point of Service application. Thus, Xstore Point of Service
can notify Xenvironment when a specific task must be completed. For example, store
closing processes handled by Xenvironment are started automatically when Xstore Point
of Service sends a message through this communication link. See the Oracle Retail
Xenvironment User Manual for detailed information about the Xenvironment application.
DataLoader
The DataLoader application is responsible for translating flat data files into database
data that can be used by the Xstore Suite. For example, many host systems can be
configured to export data to a delimited flat file. Then, that flat file is delivered to the
stores throughout the chain. Finally, the flat file is read in by the DataLoader and loaded
into the store databases for use. This is used for propagating data changes (such as
prices, employees, etc.) to Xstore Point of Service or Xstore Office databases throughout
the enterprise. See the Xstore Point of Service Host Interface Guide for detailed information
about the DataLoader application.
DataLoader is also responsible for loading data files from Oracle Retail Merchandising
Operations Management (MOM) into the Xstore Suite databases.
GenKeys
GenKeys is a utility used to create the Xstore Point of Service cipher files (.cip) used for
encryption, and for encrypting data using the Xstore Point of Service .cip files. This
utility combines the Encrypter utility and the GenKeys utility.
Xcenter
The Xcenter application (a part of Oracle Retail Xstore Office) is a Java messaging
framework that runs on an application server. Xstore Point of Service uses Xcenter for
reading and writing data. Xcenter provides data access through WebLogic, Tomcat, or
Jetty.
Implementation and Security Guide 1-3

The Xcenter Database is a central data repository containing consolidated data from
specified database tables in every store. These POS transaction records from all stores
can be made available to host systems, analytics tools, and other transaction processing
engines. Xcenter is also an on-line data source for messaging-based inquiries originating
from Xstore Point of Service/Xenvironment. Data is made available to Xcenter by direct
persistence, replication, data loading, Xadmin, and deployment services, depending on
your deployment model.
Xadmin
Xadmin (a part of Oracle Retail Xstore Office) is an application used to administer Xstore
Point of Service’s corporate-based functions over the customer’s intranet, providing the
corporate office access to store-level data in the Xcenter database and the ability to
remotely manage many local Xstore Point of Service data and configuration options. See
the Oracle Retail Xstore Office User Guide for detailed information about the Xstore Office
application.
EFTLink
EFTLink is an efficient, platform-independent way of connecting Point of Sale (POS)
systems with multiple card readers and PIN Entry Devices (PEDs), as well as with a
wide range of Electronic Payment Systems (EPS). This allows EFTLink to serve as a
router and protocol converter that presents Xstore Point of Service with a standard
interface to card readers, PEDs, and the authorization systems used by a retailer. See the
Oracle Retail EFTLink Core Configuration Guide, the Oracle Retail EFTLink Framework
Installation Guide, and the Oracle Retail EFTLink Security Guide for detailed information
about the EFTLink application.
InstallX
InstallX is used to build the Xstore Point of Service installations, and to install Xstore
Point of Service and the associated components.
WebLogic
Oracle WebLogic is the preferred Java Application Server.
Jetty
Jetty is a Java Application Server.
Apache Tomcat
Tomcat is a Java Application Server.
JRE
Java runtime components are not included in the Xstore Point of Service distribution. An
InstallX component, jrepackager, is available in the tools folder of the InstallX distro and
can be used to create a platform-appropriate JRE that is suitable for use with Xstore Point
of Service components.
Xstore Point of Service Mobile

Xstore Point of Service Mobile is a function of the Xstore Point of Service application that
enables the software to be run on a remote handheld device. Xstore Point of Service’s
mobile application is a web interface that accesses a Xstore Point of Service server

Real-Time Product Integration with Xstore Point of Service
through a wireless connection, and offers Xstore Point of Service functions through a
mobile-friendly GUI presentation on a handheld device.
Oracle Retail Xstore Settlement

Oracle Retail Xstore Settlement is a centralized debit and credit card settlement solution
residing on a server at the corporate office.
Web Server
A web server (for example, Apache or Internet Information Services) is used by Oracle
Retail Xstore Office for uploads, and by Xenvironment for uploads and downloads.

The following products have been integrated and tested with base Xstore Point of
Service.
Customer Engagement Cloud Services - This software solution for customer
relationship marketing (CRM) and customer loyalty is a central repository of customer
data, providing a look at a customer’s activity including purchases, returns, and
participation in promotions and special offers. This information provides the
information needed to build and develop long-term, profitable relationships by
rewarding purchasing behavior and targeting offers and incentives to the right people
based on their actual activity and transaction information.
Order Management Cloud Service - This direct commerce software provides a method
for managing your retail transactions, including order management, fulfillment,
warehousing/inventory control, customer service, merchandising, marketing and
finance.
Order Broker Cloud Service - This cross-channel order broker solution provides real-
time visibility of inventory availability across all retail channels and distribution centers
from any point of service.
Store Inventory Management - This inventory management solution enables real-time,
accurate, and accessible store-stock data to execute commerce anywhere through
consistent, efficient, and effective in-store processes and procedures.
Retail Extension Module - This module provides point-of-service software with
information normally reserved for online shopping. Cashiers can interact with a
customer’s online shopping cart, or view recommendations based upon a customer’s
purchases.
Quick Address Services - When looking up addresses using Quick Address Services
(QAS), valid address information is provided to the user, allowing them to quickly
choose a correct, validated address on a minimum of entered information. This speeds
address lookups and improves data validity.
Note: Contact your Oracle representative for more information about

these integrated software solutions.


2
Prerequisites for Installing Xstore Office
Before installing any components of the Xstore Office, it is necessary to prepare the
system on which the software will be installed.
System Requirements
Xstore Office is supported on the following software:
Table 2-1: Xstore Office Supported Software
Type Software
Operating System Oracle Enterprise Linux 6
Oracle Enterprise Linux 7
Microsoft Windows Server 2012 R2
Microsoft Windows Server 2016

Note: Oracle Retail assumes that the retailer has ensured its
Operating System has been patched with all applicable
Windows updates.
Database Oracle Database 12c
SQL Server 2012 SP1
SQL Server 2014 SP1
SQL Server 2016
Web Server Apache HTTPD
Microsoft Internet Information Services (IIS)
Application Server Oracle WebLogic Server 12.2.1.3
Tomcat 9.0.11
Jetty 9.4.11
Prerequisites for Installing Xstore Office 2-1

Install Web Server
Supported Web Browsers

Xstore Office can be accessed through the following web browsers:
• Mozilla Firefox ESR 52+
• Internet Explorer 11
• Chrome 55+
Backup and Recovery

The retailer is responsible for ensuring that there is a backup and recovery system for all
customer and employee personal data.
The backup and recovery system must meet the following requirements:
• Secure backup and recovery must be available in a timely manner.
• Encryption of all backups (including removable media or replication data).
• Capability for shopper bulk data export options.
Install Web Server

When installing the web server:
1. Install and enable the HTTP Server.
Follow the procedures specified by your OS or HTTP service vendor to install the
HTTP server, taking care to ensure that WebDAV and HTTPS functionality is
installed with it, if it is optional.
2. Enable HTTPS with TLS.
Xstore Office requires HTTPS over TLSv1.2 for communications with the HTTP
server. Follow the procedures specified by your OS or HTTP service vendor to
enable HTTPS functionality, and to ensure that communications over TLSv1.2 are
possible.
3. Disable non-HTTPS endpoint.
Most HTTP implementations will enable a standard, non-HTTPS, endpoint by
default. This endpoint should be disabled or rendered unreachable by a firewall to
prevent its use.
4. Enable HTTPS basic authentication.
Follow the procedures specified by your OS or HTTPS service vendor to enable
HTTPS basic authentication for your HTTPS service. Credentials will be required by
the Xstore Office and Xstore Point of Service applications to allow the uploading and
downloading of files.
5. Enable WebDAV.
Upload functionality, which uses HTTP PUT calls, requires WebDAV functionality to
be enabled. Follow the procedures specified by your OS or HTTP service vendor to
enable WebDAV functionality. If necessary, grant access to the users responsible for
uploading files to allow HTTP PUT functions to be accessible.
6. In IIS, enable additional MIME types.
Because Microsoft IIS does not support unknown MIME types, the following file
types must be enabled:
- .dat

Xstore Office Installation .zip File
- .mnt
- .cip

1. Download the correct Xstore Office .zip installation file for your system from the
Oracle Software Delivery Cloud.
2. Move the file to an easy-to-find location.
3. Extract the files in the .zip file.
4. This will create the files that are in the <root_directory>.
<root_directory>
The extracted .zip file will create a set of directories and files, which will contain the
Xstore Office installation files.
artifacts
Build artifacts.
RTLog-Generator
Installation files for the RTLog Generator.
jetty-X.X.X-OS-installer-YY.jar
The installer for Jetty, where:
• X.X.X is the version number.
• OS is the operating system.
• YY is the build number.
tomcat-X.X.X-OS-installer-YY.jar
The installer for Tomcat, where:
• X.X.X is the version number.
• OS is the operating system.
• YY is the build number.
Installation File Directories

There are a set of package directories for Xstore Office, each of which contain installation
files for a particular system. Use the correct package directory for your installation. See
“Installation File Directories” for more information about these directories.


In the <root_directory>, there will be a set of directories, one of which will contain the
Xstore Office package for your install.
oraclepdb_install,upgrade
Installation and upgrade files for an Xstore Office system that connects to an Oracle
database that uses pluggable databases. Contains Office Installation .zip Files.
Important: Xstore Point of Service does not support Oracle Managed

Files when using Oracle pluggable databases.
oracle_install,upgrade
Installation files for an Xstore Office system that connects to an Oracle database.
Contains Office Installation .zip Files.
mssql_install,upgrade
Installation and upgrade files for an Xstore Office system that connects to a Microsoft
SQL Server database that does not use Unicode characters. Contains Office Installation
.zip Files.
mssql-unicode_install, upgrade
SQL Server database that uses Unicode characters. Contains Office Installation .zip Files.
Office Installation .zip Files

In each of the Installation File Directories, there are two .zip files, where:
• X_X_X_X_X is the version and build number.
• CCC is the customer ID (XST for base Xstore Office).
• V_V_V is the customer release version.
OracleRetailXstoreOffice_X_X_X_X_CCC_V_V_V.zip
Extract this .zip file to create a directory that contains installation files for Xstore Office
and related software. This directory will have the format:
X.X.X.X.XXX_V.V.V
where:
• X.X.X.X.XXX is the version and build number.
• V.V.V is a customer release version.
This extracted directory will contain the following directories:
tools
Various tools used by the installation procedure and the Xstore Office. This includes the
following subdirectories:
- dataloader - Installation files for DataLoader.
- poslog - Installation files for the Xstore Office POS Log Generator.

Java
xcenter
Installation files for Xstore Office.
OracleRetailXstoreCommon_X_X_X_X_X_CCC_V_V_V.zip
Extract this .zip file to create a directory X_X_X_X_X_CCC_V_V_V, where:
This extracted directory will contain the following directory:
tools
- genkeys - Installation files for the GenKeys utility. This includes the string
encryption utility (see Appendix A: “String Encrypter Utility”) used to encrypt
information in the installation procedure, and generates security keys for use by
Xstore Office.
- jrepackager - Creates a JRE .zip file used by the installation procedure.
Java
Several Java components must be installed as part of the Xstore Office installation
procedure.
Perform the following procedures:
• “Java Runtime Environment (JRE)”
• “Java Development Kit (JDK)”
• “Create JRE Package”
Java Runtime Environment (JRE)

1. Download latest version of JRE 8 from Oracle.
Important: If you are upgrading from an earlier version of Xstore

Office, you must upgrade from JRE 7 to JRE 8.
2. Move the downloaded file to a temporary folder.

- Windows: c:\temp
- Linux: /tmp

Java
Java Development Kit (JDK)

JDK (Java Development Kit) is not included in the Tomcat or Jetty installers. A JRE (Java
Runtime Environment), with JCE (Java Cryptography Extension) functionality available,
is also required. The installers will confirm that it is present in the system's JDK prior to
installing.
Before installing Tomcat or Jetty, do the following:
1. Install the latest 64-bit 1.8 JDK. Available from Oracle. The JDK includes the JRE, so
you do not have to download both separately.
2. Change the JAVA_HOME system environment variable to point to the root of the JDK
install (for example, C:\Program Files\Java\jdk1.8.0_141).
The JAVA_HOME environment variable (set at the system level), will be used to find
the appropriate JDK. Any other JDK or JRE installs will be ignored.
3. Add the bin directory in the JAVA_HOME directory to the start of the PATH system
environment variable.
Note: The JAVA_HOME/bin directory must be placed at the start of

the PATH variable so that the system will find those executables first.
Enable Unlimited Java Encryption

To enable unlimited cryptography on the JRE, do the following:
1. Navigate to the directory where the 1.8 JDK is installed.
2. Within the JDK directory, navigate into the jre\lib\security.
For example, if the JDK is installed in:
C:\Program Files\Java\jdk1.8.0_141
the directory would be:
C:\Program Files\Java\jdk1.8.0_141\jre\lib\security
3. Open the file java.security in a text editor (for example, Wordpad or emacs).
4. Find the crypto.policy setting.
5. Change the setting to the following:
crypto.policy=unlimited
6. Save and close the file.
Java now has unlimited cryptography.
Create JRE Package

Before installing any Xstore Office components, you must create a custom JRE package
that will be used by the installation procedures.
7. In a file manager, navigate to the jrepackager directory extracted from the
OracleRetailXstoreCommon_X_X_X_X_X_CCC_V_V_V.zip file. See “Xstore Office
Installation .zip File” for more information.
8. Open the ant.install.properties file in a text editor (for example, Notepad or
emacs).
9. In the ant.install.properties file:

Java
a. Change the jre.package property to the correct location and name of the Java
Runtime Environment (JRE) package.
For example:
* In Windows:
jre.package=C\:\\temp\\jre-8u141-windows-i586.tar.gz
Note: The properties file requires a double backslash (\\) for a

Windows directory structure.
* In Linux:
jre.package=/tmp/jre-8u141-windows-i586.tar.gz
b. Change the platform.os property to the correct platform operating system:
* Linux 32-bit: linux
* Linux 64-bit: linux_64
* Windows 32-bit: windows
* Windows 64-bit: windows_64
10. Save and close the ant.install.properties file.
11. Open a command prompt.
12. Navigate to the jrepackager directory extracted from the
13. In the command prompt, create the JRE package with the command:
- In Windows:
java –jar xstore-17.0.2.XXX-V.V.V-CCC-jrepackager-windows.jar
- In Linux:
java –jar xstore-X.X.X.X.XXX-V.V.V-CCC-jrepackager-linux.jar
where:
- X.X.X.X.XXX is the version and build number.
- XXX is a build number
- V.V.V is a customer release version
- CCC is the three-letter customer ID
14. Open the .zip file created by the JRE packager process.
15. Extract the jre directory to the root directory in Windows, or the /opt directory in
Linux. For example, in Windows, you would have the directory:
C:\jre
In Linux you would have the directory:
/opt/jre
Java setup for Xstore Office is complete.

Database
Database
You will need a database either installed on the local system, or network access to a
database server. The database must be one of the following:
Oracle
In order for Xstore Office installs to proceed without errors, a number of objects need to
be created within the Oracle database instance before running the Xstore Office schema
script.
Installation Directory
Xstore Office assumes that the Oracle database has been installed in the oradata folder
for the Oracle instance.
• On Linux, this would be similar to /u01/app/oradata/xstore
• On Windows, this would be similar to c:\app\oracle\oradata\xstore.
OPEN_CURSORS Setup for Oracle

When using an Oracle database for Xstore Office, you must increase the default value of
open cursors at the DB level. This reduces the possibility of receiving "max cursors
exceeded" errors while running the applications. A baseline of 500 is recommended;
however, this value should be increased based on need.
OPEN_CURSORS specifies the maximum number of open cursors (handles to private
SQL areas) a session can have at once. You can use this parameter to prevent a session
from opening an excessive number of cursors.
Following is the method for adjusting the count is this statement, which must be run by
a system user:
alter system set open_cursors=<new_value> scope=both;
MS SQL Server
If you are using an MS SQL Server database, it must have the following properties:
• The instance name must be MSSQLSERVER.
• The Authentication Mode must be Mixed Mode (SQL Server authentication and
Windows authentication).
Creating Databases
The Xstore Office installation process does not automatically create databases. You must
create your own databases on your local system.
Xstore Office requires three databases to be created:
• An Xcenter database.
• An Xadmin database.
• An Xcenter replication database.
TLS Certificates
Several Xstore Office components require TLS certificates to encrypt inter-process
communication. You must either create your own, or receive these certificates from a
certificate authority.

WebLogic
If you will be creating your own certificates, you will need OpenSSL & Keytool Utility.
See Appendix B: “Public Key Certificates” for more information.
• If you are installing Xstore Office components for the first time, you will likely not
know all the security certificates you will require. The installation procedures will
inform you of the certificates you will require as you need them.
• If you have installed Xstore Office before, it is recommended that you either reuse
existing security certificates, or create new certificates prior to installing Xstore
Office components.
WebLogic
If you are installing WebLogic as your application server, see the Installation Guide for
Oracle WebLogic Server for installation prerequisites.
Tomcat or Jetty
If you are installing Tomcat or Jetty as your application server, you must download and
install a Java 8 SE Development Kit (JDK 8) from Oracle, and your JAVA_HOME variable
must point to that JDK for either Jetty or Tomcat to be installed. Additionally, you must
have Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 8
applied to the JRE within the JDK.
Jetty & Tomcat Memory Values

The guidelines in this section are provided as suggestions only, and may not apply to
your setup. These values will only be valid if the system is a dedicated application server
with a single instance of Jetty or Tomcat. Anything beyond that will require special
consideration. For Jetty, you will enter the Jetty memory values in step 153 on page 25.
For Tomcat, you will enter the Tomcat memory values in step 179 on page 28.
• Only 64-bit Windows and Linux systems are supported.
• Default configurations are provided based on the number of CPUs and amount of
RAM in the system.
• The Metaspace should be left at 256MB, unless performance-related issues
determine that it is an issue.
• On production systems, the recommendation for min and max heap size values is
that the minimum (initial) and maximum values should both be set to the same
value (i.e. the maximum). Any deviation from this will result in unwanted overhead
from garbage collection because the JVM will attempt to stay as close to the initial
value as possible.
64-bit OS and JDK

- The recommendation is to use a value of the total system memory minus 2GB to
allow for the OS and OS services to have sufficient RAM. However, if other
applications are being run on the server, above and beyond the basics (standard
OS services and AV software), it’s possible that this value may be too high.
- Some example values for 64-bit systems:
* 8GB of RAM installed – 6144MB Min/Max
* 16GB of RAM installed – 14336MB Min/Max

Tomcat or Jetty

3
Install Xstore Office
Overview
InstallX is used to assemble the Xstore Office application. This installation application is
used to package the Xstore Office application and to install and configure its associated
utilities. It is customer, operating system, and database platform independent.
Note: Refer to Chapter 8, “Upgrading Xstore Suite Components” for

information about upgrade, update, and patch installation types.
Xstore Office Installation

This procedure assumes you have completed the tasks in Chapter 2, “Prerequisites for
Installing Xstore Office”.
To install Xstore Office components, do the following:
Install GenKeys and String Encrypter Utility

This procedure installs GenKeys and the string encrypter utility described in
Appendix A: “String Encrypter Utility”.
1. Navigate to the genkeys directory extracted from the
emacs).
3. If necessary, change the installDir property to the directory where GenKeys will
be installed.
For example:
installDir = C\:\\xstore-genkeys

4. Change the customerId.salt property to your salt value.
Note: You must always use the same salt value when creating cipher
files.
Install Xstore Office 3-1

Xstore Office Installation

7. In the command prompt, navigate to the genkeys directory extracted from the
8. In the command prompt, install GenKeys with the command:
c:\jre\bin\java –jar xstore-X.X.X.X.XXX-V.V.V-CCC-
genkeys.jar
where:
- X.X.X.X.XXX is the version and build number.
- V.V.V is a customer release version.
- CCC is the three-letter customer ID.
Create Cipher Key Files

9. In a file explorer, navigate to the GenKeys directory configured in step 3 on page 1.
10. Navigate to the wrapper\conf directory.
11. Open the file gen-keys.conf in a text editor (for example, Notepad or emacs).
12. Locate the following line in the gen-keys.conf file (in Section 4):
wrapper.java.additional.4=-Ddtv.CustomerId=@customerId@
13. Change the value of the property to the encryption salt value to be used. Use a value
that is at least 8 characters long and hard to guess. (See Rotating Key-Encryption-
Key in Appendix C: “About Xstore Suite GenKeys”) This value will be used in
several other installations.
Important: If you are using a salt value other than the default, you
must create and apply a customer overlay to your project. See the
Oracle Retail Xstore POS and Xstore Office Development Environment
Setup (MOS ID 2158739.1) and Oracle Retail Xstore POS and Xstore Office
Build Server Setup White Paper (MOS ID 2055918.1) on My Oracle
Support (http://support.oracle.com/) for procedures on creating and
applying customer overlays.
For example:
wrapper.java.additional.4=-Ddtv.CustomerId=XST
14. Save the file.
Generate Rotating Keys for All Keys Except Debit/Credit

15. Comment out all statements in Sections 1 & 3.
16. Uncomment the highlighted command (below) in the gen-keys.conf file (in
Section 2):
# Section 2: Generate Rotating Cipher Keys (All Keys)
# Uncomment lines below and comment out Sections 1 & 3
# Update parameter.3 (start date) and parameter.4
# (end date) with the desired effective dates (YYYY-MM-DD)

Xstore Office Database Scripts
wrapper.app.parameter.2=-all
wrapper.app.parameter.3=2007-01-01
17. Change the wrapper.app.parameter.3 property to the date on which the
certificate will be first valid.
For example:
18. Change the wrapper.app.parameter.4 property to the last date on which the
certificate will be valid.
For example:
19. Save the file.
20. In a command prompt, navigate to the GenKeys directory configured in step 3.
21. Run the command:
Windows:
gen-keys.bat
Linux:
./gen-keys.sh
22. The rotating cipher key files are generated.

23. If you have not created the databases for Xstore Office, create them now. See
“Creating Databases” in Chapter 2, “Prerequisites for Installing Xstore Office” for
information about creating these databases.
Note: To support customers with multiple Organization IDs, a DB

script has been created for each organization ID a customer uses; so it
will not be necessary to manually search and replace this information
in SQL scripts.
SCHEMA scripts have been provided, and a PROD data and a TEST
data script are provided for each Organization ID.
24. Navigate to the xcenter directory extracted from the

OracleRetailXstoreOffice_X_X_X_X_CCC_V_V_V.zip file. See “Xstore Office

Important: You will need to repeat steps 26-28 for each schema in the
Xstore Office database (Xcenter, Xadmin, and Xcenter Replication).
25. Open the file xstore-B.B.B.B-V.V.V-CCC-xcenter-install-CREATE.sql

in a database interface (for example, SQLPlus or sqlcmd/SSMS).

26. Replace the database tokens with the appropriate values:
Important: For the Xcenter schema, the values entered for the
$(DbTblspace), $(DbSchema), and $(DbUser) values must match the
values set at build time. See the Xstore Point of Service and Xstore Office
Development Environment Setup document for more information.
- On many databases:
* $(DbName) - Desired name of the database.
* $(DbDataFilePath) - Location of data files in the file system.
- On all Oracle databases:
* $(DbIndexFilePath) - Location of index files in the file system.
* $(DbTblspace) - The desired database tablespace name.
Note: For the Xcenter schema, this must be consistent with the value
used at build time (default value: xstore).
* $(DbSchema) - The desired schema name.
Note: or the Xcenter schema, this must be consistent with the value
used at build time (default value: dtv).
* $(DbUser) - The desired schema username.
Note: or the Xcenter schema, this must be consistent with the value
used at build time (default value: pos).
- On Oracle PDB databases:

* $(dbSeedFilePath) - the location of the pdbseed folder.
* $(DbAdmin) - The PDB owner user’s username.
* $(DbAdmpwd) - The PDB owner user’s password.
27. Save the file.
28. Run the xstore-B.B.B.B-V.V.V-CCC-xcenter-install-CREATE.sql SQL
script.
29. Repeat steps 26-28 for each schema in the Xstore Office database (Xcenter, Xadmin,
and Xcenter Replication).
30. Run the xstore-B.B.B.B-V.V.V-CCC-xcenter-install-SCHEMA.sql
script.
31. Run the xstore-B.B.B.B-V.V.V-CCC-xcenter-install-SCHEMA-
SYNONYM.sql script.
32. Run the xstore-B.B.B.B-V.V.V-CCC-xcenterrepl-install-SCHEMA.sql
script.
33. Open the file xstore-B.B.B.B-V.V.V-CCC-XST-xadmin-install.sql in a
database interface (for example, SQLPlus or sqlcmd/SSMS).

Install an Application Server: WebLogic, Jetty, or Tomcat
34. Run the xstore-B.B.B.B-V.V.V-CCC-XST-xadmin-install.sql SQL script.

35. Run the data script that is appropriate for your organization(s) against the created
database.
- xstore-B.B.B.B-V.V.V-CCC-xcenter-install-PROD_DATA_ORG-
1000.sql
<OR>
- xstore-B.B.B.B-V.V.V-CCC-xcenter-install-TEST_DATA_ORG-
1000.sql against the xcenter database
36. Wait until the script completes, then verify the query executed successfully. (Contact
your Oracle representative if there are any problems).
37. Create a job to run sp_report stored procedure at your desired interval
(recommendation is 3 minutes) against the Xcenter DB.
Note: The sp_report stored procedure is responsible for generating

reporting data in the Xcenter database. The minimum
recommendation is to schedule it to run at a 3-minute interval. For
detailed instructions on scheduling the procedure, see the
documentation for your database, or contact your Oracle
representative.

Prerequisites for Application Server Installation
You will be prompted for the following information during the install process. You may
want to define these usernames, passwords, etc. before you begin the install process.
Important: If you are running multiple instances of WebLogic, Jetty,

or Tomcat on the same server you will have to make modifications that
deviate from this procedure. Contact your Oracle representative for
more information.
• Keystore Password (The password chosen when the Xstore Office TLS certificates
were created).
• Security Key Alias (The alias chosen when the Xstore Office TLS certificates were
created).
• Password that Xstore Point of Service will use to access Xstore Office.
• Tomcat only - Username and password that will be used to access the
Administration consoles.
• Jetty and Tomcat only - Jetty/Tomcat memory values (See “Jetty & Tomcat Memory
Values” of Chapter 2, “Prerequisites for Installing Xstore Office”).
• Jetty and Tomcat only - Copy the following files into the same directory as the
installer:
- Any cipher files you created by GenKeys (the .cip files created by GenKeys in
“Create Cipher Key Files”).

- xcenter-config.zip - Found in the xcenter directory extracted from the

- server.keystore - If you created your own certificates, this is the file created
in either “Certificate Authority-Signed Certificates: Oracle Retail Xstore Office”
or “Self-Signed Certificates: Oracle Retail Xstore Office” in Appendix B: “Public
Key Certificates”.
- xcenter-X.X.X.X.XXX-CCC-V.V.V.war - Found in the xcenter directory
extracted from the OracleRetailXstoreOffice_X_X_X_X_CCC_V_V_V.zip file. See
“Xstore Office Installation .zip File” for more information.
- xadmin-X.X.X.X.XXX-CCC-V.V.V.war - Found in the xcenter directory
where:
* X.X.X.X.XXX is the version and build number
* V.V.V is a customer release version
* CCC is the three-letter customer ID
Pre-Installation Configuration
38. Create the following directories for each organization hosted by the Xstore Office
server, where <ORGID> is the organization ID. The locations of these directories are
configurable; the locations below are default locations:
- Windows:
* c:\filetransfer\auto\org<ORGID>
* c:\fileuploads\org<ORGID>
* c:\poslog\org<ORGID>
- Linux:
* /filetransfer/auto/org<ORGID>
* /fileuploads/org<ORGID>
* /poslog/org<ORGID>
39. Open the file xcenter-config.zip in an archive browser (for example, 7-Zip).
This file is found in the xcenter directory extracted from the
40. Navigate into the directory xcenter-config.
41. Open the file xcenter.properties in a text editor (for example, Notepad or
emacs).
42. Enter the correct information for the following properties:
a. xcenter.org.id - Organization ID.
b. dtv.CustomerId - Three-letter customer code.
c. dtv.CustomerId.salt - Salt value.
d. dtv.config.path - Configuration path for queries:

* If you are using SQL Server, edit this property as follows to run SQL Server
customer-related queries (each property is all on one line):
dtv.config.path=:db/sql/mssql:cust:cust/loyalty:
cust/loyalty/award:order:locate:relate:version1:
MASTER/DEFAULT:dataloader:xcenter:xcenter/mssql:
xcenter/event_log:xcenter/xbr
e. *.connectionfactory - Verify the .connectionfactory line is appropriate for
the database platform:
* For Oracle (the property is all on one line):
dtv.datasource.connectionfactory=
oracle.jdbc.pool.OracleDataSource
* For Oracle PDB (the property is all on one line):
oracle.jdbc.pool.OracleDataSource
* For SQL Server (the property is all on one line):
com.microsoft.sqlserver.jdbc.SQLServerDataSource
f. Database URLs are a configured for each Xstore Office database:
Important: You must review and change the default URL

configuration set provided here.
Also, ensure all the user names and passwords are encrypted.
* If you are using WebLogic as your app server, use the following settings:
dtv.local.db.url=jndi:jdbc/Local
dtv.xadmin.db.url=jndi:jdbc/XcenterAdmin
dtv.xcrepl.db.url=jndi:jdbc/XcenterReplication
* If you are using Jetty or Tomcat as your app server, the URL configuration
depends upon the type of database on which you are running:
Oracle (each property is all on one line)
dtv.local.db.url=jdbc:oracle:thin:@localhost:1521:
<Xcenter_Database_SID>
dtv.xadmin.db.url=jdbc:oracle:thin:@localhost:1521:
<Xadmin_Database_SID>
dtv.xcrepl.db.url=jdbc:oracle:thin:@localhost:1521:
<Xcenter_Replication_Database_SID>
Oracle PDB (each property is all on one line)
dtv.local.db.url=jdbc:oracle:thin:@localhost:1521/
<Xcenter_Database_PDB>
dtv.xadmin.db.url=jdbc:oracle:thin:@localhost:1521/
<Xadmin_Database_PDB>

dtv.xcrepl.db.url=jdbc:oracle:thin:@localhost:1521/
<Xcenter_Replication_Database_PDB>
SQL Server (each property is all on one line)
dtv.local.db.url=jdbc:sqlserver://localhost;
databaseName=<Xcenter_Database_Name>;
sendStringParametersAsUnicode=true
dtv.xadmin.db.url=jdbc:sqlserver://localhost;
databaseName=<Xadmin_Database_Name>;
dtv.xcrepl.db.url=jdbc:sqlserver://localhost;
databaseName=<Xcenter_Replication_Database_Name>;
If you are using a non-default SQL Server instance, the URL will need to be
updated to include the ";instancename=<instance_name>" details. For
example (each property is all on one line):
dtv.local.db.url=jdbc:sqlserver://localhost;
instancename\=<SQLServerInstance>;
databaseName=<Xcenter_Database_Name>;
dtv.xadmin.db.url=jdbc:sqlserver://localhost;
databaseName=<Xadmin_Database_Name>;
dtv.xcrepl.db.url=jdbc:sqlserver://localhost;
databaseName=<Xcenter_Replication_Database_Name>;
g. Database user names and passwords:
Tip: Use the String Encrypter Utility to encrypt the strings for this
section. (See Appendix A: “String Encrypter Utility”).
* dtv.local.db.user - The Xcenter database user name (encrypted).

* dtv.local.db.password - The Xcenter database password (encrypted).
* dtv.xadmin.db.user - The Xadmin database user name (encrypted).
* dtv.xadmin.db.password - The Xadmin database password (encrypted).
* dtv.xcrepl.db.user - The Xcenter replication database user name
(encrypted).
* dtv.xcrepl.db.password - The Xcenter replication database password
(encrypted).
h. dtv.xadmin.support.criticalAlertEmails.enabled - Set the switch for critical alert
emails:
dtv.xadmin.support.criticalAlertEmails.enabled=true
i. dtv.xadmin.baseURL - Configure the following property for email links used in
Wave Approval email:

dtv.xadmin.baseURL=https://localhost:8443/xadmin/
j. Email Configuration - Configure the following properties for email alerts:
dtv.xadmin.smtp.host=localhost
dtv.xadmin.smtp.port=25
dtv.xadmin.smtp.auth=false
dtv.xadmin.smtp.user=
dtv.xadmin.smtp.password=
dtv.xadmin.smtp.sender=noreply@xadmin.com
k. For the web server, configure the URL, username, and password:
dtv.deployment.StagingHostBaseURL=https://staginghost/
dtv.deployment.StagingHostUsername=
Pj4+MAAAAADvHIxh8KlKpMb58080fuVH
dtv.deployment.StagingHostPassword=
Pj4+MAAAAACxzvu3yc0wTglnR9h+w5f6
l. Configure the replication properties. (Refer to Appendix G: “Replication” for
more information).
* Replication publishing to Xcenter - The re-sequencing publisher process
(including all related threads) can be individually enabled/disabled on each
instance of Xcenter.
cluster.processes.enabled=true
replication.publisher.resequencing_delay.seconds=10
replication.publisher.polling_interval.milliseconds=
3000
replication.publisher.threads_per_orgid=3
cluster.processes.enabled determines whether or not the server will
have replication publisher functionality enabled and whether clustering
processes will be enabled.
replication.publisher.resequencing_delay.seconds
determines the amount of time records remain at rest in the replication
queue before they are eligible for processing (to provide time for the records
arriving out-of-order to regain their initial ordering).
replication.publisher.polling_interval.milliseconds
determines how frequently the replication publisher threads will check for
new data in the queue when no data was encountered on the previous
check. When data was present during the prior check, this delay is not taken
into account.
replication.publisher.threads_per_orgid determines how many
replication publisher threads will be hosted, per organization ID, on this
server. This should generally be set to a value equal to the number of CPU
cores in the system hosting the instance.
m. Configure the file upload types. (Separate the valid values with commas).

deployment.FileType.JRE=zip
Note: JRE file extension, defaults to zip. Valid Values: zip, exe, etc.
deployment.FileType.DATA=mnt,rep,reo,dat
Note: Data update (for DataLoader), defaults to mnt, rep, reo, dat.
Valid Values: mnt, rep, reo, dat, etc.
deployment.FileType.CONFIG=
Note: Configuration update. Xadmin will generate a file container

with the proper file extension (usually jar or zip).
deployment.FileType.APPUPD=jar
Note: Application update (executable JAR). Defaults to jar. Valid

Values: jar, etc.
deployment.FileType.COMPRESSED_DATA=
Note: A zipped data update (for DataLoader). Xadmin will generate a

file container with the proper file extension (usually jar or zip).
deployment.FileType.CIP=cip
Note: Cipher file, defaults to cip.
deployment.FileType.DEBITBIN=debit.txt
Note: Debit BIN file. Defaults to debit.txt.
deployment.FileType.NEW=newExt
Note: A configurable file type. For example,

deployment.FileType.EPD=epd
deployment.FileType.ENVUPD=tar.gz
Note: This file upload type provides the ability to upload tarball files
(.tar.gz) as application updates to Xenvironment.
deployment.FileType.TRANSARMOR_BIN=tgx
Note: Transarmor BIN files. Defaults to tgx.

n. Configure character encoding if running a Unicode-based system (used for

many foreign language installations).
* Accept the default:
deployment.dataloader_file.character_encoding=UTF-8
Note: This configuration must match the Xstore Point of Service

"DataLoader" config named dataloader.characterEncoding
This config
(deployment.dataloader_file.character_encoding in
Xadmin) controls how DataLoader files are generated by Xadmin.
Xstore Point of Service must be configured the same so that it can
digest those DataLoader files properly.
Important: The poslog broadcasters are no longer configured in

xcenter.properties. Configuration is now done in the xcenter-
spring-beans.xml file (located in the same directory as
xcenter.properties). See ““Broadcaster Configuration” for more
information about configuring the broadcasters.
xcenter.properties Sample
xcenter.org.id=1
xcenter.rtl_location.id=0
xcenter.wkstn.id=0
dtv.CustomerId=XST
dtv.CustomerId.salt=DTV
dtv.config.path=:cust:cust/loyalty:cust/loyalty/award:purge:purge/
oracle:order:locate:relate:24x7:version1:MASTER/
DEFAULT:dataloader:xcenter:xcenter/event_log:xcenter/xbr
# JDBC driver/connection factory

dtv.datasource.connectionfactory=oracle.jdbc.pool.OracleDataSource
dtv.local.db.url=jdbc:oracle:thin:@localhost:1521:xcenter
# PDB dtv.local.db.url=jdbc:oracle:thin:@localhost:1521/xcenter
dtv.local.db.user=Pj4+MAAAAABEJKQVOAJI+5sGlAQ30XIQ
dtv.local.db.password=Pj4+MAAAAABEJKQVOAJI+5sGlAQ30XIQ
dtv.xadmin.db.url=jdbc:oracle:thin:@localhost:1521:xcenter
# PDB dtv.xadmin.db.url=jdbc:oracle:thin:@localhost:1521/xcenter
dtv.xadmin.db.user=Pj4+MAAAAABEJKQVOAJI+5sGlAQ30XIQ
dtv.xadmin.db.password=Pj4+MAAAAABEJKQVOAJI+5sGlAQ30XIQ
dtv.xcrepl.db.url=jdbc:oracle:thin:@localhost:1521:xcenter

# PDB dtv.xcrepl.db.url=jdbc:oracle:thin:@localhost:1521/xcenter
dtv.xcrepl.db.user=Pj4+MAAAAABEJKQVOAJI+5sGlAQ30XIQ
dtv.xcrepl.db.password=Pj4+MAAAAABEJKQVOAJI+5sGlAQ30XIQ
dtv.xadmin.baseURL=https://localhost:8443/xadmin/
dtv.xadmin.smtp.host=localhost
dtv.xadmin.smtp.port=25
dtv.xadmin.smtp.auth=false
dtv.xadmin.smtp.user=
dtv.xadmin.smtp.password=
dtv.xadmin.smtp.sender=noreply@xadmin.com
dtv.xadmin.smtp.starttls=true
dtv.deployment.StagingHostBaseURL=https://staginghost/
dtv.deployment.StagingHostUsername=Pj4+MAAAAADvHIxh8KlKpMb58080fuVH
dtv.deployment.StagingHostPassword=Pj4+MAAAAACxzvu3yc0wTglnR9h+w5f6
dtv.pospoll.workingDir=file:/pospoll
cloud.sftp.host=localhost
cloud.sftp.username=Pj4+MP3///9WvtrRwjWZCQRQ+NUzDeqj
cloud.sftp.password=Pj4+MP3///9WvtrRwjWZCQRQ+NUzDeqj
cloud.sftp.locate.workingDir=locate
cloud.sftp.relate.workingDir=relate
cloud.sftp.nfe.workingDir=nfe
cloud.http.locate.endpoint=https://HOST:PORT/Locate/faws/FileService/
OROB-IMPORTS
cloud.http.locate.timeout.connect=30
cloud.http.locate.timeout.read=30
cloud.http.locate.compress=true
cloud.http.locate.username=Pj4+MAAAAADvHIxh8KlKpMb58080fuVH
cloud.http.locate.password=Pj4+MAAAAACxzvu3yc0wTglnR9h+w5f6
#####-----------------------------------------------------------------
##### cluster processes enabled
#####
##### This configuration is a "master switch" that can enable/disable
##### ALL clustering-related processes, including replication,
broadcasting,
##### and the SFTP file-transfer processes (loading promotions from
Customer
##### Engagement, order broker updates, etc). When disabled, this
Xcenter
##### node really ends up just running the various DTX query servlets
used
##### by Xstore.
cluster.processes.enabled=true
#####-----------------------------------------------------------------
##### cluster server number
#####

##### THIS SETTING IS REQUIRED EVEN IF NOT RUNNING CLUSTERED INSTANCES.

#####
##### Each server instance must be configured with a UNIQUE server
##### number.
#####
##### In Xcenter, cluster.server-number is used by Xcenter's
clustering
##### framework to uniquely identify each cluster node.
#####
##### Also noteworthy for Xcenter: this configuration is not given a
##### default value; if left unconfigured, Xcenter will fail to
##### start up until a server number is provided.
#####
##### This number must be an integer from 1..{max int}.
#####-----------------------------------------------------------------
cluster.server-number=
#####-----------------------------------------------------------------
##### Replication publishing to Xcenter
#####-----------------------------------------------------------------
replication.publisher.resequencing_delay.seconds=10
replication.publisher.polling_interval.milliseconds=3000
replication.publisher.threads_per_orgid=3
## MS SQL Server EXAMPLES ##
# DB DRIVER
#dtv.datasource.connectionfactory=com.microsoft.sqlserver.jdbc.SQLServ
erDataSource
# DB URL
#dtv.local.db.url=jdbc:sqlserver://localhost;databaseName=xcenter_test
#dtv.xadmin.db.url=jdbc:sqlserver://localhost;databaseName=xadmin_test
#dtv.xcrepl.db.url=jdbc:sqlserver://
localhost;databaseName=xcenter_replication
# DB URL (Unicode)
#dtv.local.db.url=jdbc:sqlserver://
localhost;databaseName=xcenter_test;sendStringParametersAsUnicode=true
#dtv.xadmin.db.url=jdbc:sqlserver://
localhost;databaseName=xadmin_test;sendStringParametersAsUnicode=true
#dtv.xcrepl.db.url=jdbc:sqlserver://
localhost;databaseName=xcenter_replication;sendStringParametersAsUnico
de=true
## JNDI EXAMPLES ##
# DB DRIVER
# Required for detection of SQL Dialect. Configured as per prior
examples.
# DB URL

# Note: These JNDI datasources must be configured on your application

server prior to use.
# The format of the url is jndi:<jndi_path> (ie. Xcenter path
jndi:jdbc/Local should be used
# with a database defined at jdbc/Local).
#dtv.local.db.url=jndi:jdbc/Local
#dtv.xadmin.db.url=jndi:jdbc/XcenterAdmin
#dtv.xcrepl.db.url=jndi:jdbc/XcenterReplication
deployment.FileType.JRE=zip
deployment.FileType.DATA=mnt,rep,reo,dat
deployment.FileType.CONFIG=
deployment.FileType.APPUPD=jar,sig
deployment.FileType.COMPRESSED_DATA=
deployment.FileType.CIP=cip
deployment.FileType.DEBITBIN=debit.txt
deployment.FileType.NEW=newExt
deployment.FileType.ENVUPD=tar.gz
deployment.FileType.TRANSARMOR_BIN=tgx
deployment.dataloader_file.character_encoding=UTF-8
# This entry defines which serenade response field contains Xstore's

item Id value
# valid values are "item_id", "retail_ref_number", "sku", and
"short_sku_number"
# if this entry is missing or is not one of the valid values, it
defaults to "item_id"
serenade.item.field=item_id
# IDCS
#### Populated by CHEF ###
idp.connectionURL=https://localhost:443
idcs.tenant=
idcs.hostname=
### Retrieved from OPAM ###

idcs.xcenter.client.id=
idcs.xcenter.client.secret=
signing.jwk.file=
idcs.xcenter.redirect.uri=
idcs.xcenter.response.type=
idcs.xcenter.authorization.scope=
43. Save the file and then answer Yes when prompted to save your changes in the
archive.
44. Configure the broadcasters in the xcenter-spring-beans.xml file (located
in the same directory as xcenter.properties), then Save the file. See

“Broadcaster Configuration” in Appendix F: “Xstore Office Broadcaster System” for

instructions.
Note: The poslog broadcasters are no longer configured in

xcenter.properties.
45. Open the file the xadmin-log4j2.xml file in the directory xcenter-config with
the xcenter-config.zip file.
This file can be found in the xcenter directory extracted from the
46. Change the following lines as necessary:
- If using WebLogic:
<Properties>
<Property name="log.dir.name">${sys:user.dir}</Property>


</Properties>
- If using Jetty:
<Properties>

<Property name="log.dir.name">${sys:jetty.logs}</
Property>

</Properties>
- If using Tomcat:
<Properties>


<Property name="log.dir.name">${sys:catalina.home}/
logs</Property>
</Properties>
archive.
48. Open the file xcenter-log4j2.xml in the directory xcenter-config in the file
xcenter-config.zip

This file can be found in the xcenter directory extracted from the
49. Change the following configuration lines as needed:
- If using WebLogic:
<Property name="log.dir.name">${sys:user.dir}</Property>


- If using Jetty:

<Property name="log.dir.name">${sys:jetty.logs}</Property>

- If using Tomcat:


<Property name="log.dir.name">${sys:catalina.home}/logs</
Property>
archive.
51. Perform the appropriate installation procedure:
- If installing WebLogic, continue with “Install WebLogic”.
- If Installing Jetty, continue with “Install Jetty”.
- If installing Apache Tomcat, skip to “Install Apache Tomcat”.
Install WebLogic
For information and procedures about installing Oracle WebLogic Server, see the
Installation Guide for Oracle WebLogic Server. This installation must include:
• A domain created using the Basic WebLogic Server Domain Template.
• A user that can be used to connect to the management console and configure the
server.
• The Xcenter, Xadmin, and Xcenter Replication databases have been created on the
database server. and the appropriate scripts have been run against them.
To complete the installation of WebLogic, do the following:
• Enable Only Strong Cipher Suites
• Enable Secure Cookies

Prepare WebLogic Files

52. Create a directory for the Xcenter keystore file (for example, C:\xcenter-
keystore).
53. Copy the Xcenter keystore file to the keystore directory (for example,
server.keystore from “Certificate Authority-Signed Certificates: Oracle Retail
Xstore Office” or “Self-Signed Certificates: Oracle Retail Xstore Office” in
Appendix B: “Public Key Certificates”).
54. Create the folder for Xstore Office configuration files:
- Windows:
c:\xcenter-config
- Linux:
/usr/local/xcenter-config
55. Extract the xcenter-config.zip file into the Xstore Office configuration files
directory (created in step 54).
The xcenter-config.zip file is found in the xcenter directory extracted from
the OracleRetailXstoreOffice_X_X_X_X_CCC_V_V_V.zip file. See “Xstore Office
Enable Only Strong Cipher Suites

56. Update config.xml with the base cipher suites in the NetSecurityConfig.xml
file found in the dtv/res/config directory within the config.jar files.
Note: The config.xml file is found in the config folder in the

Domain Home folder for your WebLogic installation. See the
WebLogic documentation for more information.
To find the cipher suites in the NetSecurityConfig.xml file:

a. In an archive editor, open the xcenter-X.X.X.X.X-CCC-V.V.V.war file.
b. Navigate to the WEB-INF/lib folder within the archive.
c. Open the config.jar archive in an archive editor.
d. Navigate to the dtv/res/config folder within the config.jar archive.
e. Open the NetSecurityConfig.xml file. Go to the <ContextSetting
name=”*”> element. Obtain the list of ciphers used in the <ciphersuite>
tags.
f. Then enter the cipher suites into the ssl block of the config.xml, by using
the following format:
Example: config.xml <ssl>
<ssl>
<name>examplesServer</name>
<enabled>true</enabled>
<ciphersuite>example_ciphersuite_1</ciphersuite>
<ciphersuite>example_ciphersuite_2</ciphersuite>
...

<listen-port>7002</listen-port>
...
</ssl>
Enable Secure Cookies

57. Add the following configurations in the <weblogic-web-app> element in the
weblogic.xml files:
Note: There are two weblogic.xml files. In the home directory for
WebLogic:
• webapps/xadmin/WEB-INF/weblogic.xml
• webapps/xcenter/WEB-INF/weblogic.xml
<session-descriptor>
<cookie-http-only>true</cookie-http-only>
<cookie-secure>true</cookie-secure>
</session-descriptor>
Configure WebLogic Server

58. Connect to the WebLogic Server management console using a web browser.
59. Log into the WebLogic Server management console.
60. Select the server in the Domain Structure screen.
61. Click Lock & Edit.
62. Click the General tab.
63. Configure the General settings:
- SSL Listen Port Enabled - Select this option.
- SSL Listen Port - Enter 8443.
64. Click Save.
65. Click the Keystores tab.
66. Configure the Keystores settings:
- Keystores - Select Custom Identity and Custom Trust.
- Custom Identity Keystore - Enter the path and filename of the Xcenter keystore
file (see steps 52-53).
- Custom Identity Keystore Type - Select JKS.
- Custom Identity Keystore Passphrase - Enter the password for the Xcenter
keystore file (see steps 52-53).
- Confirm Custom Identity Keystore Passphrase - Re-enter the password for the
Xcenter keystore file (see steps 52-53).
- Custom Trust Keystore - Set to the correct value for your operating system:
* Windows:
c:\xcenter-config\res\ssl\.truststore

* Linux:
/usr/local/xcenter-config/res/ssl/.truststore
- Custom Trust Keystore Type - Select JKS.
- Custom Trust Keystore Passphrase - Enter the password for the for the
WebLogic truststore file.
- Confirm Custom Trust Keystore Passphrase - Re-enter the password for the for
the WebLogic truststore file.
67. Click Save.
68. Click the SSL tab.
69. Configure the security key settings:
- Identity and Trust Locations - Select Keystores.
- Private Key Locaiton - Select from Custom Identity Keystore.
- Private Key Alias - Enter the Xcenter key alias in the Xcenter keystore file.
- Private Key Passphrase - Enter the password for the Xcenter TLS security key.
- Confirm Private Key Passphrase - Re-enter the password for the Xcenter TLS
security key.
- Certificate Location - Select from Custom Identity Keystore.
- Trusted Certificate Authorities - Select from Custom Trust Keystore.
70. Click Save.
71. Click Activate Changes.
72. Click Data Sources in the Domain Structure screen.
73. Click the Lock & Edit button.
Create the Xcenter Datasource

74. Click the New button to create the first datasource.
75. Click Generic Data Source.
76. Configure the datasource:
- Name - Enter xcenter.
- JNDI Name - Enter jdbc/Local.
- Database Type - Select the type of database for your database server.
77. Click Next.
78. Click Next.
79. Enter the connection properties:
- Database Name - Name of the Xcenter database.
- Host Name - Hostname of the Xcenter database server.
- Port - Port for the Xcenter database server.
- Database User Name - Login name for the Xcenter database (for example, pos).
- Password - Password for the Xcenter database user.
- Confirm Password - Re-enter the password for the Xcenter database user.

80. Click Next.

81. Test the database connection.
- If the test is successful, continue with the next step.
- If the test is unsuccessful, go back and make any necessary corrections to the
configuration information, or troubleshoot the connection to the database server.
82. Click Next.
83. Select the WebLogic Server that will be using the datasource.
84. Click Finish.
Create the Xadmin Datasource

- Name - Enter xadmin.
- JNDI Name - Enter jdbc/XcenterAdmin.
88. Click Next.
89. If you are using an Oracle database:
a. Click Oracle's Driver (Thin) for Service connections; Versions Any.
b. Click Next.
90. Click Next.
91. Enter the connection properties:
92. Click Next.
93. Test the database connection.
94. Click Next.
95. Select the WebLogic Server that will be using the datasource.
96. Click Finish.
Create the Xcenter Replication Datasource



- Name - Enter xcenterreplication.
- JNDI Name - Enter jdbc/XcenterReplication.
100.Click Next.
101.If you are using an Oracle database:
a. Click Oracle's Driver (Thin) for Service connections; Versions Any.
b. Click Next.
102.Click Next.
103.Enter the connection properties:
104.Click Next.
105.Test the database connection.
106.Click Next.
107.Select the WebLogic Server that will be using the datasource.
108.Click Finish.
Configure Datasources
109.Click the Connection Pool tab for the xcenter datasource.
110.Click the Advanced link.
111.Configure the Connection Pool settings for the xcenter datasource:
- Maximum Capacity - Enter 75.
- Minimum Capacity - Enter 5.
- Statement Cache Size - Enter 64.
- Wrap Data Types - Unselect this option.
112.Click Save.
113.Click the Connection Pool tab for the xadmin datasource.
114.Configure the Connection Pool settings for the xadmin datasource:


116.Click Save.
117.Click the Connection Pool tab for the xcenterreeplication datasource.
118.Configure the Connection Pool settings for the xcenterreeplication datasource:
120.Click Save.
121.Click the domain structure.
122.Click Security Realms.
123.Click Lock & Edit.
124.Click myrealm.
125.Click the Users tab in the Users and Groups area.
126.Click New.
127.Configure the Users settings:
- Name - Enter the user name Xstore Point of Service registers use to log into
Xstore Office.
- Password - Enter the password Xstore Point of Service registers use to log into
Xstore Office.
- Confirm - Re-enter the password Xstore Point of Service registers use to log into
Xstore Office.
128.Click OK.
129.Click the Groups tab in the Users and Groups area.
130.Click New.
131.Configure the Groups settings:
- Name - Enter XcenterUsers.
132.Click OK.
133.Click the newly created user (see steps 124-128) in the Users and Groups area.
134.Click the Groups tab.
135.Click the XcenterUsers group in the Available: list.
136.Click the > link.
137.Click Save.

Edit Batch File or Shell Script

138.In a text editor (for example, Notepad or emacs) open the batch file or shell script
that starts your managed server.
139.Add the following lines to the start of the script:
Linux
EXPORT JAVA_VENDOR=Oracle
EXPORT JAVA_VM=-server
EXPORT USER_MEM_ARGS=-Xms4096m -Xmx4096m
-XX:MaxMetaspaceSize=256m
-XX:+UseG1GC -XX:+ParallelRefProcEnabled
EXPORT JAVA_OPTIONS=-Dweblogic.wsee.StateCleanInterval=6000
-Dweblogic.security.SSL.minimumProtocolVersion=TLSv1.2
-Djava.awt.headless=true
-Dorg.eclipse.persistence.moxy.annotation.xml-value-
extension=true
Note: For the USER_MEM_ARGS variable, the setting -Xms4096m sets

the minimum heap size to 4096 MB and the setting -Xmx4096m sets
the maximum heap size to 4096 MB. These values may be changed
depending upon the amount of RAM in your system.
Windows
SET JAVA_VENDOR=Oracle
SET JAVA_VM=-server
SET USER_MEM_ARGS=-Xms4096m -Xmx4096m -
XX:MaxMetaspaceSize=256m
-XX:+UseG1GC -XX:+ParallelRefProcEnabled
SET JAVA_OPTIONS=-Dweblogic.wsee.StateCleanInterval=6000
extension=true
Note: For the USER_MEM_ARGS variable, the setting -Xms4096m sets

the minimum heap size to 4096 MB and the setting -Xmx4096m sets
the maximum heap size to 4096 MB. These values may be changed
depending upon the amount of RAM in your system.
140.If you are running Xstore Office using WebLogic, and using an Apache web server,
add the following configuration to the JAVA_OPTIONS variable setting:
-Dhttp.keepAliveCache.socketHealthCheckTimeout=1
The setting would be the following:
Linux
EXPORT JAVA_OPTIONS=-Dweblogic.wsee.StateCleanInterval=6000

extension=true -Dhttp.keepAliveCache.socketHealthCheckTimeout=1
Windows
SET JAVA_OPTIONS=-Dweblogic.wsee.StateCleanInterval=6000
extension=true -Dhttp.keepAliveCache.socketHealthCheckTimeout=1
141.Install the Xcenter and Xadmin .war files in the Domain Structure screen.
Note: See the WebLogic documentation for more information.
142.Confirm that WebLogic is running by logging into it with a web browser. The format
for the URL is:
https://<server_hostname>:<server_port>/xcenter/dtx/
GetById?NAME=Party&ID=<organization_id>::0
Note: The GetById?NAME section of the URL shown above is case-

sensitive. Be sure to enter it exactly as shown above.
FOR EXAMPLE, IF:

• server_hostname: xstore.office.biz
• server_port: 8443
• organization_id: 1000
THEN THE URL=
https://xstore.office.biz:8443/xcenter/dtx/
GetById?NAME=Party&ID=1000::0
143.Confirm that Xadmin is running by logging into it with a web browser. The format
for the URL is:
https://<server_hostname>:<server_port>/xadmin
FOR EXAMPLE, IF:
THEN THE URL=
https://xstore.office.biz:8443/xadmin
144.If you are installing Xcenter DataLoader, continue with “Install Xstore Office
DataLoader”.
145.If you are installing Xcenter POSLog Generator, continue with “Install Xstore Office
POS Log Generator”.

Install Jetty
...continued from step 51
Important: Only 64-bit Windows and Linux systems are supported.
146.In a file manager, navigate in the <root_directory> extracted from the Xstore
Office Installation .zip File.
147.Copy the Xcenter keystore file to the jetty_installer directory (for example,
server.keystore from “Certificate Authority-Signed Certificates: Oracle Retail
Xstore Office” or “Self-Signed Certificates: Oracle Retail Xstore Office” in
Appendix B: “Public Key Certificates”).
148.Launch the Jetty Installer. jetty-x.x.x-installer.jar.
149.Specify the directory where Jetty will be installed.
Tip: Oracle recommends you keep the default value. Using the
default installation directory specified here makes it easier to locate the
directory if troubleshooting is needed.
150.Click Next.
151.Set up the Jetty TLS Configuration:
a. Java Keystore - If the server.keystore file is detected in the installation
folder, this field is completed by default. If you did not place it in the installation
folder as instructed in step 147, use the browse button to locate the
server.keystore file.
b. Keystore Password - Type the password chosen when the TLS certificates were
created, then confirm the password in the field below.
c. SSL Key Alias - Type the alias chosen when the TLS certificates were created.
152.Click Next.
153.Specify the memory values for the Jetty service.
Important: See “Jetty & Tomcat Memory Values” in Chapter 2,

“Prerequisites for Installing Xstore Office” for generalized memory
value guidelines.
a. Xms Value - Initial heap size

b. Xmx Value - Maximum heap size
c. MaxPermSize Value - Maximum value for the PermGen space
Note: The system checks the maximum heap size (Xmx Value)
specified here.
154.Click Next.
155.Configure the ports and threads:
a. Jetty Server Port Number - TCP/IP port used by the Jetty server.

b. Acceptor Thread Count - Number of threads dedicated to accepting incoming

connections.
c. Maximum Server Thread Count - Maximum number of threads available to the
Jetty instance for processing requests.
156.Click Next.
157.Enter the name of the Windows service that runs Jetty (Jetty Service Name).
158.Click Next.
159.Enter the username and password that Xstore Point of Service will use to access
Xstore Office:
a. Username - Username to be used by Xstore Point of Service to log into Xstore
Office.
b. Password - Password to be used to Xstore Point of Service to log into Xstore
Office.
c. Confirm - Same password as above.
160.Click Next.
- If the WAR files are detected in the installation directory, you will see the
message:
One or more WAR files was detected in the same directory as this installer, and
will be copied to C:\jetty-X.X.X\webapps during the installation process.
- If the WAR files are not detected in the installation directory, copy the WAR files
to the same directory as the installer, then select the Back button, then the Next
button (see Prerequisites for Application Server Installation for more
information).
161.Click Next.
- If the Configuration .zip file is detected in the installation directory you will
see the message:
An xcenter-config.zip was detected in the same directory as this installer.
It will be automatically extracted to c:\ during this installation.
Note: If a folder named xcenter-config already exists in c:\, you

will be prompted that the existing folder will be renamed during the
install. Click Ok to close the message box.
- If the xcenter-config.zip file is not detected in the installation directory,

copy the file to the same directory as the installer, then select the Back button,
then the Next button (see Prerequisites for Application Server Installation for
more information).
162.Click Next.
- If the cipher files are detected in the installation directory you will see the
message:
Cipher files (*.cip) have been detected in the same directory as this installer and
will be automatically copied to the proper directory -
c:\xcenter-config\res\keys during the installation process.
- If no cipher files are detected in the installation directory, copy the cipher files to
the same directory as the installer, then select the Back button, then the Next


information).
163.Click Next.
164.Select the Start the Jetty Service? check box if the Jetty service should start
automatically at the end of this installation procedure (recommended).
The setup steps for Jetty are complete.
165.Click Next.
166.Click Next to begin installing Jetty.
167.The Installing screen shows the installation progress as Jetty is installed. This
process may take a few minutes.
168.Click Finish when installation is complete.
169.Confirm that Jetty is running by logging into it with a web browser. The format for
the URL is:

sensitive. Be sure to enter it exactly as shown above.
FOR EXAMPLE, IF:

THEN THE URL=
for the URL is:
FOR EXAMPLE, IF:
THEN THE URL=
171.If you are installing Xcenter DataLoader, continue with “Install Xstore Office
DataLoader”.
172.If you are installing Xcenter POSLog Generator, continue with “Install Xstore Office
POS Log Generator”.

Install Apache Tomcat

...continued from step 51
173.Launch the Tomcat Installer tomcat-x.x.x-installer.jar.
Note: During the installation, if you need to change the information

entered in a previous screen, click the “Back” button to return to a
prior screen.
If, at any point, you must stop the installation, click the “Cancel”
button. You will be prompted to confirm the cancellation. Click the
“Yes” button to cancel the installation and exit the GUI.
Important: Only 64-bit Windows and Linux systems are supported.
174.At the Welcome screen, click Next to begin the install.

175.If necessary, update the directory where Tomcat will be installed.
Tip: Oracle recommends you keep the default value. Using the
default installation directory specified here makes it easier to locate the
directory if troubleshooting is needed.
176.Click Next.
177.Enter the Tomcat SSL Configuration information:
a. Java Keystore - If the server.keystore file is detected in the installation
folder, this field is completed by default. If you did not place it in the installation
folder as instructed in step • on page 5, use the browse button to locate the
server.keystore file.
b. Keystore Password - The password chosen when the TLS certificates were
created, then confirm the password in the field below.
c. SSL Key Alias - The alias chosen when the TLS certificates were created.
d. Salt Value - Enter the encryption salt value to be used.
Note: The system checks the amount of memory installed on the

machine.
178.Click Next.
179.Specify the memory values for the Tomcat service.
Important: See “Jetty & Tomcat Memory Values” in Chapter 2,

“Prerequisites for Installing Xstore Office” for generalized memory
value guidelines.
a. Xms Value - Initial heap size

b. Xmx Value - Maximum heap size

c. MaxPermSize Value - Maximum value for the PermGen space

180.Click Next.
181.Configure the ports and threads.
a. Tomcat Server Port Number - The TCP/IP port used by the Tomcat server.
b. Tomcat Server Shutdown Port Number - The TCP/IP port used to shut down
the Tomcat server.
c. Acceptor Thread Count - The number of threads dedicated to accepting
incoming connections.
d. Maximum Server Thread Count - The maximum number of threads available to
the Tomcat instance for processing requests.
182.Click Next.
183.Enter the Tomcat Service Name to be used by Windows.
184.Click Next.
185.Enter the credentials to be used to access Tomcat’s administration and management
consoles.
a. Username - Enter the username that will be used to access the Tomcat
Administration and Management consoles.
b. Password - Enter the password that will be used to access the Tomcat
Administration and Management consoles.
c. Confirm - Confirm the password entered above.
186.Click Next.
187.Enter the credentials Xstore Point of Service will use to access Xstore Office. This is
the App Server user name and App Server password.
a. Username - Enter the username that will be used by Xstore Point of Service to
access Xstore Office.
b. Password - Enter the password that will be used by Xstore Point of Service to
access Xstore Office.
c. Confirm - Confirm the password entered above.
188.Click Next.
- If the WAR files are detected in the installation directory, you will see the
message:
One or more WAR files was detected in the same directory as this installer, and
will be copied to C:\tomcat-X.X.X\webapps during the installation process.
- If the WAR files are not detected in the installation directory, copy the WAR files
to the same directory as the installer, then select the Back button, then the Next
information).
189.Click Next.
- If the Configuration .zip file is detected in the installation directory you will
see the message:

An xcenter-config.zip was detectedin the same directory as this installer. It will

be automatically extracted to c:\ during this installation.
Note: If a folder named xcenter-config already exists in c:\, you

will be prompted that the existing folder will be renamed during the
install. Click Ok to close the message box.
- If the xcenter-config.zip file is not detected in the installation directory,

copy the file to the same directory as the installer, then select the Back button,
then the Next button (see Prerequisites for Application Server Installation for
more information).
190.Click Next.
- If the cipher files are detected in the installation directory you will see the
message:
Cipher files (*.cip) have been detected in the same directory as this installer and
will be automatically copied to the proper directory -
c:\xcenter-config\res\keys during the installation process.
- If no cipher files are detected in the installation directory, copy the cipher files to
the same directory as the installer, then select the Back button, then the Next
information).
191.Select the Start the Tomcat Service? check box if the Tomcat service should start
automatically at the end of this installation procedure (recommended).
The setup steps for Tomcat are complete.
192.Click Next.
193.Click Next to begin installing Tomcat.
194.The Installing screen shows the installation progress as Tomcat is installed. This
process may take a few minutes.
195.Click Finish when installation is complete.
196.Confirm that Tomcat is running by logging into it with a web browser. The format
for the URL is:

sensitive. Be sure to enter it as shown above.
FOR EXAMPLE, IF:

THEN THE URL=

Install Xstore Office DataLoader
for the URL is:
FOR EXAMPLE, IF:
THEN THE URL=
198.If you are installing Xstore Office DataLoader, continue with “Install Xstore Office
DataLoader”.
199.If you are installing Xstore Office POSLog Generator, continue with “Install Xstore
Office POS Log Generator”.
Loading Profil Group/Element Configurations

To load the appropriate profile group/element configurations when accessing the
Configurator in Xstore Office, add the following configuration to the JAVA_OPTIONS
variable settings in startWebLogic.cmd on Windows or startWebLogic.sh on
Linux:
extension=true
Install Xstore Office DataLoader

Perform the following steps if you are installing Dataloader. If you are not installing
Xstore Office DataLoader, continue with “Install Xstore Office POS Log Generator”.
200.Verify a JRE is present in c:\jre (Windows) or /opt/jre (Linux).
201.Copy the dataloader directory to a temporary location from the directory
202.Open a command prompt.
203.Navigate to the temporary dataloader directory in the command prompt.
204.Enter the following command to launch the Xstore Office DataLoader Installer in
GUI Mode:
c:\jre\bin\java -jar xstore-B.B.B.B-V.V.V-CCC-dataloader-
install.jar GUI
GUI Mode Installation

Perform the following steps to customize settings for the installation using GUI Mode.
205.Click Next in the welcome screen.
206.Select an installation directory for the DataLoader.
207.Click Next.
208.If you are prompted to create the directory, click Yes to create the directory

Install Xstore Office POS Log Generator
209.Enter the DataLoaderConfig.xml Path where the DataLoaderConfig.xml file

will be located.
210.Click Next.
211.Enter the DataLoader Settings.
a. Customer ID Salt - Salt value for the encrypted values.
b. Organization Id - ID of the organization.
c. Dataloader File Encoding - Character encoding used in the files.
212.Click Next.
Tip: Oracle recommends you keep the default values specified here
unless you are advised otherwise.
213.Configure Xcenter database connectivity.

- Xcenter Host Name/IP - Host name or IP address of the Xcenter database server.
- Xcenter Database Name - Name of the Xcenter database.
- Database Username - Encrypted database username.
- Database Password - Encrypted database password.
Note: To encrypt values, see Appendix A: “String Encrypter Utility”.
214.Click Next.
215.Click Install Xcenter DataLoader to begin the installation.
216.Click OK, the Exit when the installation is complete.
217.Run DataLoader to verify it runs as expected.
To Load Xadmin User Records via DataLoader (Optional)

The DataLoader install provided in the InstallX package can be used to load Xadmin
users. Perform the following steps if you want to use this functionality.
218.When installing the DataLoader using InstallX, provide the details for an Xadmin
database rather than the details for an Xcenter database.
219.After installing the DataLoader, comment out or remove the following section from
the log4j.xml file (found in config\dataloader\log4j.xml in the install
folder once it is installed).
<DtxAppender name="EVENT.dtx.critical"
guaranteedDelivery="true" />
220.If you are installing Xstore Office POSLog Generator, continue with “Install Xstore
Office POS Log Generator”.
If you are not installing Xstore Office POS Log Generator, the installation is
complete.
Install Xstore Office POS Log Generator

If you are installing Xstore Office POS Log Generator, perform the following steps. If you
are not installing Xstore Office POS Log Generator, the installation is complete.

Retrieve Files through SFTP
221.Verify a JRE is present in c:\jre (Windows) or /opt/jre (Linux).

222.Copy the posloggenerator directory extracted from the
224.Navigate to the temporary posloggenerator directory in the command prompt.
225.Enter the following command to launch the POSLogGenerator Installer in GUI
Mode:
c:\jre\bin\java -jar xstore-B.B.B.B-V.V.V-CCC-
posloggenerator.jar GUI

Perform the following steps to customize settings for the installation using GUI Mode.
226.Click Next in the welcome screen.
227.Select an installation directory for the POS Log Generator.
228.Click Next.
229.If you are prompted to create the directory, click Yes to create the directory.
230.Enter the Configuration Path information:
a. Oraganization Id - ID for the organization.
b. Customer ID Salt - Salt value.
c. Config Path - Directory where configurations will be stored (in the installation
directory configured in step 227).
231.Click Next.
232.Configure Xcenter data source connectivity, then click Next.
- Xcenter Host Name/IP - Host name or IP address of the Xcenter database server.
- Xcenter Database Name - Name of the Xcenter database.
- Database Username - Encrypted username used to connect to the database (See
Appendix A: “String Encrypter Utility”).
- Database Password - Encrypted password used to connect to the database (See
Appendix A: “String Encrypter Utility”).
233.Click Install Xcenter POSLogGenerator to begin the installation.
234.Once the process has completed, click OK to close the message box, then click Exit to
exit the InstallX Xcenter PosLogGenerator Installer.
235.Place a copy of the cipher files (.cip) in xstore-poslog/res/keys.

Xstore Office can be configured to routinely retrieve files from an SFTP server (for
example, Oracle Retail Customer Engagement Cloud Service). To configure this feature:
1. Open the file xcenter-spring-beans.xml in the xcenter-config directory in
a text editor.
2. Locate the section <task:scheduled-tasks>.

3. Add the following line to the <task:scheduled-tasks> section:


4. Locate the section <beans profile="xcenter">.
5. Add the following line to the <beans profile="xcenter"> section:
<bean id="relateFilePollSftpTask"
class="com.micros_retail.xcenter.sftp.RelateFilePollTask"
init-method="init" />
6. Save the xcenter-spring-beans.xml file.
7. Stop and restart Xstore Office.
SFTP file retrieval is enabled.

4
Prerequisites for Installing Xstore Point of
Service
Before installing any components of the Xstore Point of Service, it is necessary to prepare
the system on which the software will be installed.
System Requirements
Note: Oracle Retail assumes that the retailer has applied all required
fixes for supported compatible technologies.
Hardware Requirements
The minimum hardware requirements for a system running Xstore Point of Service
depend upon whether the system is a Lead Register or a Non-Lead Register.
Lead Register
Following is a list of the minimum processor and memory requirements needed to
provide the best operating environment in the store to run Xstore Point of Service,
Xenvironment, and DataLoader.
Lead register requirements also apply to systems that will be required to perform as a
Lead in disaster recovery situations.
Processor: Intel Core i5-5350U dual-core processor >= 1.8GHz or equivalent
Memory: 8GB
Non-Lead Register
Following is a list of the minimum processor and memory requirements needed to
provide the best operating environment in the store to run Xstore Point of Service,
Xenvironment, and DataLoader.
Processor: Intel Celeron 3765U dual-core processor >= 1.9GHz or equivalent
Memory: 4GB
Backup and Recovery

The retailer is responsible for ensuring that there is a backup and recovery system for all
customer and employee personal data.
The backup and recovery system must meet the following requirements:
• Secure backup and recovery must be available in a timely manner.
Prerequisites for Installing Xstore Point of Service 4-1

System Requirements
• Encryption of all backups (including removable media or replication data).

• Capability for shopper bulk data export options.
Geolocation and Device Identifiers

It is the responsibility of the retailer to ensure that they do not record any tracking
information for either customers or employees through their systems or devices, or
through any other software on their systems or devices.
Xstore Point of Service does not interact directly with shoppers and does not record any
tracking information, such geolocation or other device identifier information, for a
shopper from any other applications.
Xstore Point of Service does not record geolocation or other device identifier information
for an employee, because the devices are owned by the retailer. Xstore Point of Service is
not intended to be used on employee-owned devices and is not supported on them.
Supported Software
Xstore Point of Service is supported on the following software:
Table 4-1: Xstore Point of Service Supported Software
Software Type Product
Operating System Oracle Enterprise Linux 7
Windows POSReady 2009
Windows POSReady 7
Windows 7
Windows 10
Windows 10 IOT Enterprise LTSB 2016 (1607)

Note: Oracle Retail assumes that the retailer has ensured its
Operating System has been patched with all applicable
Windows updates.
Database Oracle Database 12c
SQL Server 2012 SP1
SQL Server 2014 SP1
SQL Server 2016
Table 4-2: Xstore Point of Service Supported Oracle Products
Oracle Product Version
Oracle Retail Merchandising System (RMS) 16.0
Oracle Retail Sales Audit (ReSA) 16.0
Oracle Retail Price Management System (RPM) 16.0
Oracle Retail Store Inventory Management (SIM) 16.0

System Requirements
Table 4-2: (continued)Xstore Point of Service Supported Oracle Products
Oracle Product Version
Oracle Retail Customer Engagement Cloud Service 17.0
Oracle Retail Order Broker Cloud Service 16.0
Oracle Retail Order Management System Cloud Service 17.0
Oracle Commerce Retail Extension Module 16.0
Oracle Hospitality OPERA Cloud Services 5
Supported Peripherals
Xstore Point of Service supports the following hardware peripherals:
Table 4-3: Xstore Point of Service Supported Peripherals
Type Hardware
Biometric Digital Persona U are U 4500
Oracle Hospitality Biometric Fingerprint

Module for Oracle MICROS Workstation 6
Eikon Touch 510 (SteelCoat)

Note: for Windows-based systems only
Cash Drawer APG

IBM
MICROS
Fiscal Module Unit (FMU) Retail Innovation - CleanCash Type A

(Sweden)
Retail Innovation - CleanCash Type C
(Sweden)
West International - WestInt KE Type A
(Sweden)
West International - WestInt KE Type C
(Sweden)
Network-Enabled Cash Drawer APG 486
Label Printer (ZPL II) IP-based Zebra GK420t (not supported on

Xstore Point of Service Mobile running on a
Workstation 310 or 610)
MSR Oracle MICROS WS620/WS650 MSR
Pole Display Logic Controls 3000 series

Oracle MICROS Workstation 620/650 Line
Display

System Requirements
Table 4-3: (continued)Xstore Point of Service Supported Peripherals
Type Hardware
Receipt Printer Epson TM-88V

Epson TM88-IV
Epson TM-H6000IV
Register/PC HP RP5-5810
HP RP5800
Oracle MICROS Workstation 620
Oracle MICROS Workstation 650
Scanner Honeywell MS7580

Honeywell Xenon 1900
Motorola DS4208
Symbol LS 2108
Symbol LS 2208
Zebra DS2278
Zebra DS8178
Signature Capture/PIN Pad/MSR Verifone MX915

Verifone MX925

Xstore Point of Service Mobile can be run on the following devices.
Table 4-4: Xstore Point of Service Mobile Supported Devices
Mobile Device Peripherals Operating System
iPad Mini 1 Verifone e335 iOS 9

Verifone e355
Symbol CS4070
iPod Touch 5th Gen Verifone e315 iOS 9

Verifone e315M
Verifone e355
Linea Pro 5
Symbol CS4070
iPod Touch 6th Gen Verifone e315 iOS 9

Verifone e315M iOS 10
Verifone e355 iOS 11
Linea Pro 5
Symbol CS4070

System Requirements
Table 4-4: (continued)Xstore Point of Service Mobile Supported Devices
Mobile Device Peripherals Operating System
iPad Mini 2 Verifone e355 iOS 9

iPad Mini 3 Symbol CS4070 iOS 10
iPad Mini 4 iOS 11
iPad 4
Oracle DT 317BT 7-inch Windows 10 IOT Enterprise

Tablet LTSB 2016 (1607) or later
Workstation 310 See Workstation 310 and 610 Windows 10 IOT Enterprise
Supported Peripherals LTSB 2016 (1607) or later
Workstation 610
Zebra MC40 Android 5.1.1 (Lollipop)
Zebra TC51 Android 6.0.1

(Marshmallow)
Zebra TC70 Android 5.1.1 (Lollipop)

Android 6.0.1
(Marshmallow)
Zebra ET55 Tablet Android 5.1.1 (Lollipop)

Android 6.0.1
(Marshmallow)
Supported Barcode Formats

Xstore Point of Service Mobile is able to scan barcodes with the following formats:
• Code 39 (Default)
• Code 93
• Code 128 (Default)
• EAN 13
• Interleaved 2 of 5
• UPC-A (Default)
Workstation 310 and 610 Supported Peripherals
Scanners
• Motorola DS4208
• Symbol LS 2108
• Symbol LS 2208
Cash Drawers
• APG 4000 series
• Micros
Printers
• Epson TM-H6000IV

System Requirements
• Epson TM-T88V
Fiscal Printers
• Custom K3-F
• Epson FP81/90
Line Display
• MICROS Line Display
Fingerprint Scanner
• Digital Persona U are U 4500
• EikonTouch 510
• Oracle Biometric Fingerprint Module for Oracle MICROS Workstation
Supported Payment Processors

Xstore Point of Service and Xstore Point of Service Mobile support the following
payment processors through EFTLink:
• Adyen (credit/debit only)
• AJB/Fipay (credit, debit, and gift card)
• Cayan (credit, debit, and gift card)
• Merchant Link (credit, debit, and gift card)
• Tender Retail (credit, debit and gift card)
• Verifone Point (credit, debit, and gift card)
Synchronized System Clocks

To ensure proper communication between systems using time-based one-time password
(TOTP) authentication, systems running Xenvironment or Xstore Point of Service must
have their system clocks synchronized.
Workstation 620 and 650 Systems with Oracle Databases

For systems running on these workstations and use an Oracle database, there are some
administrative shares that must be enabled for a successful installation of the Oracle
Database. To enable these shares, do the following:
1. Run the Windows registry editor:
a. Open the Start menu in Windows.
b. Enter regedit in the Search programs and files field.
c. Click regedit.exe.
d. Click Yes if you are prompted to allow the program to make changes to the
computer.
2. Open the HLKM folder in the registry directory.
3. Open System in the HLKM folder.
4. Open CurrentControlSet in the System folder.
5. Open Services in the CurrentControlSet folder.

System Requirements
6. Open LanmanServer in the Services folder.

7. Open Parameters in the LanmanServer folder.
8. Delete the AutoShareWks registry key.
9. Close regedit.
10. Restart the Windows Server service:
a. Open the Control Panel.
b. Click Administrative Tools.
c. Double-click Services.
d. Click to select the Windows Server service.
e. Click the Restart Service button.

Install Web Server
Install Web Server

When installing the web server:
1. Install and enable the HTTP Server.
Follow the procedures specified by your OS or HTTP service vendor to install the
HTTP server, taking care to ensure that WebDAV and HTTPS functionality is
installed with it, if it is optional.
2. Enable HTTPS with TLS.
Xstore Point of Service requires HTTPS over TLSv1.2 for communications with the
HTTP server. Follow the procedures specified by your OS or HTTP service vendor to
enable HTTPS functionality, and to ensure that communications over TLSv1.2 are
possible.
3. Disable non-HTTPS endpoint.
Most HTTP implementations will enable a standard, non-HTTPS, endpoint by
default. This endpoint should be disabled or rendered unreachable by a firewall to
prevent its use.
4. Enable HTTPS basic authentication.
Follow the procedures specified by your OS or HTTPS service vendor to enable
HTTPS basic authentication for your HTTPS service. Credentials will be required by
the Xstore Office and Xstore Point of Service applications to allow the uploading and
downloading of files.
5. Enable WebDAV.
Upload functionality, which uses HTTP PUT calls, requires WebDAV functionality to
be enabled. Follow the procedures specified by your OS or HTTP service vendor to
enable WebDAV functionality. If necessary, grant access to the users responsible for
uploading files to allow HTTP PUT functions to be accessible.
Create and Apply Customer Overlay

If you are using a customer ID and/or salt value other than the default values, you must
build a customized installation using a customer overlay on Xstore Point of Service. To
do this, you must perform the steps described in the following documents, which can be
found on My Oracle Support: (http://support.oracle.com/):
• Oracle Retail Xstore POS and Xstore Office Development Environment Setup (MOS ID
2158739.1)
• Oracle Retail Xstore POS and Xstore Office Build Server Setup White Paper (MOS ID
2055918.1)
Xstore Point of Service Installation .zip File

1. Download the Xstore Point of Service .zip installation files for your system from the
Note: The download files for Windows have parts 1 and 2. It is

recommended that you download both files. Xstore Point of Service
installations that use an Oracle database require both .zip files.


4. This will create the files and directories that are in the <root_directory>.
<root_directory>
Xstore Point of Service installation files.
artifacts
Build artifacts.

There are a set of package directories for Xstore Point of Service, each of which contain
installation files for a particular system. Use the correct package directory for your
installation. See “Installation File Directories” for more information about these
directories.

Xstore Point of Service package for your install.
database that uses pluggable databases. Contains Point-of-Service Installation .zip Files.

Contains Point-of-Service Installation .zip Files.
SQL Server database that does not use Unicode characters. Contains Point-of-Service
Installation .zip Files.
SQL Server database that uses Unicode characters. Contains Point-of-Service Installation
.zip Files.
Point-of-Service Installation .zip Files


Java
OracleRetailXstorePointofService_X_X_X_X_CCC_V_V_V.zip
X.X.X.X.XXX_V.V.V
where:
• X.X.X.X.XXX is the version and build number
• V.V.V is a customer release version
pos
Installation files for the Xstore Point of Service software. This includes the following
subdirectory:
• mobile - Installation files for Xstore Point of Service Mobile.
xenvironment
Installation files for Xenvironment.
xservices
Installation files Xstore Point of Service web services.
tools
- genkeys - Installation files for the GenKeys utility. This includes the string
encryption utility (see Appendix A: “String Encrypter Utility”) used to encrypt
information in the installation procedure, and generates security keys for use by
Xstore Office.
- jrepackager - Creates a JRE .zip file used by the installation procedure.
Java
Several Java components must be installed as part of the Xstore Point of Service
installation procedure.
Perform the following procedures:
• “Java Runtime Environment (JRE)”
• “Create JRE Package”

Java
Java Virtual Machine

If a Java Virtual Machine (JVM) is not currently installed on your system, you must
download and install a JVM before proceeding.
Important: A JVM must be installed on your system before you can

create the JRE package.

1. Download latest version of JRE 8 from Oracle.
Important: If you are upgrading from an earlier version of Xstore

Point of Service, you must use JRE 8.
2. Move the downloaded file to a temporary folder.

- Windows: c:\temp
- Linux: /tmp
Create JRE Package

Before installing any Xstore Point of Service components, you must create a custom JRE
package that will be used by the installation procedures.
3. Open a command prompt (for example, cmd in Windows or xterm in Linux).
4. Navigate to the jrepackager directory in the command prompt.
This directory can be found in the directory extracted from the
5. Run the following command:
- In Windows:
java –jar xstore-X.X.X.X.XXX-V.V.V-CCC-jrepackager.jar GUI
- In Linux:
java –jar xstore-X.X.X.X.XXX-V.V.V-CCC-jrepackager.jar GUI
where:
- X.X.X.X.XXX is the version and build number
6. Enter the JRE package creation information:
a. JRE Tarball Package: Full path to the JRE .tar.gz file.
For example:
* In Windows:
C:\temp\jre-8u141-windows-x64.tar.gz
* In Linux:
/tmp/jre-8u141-windows-i586.tar.gz

Database
b. Select the OS Platform for the supplied JRE.

7. Click Next.
8. Click Create JRE Package.
When the Finished notification opens, Java setup for Xstore Point of Service is complete.
Database
You will need a database either installed on the local system, or network access to a
database server. The database must either an Oracle or a Microsoft SQL Server database.
Oracle
Xstore Point of Service assumes that the Oracle database has been installed in the
oradata folder for the Oracle instance.
• On Linux, this would be similar to /u01/app/oradata/xstore
• On Windows, this would be similar to c:\app\oracle\oradata\xstore.
Microsoft SQL Server

If you are using an MS SQL Server database, it must have the following properties:
• The instance name must be MSSQLSERVER.
• The Authentication Mode must be Mixed Mode (SQL Server authentication and
Windows authentication).
• TCP/IP networking is turned on for MS SQL Server. This is configured through the Sql
Server Configuration Manager.
TLS Certificates
Several Xstore Point of Service components require TLS certificates to encrypt inter-
process communication. You must either receive these certificates from a certificate
authority, or you must create your own.
Important: Place all keystore files in the same directory as the Xstore
Point of Service installer. The installer will automatically find these
keystore files when they are in the same directory.
If you will be creating your own certificates, you will need OpenSSL & Keytool Utility.
See Appendix B: “Public Key Certificates” for more information.
• If you are installing Xstore Point of Service components for the first time, you will
likely not know all the security certificates you will require. The installation
procedures will inform you of the certificates you will require as you need them.
• If you have installed Xstore Point of Service before, it is recommended that you
either reuse existing security certificates, or create new certificates prior to installing
Xstore Point of Service components.


To install Xstore Point of Service Mobile, there are additional procedures that must be
performed:
• Install Xstore Mobile on Windows 10
• Set Screen Resolution (Windows 10 Only)
• Build an Xstore Point of Service Mobile Client Application (iOS Only)
• Extract the Jetty Password Obfuscation Utility (Xstore Point of Service Mobile and
Xservices)
Install Xstore Mobile on Windows 10

Follow the steps below to install the application package on a Windows 10 device:
Note: The signing certificate only needs to be created and imported

into the machine store the first time you install the app. After that, the
same certificate can be used for signing each time a new version of the
app is installed.
1. Obtain the appropriate appx bundle file that represents the Xstore Mobile Universal
Windows Platform (UWP) app.
2. Enable side-loading of the UWP apps through the Windows UI or by using a
registry edit command.
reg add
"HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\
AppModelUnlock" /t REG_DWORD /f /v "AllowAllTrustedApps" /d
"1"
3. Generate a new signing certificate. This will tell you the thumbprint of the certificate
when it succeeds.
Note: The subject must be "CN=Oracle Corporation". This is a

Windows PowerShell command. For more information about creating
signing certificates, see https://docs.microsoft.com/en-us/windows/
uwp/packaging/create-certificate-package-signing.
New-SelfSignedCertificate -Type Custom -Subject "CN=Oracle

Corporation" -KeyUsage DigitalSignature -CertStore
"Cert:\LocalMachine\My"
4. Export the certificate to a PFX file, as it is not usable for production purposes in the
"My" certificate store. Use the following Windows PowerShell command.
$pwd = ConvertTo-SecureString -String <password> -Force -
AsPlainText
Export-PfxCertificate -cert
"Cert:\LocalMachine\My\<certificate thumbprint>" -FilePath
<certificate-name>.pfx -Password $pwd
5. Sign the appx bundle package with the exported certificate. The SignTool is a utility
that comes with the Windows 10 SDK. For more information on the SignTool, see

https://docs.microsoft.com/en-us/windows/uwp/packaging/sign-app-package-
using-signtool.
C:\Program Files (x86)\Windows
Kits\10\bin\<versionNumber>\x64\signtool.exe sign /fd SHA256 /
a /f <certificate-name> /p <password> <package-
name>.appxbundle
6. Import the PFX certificate that you generated in the LocalMachine store. The
TrustedPeople certificate store is recommended for this purpose. Use the following
Windows PowerShell command.
$pwd = ConvertTo-SecureString -String <password> -Force -
AsPlainText
Import-PfxCertificate -FilePath <certificate-name> -
CertStoreLocation Cert:\LocalMachine\<Certificate Store Name>
-Password $pwd
7. Install the appx bundle package onto the device.
Note: The .NET Native Framework, the .NET Native Runtime and the
Microsoft VC Libs packages must be installed on the device prior to
this app package being installed. These packages can be obtained from
the Windows 10 SDK. Installing the dependencies is a one-time
operation per device.
Use the following Windows PowerShell command.

Add-AppxPackage -Path <package-name>.appxbundle
8. Obtain the SSL certificate from the system where the mobile server is running and
install that into the certificate store on the client device where the UWP app will be
running. Installing the certificate at the local machine (not the user) level is
recommended. Using the Trusted Root Certification Authorities certificate store
should be sufficient.
Import-Certificate -FilePath <certificate-name>.cer -
CertStoreLocation Cert:\LocalMachine\<Certificate Store Name>
9. Enable the network to use the Public Profile in Windows.
Set Screen Resolution (Windows 10 Only)

If you are using Xstore Point of Service Mobile on a Windows 10 tablet, there are certain
screen resolutions that must be used. To set the screen resolution to the proper scale:
1. Open the Windows Start menu.
2. Tap the Settings icon.
3. Tap System.
4. Tap Display.
5. Tap Advanced display settings.
6. Tap Advanced sizing of text and other items.
7. Tap set a custom scaling level.
The Custom sizing options window opens.

8. Select 100% in the Scale to this percentage of normal size menu.

9. Tap Ok.
The resolution is changed.
Build an Xstore Point of Service Mobile Client Application (iOS Only)

For iOS systems (iPhone and iPad), Xstore Point of Service Mobile is released as an
Xcode framework (XstoreMobile.framework) that you will use to build your own
iOS application. This section describes how to build your own Xstore Point of Service
Mobile client application.
Note: The Xstore Point of Service package can only be prepared on a

Mac.
Prerequisites
You will be required to set up a relationship with Apple to obtain and manage the
necessary developer provisioning profiles and certificates. As part of that program, you
will receive a signing certificate (.p12 file) and a .mobileprovision file. These
artifacts are used to sign your application.
Important: If the signing has not been done correctly, the

Xstore.ipa will fail to install properly. The typical behavior will be
as follows: iOS will grey out the Xstore Point of Service icon and
prevent the user from launching the application.
Install the Certificate

To install the certificate on the Mac where the Xstore Point of Service package will be
prepared:
1. Open the keychain access tool.
2. In the keychain tool, double-click the certificate.
3. Get the name of the certificate by doing one of the following:
- Click Get Info.
- Enter security find-identity on the command line.
Create a New Xcode Project

1. Create a new project in Xcode.
2. Select Single View Application for the template.
3. Configure the options for the new project:
a. Product Name: Enter Xstore.
b. Team: Select your Apple Developer Team.
c. Organization Name: Enter the name of your company.
d. Organization Identifier: Enter the package identifier for your company.
e. Language: Select Objective-C.
f. Devices: Select Universal.

g. User Core Data: Leave unchecked.

h. Include Unit Tests: Leave unchecked.
i. Include UI Tests: Leave unchecked.
4. Click Next.
5. Remove the following auto-generated files:
Note: These files must be moved to the trash. Do not just delete the
references.
- AppDelegate.h
- AppDelegate.m
- ViewController.h
- ViewController.m
- Main.storyboard
- LaunchScreen.storyboard
- Info.plist
Add XstoreMobile.framework to the Project

6. Copy the file XstoreMobile.framework to the root directory of the new project.
7. Add XstoreMobile.framework to the Xstore project:
a. Right-click Xstore in the left pane.
A menu opens.
b. Click Add Files to Xstore.
A file list opens.
c. Select XstoreMobile.framework.
d. Click Add.
8. Add XstoreMobile.framework to the Embedded Binaries:
a. Click the General tab.
b. Click the + in the Embedded Binaries section.
A file list opens.
c. Click XstoreMobile.framework.
d. Click Add.
The file list closes and the file is added.
9. Add resources from XstoreMobile.framework to Xstore:
a. Right click Xstore in the left pane.
A menu opens.
b. Click Add Files to Xstore.
A file list opens.
c. Click the following while pressing and holding the Command key:

* config.xml
* www
* Xstore-Info.plist
d. Click Add.
The file list closes and the file is added.
Import Properties from XstoreMobile.framework Project

11. Click Choose Info.plist File in the Identity section.
12. Select the Xstore-Info.plist file.
13. Click Add.
The properties from the Xstore-Info.plist file will appear in the Custom iOS
Target Properties section of the Info tab.
Update Icons and Launch Images

14. Remove all the automatically generated files from Assets.xcassets:
a. Click Assets.xcassets in the Project navigator.
A menu opens.
b. Click each item while pressing and holding the Command key.
c. Right click in the pane.
A menu opens.
d. Click Remove Selected Items.
The items are removed.
15. Import images into Assets.xcassets:
a. Right click Assets.xcassets in the left pane.
A menu opens.
b. Click Import...
A file list opens.
c. Click AppIcon.appiconset and LaunchImage.launchimage within the
XstoreMobile.framework file while pressing and holding the Command
key.
d. Click Open.
The file list closes and the files are added.
17. Click Use Asset Catalog in the App Icons and Launch Images section.
A Migrate launch images to an asset catalog prompt opens.
18. Select Assets.
19. Click Migrate.

The prompt closes and returns to the General tab.
Note: You may need to click a different tab, then return to the General
tab to refresh the choices in the LaunchImage menu.
20. Select AppIcon in the App Icons Source field.

21. Select LaunchImage in the Launch Images Source field.
Configure Build Settings

22. Click the Build Settings tab.
23. Set Enable Bitcode to No.
Set the Application’s Main Entry Point

24. Open the file main.m.
25. Enter the following in the main.m file:
//
// main.m
// Xstore
//
#import <UIKit/UIKit.h>
#import <XstoreMobile/XstoreMobile.h>
int main(int argc, char * argv[]) {

@autoreleasepool {
return UIApplicationMain(argc, argv, nil, @"AppDelegate");
}
}
Configure your Apple Developer Provisioning Profiles

Select your Apple Developer Provisioning Profile to sign your application:
27. Select your Provisioning Profile in the Signing (Debug) section.
28. Select your Provisioning Profile in the Signing (Release) section.
Configure Verifone Support

If your iOS device is integrated with a supported Verifone peripheral (e315, e335, or
e355), do the following:
29. Copy the file XstoreMobileVerifoneSupport.framework to the root directory
of the project.
30. Right click Xstore in the left pane.

A menu opens.
31. Click Add Files to Xstore.
33. Add XstoreMobileVerifoneSupport.framework to the Embedded Binaries:
a. Click the + in the Embedded Binaries section.
A file list opens.
b. Click XstoreMobileVerifoneSupport.framework.
c. Click Add.
34. If necessary, add XstoreMobileVerifoneSupport.framework to the Linked
Frameworks and Libraries:
a. Click the + in the Linked Frameworks and Libraries section.
A file list opens.
c. Click Add.
35. Copy the file VMF.framework to the root directory of the project.
A menu opens.
A file list opens.
38. Click VMF.framework.
39. Click Add.
40. Add VMF.framework to the Linked Frameworks and Libraries:
A file list opens.
b. Click VMF.framework.
c. Click Add.
41. Edit the main.m file to include the highlighted information:
//
// main.m
// Xstore
//
#import <XstoreMobileVerifoneSupport/VerifoneHardwareDelegate.h>

@autoreleasepool {
// Inspect for hardware devices
NSArray *hardware = [[EAAccessoryManager
sharedAccessoryManager] connectedAccessories];
// Find the first supported hardware accessory and

instantiate a delegate for it
if ([hardware count] > 0) {
for (int i = 0; i < [hardware count]; i++) {
NSString *hardwareName = [[[hardware objectAtIndex:i]
name] uppercaseString];
NSLog(@"hardwareName=%@",hardwareName);
if ([hardwareName hasPrefix:@"PAYWARE"]) {
[[PosHardwareAPI sharedInstance]
setPosHardwareDelegate:[[VeriFoneHardwareDelegate alloc]init]];
}
}
}
}
}
42. Click the Info tab.
43. Ensure that the Supported external accessory protocols contains the following
values:
com.verifone.pmr.xpi
com.verifone.pmr.control
com.verifone.pmr.barcode
com.verifone.pmr.zontalk
com.verifone.pmr2.xpi
com.verifone.pmr2.control
com.verifone.pmr2.barcode
com.verifone.pmr2.zontalk
Configure Zebra or Symbol Support

If your iOS device is integrated with a supported Zebra or Symbol peripheral (CS4070),
do the following:
44. Copy the file XstoreMobileZebraSupport.framework to the root directory of
the project.
A menu opens.


48. Add XstoreMobileZebraSupport.framework to the Embedded Binaries:
a. Click the + in the Embedded Binaries section.
A file list opens.
c. Click Add.
49. If necessary, add XstoreMobileZebraSupport.framework to the Linked
Frameworks and Libraries:
A file list opens.
b. Click XstoreMobileZebraSupport.framework.
c. Click Add.
50. Copy the directory symbolbt-sdk to the root directory of the project.
A menu opens.
A file list opens.
53. Click the libsymbolbt-sdk.a file.
54. Click Add.
56. Verify that libsymbolbt-sdk.a is included in Linked Frameworks and Libraries.
57. Add the symbol header files to the Linked Frameworks and Libraries:
A file list opens.
b. Select all the .h files in the symbolbt-sdk/include directory:
* iSbtSdkApi.h
* iSbtSdkApiDelegate.h
* RMDAttributes.h
* SbtScannerInfo.h
* SbtSdkDefs.h
* SbtSdkFactory.h
c. Click Add.

58. Edit the main.m file to include the highlighted information:
Note: The content will be different if you are integrating with both a
Verifone device and a Zebra device. Speak with your Xstore Point of
Service product representative for assistance integrating more than
one device with Xstore Point of Service Mobile.
//
// main.m
// Xstore
//
#import <XstoreMobileZebraSupport/ZebraScannerDelegate.h>

@autoreleasepool {
// Inspect for hardware devices
NSArray *hardware = [[EAAccessoryManager
sharedAccessoryManager] connectedAccessories];
// Find the first supported hardware accessory and

instantiate a delegate for it
if ([hardware count] > 0) {
for (int i = 0; i < [hardware count]; i++) {
NSString *hardwareName = [[[hardware objectAtIndex:i]
name] uppercaseString];
NSLog(@"hardwareName=%@",hardwareName);
if ([hardwareName hasPrefix:@"CS4070"]) {
[[PosHardwareAPI sharedInstance]
setPosHardwareDelegate:[[ZebraScannerDelegate alloc]init]];
}
}
}
}
}
59. Click the Info tab.

60. Ensure that the Supported external accessory protocols contains the following
value:
com.motorolasolutions.CS4070_ssi
61. Click the Capabilities tab.
62. Enable the Background Modes section.
A list of options opens.
63. Enable External accessory communication in the Background Modes section.
64. If necessary, configure the background mode for the CS4070:
Note: These steps are only required if you are installing Xstore Point
of Service Mobile on a device that uses the Zebra or Symbol CS4070
scanner peripheral.
a. Open the Products folder in the left pane.

b. Open the Applications folder.
c. Open the Xstore folder.
d. Open the Info.plist file for editing.
e. Add the following line to the Info.plist file:
"Required background modes": "App communicates with an accessory"
Archive the Application

There are two methods for archiving the application:
• Xcode UI
• Xcodebuild
Xcode UI
After setting up the application, create an application archive that can be installed on an
iOS device:
65. Click Archive in the Product menu.
A archiving window opens.
66. Click Export... in the right pane.
A list of export methods opens.
67. Select Save for Enterprise Deployment.
Note: This is the most commonly used option. You may use a
different export method, if necessary.
68. Click Next.

A window prompts for the Apple developer profile.
69. Select your Apple developer profile.
70. Click Choose.

A Device Support window opens.

71. Select Export one app for all compatible devices.
72. Click Next.
A Summary window opens.
73. Click Next.
Wait for the package to be prepared. When it is finished, a window prompts for the
export location.
74. Enter the name of the directory to which to package will be exported.
75. Select the location of the destination directory.
76. Click Export.
The package is exported.
77. Use mobile device management (MDM) software to load the Xstore.ipa file on an
iOS device. For example, Apple Configurator 2 or iTunes.
Xcodebuild
After setting up the application, create an application archive that can be installed on an
iOS device:
78. Open a terminal window.
79. Navigate to the Xcode project directory in the terminal.
xcodebuild archive -project Xstore.xcodeproj -scheme Xstore
-archivePath Xstore
81. Create an options.plist file in the Xcode project directory.
82. Enter the following content into the options.plist file:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://
www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>method</key>
<string>enterprise</string>
<key>compileBitcode</key>
<false/>
<key>teamID</key>
<string>{your 10 digit Apple Developer teamID}</string>
</dict>
</plist>
Where:

Extract the Jetty Password Obfuscation Utility (Xstore Point of Service Mobile and Xservices)
{your 10 digit Apple Developer teamID} is the team ID for your Apple
Developer account.
Note: Your team ID can be found in the value for the

TeamIdentifier key .mobileprovision file, or it can be found by
logging into your Apple Developer account.
83. Save the file.

xcodebuild -exportArchive -archivePath Xstore.xcarchive
-exportPath . -exportOptionsPlist options.plist
This will produce an Xstore.ipa file, in the current directory, that has been signed
with your Apple Developer provisioning profile signature.
85. Use mobile device management (MDM) software to load the Xstore.ipa file on an
iOS device. For example, Apple Configurator 2 or iTunes.
Extract the Jetty Password Obfuscation Utility (Xstore Point

of Service Mobile and Xservices)
If you are installing either Xstore Point of Service Mobile or Xservices, you must
obfuscate passwords prior to entering them into the Xstore Point of Service installation
interface. Password obfuscation uses a Jetty utility that is included in the Xstore Point of
Service installation package. To extract the utility:
1. Navigate to the file location of the Xstore Point of Service installation .jar file.
2. Open the Xstore Point of Service installation file in a file archiver that can navigate
both .jar and .zip files (for example, 7-Zip).
3. Open xstore-pos-mobile.zip in the archive.
4. Open the lib\ext\jetty\ subdirectory in the archive.
5. Copy the file jetty-util-9.4.11.vXXXXXXXX.jar from the archive to your
local file system.
Note: This file should be placed in an easy-to-find directory.
Linux Pre-installation Procedures for Xenvironment

Because of the different processing requirements of Linux, extra steps must be
performed prior to installing Xenvironment on a Linux system:
1. Install KDE as the desktop environment.
2. Locate the xconfigs.tar.gz file in the ext directory for Xenvironment (for
example: c:\environment\ext\xconfigs.tar.gz).
3. Copy the file xconfigs.tar.gz (see step 2)to the xstore home directory.
4. Extract the files in the xconfigs.tar.gz into the xstore user’s home directory.
cd ~xstore
tar -xz xconfigs.tar.gz

Linux Integration with APG Network Cash Drawer
5. Grant the xstore user access to the shutdown command with the following
command:
chmod +s /sbin/shutdown
6. Create the following folders and give the xstore user full access to them:
/opt/environment
/opt/updates
/opt/xstoredb/backup
/opt/jre
7. Transfer ownership of the directory /opt/xstoredb/backup to the oracle user
with the following command:
chown –R oracle:users /opt/xstoredb
8. Grant additional access to the /opt/xstoredb and /opt/xstoredb/backup
directories with the following commands:
chmod –R 775 /opt/xstoredb
chmod g+s /opt/xstoredb/backup
Linux Integration with APG Network Cash Drawer

Add a persistent route to the 169.254.0.0 network on any register running Oracle
Enterprise Linux that is integrated with an APG network cash drawer with a static IP
address.
By default, APG's network cash drawer is configured to use DHCP to obtain an IP
address (as opposed to having a static address). When it is powered on for the very first
time or a reset is performed on it, the device will attempt to contact a DHCP Server to
obtain an IP Address. If there is no DHCP Server available, the cash drawer will assign
itself an IP address on the 169.254.0.0 network (this is a range reserved specifically for
this situation in IPv4).
For a register with a static IP address to be able to communicate with an APG network
cash drawer, there must be a route to the 169.254.0.0 network on the register.

5
Install Xstore Point of Service
Overview
InstallX is used to build and install builds of the Xstore Point of Service application and
associated server-based components. This installation application is used to package,
install and configure the Xstore Point of Service application, associated server-based
components, and utilities. It is customer, operating system, and database platform
independent.
InstallX maintains the order in any properties files it updates (using ant tasks) during the
install. The properties are carried over into the base-xstore.properties which is
human-readable and retains comments and line breaks.
baseconfigure.bat does not change ordering or remove comments in any properties
files it touches. For example, you can edit system.properties, re-order it to your
liking, and add comments. baseconfigure.bat is able to update values in it and
retain the formatting.

information about upgrade, update, and patch installation types.
Install Xstore Point of Service 5-1

InstallX Modes of Operation - Overview
InstallX Modes of Operation - Overview

The install can be run unattended in Silent mode or it can be run using a GUI that
prompts for some additional information. A command line parameter is required to run
the GUI.
Silent Mode
Silent mode, also referred to as “unattended mode”, allows you to set customization
options in a properties text file before running InstallX. This allows for the InstallX
process to be run without user interaction. It is designed for deployments when user
interaction is not possible or not desired.
Note: Silent mode is the default mode.
For example, the following command is used to launch the InstallX Xstore Point of
Service Installer in Silent Mode:
c:\jre\bin\java -jar xstore-version-XYZ-appname.jar
GUI Mode
GUI mode provides an interactive graphical interface that guides you through a wizard-
style process to install applications in a demo or lab environment. You will be prompted
with a series of configuration choices and deployment options to customize your
installation.
Note: GUI mode is only supported for installs.
For example, the following command is used to launch the InstallX Xstore Point of
Service Installer in GUI Mode:
c:\jre\bin\java -jar xstore-version-XYZ-appname.jar gui
Xstore Point of Service Installer: File Naming Conventions

The following naming convention will be used throughout the Install Instructions in this
section.
xstore-B.B.B.B-V.V.V-P.P-CCC-pos-TYPE.jar
Where...
B.B.B.B is the base release version
V.V.V is the customer release version
P.P is the patch release version
CCC is the three-letter customer ID
pos is the app name
TYPE is the installer type (install, upgrade, update, patch)

Xstore Point of Service Installation

To install Xstore Point of Service components, do the following:
Install GenKeys String Encrypter Utility

This procedure creates the string encrypter utility described in Appendix A: “String
Encrypter Utility”.
1. Navigate to the genkeys directory extracted from the
OracleRetailXstoreCommon_X_X_X_X_X_CCC_V_V_V.zip file. See “Xstore Point of
Service Installation .zip File” in Chapter 4, “Prerequisites for Installing Xstore Point
of Service” for more information.
emacs).
3. If necessary, change the installDir property to the directory where GenKeys will
be installed.
For example, in Windows:
installDir = C\:\\xstore-genkeys

In Linux:
installDir = /opt/xstore-genkeys
4. Change the customerId.salt property to your salt value.
Note: You must always use the same salt value when creating
certificates. It is recommended that you use a value that is at least 8
characters in length and difficult to guess.

7. In the command prompt, navigate to the genkeys directory extracted from the
OracleRetailXstoreCommon_X_X_X_X_X_CCC_V_V_V.zip file. See “Xstore Point of
Service Installation .zip File” for more information.
8. In the command prompt, install GenKeys with the command:
c:\jre\bin\java –jar xstore-X.X.X.X.XXX-V.V.V-CCC-
genkeys.jar
where:

Create Cipher Key Files

9. In a file explorer, navigate to the GenKeys directory configured in step 3 on page 3.
10. Navigate to the wrapper\conf directory.
11. Open the file gen-keys.conf in a text editor (for example, Notepad or emacs).
12. Find the following line in the gen-keys.conf file (in Section 4):
wrapper.java.additional.4=-Ddtv.CustomerId=@customerId@
13. Change the value of the property to your encryption salt value.
For example:
wrapper.java.additional.4=-Ddtv.CustomerId=XST
14. Save the file.
Generate Rotating Keys for All Keys Except Debit/Credit

Section 2):
# Section 2: Generate Rotating Cipher Keys (All Keys)
# Update parameter.3 (start date) and parameter.4
(end date) with the desired effective dates (YYYY-MM-DD)
#
wrapper.app.parameter.2=-all
For example:
For example:
19. Save the file.
20. In a command prompt, navigate to the GenKeys directory configured in step 3 on
page 3.

Windows:
gen-keys.bat
Linux:
./gen-keys.sh
22. The rotating cipher key files are generated.
Generate Rotating Keys for Debit/Credit

Section 3):
# Section 3: Generate Rotating Cipher Keys (Credit Card
Keys Only)
# Update parameter.4 (start date) and parameter.5 (end
date) with the desired effective dates (YYYY-MM-DD)
#
wrapper.app.parameter.2=-make
wrapper.app.parameter.3=ccenc
For example:
For example:
27. Save the file.
28. In a command prompt, navigate to the GenKeys directory configured in step 3.
Windows:
gen-keys.bat
Linux:
./gen-keys.sh
30. The rotating debit/credit cipher key files are generated.


Before you install Xstore Point of Service...
You will be prompted for the following information during the Xstore Point of Service
install process. You may want to define (and encrypt as needed) these usernames,
passwords, host names, etc. before you begin the install process. See Appendix A:
“String Encrypter Utility” for information about encrypting text using cipher keys.
• If you are installing Xstore Point of Service Mobile:
- Copy the keystore file for Xstore Point of Service Mobile to the same directory as
the installer.
- Rename the keystore file to xstore_mobile.keystore.
• Xstore Office Application Server details including:
- Host Name or IP address and Port
- App Server Username and App Server Password
- Keystore Password and Truststore Password
• Store Primary Database details including:
- Store Primary Host name
- Store Primary Database name
- Database Username and Database Password
- Database Schema Owner Username and Database Schema Owner Password
• Store Backup data source details including:
- Store Backup Host name
- Store Backup Database name
• Local/Offline database server details including:
- Local/Offline Host name
- Local/Offline Database name
• Replication database server details including:
- Replication Host name
- Replication Database name
• Master Database server details including:
• Training database server details including:

- Training Host name

- Training Database name
- Database Administrator Username and Database Administrator Password
• Customer Engagement Cloud Service server details if using Customer Engagement
Cloud Service
• Order Broker Cloud Service server details if using Order Broker Cloud Service
• Opera server details if using Opera
Installation Procedure
32. In the command prompt, navigate to the pos directory extracted from the
OracleRetailXstorePointofService_X_X_X_X_CCC_V_V_V.zip file. See “Xstore Point
of Service Installation .zip File” in Chapter 4, “Prerequisites for Installing Xstore
Point of Service” for more information.
33. Run the Xstore Point of Service installation procedure with the command:
c:\jre\bin\java -jar xstore-X.X.X.X.XXX-V.V.V-P.P-CCC-pos-
install.jar GUI
where:
- P.P is a patch number
The Xstore Point of Service installation window opens to the welcome screen.
34. Click Next.
35. Select the installation type:
a. Full Service Workstation - Perform a full installation of Xstore Point of Service.
b. Thin Client Workstation - Perform an installation of a thin client version of
Xstore Point of Service. This is the Windows tablet version of Xstore Point of Service
Mobile.
c. Full Service plus Mobile Server - Perform a full installation of Xstore Point of
Service, including a server for Xstore Point of Service Mobile.
d. Lane Check Out - Perform a full installation of Xstore Point of Service with the
Lane Checkout Interface.
36. Click Next.
- If you selected Thin Client Workstation in step 35, continue with the next step.
- If you selected an option other than Thin Client Workstation in step 35,
continue with step 39.
37. Enter the Install Location configurations:

a. Select an installation directory: Enter the directory where Xstore Point of

Service will be installed.
b. Customer ID salt: Salt value used when creating certificates.
must create and apply a customer overlay to your project.
38. Click Next to continue with step 95.

39. Enter the Install Location configurations:
a. Select an installation directory: Enter the directory where Xstore Point of
Service will be installed.
b. Select a database installation directory: Enter the directory where the Xstore
Point of Service database will be installed.
Note: For Oracle database installations, this should be the oradata

folder for the instance.
c. Local Database: Select a local database option.

* Select Yes if the system hosts a local database.
* Select No if the system does not host its own database (for example, a
tablet).
* Select Replication Only if the system hosts a local replication database, but
no local Xstore Point of Service database (in the
ant.install.properties file, this option is replonly.).
Note: This is only appropriate for tablet installations.
d. Environment - Select the environment Xstore Point of Service is being installed

in:
* Production: Does not populate the database.
* Test: Populates the database with test data.
40. Click Next.
41. If a directory does not exist, click Yes when prompted whether to create it.
42. Enter the Location Settings:
a. Organization Id: Numeric identifier for the organization.
b. Store #: Numeric identifier for the store.
c. Register #: Numeric identifier for the register.
d. Country Id: Two-letter identifier for the country.
e. Currency Id: Three-letter identifier for the default currency used by 1the system.
f. Region Id: Identifier for the region (Optional).
43. Click Next.
44. Enter the Miscellaneous Settings:

a. Payroll/OT Rule: Rule used to determine whether a worker logged overtime for
the day.
b. Send Sale Tax Type: Rule used when applying sales tax to a send-sale item.
c. Salt: Salt used when creating certificates (must match the salt entered in step 4).
d. Dataloader File Encoding: Character encoding that Dataloader should expect in
host interface files.
45. Click Next.
- If you selected Full Service plus Mobile Server in step 35, continue with the
next step.
- If you selected Lane Check Out in step 35, continue with step 51.
- If you did not select Full Service plus Mobile Server in step 35, continue with
step 53.
46. Enter the Xstore Mobile Settings:
a. Xstore Mobile install dir: Directory where Xstore Point of Service Mobile will
be installed.
b. Configurations: Additional configuration path elements for Xstore Point of
Service Mobile.
c. Server Key Alias: The key alias used for the Xstore Point of Service Mobile key
added to the keystore.
d. Server Keystore Password (OBF): The password for the keystore, in Jetty's
proprietary Obfuscated format. For more information, see Extract the Jetty
Password Obfuscation Utility (Xstore Point of Service Mobile and Xservices) in
Chapter 4, “Prerequisites for Installing Xstore Point of Service”.
To obfuscate a password:
i) Open a command prompt (for example, cmd in Windows or xterm in
Linux).
ii) In the command prompt, navigate to the directory where you placed the
Jetty password obfuscation utility (see Extract the Jetty Password
Obfuscation Utility (Xstore Point of Service Mobile and Xservices)).
iii) Run the command:
c:\jre\bin\java -cp jetty-util-<version>.jar
org.eclipse.jetty.util.security.Password <password>
where:
<version> version of the Jetty password obfuscation utility.
<password> is the password to obfuscate.
The output of the command will look like the following (if the password is
allgoodthings):
Note: The default password must be changed.
allgoodthings
OBF:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
MD5:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The output line starting with OBF: will be used during the installation
procedure.
e. RSA Private Key Path: Full pathname to the RSA private key.
f. RSA Private Key Password: Encrypted password required to use the RSA
private key. Use the String Encrypter Utility to encrypt this value.
47. Click Next.
48. If the directory entered for Xstore Mobile install dir does not exist, click Yes when
prompted whether to create it.
49. Enter the Xstore Mobile Form Factor Settings:
a. Handheld Server Register #: Register number for the register operating as the
server for handheld devices.
b. Tablet Server Register #: Register number for the register operating as the
server for tablet devices.
c. Thin Client Server Register #: Register number for the register operating as the
server for thin client devices.
d. Disable Mobile Server start?: If checked, the system will not receive requests
from handheld devices.
e. Disable Tablet Server start?: If checked, the system will not receive requests
from tablet devices.
f. Disable Thin Client Server start?: If checked, the system will not receive
requests from thin client devices.
Note: No more than one of the three preceding options can be

unchecked. Each form factor for Xstore Point of Service Mobile
(handheld, tablet, or thin client) must run on its own server.
50. Click Next.

Continue with step 53.
51. Enter the Lane Check-out Settings:
a. Register Model: Model of the hardware, cash register, scanner, or scale on
which Xstore Point of Service is being installed. This setting has the following
possible values:
* Workstation_6 - A Workstation 6 model with a screen resolution of 1920 x
1080.
* VIRTUAL - A system with a screen resolution of 1024 x 768.
Note: No automatic resizing of the screen will be performed.
b. Velocity MacroLibrary: The path to the MacroLibrary with additional scripts for
the interpreter.
52. Click Next.
53. Enter the Email Server settings:
a. Mail Server Host: The email server host name or IP address.

b. Mail Server Port: The email server port number.

c. SMTP Debug?: Determines whether SMTP debugging settings:
* Checked - The logger severity is set to DEBUG and Xstore Point of Service
will log SMTP debug messages to the console.
* Unchecked - The logger will not log debugging messages, and the messages
will not be sent to the console.
d. SMTP Auth?: Determines whether Xstore Point of Service will make secure
SMTP connections to the SMTP server:
* Checked - Xstore Point of Service will make secure SMTP connections
(smtps) for email operations. This usually requires a user name and
password.
* Unchecked - Xstore Point of Service will use unsecured SMTP connections
(smtp) for email operations. Username and Password will be ignored.
e. Mail Server Username: Username used when making secure SMTP
connections.
f. Mail Server Password: Password used when making secure SMTP connections.
g. Mail Default Sender: The default email address used when sending emails.
54. Click Next.
55. Enter any Configurations used to determine the loading order of base and custom
configurations and resources.
Note: The configuration paths are specific to your organization.

Separate paths for resource bundles (translations, hardware, help,
email, phone numbers, etc.) have been eliminated. All resource
bundles now use the regular configuration path for loading.
56. Click Next.

57. Select the Data Sources that will be used by Xstore Point of Service:
a. Customer Engagement - Oracle Retail Customer Engagement Cloud Service.
b. SIM - Oracle Retail Store Inventory Management.
c. RXM - Oracle Commerce Retail Extension Module.
d. AVS - Oracle Retail Address Verification Service.
e. Order Broker - Oracle Retail Order Broker Cloud Service.
f. Order Management - Oracle Retail Order Management Cloud Service.
g. Xcenter - Xstore Office.
h. StorePrimary - The primary store database.
i. StoreBackup - The backup store database.
Note: Currently, there is no support for StoreBackup in base Xstore

Point of Service.
j. Replication - This option is required and cannot be changed.

k. Training - This option is required and cannot be changed.

l. Opera - Oracle® Hospitality OPERA.
58. Click Next.
59. If you selected Customer Engagement in step 57, enter the Customer Engagement
Cloud Service Data Source Settings for Oracle Retail Customer Engagement Cloud
Service:
a. Customer Engagement Protocol: Protocol used to connect to Customer
Engagement Cloud Service.
b. Customer Engagement Host: Hostname for Customer Engagement Cloud
Service.
c. Customer Engagement Port: Port for Customer Engagement Cloud Service.
d. Customer Engagement Customer Name: Organization ID for Customer
Engagement Cloud Service.
e. Customer Engagement Service Timeout: Timeout (in seconds) to use when
connecting to Customer Engagement Cloud Service.
f. Customer Engagement Loyalty Card Prefix: Numeric prefix used by loyalty
cards.
g. Customer Engagement Loyalty Card Series: Card series used by loyalty cards.
h. Customer Engagement Authentication: An encrypted string representing the
Customer Engagement Cloud Service Org, User, and Password in the format
<Org>:<User>:<Password>. Use the String Encrypter Utility to encrypt this
value.
For example, if your Customer Engagement Cloud Service Org is xst, the user to
connect to Customer Engagement Cloud Service is myuser, and that user’s
password is mypassword then you would encrypt the string
xst:myuser:mypassword and then place that encrypted string into this field.
i. Customer Engagement Auth. Token Name: Method used to create the
authentication string.
Note: Enter Org-User into this field.
60. Click Next.

61. If you selected SIM in step 57, enter the SIM Data Source Settings:
Note: For more information about Xstore Point of Service integration

with Store Inventory Management (SIM), see Appendix J: “Store
Inventory Management Integration”.
a. SIM Protocol: Protocol used to connect to SIM.

b. SIM Host: Hostname for SIM.
c. SIM Port: Port for SIM.
d. SIM Username: Encrypted username used to log into SIM. Use the String
Encrypter Utility to encrypt this value.

e. SIM Password: Encrypted password used to log into SIM. Use the String

f. SIM Service Timeout: Timeout (in seconds) to use when connecting to SIM.
g. SIM Process Transaction Retry Interval: The time to wait (after a timeout)
before attempting to connect to SIM again.
62. Click Next.
63. If you selected RXM in step 57, enter the RXM Data Source Settings for Retail
Extension Module.
Note: If you are integrating Xstore Point of Service with RXM, there
are additional configurations that must be performed for the
integration to work correctly. These configurations are described in
Configure Xstore Point of Service for Retail Extension Module.
a. RXM Protocol: Protocol used to connect to RXM.

b. RXM Host: Hostname for RXM.
c. RXM Port: Port for RXM.
d. RXM Container Username: Encrypted username used to log into RXM. Use the
String Encrypter Utility to encrypt this value.
e. RXM Container Password: Encrypted password used to log into RXM. Use the
f. RXM Application Username: Encrypted username used to log into RXM. Use
the String Encrypter Utility to encrypt this value.
g. RXM Application Password: Encrypted password used to log into RXM. Use the
h. RXM Site ID: ID for the RXM site.
i. RXM Service Timeout: Timeout (in seconds) to use when connecting to RXM.
64. Click Next.
65. If you selected AVS in step 57, enter the AVS Data Source Settings for AVS
integration.
Note: If you are integrating Xstore Point of Service with AVS, there
are additional configurations that must be performed for the
integration to work correctly. These configurations are described in
Configure Xstore Point of Service for Retail Extension Module.
a. AVS Protocol: Protocol used to connect to AVS.

b. AVS Host: Hostname for AVS.
c. AVS Port: Port for AVS.
d. AVS Password: Encrypted password used to log into AVS. Use the String
e. AVS Service Timeout: Timeout (in seconds) to use when connecting to AVS.
66. Click Next.

67. If you selected Order Broker in step 57, enter the Order Broker Integration Settings
for Oracle Retail Order Broker Cloud Service.
a. Order Broker Service WSDL Location: URL for the Order Broker Cloud Service
web service.
b. Order Broker Username: Encrypted username used to log into Order Broker
Cloud Service. Use the String Encrypter Utility to encrypt this value.
c. Order Broker Password: Encrypted password used to log into Order Broker
d. Order Broker Service Timeout: Timeout (in seconds) to use when connecting to
Order Broker Cloud Service.
e. Order Broker-Xstore System Code: System code that Xstore Point of Service
will be using in Order Broker Cloud Service. This value is defined in Order Broker
Cloud Service and simply needs to be specified in Xstore Point of Service.
f. Order Broker Destination: Identifies what should be sent to Order Broker
Cloud Service as the destination in a request message. This is set in Order Broker
Cloud Service and dictated by Order Broker Cloud Service.
68. Click Next.
69. If you selected Order Management in step 57, enter the Order Management
Integration Settings for Oracle Retail Order Management Cloud Service.
a. Order Management Service WSDL Location: URL for the Order Management
Cloud Service web service.
b. Order Management Username: Encrypted username used to log into Order
Management Cloud Service. Use the String Encrypter Utility to encrypt this value.
c. Order Management Password: Encrypted password used to log into Order
Management Cloud Service. Use the String Encrypter Utility to encrypt this value.
d. Order Management Service Timeout: Timeout (in seconds) to use when
connecting to Order Management Cloud Service.
e. Order Management-Xstore System Code: System code that Xstore Point of
Service will be using in Order Management Cloud Service. This value is defined in
Order Management Cloud Service and simply needs to be specified in Xstore Point of
Service.
70. Click Next.
71. If you selected Xcenter in step 57, enter the Xcenter Application Server Settings for
Xstore Office.
a. App Server Host: Hostname for Xstore Office.
b. App Server Port: Port for Xstore Office.
c. App Server Username: Encrypted username for Xstore Office. Use the String
d. App Server Password: Encrypted password for Xstore Office. Use the String
Note: The App Server Customer Name and App Server Password are
specified in the WebLogic installation, the Jetty installation step 159, or
Tomcat installation step 187.

e. Keystore Pwd: Encrypted password for the Xstore Office keystore. Use the String
f. Truststore Pwd: Encrypted password for the Xstore Office truststore. Use the
72. Click Next.
73. Enter the Schema Creation details:
a. Database Admin Username: Encrypted username for the database
administrator. Use the String Encrypter Utility to encrypt this value.
Note: The username should be pos.
b. Database Admin Password: Encrypted password for the database

74. If you selected StorePrimary in step 57, enter the StorePrimary Data Source Settings
for the StorePrimary database.
a. Store Primary Host: Hostname for the StorePrimary database.
b. Store Primary Database: Name of the StorePrimary database.
c. Database Username: Encrypted username for the StorePrimary database. Use
Note: The username should be pos.
d. Database Password: Encrypted password for the StorePrimary database. Use the

75. Click Next.
76. If you selected StoreBackup in step 57, enter the StoreBackup Data Source Settings
for the StoreBackup database.
Note: Currently, there is no support for StoreBackup in base Xstore

Point of Service.
a. Store Backup Host: Hostname for the StoreBackup database.

b. Store Backup Database: Name of the StoreBackup database.
c. Database Username: Encrypted username for the StoreBackup database. Use the
d. Database Password: Encrypted password for the StoreBackup database. Use the
77. Click Next.
78. Enter the Local Data Source Settings for the local database.
a. Local/Offline Host: Hostname for the local database.
b. Local/Offline Database: Name of the local database.
c. Database Username: Encrypted username for the local database. Use the String

d. Database Password: Encrypted password for the local database. Use the String

79. Click Next.
80. Enter the Replication Data Source Settings for the replication database.
a. Replication Host: Hostname for the replication database.
b. Replication Database: Name of the replication database.
c. Database Username: Encrypted username for the replication database. Use the
d. Database Password: Encrypted password for the replication database. Use the
81. Click Next.
82. Enter the Schema Creation Details for the master database.
a. Database Admin Username: Encrypted username for the database
administrator (the username is either sys or system for Oracle, and sa for SQL
Server). Use the String Encrypter Utility to encrypt this value.
b. Database Admin Password: Encrypted password for the database
83. Click Next.
84. Enter the Other Data Source Settings for the master database.
a. Master Database:
i) Database Username: Encrypted username for the master database. Use the
Note: The username should be dtv.
ii) Database Password: Encrypted password for the master database. Use the
b. Schema Owner:
i) Database Username: Encrypted username for the schema owner. Use the
Note: The username should be dtv.
ii) Database Password: Encrypted password for the schema owner. Use the
85. Click Next.
86. Enter the Training Data Source Settings for the training database.
a. Training Host: Hostname for the training database.
b. Training Database: Name of the training database.

c. Database Username: Encrypted username for the training database. Use the

Note: The username should be training on systems using Oracle

databases and pos on systems using SQL Server.
d. Database Password: Encrypted password for the training database. Use the

87. Click Next.
88. If you selected Opera in step 57, enter the Opera Integration Settings for Oracle
Hospitality OPERA.
a. Opera Connection URL: URL for OPERA.
b. Opera Connection String: Connection string used when connecting to OPERA.
c. Opera Timeout: Timeout (in seconds) to use when connecting to OPERA.
d. Opera Resort: Resort for OPERA.
e. Opera Row ID: ID for the OPERA row.
89. Click Next.
90. Select the services to be turned on for this installation:
a. Replication: Database replication.
b. Authorizations: Payment authorization.
91. Click Next.
- If Authorizations are turned On in step 89, continue with the next step.
- If Authorizations are turned Off in step 89, continue with step 95.
92. Select the authorization platforms for credit/debit authorization:
* EFT Link - EFTLink.
Note: For information about EFTLink, see the Oracle Retail EFTLink

Framework Installation Guide, the Oracle Retail EFTLink Core
Configuration Guide, and Oracle Retail EFTLink Security Guide.
* Tender Retail - Tender Retail.
Note: Speak with your Oracle product representative if you plan to

use Xstore Payment as the authorization platform.
93. Click Next.

- If you selected EFT Link as the authorization platform, continue with step 95.
- If you selected Tender Retail as the authorization platform, continue with the
next step.
94. Enter the Tender Retail authentication configurations:
a. Tender Retail Dial Host URL: URL for Tender Retail.

Install RTLog Generator
b. Merchant Number: Merchant ID number used by Tender Retail.

c. Terminal ID: Terminal ID used by Tender Retail.
95. Click Install.
Xstore Point of Service installs.
96. When the Xstore Point of Service installation completes, click Exit.
Xstore Point of Service starts and will likely fail during startup.
97. Open a file manager.
98. Navigate to the GenKeys installation directory (configured in step 3).
99. Navigate into the res\keys directory in the GenKeys folder.
100.Copy the following files folder to the res\keys directory in the Xstore Point of
Service installation folder (configured in step 39).
- ccenc.*.cip
- config.*.cip
- pinfo.*.cip
- rcpt.*.cip
101.Create a backup directory in the Xstore Point of Service database folder (see
step 39.b).
102.If necessary, change the users and/or passwords in the database software to the
values entered in step 78, step 80, step 82, and step 86.
Install RTLog Generator

If you are integrating Xstore Point of Service with Oracle Retail Sales Audit, you must
install RTLog Generator. This procedure is found in the Oracle Retail Xstore Point of
Service 17.0/Merchandising 16.0.1 Implementation Guide.
Enable Store Inventory Management (SIM) in Xstore Point of

Service
Note: See Appendix J: “Store Inventory Management Integration” for
more information about Xstore Point of Service integration with Store
Inventory Management.
If you are integrating with SIM (see step 61), do the following:
103.Uncomment the following, highlighted line in the file system.properties.
Note: This file is located in the root directory of the Xstore Point of
Service installation.
#********************************
# -- SIM
#********************************

Enable Store Inventory Management (SIM) in Xstore Point of Service
dtv.config.path.-380=:sim
104.Load items into Xstore Office and SIM databases as necessary.
Note: The inventory items in Xstore Point of Service and SIM must be
the same. Neither Xstore Point of Service nor SIM automatically
populate items in the other software.
Configure Xstore Point of Service for Retail Extension Module

If you are integrating Xstore Point of Service with RXM (see step 63), do the following:
105.Uncomment the following, highlighted line in the file system.properties.
dtv.config.path.-390=:rxm
106.If necessary, set the following configuration in the file system.properties:
Note: This configuration is only necessary if primary keys in the RXM

database include lowercase letters. By default, Xstore Point of Service
forces all primary keys to be uppercase. This configuration allows both
lowercase and uppercase letters in primary keys in the Xstore Point of
Service database.
dtv.data2.access.impl.PersistenceConstants.manageCase=false
Configure Xstore Point of Service for Address Verification Service

If you are integrating Xstore Point of Service with AVS (see step 65), do the following:
107.Download the security certificates for AVS from the following:
http://support.qas.com/qas_pro_on_demand_ssl_certificates__ws__1952.htm
108.Extract the files from the downloaded EDQ_public_keys.zip file.
109.If necessary, navigate to the extracted directory.
110.Extract the files from the EDQ public keys - ws.ondemand.qas.com.zip file.
The directory where the extracted files are found will be referred to as the
<extracted_certificate_directory>.
112.In the command prompt, navigate to the res/ssl directory in the Xstore Point of
Service home directory:
- Windows (default) - c:\xstore\res\ssl
- Linux (default) - /opt/xstore/res/ssl
113.Import the Root.crt certificate file into the .truststore file:
keytool -import -keystore .truststore -alias avsroot
-file <extracted_certificate_directory>\Root.crt
114.Import the Intermediate1.crt certificate file into the .truststore file:

keytool -import -keystore .truststore -alias avsintermed1

-file <extracted_certificate_directory>\Intermediate1.crt
115.Import the Intermediate2.crt certificate file into the .truststore file:
keytool -import -keystore .truststore -alias avsintermed2
-file <extracted_certificate_directory>\Intermediate2.crt
116.Import the ws.ondemand.qas.com.cer certificate file into the .truststore file:
keytool -import -keystore .truststore -alias qas -file
<extracted_certificate_directory>\ws.ondemand.qas.com.cer
117.Uncomment the following, highlighted lines in the file system.properties.
dtv.config.path.-425=:qas
dtv.config.path.-450=:avs
118.Create a cust_config\version1\spring directory in the Xstore Point of Service
root directory.
119.Open a text editor (for example, emacs in Linux or Wordpad in Windows).
120.Enter the following text in the text editor:
<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:mvc="http://www.springframework.org/schema/mvc"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:util="http://www.springframework.org/schema/util"
xmlns:task="http://www.springframework.org/schema/task"
xsi:schemaLocation="
http://www.springframework.org/schema/mvc http://
www.springframework.org/schema/mvc/spring-mvc-3.2.xsd
http://www.springframework.org/schema/beans http://
www.springframework.org/schema/beans/spring-beans-3.2.xsd
http://www.springframework.org/schema/context http://
www.springframework.org/schema/context/spring-context-3.2.xsd
http://www.springframework.org/schema/util http://
www.springframework.org/schema/util/spring-util-3.2.xsd
http://www.springframework.org/schema/task http://
www.springframework.org/schema/task/spring-task-3.2.xsd"
default-init-method="init">
<context:annotation-config />

<bean id="oracleProxyAddress" class="java.net.InetSocketAddress">


<constructor-arg value="rn-proxy.oracle.com" />

<constructor-arg value="80" />
</bean>
<bean id="oracleProxy" class="dtv.servicex.impl.XstoreProxy">

<constructor-arg value="#{T(java.net.Proxy.Type).HTTP}" />
<constructor-arg ref="oracleProxyAddress" />
<constructor-arg value="ws2.ondemand.qas.com" />
</bean>

<bean id="proxySelector"
class="dtv.servicex.impl.CustomProxySelector" init-method="init"/>
</beans>
121.If necessary, change the proxy address to a location closer to you:

<constructor-arg value="rn-proxy.oracle.com" />
122.Save the file as proxySelector.xml in the cust_config\version1\spring
directory created in step 118.
Enable Networked Cash Drawers

If you are using networked cash drawers in your implementation of Xstore Point of
Service, the cash drawers need to be enabled:
123.Add the following configuration to the system.properties file:
dtv.config.path.10000=:ipcashdrawer:version1/hardware/
cashdrawer-apg-486-ETHERNET:localconfig
Note: This assumes that the system is connecting to an APG

networked cash drawer. Speak with your Oracle product
representative to connect to a different networked cash drawer.
124.Add the encrypted cash drawer credential to the system.properties file:

dtv.hardware.cashdrawer.networked.credentials=
<encrypted_credential>
where:
<encrypted_credential> is the encrypted value (using the String Encrypter Utility)
for the following credential string:
a5003c5f8bee76b19e512b8c7cdec4089188d5e60b302aaf95a463291b568e567
66755bf8a6fa21aa257a934aca57e25388d92b67c410fc63d082ec1a2e211e313
74b8fb458199745608be1da15ed1f67b0b2b788c4110fd5ec38000139c6b5c3b4
26975dd6c421dcba8cd4f1ca23eacafa491ef23a0460065c0afda92dc29067f56

Install Xservices
a14853e3f73eb9b315c2cbe139ae9d438671f0c5ac00f9643524773989187aec1
77b962769c1a44b2ad16f3970cb3f1abfe02400b1c451d22c8b68b6efb9041717
844bd5b7493e059aefe657acb7e973e0560ab5361678bc45a7add88e77aeb668c
0a2396e8a4fe5486051534e3569b59a2c31352b62ba2ff5db890d8721fc2b4641
1ee27169
Install Xservices
Perform the following steps to customize the settings for the installation. The GUI
screens are used to capture settings, and the resulting properties are captured in the
ant.install.properties file.
1. Copy the folder to a temporary location (Recommended).
2. In a Command Prompt, navigate to the folder where the installer is located and type
the following command:
c:\jre\bin\java -jar xservices-B.B.B.B-V.V.V-P.P-CCC-
xservices.jar GUI
Note: During the installation, if you need to change the information

entered in a previous screen, click the “Back” button to return to a
prior screen. If, at any point, you must stop the installation, click the
“Cancel” button. You will be prompted to confirm the cancellation.
Click the “Yes” button to cancel the installation and exit the GUI.

1. The first prompt provides general information about the install process. Click Next
to continue.
2. Verify/specify the Xservices Installation Location, then click Next.
Tip: Use c:\xservices. for Windows and /opt/xservices for

Linux.
3. Verify/specify the Location Settings, then click Next.

a. Customer ID: Customer ID used by Xstore Point of Service.
Important: If you are using a customer ID other than the default, you

Install Xservices
b. Customer ID salt: Salt value used when creating certificates.
must create and apply a customer overlay to your project.
c. Organization ID: Organization ID used by Xstore Point of Service.

d. Xservices organization ID: Organization ID used by Xservices.
e. Xcenter organization ID: Organization ID used by Xstore Office.
Note: The three organization IDs should be the same value.
f. Store #: Store number used by Xstore Point of Service.

g. Currency: Three-letter identifier for the default currency used by Xstore Point of
Service.
4. Verify/specify the Additional Settings, then click Next.
a. Xservices log path: The location, within the Xservices installation directory
(step 3), where Xservices will create log files.
b. Replication enables: Indicates whether replication is enabled.
c. Database connection factory class: The Java class used by the database
connection factory.
5. Verify/specify the Primary Database settings, then click Next.
a. Database URL: Connection string defining the location of the primary Xstore
Point of Service database.
b. Encrypted Username: Encrypted username used to log into the primary Xstore
Point of Service database. Use the String Encrypter Utility to encrypt this value.
c. Encrypted Password: Encrypted password used to log into the primary Xstore
6. Verify/specify the Local Database settings, then click Next.
a. Database URL: Connection string defining the location of the local Xstore Point
of Service database.
b. Encrypted Username: Encrypted username used to log into the local Xstore
c. Encrypted Password: Encrypted password used to log into the local Xstore
7. Verify/specify the Replication Database settings, then click Next.
a. Database URL: Connection string defining the location of the Xstore Point of
Service replication database.
b. Encrypted Username: Encrypted username used to log into the Xstore Point of
Service replication database. Use the String Encrypter Utility to encrypt this value.
c. Encrypted Password: Encrypted password used to log into the Xstore Point of
Service replication database. Use the String Encrypter Utility to encrypt this value.

Install Xservices
8. Verify/specify the Store Backup Database settings, then click Next.
Note: Store Backup Database is not supported in base Xstore Point of

Service.
a. Database URL: Connection string defining the location of the Xstore Point of
Service backup database.
b. Encrypted Username: Encrypted username used to log into the Xstore Point of
Service backup database. Use the String Encrypter Utility to encrypt this value.
c. Encrypted Password: Encrypted password used to log into the Xstore Point of
Service backup database. Use the String Encrypter Utility to encrypt this value.
9. Verify/specify the Xstore Office Data Source settings, then click Next.
Note: The passwords were defined during the application server

installation.
a. URL: URL for Xstore Office.

b. Hostname: Hostname for Xstore Office.
c. Port: Port for Xstore Office.
d. User name: Encrypted user name used to log into Xstore Office. Use the String
e. Password: Encrypted password used to log into Xstore Office. Use the String
f. Keystore file: Xservices keystore file.
g. Keystore password: Encrypted password for the Xservices keystore file. Use the
h. Truststore file: Xservices truststore file.
i. Truststore password: Encrypted password for the Xservices truststore file. Use
10. Verify/specify the Customer Engagement Configuration settings for connecting to
Customer Engagement Cloud Service, then click Next.
a. Hostname: Hostname for Customer Engagement Cloud Service.
b. Port: Port for Customer Engagement Cloud Service.
c. Customer ID: Customer ID used in Customer Engagement Cloud Service.
d. Protocol: Protocol used to connect to Customer Engagement Cloud Service.
e. Auth password: Encrypted password used to authorize to Customer
Engagement Cloud Service. Use the String Encrypter Utility to encrypt this value.
f. Auth token name: Token name used to authorize to Customer Engagement
Cloud Service.
11. Verify/specify the Order Broker Configuration settings used to connect to Order
Broker Cloud Service, then click Next.
a. Order Broker enabled?: Determines whether Xservices will connect to Order
Broker Cloud Service.

Install Xservices
b. Order Broker WSDL URL: URL for the Order Broker Cloud Service WSDL.
c. Order Broker user name: Encrypted user name used to connect to Order Broker
d. Order Broker password: Encrypted password used to connect to Order Broker
12. Verify/specify the Authorizations settings, then click Next.
a. Host 1: Connection string used to connect to the first authorization host.
b. Host 2: Connection string used to connect to the second authorization host.
c. Xpay user name: Encrypted user name used to connect to the Xpay server. Use
d. Xpay password: Encrypted password used to connect to the Xpay server. Use the
Important: Integration with Xpay requires setting up an overlay and

writing custom code.
e. Credit Merchant Terminal ID: Terminal ID for credit transactions.

f. Credit Merchant Number: Merchant number for credit transactions.
g. Credit Client ID: ID of the credit client.
h. Gift Card Merchant Number: Merchant number used for gift card transactions.
i. Gift card terminal ID: ID of the terminal used for gift card transactions.
j. Gift card client ID: ID of the client used for gift card transactions.
k. Organization ID: Organization ID used for authorizations.
13. Verify/specify the Receipt Printer settings, then click Next.
a. Printer port name: Name of the printer port.
b. Printer name: Name of the printer.
14. Verify/specify the Email configuration settings, then click Next.
a. SMTP host: Host name of the SMTP server.
b. SMTP port: Port for the SMTP server.
c. SMTP auth: Determines whether authorization is required by the SMTP server.
d. SMTP user: Encrypted username for the SMTP server. Use the String Encrypter
Utility to encrypt this value.
e. SMTP password: Encrypted password for the SMTP server. Use the String
15. Click Install Services to begin the installation process.
16. When the install is complete, exit the installer to close the window.
17. Open a file manager.
18. Navigate to the GenKeys installation directory (configured in step 3).
19. Navigate into the res\keys directory in the GenKeys folder.
20. Copy the following files to the xservices-config/res/keys folder.

Install Xservices
- ccenc.*.cip
- config.*.cip
- pinfo.*.cip
- rcpt.*.cip
21. Import the client certificate for Xstore Office into xservices-config/res/ssl
by copying the .truststore file from xstore\res\ssl to xservices-
config\res\ssl.
22. Perform the certificate generation steps for xservices and place the keystore file in
the xservices-config folder. (See Appendix B: “Public Key Certificates”).
23. Create an obfuscated password for Jetty:
a. Open a Command Prompt and navigate to the xservices folder
(c:\xservices).
b. Run the following command, substituting <version> with the version of the
Jetty password obfuscation utility and replacing <keystore password> with
the password you want to use:
c:\jre\bin\java -cp lib\jetty-util-<version>.jar
org.eclipse.jetty.util.security.Password <keystore password>
c. The output of that command will look like this (if the password is
allgoodthings):
allgoodthings
MD5:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
d. Copy the string on the line starting with OBF: (including OBF) into three places
in jetty-ssl.xml (C:\xservices-config):
* Password
* KeyPassword
* TrustPassword
<Configure class="org.eclipse.jetty.server.Server" id="Server">
<Call name="addConnector">
<Arg>
<New class="org.eclipse.jetty.server.ServerConnector">
...
<Arg name="sslContextFactory">
<New
class=
"org.eclipse.jetty.util.ssl.SslContextFactory"
id="sslContextFactory">
...

Install Xservices
<Set name="KeyStorePassword">
</Set>
<Set name="KeyManagerPassword">
</Set>
...
</New>
...
e. Save the changes.
Login Configuration
After installing Xservices, you will need to configure the login information used to
connect to Xservices:
24. Create an SHA512 hash of each user password:
a. Open a command prompt (for example cmd in Windows, or xterm in Linux).
b. In the command prompt, navigate to the lib directory within the Xstore Point of
Service root directory. The default location is:
* c:\xstore in Windows
* /opt/xstore in Linux
c. Enter the following command:
c:\jre\bin\java -cp dtv-password.jar
oracle.retail.xstore.passwd.impl.Ssha2Hasher
d. Enter the password to hash.
e. Copy the hashed password to someplace where it can be retrieved easily.
f. Repeat steps c-e for each password to be hashed.
25. Configure the Xservices users and passwords (see step 24) in the
sec_user_password table in the Xstore Point of Service database. See the Xstore
Point of Service Database Dictionary for information about this table.
Note: Xsersvices users must be configured directly in the database.

There is no interface for these configurations. Xservices users are
configured in the sec_user_password and sec_user_role tables.
26. Assign the ADMIN role to each Xservices user in the sec_user_role table in the
Xstore Point of Service database. See the Xstore Point of Service Database Dictionary for
more information about this table.
27. Navigate to the Xservices root directory configured in step 2.
28. Enter the etc directory.
29. Edit the login.conf file in a text editor (for example, Wordpad or emacs).
30. Set the following configurations:

Install Xenvironment
- passwordProvider - The database flavor for a password provider. The

recommended setting is
com.micros_retail.xservices.login.DatabaseUserPasswordProvider.
- passwordVerifier - The password verifier. The recommended setting is
com.micros_retail.xservices.login.XservicesPasswordVerifier.
- passwordLifespanInDays - The number of days a password is allowed to be
active.
- passwordFailureLockoutLifespanInMinutes - The number of minutes that a
user will be locked out of the system after a defined number of consecutive,
incorrect password entries.
- passwordFailuresAllowed - The number of consecutive times a user is allowed
to enter an incorrect password before that user is locked out for a defined
number of minutes.
- passwordHashers - The list of password hashers. The recommended value is
oracle.retail.xstore.passwd.impl.Ssha2Hasher.
- passwordHasherSetImpl - The default hasher set implementation. The
recommended value is
oracle.retail.xstore.passwd.impl.DefaultPasswordHashSet.
To install Xenvironment:
2. Navigate to the xenvironment directory extracted from the
OracleRetailXstorePointofService_X_X_X_X_CCC_V_V_V.zip file. See “Xstore Point
of Service Installation .zip File” in Chapter 4, “Prerequisites for Installing Xstore
Point of Service” for more information.
3. Run the Xenvironment installer in GUI mode:
c:\jre\bin\java -jar xenvironment-X.X.X.X.XXX-V.V.V-P.P-CCC-
install.jar GUI
where:
- P.P is the patch release version
The installation GUI opens.
4. Click Next.
5. Select the installation options:
a. Select an installation directory: Select the directory where Xenvironment will
be installed.
b. Register Type: Type of register:
* Lead Workstation/Server - A fixed register in a retail (that is, non-grocery)
store, or a back office server that serves as the lead register.

* Non-lead Workstation - A fixed register in a retail (that is, non-grocery)

store that does not serve as a lead register.
* Thin Client Workstation - A workstation that runs the thin client version of
Xstore Point of Service Mobile.
* Lane Check Out Workstation - A fixed register in a grocery store.
* Windows Tablet - A Windows tablet that serves as a mobile register.
c. Enable Integrated Polling: Determines whether Xenvironment will poll data
directly to an HTTP server.
d. Touch screen support: Indicates whether Xenvironment should include
touchscreen options (such as an on-screen keyboard).
Important: Some languages require multiple keystrokes to enter

individual characters. These include languages that use double-byte
characters, such as Chinese, Japanese, and Korean. Other languages—
such as Spanish, Portuguese, and German—use character annotations
(for example, accents or umlauts) that require multiple keystrokes to
enter one character. In this guide, these are referred to as multi-
keystroke characters.
While these characters are supported in Xstore Point of Service and

Xstore Office, the on-screen keyboard for Xstore Point of Service does
not support the entry of multi-keystroke characters.
Languages that use multi-keystroke characters must use a physical

keyboard for data entry. The virtual keyboard does not support
entering these characters.
e. Install UI Plugins: Determines whether UI plugins will be installed on

Xenvironment.
f. Enable Xenvironment UI: Determines whether the Xenvironment user interface
will be enabled.
6. Click Next.
7. If the directory does not currently exist, click Yes when prompted whether to create
the directory.
8. Enter the system information:
a. Lead Register Hostname: Hostname of the lead register.
b. Organization ID: ID for the organization used by Xstore Point of Service.
c. Store #: ID number of the store.
d. Register #: ID number of the register.
e. Store Name: Name of the store.
f. Helpdesk Phone Number: Phone number for the help desk.
g. Country: Country where the workstation is located.
h. Language: Default language for workstation users.
9. Click Next.

10. Enter the System Information:

a. Xstore Present?: Indicates whether Xstore Point of Service will run on the local
system.
b. Xstore Handheld Present?: Indicates whether an Xstore Point of Service Mobile
server will run on this system and handheld devices will be connecting to it.
c. Xstore Tablet Present?: Indicates whether an Xstore Point of Service Mobile
server will run on this system and tablet devices will be connecting to it.
d. Xstore Thin Client Present?: Indicates whether an Xstore Point of Service
Mobile server will run on this system and thin client devices will be connecting
to it.
11. Click Next.
12. Indicate whether a database is present:
- Yes - There is a database installed on this system.
- No - There is no database installed on this system.
13. Click Next.
- If you selected Yes in step 12, continue with the next step.
- If you selected No in step 12, continue with the step 16.
14. Enter the SID of the Oracle database or the Instance name of the SQL Server
database.
15. Enter the StorePrimary Data Source Settings:
- Store Primary Hostname: Hostname for the Xstore Point of Service database
server.
- Store Primary Database Name: Name of the Xstore Point of Service database.
- Encrypted Username: Encrypted username used to log into the database. See
Appendix A: “String Encrypter Utility” for more information.
- Encrypted Password: Encrypted password used to log into the database. See
Appendix A: “String Encrypter Utility” for more information.
16. Click Next.
- If you selected Enable Integrated Polling in step 5, continue with the next step.
- If you did not select Enable Integrated Polling in step 5, continue with step 19.
17. Enter the Integrated Xenvironment Polling configurations:
a. URL: URL for the web server (not produced by the utility).
b. Encrypted Username: Encrypted username for the web server. See Appendix A:
“String Encrypter Utility” for more information.
c. Encrypted Password: Encrypted password for the web server. See Appendix A:
“String Encrypter Utility” for more information.
18. Click Next.
19. Enter the Security Parameters for Xenvironment:
a. Client Code: Unique ID for the client (assigned by Oracle).
b. Salt: Enter the salt value. See Appendix A: “String Encrypter Utility” for more
information.

Configure Xenvironment for Thin Client
c. Encrypted Keystore Password: Encrypted password for the Xenvironment

keystore. See Appendix A: “String Encrypter Utility” for more information.
20. Click Next.
21. Click Install Xenvironment.
Xenvironment installs.
22. Click Exit when Xenvironment finishes installing.
23. If necessary, create the certificates for Xenvironment. See “Xenvironment
Certificates” in Appendix B: “Public Key Certificates” for more information.
24. Perform the procedure “Install Certificates for Xenvironment-Xstore Point of Service
Communication”.
25. If you are running the Thin Client version of Xstore Point of Service, perform the
procedure Configure Xenvironment for Thin Client.
Install Certificates for Xenvironment-Xstore Point of Service

Communication
26. Copy each .truststore file from c:\xstore\res\ssl and
c:\environment\res\ssl and place them on all other registers in the store, in
the same directory locations.

If you are running the Thin Client version of Xstore Point of Service, you must configure
the system to run Xenvironment:
Note: See your Windows documentation for assistance with this

procedure.
27. Log in as the user that runs Xstore Point of Service.

28. Open the Windows Registry Editor.
29. Go to the following registry location:
HKCU\Software\Microsoft\Windows\CurrentVersion\Run
30. Create a new registry String key.
Note: The name of the key can be anything you like.
31. Set the value of the new registry key to the following:
c:\windows\system32\wscript.exe //B
c:\environment\start_eng.vbs
32. Configure Assigned Access to launch Xstore Point of Service Mobile for the user:
a. Open Settings as an administrator.
b. Open Accounts in the Settings window.
c. Open Family & Other People.
d. Open Set up assigned access.

e. Select the user that will run the Xstore Point of Service.
f. Select the Xstore Point of Service Mobile application.
g. Click OK.
The Xstore Point of Service Mobile application will open automatically when the
assigned user logs in.
Run Xenvironment as a Service

If you are planning to run Xenvironment as a background service, rather than as a shell,
perform the steps for your operating system:
• Windows
• Linux (systemd)
• Linux (init.d)
Windows
1. Stop Xenvironment, if necessary.
2. Navigate to the cust_config\version1 directory in the Xenvironment directory.
Note: C:\environment\cust_config\version1 is the default

location of this directory.
3. Open environment.properties in a text editor (for example, Notepad or

Wordpad).
4. Add the following line to the environment.properties file:
environment.gui.disabled=True
5. Save and close the file.
6. Open a command prompt as an administrator (for example, cmd).
7. In the command prompt, navigate to the Xenvironment directory.
Note: C:\environment is the default Xenvironment directory.

start_eng.bat install
9. Open the Control Panel.
10. Open the Services window.
Note: The location of the Services window depends upon your

version of Windows, and the configuration of your system. See
Windows help for more information.
11. Find the engine service.

12. Right-click the engine service to open the menu.
13. Click Properties in the menu.

14. Click the Log On tab.

15. Click the This account radio button.
16. Enter xstore as the user name.
17. Enter the Password for the xstore user.
18. Re-enter the Confirm Password for the xstore user.
19. Click OK.
20. Reboot the system or start the service in the Services window.
21. Check for the xenv_eng.anchor and xenv_eng.pid files in the Xenvironment
tmp directory.
Note: C:\environment\tmp is the default location of this directory.
If both of these files are present, Xenvironment is running.
Linux (systemd)
If your Linux system uses the /etc/systemd directory for services, do the following:
2. Navigate to the directory where Xenvironment is installed.
Note: /opt/environment is the default Xenvironment directory.
3. Open a text editor (for example, emacs or vi).

4. Enter the following in the text editor:
[Unit]
Description=Oracle Xstore Point of Service Environment Engine
[Service]
Type=forking
ExecStart=/opt/environment/start_eng.sh 'start'
ExecStop=/opt/environment/start_eng.sh 'stop'
ExecReload=/opt/environment/start_eng.sh 'restart'
[Install]
WantedBy=multi-user.target
5. Save the file as /etc/systemd/system/xenv_eng.service.
6. In a terminal window, enter the following command:
systemctl enable xenv_eng.service

7. Navigate to the cust_config/version1 directory in the Xenvironment directory.
Note: /opt/environment/cust_config/version1 is the

default location of this directory.
8. Open environment.properties in a text editor (for example, emacs or vi).

9. Add the following line to the environment.properties file:
environment.gui.disabled=True
10. Reboot the system.
11. Check for the xenv_eng.anchor and xenv_eng.pid files in the Xenvironment
tmp directory.
Note: /opt/environment/tmp is the default location of this

directory.
If both of these files are present, Xenvironment is running.
Disable Running Xenvironment as a Service

1. Change user to root using the following command:
sudo -s
2. Execute the following command:
systemctl disable xenv_eng.service
3. Reboot the system with the following command:
shutdown -r now
4. After the system reboots, ensure the following files do not exist:
- /opt/environment/tmp/xenv_eng.anchor
- /opt/environment/tmp/xenv_eng.java.pid
If these files do not exist, Xenvironment is not running.
Linux (init.d)
If your Linux system uses the /etc/init.d directory for services, do the following:
2. Open a text editor (for example, emacs or vi).
3. Enter the following into the text editor:
#!/bin/sh
# /etc/init.d/xenv_eng
#
# System startup script for Xenvironment Point of Service
engine service/daemon
#
### BEGIN INIT INFO

# Provides: xenv_eng
# Required-Start: $null
# Required-Stop: $null
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Xenvironment engine daemon
# Description: Start Xenvironment engine as a daemon
### END INIT INFO
case "$1" in
start)
su xstore -c '/opt/environment/start_eng.sh start'
;;
stop)
su xstore -c '/opt/environment/start_eng.sh stop'
;;
restart)
$0 stop
$0 start
;;
status)
su xstore -c '/opt/environment/start_eng.sh status'
;;
*)
echo "Usage: $0 {start|stop|status|restart}"
exit 1
;;
esac
4. Save the file as /etc/init.d/xenv_eng.
sudo chown xstore /etc/init.d/xenv_eng
6. Set the file permission to 750 with the following command:
sudo chmod 750 /etc/init.d/xenv_eng
7. Change user to root with the following command:
sudo -s
chkconfig --set xenv_eng on

Xstore Point of Service Mobile Installation on Device

shutdown -r now
10. After the system reboots, check whether the following files exist:
- /opt/environment/tmp/xenv_eng.java.pid
If these files exist, Xenvironment is running.
Disable Running Xenvironment as a Service

1. Change user to root using the following command:
sudo -s
chkconfig --set xenv_eng off
shutdown -r now
4. After the system reboots, ensure the following files do not exist:
- /opt/environment/tmp/xenv_eng.pid
If these files do not exist, Xenvironment is not running.

If you are installing Xstore Point of Service Mobile, you will need to install the package
on the mobile device.
Run the package installation procedure for your device’s operating system:
• iOS
• Android
iOS
Installation of Xstore Point of Service Mobile on an iOS device requires the use of mobile
device management (MDM) software:
1. Use your MDM software to install the prepared Xstore Point of Service Mobile on
the device(s). See Build an Xstore Point of Service Mobile Client Application (iOS
Only) in Chapter 4, “Prerequisites for Installing Xstore Point of Service” for more
information.
2. Install the certificate authority on the device:
a. Create a cacert.cer certificate:
i) On a Mac, double-click the cacert.pem file (see cacert.pem in Appendix B:
“Public Key Certificates”).
ii) The cacert.pem files opens in Keychain Access.
iii) Right click the cacert.pem file in Keychain Access.
iv) Export the file as a .cer file.
A cacert.cer file is created.

b. Open Apple Configurator 2.

c. Create a profile in Apple Configurator 2 that includes the cacert.cer file
certificate.
d. Add the profile to the iOS device (using Apple Configurator 2).
Note: It is recommended you save the profile so that other devices

can use it to connect to the Xstore Point of Service Mobile server.
3. If the iOS device is running iOS 10.3 or later, do the following:

a. Open Settings.
b. Click General in Settings.
c. Click About.
d. Click Certificate Trust Settings.
e. Find the certificate in the list of certificates.
f. Set the certificate to Trusted.
4. Run Xstore Point of Service Mobile on the mobile device. Continue with Configure
Xstore Point of Service Mobile.
Android
Create and Install SSL Certificates

1. If necessary, create the SSL certificates for the Xstore Point of Service Mobile server
and Xstore Point of Service Mobile device. See Appendix B: “Public Key
Certificates”.
2. Install the SSL certificate on the device.
- CA-Signed Certificate - Install a certificate signed by a certificate authority.
- Self-Signed Certificate - Install a self-signed certificate.
- If you are installing Xstore Point of Service Mobile on an iOS device, you must
use a certificate signed by a certificate authority. See CA-Signed Certificate.
Xstore Point of Service Mobile will not work on iOS with a self‐signed certificate.
CA-Signed Certificate
1. Copy the provided certificate file to the storage of the Android device. If you used the
certificate creation process Certificate Authority‐Signed Certificates: Xstore Point of Service
Mobile, in Appendix B: “Public Key Certificates”, this is the cacert.pem file.
2. If necessary, change the extension of the file from .pem to .cer.
3. Open the device’s security menu.
4. In the security menu of the Android device, enable a face unlock, pattern, PIN, or
password lock screen.
5. In security menu of the Android device, select the Install from storage option and,
when prompted for the name, select the file that was copied to the device's storage.
Self-Signed Certificate
1. Export the certificate from the keystore file by typing the following command:

keytool -export -alias xstoremobile-YYYYMMDD -keystore

xstoremobile.keystore -rfc-file xstoremobile-YYYYMMDD.cer
2. Copy the xstoremobile-YYYYMMDD.cer file to the storage of the Android device.
5. In security menu of the Android device, select the Install from storage option and,
when prompted for the name, select the file that was copied to the device's storage.
Install the package using one of the methods below:
• If you are using mobile device management (MDM) software:
a. Use your mobile device management software to install Xstore Point of Service
Mobile on the device(s).
b. Run Xstore Point of Service Mobile on the mobile device. Continue with
Configure Xstore Point of Service Mobile.
• If you are not using MDM software:
a. Connect to the device using a USB cable.
b. Copy the .apk file onto the device.
c. Use an Android software installation program to install the .apk file.
d. Continue with Install and Configure DataWedge.
Install and Configure DataWedge

If you are installing Xstore Point of Service Mobile on an Android device, configure
DataWedge:
1. Install DataWedge, if necessary. DataWedge should already be installed on the Zebra
MC40, Zebra TC70, or Zebra ET55
2. Open DataWedge.
3. Continue with Create and configure a new profile in DataWedge.
Create and configure a new profile in DataWedge

To create and configure a new profile in DataWedge:
1. Select the context menu button.
2. Select New profile.
3. Enter Xstore.
4. Select OK.
5. Select the profile.
6. If necessary, enable the profile. (Default)
7. If necessary, enable barcode input in the profile. (Default)
8. Select Decoders.
9. Enable the following decoders (do not disable any enabled decoders):
- UPC-A (Default)
- Code 128 (Default)

- Code 39 (Default)
- QR Code (Default)
- Code 93
10. Exit the barcode decoder screen to return to the profile screen.
11. If necessary, enable MSR input. This option is not available on the Motorola TC70.
Continue with Associate the profile with Xstore Point of Service Mobile.
Associate the profile with Xstore Point of Service Mobile

To associate the profile with Xstore Point of Service Mobile:
1. Select Associated apps.
3. Select New app/activity.
4. Select com.oracle.retail.xstore.
5. Select com.oracle.retail.xstore.Xstore.
7. Select New app/activity.
8. Select com.oracle.retail.xstore.
9. Select *.
10. Exit the XstoreM application associations screen and return to the profile screen.
11. Continue with Enable intent actions.
Enable intent actions

To enable intent actions in the profile:
1. Enable Intent Output.
2. Select Intent action.
3. Enter ppScan.
4. Select OK.
5. Select Intent category.
6. Enter android.intent.category.DEFAULT.
7. Select OK.
DataWedge configuration is complete.
8. Exit DataWedge.
9. Run Xstore Point of Service Mobile and continue with Configure Xstore Point of
Service Mobile.
Configure Xstore Point of Service Mobile

To update the configurations on Xstore Point of Service Mobile after installation:
• On a handheld device: Swipe to the left on the image on the main page.
• On a tablet: Long-press the Oracle logo on the bottom right of the app.

The Server Configuration screen opens.

Configuration of Xstore Point of Service Mobile includes the following procedures:
• Server Configuration
• Location Configuration
Configure Xstore Point of Service Mobile

Configuration of Xstore Point of Service Mobile includes the following procedures:
• Server Configuration
• Location Configuration
Server Configuration
Enter the server configuration information on the device:
1. Enter the hostname or IP address for the Xstore Point of Service Mobile server.
2. Enter the server port:
- Handheld: Enter 8443.
- Tablet: Enter 8543.
- Thin Client: Enter 8643.
3. Select Test Connection to test the connection to the server.
- If the test is successful, continue the procedure.
- If the test fails, check the hostname and port, and the network connection.
4. If necessary, perform Location Configuration.
5. Select Save.
6. Configuration is complete.
Location Configuration
To configure the location information in Xstore Point of Service Mobile:
1. Select Location Details in the configuration screen.
2. Enter the store number.
3. Enter the register number.
4. Select Save.
5. Ensure the device is enabled in Xstore.
6. Select Save.
7. Xstore Point of Service Mobile returns to the Server Configuration screen.
Additional Configuration
Additional configuration of Xstore Point of Service Mobile is performed through the
back office component of Xstore Point of Service.

For initial configuration, or whenever changing the Register number, a pop-up message
appears with a token.
The server will initially block a device from running Xstore Point of Service Mobile until
an administrator goes into a new function (Mobile Client Device Access) within Manage
Hardware in Xstore Point of Service’s Back Office to enable the newly configured device.
Administrators can also use this new function in Xstore Point of Service’s Back Office to
disable access to any currently enabled mobile device.
See also the Xstore Point of Service Manager’s Guide for more information about these
configurations.

Functional Settings
Inventory
• Prompt For a Quantity After Manual Entry Of An Item? - Determines whether
Xstore Point of Service and Xstore Point of Service Mobile will prompt for a quantity
after a user enters an item ID.
• Prompt For a Quantity After Scanning An Item? - Determines whether Xstore Point
of Service and Xstore Point of Service Mobile will prompt for a quantity after the
user scans an item.
Inventory Count
• Enable Count Sheet Mode? - Determines whether count sheets are used in
inventory counts. This must be set to False for any implementation using Xstore Point of
Service Mobile.
Item Options
• Show item images? - Determines whether images will be shown for items in Xstore
Point of Service Mobile.
Security Settings
Xstore Point of Service Mobile also uses the following user security settings for Xstore
Point of Service:
• Search Inventory Count - Permission to search for inventory counts.
• Create Inventory Count - Permission to create inventory counts.
• Complete Inventory Count - Permission to complete inventory counts.
• Cancel Inventory Count - Permission to cancel inventory counts.
Integrate with Xcommerce

To integrate Xstore Point of Service Mobile with an Xcommerce guided selling website,
add the following configuration to the system.properties file in the root directory
for Xstore Point of Service:
dtv.config.path.XXXXXX=:xcommerce
where XXXXXX is the configuration path number.
Writing Your Xcommerce Application

In order to integrate with Xstore Point of Service Mobile, an iOS Xcommerce application
must conform to the following interface:
Note: Oracle does not provide an Xcommerce application. You must

create your own.
iOS: Outbound Call to the Xcommerce Application

The call to the Xcommerce app will have the following format:
xstorecommerce://?arg1=arg1value&arg2=arg2value
where:
• arg1 and arg2 are names of parameters sent to the Xcommerce application

• arg1value and arg2value are the values for the parameters sent to the
Xcommerce application
Note: These parameters are how data is sent to Xcommerce from

Xstore Point of Service.
An Xcommerce iOS app must register the xstorecommerce URL scheme in its
Info.plist properties file. This will tell the operating system that when Xstore
attempts to open a url that starts with xstorecommerce://, iOS will know that it
needs to launch the Xcommerce app.
The parameters passed to the Xcommerce app are initialized on the server in Spring-
configured code.
Info.plist File
Enter the following in the Info.plist file for your Xcommerce application:
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array>
<string>xstorecommerce</string>
</array>
</dict>
</array>
Desktop: Outbound Call to the Xcommerce Application

Xstore Point of Service desktop uses a Xcommerce web application instead of a third
party application. The URL of this web application is configured in the system
configuration XcommerceUrl in the SystemConfig.xml file.
Example: Configuration System.Config.xml
<XcommerceUrl dtype="String">http://localhost:8080/
Xcommerce_Demo/</XcommerceUrl>
Xstore Point of Service opens the web application in its internal browser and allows
users to interact with the Xcommerce web application.
Inbound Response from Xcommerce to Xstore Point of Service

When the Xcommerce session is complete, and control needs to be passed back to Xstore
Point of Service, the Xcommerce app needs to open a URL of the format:
xstorepos://xstorecommerce?arg1=arg1value&arg2=arg2value
where:
• arg1 and arg2 are names of parameters being sent to Xstore Point of Service from
Xcommerce

• arg1value and arg2value are the values for the parameters being sent to Xstore
Point of Service from Xcommerce
Note: These parameters are how data is returned to Xstore Point of

Service from Xcommerce.
The parameters passed back to Xstore Point of Service will be handled on the server in
the same Spring-configured code as the initial setup mentioned in the iOS: Outbound
Call to the Xcommerce Application.
IXcommerceHandler Interface
There is an IXcommerceHandler interface that a class can implement, based on the
Xcommerce application’s requirements. This interface includes methods for:
• server side parsing of any parameters to send to the Xcommerce application
• processing the parameters returned to Xstore Point of Service from Xcommerce.
public interface IXcommerceHandler {
Map<String, String> getInitialParameters();
List<XcommerceItem> processResponseData(Map<String, String>
argResponseData);
}
getInitialParameters retrieves the parameters to send to Xcommerce. This method
allows for the server-side setup of any parameters that need to be sent to the Xcommerce
application.
Note: This function is used to populate the parameters that are

inserted into the URL (see Inbound Response from Xcommerce to
Xstore Point of Service).
processResponseData does the following:

• processes the parameters that Xcommerce sends back to Xstore Point of Service
• creates a list of XcommerceItem elements for Xstore Point of Service to use when
prompting the user.
Map<String, String> is a Map where each key-value pair is a parameter to send
to the Xcommerce application. The key is the name of the parameter and the value is
the value for the parameter.
Spring Configuration
See mobile-beans.xml for how this is all put together:
xcommerceHandlerServiceFactory this uses the ServiceLocatorFactoryBean
pattern, and is wired up with an IXcommerceHandlerServiceFactory.
The xcommerceHandlerServiceFactory factory returns an IXcommerceHandler.
xcommerceHandler (DefaultXcommerceHandler) - Defines a default
implementation of the IXcommerceHandler.

Default Call to Xcommerce

A default call to Xcommerce has been provided (DefaultXcommerceHandler), which
passes a generated sessionID, and some customer information to Xcommerce.
The DefaultXcommerceHandler launches the following URL:
xstorecommerce://?sessionID={uuid}&customerID={customerID}&
firstName={firstName}&lastName={lastName}
Default Return from Xcommerce to Xstore Point of Service Mobile

A default response handler from Xcommerce to Xstore Point of Service has been
provided, which expects a session ID, and a list of items that specify an item ID, quantity,
and an optional retail type (SALE or ORDER).
When the Xcommerce application launches the following Xcommerce URL:
xstorepos://xstorecommerce?sessionID={uuid}&items={itemInfo}
where itemInfo could have the following example content:
1002~1+1003~2~SALE+1004~1~ORDER
This particular example would present the following items to the user:
• itemID=1002 with quantity=1
• itemID=1003 with quantity=2 and the retail type defaulted to SALE
• itemID=1004 with quantity=1 defaulted to ORDER
Note: The DefaultXcommerceHandler can be used as is, or as a

starting point for a customer-specific implementation.


6
About Implementing the Xstore Suite
What you need to do...

This chapter contains information about the Xstore Suite technical landscape. The
enterprise flow for your store systems will be determined and documented based on the
answers to the following questions.
First, answer a few questions about your store operations

1. What is the maximum transaction count for your busiest store on its busiest business
day?
2. In how many stores will Xstore Point of Service be installed?
3. What is the average number of registers in your stores?
4. What is the maximum number of registers within a store?
5. What is the total transaction count for your chain for a year?
Next, scope out your technical landscape

The technical landscape captures detail on the hardware and software platforms to be
implemented centrally and in stores, store and home office connectivity, and Xstore Suite
data architecture. You will work with Oracle Technical Services when determining your
needs. The following section lists the technical landscape decisions you must make in
order to implement Xstore Suite.
Xstore Point of Service System Configuration

• Hardware & Peripheral Configuration - Xstore Point of Service supports many
hardware devices and peripherals. When planning your hardware configuration,
decide whether the hardware will be deployed along with Xstore Point of Service or
if existing hardware will be reused. You will also be asked to specify the type of
cable or connection used for each device.
• Software Configuration - Xstore Point of Service has been designed on an open
platform which provides several choices for operating systems and databases. For a
list of certified platforms, refer to the Xstore Point of Service Release Notes. If you have
any questions, contact your Project Implementation Manager.
- Windows and Linux are supported operating system platforms for base Xstore
Point of Service. Other operating system platforms will require additional
services, configuration, and testing to implement.
- Oracle and SQL Server database platforms are certified and pre-configured for
base Xstore Point of Service. Other database platforms will require additional
services, configuration, and testing to implement.
About Implementing the Xstore Suite 6-1

What you need to do...
• Xstore Point of Service Mobile - This is an optional feature. Xstore Point of Service
Mobile is cross-platform, running both on Apple and Android devices using thin-
client technology, but presented with an app-like feel.
Store and Home Office Connectivity

• Network Topology - Decide what IP scheme you will be using in your stores. This
will be either a pattern that can be applied to all stores (addressing each store with
the same scheme, i.e. 192.168.1.1-254 at all stores) or a spreadsheet listing IP schemes
by store. For registers, you will need to define a machine name scheme and also
decide if registers will belong to a domain or active directory structure.
• Networking and Remote Connections - Decide how Oracle will be connecting to
home office servers and POS Labs and stores for software installation and support.
You will also need to specify what software will be used for this remote support.
Contact your Oracle representative to discuss WAN solutions for your enterprise.
Corporate Server Applications

• Oracle Enterprise Application
• Other Oracle Applications
• Polling Applications
Some questions to keep in mind when making corporate server decisions include:
1. How many servers will you implement for this app?
2. Will Oracle have a test server?
3. Will you have a test server at your office?
4. What OS version will be hosting this app?
5. Which DB platform will be used with this app?
6. Will this be in a VM environment?
Authorization Software and Setup Options

Some questions to keep in mind when making authorization decisions include:
1. What software will be used to perform authorizations from registers?
2. Will each register have authorization software installed on it?
3. Will authorization requests from the register be sent to the home office or directly to
the processor?
Xenvironment Setup Options

Some questions to keep in mind when making Xenvironment decisions include:
1. How many database backup archives do you want to keep on the register?
2. Will you need any custom Xenvironment menus?
Finally, consider the enterprise flow

After capturing the technical landscape data listed above, consider how Xstore Point of
Service will interact with different servers and software systems. See Chapter 7, “Xstore
Suite Data Architecture” to capture information about Xstore Point of Service data
architecture and design considerations, including primary data source configuration and
persistence, lookups, and replication.

Installation Requirements
Oracle project managers can work with you to determine these requirements.
When you are ready to install Xstore Point of Service, review this section to make sure
you understand what’s needed for the install and have completed any pre-install steps.
See the Xstore Point of Service Release Notes for the platforms supported in each Xstore
Point of Service version.
Prerequisites and Assumptions

Note: Installation instructions for the components listed below is
beyond the scope of this guide. Refer to the specific Operating System
product documentation and Database product documentation for
detailed information about installing these components.
The following components must be installed prior to beginning the Xstore Point of
Service install. As noted above, the instructions for installing these components are not
included in this guide.
• Operating system fully installed and configured (See “Base Operating System
Configurations”)
• Database platform fully installed and configured (See “Base Software Installation
Configurations”)
Important: Refer to the Certified Platforms section of the Xstore Point

of Service Release notes for platform and version information.
Database and Operating System Configurations

Important: Refer to Appendix D: “PCI Best Practices:
Implementation & Configuration” for detailed information about the
configuration requirements for Databases and Operating Systems.
Database Platforms: General Considerations

• Oracle and MS SQL Server:
- All user logins (successful or failed) should be logged for audit purposes.
- Complex non-default passwords should be used for all login accounts.
- Must be current with all service packs and software patches.
• Oracle:
- The Listener service must be enabled.
• SQL Server:
- The SQL Server Browser service must be enabled.
- TCP/IP connectivity should be enabled and set to listen on port 1433.
- Use the default SQL Server instance name of MSSQLSERVER if possible.

Operating Systems: General Considerations

• Windows and Linux:
- A firewall should be enabled. See “Communication Ports” for more information
about ports.
Firewall Port Exceptions:
* Oracle - 1521 <OR> SQL Server - 1433
* Xstore IPC - 9090
* Environment UI IPC - 9095
* Environment Engine - 9096
* Environment (file server) - 9097
* Xstore JMX Console - 2020
- Antivirus software should be installed.
- The non-administrative user should be used to log into the system for running
Xstore Point of Service and Xenvironment.
- The OS should be configured to record both successful and failed login attempts.
- Complex non-default passwords should be used for all login accounts.
- The application user should be logged in automatically on boot.
- Must be current with all service packs and software patches.
• Windows:
See Appendix D: “PCI Best Practices: Implementation & Configuration” for more
information.
- System restore should be disabled.
- The OS shell should be set to Xenvironment.
- The login user should be granted access to set the system time.
- The login user should be granted access to shut down/reboot the system.
Note: This is required on server Operating Systems only — client

Operating Systems allow this by default.
- The page file should be encrypted and cleared on shutdown.

- Fast user switching should be disabled.
- All of the options on the CTRL+ALT+DEL screen should be disabled (i.e. logoff,
shutdown, task manager, change password).
• Linux:
- The configurations referenced in “Install Xenvironment” of Chapter 5, “Install
Xstore Point of Service” should be in place. These configurations take care of the
following:
* The page file should be encrypted.
* Launch only Xenvironment at login.
* The OS shell should be set to Xenvironment.

Xstore Point of Service: Installation Types & Tasks
* Allow DB backups to be taken.

* Allow the system to be shut down & restarted.

more information about upgrade, update, and patch installation types.
The build/installation type will indicate the steps the installer will perform:
• Install - Installs a new Xstore Point of Service version on a clean machine. On a
system with an existing Xstore Point of Service version, it will delete the existing
version and databases and replace it with the new.
• Upgrade - Applies a new base version, updates the database, and applies the
customer overlay.
• Update - Retains the existing Xstore Point of Service version, updates the database,
and applies a new customer overlay.
• Patch - Applies critical fixes and may update the database.
The following steps will be completed based on the type of installer: Install, Upgrade,
Update, or Patch:
Table 6-1: Installer Types/Steps Performed
Step Install Upgrade Update Patch
1. Shutdown Xstore Point of

Service application
   
2. Execute scripts added to

installer
   
3. Execute customer specific

scripts (if added)
   
4. Backup previous
installation
  
5. Drop physical Xstore

Point of Service databases

6. Create physical Xstore

Point of Service databases

7. Create Xstore Point of

Service schema

8. Create customer schema 

9. Run customer base data
SQL

10. Run customer test data

SQL (in TEST mode)


Table 6-1: Installer Types/Steps Performed (continued)
Step Install Upgrade Update Patch
11. Run downloads through

DataLoader
  
12. Remove old Xstore Point

of Service version

13. Extract new Xstore Point

of Service version
  
14. Apply patch files 

15. Run customer schema
update SQL
   1
16. Run customer data

update SQL
   
17. Run baseconfigure.bat   

18. Run configure.bat   
19. Execute customer specific
scripts
  
20. Execute scripts added to

installer (if added)
   
21. Start Xstore Point of

Service application
   
1. When applicable.

Communication Ports
Communication Ports
Application Port Protocol Where? Comments
Xstore Point of 9090 HTTP Store

Service IPC over TLS
Xstore Point of 2020 HTTP Store

Service JMX over TLS
Console
Xenvironment 9095 HTTP Store This port only needs to be connectable

UI IPC over TLS within the same system to allow the
Xenvironment engine application process
to send updates to the Xenvironment UI
application process.
Xenvironment 9096 HTTP Store 9096 is the general-purpose web server. It

Engine IPC over TLS serves files and it serves endpoints for
IPC communications (commands sent to
Xenvironment, register discovery, etc.).
Xstore Point of Service, Xenvironment
UI, Engines running on other registers,
Tech support personnel via cURL, wget,
browser, etc.
Xenvironment 9097 HTTP Store 9097 is the specialized web server that's
Engine File over TLS optimized for serving files. It's 6-10 times
Server faster than downloading files from the
IPC server. Currently, the only files
downloaded via this service are the
database backups.
Xservices Web 8443 HTTP Store

Services over TLS
<OR>
Xstore Point of
Service Mobile
Server
Xstore 8443 HTTP Store & If running Xstore Payment in the store,
Payment IPC over TLS Corp the Xstore Payment ports should be
opened in the firewall on the POS system.
Xstore 8543 HTTP Store & If running Xstore Payment in the store,
Payment GUI over TLS Corp the Xstore Payment ports should be
opened in the firewall on the POS system.
Oracle Retail 8443 HTTP Corp

Xstore Office over TLS
Customer 8443 HTTP Corp

Engagement over TLS
Cloud Services
Web Services
Oracle 1521 TCP/IP Store & Store systems and Database Servers at
Corp corporate.
Leverages industry-standard JDBC driver.

Oracle Retail Xstore Point-of-Service, Lane Checkout User Interface Communication Ports
Application Port Protocol Where? Comments
SQL Server 1433 TCP/IP Store & Store systems and Database Servers at
Corp corporate.
Leverages industry-standard JDBC driver.
HTTP File 443 HTTP Corp

Server over TLS
Xstore Point of 4886 HTTP Store This port is hosted by Xstore Point of
Service Lane over TLS Service Lane Checkout User Interface
Checkout User hardware module to allow Xstore Point of
Interface Service Lane Checkout User Interface
Hardware client module to send receipts to a receipt
Module printer.
Oracle Retail Xstore Point-of-Service, Lane Checkout User

Interface Communication Ports
The communication ports listed in “Communication Ports” are also used for the Oracle
Retail Xstore Point-of-Service, Lane Checkout User Interface. In addition to the
communication ports referred to before, the following ports are used.
Table 6-1: Additional Communication Ports for the Oracle Retail Xstore Point-of-Service,
Lane Checkout User Interface
Application Port Where? Comments
Gserver 7777 Store

Communication
(Gserver -
graphical user
interface for the
Oracle Retail
Xstore Point-of-
Service, Lane
Checkout User
Interface client)
Hardware 6789 Store

Communication
Note: The listed Gserver port is only used when the network com-
munication for this component is activated. The in-memory communi-
cation is the default mode.

7
Xstore Suite Data Architecture
Primary Data Source Configuration

There are several options available for register and database setup within the store
environment. The Xstore Suite's data lookup and persistence framework may be
configured in a variety of ways to control where the application retrieves and saves data.
Choose one of the following options to determine where the primary data source will
reside in the store:
1. A Dedicated Database Server can be used as the primary source for data lookups
and persistence in the store. See “Store Server serves as store primary data source
diagram”).
<OR>
2. A Back Office Only Workstation (manager's workstation) can be used as the
primary source for data lookups and persistence in the store and run Xstore Point of
Service back office components for reporting, electronic journal viewing, payroll and
other back office functions. A back office only workstation will not have a cash
drawer attached and will not perform any register functions.
<OR>
3. A Standard Register Workstation can be used as the primary source for data
lookups and persistence in the store. The register will have all standard peripherals
attached and perform all register and back office functions, but be considered the
lead register. (See “Lead Register as store primary data source diagram”).
Note: This option is usually only appropriate for smaller stores.
4. Other 3rd Party Systems - You must specify details and provide a diagram
illustrating the configuration.
Note: Xstore Point of Service's data lookup and persistence

framework may be integrated with outside data sources. However, this
work requires custom development.
All data saved to the StorePrimary or Local data sources is replicated to Oracle Retail
Xstore Office.
Important:Oracle Retail Xstore Office runs on WebLogic, Jetty, or

Apache Tomcat.
Xstore Suite Data Architecture 7-1

Primary Data Source Configuration
Lead Register as store primary data source diagram
Store Server serves as store primary data source diagram

8
Upgrading Xstore Suite Components
Overview
InstallX is used to build and release installations of the Xstore Suite applications and
associated server-based components. This section provides instructions for using
InstallX to upgrade, update, or patch the Xstore Suite:
• Upgrade - Applies a new base version and applies the customer overlay. During an
upgrade, InstallX will re-order any unordered files. For example, base-
xstore.properties will be reformatted to include the arbitrary ordering and
comments that are included.
If there are any keys in the old base-xstore.properties that do not exist in the
new, they will be placed at the bottom of the file and commented out with a hash
("#") sign.
• Update - Retains the existing Xstore Point of Service version and applies a new
customer overlay.
• Patch - Applies critical fixes.
InstallX can invoke a call to Xenvironment to process any pending deployments during,
or shortly after, applying an update or upgrade with the required configuration.
Note: The steps in this section use the “upgrade” install type in the
commands as an example. Be sure to select the appropriate installer
type: upgrade, update, or patch for the function you want to perform.
Refer to Chapter 5, “Install Xstore Point of Service” for information about installing
Xstore Point of Service.
Upgrading Xstore Suite Components 8-1


1. Download the Xstore Point of Service .zip installation files for your system from the
Note: The download files for Windows have parts 1 and 2. It is

recommended that you download both files. Xstore Point of Service
installations that use an Oracle database require both .zip files.

4. This will create the files and directories that are in the <root_directory>.
<root_directory>
Xstore Point of Service installation files.
artifacts
Build artifacts.

There are a set of package directories for Xstore Point of Service, each of which contain
installation files for a particular system. Use the correct package directory for your
installation. See “Installation File Directories” for more information about these
directories.

Xstore Point of Service package for your install.
database that uses pluggable databases. Contains Point-of-Service Installation .zip Files.

Contains Point-of-Service Installation .zip Files.
SQL Server database that does not use Unicode characters. Contains Point-of-Service
Installation .zip Files.

SQL Server database that uses Unicode characters. Contains Point-of-Service Installation
.zip Files.
Point-of-Service Installation .zip Files

OracleRetailXstorePointofService_X_X_X_X_X_CCC_V_V_V.zip
X.X.X.X.XXX_V.V.V
where:
• X.X.X.X.XXX is the version and build number
• V.V.V is a customer release version
pos
Installation files for the Xstore Point of Service software. This includes the following
subdirectory:
• mobile - Installation files for Xstore Point of Service Mobile.
xservices
Installation files Xstore Point of Service web services.
xenvironment
Installation files for Xenvironment.
genkeys
Installation files for the GenKeys utility. This includes the string encryption utility (see
Appendix A: “String Encrypter Utility”) used to encrypt information in the installation
procedure, and generates security keys for use by Xstore Office.
jrepackager
Creates a JRE .zip file used by the installation procedure.

Update/Upgrade Instructions in this section
Update/Upgrade Instructions in this section

The steps in this section use the “upgrade” install type in the commands as an example.
Be sure to select the appropriate installer type: upgrade, update, or patch for the function
you want to perform.
To get started, unzip the InstallX package, then continue with the steps below.

If you are upgrading from an earlier version of Xstore Office, you must upgrade from
JRE 7 to JRE 8.
Xstore Point of Service

“Xstore Point of Service Upgrade - Manual Application”
“Xstore Point of Service Upgrade - Using Xenvironment”
Oracle Retail Xstore Office

“Oracle Retail Xstore Office Upgrade”
DataLoader
“Dataloader Upgrade”
POS Log Generator

“POS Log Generator Upgrade”
Xenvironment
“Upgrading Xenvironment”
Xstore Point of Service Installer: File Naming Conventions

The following naming convention will be used throughout the Upgrade Instructions in
this section.
xstore-B.B.B.B-V.V.V-P.P-CCC-pos-TYPE.jar
Where...
B.B.B.B is the base release version
V.V.V is the customer release version
P.P is the patch release version
CCC is the three-letter customer ID
pos is the app name
TYPE is the installer type (install, upgrade, update, patch)

Xstore Point of Service Upgrade - Manual Application
Xstore Point of Service Upgrade - Manual Application

Tip: To quickly open a Command Prompt in the folder location, see
“Opening a Command Prompt in a Location”.
To auto-complete the file name, simply type c:\jre\bin\java

-jar xstore
then press the [Tab] key to complete the file name.
1. Open the pos subdirectory.

2. In a Command Prompt navigate to the folder where the installer is located and enter
c:\jre\bin\java -jar xstore-B.B.B.B.B-V.V.V-P.P-CCC-pos-
upgrade.jar
Xstore Point of Service Upgrade - Using Xenvironment

1. Copy xstore-B.B.B.B.B-V.V.V-P.P-CCC-pos-upgrade.jar to
c:\updates\inbox\xstore
2. Add a file called update.ok to the c:\updates\inbox\xstore directory.
Note: The update.ok file serves as a flag file, meaning that its
presence is checked, not its contents. (The contents of this update.ok
file are irrelevant). The update.ok flag file will be deleted during the
update process.
3. Perform a store close.
Oracle Retail Xstore Office Upgrade

WebLogic
Upgrading Xstore Office on WebLogic is done through a WebLogic deployment web
interface. See the WebLogic documentation for information about deploying .war files.
Jetty or Tomcat
Note: If using Tomcat rather than Jetty, simply substitute Tomcat for
the Jetty locations shown in the procedure.
If using Tomcat, you must rename the xcenter and xadmin war files to
xcenter.war and xadmin.war.
By default, the names of these files include build number information.
They must be renamed to xcenter.war and xadmin.war before use.
1. Stop the application server.

2. Replace the xcenter WAR file located in C:\jetty-x.x.x\webapps with
xcenter-X.X.X.X.X-XXX-0.0.0.war from the upgrade-->xcenter folder.

Dataloader Upgrade
3. Replace the xadmin WAR file located in C:\jetty-x.x.x\webapps with

xadmin-X.X.X.X.X-XXX-0.0.0.war from the upgrade-->xcenter folder.
4. Remove the contents of the work folder (C:\jetty-x.x.x\work).
5. Open the Xcenter Replication DB build script xstore-B.B.B.B.B-V.V.V-CCC-
xcenterrepl-upgrade-SCHEMA.sql and replace the $(DbName); text with the
name of your xcenter database.
set @xcenterDbName = '$(DbName)';
6. Run the SQL script you modified in step 5 above against the Xcenter Replication DB.
xstore-B.B.B.B.B-V.V.V-CCC-xcenterrepl-upgrade-SCHEMA.sql
7. Run SQL scripts against the Xcenter DB:
The upgrade scripts are found in the xcenter folder.
xstore-B.B.B.B.B-V.V.V-CCC-xcenter-upgrade-SCHEMA.sql
xstore-B.B.B.B.B-V.V.V-CCC-xcenter-upgrade-DATA_ORG-
xxxx.sql
8. Run the following SQL script against the Oracle Retail Xstore Office DB:
xstore-B.B.B.B.B-V.V.V-CCC-xadmin-upgrade.sql
9. Start Jetty.
Dataloader Upgrade
1. Copy the dataloader folder (located in the tools folder) to a temporary location
and open it.
2. Open the dataloader subdirectory.
3. Open ant.install.properties file and confirm the values. Edit as needed.
c:\jre\bin\java -jar xstore-B.B.B.B.B-V.V.V-CCC-dataloader-
upgrade.jar
POS Log Generator Upgrade

1. Copy the poslog folder (located in the tools folder) to a temporary location and
open it.
2. Open the poslog subdirectory.
3. Open ant.install.properties file and confirm the values. Edit as needed.
c:\jre\bin\java -jar xstore-B.B.B.B-V.V.V-CCC-
posloggenerator.jar

Xservices Upgrade
Xservices Upgrade
Note: Updates and Upgrades are only applied on systems where
Xservices is installed.
1. Open the xservices subdirectory.

c:\jre\bin\java -jar xservices-B.B.B.B-V.V.V-P.P-CCC-
upgrade.jar
Upgrading Xenvironment
Important: Updates and Upgrades are only applied on systems
where Xenvironment is installed.
1. Open the xenvironment subdirectory.

2. Open a a command prompt (for example, cmd or xterm).
3. In the command prompt, navigate to the folder where the installer is located\
4. Enter the following command:
c:\jre\bin\java -jar
xenvironment-B.B.B.B-V.V.V-P.P-CCC-upgrade.jar
See “Install Xenvironment” of Chapter 5, “Install Xstore Point of Service”for installation
instructions.

Upgrading Xenvironment

9
Internationalization
Internationalization is the process of creating software that can be translated easily.

Changes to the code are not specific to any particular market. Oracle Retail Xstore Point
of Service Suite has been internationalized to support multiple languages.
This section describes configuration settings and features of the software that ensure that
the base application can handle multiple languages.
Translation
Translation is the process of interpreting and adapting text from one language into
another. Although the code itself is not translated, components of the application that are
translated may include the following, among others:
• Graphical user interface (GUI)
• Error messages
The following components are not usually translated:
• Documentation (for example, Online Help, Release Notes, Installation Guide, User
• Guide, Operations Guide)
• Batch programs and messages
• Log files
• Configuration Tools
• Reports
• Demo data
• Training Materials
The user interface for Xstore Point of Service has been translated into:
• EN - English
• ES - Spanish
• DE - German
• IT - Italian
• JA- Japanese
• RU - Russian
• FR - French
• PT-BR- Brazilian Portuguese
Internationalization 9-1
Localization
• ZH-CN - Simplified Chinese

• NL - Dutch
• SV - Swedish
Any of these language packs are available to be installed on any registers.
Localization
The default country settings, can be overridden to suit the specific retailers requirements
during the installation of Xstore Point of Service
The country settings include country specific configurations and features such as:
• Date/Time formats
• Default address and printed address formats
• Default phone and post code formats, default receipt formats
• Capture customer info, when tenders or cash tenders exceed defined thresholds
• Automated Store Close Z-Reports
• Fiscal printer and other fiscalization support
Configuration Accelerators
For information about configuration accelerators (localization packs), including
procedures for applying them, see the Xstore Suite Configuration Accelerator Guide. This
document is available on My Oracle Support, Doc ID 1994467.1.
Multi-Keystroke Character Entry

Some languages require multiple keystrokes to enter individual characters. These
include languages that use double-byte characters, such as Chinese, Japanese, and
Korean. Other languages—such as Spanish, Portuguese, and German—use character
annotations (for example, accents or umlauts) that require multiple keystrokes to enter
one character. In this guide, these are referred to as multi-keystroke characters.
While these characters are supported in Xstore Point of Service and Xstore Office, the on-
screen keyboard for Xstore Point of Service does not support the entry of multi-
keystroke characters.
Important: Languages that use multi-keystroke characters must use a

physical keyboard for data entry. The virtual keyboard does not
support entering these characters.
Fiscalization
Xstore Point of Service supports features, base frameworks and extensions to help
support fiscal, tax, currency and general selling rules and requirements in different
countries, regions, and tax authorities, especially within fiscal countries.
Many countries and regions have specific requirements, some of which are best practice,
and others are mandated by the country and/or the country’s tax authorities.
Some of these fiscal features and rules are included within the localization country
settings.

Fiscalization
Features
Fiscal Printer Support
Framework extensions enable the support of fiscal printers with minimal integration
requirements.
Currency Rounding
Rules that control currency rounding effects based on configurable criteria are
supported by Xstore Point of Service.
Enforced End of Day
Xstore Point of Service is able to enforce cessation of trading to comply with regulations
in some regions and localities.
Extended Address Syntaxes
Xstore Point of Service supports extended address syntaxes such as neighborhood and
county address fields.
Digital Signature Support
Xstore Point of Service supports fiscal digital signatures enforced in some fiscal
locations.
Invoice Printing
Xstore Point of Service produces an invoice a well as a receipt in certain localities.
Enhanced Transaction Mixing Rules
Xstore Point of Service supports enhanced rules for controlling contents of transactions
and the mixing of basket line types, to comply with regulations in many countries.
Sequential Numbers by Store
Xstore Point of Service supports sequential numbers by store, instead of by individual
register, e.g. for invoice numbers, credit notes etc.
Transaction Discounts displayed in Total Section
The transaction discounts are displayed in the Total section on the item display, instead
of displaying discounts against each item, to comply with regulations in some countries.
Storage and Search by Fiscal Receipt/Invoice Number
Xstore Point of Service supports storage and search by fiscal receipt/invoice number, to
comply with regulations in some countries.
Printing of Receipts for cancelled Transactions
Xstore Point of Service Suite allows for filling in store, and for searching for cancelled
receipts.
Display Items Tax Code and Tax Summary on Receipt
Xstore Point of Service allows for more flexibility of receipt contents, and is a
requirement in certain countries.

Fiscalization

A
String Encrypter Utility
Running the Encrypter

Note: The Encrypter utility is created as part of the GenKeys
installation procedure. For more information, see:
• “Install GenKeys and String Encrypter Utility” of Chapter 3, “Install Xstore
Office”
• “Install GenKeys String Encrypter Utility” of Chapter 5, “Install Xstore
Point of Service”
The Encrypter utility is a stand-alone package that allows you to run encrypt.bat for
encryption of text using Xstore Suite cipher keys.
- For Windows, execute encrypt.bat to run the string Encrypter.
- For Linux, execute encrypt.sh to run the string Encrypter.
1. Double-click the encrypt.bat (or encrypt.sh) utility.
2. Complete the fields as needed.
a. customer - Salt value. This is not the customer code, unless the customer code is being
used as the salt value.
b. keystore - Location of the GenKeys certificate files.
c. value - String to be encrypted.
d. cipher - Do not change this value.
3. Click the encrypt button to create the encrypted string in the result field.
Figure A-1: String Encrypter Utility Results
4. Click the copy button to copy the encrypted value to the system clipboard.
String Encrypter Utility A-1

Running the Encrypter
A-2 Implementation and Security Guide

B
Public Key Certificates
Introduction
In the interest of data security, retailers require the ability to manage the public key
certificates that are used when one part of the Point of Sale (POS) solution communicates
with another. This section will concentrate on public key certificates for use within a
managed network, specifically for use with Xstore Point of Service, Oracle Retail Xstore
Office, Xenvironment, and the web server.
Important: The key creation steps outlined in this document must be

performed on a secure system, not on a register and not on the server
where it will be deployed.
A JRE must exist on the secured system before you can create the TLS
certificates.
This appendix covers the following topics:

• Explaining the ways public key certificates can be managed.
• Discussing the advantages and disadvantages of each management strategy.
• Describing the technical details of generating public/private key pairs, and using the
generated keys for Transport Layer Security (TLS) communication between Xstore
Suite products.
Note: The business details of exactly how to manage certificate

replacement are beyond the scope of this guide.
When the term “certificate” appears in this document, it refers to a public key certificate.
The tools referenced in this document are OpenSSL and Sun’s keytool utility. The steps in
this guide assume that both utilities have been installed and added to the system path. (See
Public Key Certificates B-1

OpenSSL & Keytool Utility
“OpenSSL & Keytool Utility”). Other tools could potentially be used in place of these;
however, to keep things simple we will only cover one way of doing things.
Important: The private key that goes with a public key certificate is
considered extremely sensitive information since it is used to initiate
an encrypted communication session that may contain customers’
cardholder data.
For this reason, Oracle will not store or create a customer’s production
private keys on its corporate network, nor will Oracle accept a private
key file in any form. This policy has been adopted to provide
additional security protection to our customers.
Accordingly, the customer is responsible for creating all TLS certificate

components listed in this document. Oracle will only import the public
key certificate into the Xstore Point of Service keystore on each register.

Important: The examples shown below assume a 32-bit Operating
System. If you have a 64-bit Operating System be sure to obtain and
use the correct version!
The steps in this guide assume that both OpenSSL and Sun’s keytool utility have been
installed and added to the system path. A JRE must exist on the secured system before
you can create the TLS certificates. See “Create JRE Package” of Chapter 2, “Prerequisites
for Installing Xstore Office” or “Create JRE Package” of Chapter 4, “Prerequisites for
Installing Xstore Point of Service”.
Where To Find OpenSSL & Sun’s Keytool Utility

If you are using Windows, OpenSSL can be obtained from:
http://www.slproweb.com/products/Win32OpenSSL.html
Use the latest release version for your operating system.
The keytool utility comes with Java.
Add OpenSSL & Keytool Utility to the System Path (Windows)

The example shown below assumes a 64-bit operating system.
1. Click Control Panel.
2. Double-click the System icon in the Control Panel.
3. Click the Advanced tab (or Advanced system settings on Windows Vista, Windows
7, or Windows 10, or Advanced System Settings link using Windows Server 2008
R2 Std).
4. In the System properties window, click the Environment Variables button. (Within
the properties screen, click the Advanced tab-->Find Environment Variables.)
5. In System variables, click the variable named Path, then click Edit.
6. Add the target directory to the value of the variable (Variable value field), using a
semi-colon as a separator.
B-2 Implementation and Security Guide

- To add the keytool utility to your system (if you have finished installing
GenKeys), you would enter the following to the end of the Path:
;c:\jre\bin
Note: This assumes that you have completed “Create JRE Package” in
Chapter 4, “Prerequisites for Installing Xstore Point of Service”.
- To add the path to the OpenSSL executable to your system, if it is located at

c:\OpenSSL-Win64\bin, you would enter the following at the end of the
Path:
;c:\OpenSSL-Win64\bin
Note: The 32-bit path would be c:\OpenSSL-Win32\bin
Certificate File Directories
Windows
1. Open a command prompt and type the following sequence of commands:
md c:\cert\sslcert
cd c:\cert\sslcert
md certs
md private
echo 100001 > serial
echo on > certindex.txt
2. Continue with “openssl.cnf”.
Linux
1. In a shell command window (for example, xterm), run the following sequence of
commands:
mkdir /opt/cert/sslcert
cd /opt/cert/sslcert
mkdir certs
mkdir private
echo 100001 > serial
touch certindex.txt
Keep the shell window open while performing the next steps.
2. Continue with “openssl.cnf”.
Implementation and Security Guide B-3

Create a Certificate Authority
openssl.cnf
Certificate Authority (CA) signed TLS certificates require you to create an
openssl.cnf file, which defines configurations for the TLS certificates.
To create the openssl.cnf file:
1. Navigate to the c:\cert\sslcert or /opt/cert/sslcert directory.
2. Open a text-editing program (for example, Notepad, emacs, Wordpad, or vi).
3. Copy the following OpenSSL configuration information into the text-editing
program (for example, Notepad, emacs, Wordpad, or vi), editing the highlighted
fields as indicated:
#
# OpenSSL configuration file.
#
# Establish working directory.
dir = .
[ ca ]
default_ca = CA_default
[ CA_default ]
serial = $dir/serial
database = $dir/certindex.txt
new_certs_dir = $dir/certs
certificate = $dir/cacert.pem
private_key = $dir/private/cakey.pem
default_days = 395
default_md = sha256
preserve = no
email_in_dn = no
nameopt = default_ca
certopt = default_ca
policy = policy_match
copy_extensions = copy

[ policy_match ]
countryName = match
stateOrProvinceName = match
organizationName = match
organizationalUnitName = optional
commonName = supplied
emailAddress = optional
[ req ]
default_bits = 2048 # Size of keys
default_keyfile = key.pem # name of generated keys
default_md = sha256 # message digest algorithm
string_mask = nombstr # permitted characters
distinguished_name = req_distinguished_name
req_extensions = v3_req
keyUsage = digitalSignature,keyCertSign
[ req_distinguished_name ]
# Variable name Prompt string
#------------------------- ----------------------------------
0.organizationName = Organization Name (company)
0.organizationName_default = <Your Company>
organizationalUnitName = Organizational Unit Name
(department, division)
organizationalUnitName_default = <Your Organizational Unit>
emailAddress = Email Address
emailAddress_max = 40
emailAddress_default = <Your Email Address>
localityName = Locality Name (city, district)
localityName_default = <Your City>
stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName_default = <Your State>
countryName = Country Name (2 letter code)
countryName_min = 2
countryName_max = 2
countryName_default = <Your 2-Letter Country Code>

commonName = Common Name (hostname, IP, or your

name)
commonName_max = 64
commonName_default = <Certificate Authority Name>
# Default values for the above, for consistency and less typing.
# Variable name Value
#------------------------ ------------------------------
0.organizationName_default = My Company
localityName_default = My Town
stateOrProvinceName_default = State or Province
countryName_default = US
[ v3_ca ]
basicConstraints = CA:TRUE
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer:always
[ v3_req ]
basicConstraints = CA:FALSE
subjectKeyIdentifier = hash
4. Save the file as openssl.cnf in the c:\cert\sslcert or /opt/cert/sslcert

directory.
cacert.pem
Many of the certificates used in the Xstore Suite require a certificate signed by a
certificate authority. To create your own certificate authority to sign your certificates, the
procedures in this manual use a cacert.pem file.
To create a cacert.pem file, do the following:
2. Enter the following command:
- In Windows:
cd c:\cert\sslcert
md private
- In Linux:
cd /opt/cert/sslcert
md private
3. Enter the following command in the sslcert directory:

- In Windows:
openssl req -new -x509 -extensions v3_ca -keyout
private\cakey.pem -out cacert.pem -days 3653 -config
openssl.cnf
- In Linux:
openssl req -new -x509 -extensions v3_ca -keyout private/
cakey.pem -out cacert.pem -days 3653 -config ./openssl.cnf
Note: -days 3653 option - This value (ten years until expiration)
would typically only be used on a root certificate so that you do not
have to reissue it so often. At eight or nine years, you could generate an
additional root certificate and distribute both for one-two years.
a. When prompted, enter and confirm the PEM password.

b. Answer the questions when prompted. This information will be incorporated
into the certificate request. (NOTE: The questions may appear in a different order
than shown in the table below. Answer each question appropriately using the
table below as a guide).
Name Field Explanation Example
Organization Name The exact legal name of your Oracle

organization. Do not abbreviate.
(Must match name entered
previously for Organization
Name).
Organizational Unit Name Optional for additional <Name>-YYYYMMDD

organization information. The
where <Name> is name
OU must be different on each
chose for the key.
key. (One option is to add a date
to make it unique).
Email Address The email address of the person myname@company.com

to be contacted about this
certificate.
Locality Name The city or district where your Cleveland

organization is located.
State or Province Name The state or province where your Ohio

organization is located. Cannot
(Must match name entered
be abbreviated.
previously for State or
Province Name).
Country Name The two-letter ISO abbreviation US

for your country.
(Must match code entered
previously for Country Name).
Common Name The name of your root Oracle Certificate Authority

certificate.

c. Back up the two files that are created: cacert.pem located in the sslcert
directory and cakey.pem located in the sslcert/private directory.
Note: The cacert.pem in the sslcert directory is the file

containing the "public" information on this new root certificate
authority. You will import this public certificate to the various Java
truststores as well as the server's keystore. The cakey.pem file in the
sslcert/private directory will be used to sign the certificates that will be
used.
Certificate Management Strategy Detail

• For certificates signed by a CA, refer to:
- “Certificate Authority-Signed Certificates: Oracle Retail Xstore Office”
- “Certificate Authority-Signed Certificates: Xservices”
- “Certificate Authority-Signed Certificates: Apache”
• For unsigned or self-signed certificates, refer to:
- “Self-Signed Certificates: Oracle Retail Xstore Office”
- “Self-Signed Certificates: Xservices”
- “Self-Signed Certificates: Apache”
• For Xenvironment certificates, refer to
- “Xenvironment Certificates”
Validation
Important: The procedures in this appendix assume a consistent use
of the values listed below.
When you create a certificate authority, the following entries are validated:
• Organization Name - This is the exact legal name of your organization. When
prompted, always enter the same value for your Organization Name.
• State or Province Name - This is the state or province where your organization is
located. This value cannot be abbreviated. When prompted, always enter the same
value for your State or Province Name.
• Country Name - This is the two-letter ISO code for your country. When prompted,
always enter the same value for your Country Name.

Certificate Authority-Signed Certificates: Oracle Retail Xstore Office
Certificate Authority-Signed Certificates: Oracle Retail Xstore

Office
Customer Responsibility: Oracle Retail Xstore Office
What you need to know before creating certificates

• The steps in this section assume that both OpenSSL and Sun’s keytool utility have
been installed and added to the system path. See “OpenSSL & Keytool Utility”.
• While following the steps outlined in this section, you will be prompted to enter
information that will be embedded into the new certificate. Ensure that the
information conforms to the requirements defined in each procedure. Always use
the exact legal name of your organization when prompted for your organization
name.
• The provided commands include xcenter-YYYYMMDD, representing the alias of the
key. This alias can be any unique value. Including the date in the alias allows you to
more easily identify the key and track when the keys should be rotated.
• Be sure to replace “YYYYMMDD” with a current date string throughout this
procedure.
To create and deploy Certificate Authority-Signed Certificates

Perform the following procedure to create and deploy CA-signed certificates for Oracle
Retail Xstore Office.
1. To create a directory structure for key creation, type the following commands:
- Windows:
md C:\cert\xcenter
cd C:\cert\xcenter
- Linux:
mkdir /opt/cert/xcenter
cd /opt/cert/xcenter
2. To create a Keystore, Key, and Certificate Signing Request, type the following
command in the C:\cert\xcenter directory:
keytool -genkey -keystore server.keystore -alias
xcenter-YYYYMMDD -keyalg RSA -keysize 2048 -ext
SAN=DNS:<hostname>[,DNS:<hostname>...] -validity 395
Note: The number following the –validity switch in the keytool

commands represents the validity timeframe for the key. PCI
requirements mandate that encryption keys are rotated annually. See
““Choosing a Certificate Management Strategy” for more details.
a. When prompted, enter and confirm the keystore password.

Note: This password will need to be configured in the application

server. The password will also need to be entered and confirmed in
later sections.
When prompted for a key password, press [Enter] to use the same
password as the keystore. Oracle recommends using the same
password for both the keystore password and the key password.
b. Answer the questions when prompted. (NOTE: The questions may appear in a
different order than shown in the table below. Answer each question
appropriately using the table below as a guide).
First and Last Name (aka The hostname or IP address that will localserver
Common Name) be used to access the server.
Organizational Unit Use this field to remind you what the Xcenter-
certificate is used for. YYYYMMDD
The OU must be different on each key.
(One option is to add a date to make it
unique).

organization.
City or Locality The city where your organization is Cleveland

located.

organization is located. Cannot be
abbreviated.
Two-letter country code The two-letter ISO abbreviation for US

your country.
c. When prompted if the information is correct, type y or yes.

d. When prompted, press [Enter] to use the same password as the keystore
(Recommended).
e. Type the following command:
keytool -certreq -keystore server.keystore -alias
xcenter-YYYYMMDD -file xcenter-YYYYMMDD.req -ext
SAN=DNS:<hostname>[,DNS:<hostname>...]
f. When prompted enter the keystore password.
3. Submit the resulting .req file to the certificate assigning authority to be signed.
Secure channels are not required for sending the request because no private key
information is included in the request file.


Authority
4. Perform the applicable step to create a Root Certificate Authority:
- If you have already created a certificate authority while following this guide
for another product, skip to step 5 below and use the certificate authority that
was created at that time.
If you have already created a certificate authority, the following entries are
validated and must match the values entered when the CA was set up originally.
countryName = match
stateOrProvinceName = match
organizationName = match
- If you have not created a certificate authority, go to “Create a Certificate
Authority” and follow the instructions to create a certificate authority. After
creating a certificate authority, continue with step 5 below.
The following instructions should be followed by the Certificate

Authority
5. Sign the Certificate Signing Request with the Root Certificate:
Before proceeding with this step, you should have your certificate request file ready.
For this example, we will assume that we were given xcenter-YYYYMMDD.req to
work with. Details on creating certification requests are in step 2.
a. Copy xcenter-YYYYMMDD.req to the c:\cert\sslcert folder on the
Certificate Authority system. Secure channels are not required for receiving the
request because no private key is included in the request file.
b. Type the following command in the C:\cert\sslcert directory::
openssl ca -out xcenter-YYYYMMDD.cer -config ./openssl.cnf
-infiles xcenter-YYYYMMDD.req
c. Type the password for ./private/cakey.pem.
d. When prompted to sign the certificate, type y or yes.
e. When prompted to commit the certificate, type y or yes.
f. Enter the following commands in the C:\cert\sslcert directory. This
assumes you used the base path names.
* Windows:
set OPENSSL_CONF=c:\cert\sslcert\openssl.cnf
openssl x509 -in xcenter-YYYYMMDD.cer -out
xcenter-YYYYMMDD.der.cer -outform DER
* Linux:
set OPENSSL_CONF=/opt/cert/sslcert/openssl.cnf
g. Return the resulting .der.cer file to the party that submitted the request file
along with the cacert.pem file. Secure channels are not required because the
signed certificate file does not contain any private key information.

6. Import the Root Certificate into the Keystore
Note: Including the date in the aliases will help avoid someone
removing an old CA certificate too soon when rolling out a new CA
certificate. It is recommended that you have an overlapping period
when certificates issued with both the old and the new CA certificates
are acceptable.
For this example, we will assume that we were given a cacert.pem file.
a. Copy the cacert.pem file to the c:\cert\xstore directory. Secure channels
are not required for receiving the root certificate because no private key
information is included in the file.
b. Type the following command in the c:\cert\xstore directory:
keytool -import -file cacert.pem -keystore server.keystore
-alias myrootca-YYYYMMDD
c. When prompted, enter the keystore password.
d. When prompted, type y or yes to trust the certificate. The certificate is added to
the keystore.
7. Import the Signed Request into the Keystore.
For this example, we will assume that we were given
xcenter-YYYYMMDD.der.cer to work with.
a. Copy xcenter-YYYYMMDD.der.cer to the c:\cert\xcenter folder. Secure
channels are not required for receiving the signed certificate request file because
no private key is included in the file.
b. Type the following command in the C:\cert\xcenter directory:
keytool -import -trustcacerts -file xcenter-
YYYYMMDD.der.cer
-keystore server.keystore -alias xcenter-YYYYMMDD
c. When prompted, enter the keystore password. The certificate reply is installed
in the keystore.
d. The resulting server.keystore will be used during the Jetty/Tomcat install.
See “Install an Application Server: WebLogic, Jetty, or Tomcat” of Chapter 3,
“Install Xstore Office” for installation instructions.

Integrator’s Responsibility: Xstore Office

Important: If a customer or integrator is doing their own installation
and integration, they must perform all the steps in this section, in
addition to the steps in the Customer Responsibility section.
The root certificate must be created by the customer and provided to the person
installing the software in order for the following steps to be executed.
Important: The following steps are performed during the Xstore

Office install as a prerequisite to installing the application server. If
you have already completed these steps, it is not necessary to do this
again.
After installing Xstore Point of Service, perform the following steps to import the root
certificate into Xstore Point of Service’s truststore.
1. Run the following command in the xcenter directory to import the root certificate
into Xstore Point of Service’s Truststore.
- Windows:
keytool -import -file cacert.pem -keystore
\xstore\res\ssl\.truststore -alias myrootca-YYYYMMDD
- Linux:
/opt/xstore/res/ssl/.truststore -alias myrootca-YYYYMMDD
2. When prompted, enter the keystore password.
3. When prompted, type y or yes to trust the certificate.
4. Place the truststore file on every Xstore Point of Service register in the field, and
verify that appropriate DataSourceConfig or InstallX settings are in place on every
system as well.
into Xenvironment’s truststore.
- Windows:
\environment\res\ssl\.truststore -alias myrootca-YYYYMMDD
- Linux:
/opt/environment/res/ssl/.truststore -alias
myrootca-YYYYMMDD
6. Place the .truststore file on every Xenvironment system in the field.

Certificate Authority-Signed Certificates: Xservices

Customer Responsibility: Xservices

information conforms to the requirements defined in each procedure.
• The provided commands include xservices-YYYYMMDD, representing the alias of
the key. This alias can be any unique value. Including the date in the alias allows you
to more easily identify the key and track when the keys should be rotated.
procedure.
To create and deploy Certificate Authority-Signed Certificates for

Xservices
Perform the following procedure to create and deploy CA-signed certificates for
Xservices.
1. To create a directory structure for key creation, enter the following commands:
- Windows:
md C:\cert\xservices
cd C:\cert\xservices
- Linux:
mkdir /opt/cert/xservices
cd /opt/cert/xservices
command in the C:\cert\xservices directory:
keytool -genkey -keystore keystore -alias xservices-YYYYMMDD
-keyalg RSA -keysize 2048 -ext

“Choosing a Certificate Management Strategy” for more details.
Note: The password will also need to be entered in later sections.


First and Last Name (aka The hostname or IP address that will StoreName
Organizational Unit Use this field to remind you what the Xservices-
unique).

organization.

located.

abbreviated.

your country

(Recommended).
e. Type the following command in the xservices directory:
keytool -certreq -keystore keystore -alias
xservices-YYYYMMDD -file xservices-YYYYMMDD.req -ext
f. When prompted, enter the keystore password.
3. Submit the resulting req file to the certificate assigning authority to be signed.
The instructions in steps 4 and 5 should be followed by the Certificate Authority

- If you have not created a certificate authority, go to “Create a Certificate
Authority” and follow the instructions to create a certificate authority. After
The instructions in this step should be followed by the Certificate Authority

5. Sign the Certificate Signing Request with the Root Certificate.

For this example, we will assume that we were given xservices-YYYYMMDD.req
to work with. Details on creating certification requests are outlined in step 2.
a. Copy xservices-YYYYMMDD.req to the sslcert directory on the Certificate
Authority system. Secure channels are not required for receiving the request
because no private key is included in the request file.
b. Enter the following command in the sslcert directory:
openssl ca -out xservices-YYYYMMDD.cer -config openssl.cnf
-infiles xservices-YYYYMMDD.req
c. When prompted, enter the password for ./private/cakey.pem.
f. Run the following lines in the C:\cert\sslcert directory. This assumes you
used the base path names.
* Windows:
openssl x509 -in xservices-YYYYMMDD.cer -out
xservices-YYYYMMDD.der.cer -outform DER
* Linux:
6. Import the Root Certificate into the Keystore.
are acceptable.
a. Copy the cacert.pem file to the xservices directory. Secure channels are not
required for receiving the root certificate because no private key information is
included in the file.
b. Enter the following command in the xservices directory:
keytool -import -file cacert.pem -keystore keystore -alias
myrootca-YYYYMMDD
d. When prompted, type y or yes to trust the certificate.

Certificate Authority-Signed Certificates: Apache

xservices-YYYYMMDD.der.cer to work with.
a. Copy xservices-YYYYMMDD.der.cer to the xservices certificate folder.
Secure channels are not required for receiving the signed certificate request file
because no private key is included in the file.
b. Type the following command in the xservices directory:
keytool -import -trustcacerts -file
xservices-YYYYMMDD.der.cer -keystore keystore -alias
xservices-YYYYMMDD
8. After installing Xservices, copy the newly created keystore into C:\xservices-
config for Windows or /opt/xservices-config for Linux.

Customer Responsibility: Apache
Prerequisites:
1. Both OpenSSL and Sun’s keytool utility must be installed and added to the system
path. See “OpenSSL & Keytool Utility” for more information.
2. The openssl.cnf and cacert.pem files must exist. See “Create a Certificate
Authority” for more information. If you have already created a certificate authority
while following this guide for another product, use the certificate authority that was
created at that time.
To create and deploy Certificate Authority-Signed Certificates for

Apache
Perform the following procedure to create and deploy CA-signed certificates for Apache
Server. While following the steps outlined in this section, you will be prompted to enter
information that will be embedded into the new certificate. Ensure that the information
conforms to the requirements defined in each procedure. The steps in this section
assume both OpenSSL and Sun’s keytool utility have been installed and added to the
system path, and the openssl.cnf file has been created.
- Windows:
md C:\cert\apache
cd C:\cert\apache
- Linux:
mkdir /opt/cert/apache
cd /opt/cert/apache
2. To generate a new cert and signing request, type the following command in the
apache director:

openssl req -nodes -days 395 -newkey rsa:2048 -keyout

server.key -out server.csr -config
<location of ssl conf file>/openssl.cnf
3. Answer the questions when prompted. This information will be incorporated into
the certificate request. (NOTE: The questions may appear in a different order than
shown in the table below. Answer each question appropriately using the table below
as a guide).

Organizational Unit Optional for additional organization Apache-YYYYMMDD

Name information.
The OU must be different on each
key. (One option is to add a date to
make it unique).
Email Address The email address of the person to be myname@company.com

contacted about this certificate.


abbreviated.
Country Name The two-letter ISO abbreviation for US

your country.
Common Name The hostname or IP address that will StoreName

be used to access the server.
4. Submit the resulting .csr file to the certificate assigning authority to be signed.

The instructions in this step should be followed by the Certificate

Authority.
Details on creating certification requests are outlined in step 3 on page 18. For this
example we will assume that we were given server.csr to work with.
a. Copy server.csr to the sslcert folder on the Certificate Authority system.
Secure channels are not required for receiving the request because no private
key is included in the request file.
b. Type the following command in the sslcert directory:
openssl ca -out server.crt -config openssl.cnf -infiles
server.csr
f. To add the CA's public key to the server.crt file so it can be trusted, type the
following command in the sslcert directory:
type cacert.pem >> server.crt
g. Return the resulting server.crt file to the party that submitted the request
file, along with the cacert.pem file. Secure channels are not required because
the signed certificate file does not contain any private key information.
6. The resulting server.crt file, along with the server.key file that was originally-
generated, will be used by the Xstore Office web server. See Chapter 3, “Install
Xstore Office” for more information.
Integrator’s Responsibility: Web Server

Important: If a customer is doing their own staging, they must
perform all the steps in the Oracle Responsibility section, in addition to
the steps in the Customer Responsibility section.
After installing the web server, perform the following steps to import the CA's public
key. See Chapter 3, “Install Xstore Office” for more information.
1. Enter the following command in the C:\cert\apache directory to import the CA's
public key into xcenter-config's truststore.
- Windows:
keytool -import -file cacert.pem -alias myrootca-YYYYMMDD
-keystore c:\xcenter-config\res\ssl\.truststore
- Linux:
-keystore /opt/xcenter-config/res/ssl/.truststore
2. When prompted, enter and confirm the keystore password.
3. When prompted to trust the certificate, type y or yes.
4. Place the truststore file on every Xstore Point of Service register in the field.

Certificate Authority-Signed Certificates: Xstore Point of Service Mobile
5. Run the following command in the apache directory to import the root certificate
- Windows:
-keystore \environment\res\ssl\.truststore
- Linux:
-keystore /opt/environment/res/ssl/.truststore
Certificate Authority-Signed Certificates: Xstore Point of

Service Mobile
Perform the following procedure to create and deploy a CA-Signed Certificate for Xstore
Point of Service Mobile:
Important: If you are using iOS devices to connect to Xstore Point of

Service Mobile, you must use CA-signed certificates.
- Windows:
md C:\cert\xstoremobile
cd C:\cert\xstoremobile
- Linux:
mkdir /opt/cert/xstoremobile
cd /opt/cert/xstoremobile
command:
keytool -genkey -keystore keystore -alias
xstoremobile-YYYYMMDD -keyalg RSA -keysize 2048 -ext
Where YYYYMMDD is the year, month, date day on which the certificate is created.
If you have to use IP addresses as SAN parameter, see the example below.
Example:
-ext
SAN=DNS:hostname1,IP:10.198.51.100.1,DNS:hostname2,IP:10.198.5
1.100.2, [...]
Note: You can use any combination of DNS and IPs in the same SAN
parameter separated by commas.

b. Answer the questions when prompted.
Organizational Unit Use this field to remind you what the XstoreMobile-
unique).

organization.

located.

abbreviated.

your country

(Recommended).
e. Type the following command in the xservices directory:
xstoremobile-YYYYMMDD -file xstoremobile-YYYYMMDD.req
-ext SAN=DNS:<hostname>[,DNS:<hostname>...]
Where YYYYMMDD is the year, month, date day on which the certificate is created.
f. When prompted, enter the keystore password.
3. Submit the resulting .req file to the certificate assigning authority to be signed.

Authority
- If you have not created a certificate authority, go to Create a Certificate
Authority and follow the instructions to create a certificate authority. After

The instructions in this step should be followed by the Certificate

Authority
For this example, we will assume that the request file is named xstoremobile-
YYYYMMDD.req.
a. Copy xstoremobile-YYYYMMDD.req to the c:\cert\sslcert folder on
the Certificate Authority system. Secure channels are not required for receiving
the request because no private key is included in the request file.
b. Type the following command:
openssl ca -out xstoremobile-YYYYMMDD.cer -config
./openssl.cnf -infiles xstoremobile-YYYYMMDD.req
f. Run the following commands. This assumes you used the base path names.
openssl x509 -in xstoremobile-YYYYMMDD.cer -out
xstoremobile-YYYYMMDD.der.cer -outform DER
along with the cacert.pem file.
Note: Secure channels are not required because the signed certificate
file does not contain any private key information.
6. Import the Root Certificate into the Keystore.
are acceptable.
a. Copy the cacert.pem file to the c:\cert\xstoremobile folder. Secure
channels are not required for receiving the root certificate because no private
key information is included in the file.
b. Run the following command in the c:\cert\xstoremobile directory:
keytool -import -file cacert.pem -keystore keystore -alias
myrootca-YYYYMMDD
d. When prompted, type y or yes to trust the certificate.

Self-Signed Certificates: Oracle Retail Xstore Office
For this example, we will assume that we were given xstoremobile-

YYYYMMDD.der.cer to work with.
a. Copy xstoremobile-YYYYMMDD.der.cer to the c:\cert\xstoremobile
folder. Secure channels are not required for receiving the signed certificate
request file because no private key is included in the file.
b. Run the following command in the c:\cert\xstoremobile directory:
xstoremobile-YYYYMMDD.der.cer -keystore
keystore -alias xstoremobile-YYYYMMDD
8. Change the name of the keystore file to xstore_mobile.keystore.
9. Copy the xstore_mobile.keystore file to the same folder as the Xstore Point of
Service installer.
Install the Certificate on Android

1. Copy the provided cacert.pem file to the storage of the Android device.
2. Change the extension of the file from .pem to .cer.
5. In the security menu of the Android device, select the Install from storage option
and, when prompted for the name, select the file that was copied to the device's
storage.

Customer Responsibility: Oracle Retail Xstore Office

been installed and added to the system path. See “OpenSSL & Keytool Utility” for
more information.
• The provided commands include xcenter-YYYYMMDD, representing the alias of the
key. This alias can be any unique value. Including the date in the alias allows you to
more easily identify the key and track when the keys should be rotated.
procedure.
Suggested certificate rotation strategy

With self-signed certificates you should be sure to create and distribute a new key for
your servers before the old one expires. If you rotate annually, consider a validity of 1
year+30 days to allow for a rollout period.

1. Create a new key.

2. Distribute an updated truststore that includes both the old key and the new key.
3. Once fully rolled out, modify the Xstore Office server to use the new key.
4. For the next new truststore you send out, the old (now unused) key can be omitted.
Always include the current key and a new key when rolling out changes to the
truststore.
To create and deploy Self-Signed Certificates

Perform the following procedure to create and deploy Self-Signed Certificates for Oracle
Retail Xstore Office.
- Windows:
md C:\cert\xcenter
cd C:\cert\xcenter
- Linux:
mkdir /opt/cert/xcenter
cd /opt/cert/xcenter
2. To create a Keystore and Key, type the following command in the xcenter
directory:

““Choosing a Certificate Management Strategy” for more details.
Note: This password will need to be configured in the application

server. The password will also need to be entered and confirmed in
later sections.
b. Answer the questions when prompted. (The questions may appear in a different
order than shown in the table below. Answer each question appropriately using
the table below as a guide).

Organizational Unit Use this field to remind you what the Xcenter-
unique).

organization.

located.

abbreviated.

your country

(Recommended).
3. To Self-Sign the Certificate, type the following command in the xcenter directory:
keytool -selfcert -alias xcenter-YYYYMMDD -keystore
server.keystore -validity 395
a. When prompted, enter the keystore password.
4. To export the Certificate, type the following command:
keytool -export -alias xcenter-YYYYMMDD -keystore
server.keystore -rfc -file xcenter-YYYYMMDD.cer
5. The resulting server.keystore will be used during the Jetty/Tomcat install. See
“Install an Application Server: WebLogic, Jetty, or Tomcat” of Chapter 3, “Install
Xstore Office” for installation instructions.

Important: If a customer is doing their own installation, they must
perform all the steps in the Oracle Responsibility section, in addition to
the steps in the Customer Responsibility section.
After installing Xstore Point of Service, perform the following steps to import the
Certificate into Xstore Point of Service's Truststore. (See “Install Xstore Point of Service”
of Chapter 5, “Install Xstore Point of Service”)
1. To import the Certificate into Xstore Point of Service's Truststore, type the following
command:
- Windows:

Self-Signed Certificates: Xservices
keytool -import -file xcenter-YYYYMMDD.cer -keystore

\xstore\res\ssl\.truststore -alias xcenter-YYYYMMDD
- Linux:
/opt/xstore/res/ssl/.truststore -alias xcenter-YYYYMMDD
b. When prompted, type y or yes to trust the certificate.
2. Place the Truststore file on every Xstore Point of Service register in the field, and
verify that appropriate DataSourceConfig or InstallX settings are in place on every
system as well.
into Xenvironment's Truststore.
- Windows:
\environment\res\ssl\.truststore -alias xcenter-YYYYMMDD
- Linux:
/opt/environment/res/ssl/.truststore -alias xcenter-YYYYMMDD

Customer Responsibility: Xservices

• The provided commands include xservices-YYYYMMDD, representing the alias of
the key. This alias can be any unique value. Including the date in the alias allows you
to more easily identify the key and track when the keys should be rotated.
procedure.

i) Create a new key.
ii) Modify the Xservices server to use the new key by delivering a new keystore
that no longer includes the previous key.

To create and deploy Self-Signed Certificates for Xservices

Perform the following procedure to create and deploy Self-Signed Certificates for
Xservices.
- Windows:
md C:\cert\xservices
cd C:\cert\xservices
- Linux:
mkdir /opt/cert/xservices
cd /opt/cert/xservices
2. To create a Keystore and Key, type the following command in the xservices
directory:
keytool -genkey -keystore xservices.keystore -alias
xservices-YYYYMMDD -keyalg RSA -keysize 2048 -ext

“Choosing a Certificate Management Strategy” for more details.
Note: The password will also need to be entered in later sections.

Organizational Unit Use this field to remind you what the Xservices-
unique).

organization.

located.

Self-Signed Certificates: Apache

abbreviated.

your country
c. When prompted, type y or yes to confirm your entries.

(Recommended).
3. To self-sign the Certificate, enter the following command in the xservices
directory:
keytool -selfcert -alias xservices-YYYYMMDD -keystore
xservices.keystore -validity 395
After installing Xservices, perform the following step.
4. Copy the newly created keystore from the xservices directory into
C:\xservices-config on Windows or /opt/xservices-config on Linux.
See “Install Xservices” of Chapter 5, “Install Xstore Point of Service”.

Customer Responsibility: Apache


1. Create a new key.
2. Distribute an updated truststore that includes both the old key and the new key.
3. Once fully rolled out, modify the Apache server to use the new key.
4. For the next new truststore you send out, the old (now unused) key can be omitted.
Always include the current key and a new key when rolling out changes to the
truststore.
To create and deploy Self-Signed Certificates for Apache

Perform the following procedure to create and deploy Self-Signed Certificates for
Apache.

- Windows:
md C:\cert\apache
cd C:\cert\apache
- Linux:
mkdir /opt/cert/apache
cd /opt/cert/apache
2. To generate a self-signed certificate, type the following command in the apache
directory:
openssl req -x509 -nodes -days 395 -newkey rsa:2048 -keyout
server.key -out server.crt
3. Answer the questions when prompted. This information will be incorporated into
the certificate request. (NOTE: The questions may appear in a different order than
shown in the table below. Answer each question appropriately using the table below
as a guide).
Country Name The two-letter ISO abbreviation for US

your country.

abbreviated.


Organizational Unit Optional for additional organization Apache-YYYYMMDD

Name information.
The OU must be different on each
key. (One option is to add a date to
make it unique).
Common Name The hostname or IP address that will StoreName

be used to access the server.
Email Address The email address of the person to be myname@company.com

contacted about this certificate.
4. Retain the server.key and server.crt files for the Apache installer.
5. The server.crt file, along with the server.key file that was originally-
generated, will be used by the Xstore Office web server. See Chapter 3, “Install
Xstore Office” for more information.

Self-Signed Certificates for Xstore Point of Service Mobile
Integrator’s Responsibility: Web Server

Important: If a customer or integrator is doing their own installation,
they must perform all the steps in this section, in addition to the steps
in the Customer Responsibility section.
After installing the web server and Xenvironment, perform the following steps to
import the public key into xcenter-config's truststore. See Chapter 3, “Install Xstore
Office” for more information.
1. To import the public key into xcenter-config's truststore, type the following
command in the apache directory:
- Windows:
keytool -import -file server.crt -alias apache-YYYYMMDD
- Linux:
3. When prompted, type y or yes to trust the certificate.
4. Place the truststore file on every Xstore Point of Service register in the field.
- Windows:
-keystore \environment\res\ssl\.truststore
- Linux:

Perform the following procedure to create and deploy a Self-Signed Certificate for
Xstore Suite.
1. Create the certificate directories:
md C:\cert\xstoremobile
cd C:\cert\xstoremobile
2. To create a Keystore and Key, type the following command:
keytool -genkey -keystore keystore -alias
xstoremobile-YYYYMMDD -keyalg RSA -keysize 2048 -ext
If you have to use IP addresses as SAN parameter, see the example below.

Example:
-ext
SAN=DNS:hostname_1,IP:10.198.51.100.1,DNS:hostname_2,IP:10.198
.51.100.2, [...]
Note: You can use any combination of DNS and IPs in the same SAN
parameter separated by commas.

First and Last Name (aka The hostname or IP address StoreName

Common Name) that will be used to access
the server.
Organizational Unit Use this field to remind you XstoreMobile-

what the certificate is used YYYYMMDD
for.
The OU must be different
on each key. (One option is
to add a date to make it
unique).
Organization Name The exact legal name of Oracle

your organization.
City or Locality The city where your Cleveland

State or Province Name The state or province where Ohio

your organization is
located. Cannot be
abbreviated.
Two-letter country code The two-letter ISO US

abbreviation for your
country

(Recommended).
3. To self-sign the Certificate, type the following command:
keytool -selfcert -alias xstoremobile-YYYYMMDD
-keystore keystore -validity 395
5. Change the name of the keystore file to xstore_mobile.keystore.
6. Copy the xstore_mobile.keystore file to the same folder as the Xstore Point of
Service installer.

Xenvironment Certificates
Install the Certificate on Android

1. Export the certificate from the keystore file by typing the following command:
keytool -export -alias xstoremobile-YYYYMMDD -keystore
xstoremobile.keystore -rfc -file xstoremobile-YYYYMMDD.cer
2. Copy the xstoremobile-YYYYMMDD.cer file that was exported to the storage of
the Android device.
5. In the security menu of the Android device, select the Install from storage option
and, when prompted for the name, select the file that was copied to the device's
storage.
Xenvironment Certificates
Generating and Importing the Key File (Windows)

You may use your own keys, or you can create key files. To create your own certificates:
• The steps in this section assume that Sun’s keytool utility has been installed and
added to the system path. See “OpenSSL & Keytool Utility”.
• The key creation steps outlined in this section must be performed on a secure
system: not on a register and not on the server where it will be deployed.
To create and deploy certificates for Xenvironment

To create and deploy Xenvironment certificates:
1. To create a directory structure for key creation, run the following commands:
md C:\cert\environment
cd C:\cert\environment
2. To create a Keystore and Key, type the following command:
keytool -genkey -keystore .keystore -alias xstore -keyalg RSA
-keysize 2048 -ext SAN=DNS:<hostname>[,DNS:<hostname>...]
-validity 395
First and Last Name (aka The hostname or IP address StoreName

Common Name) that will be used to access
the server.

Digital Signatures
Organizational Unit Use this field to remind you Xenvironment-

what the certificate is used YYYYMMDD
for.
The OU must be different
on each key. (One option is
to add a date to make it
unique).
Organization Name The exact legal name of Oracle

your organization.
City or Locality The city where your Cleveland

State or Province Name The state or province where Ohio

your organization is
located. Cannot be
abbreviated.
Two-letter country code The two-letter ISO US

abbreviation for your
country

(Recommended).
3. To self-sign the Certificate, type the following command:
keytool -selfcert -alias xstore -keystore .keystore
-validity 395
5. Copy the .keystore file to Xenvironment ssl directory:
copy .keystore C:\environment\res\ssl
6. Export the certificate from the keystore:
keytool -export -alias xstore -keystore .keystore -file
xstore.cer
7. Import the certificate into the truststore:
keytool -import -alias xstore -keystore .truststore -file
xstore.cer
8. Copy the .truststore file to Xenvironment ssl directory:
copy .truststore c:\environment\res\ssl
Digital Signatures
If you are using .sig digital signature files to validate updates, you will need to
perform additional steps to prepare the system for signature file creation.
Important: When following the instructions in this section (whether

on Linux or Windows), replace “YYYYMMDD” with a current date
string.

Digital Signatures
Perform the proper procedure for your system:

• Digital Signatures - Windows below
• Digital Signatures - Linux
Note: The following procedures assume that OpenSSL has been

installed on your system.
Digital Signatures - Windows

To prepare digital signature file creation on a Windows system, do the following:
1. Type the following command:
set PATH=%PATH%;c:\xstore\windows\jre\bin
2. Type the following command in the C:\cert\sslcert directory:
keytool -genkey -keystore updates.keystore -alias
updates-YYYYMMDD -keyalg RSA -keysize 2048 -ext
SAN=DNS:<hostname>[,DNS:<hostname>...] -validity 395 -
storepass <password>
Where <password> is the keystore password.
a. Answer any and all prompts. Answers to these prompts need to be entered the
same as, and match, the entries you made in step 2 on page 32.
b. When prompted to confirm the values, type y or yes.
c. When prompted, press [Enter] to use the keystore password for the key
password.
3. Type the following command in the c:\cert\sslcert directory:
keytool -certreq -keystore updates.keystore -alias
updates-YYYYMMDD -file updates-YYYYMMDD.req -storepass
<password> -ext SAN=DNS:<hostname>[,DNS:<hostname>...]
4. Type the following command in the C:\ssl\sslcert directory:
c:\OpenSSL-Win64\bin\openssl req -new -x509 -extensions v3_ca
-keyout private\cakey.pem -out cacert.pem -days 3653 -config
openssl.cnf
a. When prompted, enter and confirm the PEM password.
b. When prompted, answer the questions. (NOTE: The questions may appear in a

Organizational Unit Enter the application for which Xenvironment-YYYYMMDD

Name the certificate will be used.
The OU must be different on
each key. (One option is to add a
date to make it unique).

Digital Signatures
Email Address The email address of the person myname@company.com

to be contacted about this
certificate.


organization is located. Cannot
be abbreviated.
Country Name The two-letter ISO abbreviation US

for your country.
Common Name (aka Enter the hostname or IP address Company_Name Certificate

First and Last Name) that will be used to access the Authority
server, or a name for the
certificate.

c:\OpenSSL-Win64\bin\openssl ca -md sha256 -out
updates-YYYYMMDD.cer -config openssl.cnf -infiles updates-
YYYYMMDD.req
a. When prompted, type the password for ./private/cakey.pem.
b. When prompted, type y or yes to sign the certificate.
c. When prompted, type y or yes to commit the certificate.
c:\OpenSSL-Win64\bin\openssl x509 -in updates-YYYYMMDD.cer -out
updates-YYYYMMDD.der.cer -outform DER
keytool -import -file cacert.pem -keystore updates.keystore -
alias myrootca-YYYYMMDD -storepass <password>
a. When prompted, type y or yes to trust the certificate.
keytool -import -trustcacerts -file updates-YYYYMMDD.der.cer
-keystore updates.keystore -alias updates-YYYYMMDD -storepass
<password>
10. Make a copy of cacert.pem and rename the copy to updates.pem.
11. Open the file updates-YYYYMMDD.cer in a text-editing program (for example,
Wordpad).

Digital Signatures
12. Copy the certificate portion of the updates-YYYYMMDD.cer file to the clipboard.
This is the part of the file that begins with the -----BEGIN CERTIFICATE-----
line and ends with the -----END CERTIFICATE----- line.
Note: Include -----BEGIN CERTIFICATE----- and

-----END CERTIFICATE----- in the copy.
13. Open the file updates.pem in a text-editing program (for example, Wordpad).
14. Paste the certificate portion of the updates-YYYYMMDD.cer file to the end of the
updates.pem file and save the updates.pem file.
The final file should appear similar to the following:
-----BEGIN CERTIFICATE-----
MIIEpzCCA4+gAwIBAgIJAMDrmOAxJeeNMA0GCSqGSIb3DQEBBQUAMIGTMRYwFAYD
VQQKEw1NSUNST1MtUmV0YWlsMQwwCgYDVQQLFANSJkQxJzAlBgkqhkiG9w0BCQEU
GGFtZXNrZUBtaWNyb3MtcmV0YWlsLmNvbTEOMAwGA1UEBxMFU29sb24xCzAJBgNV
BAgTAk9IMQswCQYDVQQGEwJVUzEYMBYGA1UEAxMPQWxleGFuZGVyIE1lc2tlMB4X
DTEwMDUxMTE4MDA0NloXDTIwMDUxMTE4MDA0NlowgZMxFjAUBgNVBAoTDU1JQ1JP
Uy1SZXRhaWwxDDAKBgNVBAsUA1ImRDEnMCUGCSqGSIb3DQEJARYYYW1lc2tlQG1p
Y3Jvcy1yZXRhaWwuY29tMQ4wDAYDVQQHEwVTb2xvbjELMAkGA1UECBMCT0gxCzAJ
BgNVBAYTAlVTMRgwFgYDVQQDEw9BbGV4YW5kZXIgTWVza2UwggEiMA0GCSqGSIb3
DQEBAQUAA4IBDwAwggEKAoIBAQDX7JAB8DigCn0TpjA8/c1HI1EPfCkUSJWmCoPC
FZzyDJHAT0KcAI6c6zGQ4wPqI502Kq12aQBwG3+rGyuZ0if/9eM//3FXUpnyOiue
kismbkXvrU87/NMF59boM5N70jG7hyiIbeEydqnxDljHpFLOYgEa31Mh7kANoj2M
KJHK/MrIC862F0qmzjnWkuqIIoF2xuyBzbBSpOMt1JVqmz679gh6O4PF6HpajghQ
pgiy89iEFP+x5DP76BPjEj26yZ483rawCOIHf87VkX8jZo59AgMBAAGjgfswgfgw
A1UdIwSBwDCBvYAULDDh4nTEockZ9E836vTqjP1Kc3uhgZmkgZYwgZMxFjAUBgNV
BAoTDU1JQ1JPUy1SZXRhaWwxDDAKBgNVBAsUA1ImRDEnMCUGCSqGSIb3DQEJARYY
CBMCT0gxCzAJBgNVBAYTAlVTMRgwFgYDVQQDEw9BbGV4YW5kZXIgTWVza2WCCQDA
65jgMSXnjTANBgkqhkiG9w0BAQUFAAOCAQEAPkY4OOPWBjlhJ29523AnR2kY5cji
IOb87I2s6DOedba0IAposGKhCoiZ9RbPf6GB44V87y2fOG9aU3l/7b8pQUW7NtkB
j8M43II+zh7BZ1V9onYi6vNLGfF2l0/yZM6/MaxbQiJ42RF/un5hhVvk23Y7ufw1
WVbhwlVYdEbkyh4SXPfoMyXdwg7HMCDqbED1nT+YtDci0/iFI+an8Xc0lKGIsaG+
TStPa5KW6aZmoaZ32A34W4fLOQamxmJzxxDRzDkvsziIWYzzUARK+vPHxoH/dYuw
fRY4OQ+FbgSzyZj3yA0uD5cpbwBZ0xK8t5kYqufgJH1WFbZ65JucJiL8zw==
-----END CERTIFICATE-----
MIIDZDCCAkwCAxAAATANBgkqhkiG9w0BAQUFADCBkzEWMBQGA1UEChMNTUlDUk9T
LVJldGFpbDEMMAoGA1UECxQDUiZEMScwJQYJKoZIhvcNAQkBFhhhbWVza2VAbWlj
cm9zLXJldGFpbC5jb20xDjAMBgNVBAcTBVNvbG9uMQswCQYDVQQIEwJPSDELMAkG
A1UEBhMCVVMxGDAWBgNVBAMTD0FsZXhhbmRlciBNZXNrZTAeFw0xMDA1MTExODAz
MDBaFw0xMTA2MTAxODAzMDBaMFoxCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJPSDEW
MBQGA1UEChHNTUlDUk9TLVJldGFpbDEMMAoGA1UECwwDUiZEMRgwFgYDVQQDEw9B
Vbs7C/OITctKFro8JbPLwR85D5z7C9QJvzrZzwY6KZTpht+bl4UOxvBlr8wLZNH4
iGOqCUzRz90uSc1hX2jJ7w0WOHb//63bAoBhgva39HUbpM/tjpV3jWV9GfLYR4Xp
bfSdxIE4cSmQlfCsNw9cmzVDeexj6kPIQU9TFKIovAmgiLYxaMCPElDlTvIq4HWq
mviW0MX4aR/TvYyagemNWdaUDa7UxEZuiiua2YP3JKT7VFAe2LTJHKqfgdJLowcY
gNpkA0/3GIzQIKnGCAlTAgMBAAEwDQYJKoZIhvcNAQEFBQADggEBAAWwrp4qPbek
Iu+89+oUv3IImKzF1j58UYwGpSTvsxfLhEZVmdPLft/6oVCvdRi2mpxTrorkaYwl
1xoFiudz79x9J8HoB73WRgQKR/dP9/rfOTI9BkDC2DvSPe5q339y4LxUupKdT66R
yr9sUdZ4bRjYJ8cFyCbxR6g6+v7vGAC/T64vLLaLeJ6Ck8+DaS4FOJJHW9J24ht2
vhU9ptLjZLhi2950zGmH1VXjwuUg6LbxZLxyXKr2P4XAHgdjZDqVGUzLRF5rzXo5
NycMDUHmqPw=

Linux Instructions
15. Move the updates.pem file to the c:\environment\certs directory.

16. Turn on signature validation in the by adding the following setting to the
c:\environment\cust_config\environment.properties file:
security.signaturevalidation=True
17. Save the file.
18. To run Xenvironment, go to c:\environment and run environment.bat.
Linux Instructions
Generating and Importing the Key File (Linux)
In order to run Xenvironment with the GUI, you must import a TLS certificate into the
GUI’s truststore as a key file. This is done through line commands in a command
window. You may use your own keys, or you can use OpenSSL to create key files.
Installing OpenSSL in Linux

Linux installations offer OpenSSL during their install processes. If OpenSSL is not
currently installed on your Linux system, see your Linux installation documentation for
instructions describing how to install OpenSSL. An OpenSSL installation package for
compilation can also be found at: http://www.openssl.org/
Generating the Key File in Linux

To generate a TLS certificate that can be used as a key file, do the following:
1. Open a terminal Command Prompt (for example, xterm).
2. Run the following command in the Command Prompt:
cd /tmp
openssl genrsa 2048 > privkey.pem
This generates the file privkey.pem.
3. Run the following command in the Command Prompt:
openssl req -new -x509 -sha256 -days 365 -key privkey.pem >
cacert.pem
The openssl program prompts you for information.
4. Answer each question with the proper information:
- Country Name: Enter the 2 letter ISO country code for the country where the
register is located. (For the United States, it is “US”).
- State or Province Name: Enter the full name (not the abbreviation) of the state
or province.
- Locality Name: Enter the name of the city or town.
- Organization Name: Enter the name of your company.
- Organizational Unit Name: Enter the application for which the certificate will
be used.
- Common Name: Enter the hostname or IP address of the server that will be used
to access the server, or a name for the certificate.

Linux Instructions
- Email Address: Enter your email address, or the email address of the
administrator responsible for the register systems.
The openssl program generates the file cacert.pem.
Importing the Key File in Linux

To import a key file into the truststore for both the Xenvironment GUI and Xstore Point
of Service, do the following:
1. Open a terminal Command Prompt (for example, xterm).
2. In the Command Prompt, enter the following commands:
export PATH=$PATH:/opt/xstore/linux/jre/bin
keytool -import -keystore /opt/environment/res/ssl/.truststore
-alias xenv -file /opt/cert/sslcert/cacert.pem
The keytool import program prompts you for the keystore password.
3. Enter the keystore password. The default value for the password is “allgoodthings”.
The program displays the following information (note that the information is an
example, and should not match your certificate):
Owner: EMAILADDRESS=******@******.com, CN=******, OU=******,
O=******, L=******, ST=******, C=***
Issuer: EMAILADDRESS=******@******.com, CN=******, OU=******,
O=******, L=******, ST=******, C=***
Serial number: *********************************
Valid from: Mon Feb 16 09:51:08 EST 2009 until: Thu Feb 14
09:51:08 EST 2019
Certificate fingerprints:
MD5: ***********************************************
SHA256: *********************************************************
Trust this certificate? [no]:
The final line prompts whether to trust the certificate.
4. Enter y or yes.
The program displays the following to confirm that the key file was imported:
Certificate was added to keystore
5. In the Command Prompt, enter the following command:
keytool -import -keystore /opt/xstore/res/ssl/.truststore -alias
xenv -file /opt/cert/sslcert/cacert.pem
The keytool import program prompts you for the keystore password.
6. Enter the keystore password. The default value for the password is “allgoodthings”.

Linux Instructions
The program displays the following information (note that the information is an
example, and should not match your certificate):
Owner: EMAILADDRESS=******@******.com, CN=******, OU=******,
O=******, L=******, ST=******, C=***
Issuer: EMAILADDRESS=******@******.com, CN=******, OU=******,
O=******, L=******, ST=******, C=***
Serial number: ************(shortened for brevity here)
Valid from: Mon Feb 16 09:51:08 EST 2009 until: Thu Feb 14
09:51:08 EST 2019
Certificate fingerprints:
MD5: ***********************************************
SHA256: *********************************************************
Trust this certificate? [no]:
The final line prompts whether to trust the certificate.
7. Enter y or yes.
The program displays the following to confirm that the key file was imported:
Certificate was added to keystore
The installation process is complete.
Digital Signatures - Linux

If you are using .sig digital signature files to validate updates, you will need to
perform additional steps to prepare the system for signature file creation.
Important: When following the instructions in this section (whether

on Linux or Windows), replace “YYYYMMDD” with a current date
string.
1. Enter the following command in the /opt/cert/sslcert directory:

keytool -genkey -keystore updates.keystore -alias
updates-YYYYMMDD -keyalg RSA -keysize 2048 -ext
-storepass <password>
a. Answer any and all prompts. When prompted to confirm the values, enter y or
yes.
b. When prompted, press [Enter] to use the keystore password for the key
password.
keytool -certreq -keystore updates.keystore -alias
updates-YYYYMMDD -file updates-YYYYMMDD.req -storepass
<password> -ext SAN=DNS:<hostname>[,DNS:<hostname>...]

Linux Instructions
openssl req -new -x509 -extensions v3_ca -keyout

private\cakey.pem -out cacert.pem -days 3653 -config openssl.cnf
Answer any and all prompts.
export OPENSSL_CONF=/opt/cert/sslcert/openssl.cnf
openssl ca -md sha256 -out updates-YYYYMMDD.cer -config
openssl.cnf -infiles updates-YYYYMMDD.req
openssl x509 -in updates-YYYYMMDD.cer -out
updates-YYYYMMDD.der.cer -outform DER
keytool -import -file cacert.pem -keystore updates.keystore
-alias myrootca-YYYYMMDD -storepass <password>
keytool -import -trustcacerts -file updates-YYYYMMDD.der.cer
-keystore updates.keystore -alias updates-YYYYMMDD -storepass
<password>
9. Make a copy of cacert.pem and rename the copy to updates.pem.
10. Open the file updates-YYYYMMDD.cer in a text-editing program (for example,
emacs or vi).
11. Copy the certificate portion of the updates-YYYYMMDD.cer file. This is the part of
the file that begins with the -----BEGIN CERTIFICATE----- line and ends with
the
-----END CERTIFICATE----- line. (Include BEGIN CERTIFICATE and END
CERTIFICATE in the copy).
12. Open the file updates.pem in a text-editing program (for example, emacs or vi).
13. Paste the certificate portion of the updates-YYYYMMDD.cer file to the end of the
updates.pem file and save the updates.pem file. The final file should appear
similar to the following:
MIIEpzCCA4+gAwIBAgIJAMDrmOAxJeeNMA0GCSqGSIb3DQEBBQUAMIGTMRYwFAYD
VQQKEw1NSUNST1MtUmV0YWlsMQwwCgYDVQQLFANSJkQxJzAlBgkqhkiG9w0BCQEU
GGFtZXNrZUBtaWNyb3MtcmV0YWlsLmNvbTEOMAwGA1UEBxMFU29sb24xCzAJBgNV
BAgTAk9IMQswCQYDVQQGEwJVUzEYMBYGA1UEAxMPQWxleGFuZGVyIE1lc2tlMB4X
DTEwMDUxMTE4MDA0NloXDTIwMDUxMTE4MDA0NlowgZMxFjAUBgNVBAoTDU1JQ1JP
Uy1SZXRhaWwxDDAKBgNVBAsUA1ImRDEnMCUGCSqGSIb3DQEJARYYYW1lc2tlQG1p
Y3Jvcy1yZXRhaWwuY29tMQ4wDAYDVQQHEwVTb2xvbjELMAkGA1UECBMCT0gxCzAJ
BgNVBAYTAlVTMRgwFgYDVQQDEw9BbGV4YW5kZXIgTWVza2UwggEiMA0GCSqGSIb3
DQEBAQUAA4IBDwAwggEKAoIBAQDX7JAB8DigCn0TpjA8/c1HI1EPfCkUSJWmCoPC
FZzyDJHAT0KcAI6c6zGQ4wPqI502Kq12aQBwG3+rGyuZ0if/9eM//3FXUpnyOiue

Annual Distribution Requirements
kismbkXvrU87/NMF59boM5N70jG7hyiIbeEydqnxDljHpFLOYgEa31Mh7kANoj2M
KJHK/MrIC862F0qmzjnWkuqIIoF2xuyBzbBSpOMt1JVqmz679gh6O4PF6HpajghQ
pgiy89iEFP+x5DP76BPjEj26yZ483rawCOIHf87VkX8jZo59AgMBAAGjgfswgfgw
A1UdIwSBwDCBvYAULDDh4nTEockZ9E836vTqjP1Kc3uhgZmkgZYwgZMxFjAUBgNV
BAoTDU1JQ1JPUy1SZXRhaWwxDDAKBgNVBAsUA1ImRDEnMCUGCSqGSIb3DQEJARYY
CBMCT0gxCzAJBgNVBAYTAlVTMRgwFgYDVQQDEw9BbGV4YW5kZXIgTWVza2WCCQDA
65jgMSXnjTANBgkqhkiG9w0BAQUFAAOCAQEAPkY4OOPWBjlhJ29523AnR2kY5cji
IOb87I2s6DOedba0IAposGKhCoiZ9RbPf6GB44V87y2fOG9aU3l/7b8pQUW7NtkB
j8M43II+zh7BZ1V9onYi6vNLGfF2l0/yZM6/MaxbQiJ42RF/un5hhVvk23Y7ufw1
WVbhwlVYdEbkyh4SXPfoMyXdwg7HMCDqbED1nT+YtDci0/iFI+an8Xc0lKGIsaG+
TStPa5KW6aZmoaZ32A34W4fLOQamxmJzxxDRzDkvsziIWYzzUARK+vPHxoH/dYuw
fRY4OQ+FbgSzyZj3yA0uD5cpbwBZ0xK8t5kYqufgJH1WFbZ65JucJiL8zw==
MIIDZDCCAkwCAxAAATANBgkqhkiG9w0BAQUFADCBkzEWMBQGA1UEChMNTUlDUk9T
LVJldGFpbDEMMAoGA1UECxQDUiZEMScwJQYJKoZIhvcNAQkBFhhhbWVza2VAbWlj
cm9zLXJldGFpbC5jb20xDjAMBgNVBAcTBVNvbG9uMQswCQYDVQQIEwJPSDELMAkG
A1UEBhMCVVMxGDAWBgNVBAMTD0FsZXhhbmRlciBNZXNrZTAeFw0xMDA1MTExODAz
MDBaFw0xMTA2MTAxODAzMDBaMFoxCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJPSDEW
MBQGA1UEChHNTUlDUk9TLVJldGFpbDEMMAoGA1UECwwDUiZEMRgwFgYDVQQDEw9B
Vbs7C/OITctKFro8JbPLwR85D5z7C9QJvzrZzwY6KZTpht+bl4UOxvBlr8wLZNH4
iGOqCUzRz90uSc1hX2jJ7w0WOHb//63bAoBhgva39HUbpM/tjpV3jWV9GfLYR4Xp
bfSdxIE4cSmQlfCsNw9cmzVDeexj6kPIQU9TFKIovAmgiLYxaMCPElDlTvIq4HWq
mviW0MX4aR/TvYyagemNWdaUDa7UxEZuiiua2YP3JKT7VFAe2LTJHKqfgdJLowcY
gNpkA0/3GIzQIKnGCAlTAgMBAAEwDQYJKoZIhvcNAQEFBQADggEBAAWwrp4qPbek
Iu+89+oUv3IImKzF1j58UYwGpSTvsxfLhEZVmdPLft/6oVCvdRi2mpxTrorkaYwl
1xoFiudz79x9J8HoB73WRgQKR/dP9/rfOTI9BkDC2DvSPe5q339y4LxUupKdT66R
yr9sUdZ4bRjYJ8cFyCbxR6g6+v7vGAC/T64vLLaLeJ6Ck8+DaS4FOJJHW9J24ht2
vhU9ptLjZLhi2950zGmH1VXjwuUg6LbxZLxyXKr2P4XAHgdjZDqVGUzLRF5rzXo5
NycMDUHmqPw=
14. Turn on signature validation in the cust_config/environment.properties
file with the following setting:
security.signaturevalidation=True
15. Save the file.

Overview
PCI requirements mandate that encryption keys are rotated annually. You must generate
and distribute new certificates every year.
Self-Signed Certificates
If you are using self-signed certificates, the generated certificate will need to be added to
the servers and all client systems.
Refer to “Annual Key Rotation: Self-Signed Certificates” if you are using Self-signed
certificates.

Certificate Authority-Signed Certificates

If you are using CA-signed certificates, the annual distribution of certificates will only
need to be delivered to the servers.
Refer to “Annual Key Rotation: Certificate Authority-Signed Certificates” if you are
using CA-signed certificates.
Tip: Perform the rotation outside of business hours since these

changes will interrupt server traffic.
Important: PCI requirements also mandate that cryptographic key

material or cryptograms such as encryption keys stored by previous
payment application versions must be removed.
Old keys and certificates should be removed once the keys and
certificates reach the end of their usable life.
Such irretrievability is absolutely necessary for PCI.
See “Delete expired certificates and keys” for procedural information.

Annual Key Rotation: Certificate Authority-Signed Certificates
Annual Key Rotation: Certificate Authority-Signed

Certificates
Perform the following steps when using CA-signed certificates.
Note: The steps in this section assume that both OpenSSL and Sun’s
keytool utility have been installed and added to the system path. See
“OpenSSL & Keytool Utility”.
Be sure to replace “YYYYMMDD” with a current date string

throughout this procedure!
For Xstore Point of Service and Xstore Office Application Server

Note: In addition to replacing the alias and certificate signing request
names with updated appropriate names, as was done during the
generation of the initial keys, the originally determined values should
be substituted into this command in the following locations:
• First and Last Name (aka Common Name) should be entered in place of
<common name>
• Organizational Unit should be entered in place of <organizational_unit>
• The OU must be different on each key. (One option is to add a date to make
it unique).
• Organization Name should be entered in place of <organization_name>
• City or Locality should be entered in place of <city>
• State or Province Name should be entered in place of <territory>
• Two-letter country code should be entered in place of <country>
1. To create a new certificate and certificate signing request, type the following
command in the C:\cert\xstore or /opt/cert/xstore directory. The
originally-generated keystore file should be in the working directory.
-dname "CN=<common_name>, OU=<organizational_unit>,
O=<organization_name>, L=<city>, S=<territory>, C=<country>"
b. When prompted, press [Enter] to use the same password as the keystore
(Recommended).
c. Enter the following command in the xstore directory:
keytool -certreq -keystore server.keystore -alias
xcenter-YYYYMMDD -file xcenter-YYYYMMDD.req -ext
d. When prompted, enter the keystore password.

Note: The instructions in this step (step 3) should be performed by

the certificate authority, and assume that the certificate authority was
generated as detailed in “Certificate Authority-Signed Certificates:
Oracle Retail Xstore Office”. If an alternate certificate authority is being
used, appropriate equivalent steps will need to be substituted.
For this example, we will assume that we were given xcenter-YYYYMMDD.req to
work with.
a. Copy xcenter-YYYYMMDD.req to the c:\cert\sslcert or
/opt/cert/sslcert directory on the Certificate Authority system. Secure
channels are not required for receiving the request because no private key is
included in the request file.
b. Enter the following command in the c:\cert\sslcert or
/opt/cert/sslcert directory:
openssl ca -out xcenter-YYYYMMDD.cer -config openssl.cnf
-infiles xcenter-YYYYMMDD.req
f. Enter the following commands in the sslcert directory. This assumes you used
the base path names.
* Windows:
* Linux:
xcenter-YYYYMMDD.der.cer to work with.
a. Copy xcenter-YYYYMMDD.der.cer to the c:\cert\xstore or
/opt/cert/xstore directory. Secure channels are not required for receiving
the signed certificate request file because no private key is included in the file.
b. Enter the following command in the xstore directory:
xcenter-YYYYMMDD.der.cer -keystore server.keystore -alias
xcenter-YYYYMMDD


5. Enter the following command in the xstore directory to back up the existing
deployed keystore file and add the newly created keystore file.
Note: This section assumes that Jetty is installed on the current

system. Substitute the appropriate destination when running this
command.
- Windows:
ren c:\jetty-x.x.x\etc\server.keystore
server.keystore.preYYYYMMDD
copy server.keystore c:\jetty-x.x.x\etc
- Linux:
mv /opt/jetty-x.x.x/etc/server.keystore
/opt/jetty-x.x.x/etc/server.keystore.preYYYYMMDD
cp server.keystore /opt/jetty-x.x.x/etc
6. Update the certificate alias name in the jetty-xcenter.xml file.
For Jetty, the connector that needs to be updated should look similar to the
following. The certAlias will need to be updated to match the alias of the newly
generated key.
<Set name="certAlias">jetty-YYYYMMDD</Set>
7. Restart Jetty to begin using the new key.
For Xservices
<common name>
it unique).
command in the C:\cert\xservices directory. The originally-generated keystore
file should be in the working directory.
SAN=DNS:<hostname>[,DNS:<hostname>...] -validity 395 -dname

"CN=<common_name>, OU=<organizational_unit>,
(Recommended).
c. Type the following command in the C:\cert\xservices or
/opt/cert/xservices directory:
xservices-YYYYMMDD -file xservices-YYYYMMDD.req -ext

Xservices”. If an alternate certificate authority is being used,
appropriate equivalent steps will need to be substituted.
For this example, we will assume that we were given xservices-YYYYMMDD.req

to work with.
a. Copy xservices-YYYYMMDD.req to the c:\cert\sslcert or
/opt/cert/sslcert directory on the Certificate Authority system. Secure
channels are not required for receiving the request because no private key is
included in the request file.
b. Type the following command in the C:\cert\sslcert or
/opt/cert/sslcert directory:
openssl ca -out xservices-YYYYMMDD.cer -config openssl.cnf
-infiles xservices-YYYYMMDD.req
f. Enter the following command in the C:\cert\sslcert or
/opt/cert/sslcert directory. This assumes you used the base path names.
* Windows:
* Linux:


xservices-YYYYMMDD.der.cer to work with.
a. Copy xservices-YYYYMMDD.der.cer to the c:\cert\xservices or
/opt/cert/xservices folder. Secure channels are not required for receiving
the signed certificate request file because no private key is included in the file.
b. Type the following command in the C:\cert\xservices or
xservices-YYYYMMDD.der.cer -keystore keystore -alias
xservices-YYYYMMDD
5. Remove the previous year's server certificate from the keystore file by entering the
following command in the in the C:\cert\xservices or
/opt/cert/xservices directory.
For this example, we will assume that the previous year's keystore was named
xservices-YYYYMMDD. The appropriate alias will need to be substituted as
needed.
keytool -delete -keystore keystore -alias xservices-YYYYMMDD
6. Enter the following commands in the C:\cert\xservices or
/opt/cert/xservices directory to back up the existing deployed keystore file
and add the newly created keystore file.
This section assumes that Xservices is installed on the current machine. Substitute
the appropriate destination when running this command.
- Windows:
ren c:\xservices-config\keystore keystore.preYYYYMMDD
copy keystore c:\xservices-config
- Linux:
mv /opt/xservices-config/keystore
/opt/xservices-config/keystore.preYYYYMMDD
cp keystore /opt/xservices-config
7. Restart Xservices to begin using the new key.

For Apache
Note: This process creates new files, so make sure you retain copies of
the previous server.key, server.csr, and server.crt files for
archival purposes. Oracle recommends creating a subdirectory to hold
the three files used previously and renaming the files with a date or
other identifying information before following these steps.
command in the C:\cert\apache or /opt/cert/apache directory:
openssl req -nodes -days 395 -newkey rsa:2048 -keyout
server.key -out server.csr -config
<location of ssl conf file>/openssl.cnf
a. Answer all questions when prompted. See “To create and deploy Certificate
Authority-Signed Certificates for Apache”.
2. Submit the resulting csr file to the certificate assigning authority to be signed.

Apache”. If an alternate certificate authority is being used, appropriate
equivalent steps will need to be substituted.
For this example, we will assume that we were given server.csr to work with.
a. Copy server.csr to the c:\cert\sslcert or /opt/cert/sslcert folder
on the Certificate Authority system. Secure channels are not required for
receiving the request because no private key is included in the request file.
b. Type the following command in the C:\cert\apache or /opt/cert/apache
directory:
openssl ca -out server.crt -config openssl.cnf -infiles
server.csr
f. Return the resulting crt file to the party that submitted the request file along
with the cacert.pem file. Secure channels are not required because the signed
certificate file does not contain any private key information.
4. Remove the previous year's server.csr and server.key from the conf folder
(apache-x.x.x\conf). Remember to rename and move the previous certificates
for archival purposes.
5. Place the new files in the apache-x.x.x\conf folder, replacing the previous year’s
files.
6. Restart Apache to begin using the new key.

Annual Key Rotation: Self-Signed Certificates

Important: Be sure to replace “YYYYMMDD” with a current date
string throughout this procedure!
For Xstore Point of Service and Xstore Office Application Server

<common name>
it unique).
1. To create and self-sign a new certificate, type the following command in the
C:\cert\xstore or /opt/cert/xstore directory. The originally-generated
keystore file should be in the working directory.
-dname "CN=<common_name>, OU=<organizational_unit>,
(Recommended).
c. Type the following command in the xstore directory:
keytool -selfcert -alias xcenter-YYYYMMDD -keystore
server.keystore -validity 395
2. To export the Certificate, type the following command in the C:\cert\xstore or
/opt/cert/xstore directory:
keytool -export -alias xcenter-YYYYMMDD -keystore
server.keystore -rfc -file xcenter-YYYYMMDD.cer

3. To import the Certificate into Xstore Point of Service's Truststore, type the following
command in the xstore directory.
Note: The following command assumes that the existing truststore

file is in the \xstore\res\ssl or /opt/xstore/res/ssl
directory on the current system. If that is not the case, substitute the
appropriate path.
- Windows:
\xstore\res\ssl\.truststore -alias xcenter-YYYYMMDD
- Linux:
/opt/xstore/res/ssl/.truststore -alias xcenter-YYYYMMDD
b. When prompted, type y or yes to trust the certificate.
4. Deploy the updated truststore file to all Xstore Point of Service registers.
5. Once the new truststore has been fully rolled out, back up the existing deployed
keystore file and add the newly created keystore file by running the following
commands in the C:\cert\xstore or /opt/cert/xstore directory:
Note: This section assumes that Jetty is installed on the current

machine. Substitute the appropriate destination when running this
command.
- Windows:
ren c:\jetty-x.x.x\etc\server.keystore
server.keystore.preYYYYMMDD
copy server.keystore c:\jetty-x.x.x\etc
- Linux:
mv /opt/jetty-x.x.x/etc/server.keystore
/opt/jetty-x.x.x/etc/server.keystore.preYYYYMMDD
cp server.keystore /opt/jetty-x.x.x/etc
6. Update the certificate alias name in the jetty-xcenter.xml file. On Jetty 9.x.x,
the jetty-xcenter.xml is stored in the C:\jetty-x.x.x\etc or
/opt/jetty-x.x.x/etc directory.
For Jetty 9.x.x, the connector that needs to be updated should look similar to the
following. The certAlias will need to be updated to match the alias of the newly
generated key:
<Set name="certAlias">jetty-YYYYMMDD</Set>
7. Restart Jetty to begin using the new key.

For Xservices
<common name>
it unique).
1. To create and self-sign a new certificate, type the following commands in the
C:\cert\xservices or /opt/cert/xservices directory. The originally-
generated keystore file should be in the working directory.
SAN=DNS:<hostname>[,DNS:<hostname>...] -validity 395 -dname
"CN=<common_name>, OU=<organizational_unit>,
(Recommended).
c. Type the following command in the C:\cert\xservices or
keytool -selfcert -alias xservices-YYYYMMDD -keystore
keystore -validity 395
2. Remove the previous year's server certificate from the keystore file by running the
following command in the C:\cert\xservices or /opt/cert/xservices
directory.
For this example, we will assume that the previous year's keystore was named
xservices-YYYYMMDD. The appropriate alias will need to be substituted as
needed.
keytool -delete -keystore keystore -alias xservices-YYYYMMDD

3. Back up the existing deployed keystore file and add the newly created keystore file
by running the following commands in the C:\cert\xservices or
/opt/cert/xservices directory.
Note: This section assumes that Xservices is installed on the current

machine. Substitute the appropriate destination when running this
command.
- Windows:
ren c:\xservices-config\keystore keystore.preYYYYMMDD
copy keystore c:\xservices-config
- Linux:
mv /opt/xservices-config/keystore
/opt/xservices-config/keystore.preYYYYMMDD
copy keystore /opt/xservices-config/
4. Restart Xservices to begin using the new key.
For Apache
Note: This process creates new files, so make sure you retain copies of
the files for archival purposes. Oracle recommends creating a
subdirectory to hold the files used previously and renaming the files
with a date or other identifying information before following these
steps.
1. Create and self-sign a new certificate by running the following command in the
C:\cert\apache or /opt/cert/apache directory:
openssl req -x509 -nodes -days 395 -newkey rsa:2048 -keyout
server.key -out server.crt
a. Answer all questions when prompted. See “To create and deploy Self-Signed
Certificates for Apache”.
2. Enter the following command in the C:\cert\apache or /opt/cert/apache
directory to import the server.crt into xcenter-config's truststore.
- Windows:
- Linux:
b. When prompted to trust the certificate, type y or yes.
3. Place the Truststore file on every Xstore Point of Service register in the field.
into Xenvironment's Truststore.

Why Certificates Are Used
- Windows:
-keystore\environment\res\ssl\.truststore
- Linux:
Why Certificates Are Used

When working with public/private key encryption, it is important to identify the goals of
using certificates. We only care about a subset of certificates capabilities. This will aid us
later in weighing the advantages and disadvantages of several different certificate
management strategies. Anyone who isn't familiar with X.509 may want to consider
additional reading to gain some familiarity with Public-Key Infrastructure standards.
Certificates can be used for a number of purposes:
1. Encryption - A piece of sensitive data can be encrypted with a public key. It can then
only be decrypted using the private key.
2. Signing - To create a signature on a piece of data using your private key. Others can
later use your private key to verify that the piece of data is identical to the data that
you signed.
3. Authentication - You prove that you are who you say you are by encrypting a
known piece of information using the private key. Another party can then decrypt
the information using the public key and verify that the result is the same as what
was requested to be encrypted. You can also prove that you are who you say you are
by being able to decrypt and use a piece of data that was encrypted using the public
key.
Of these uses, only encryption is required when Xstore Point of Service communicates
with external systems. Certificates are used at the beginning of a TLS session to create a
secure channel for passing other information. This means that Certificate Revocation
Lists will not come into play in this document.
Types of Certificate Management

Generally speaking, there are two management strategies that can be used for the
certificates needed by the Xstore Point of Service family of products. Certificates can be
signed by a Certificate Authority (CA), or they can be Self-Signed.
Certificate Authority
A CA can be authenticated by another CA, or it can be a Root Certificate Authority. For
eCommerce, a chain of CAs will always end with a public Root Certificate Authority.
This is because a Root Certificate Authority must be "trusted" by the client machine to
operate smoothly. A web browser will show a warning if the server's certificate was not
signed by a trusted root CA out-of-the-box. In the case of CA-signed certificates, the
browser warnings can be avoided by importing the CA's cert into the trusted
certification providers list. A Java program without special coding will fail to connect if
the certificate does not have a signature from a trusted CA.

Types of Certificate Management
Web browsers include a database of trusted public Certificate Authorities when they are
distributed. Additional trusted certificates can typically be imported through a menu
within the web browser. Java distributions have a similar database of trusted public
Certificate Authorities, but any additional certificates must be managed by a program
written in Java. These are typically stored in a truststore that a Java program can
reference.
If you already have an internal CA set up with a certificate that was signed by a public
CA (VeriSign, Entrust, etc.), any certificates issued by your CA can be used without
distributing that public CA's trust information. Only the internal CA's information
would need to be distributed.
If you don't already have such a CA set up, you can save yourself the cost of a signed CA
certificate without the extra management overhead of self-signed certificates by setting
up an internal CA and publishing the trust information in the appropriate locations in
your infrastructure. Such a CA is sometimes called a Root Certificate Authority or Root
CA.
Once you add a Root CA's certificate to the various Certificate Trust Lists (CTLs), any
certificates signed by this Root CA will work the same as those signed by a public CA
like VeriSign, Entrust, and many others.
Refer to “Certificate Authority-Signed Certificates: Oracle Retail Xstore Office” or
“Certificate Authority-Signed Certificates: Xservices” for more information.
Self-Signed Certificates
If a public key certificate is not signed by a Certificate Authority, it is said to be "self-
signed”. Since no external entity has "signed" the certificate, you have only the word of
the certificate itself that it is valid. For a self-signed certificate to function like a certificate
issued by a public CA, the certificate must be added to the CTL on each client.
Refer to “Self-Signed Certificates: Oracle Retail Xstore Office” or “Self-Signed
Certificates: Xservices” for more information.

Where Certificates Are Used
Where Certificates Are Used

Xstore Point of Service to Xstore Office Application Server
The Xstore Office application server opens an HTTPS socket for Xstore Point of Service
requests. The server certificate is stored in a Java keystore.
Xstore Point of Service to Xenvironment

Xenvironment opens an HTTPS socket for web service. The server certificate is stored in
PEM format in the Xenvironment installation.
JMX console
When Xstore Point of Service is running, it opens port 2020 for its JMX console. The
server certificate is stored in the Java keystore at xstore/res/ssl/.keystore. The
certificate stored under the "xstore" alias is used by default. The keystore password lives
in the system.properties file.
Since sensitive data is never displayed in the JMX console, you may be wondering why
we use HTTPS for this portal. HTTPS is used to protect the login password that is passed
from the browser to Xstore Point of Service when accessing the JMX console. Since this
password is not cardholder data, the default public key certificate was created with an
expiration date in the future. The current certificate is set to expire on October 22, 2025,
ten years after it was created.
The certificate for the JMX console is typically managed as part of an Xstore Point of
Service build, but if you have distributed the certificate for an internal CA across your
infrastructure, it might make sense to change Xstore Point of Service's JMX console to
use a certificate signed by that CA.
In addition to the JMX Console, Xstore Point of Service opens an additional HTTPS port
using the same certificate that is used for the JMX Console. This port is used for
communication from the environment to Xstore Point of Service (primarily to see the
messages field with closing steps).
Xenvironment and Xstore Office to Web Server

Xenvironment opens an HTTPS socket to download update and deployment files.
Xenvironment also opens an HTTPS socket to upload pospoll data.
Oracle Retail Xstore Office opens an HTTPS socket to upload update and deployment
files. The server certificate is stored in PEM format on the web server.
Annual Requirements
PCI requirements mandate that encryption keys are rotated annually. This means that
you must generate and distribute new certificates every year.
• If you are using self-signed certificates, the generated certificate must be added to
both the servers and all client systems.
• If you are using CA-signed certificates, the annual distribution of certificates would
only need to deliver them to the servers since a signing CA typically only expires
every ten years.
As a result, if you have a certificate server, the annual distribution of keys is easier
because there are fewer places that have to be maintained.

Choosing a Certificate Management Strategy
See “Annual Distribution Requirements” for the steps you must take each year to avoid
expired certificates.
Choosing a Certificate Management Strategy

There are advantages and disadvantages of both signed and self-signed certificates. For a
certificate to be usable, it must not be expired, and it must be trusted.
Certificates signed by a CA
If a certificate is signed by a CA, only the certificate of the signing CA needs to be in the
Certificate Trust List (CTL) for the certificate to be trusted. The public key certificate for
your internal CA will be maintained by InstallX for Xstore Point of Service builds.
Self-signed Certificates
For a self-signed certificate to be trusted, the certificate itself must be added to the CTL.
Certificates suspected to be compromised

Another decision point to consider when selecting to use self-signed certificates or not is
the ease of distributing a new certificate.
If using a self-signed certificate, it must be distributed to each client (each register
running Xstore Point of Service) and then installed on the server.
With the use of trusted certificate authority, a new certificate would only need to be
installed on the server.
Terms used in this section

Certificate
An electronic document consisting of a public key and an electronic signature.
Certificate authority
An entity that issues digital certificates for use by other parties.
Certificate signing
The process of adding an additional signature to the certificate by a certificate authority.
Certificate trust list
A database of trusted certificates. These could be public Root CAs, internal CAs, or
individual server certificates.
Keystore
An encrypted file storage format that is defined by Java's cryptography framework.
Keystores can be used to store public/private keys or secret keys. Xstore Point of Service
only uses keystores for public/private keys.
Keytool
A utility that comes with the Java SDK for generating certificates. Additional
information on keytool can be found in the Javadoc at Sun's website.
OpenSSL
A cryptography toolkit implementing Transport Layer Security (TLS v1.2) network
protocols and related cryptography standards required by them.

Private key
The half of a public/private key pair that is secured. In public/private key encryption, a
private key is used to decrypt information.
Public key
The half of a public/private key pair that is openly shared. In public/private key
encryption, a public key is used to encrypt information.
Public/private key pair
A set of asynchronous keys that are generated at the same time. In public/private key
encryption, data encrypted with the public key can be decrypted using the private key.
Root certificate authority
A root certificate authority is a public certificate authority that is typically included in
standard certificate trust lists.
Self-signed certificate
A certificate whose only signature is one created with the private key that goes with the
public key that is part of the certificate.
Truststore
A keystore that contains public keys for client and servers to be trusted for TLS
communication.


C
About Xstore Suite GenKeys
Overview
In the interest of data security, retailers require the ability to manage the components of
credit and debit card data encryption. Oracle has provided a utility which a customer
can use to manage the keys for encrypting this sensitive data.
The Payment Card Industry Data Security Standard (PCI DSS) governs the storage and
protection of debit and credit card account data anywhere it is stored. This standard has
many requirements associated with it that relate both to your Point Of Sale and
Corporate applications. This utility should be properly secured on your corporate
network and access limited to "need to know" employees within your organization.
One of the PCI requirements states that retailers are responsible for rotating their
encryption keys on at least an annual basis. GenKeys provides the ability to comply with
this requirement by allowing you to set the effective and expiration dates for the keys.
Multiple keys can be created by changing the effective and expiration dates in the
configuration file and running the utility.
Encryption keys should have overlapping effective and expiration dates to account for
situations where returns or cancelled layaways might require an older key to process the
transaction. The overlap should be consistent with your corporate return and special
transaction cancellation policies.
The encryption key files are considered extremely sensitive information since they are
used to encrypt your customers' cardholder data. Due to this fact, Oracle will not store or
create a customer's production cipher key file on its corporate network, nor will Oracle
accept a production cipher key file in any form. This policy has been adopted to provide
additional security protection to our customers. Accordingly, Oracle will not include the
customer's cipher key file in their PCI release. The customer is responsible for creating
the file and distributing it to their stores prior to deploying their PCI release.
Encryption keys at corporate must be kept as long as the data that is encrypted using
those keys is kept.
Note: See “Delete expired certificates and keys” for more information
about removing old keys. Old keys and certificates should be removed
once the keys and certificates reach the end of their usable life.
The PCI DSS states, "Keep cardholder data storage to a minimum. Develop a data
retention and disposal policy. Limit storage amount and retention time to that which is
required for business, legal, and/or regulatory purposes, as documented in the data
retention policy". The development and implementation of a Data Retention Policy
(DRP) is a significant factor in the overall security of your environment.
About Xstore Suite GenKeys C-1

About Encryption Key Expiration - Credit Ciphers Only
A DRP forms an important foundation for helping to manage an organization's data. The
creation of a DRP is a complex task that requires exhaustive research and the assistance
of qualified legal counsel. The scope of your DRP should reach far beyond the PCI DSS,
and you should work closely with your legal counsel to ensure your compliance with the
laws and governmental regulations that pertain specifically to your organization.
Upon implementation of your DRP, you should contract with a Visa-approved PCI
assessment company to review the DRP's impact on the storage of payment card data, in
compliance with Requirement #3 of the PCI DSS.
About Encryption Key Expiration - Credit Ciphers Only

Once the encryption key expires, the Point Of Sale application will alert the user that the
current key is expired each time the application is started, and each time a user enters
the tender screen. For this reason, it is important to be prepared and deploy a new key
before the existing one expires. This will prevent unnecessary calls to your help desk and
additional inconveniences to your store associates.
Key Types Overview

The Generate Keys Utility provides you with three different key types from which to
choose:
• Initial cipher keys (all keys) - These should be generated during your initial
installation of Xstore Point of Service, and should only be changed if it is suspected
that they have become compromised. These are generally created by Oracle as part
of your initial configuration. Output files are as follows: config.cip,
ipclog.cip, log4jenc.cip, rcpt.cip
• Rotating cipher keys (all keys) - These cipher key files should also be generated
during your initial Xstore Point of Service installation, and on a regular basis, so that
newly effective keys are in place in advance of the previous key expiring. Output
files are as follows (YYYY-MM-DD = effective date of key): config.YYYY-MM-
DD.cip, ipclog.YYYY-MM-DD.cip, log4jenc.YYYY-MM-DD.cip,
rcpt.YYYY-MM-DD.cip
• Rotating cipher keys (credit and debit card keys only) - This option is used to
generate rotate keys for credit and debit card encryption. Output files are as follows
(YYYY-MM-DD = effective date of key): ccenc.YYYY-MM-DD.cip
Important: Your ccenc*.cip file should be rotated yearly. However, if

a compromise is suspected, new keys should be deployed
immediately.
You must choose which type of key(s) you want to create, and modify each section of
gen-keys.conf accordingly. All other sections, with the exception of section 4 and
possibly section 5 if it is being used, must be completely commented out (begin each line
with the "#" character). See “Create Cipher Key Files” of Chapter 3, “Install Xstore
Office” or “Create Cipher Key Files” of Chapter 5, “Install Xstore Point of Service” for
procedural information.
C-2 Implementation and Security Guide

Cipher Health Codes
A description of each key file is noted below:
File Description
ccenc*.cip Contains the key used to encrypt credit and debit card data. This file should
be rotated yearly unless a compromise is suspected at which time you should
deploy a new key immediately.
config*.cip Contains the key used to encrypt any configuration file. For example,
database connection information
pinfo.cip Contains the key used to encrypt personal information. For example, Social
Security Numbers.
rcpt*.cip Contains the key used to encrypt the copy of the receipt stored in the Xstore
Point of Service database.
Cipher Health Codes

During Xstore Point of Service's pre-flight check, the condition of Xstore Point of
Service's encryption environment is analyzed to make sure that all the components are
in order. A cipher health code will provide an explanation of why the pre-flight check
failed. These codes are displayed to the Xstore Point of Service user in an error message,
and can also be found in the xstore.log file. The possible cipher health codes are
listed below.
Cipher Health Level What It Means How To Fix It
GOOD At least one good cipher is NA

available.
EXPIRED Only expired ciphers are Generate a cipher with both an

available. Encryption will still effective date and an expiration
occur, but a warning will be date that are current.
displayed during each
transaction.
NOT_YET_EFFECTIVE The best cipher option is not yet Generate a cipher with both an
effective. Encryption will still effective date and an expiration
occur, but a warning message date that are current.
will be displayed during each
transaction.
FAILOVER The fail-over cipher is being Verify that valid cipher files are
used. Encryption will still occur, in place for "ccenc" and that the
but a warning message will be "dtv.CustomerId" system
displayed during each property matches the value used
transaction. to generate the key. Remember,
the customer ID is case-sensitive.
DEFAULT_KEY A cipher with no effective date is Generate a cipher with both an

being used. Encryption will still effective date and an expiration
occur, but a warning message date that are current.
will be displayed during each
transaction.
NO_EXPIRATION The most current cipher has no Generate a cipher with both an
expiration date. Encryption will effective date and an expiration
still occur, but a warning will be date that are current.
displayed during each
transaction.
Implementation and Security Guide C-3

Open Format Export
Cipher Health Level What It Means How To Fix It
NONE No encryption can take place. Make sure that Unlimited

Xstore Point of Service should Cryptography support is
not be able to fully start. available in the JVM.
Open Format Export

If a valid public key was made available to the gen-key process, a "ciphers.csv" file will
have been created. There will be one entry in the file for each cipher that has been
generated.
Field Contents Usage
use The usage code of the cipher. (for In combination with the effective date, the
example, ccenc) usage uniquely identifies a cipher.
eff The effective date of the cipher In combination with the usage code, the
in YYYY-MM-DD format. (for effective date uniquely identifies a cipher. At
example, 2014-01-01) the time of encryption, the effective date is a
criterion when picking one cipher ahead of
another. At decryption, the effective date is
used to pick the same cipher used for
encryption.
exp The expiration date of the cipher The effective date is used as a criterion for
in YYYY-MM-DD format. (for picking one cipher over another.
example, 2014-12-31)
id The hexadecimal values that will This information can be used to pick a cipher
appear as the first 8 bytes in data at the time of decryption. This is included to
that was encrypted using this avoid mistakes in calculating this value in an
cipher. for example, external system.
3E3E3E30E5653201 would
indicate that an account number
credit card encrypted with this
cipher would start with the bytes
0x3E, 0x3E, 0x3E, 0x30, 0xE5,
0x65, 0x32, and 0x01.
alg The algorithm in use for this The same algorithm that was used to encrypt
cipher. for example, AES/CBC/ the data must be used when decrypting the
PKCS5Padding data.
key The randomly generated key The key is used to encrypt or decrypt data.
that is always used by this
cipher. The key is encrypted
using the public key that was
provided and Base-64 encoded.
iv The randomly generated The initialization vector is used when setting

initialization vector. The up the encryption space for encryption or
initialization vector is encrypted decryption. By using a randomly generated IV
using the public key that was instead of zeros, the key size is effectively
provided and Base-64 encoded. increased.
md5 The MD5 of the CIP file that was This could be used to make sure the
created. information you have in the ciphers.csv
matches up with a given CIP file.

Working with Data Encrypted Using Xstore Point of Service

The Xstore Point of Service encryption format supports encryption without requiring an
additional field to identify the key used to encrypt the data. This is accomplished by
adding a header to the encrypted data. The following exercise is meant to be used in
combination with some example code that you may have received along with this
documentation.
Generate Key 1
Let's say that we have generated a key for the "ccenc" usage with an effective date of
January 1, 2015 and an expiration date of December 31, 2015. The console output would
be recorded in xstore-wrapper-######.log where ###### is today's date.
Two files would be created: ciphers.csv and ccenc-2015-01-01.cip.
Console
generated ccenc eff:2015-01-01 exp:2015-12-31
--ALL CIPHERS--
***********ccenc.2015-01-01***********
v4 eff:2015-01-01 exp:2015-12-31 alg:AES/CBC/PKCS5Padding
keysize:256 (C:\genkeys\res\keys\ccenc.2015-01-01.cip)
v4 eff:FAILOVER_INSTANCE exp:2999-12-31 alg:AES/CBC/PKCS5Padding
keysize:256 (FAILOVER)
v3 eff:FAILOVER_INSTANCE exp:2999-12-31 alg:AES/ECB/PKCS5Padding
ciphers.csv Contents
use,eff,exp,id,alg,key,iv,md5
ccenc,2015-01-01,2015-12-31,3E3E3E3055773301,AES/CBC/
PKCS5Padding,N5zu5iN7uwGI2nMI5XT+N8hhZFyg04MzH3br1/
JCH06wbONKIfcv6PN44rgSlpNddZEtkLbYRCjiggxhXRQpOQmy3QqyKLNZKfDlntR
T/GZdGp4XSAPE1N/T3O7ldOgPMG82bm6Mm9164KBgxke5f/
CPOtHPI0ZNVSmPBG7l1j7D+ItAUMkyKaVkngjp6yQncBpnCrihF9/
p6SQeUrrjiLWX53WW8lhKNg62B2SehOGHqs/45r/
ZAkkCDWWpKmWLKt1ebOAcvyePGn6Col2RwvH4ajvxsil6en935CsGn4pkgUtoEeEm
rPJnhERWrtejTMMsWHw6w37g9OzhYr4nwQ==,DVV+G/
lPX30M56A9hmgQhycwlZDu0SfpR2aMvnEp734xiHeckWgZ4SXicJE+dUuCUf7OUC1
JEyZ5xUgDGXtLe6Sa/eOCsfbS090v3UL5osAK0QRcwdxb6W2osRTevVnZJp3d/
VgHJKa9PuAjU0PbCLlqEGcdy5mBsfBFpUVcYlEC7EHtmSd6MpZnIvYnp1hyB92S8J
YpTlk7mcTpOGyAKFk95IG77acHoaC8eGNCLE+RlyOmtPBZw8lGzVcSVoAPb3DmY3X
hdKmJG/S6rtoqhEyAIOkp8mrTZvvpoCNTJSD/pF8iM25NsDV9gzud+l/
0ghlT7lhJ7Nj7tkZWTS6mdQ==,9c070f91cf349b6a02063d8589318f21
ccenc.2015-01-01.cip Contents
*v4.DTV.KqSEI/tbGDsVgH74DJ3sAg==.mUXmubP13L2pnDL2/
0e9SRZzLjl2oH0jtJ6+mPRvxTw92nXN6d/
5+Yp4fQTaDhmtrlTLC42jf8Qn8AB4dMf/
VhrZErglr1H8BRXmNKisY7Oy653i5Ft2gEJ6UYivjs5j2ei7zpDGJORiH5UQHQB7N
A==

Deploy Key 1
Let's say we deploy the CIP file to a register and tender a transaction with credit card
number 4444111122223333.
ttr_credit_debit_tndr_lineitm.acct_nbr Contents
Pj4+MFV3MwFSsSP+mTAGnNn/OU2xTFfY37RC3u1NDIjeazC9AV/Zxw==
Generate Key 2
Now, we generate another key with effective date February 2, 2015 and expiration date
December 31, 2015. A line is appended to ciphers.csv and the file ccenc-2015-02-01.cip is
created.
Console
generated ccenc eff:2015-02-01 exp:2015-12-31
--ALL CIPHERS--
***********ccenc***********
v3 eff:FAILOVER_INSTANCE exp:2999-12-31 alg:AES/ECB/PKCS5Padding
ciphers.csv Contents
use,eff,exp,id,alg,key,iv,md5
ccenc,2015-01-01,2015-12-31,3E3E3E3055773301,AES/CBC/
PKCS5Padding,N5zu5iN7uwGI2nMI5XT+N8hhZFyg04MzH3br1/
JCH06wbONKIfcv6PN44rgSlpNddZEtkLbYRCjiggxhXRQpOQmy3QqyKLNZKfDlntR
T/GZdGp4XSAPE1N/T3O7ldOgPMG82bm6Mm9164KBgxke5f/
CPOtHPI0ZNVSmPBG7l1j7D+ItAUMkyKaVkngjp6yQncBpnCrihF9/
p6SQeUrrjiLWX53WW8lhKNg62B2SehOGHqs/45r/
ZAkkCDWWpKmWLKt1ebOAcvyePGn6Col2RwvH4ajvxsil6en935CsGn4pkgUtoEeEm
rPJnhERWrtejTMMsWHw6w37g9OzhYr4nwQ==,DVV+G/
lPX30M56A9hmgQhycwlZDu0SfpR2aMvnEp734xiHeckWgZ4SXicJE+dUuCUf7OUC1
JEyZ5xUgDGXtLe6Sa/eOCsfbS090v3UL5osAK0QRcwdxb6W2osRTevVnZJp3d/
VgHJKa9PuAjU0PbCLlqEGcdy5mBsfBFpUVcYlEC7EHtmSd6MpZnIvYnp1hyB92S8J
YpTlk7mcTpOGyAKFk95IG77acHoaC8eGNCLE+RlyOmtPBZw8lGzVcSVoAPb3DmY3X
hdKmJG/S6rtoqhEyAIOkp8mrTZvvpoCNTJSD/pF8iM25NsDV9gzud+l/
0ghlT7lhJ7Nj7tkZWTS6mdQ==,9c070f91cf349b6a02063d8589318f21
ccenc,2015-02-01,2015-12-31,3E3E3E30B9773301,AES/CBC/
PKCS5Padding,M2X6VxBHc/
dgDsudVtn7EMW9nQ4xKRu8eBI5gKNfz4ajYj45zb2TS4fOCiMxu/
nmQiQIqKMO+fc/IZ9YHgCDS6etNVcLEK3cSHxo65XboNm/
ojTiWzDYN62PlsKJfHY9OetNuavOnGYFLitNuql8O1jC0J1zIgTTZRgL8qSm6bGdk
MmfRT3u6QNjJEMUFtYIVSNGfAgXtFm0jAaBHvL3vFlmN64AatuTgFBLkIJbbCNe5f
wsxnq3ZptI/Uo5sMrR4fgLGSxlbWOhEgbFu+rlEk+MT8JS12/
424Brcx762Q9AUPdkT4P+yWqbqj4muGmt+PIeE13xs9vChFTjyJmMHQ==,gNDiX8t

Console Cipher Details
VJW8+WEnpb2wjb5FuszSx4y0FHnjfqIx/
3NmcmwiKUXPZsRr5rkCiCCF0r3k2sAwfwsdS4QMc9AgwA0JZdqzRVWWdcNwrI8jyg
sm1VcD40q3QGFALfS8RFG7RWMLg3/
Jw1evF3h1vJMKwaQFh9cO5m2kYunoJ53aFQy2gV/qEqWPEbxcJpUt/
8DoFQduhTGyG9gY3uUfhwCJ80Sp4JtZnXJOL3Ngq1P4lGuEnQkdOhce1N/
YmWmvE7w53kj+/
tIvgXEdQINRphxpR7guqoDp5AA0Vr0UpmDa1O0kXRvaDXhHrjbG+RsP0wItV02ow5
aflnPdWh3yT0iFT7Q==,08894dfc84e285cec371656517785c69
ccenc.2015-02-01.cip Contents
*v4.DTV.zpepeYYyGv9Nernx2NlvfA==.yqqVr9k7Eb8H90Z+qFOIMm4Rbi7aS+c5
Ua+GlzBnLey0FbGl5Zs1SC0oI9lGlNeAkWgAs0FuspE+i8Yb2TgRFzbBWXymLVCD/
80GvfA0WA4TZNUi2U3PqndjoUjyOoS9XwkCZ9tLM8u4svuI9j+sug==
Deploy Key 2
Let's say we deploy the new key on February 2, 2015 and ring another transaction with
account number 4444111122223333.
ttr_credit_debit_tndr_lineitm.acct_nbr Contents
Pj4+MLl3MwHSl+0u9d8Euu2HeEA6pdwhbWoKfpfM1pV6jkkkSyRSGQ==
Identifying the Key for Decryption

In the main method of "example.decrypt.DecryptExample", we see that we are
decrypting each of the results we would receive in a PosLog. The library method
dtv.util.Base64.base64ToByteArray(java.lang.String) is used to decode the base-64
encoded text resulting in the following bytes.
3e 3e 3e 30 b9 77 33 01 d2 97 ed 2e f5 df 04 ba |>>>0.w3.........|
ed 87 78 40 3a a5 dc 21 6d 6a 0a 7e 97 cc d6 95 |..x@:..!mj.~....|
7a 8e 49 24 4b 24 52 19 |z.I$K$R.|
You may notice that the first four bytes are ">>>0". This indicates that the data was
encrypted by a version of the library that supports key rotation. The next four bytes are
the effective date of the cipher used to encrypt the data. To determine the date, convert
the four bytes into a 32-bit integer. In this example, the resulting integer is 20150201.
To simplify matters, this is where the ID comes into play. Notice the first 8 bytes of the
data are 3E 3E 3E 30 b9 77 33 01. Now notice that the ID for the 2nd cipher we generated
is 3E3E3E30b9773301. The ID is the hexadecimal values for the first eight bytes of any
data encrypted using that key. (Bytes 4-8 are a representation of the effective date, but if
you use the ID there will be no need to cover the method used here to convert a date to
four bytes).
The rest of the data is the actual encrypted data. The key, IV, and algorithm of the cipher
we identified can be used to decrypt this block of data.

The following information is a translation of the status information listed in the console
after running gen-keys. The information is shown on the console in the following order:
<version> eff:<eff> exp:<exp> alg:<algorithm/mode/padding>
keysize:<keysize> (<location>)

For example:
If a file ending with .cip is in the res/keys, but is not a valid CIP for the customer, only the
existence of the file will be reported as a line starting with ERROR.
ERROR: c:\genkeys\res\keys\ccenc.2017-01-02.cip
c:\genkeys\res\keys\ccenc.2017-01-02.cip is corrupt or has been
tampered with
version - (for example, v3 or v4)
- v1 Indicates the CIP is a version 1 cipher. These ciphers were stored encrypted
with Triple-DES and did not support key rotation. (NOT PCI-COMPLIANT)
- v2 Indicates the CIP is a version 2 cipher. These ciphers were stored encrypted
with AES-128 and did not support key rotation. (NOT PCI-COMPLIANT)
- v3 Indicates the CIP is a version 3 cipher. These ciphers are stored encrypted
using AES-256 and support key rotation. However, these ciphers should only be
used for decrypting legacy data encrypted by Xstore Point of Service versions
previous to 15.0. (As long as a newer cipher is v4, the v4 cipher will be used for
encryption.)
- v4 Indicates the CIP is a version 4 cipher. These ciphers are stored encrypted
using AES-256 and support key rotation. They are used for encryption and
decryption in Xstore Point of Service version 15.0 and up.
eff - The effective date of the cipher. (for example, eff:2017-01-01, eff:NULL_INSTANCE,
and eff:FAILOVER_INSTANCE)
- This date is when the cipher will first be selected for encryption purposes.
- This date serves as the unique identifier for the cipher. (for example, For key
rotation to function properly, only one ccenc key may have a given effective
date).
- NULL_INSTANCE indicates that there is no effective date. (A cipher with an
effective date will be selected ahead of this one for encryption).
- FAILOVER_INSTANCE indicates that there is no effective date and no CIP file.
(Any cipher with an effective date or even the NULL_INSTANCE would be
selected ahead of the cipher).
exp - The expiration date of the key. (for example, exp:2017-12-31,
exp:NULL_INSTANCE, and exp:FAILOVER_INSTANCE)
- This date is used in selecting a preferred key for encryption.
- Decryption will continue to work after this date.
alg - The algorithm used with this cipher. (for example, alg:AES/CBC/PKCS5Padding)
- The first part of the algorithm (AES, DES, or DESede) indicates the actual
algorithm that is used with the cipher.
- The second part indicates the mode used with the cipher.
* CBC or 'cipher block chaining' is used with all generated ciphers. When keys
are generated, an initialization vector (IV) is also randomly generated and
stored in the CIP file. This effectively increases the key size from 256 to 384.

Rotating Key-Encryption-Key
* CBC or the same mode is used with the FAILOVER ciphers. ECB mode is
used for older version of FAILOVER ciphers.
- The third part (PKCS5Padding) indicates the padding scheme used with the
cipher.
* PKCS5Padding indicates that PKCS#5 padding is used.
keysize - The key-size for this cipher. (for example, keysize:256)
location - Where this cipher is stored. (for example, c:\xstore-
genkeys\res\keys\rcpt.cip or FAILOVER)
- FAILOVER indicates that there is no CIP file for this cipher. There is one
FAILOVER cipher for each usage. These cannot be removed. Changing these
ciphers requires use of a "nuclear option" which would invalidate all ciphers
ever generated for the customer.
key - The key is stored in a CIP file, but is not displayed by the cipher report for obvious
reasons.
iv - The initialization vector (IV) is stored in a CIP file, but is not displayed by the cipher
report for obvious reasons.
Important: The following section provides information about

creating a Public/Private Key pair that can be stored in a secondary
open format to allow integration with external processes. An external
process would then use the private key to access the generated key.
This method is not commonly used; however, your Oracle
implementation consultant will work with you if you need to set up a
Public/Private Key.
Rotating Key-Encryption-Key
A Key-Encryption-Key (KEK) is used to encrypt and decrypt data-encryption keys. The
KEK size is 256 bits in size and uses the same strong symmetric encryption algorithm
that is used for the data encryption/decryption process. The KEK is calculated using a
sophisticated algorithm at application start-up and is kept in volatile RAM while the
application is running.
Customers have an ability to rotate KEKs by modifying a configuration parameter that is
used to calculate the KEK. The following steps detail this change.
1. Back up the old cipher files in a separate, safe, and secure directory.
2. Open the system.properties file for the GenKeys installation in a text editor.
3. Change the dtv.CustomerId.salt setting to a new value. Use a value that is long
enough (at least 8 characters) and hard to guess.
4. Generate the new ciphers.

Creating a Public/Private Key Pair
5. Place the new ciphers on all required systems.
Note: Some applications use only select type of ciphers, such as

config.cip.
6. Re-encrypt all configuration entries that were encrypted with the old ciphers;
7. For all applications, update all configuration files with the new encrypted values.
Creating a Public/Private Key Pair

When the keys are initially generated, they can (optionally) be stored in a secondary
open format to allow integration with external processes. The sensitive information in
this open format is stored encrypted using a public key. An external process would then
use the private key to access the generated key.
The Java SDK comes with a program called "keytool" that can be used to generate a
public/private key pair that can be used. Simple usage could involve invoking "keytool"
with the following arguments.
Important: The following text should all be entered on one line, with
a space in place of the line wraps seen below.
c:\genkeys\res\keys> keytool -genkey -keystore .keystore

-storepass publicpassword -alias export -keypass secretpassword
-keyalg RSA -dname "CN=Unknown"
The result will be a file named ".keystore" in the "c:\genkeys\res\keys\" directory.
This file will be secured with the password "publicpassword". The file will contain one
RSA public/private key pair stored under the alias "export". The public key can be
accessed as a certificate with only the keystore password. To access the private key, the
key password "secretpassword" would be required.
Important: Always use your own passwords as required throughout

this process. The passwords shown in this document are for
illustration purposes only.
Import a Public Key Generated by Another System

Important: The process described in this section is an alternative to
the method described above. Depending on how the functionality is
being used, one or the other (but not both) will need to be followed.
The same "keytool" can be used to import a public key from an external process.
Example usage is shown below.
Important: This should all be entered on one line, with a space in

place of the line wraps seen below.

Configure the Public Key
c:\genkeys\res\keys> keytool -import -keystore .keystore

-storepass publicpassword -alias export -file genkeys.cer
-keypass secretpassword -noprompt
This example imports a key from a file named "genkeys.cer". Sun's "keytool" can import
X.509 v1, v2, and v3 certificates/keys, and PKCS#7 formatted certificate chains consisting
of certificates of that type. The data to be imported must be provided either in binary
encoding format, or in printable encoding format (also known as Base64 encoding) as
defined by the Internet RFC 1421 standard. In the latter case, the encoding must be
bounded at the beginning by a string that starts with "-----BEGIN", and bounded at the
end by a string that starts with "-----END".
Keys can be for the RSA (recommended) or DSA algorithm should be minimum 2048 bit.
See https://gps.oracle.com/ossa/farm/standards/doku.php?id=ats:start for more
information.

To access the public key, the gen-key process needs three pieces of information:
• The location of the keystore containing the public key,
• the password for the keystore,
• and the alias of the public/private key pair.
This information is configured in Section 5 of gen-keys.conf.
Example
# --------------------------------------------------------------
# Section 5: Define information used for secondary export during
generation
wrapper.java.additional.5=-Ddtv.keygen.export.keystore=res/keys/
.keystore
wrapper.java.additional.6=-Ddtv.keygen.export.key.alias=export
wrapper.java.additional.7=-
Ddtv.keygen.export.keystore.password=publicpassword
Save your changes. Continue with “Create Cipher Key Files” of Chapter 3, “Install
Xstore Office” or “Create Cipher Key Files” of Chapter 5, “Install Xstore Point of
Service”.


D
PCI Best Practices: Implementation &
Configuration
PCI Implementation Best Practices

PCI Data Security Standards protect credit and debit card numbers by imposing security
requirements on the storage and dissemination of account numbers. The major credit
card issuers created PCI (Payment Card Industry) compliance standards to protect
personal information and ensure security when transactions are processed using a
payment card. All members of the payment card industry (financial institutions, credit
card companies and merchants) must comply with these standards if they want to accept
credit cards. Failure to meet compliance standards can result in fines from credit card
companies and banks and even the loss of the ability to process credit cards.
This appendix is intended as a quick reference guide to provide you with information
concerning Oracle's adherence to the Visa USA PCI Data Security Standard concerning
Payment Application Data Security Standard (PA-DSS) compliance.
Please refer to the SSC web page for updated listings:
https://www.pcisecuritystandards.org/
About CISP Compliance

When customers offer their bankcards at the point of sale, over the Internet, on the
phone, or through the mail, they want assurance that their account information is safe.
That's why Visa USA has instituted the Cardholder Information Security Program
(CISP). Mandated since June 2001, the program is intended to protect Visa cardholder
data—wherever it resides—ensuring that members, merchants, and service providers
maintain the highest information security standard.1
For more detailed information concerning CISP compliance, please refer to the PCI
Security Standards Council website: https://www.pcisecuritystandards.org
1. Reprinted from "Cardholder Information Security Policy",

http://usa.visa.com/merchants/risk_management/cisp_overview.html
PCI Best Practices: Implementation & Configuration D-1

About the PCI Data Security Standard

CISP compliance is required of all merchants and service providers that store, process, or
transmit Visa cardholder data. The program applies to all payment channels, including
retail (brick-and-mortar), mail/telephone order, and ecommerce. To achieve compliance
with CISP, merchants and service providers must adhere to the Payment Card Industry
(PCI) Data Security Standard, which offers a single approach to safeguarding sensitive
data for all card brands.
This Standard is a result of collaboration between Visa® and MasterCard® and is

designed to create common industry security requirements, incorporating the CISP
requirements. Other card companies operating in the U.S. have also endorsed the PCI
Data Security Standard within their respective programs.
Using the PCI Data Security Standard as its framework, CISP provides the tools and
measurements needed to protect against cardholder data exposure and compromise
across the entire payment industry.
Audience
This document is intended for the following audiences:
- Oracle Installers/Programmers
- Oracle Customer Service
- Oracle Training Personnel
- MIS Personnel
- Oracle Customers
What the reader should already know

This document assumes that you have the following knowledge or expertise:
- Operational understanding of PCs
- Understanding of basic network concepts
- Experience with Windows 2000, Microsoft Windows 7, Windows 8, or Windows
10
- Familiarity with the Xstore Point of Service software
- Familiarity with operating Xstore Point of Service peripheral devices
How this appendix is organized

• This section (PCI Implementation Best Practices) is organized by each of the 12 basic
requirements outlined in the PCI Data Security Standard. For each requirement,
there is a Oracle Development response or recommendation that applies to Xstore
Point of Service software.
• The PCI Configuration Best Practices section is intended to be used as a Security
Checklist for protecting Xstore Point of Service systems from potential security
breaches.
PCI Best Practices Revision History

New versions of this guide incorporate additions and changes to the material since the
previous release. This guide will be reviewed on an annual basis to ensure compliance
with the latest PCI DSS requirements along with changes to the Xstore Point of Service
application.
D-2 Implementation and Security Guide

Overview of the Cardholder Data Environment
Figure D-1: Typical Network Implementation
Implementation and Security Guide D-3

Cardholder Data Flow Diagram
Figure D-2: Cardholder Data Flow Diagram

PCI Data Security Standard
PCI Data Security Standard

The PCI Data Security Standard, seen below, consists of twelve basic requirements
supported by more detailed sub-requirements.2
The PCI standards listed in this section are from the Payment Card Industry (PCI) Data
Security Standard, Requirements and Security Assessment Procedures, Version 3.2.1.
Refer to https://www.pcisecuritystandards.org for more information.
The first step in PCI compliance is to meet the following standards:
Build and Maintain a Secure Network

1. Install and maintain a firewall configuration to protect cardholder data
2. Do not use vendor-supplied defaults for system passwords and other security
parameters
Protect Cardholder Data

3. Protect stored cardholder data
4. Encrypt transmission of cardholder data across open, public networks
Maintain a Vulnerability Management Program

5. Use and regularly update anti-virus software or programs
6. Develop and maintain secure systems and applications
Implement Strong Access Control Measures

7. Restrict access to cardholder data by business need to know
8. Assign a unique ID to each person with computer access
9. Restrict physical access to cardholder data
Regularly Monitor and Test Networks

10. Track and monitor all access to network resources and cardholder data
11. Regularly test security systems and processes
Maintain an Information Security Policy

12. Maintain a policy that addresses information security for all personnel
2. From "Payment Card Industry Security Standards Overview",

http://usa.visa.com/download/merchants/cisp_overview.pdf

Achieving PCI Compliance

While Oracle recognizes the importance of upholding cardmember security and data
integrity, certain parameters of the PCI Data Security Standard and CISP compliance are
the sole responsibility of the client. This section contains a description of the 12 points of
the PCI Data Security Standard and discusses how the Xstore Point of Service software
adheres to it.
For a complete description of the PCI Data Security Standard, please consult the PCI
Security Standards Council website:
https://www.pcisecuritystandards.org/security_standards/
documents.php?category=standards
Build and Maintain a Secure Network
Requirement 1: Install and maintain a firewall configuration to protect

cardholder data
Firewalls are devices that control computer traffic allowed between an entityʹs networks
(internal) and untrusted networks (external), as well as traffic into and out of more sensitive
areas within an entityʹs internal trusted networks. The cardholder data environment is an
example of a more sensitive area within an entityʹs trusted network. A firewall examines all
network traffic and blocks those transmissions that do not meet the specified security criteria. All
systems must be protected from unauthorized access from untrusted networks, whether entering
the system via the Internet as e‐commerce, employee Internet access through desktop browsers,
employee e‐mail access, dedicated connections such as business‐to‐business connections, via
wireless networks, or via other sources. Often, seemingly insignificant paths to and from
untrusted networks can provide unprotected pathways into key systems. Firewalls are a key
protection mechanism for any computer network.3
In accordance with the Visa USA PCI Data Security Standard, Oracle strongly
recommends every site install and maintain a firewall configuration to protect data.
Configure your network so that databases and wireless access points always reside
behind a firewall and have no direct access to the Internet.
Personal firewall software must be installed on any employee-owned computers with
direct connectivity to the Internet, such as laptops used by employees, which are used to
access the organization's network. The firewall software's configuration settings must
not be alterable by employees.
Because of the Visa USA PCI Data Security Standard, Oracle mandates that each site
ensure that PCs, databases, wireless access points, and any medium containing sensitive
data reside behind a firewall. The firewall configuration must restrict connections
between publicly accessible PCs and any system component storing cardholder data,
including any connections from wireless networks.
Oracle does not recommend a specific vendor's firewall be installed. Work with the
customers' network administrator to set up something that works with their
configuration.
Linux and Windows 7, 8, 10, and Vista have a built in software firewall that should be
enabled when running Xstore Point of Service. The firewall should be enabled before
installing the Xstore Point of Service software.
3. PCI DSS Requirements and Security Assessment Procedures, Version 3.2 April 2016
https://www.pcisecuritystandards.org/documents/PCI_DSS_v3-2.pdf

To make sure your firewall configuration is set up in compliance with Requirement 1:

Install and maintain a firewall configuration to protect cardholder data of the PCI Data
Security Standard, please consult the PCI Security Standards Council website, "Payment
Card Industry Data Security Standard":
https://www.pcisecuritystandards.org/security_standards/pci_dss.shtml
Requirement 2: Do not use vendor-supplied defaults for system

passwords and other security parameters
Malicious individuals (external and internal to an entity) often use vendor default passwords and
other vendor default settings to compromise systems. These passwords and settings are well
known by hacker communities and are easily determined via public information.4
Xstore Point of Service allows for all application, operating system, and database
passwords to be changed. Passwords that are complex should be on by default for all
administrators and employees who have access to administrative functions.
Oracle is not permitted to manage these passwords for you. “Password Management”
provides a sample log sheet for all password management.
Important: Default settings MUST be changed before a site goes live

in order to maintain PCI compliancy. At a minimum, all passwords
should be changed every 90 days.
When a request for support is made to your support organization or to a third party
vendor, they may need one or more of these passwords to do their job. Any time that a
password is given out, it should be changed to maintain PCI compliancy.
Additionally, Xstore Point of Service has the capability to enforce complex passwords for
access to all Back Office applications, including reporting and Back Office utilities.
Complex passwords can be enforced, including minimum length, alphanumeric
passwords, periodic rotation, and lockout after failed login attempts. All Xstore Point of
Service POS user passwords are stored securely in the database through an SHA256
Hash. Oracle recommends that customers using Xstore Point of Service implement
complex passwords for access to Back Office applications in accordance with the Visa
CISP Security Standard.
For all other system components, including operating system, network devices, and
access points, Oracle recommends changing all vendor-supplied default passwords to a
complex password.
The table below lists the available options, and the minimum recommended settings.
See the Xstore Point of Service Frameworks & Technologies Guide for additional information.
Table D-1: Password options and minimum recommended settings
Option Location Recommended Setting
Password Expiration SystemConfig.xml 90 days
4. PCI DSS Requirements and Security Assessment Procedures, Version 3.2 April 2016

Table D-1: Password options and minimum recommended settings
Option Location Recommended Setting
Strong Password Rule validations.xml 8 characters

Password must contain at least one
numeric and one alphabetic
characters.
Values less than 8 will be ignored.
Password History Length SystemConfig.xml 8
Auto Log Out SystemConfig.xml 15 minutes
Account Lock Out SystemConfig.xml 3 attempts
Xstore Point of Service Database User

Oracle does not provide default accounts for the original installation of the Xstore Point
of Service software. Each customer is required to provide a complex password for each
of the accounts listed below. The passwords for these accounts must be complex in
nature and be in accordance with the Visa CISP Security Standard. These passwords
must be changed every 90 days in order to maintain PCI compliancy.
The data contained in the Database is further protected due to the operating system
lockdown from the Xstore Point of Service environment with daily changing passwords.
Furthermore, current POS systems that are on private, local networks prevent all outside
database access. The merchant is responsible for assessing security access by way of
default passwords and security parameters on any other systems that contain credit card
data at the corporate office.
* The Xstore Point of Service DB Power User name and password are both supplied by
the customer. This is the user account that Xstore Point of Service uses to connect to the
database.
Securing Operating Systems for Xstore Office and Xstore Payment

For a system that has not had its native shell replaced with Xenvironment (for example,
systems running Xstore Office or Xstore Payment), you must secure the operating
system. This requires you to set password policies for the system.
Screen Saver
Use the screen saver to help secure the system when users are away:
• Ensure the screen saver is enabled.
• Configure the screen saver to display the logon screen when on resume.

Windows Account Policy Editor

To set policies for individual accounts on a Windows system:
1. Open the Start menu.
2. Enter secpol.msc in the Start Search box.
3. Press the [Enter] key.
4. Set the Password Policy and Account Lockout Policy.
Password Policy
Set the following Password Policy settings (in the Account Policies folder):
• Enforce password history - 4 passwords remembered
• Maximum password age - 90 days
• Minimum password age - 0 days
• Minimum password length - 8 characters
• Password must meet complexity requirements - Enabled
• Store passwords using reversible encryption - Disabled
Account Lockout Policy

Set the following Account Lockout Policy settings (in the Account Policies folder):
• Account lockup duration - 30 minutes
• Account lockout threshold - 4 invalid logon attempts
• Reset account lockout counter after - 30 minutes
Third Party Application Support

The Xstore Point of Service system permits integration with third party vendors. The
merchant is responsible for managing this integration with the Xstore Point of Service
system. If the vendor needs database access or Xstore Point of Service application access,
the merchant is responsible for setting this up and for maintaining it. If utilizing third
party support, Oracle recommends the following:
• Separate database user accounts should be set up for each vendor and their data
access limited to what they need.
• Separate Xstore Point of Service application user accounts should be set up for each
vendor and their data access limited to what they need.
• Xstore Point of Service Database power user account should not be given out. If they
are given for support reasons, they should be changed immediately after use.
Wireless Environments
For wireless environments, change wireless vendor defaults, including but not limited
to, default service set identifier (SSID), password, and SNMP community strings.
Disable SSID broadcasts. Enable WiFi protected access (WPA and WPA2) technology for
encryption and authentication. This must be done to maintain PCI compliancy.
For more information, refer to the Payment Application Data Security Standard (PA-
DSS) document.
For more information on Requirement 2: Do not use vendor-supplied defaults for system
passwords and other security parameters of the PCI Data Security Standard please

consult the PCI Security Standards Council website, "Payment Card Industry Data
Security Standard":
https://www.pcisecuritystandards.org/security_standards/pci_dss.shtml.
Protect Cardholder Data
Requirement 3: Protect stored cardholder data

Note: Starting with version 16.0, Xstore Point of Service does not store
primary account numbers (PAN). For this reason, Xstore Point of
Service is not eligible for PA-DSS validation.
Oracle interprets this requirement to mean the following:

1. Do not store sensitive authentication data after authorization (even if encrypted).
Under no circumstances will Xstore Point of Service store sensitive authentication data
(even if encrypted).
Sensitive Authentication Data includes:
- Full track data (magnetic-stripe data or equivalent on a chip)
- CAV2/CVC2/CVV2/CID
- PINs/PIN blocks
2. Do not store full track data subsequent to obtaining an authorization.
Under no circumstances will Xstore Point of Service store full track data.
3. Do not allow access to full credit card numbers in the store. Also, mask or encrypt
credit card numbers wherever they are printed or stored.
The PCI Data Security Standard also requires that the keys used to encrypt cardholder
data be periodically changed as an additional safeguard in case hackers obtain the key
used to encrypt the target data. Xstore Point of Service provides the functionality to
enable the merchant to meet this requirement. We also recommend that the merchant
change keys at least every 90 days. Please note that the merchant is responsible for
encryption key maintenance and rotation of the keys. See “About Xstore Suite GenKeys”
for instructions on creating and maintaining your encryption keys.
The PCI Data Security Standard states that key custodians that have access to the keys
and are responsible for key maintenance sign a form specifying that they understand
and accept their key-custodian responsibilities.
Finally, protecting the database and the cardholder data contained therein is a primary
concern. Backups of the Xstore Point of Service database should not be made to any
shared drive where they can be accessed from other computers. Access to database
backups should only be allowed to those systems and users with a specifically defined
need or use for the data.
The PCI Data Security Standard states, Keep cardholder data storage to a minimum. Develop a
data retention and disposal policy. Limit storage amount and retention time to that which is
required for business, legal, and/or regulatory purposes, as documented in the data retention
policy.5 The development and implementation of a Data Retention Policy (DRP) is a
significant factor in the overall security of your environment.
5. PCI DSS Requirements and Security Assessment Procedures, Version 3.2 April 2016.

A DRP forms an important foundation for helping manage an organization's data. The
creation of a DRP is a complex task that requires exhaustive research and the assistance
of qualified legal counsel. The scope of your DRP should reach far beyond the PCI DSS,
and you should work closely with your legal counsel to ensure your compliance with the
laws and governmental regulations that pertain specifically to your organization.
Upon implementation of your DRP, you should contract with a Visa-approved PCI
assessment company to review the DRP's impact on the storage of payment card data in
compliance with Requirement 3 of the PCI DSS.
Xstore Point of Service can be configured to purge transactional data, including sensitive
cardholder data, through XML configuration options. The configuration option to
accomplish this PCI requirement is listed below.
Xstore Point of Service XML Configuration File - PurgeConfig.xml
<Group name="Transaction" order="10" age="365">
Set the age value to the desired number of days of transactional information to retain
and Xstore Point of Service will purge data older than the value during the nightly
closing process.
Please see the Xstore Point of Service® Technical Guide for additional information relating

to purging data.
In some situations, Xstore Point of Service integrators might be tasked with
troubleshooting an issue with the system. To ensure cardholder data is protected, Oracle
mandates Xstore Point of Service integrators must only collect customer data (for
example, sensitive authentication data, log files, debug files, databases, etc.) needed to
solve a specific problem. Such data must only be stored in specific, known locations with
limited access. Integrators must only collect the limited amount of data needed to solve a
specific problem and must encrypt such sensitive authentication data while stored. After
such data is no longer used, it must be immediately deleted in a secure manner.
When troubleshooting customer issues, integrators must keep in mind the following
when using databases from live customer sites:
- Collect live customer databases only when needed to solve a specific problem.
All customer databases must be cleansed of credit and debit card numbers once
they are received by Oracle support members. Please refer to the following:
* Oracle Policy Depot: https://policydepot.oraclecorp.com.
* Personal Information Handling and Anonymization Guidelines:
http://my.oracle.com/content/web/cnt583322.
* Oracle Information Protection Policy:
http://my.oracle.com/content/web/cnt120758.
* Additional Use of Personal Information Policy:
http://my.oracle.com/site/sec/gis/policies/cnt583367.pdf.
- Store databases in specific, known locations with limited access. Password-
protect zip archives used to store customer databases.
- Collect only the limited amount of data needed to solve a specific problem. Pull
the latest known database backup, not every backup in the
c:\xstoredb\backup or /op/xstoredb/backup directory. The more files
you retrieve, the more you have to manage through the troubleshooting process,
and the more files you will have to destroy later.

For information on destroying these files refer to the Oracle Secure Wipe Tool

documentation. PrepollDB.Zip, XstoreDB.Zip, .zip.001, .zip.002
- Securely delete such data immediately after use. This involves removing data
from the PC or terminal where the troubleshooting occurred.
- Xstore Point of Service stores a token identifying
Cardholder Data Must Never Be Stored on a Server Connected to the Internet

While encryption and masking of cardholder data is an important component of
protecting this sensitive data, so is safeguarding the systems it resides on. Per the PCI
Data Security Standard, no system containing cardholder data should reside on
Internet-accessible systems. Place system components that store cardholder data in an
internal network zone, segregated from the DMZ and other untrusted networks. It is the
merchant's responsibility to carefully design their networks to protect their servers
containing this information. See “Communication Ports” for more information about
ports.
Data Encryption
Note: Starting with version 16.0, Xstore Point of Service does not store
primary account numbers (PAN). For this reason, Xstore Point of
Service is not eligible for PA-DSS validation.
Sensitive data is encrypted on the Xstore Point of Service system when at rest. Xstore
Point of Service employs the industry-standard algorithm AES 256 to encrypt this
sensitive data.
Xstore Point of Service stores information (data at rest) in the following areas:
- The main Xstore Point of Service database
- The replication database
- The training database
- The backup database
Each of these areas contains both sensitive and non-sensitive information.
This database is replicated during the nightly closing process to the replication &
training databases on each register at the store.
Access to these databases is granted through standard SQL tools provided that the
merchant provides the required authentication credentials to a given user. The database
connection string that Xstore Point of Service uses to connect to the main Xstore Point of
Service database is encrypted with standard AES encryption to prevent unauthorized
access to the database and is stored in a core configuration file.
The Xstore Point of Service security design requires the use of an encryption key to
facilitate encrypting the sensitive data with AES 265. Xstore Point of Service allows the
end user to change or rotate the AES key as often as desired. This will be referred to as
key rotation. The AES encryption keys are stored in a cipher file which must be located
in c:\xstore\res\keys or /opt/xstore/res/keys on each register. Keys within
the cipher file have the following attributes:
- Effective Date - Date the key is in effect and to be used by Xstore Point of
Service.
- Expiration Date - Date the key expires. Xstore Point of Service parses the cipher
file during its nightly closing process and deletes any keys that are expired.

- Key Value - The actual AES encryption key.

Oracle provides merchants the ability to create and maintain their cipher file via the
GenKeys utility. The customer is solely responsible for this task. Oracle, and all of its
integrators, will never create, retrieve, or possess a merchant's cipher file.
Oracle strongly recommends that merchants maintain a minimal number of keys within
the cipher file to minimize exposure in the event of a system breech.
Note: The cipher file itself is secure by encrypting it with AES256

encryption. Only the Xstore Point of Service application contains the
key to decrypt it. See “About Xstore Suite GenKeys” for instructions on
creating and maintaining your encryption keys.
Important: The encryption key MUST be rotated at least once a year

to maintain PCI compliancy. See “Install GenKeys String Encrypter
Utility” of Chapter 5, “Install Xstore Point of Service” for procedural
information.
Secure Data Fields

Oracle provides functionality within Xstore Point of Service to enter sensitive personal
information (including passport, date of birth, and credit card numbers) in specific fields
on the user interface. The form fields that are intended to receive this information are
clearly labeled, and are designed with heightened security controls such as data masking
in the form and encryption of data at rest. Entering this sensitive personal information in
any other field (for example, in a Notes or Comments field), does not provide it with
these heightened security controls and is not consistent with the requirements for
protecting cardholder data as detailed in the Payment Card Industry Data Security
Standards (PCI DSS).
For more information on Requirement 3: Protect stored cardholder data of the PCI Data
Security Standard, please consult the PCI Security Standards Council website, "Payment
Card Industry Data Security Standard":
Requirement 4: Encrypt transmission of cardholder data across open,

public networks
Sensitive information must be encrypted during transmission over networks that are easily
accessed by malicious individuals. Misconfigured wireless networks and vulnerabilities in legacy
encryption and authentication protocols continue to be targets of malicious individuals who
exploit these vulnerabilities to gain privileged access to cardholder data environments.6
When transmitting cardholder data over a public network or the Internet, always use
TLS 1.2 or above; and when transmitting wirelessly, always use the highest level of
encryption available.
Xstore Point of Service supports protocol-level encryption features of the operating
system and networking equipment such as IPSEC (IP Security), WPA (WiFi Protected
Access), and WPA2 (WiFi Protected Access II).

Wireless transmissions of cardholder data must be encrypted over both public and
private networks. Encrypt transmissions by using WiFi Protected Access (WPA or
WPA2) technology, IPSEC VPN, or TLS. Always restrict access based on media access
code (MAC) address.
Sensitive data stored in the Xstore Point of Service database is encrypted via a strong
encryption algorithm (AES). Sensitive data is defined as the cardholder account number
as well as application access passwords. The encryption key for sensitive data can be
rotated by the end user.
Xstore Point of Service does not use end-user messaging technology to transmit
cardholder data over a network.
For more information on Requirement 4: Encrypt transmission of cardholder data across
open, public networks of the PCI Data Security Standard, please consult the PCI Security
Standards Council website, "Payment Card Industry Data Security Standard":
https:// www.pcisecuritystandards.org/security_standards/pci_dss.shtml.
Maintain a Vulnerability Management Program
Requirement 5: Use and regularly update anti-virus software or

programs
Malicious software, commonly referred to as ʺmalwareʺ — including viruses, worms, and
Trojans — enters the network during many business‐approved activities including employee e‐
mail and use of the Internet, mobile computers, and storage devices, resulting in the exploitation
of system vulnerabilities. Anti‐virus software must be used on all systems commonly affected by
malware to protect systems from current and evolving malicious software threats.7
recommends regular use and regular updates of antivirus software. Xstore Point of
Service has been certified and integrated with many antivirus software packages on the
market today.
To make sure your antivirus software is set up in compliance with Requirement 5: Use
and regularly update anti-virus software or programs of the PCI Data Security Standard,
please consult the PCI Security Standards Council website, "Payment Card Industry
Data Security Standard": https://www.pcisecuritystandards.org/security_standards/
pci_dss.shtml.
Requirement 6: Develop and maintain secure systems and applications

Unscrupulous individuals use security vulnerabilities to gain privileged access to systems. Many
of these vulnerabilities are fixed by vendor‐provided security patches, which must be installed by
the entities that manage the systems. All critical systems must have the most recently released,
appropriate software patches to protect against exploitation and compromise of cardholder data by
malicious individuals and malicious software.8
Oracle uses separate development and production environments to ensure software
integrity and security. Updated patches and security updates can be made available by
contacting your primary Oracle representative. While Oracle makes every possible effort
to conform to Requirement 6 of the PCI Data Security Standard, certain parameters,
including following change control procedures for system and software configuration

changes, and the installation of available security patches, depend on site specific
protocol and practices.
In order to comply with Requirement 6 of the PCI standard, all Operating Systems (OS)
must be patched and updated regularly.
When a critical update is released, the site must install that update to ensure that system
security is as strong as possible. Antivirus definitions must also be installed on all PCs,
and should be kept up to date with the most recent virus definitions. Check the
documentation provided by your antivirus software provider as well as for your
Operating System for steps to ensure that your software is up to date.
See “Disable System Restore” for procedural information.
To make sure your site develops and maintains secure systems and applications in
compliance with Requirement 6: Develop and maintain secure systems and applications
of the PCI Data Security Standard, please consult the PCI Security Standards Council
website, "Payment Card Industry Data Security Standard":
Implement Strong Access Control Measures
Requirement 7: Restrict access to cardholder data by business need to

know
To ensure critical data can only be accessed by authorized personnel, systems and processes must
be in place to limit access based on need to know and according to job responsibilities.9
Oracle recognizes the importance of data control, and does so by establishing access
based upon employee job level. This mechanism ensures access to sensitive information
is restricted, password protected, and based on a need-to-know basis.
Access to customer passwords by integration personnel must be restricted.
The PCI standard requires remote connectivity software to be running only while in use.
Applications such as PCAnywhere and DameWare should be disabled from running in
the background in a "waiting" state when not in use.
Web browsing from an Xstore Point of Service register or server should be disabled by
default. If corporate policy requires it to be enabled, this functionality should only be
enabled to allow browsing to known-safe sites. Oracle recommends that this feature
should only be used to browse corporate intranet sites, and should never be used to
browse the World Wide Web or untrusted sites.
For more information on Requirement 7: Restrict access to cardholder data by business
need to know of the PCI Data Security Standard, please consult the PCI Security
Requirement 8: Assign a unique ID to each person with computer

access
Assigning a unique identification (ID) to each person with access ensures that each individual is
uniquely accountable for his or her actions. When such accountability is in place, actions taken on
critical data and systems are performed by, and can be traced to, known and authorized users.10

The Xstore Point of Service POS application provides the ability to assign a unique user
ID and a complex password to each associate at the store level that will be processing
customer transactions. Each user can be assigned different security levels to restrict
access to POS functionality and information available within the POS application.
Oracle strongly recommends that the merchant also assign unique usernames and
complex passwords to all PCs, servers, and databases with payment applications and
cardholder data. The passwords for both the Xstore Point of Service POS application and
systems containing cardholder data should be a minimum length of 7 and should be
alpha numeric.
As mentioned in “Requirement 2: Do not use vendor-supplied defaults for system
passwords and other security parameters”, we suggest that these passwords be changed
on a regular basis in accordance with a policy set up by you, the merchant.
Further, new passwords should not repeat any of the last four passwords used. The
merchant is responsible for ensuring that this functionality is implemented across their
chain and that data access is also controlled at the corporate office for any non-Oracle
systems that contain sensitive credit card information. Additionally, Oracle recommends
that you encrypt all passwords during transmission and storage, on all system
components.
Additional password guidelines include:
- Do not use group, shared, or generic accounts and passwords.
- Change user passwords at least every 90 days.
- Limit repeated access attempts by locking out the user ID after not more than six
attempts.
- Set the lockout duration to thirty minutes or until an administrator enables the
user ID.
- If a session has been idle for more than 15 minutes, require the user to reenter
the password to reactivate the terminal.
Xstore Point of Service configuration options for password configuration are as follows:
Table D-2: Password configuration options
Option Description
Password Age The number of days for which a password is valid before it
expires. (Enabled by default, default value= 90 days.)
Minimum Password Length The minimum number of characters required for a password.
Minimum Alpha Characters The minimum number of alpha characters that must be in the
password.
Minimum Numeric The minimum number of numeric characters that must be in the
Characters password.
Password History Length The number of unique passwords that must be entered before a
duplicate one can be entered.
Maximum Idle Time The amount of time Xstore Point of Service waits before
securing the register. (Enabled by default, default wait seconds
value = 300.)

Table D-2: Password configuration options (continued)
Option Description
Account Lockout The number of invalid password entries before the user is locked
out. (Enabled by default, default value= 3 retries.)
New Employee Password Dictates if Xstore Point of Service will require a new employee
Expire to change their password when they initially log in.
Furthermore, Oracle advises users to control access, via unique usernames and PCI-
compliant complex passwords, to any PCs, servers, and databases with payment
applications and cardholder data.
Oracle mandates a two-factor authentication for remote access to the site's network by
Oracle, Inc. employees, administrators, and third parties. Technologies such as remote
authentication and dial-in service (RADIUS), terminal access controller access control
system (TACACS) with tokens, or VPS based on TLS or IPSEC with individual
certificates must be used.
Remote Access
Remote access software security features must always be used and implemented.
Therefore, default settings in the remote access software must be changed so that a
unique username and complex password is used for each customer. Never use the
default password and adhere to the PCI DSS password requirements established in
Requirement 8 on page 15. The new password must contain a minimum of eight
characters, including a combination of numbers and letters.
Connections must only be allowed from specific, known IP/MAC addresses. Strong
authentication or complex passwords for logins must be used. Encrypted data
transmission and account lockout after a certain number of failed attempts must be
enabled. For additional security, the systems should be configured so that a remote user
can establish a Virtual Private Network (VPN) connection via a firewall before access is
allowed. Logging functions must be enabled for security purposes. Access to customer
passwords must always be restricted.
All non-console administrative access must be encrypted using technologies such as
SSH, VPN, or TLS (transport layer security) for web-based management and other non-
console administrative access. Telnet must never be used for administration.
For more information on Requirement 8: Assign a unique ID to each person with
computer access of the PCI Data Security Standard, please consult the PCI Security
Requirement 9: Restrict physical access to cardholder data

Any physical access to data or systems that house cardholder data provides the opportunity for
individuals to access devices or data and to remove systems or hardcopies, and should be
appropriately restricted.11
recommends restricting physical access to cardholder data.

Xstore Point of Service provides data access security in the form of a proprietary shell
program that replaces the Windows-based Explorer shell. This shell program effectively
restricts access to all Windows and third party based applications by requiring customer
defined passwords (configured by default to change daily) to access applications other
than our Point of Sale (POS) and authorization programs. The merchant is responsible
for restricting data access at the corporate level for non Oracle systems that contain
credit card data.
To make sure your site is set up in compliance with Requirement 9: Restrict physical
access to cardholder data of the PCI Data Security Standard, please consult the PCI
Security Standards Council website, "Payment Card Industry Data Security Standard":
Regularly Monitor and Test Networks
Requirement 10: Track and monitor all access to network resources

and cardholder data
Logging mechanisms and the ability to track user activities are critical in preventing, detecting,
or minimizing the impact of a data compromise. The presence of logs in all environments allows
thorough tracking, alerting, and analysis when something does go wrong. Determining the cause
of a compromise is very difficult, if not impossible, without system activity logs.12
In accordance with the PCI Data Security Standard, Oracle strongly recommends that
access to network resources and cardholder data be tracked and monitored. The
database platforms Xstore Point of Service communicates with provide configuration
options to enable audit logging of database connections.
See “Enable Database & Operating System Audit Logging” for procedural information.
Centralized Logging Mechanism

Xstore Point of Service records application events in automatically-generated log files.
Viewing these log files provides valuable data about store operations and
troubleshooting information. See the Xstore Point of Service Technical Guide for more
information on logging configurations.
The Xenvironment module of Xstore Point of Service collects system log files from non-
lead registers to the lead register in a store, then uploads the log files (archived) to a web
server at the merchant’s home office. See the Xenvironment User Guide for more
information about the included log files, naming conventions, paths, and upload
process.
To make sure your site is in compliance with Requirement 10: Track and monitor all
access to network resources and cardholder data of the PCI Data Security Standard,
please consult the PCI Security Standards Council website, "Payment Card Industry
Data Security Standard": https://www.pcisecuritystandards.org/security_standards/
pci_dss.shtml.
Requirement 11: Regularly test security systems and processes

Vulnerabilities are being discovered continually by malicious individuals and researchers, and
being introduced by new software. System components, processes, and custom software should be
tested frequently to ensure security controls continue to reflect a changing environment.13

recommends regular testing of security systems and processes. To make sure your site's
security systems and processes are set up in compliance with Requirement 11: Regularly
test security systems and processes of the PCI Data Security Standard, please consult the
PCI Security Standards Council website, "Payment Card Industry Data Security
Standard": https://www.pcisecuritystandards.org/security_standards/pci_dss.shtml.
Maintain an Information Security Policy
Requirement 12: Maintain a policy that addresses information security

for all personnel
A strong security policy sets the security tone for the whole entity and informs personnel what is
expected of them. All personnel should be aware of the sensitivity of data and their responsibilities
for protecting it.14
recommends maintaining a policy that addresses information security.
A site's maintained information security policy should include information on physical
security, data storage, data transmission, and system administration.
To make sure your information security policy is setup in compliance with Requirement
12: Maintain a policy that addresses information security for all personnel of the PCI
Data Security Standard, please consult the PCI Security Standards Council website,
"Payment Card Industry Data Security Standard":

Credit Card Security Installation Checklist
Credit Card Security Installation Checklist

This checklist should be reviewed with the customer and maintained by the installing
entity as evidence that proper credit card security procedures were reviewed with the
customer.
Version of Xstore Point of Service Software Installed _______________________
Verify... Yes/No Comments
existence of a properly configured

Firewall.
Xstore Point of Service is configured to

mask the Credit Card Number and
Expiration Date for all credit cards on
both the store and customer copy of the
receipt.
the operating system's Login Passwords

are changed from the default.
the vendor-supplied passwords are

changed from the default.
access points use complex passwords and

that those passwords have been changed
from vendor defaults.
complex password settings are in

compliance with PCI requirements and
that each person has a unique user ID.
anti-virus software is installed and up-to-

date. Verify that a plan is in place to keep
anti-virus software updated.
the operating system audit logging is

enabled and is recording failed and
successful logins.
the database engine audit logging is

enabled and is recording failed logins.
Oracle Agent or Representative

Name _______________________________________
Company ____________________________________
Date ________________________________________
Signature ____________________________________

Password Management
Password Management
Oracle is not permitted to manage these passwords for you. This section provides a
sample log sheet for all password management.
Remote Access
Vendors may connect remotely to your server to support you. This connection should be
protected by a complex password.
Method Username Password Date Changed
Windows
Each individual in your organization should also be given their own Windows Login. A
separate Windows login should be given to each vendor.
Username Password Date Changed
Employees with Access to Xstore Point of Service Applications

Each individual in your organization that needs access should be given their own Xstore
Point of Service Login. A separate Xstore Point of Service login should be given to each
vendor.
Employee Username Password Date Changed

Xstore Point of Service Versioning Methodology
Database Users
Your Xstore Point of Service database requires the user accounts listed below to be
present. These accounts will need their passwords changed every 90 days. Each
individual in your organization that needs direct database access should be given their
own database login and should only be given access to what they need. A separate
database login should be given to each vendor.
Username Password Date Changed
SA
XstoreDBPowerUser*
* The XstoreDBPowerUser name and password are both supplied by the customer. This
is the user account that Xstore Point of Service uses to connect to the database.
Xstore Point of Service Versioning Methodology

The PA-DSS requirements state that vendors are required to document and follow a
software versioning methodology as part of their system development lifecycle.
Additionally, vendors must communicate the versioning methodology to their
customers and integrators/resellers in the PA-DSS Implementation and Security Guide.
Customers and integrators/resellers require this information to understand which
version of the application they are using, and the types of changes that have been made
to each version of the application.
Xstore Point of Service versions numbers are in an X.Y.Z format where:
• X is the major version number. It represents a significant enhancement or
functionality change.
• Y is the minor version number. It represents a minor enhancement to the application.
• Z is the patch version number. When this is incremented, the release could involve
defect patches. This digit would represent an internal, non-compliance-related
change. This version is not intended to be public facing.
PCI Configuration Best Practices

Visa established the Payment Card Industry (PCI) Data Security Standard to protect Visa
cardholder data -wherever it resides - ensuring that members, merchants, and service
providers maintain the highest information security standard.
Please note that since its inception, Xstore Point of Service has never stored plain text
account numbers, full track data, card validation codes, PINs, or PIN Blocks. The only
account number information that is stored is the account number and that is only stored
in encrypted format.
The guidelines outlined in this document will provide additional security to further
strengthen the installation of Xstore Point of Service.
The following section is intended to be used as a Security Checklist for protecting Xstore
Point of Service systems from potential security breaches. Following this checklist, along
with proper installation of the Xstore Point of Service software, will increase the security
of your system.

Clear virtual memory on shutdown

Virtual memory is used by the Windows operating system to optimize the use of RAM
and disk memory. It is possible for Xstore Point of Service data to be written to virtual
memory by the operating system in the normal course of swapping data between RAM
and virtual memory. The only way to clear the virtual memory is during the boot
process. It is important to clear virtual memory whenever an Xstore Point of Service PC
is rebooted. A scheduled reboot of the PC is also recommended as a means of clearing
the virtual memory.
Note: For Linux, encrypt the swap file/partition.
Steps to set up clearing virtual memory on shutdown:

1. Click Start.
3. Click Administrative Tools.
4. Double-click Local Security Policy.
5. Expand the Local Policies folder.
6. Select the Security Options folder.
7. Double-click on Shutdown: Clear Virtual Memory Pagefile.
8. Select Enabled.
9. Click Ok.
Removal Historical Sensitive Authentication Data

Previous versions of Xstore Point of Service did not store sensitive authentication data.
Therefore, there is no need for secure deletion of this historical data by the application as
required by PA-DSS v3.2.
Ensure the register has a firewall in place

A firewall is a piece of hardware or software which acts as a barrier between the local
network and the internet.
• A properly configured firewall is required for each site using a persistent connection
to the Public Internet or any private internal network where there is a potential for
unauthorized access to the Merchant's Network.
• Installing a hardware Firewall in addition to the Windows® firewall is
recommended.
• Firewalls can be configured to allow or limit the flow of data between the Xstore
Point of Service network and the public internet.
• If the Xstore Point of Service system has access to the internet, do not install credit
card processing if the site does not have a properly configured firewall in place.
• Oracle does not recommend a specific vendor's firewall. Work with the customer's
network administrator to set up something that works with the customer's
configuration.

• Windows® 7 and 8 have a built-in software firewall that should be enabled when
running Xstore Point of Service. The firewall should be enabled before installing the
Xstore Point of Service software.
• See “Firewall Port Exceptions:” for more information.
Instructions for the ensuring the register has a firewall in place are provided below for
the following operating systems:
• Windows 7, Windows 8, Windows 10, Windows Vista, Server 2008, Server 2008 R2,
PosReady 7, and So On
Windows 7, Windows 8, Windows 10, Windows Vista, Server 2008,

Server 2008 R2, PosReady 7, and So On
1. Click Start.
3. Click Windows Firewall.
4. In the left pane, click Turn Windows Firewall on or off.
5. Click Turn on Windows Firewall for each applicable network location.
6. Click OK.
Change Operating System Shell

Care should be taken to prevent unauthorized access to the desktop. Users with access to
the desktop could install malicious software and alter the approved system
configuration.
To achieve this goal, Xstore Point of Service is supplied with a replacement for the
Windows Explorer desktop named Xenvironment. The operating system must be
configured to launch Xenvironment at startup instead of Windows Explorer.
Xenvironment secures access to the desktop by requiring a password to gain access to
desktop applications.
Steps to configure the operating system to use Xenvironment:
1. Click Start.
Windows OS from Vista on: including Windows 7,

Windows 8, Windows 10, Server 2008, 2008 R2,
PosReady 7
Type Regedit.Exe in the Search field.
Click Regedit.Exe.
Continue with step 2 below.
2. Expand the Hkey_Local_Machine hive.

3. Expand the Software hive.
4. Expand the Microsoft hive.
5. Expand the Windows NT hive.
6. Expand the CurrentVersion hive.
7. Click the Winlogon folder.

8. In the right window pane, double-click the Shell icon.

9. Change the Value data field from "Explorer.Exe" to
"%systemroot%\system32\cscript.exe C:\environment\start_eng.vbs".
10. Click Ok.
11. Close the Registry Editor application.
Disable Task Manager

Task Manager provides the ability to launch new tasks that will effectively provide
access to the Windows desktop and therefore must be disabled. Steps to disable Task
Manager:
1. Click Start.

PosReady 7
Click Regedit.Exe.
2. Expand the Hkey_Current_User hive.

3. Expand the Software hive.
4. Expand the Microsoft hive.
5. Expand the Windows hive.
6. Expand the CurrentVersion hive.
7. Expand the Policies hive.
8. Expand the System hive.
9. [OPTIONAL] Create a System Folder
If the System folder does not exist under the “Policies” folder, one must be created.
Follow these steps to create the System folder:
a. Click the Policies folder.
b. Click Edit from the drop down toolbar.
c. Highlight New from the drop down menu.
d. Click Key from the expanded menu.
e. Type System for the name of the new Key and press [Enter].
10. Click Edit from the drop down toolbar.
11. Highlight New from the drop down menu.
12. Click DWORD Value from the expanded menu.
13. Type DisableTaskMgr for the name of the new DWORD value and press [Enter].
14. In the right window pane, double click DisableTaskMgr.
15. Change the Value data field from “0” to “1”.

16. Click Ok.

Disable Sensitive Buttons on Windows Security Screen

The Windows Security screen is displayed by pressing CTRL+ALT+DEL. This screen has
several buttons that, if selected, can disrupt the POS operations. Options such as
changing the operating system password, logging off the system, shutting down the
system and locking the workstation are available on this screen. To prevent this type of
scenario, the buttons on the Windows Security screen must be disabled.
Steps to disable the buttons and their associated functionality:
1. Click Start.

PosReady 7
Type gpedit.msc in the Search field.
Click gpedit.msc.
2. Expand User Configuration.

3. Expand Administrative Templates.
4. Expand System.
5. Select Ctrl+Alt+Del Options.
6. Edit the policy setting to Enable the four options shown here:
- Remove Change Password
- Remove Lock Computer
- Remove Task Manager
- Remove Logoff
Disable Fast User Switching

Set the HideFastUserSwitching dword value to 1 in
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Polici
es\System.
Note: Fast User Switching is a feature in Windows that allows you to

switch to a different computer user account without closing programs
and files first. Be sure to disable it.
Disable UAC (User Account Control) on Windows Vista, 7, 8, 2k8, & 2k8R2
Set the EnableLUA dword value to 0 in
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Policies\Sy
stem.

Disable Command Prompt Support in Safe Mode

Windows provides the ability to boot a PC with only the command prompt as the shell
application for troubleshooting purposes. In this scenario the default user has
administrative access within the operating system and can modify the security controls
that are in place on the PC. Obviously, this poses a large security hole within the
operating system.
Note: There is no equivalent step for Linux.
Steps to disable command prompt support in Safe Mode:

1. Click Start.

PosReady 7
Click Regedit.Exe.
2. Expand the Hkey_Local_Machine hive.

3. Expand the System hive.
4. Expand the CurrentControlSet hive.
5. Expand the Control hive.
6. Click the SafeBoot folder in the left window pane.
7. Double-click AlternateShell in the right window pane.
8. Change the Value data field to C:\environment\start_eng.bat from
Cmd.Exe.
9. Click Ok.
Configure Automatic OS Login

Steps to configure automatic OS login:
1. From a command prompt, type control userpasswords2.
2. Un-check Users must enter a user name and password to use this computer.
3. When prompted, enter the username and password.

Disable System Restore

Microsoft Windows feature System Restore must be disabled and remain disabled to
maintain PCI compliancy. To disable System Restore, follow the steps below:
Tip: You can also disable System Restore using the registry:
Set the DisableConfig and DisableSR dword values to 1 in the
HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows
NT\SystemRestore path of the registry.
1. From the Start Menu go to the My Computer | Properties | System Properties |

System Restore tab and enable either the Turn off System Restore option or the
Turn off System Restore on all drives option.
2. Select Ok.
3. When prompted with the following message, click Yes to confirm that you would
like to turn off the System Restore.
You have chosen to turn off System Restore. If you continue, all existing restore
points will be deleted, and you will not be able to track or undo changes to your
computer. Do you want to turn off System Restore?
4. The System Properties dialog box will close.
Install Encryption Cipher File

Xstore Point of Service utilizes AES 256 to encrypt credit and debit card numbers. The
CCENC.CIP, also known as a cipher file, contains the key used to encrypt the cardholder
data. This file is encrypted with AES 256 to prevent unauthorized access to the keys.
Only your version of Xstore Point of Service has the key to unlock it. The cipher file must
be placed in the C:\Xstore\Res\Keys directory on the lead register for proper
functionality. Once the registers are rebooted during the store close, the cipher file will
be replicated to all registers on the store network.
Please note that PCI requires that the keys used to secure cardholder data are rotated on
at least an annual basis. Oracle provides GenKeys to its customers to perform this
function. See Appendix C: “About Xstore Suite GenKeys” for additional details on
creating and maintaining your cipher file.
Review and Confirm Receipt Masking

PCI permits printing a maximum of the first six and last four digits of the credit and
debit card number on the customer copy of the receipt. Xstore Point of Service exceeds
this requirement since it is hard coded to only print the last four digits of the account
number on both the store and customer copy of the receipt.
Important: Each installation must be reviewed to confirm that the

account number is properly masked on the customer copy of the
receipt.

PCI Compliant Delivery of Updates

Xstore Point of Service POS software and its updates are delivered only through direct
action by human agent of the retailer. Customized software updates are made available
on a secure file server for retailers to download. Access to the secure software delivery
server is authenticated using username/password credentials unique to the retailer.
These credentials allow access to software deliveries that are targeted to that retailer
(retailer deliveries are segregated into folders and each retailer has access to only their
own folder). Software updates are encrypted and uploaded to a directory specific to the
retailer on the secure file server. The encryption key is shared with the customer using a
secure communication method (for example, by voice).
Generic software updates are available on OSDC (Oracle Software Delivery Cloud) for
customers to download. MD5 and SHA-256 digests are available for each software
update that should be used by a retailer's agent to verify the integrity of the software
delivery. Every retailer agent has unique credentials to access OSDC for specific software
updates.
Once the software is downloaded, it can be deployed to stores through Oracle Retail
Xstore Office deployment functionality. See the Oracle Retail Xstore Office User Guide for
more information.
PCI Compliant Remote Access

The PCI standard requires that if employees, administrators, or vendors are granted
remote access to the payment processing environment; access should be authenticated
using a two-factor authentication mechanism (username/ password and an additional
authentication item such as a token or certificate).
In the case of vendor remote access accounts, in addition to the standard access controls,
vendor accounts should only be active while access is required to provide service. Access
rights should include only the access rights required for the service rendered, and
should be robustly audited.
If users and hosts within the payment application environment may need to use third-
party remote access software such as Remote Desktop (RDP)/Terminal Server,
PCAnywhere, etc. to access other hosts within the payment processing environment,
special care must be taken.
In order to be compliant, every such session must be encrypted with at least 128-bit
encryption (in addition to satisfying the requirement for two-factor authentication
required for users connecting from outside the payment processing environment). For
RDP/Terminal Services this means using the high encryption setting on the server, and
for PCAnywhere it means using symmetric or public key options for encryption.
Additionally, the PCI user account and password requirements will apply to these access
methods as well.
When requesting support from a vendor, reseller, or integrator, customers are advised to
take the following precautions:
• Change default settings (such as usernames and passwords) on remote access
software (for example, VNC).
• Allow connections only from specific IP and/or MAC addresses.
• Use strong authentication and complex passwords for logins.
• Enable encrypted data transmission.
• Enable account lockouts after a certain number of failed login attempts.

• Require that remote access take place over a VPN via a firewall as opposed to
allowing connections directly from the internet.
• Enable logging for auditing purposes.
• Restrict access to customer passwords to authorized reseller/integrator personnel.
• Establish customer passwords.
• Remote connectivity applications must be manually started to accept an incoming
connection rather than always waiting for a connection. Therefore, the software
must be configured accordingly.
Verify User Logins Are Complex and Changed on a Regular Basis
Operating System
PC users must have unique usernames and complex passwords which are rotated on a
regular basis. The importance of using and maintaining a secure password scheme is
twofold. First, it greatly reduces the risk of un-authorized access to the Xstore Point of
Service server. Second, it facilitates proper auditing trails required for PCI compliancy.
Important: Merchants MUST apply these guidelines to all users on

the system to maintain PCI compliancy.
Passwords that are complex should be on by default for all administrators and those
employees who have access to administrative functions.
Important: Default settings MUST be changed before the site goes

live to maintain PCI compliancy. To achieve this, Oracle will not
configure a system with any default passwords. The merchant will be
responsible for selecting and providing passwords to Oracle. All
passwords should be changed every 90 days at a minimum once a POS
system enters a production environment.
Encrypt the pagefile.sys file

The pagefile.sys file is used by the Operating System as additional memory.
Encrypting this file will ensure that any sensitive data written to memory will also be
encrypted if the memory is written to disk.
Applies to the following supported platforms:
- Windows Vista
- Windows 7
- Windows 8
- Windows 10
- Windows Server 2008
- Windows Server 2008 R2
1. In an Administrator Command prompt, run the following command to encrypt the
pagefile in Windows:
fsutil behavior set EncryptPagingFile 1
2. Reboot the system for the change to take effect.

Disable Complete Memory Dump

The Complete Memory Dump option records the contents of system memory when the
computer stops unexpectedly. If enabled, this can result in PCI data being written
unencrypted to the hard drive. Therefore, Complete Memory Dump option must be
disabled on the host system.
The Small Memory Dump option records the smallest amount of information to help
identify the problem and should be enabled on the host system. This option requires a
paging file of at least 2 megabytes (MB) on the boot volume of your computer and
specifies that Windows will create a new file each time the system stops unexpectedly.
To configure Small Memory Dump option, follow these steps:
Note: Because there are several versions of Microsoft Windows, the

following steps may be different on your computer.
1. Click Start.
3. Click Performance and Maintenance.
4. Click System.
5. Click Settings in the Advanced tab under Startup and Recovery.
6. Select the Small Memory Dump option, and click Ok button to save the change.
7. Restart Windows in order for your changes to take effect.
Enable Database & Operating System Audit Logging

To enable Database audit logging, follow the steps below:
1. Launch SQL Server Management Studio.
2. In the left window pane, right click the LocalHost SQL Server instance.
3. Click the Properties option from the drop down menu.
4. In the left window pane, click Security.
5. Click Failed logins only under the Login auditing section.
6. Click Ok.
7. Close the SQL Server Management Studio application.
In addition to monitoring access to the database, Operating System access must also be
monitored. To enable Operating System audit logging, follow the steps below:
1. Launch Control Panel.
2. Double-click Administrative Tools.
3. Double-click Local Security Policy.
4. In the left window pane, expand the Local Policies hive.
5. Click the Audit Policy folder.
6. In the right window pane, double-click Audit account logon events.
7. Select both the Success and Failure options.
8. Click Ok.

9. In the right window pane, double-click Audit logon events.

10. Select both the Success and Failure options.
11. Click Ok.
12. Close the Local Security Policy window.
For troubleshooting and investigative purposes, each workstation writes to a debug log
file named DTVError.Log. The debug log is always enabled, and requires no merchant
or integration interaction. This log file is located at the following path unless otherwise
specified by the user: C:\Xstore\Flags\Log.
Note: Operating System audit logs will occasionally need to be

purged. If left unchecked and unpurged, users (such as the user that
runs Xstore Point of Service/Xenvironment) will eventually be unable
to log into the systems.
Delete expired certificates and keys

PCI requirements mandate that cryptographic key material or cryptograms such as
encryption keys stored by previous payment application versions must be removed. Old
keys and certificates should be removed once the keys and certificates reach the end of
their usable life. Such irretrievability is absolutely necessary for PCI.
To securely remove cryptographic key material or cryptograms stored by previous
payment application versions, perform the following procedures.
To delete an old certificate

1. Identify the certificate in the keystore:
keytool -list <keystore_file>
Figure D-3: Command Prompt: Identify the Certificate
2. Delete the certificate from the keystore:

keytool -delete -keystore <keystore_file> -alias <key alias>

Figure D-4: Command Prompt: Delete the Certificate
3. Confirm that the certificate has been deleted from the keystore:
keytool -list <keystore_file>
Figure D-5: Command Prompt: Confirm Deletion
To delete an old key

1. Download and extract SDelete
(http://technet.microsoft.com/en-us/sysinternals/bb897443.aspx) to a location inside
the system path.
2. Use SDelete to delete each desired key from Xstore Point of Service's res\keys folder:
sdelete -p 2 <filename>

Database Communication Encryption
Figure D-6: Command Prompt: Delete Key
3. Confirm that the file has been deleted.
Figure D-7: Command Prompt: Confirm Deletion

Communication between instances of Xstore POS and a database server will be
encrypted if the two instances are running on different machines. On the other hand, if
the two instances are running on the same machine, communication between the two
instances will not be encrypted.
Oracle
Encryption of communication between Xstore Point of Service and an Oracle database is
configured in the DataSourceConfig.xml file. By changing the values of the
OjdbcThinClientEncryptionLevel and OjdbcThinClientChecksumLevel
parameters, you can either enable or disable encryption.
The parameters can have the following values:
• REJECTED
• ACCEPTED
• REQUESTED

• REQUIRED
A typical configuration could be as follows:

<Property key="OjdbcThinClientEncryptionLevel"
value="REQUESTED" />
<Property key="OjdbcThinClientEncryptionTypes"
value="(AES256)" />

<Property key="OjdbcThinClientChecksumLevel" value="REQUESTED" />
<Property key="OjdbcThinClientChecksumTypes" value="(SHA256)" />
Please see Oracle Database Advanced Security Administratorʹs Guide for more information
on other possible options.
SQL Server
Encryption of communication between Xstore Point of Service and a SQL Server
database in configured in the xstore-base.properties file. Adding or changing the
encrypt and trustServerCertificate properties in the database connection string
determine whether database communications are encrypted.
A typical configuration could be:
jdbc:sqlserver://thehostname:1433;databaseName=xstore;
sendStringParametersAsUnicode=false;encrypt=true;
trustServerCertificate=true
Please see Connecting with SSL Encryption for more on other possible options.
Turning off Database Communication Encryption

By default, Xstore Point of Service is configured to encrypt all communications with a
database server. However, if Xstore Point of Service uses a database that is on the local
machine, performance can be improved by turning off encrypted communication
between Xstore Point of Service and the database.
Oracle
To turn off encryption between Xstore Point of Service and an Oracle database, update
the data sources configurations (except Xstore Office) in DataSourceConfig.xml:
1. Open the file DataSourceConfig.xml.
2. Turn off encryption for each DataSource group (except Xstore Office):
a. Find the key="OjdbcThinClientEncryptionLevel" property setting.
b. Change the value to ACCEPTED for the
key="OjdbcThinClientEncryptionLevel" property setting:
<Property key="OjdbcThinClientEncryptionLevel"
value="ACCEPTED" />
c. Find the key="OjdbcThinClientChecksumLevel" property setting.

Data Privacy
d. Change the value to ACCEPTED for the

key="OjdbcThinClientChecksumLevel" property setting:
<Property key="OjdbcThinClientChecksumLevel"
value="ACCEPTED" />
3. Save the file.
4. Stop and restart Xstore Point of Service.
SQL Server
To turn off encryption between Xstore Point of Service and a SQL Server database, set the
encrypt value in the SQL Server connection string to encrypt=false in the
DataSourceConfig.xml file
For example:
jdbc:sqlserver://localhost:1433;databaseName=xstore;
sendStringParametersAsUnicode=false;encrypt=false;
Data Privacy
The Xstore Suite has many features that allow it to maintain data privacy.
Data Privacy Application Programming Interface Tool

The Xstore Suite is integrated with the Omnichannel Data Privacy API Tool, allowing the
retailer to perform several actions to keep data private.
Important: The web service methods described in this section are not
available through software in the Xstore Suite. You must create your
own user interface or command line tools that will then call the
methods in the Omnichannel Data Privacy API.
End User Access and Other Requests (Data Access)

The API tool allows the retailer to request personal information for a specified person.
The response to the request contains all personal data for the person.
Web Service - Look Up Customer

Data for a customer can be looked up through a GET request with the following format:
GET <server>:<port>/xcenter/rest/privatedata/
<organization_id>::<party_id>?type=customer
where:
• <server> is the name of the Xstore Office server.
• <port> is the HTTP port for the REST API interface
• <organization_id> is the ID for your organization
• <party_id> is the Xstore Office ID for the customer
After receiving this request, Xstore Office will return a JSON object containing all the
relevant information for the customer in the Xstore Office system.

Data Privacy
Web Service - Look Up Employee

Data for an employee can be looked up through a GET request with the following
format:
GET <server>:<port>/xcenter/rest/privatedata/
<organization_id>::<party_id>?type=employee
where:
• <party_id> is the Xstore Office ID for the employee
After receiving this request, Xstore Office will return a JSON object containing all the
relevant information for the employee in the Xstore Office system.
Data Removal
The Omnichannel Data Privacy API Tool allows the retailer to remove personal data for
a specified person by anonymizing or deleting the data. The response to the request
indicates whether the removal was successful.
Note: Voiding a customer record in Xstore Point of Service does not

delete or anonymize the underlying customer data stored in the
database. The Omnichannel Data Privacy API Tool tool should be used
for this purpose.
Web Service - Remove Customer

A customer can be removed through a DELETE request with the following format:
DELETE <server>:<port>/xcenter/rest/privatedata/
where:
After receiving this request, Xstore Office will validate that the customer can be removed
(see Web Service - Validate Customer for Removal). If the customer record can be safely
removed, Xstore Office will notify Xstore Point of Service systems to anonymize data for
the customer.
This service call has the following status code responses:
• 200 - Removal successful.
• 412 - Removal unsuccessful or cannot be performed (see Web Service - Validate
Customer for Removal).
Web Service - Validate Customer for Removal

To validate that the customer record can be safely removed, perform the following GET
request for the customer:

Data Privacy
GET <server>:<port>/xcenter/rest/privatedata/validateForget/
where:
After receiving this request, Xstore Office will return one of the following status codes:
• 200 - Customer record safe for removal.
• 412 - Customer record not safe for removal.
Web Service - Remove Employee

An employee can be removed through a DELETE request with the following format:
Note: It is the retailer’s responsibility to delete user data from the

database.
Deleting a user through the Omnichannel Data Privacy API Tool does
not remove the user data from the database. The data is only
anonymized so that the data cannot be connected with a user.
where:
After receiving this request, Xstore Office will validate that the employee can be
removed (see Web Service - Validate Employee for Removal). If the employee record can
be safely removed, Xstore Office will notify Xstore Point of Service systems to
anonymize data for the employee.
• 200 - Removal successful.
• 412 - Removal unsuccessful or cannot be performed (see Web Service - Validate
Employee for Removal).
Web Service - Validate Employee for Removal

To validate that the employee record can be safely removed, perform the following GET
request for the employee:
where:

Data Privacy

• 200 - Employee record safe for removal.
• 412 - Employee record not safe for removal.
Anonymization
When removing personal data for a specified person, the system replaces the personal
data with blank fields.
Web Service - Anonymize Customer

A customer can be anonymized through a DELETE request with the following format:
where:
After receiving this request, Xstore Office will validate that the customer can be
anonymized (see Web Service - Validate Customer for Anonymization). If the customer
record can be safely anonymized, Xstore Office will notify Xstore Point of Service
systems to anonymize data for the customer.
• 200 - Anonymization successful.
• 412 - Anonymization unsuccessful or cannot be performed (see Web Service -
Validate Customer for Anonymization).
Web Service - Validate Customer for Anonymization

To validate that the customer record can be safely anonymized, perform the following
GET request for the customer:
where:
• 200 - Customer record safe for anonymization.
• 412 - Customer record not safe for anonymization.
Web Service - Anonymize Employee

A employee can be anonymized through a DELETE request with the following format:

Data Privacy
where:
After receiving this request, Xstore Office will validate that the employee can be
anonymized (see Web Service - Validate Employee for Anonymization). If the employee
record can be safely anonymized, Xstore Office will notify Xstore Point of Service
systems to anonymize data for the employee.
• 200 - Anonymization successful.
• 412 - Anonymization unsuccessful or cannot be performed (see Web Service -
Validate Employee for Anonymization).
Web Service - Validate Employee for Anonymization

To validate that the employee record can be safely anonymized, perform the following
GET request for the employee:
where:
• 200 - Employee record safe for anonymization.
• 412 - Employee record not safe for anonymization.
Customer Consent
When accessing a customer record or collecting information about a customer, Xstore
Point of Service may be configured to record and store the customer's consent to having
their data collected.
Enabling Data Privacy

Data privacy features are turned off by default. The retailer may enable them in the
extension layer, then create a build of Xstore Point of Service and Xstore Office that has
these features turned on.
See the Oracle Retail Xstore Point of Service and Xstore Office Development Environment Setup
white paper and the Oracle Retail Xstore Point of Service and Xstore Office Development
Environment Setup white paper for information about setting up a build server and
creating a build of Xstore Point of Service and Xstore Office.

E
Base OS and DB Configuration
Base Operating System Configurations

Note: This process assumes that an Oracle Certified Hardware
Platform is being used.
1. Install the Operating System (OS)

2. Install all PC device drivers
3. Install all Peripheral drivers
4. Configure Networking settings (tcpip)
5. Configure the machine name and workgroup
6. Set up two OS users (App User and Administrative User):
- App User will be configured as a user
- Administrative User will be configured as an Administrator
- Set users up with secure (complex) PCI-compliant passwords
7. Set the system to auto log in with the Xstore Point of Service user, and to force
automatic login
8. Enable a firewall
9. Disable windows automatic updates
10. Set the desired screen saver for the Xstore Point of Service user
11. Disable Ctl+Alt+Del menu options (Windows only)
Refer to Appendix D: “PCI Best Practices: Implementation & Configuration” for
more information.
Base OS and DB Configuration E-1

Base Software Installation Configurations
Base Software Installation Configurations

Prerequisites
• Install the following:
- Remote connectivity software: Complex, non-default passwords and user names
should be used for all login accounts.
* Enable logging for remote connectivity applications
* Change the remote connectivity user name and password
* Encrypt remote connectivity communications channel
* Disable remote connectivity applications from auto starting
- 7-zip
- Notepad++
- Antivirus software (See also: “Operating Systems: General Considerations”)
• Authorization Switch software
• Polling software
• Database platform application
• Latest OS and DB Service Packs and Security Patches
• Xstore Point of Service application (See Chapter 5, “Install Xstore Point of Service”)
• Xenvironment application (See “Install Xenvironment” of Chapter 5, “Install Xstore
Point of Service”).
- Will be configured as the OS shell
E-2 Implementation and Security Guide

F
Xstore Office Broadcaster System
Overview
Important: All broadcaster-related configuration is done by defining
Spring beans in the xcenter-spring-beans.xml configuration file.
This file is located in the xcenter-config directory.
The broadcaster system in Xstore Office is used to transmit PosLog data to other
systems. The data is transmitted just as Xstore Office receives it from the registers via the
Replication system.
Note: Refer to Appendix G: “Replication” for more information about

the transmission and ordering of PosLog data via the replication
system.
The broadcaster system has the ability to handle JAXB object format, Raw string format,
or a “subset” format of PosLog data to meet the differing requirements of various 3rd
party systems. (See “Supported PosLog Data Formats”).
For example, web services for Customer Engagement Cloud Service systems expect a
POSLOGType type JAXB object; however, the XBR system requires raw string PosLog data
which is exactly the same as what is sent from Xstore Point of Service to Xstore Office.
The architecture of the broadcaster system makes it possible to develop additional
custom broadcasters capable of sending data to any other remote 3rd party system.
Although all existing Xstore Office broadcasters communicate only to SOAP web
services, the broadcaster system's architecture is technology-agnostic regarding the
technical requirements of the remote systems. Broadcasters can be implemented that
send data to an FTP server, a REST web service, a message queue, email, a twitter
account, etc.
Xstore Office Broadcaster System F-1

Generic Broadcasters
Generic Broadcasters
Generic broadcasters allow customers to develop their own SOAP web server using one
of the Xstore Office generic WSDLs. Once such a server is implemented and running,
Xstore Office can easily be configured to broadcast data to that server, without requiring
any custom Xstore Office development. The key to this scenario is that the customer's
web service must be implemented using one of the generic, unmodified Oracle WSDLs.
These WSDLs were created by the Xstore Office development team and are included
with the base Xstore Office software. Generic broadcasters can successfully broadcast
data to a remote server provided that server strictly adheres to the Oracle WSDL.
Supported PosLog Data Formats

The format of PosLog data sent by a particular broadcaster to a remote system is dictated
by the remote system. The broadcaster system architecture does not impose any
restrictions on the format of the PosLog data being sent. When a broadcaster is
implemented, one of its primary tasks is to adapt the PosLog data from its native Xstore
Office format to the format required by the remote server.
There are three basic "styles" of formatting the data: Object Format, Raw XML String
Format, and Subset Format. Every existing broadcaster in base Xstore Office uses one of
these three styles.
Object Format
SOAP web services support the ability to define methods that can accept and return
"objects" which are defined by the XML Schema Definition (XSD) language.
The Customer Engagement Cloud Service broadcaster is a broadcaster that uses the
object-based approach. Customer Engagement Cloud Service has a public SOAP web
service for accepting PosLog data. The service has a method which accepts an XSD-
defined PosLog object. This XSD is part of the web service's WSDL; it is defined and
controlled by the Customer Engagement Cloud Service project team. The Xstore Office
Customer Engagement Cloud Service broadcaster must convert each PosLog object that
needs to be sent to Customer Engagement Cloud Service into Customer Engagement
Cloud Service's PosLog XSD format before sending it.
Having a web service defined by SOAP and XSDs generally makes it easier for
developers to write software that manipulates the data being sent/received because they
can be manipulated directly as objects in their native programming language.
A disadvantage to this approach is that the SOAP/XSD definitions are very rigid,
meaning if (for example) some additional, retailer-specific new information needs to be
included in the PosLog, and this data needs to be sent by a broadcaster and captured by
a remote server, then both the broadcaster and the remote server would have to be given
modified versions of the SOAP/XSD documents, and code changes must be made in
order to include the new data. These are not necessarily difficult changes to make, but
the important part is that code changes/re-compiling will be required.
F-2 Implementation and Security Guide

Currently Available Broadcasters
Raw XML String Format

Xstore Point of Service registers save PosLog data to a local file, with each PosLog
message being encoded as a simple raw string of XML data. Broadcasters can be
implemented to send this raw XML string directly without converting it into any other
format or object.
The XBR broadcaster is a broadcaster that uses the raw XML string approach.
Implementing such a broadcaster is fairly simple since no conversion of the data is
necessary. Also, no code changes to the broadcaster will ever be necessary even when
new information (like customer-specific additions to the PosLog data) needs to be added
to the PosLog.
The main disadvantage to this approach is that the remote server receives the PosLog
data in Oracle proprietary Xstore Point of Service/Xstore Office raw string format. It is
incumbent on the developer implementing the server to figure out how to parse the raw
XML string and extract the meaningful data from it.
Also note that when customer-specific changes/additions are made to the PosLog data,
code changes may still be required in the server in order to accept and use the new data,
even if no changes need to be made to its associated Xstore Office broadcaster.
Subset Format
In some cases, an external system may only be interested in just a few key pieces of
information from each PosLog transaction. There is no requirement that a broadcaster
send all of the data in each PosLog. In fact, a broadcaster does not need to send every
record; it can decide to ignore or filter out certain PosLog transactions based on any kind
of logic that can be programmed.
The remote system dictates what pieces of information should be sent, and in what
format.
For example, if the remote system only wants to know the Id of the transaction and the
total amount paid, then a broadcaster for this system can be written to simply send only
those few pieces (a subset) of information.

Type of
Sends Remote Who owns/ Server
Broadcaster PosLog data Service defines service authentication
Name as Interface interface requirements
Customer object SOAP web Customer Proprietary

Engagement Cloud service Engagement Cloud application-level
Service Broadcaster (WSDL) Service project authentication (as
team required by
Customer
Engagement Cloud
Service)
Order subset SOAP web Order none

Management service Management
System Cloud (WSDL) System Cloud
Service Broadcaster Service project
team
Implementation and Security Guide F-3

Type of
Sends Remote Who owns/ Server
Broadcaster PosLog data Service defines service authentication
Name as Interface interface requirements
XBR Broadcaster raw XML SOAP web XBR project team Proprietary
string service application-level
(WSDL) authentication (as
required by the
XBR server)
Generic Object object SOAP web Xstore Office HTTP basic

Broadcaster service project team authentication
(WSDL) (optional)
Generic String raw XML SOAP web Xstore Office HTTP basic
Broadcaster string service project team authentication
(WSDL) (optional)
ReSA Broadcaster object SOAP web Xstore Office HTTP basic

service project team authentication
(WSDL) (optional)
Customer Engagement Cloud Service Broadcaster Considerations

There are a few considerations related to Customer Engagement Cloud Service SOAP
web services that have an impact on the Customer Engagement Cloud Service
broadcaster:
• Proprietary authentication - starting with Customer Engagement Cloud Service
11.4, Customer Engagement Cloud Service's SOAP web services may be configured
to use a proprietary form of authentication. When so configured, any Xstore Office
Customer Engagement Cloud Service Broadcasters must make use of a special
configuration in xcenter-spring-beans.xml. The config file contains a sample
configuration for the Customer Engagement Cloud Service broadcaster, and
includes additional notes related to Customer Engagement Cloud Service's special
authentication requirements.
• TLS - if the Customer Engagement Cloud Service server is configured to use TLS
(the url for the web service starts with https), it is necessary to export public key
from the Customer Engagement Cloud Service server's keystore, and import/install
it into Xstore Office's truststore in order to facilitate communication between two
systems.
XBR Broadcaster Considerations

There are a few special considerations related to the XBR SOAP web service that have an
impact on the XBR broadcaster:
• Proprietary authentication - the XBR SOAP web service uses a proprietary form of
authentication that requires special configuration in
xcenter-spring-beans.xml. The config file contains a sample configuration for
the XBR broadcaster, and includes additional notes related to XBR's special
authentication requirements.
• TLS - because the server hosting the XBR SOAP web service is configured to use TLS
(the url for the web service starts with https), it is necessary to export public key
from the XBR server's keystore, and import/install it into Xstore Office's truststore in
order to facilitate communication between two systems.

The Broadcaster Database Table

The trn_poslog_work_item table in the Xstore Office replication database queues up
items of work for the broadcasters. See “Periodic Maintenance of the
trn_poslog_work_item Table” for information about maintaining this table.
As PosLog records are replicated into Xstore Office, records are queued up in this table
for each configured broadcaster.
For example, if you had two broadcasters configured in Xstore Office, each new replicated PosLog
record would cause two new records to be added into this table. The records would be
distinguished by the broadcaster service id, which is defined in the broadcaster configuration file.
Each record in trn_poslog_work_item contains sufficient fields to uniquely identify
a single record from the trn_poslog_data table. The trn_poslog_data table (in
the Xstore Office database) contains the actual PosLog data that is to be sent by each
configured broadcaster.
Each configured broadcaster is identified by the combination of organization_id and
service_id fields, as broadcasters are Org Id specific. Each register/store may only
belong to a single Org Id, however an Xstore Office server may serve multiple Org Ids.
Any single broadcaster can only belong to a single Org Id. This is in keeping with all
Oracle software products, where the concept of Org Id is intended to preserve a very
rigid separation of data across organizations.
trn_poslog_work_item Table
Name Data Type Allow Null
organization_id (PK) NUMBER(10) NOT NULL
rtl_loc_id (PK) NUMBER(10) NOT NULL
business_date (PK) DATE NOT NULL
wkstn_id (PK) NUMBER(19) NOT NULL
trans_seq (PK) NUMBER(19) NOT NULL
service_id (PK) VARCHAR2(60) NOT NULL
work_status VARCHAR2(200) NULL
error_details LONG NULL
create_date DATE NULL
create_user_id VARCHAR2(30) NULL
update_date DATE NULL
update_user_id VARCHAR2(30) NULL

service_id Field
Each configured broadcaster is indicated by the service_id field. Each PosLog
transaction record which is replicated into Xstore Office is also queued into this table for
each configured broadcaster (indicated by service_id).
The default service_id for each Broadcaster is as follows:
Broadcaster Implementation Broadcaster

Name service_id Class
Customer POST_TRANSACTION_RELATE com.micros_retail.xcenter.broadcast

Engagement Cloud .relate.RelateBroadcaster
Service Broadcaster
Order POST_TRANSACTION_SERENADE com.micros_retail.xcenter.broadcast

Management .serenade.SerenadeBroadcaster
System Cloud
Service Broadcaster
XBR Broadcaster POST_TRANSACTION_XBR com.micros_retail.xcenter.broadcast

.xbr.XBRBroadcaster
Generic Object GENERIC_POSLOG_OBJ_BROADC com.micros_retail.xcenter.broadcast

Broadcaster ASTER .generic.v2.GenericPoslogObjBroad
caster
Generic String GENERIC_POSLOG_STR_BROADC com.micros_retail.xcenter.broadcast

Broadcaster ASTER .generic.v1.GenericPoslogStrBroadc
aster
ReSA Broadcaster RESA_BROADCASTER com.micros_retail.xcenter.broadcast

.generic.v3.GenericPoslogObjBroad
caster
Note that the ReSA broadcaster is a
GenericPoslogObjBroadcaster.
work_status Field
As the broadcasters process their respective records, the statuses of their records are
maintained in the work_status field.
Note: The types of error values found in the work_status field are
subject to change, and are completely dependent on how each
broadcaster is implemented. There is no strict global standard of error
codes in this field. Aside from "NEW", and "COMPLETE", any other
value in work_status can be considered as some kind of error code.
Each new record added to trn_poslog_work_item is initialized with a

work_status field set to "NEW". As the broadcasters process their respective records,
the current status is maintained in the work_status field. Each broadcaster thread
looks for records with its orgId and broadcasterServiceId and a work_status of
"NEW". The "oldest" of these records is the next record it tries to broadcast.
See “Broadcaster Processing” for more information about this process.

Broadcaster Configuration
Important: There is no automated migration path for performing a
version upgrade. All broadcasters will need to be manually
reconfigured in the xcenter-spring-beans.xml config file.
All broadcaster-related configuration is done by defining Spring beans in the xcenter-

spring-beans.xml config file located in the same directory as
xcenter.properties.
The xcenter-spring-beans.xml file is based on Spring technology. For this reason,
it can be helpful to consult Spring's own documentation on defining/configuring beans,
dependency injection, etc.
Note: For more information about Spring, refer to the documentation at:
http://static.springsource.org/spring/docs/4.3.x/spring‐framework‐reference/html/
http://static.springsource.org/spring/docs/4.3.x/spring‐framework‐reference/html/
beans.html#beans‐factory‐xml‐import
The broadcaster bean Ids are named arbitrarily, and the names are only referenced
within this file (with one exception, serenadeServiceConfig). Refer to “Order
Management System Cloud Service Broadcaster” for more information about this
exception.
A fundamental rule of Spring requires every bean ID to be unique.
A Spring bean defines each broadcaster. (This bean must also be added to the main list of
broadcasters in order for that broadcaster to run when Xstore Office starts up).
Getting Started
To configure a broadcaster, you will need the following information:
1. Organization Id - Each broadcaster bean must define an Org Id.
2. Broadcaster service id - Each broadcaster bean must define a
broadcasterServiceId. The name is arbitrary; the existing examples in the
config file can be used.
3. Broadcaster implementation class - This is determined by what kind of remote
system you are broadcasting to (for example, Customer Engagement Cloud Service,
XBR, etc.).
4. All information required to connect to the remote system (such as hostname, port,
username/password, etc.).
Most broadcaster beans must refer to another Spring bean which defines a Jaxws
connection/configuration information bean: either a JaxWsPortProxyFactoryBean
or MrJaxWsPortProxyFactoryBean (see “Jaxws Broadcaster Configuration” for
more information).

Sample Configuration of a Single Customer Engagement Cloud Service

Broadcaster
xcenter-spring-beans.xml
1 Broadcaster Id - Each broadcaster needs a unique Spring bean Id. These Ids must be
unique within this config file, but the actual Id is arbitrary and can be anything. These
Ids are only used to tie things together within the Spring config file.
2 Broadcaster implementation class - This is the Java class in Xstore Office that
implements IBroadcaster and is designed to communicate with a specific type of
remote server (i.e. the RelateBroadcaster class can broadcast to a Customer
Engagement Cloud Service server).
3 orgId - This is the orgId of the Xstore Point of Service PosLog data that this
broadcaster should process. (In most single-org Xstore Office installations this value will
be 1, not 1000 as shown in this example).
4 broadcasterServiceId - This Id, along with the orgId, uniquely identifies this
broadcaster within the Xstore Office broadcaster system. When a PosLog record is added
to the trn_poslog_work_item table for this broadcaster, the service_id field in
that table is initialized with this configured broadcasterServiceId. This enables
each broadcaster to individually keep track of what data it is responsible for processing.
Also, the broadcasterServiceId will show up in various administrative tools in the
Oracle Retail Xstore Office user interface, so that administrators can refer to particular
broadcasters. Refer to the Oracle Retail Xstore Office User Guide for more information.
5A and 5B References to remote service connection info - Each broadcaster needs to
refer to a second Spring bean to get additional configuration information about how it
can connect to the remote system. The Id of this bean is also arbitrary, but a wise
convention is to base it on the Id of the broadcaster bean
("postTransactionRelate_1"), and append it with the kind of connection
implementation that's being used (for example,
"postTransactionRelate_1_jaxws"). All sample broadcaster configurations are
named using this convention.
6 Various broadcaster configuration parameters - These parameters control certain
aspects of timing and behavior of this broadcaster. All broadcasters have these same set
of parameters. The default values are generally sufficient.

7 Connection configuration implementation class - Most broadcasters (not all, see

Order Management System Cloud Service Broadcaster) use Spring's
JaxWsPortProxyFactoryBean class (or an Oracle-enhanced version of it called
MrJaxWsPortProxyFactoryBean) to configure all parameters necessary to talk to a
remote SOAP web service. All of the parameters in a bean of this class (such as this
"postTransactionRelate_1_jaxws" bean) are dictated by this Spring class. It
provides a great deal of flexibility in being able to talk to remote SOAP web services.
(Refer to Spring's documentation on the usage and capabilities of
JaxWsPortProxyFactoryBean).
8 endpointAddress - Of all of JaxWsPortProxyFactoryBean's configuration
parameters, this is probably the only one you will need to configure, as it specifies the
SOAP web service's URL which includes the hostname, port, and some other parameters
(depending on the service). For example, Customer Engagement Cloud Service needs an
"org code", which is related to orgId but is an alpha-code rather than a numeric code.
9 Various connection configuration parameters - These parameters are part of
JaxWsPortProxyFactoryBean's configuration. However, the values provided in the
sample configs for all of the available broadcasters should likely already be set to what
you need.
10 customProperties (Only for JaxWsPortProxyFactoryBeans) - All sample configs
for broadcasters using JaxWsPortProxyFactoryBean are pre-configured to refer to
another bean called "jaxwsCustomProperties" which simply increases the default
connection timeouts. It's probably fine for all broadcasters to use the more conservative
timeouts, but you always have the option to provide specific timeouts for any single
broadcaster if necessary. This can be done using standard Spring bean configuration
techniques. Refer to Spring's own documentation for more information.

Optional Parameters For Broadcasters
Optional Parameters For Broadcasters

The optional parameters shown below are used to configure the broadcaster timing and
behavior. These parameters apply to all broadcasters, and the default values should be
sufficient for most installations.:
Table F-1: Valid optional parameters for broadcasters
Parameter Name
Default
Description Value Unit
workQueueBatchReadSize
How many records in a batch for broadcaster to load at once 100 PosLog
record
pollingIntervalMillis
How much time, in milliseconds, for the interval between 10000 ms

each loading of records
retrySleepMillis
How much time, in milliseconds, for the interval between 5000 ms

each retry if there's a failure during broadcasting
threadcount
How many threads should the broadcaster use for 1

processing
Note: Default values will be used if parameters, such as those shown

above, are not defined.

Customer Engagement Cloud Service Broadcaster

To configure and enable Customer Engagement Cloud Service Broadcaster in an
organization with an organization_id of 1, perform the following steps.
Important: After configuring a broadcaster it must also be enabled.

To enable the broadcaster, locate the list of enabled broadcasters and
add your configured broadcaster bean to it as indicated in step 3
below. The list is located towards the top of the xcenter-spring-
beans.xml file, in a bean with the id "broadcasterManager".
1. Specify the broadcaster property parameters:
Note: The default values for the optional parameters (“Optional

Parameters For Broadcasters”) can be used for most installations.
<bean id="postTransactionRelate_1" class=

"com.micros_retail.xcenter.broadcast.relate.RelateBroadcaster">
<constructor-arg name="orgId" value="1000"/>

<constructor-arg name="broadcasterServiceId"
value="POST_TRANSACTION_RELATE"/>
<constructor-arg name="jaxwsService"
ref="postTransactionRelate_1_jaxws"/>
<property name="filters">
<list value-type=
"com.micros_retail.xcenter.broadcast.IBroadcastFilter">
<ref bean="onlyIncludeRetailSaleAndPostVoid" />
</list>
</property>
<property name="xmlModifiers">
<list value-type=
"com.micros_retail.xcenter.broadcast.IXMLModifier">
<ref bean="removePCIData"/>
</list>
</property>
<property name="retrySleepMillis" value="5000" />

<property name="workQueueBatchReadSize" value="100" />
<property name="pollingIntervalMillis" value="10000" />
<property name="threadCount" value="1" />

</bean>
<bean id="postTransactionRelate_1_jaxws" class=

"org.springframework.remoting.jaxws.JaxWsPortProxyFactoryBean" >
<property name="endpointAddress" value="http://

RELATE_HOSTNAME:8084/soap/ORGCODE/v1_0/PoslogServices?wsdl" />
<property name="serviceInterface" value=

"com.micros_retail.xcenter.poslog.relate.PoslogServicesApi" />
<property name="wsdlDocumentUrl" value=
"classpath:wsdl/relate/PoslogServicesApiService.wsdl" />
<property name="namespaceUri" value="http://
v1_0.poslog.webservices.csx.dtv.com/" />
<property name="serviceName" value=
"PoslogServicesApiService" />
<property name="portName" value="PoslogServicesApiPort" />
<property name="customProperties" ref=
"jaxwsCustomProperties" />
<property name="handlerResolver"
ref="postTransactionRelate_1_auth"/>
</bean>
<bean id="postTransactionRelate_1_auth" class=

"com.micros_retail.xcenter.broadcast.relate.
RelateAuthHandlerResolver">
<property name="relateOrgCode" value="ORG_CODE" />
<property name="encryptedUsername"
value="Pj4+MAAAAADXsyNI0q+rBCNBHqcKipM1" />
<property name="encryptedPassword"
value="Pj4+MAAAAABMOQqvnNuNXrgi792UB4OZ" />
</bean>
2. Specify the broadcaster endpointAddress parameter as needed.
3. In xcenter-spring-beans.xml uncomment/add the Customer Engagement
Cloud Service broadcaster bean reference to the list below as necessary. The
broadcaster will not run unless it is added to this list.
<bean id="broadcasterManager"
class="com.micros_retail.xcenter.broadcast.BroadcasterManager" >
<property name="broadcasterList">
<list value-type=
"com.micros_retail.xcenter.broadcast.IBroadcaster">

XBR Broadcaster
<ref bean="postTransactionRelate_1"/>





</list>
</property>
</bean>
4. Save the file.
XBR Broadcaster
There are a few special considerations related to the XBR SOAP web service that have an
impact on the XBR broadcaster.
• Proprietary authentication
The XBR SOAP web service uses a proprietary form of authentication that requires
special configuration in xcenter-spring-beans.xml. The config file contains a
sample configuration for the XBR broadcaster, and includes detailed comments on
how to configure its authentication parameters.
• TLS
Because the server hosting the XBR SOAP web service is configured to use TLS (the
url for the web service starts with https), it is necessary to export the public key from
the XBR server's keystore, and import/install it into Xstore Office's truststore in order
to facilitate communication between two systems. For details about the public key,
please refer to Appendix B: “Public Key Certificates”.
As mentioned above, the XBR broadcaster needs to send authentication info using a
proprietary technique (it does not use standard http basic authentication). The
XBRAuthHandlerResolver class implements this technique. You must define a Spring
bean using this class, specifying the encrypted username and password of the XBR
server. Then, set the "handlerResolver" property of the XBR
JaxWsPortProxyFactoryBean to use that XBRAuthHandlerResolver.
To configure and enable XBR Broadcaster on an organization with an
organization_id of 1, perform the following steps.

1. Specify the broadcaster parameters:

Parameters For Broadcasters”) can be used most installations.

XBR Broadcaster
<bean id="postTransactionXBR_1"
class="com.micros_retail.xcenter.broadcast.xbr.XBRBroadcaster">

value="POST_TRANSACTION_XBR"/>
ref="postTransactionXBR_1_jaxws"/>

</bean>
<bean id="postTransactionXBR_1_jaxws" class=

"org.springframework.remoting.jaxws.JaxWsPortProxyFactoryBean" >
<property name="endpointAddress" value="https://

XBR_HOSTNAME:8443/xbr-loader/PosLogServices" />
<property name="serviceInterface"
value="com.micros_retail.xcenter.poslog.xbr.PosLogServices" />
<property name="wsdlDocumentUrl" value=
"classpath:wsdl/xbr/PosLogServices-XBR.wsdl" />
<property name="namespaceUri" value="http://ws.xbr.dtv/" />
<property name="serviceName" value="PosLogServicesService" />
<property name="portName" value="PosLogServicesPort" />
<property name="customProperties"
ref="jaxwsCustomProperties" />
<property name="handlerResolver"
ref="postTransactionXBR_1_auth"/>
</bean>
<bean id="postTransactionXBR_1_auth" class=

"com.micros_retail.xcenter.broadcast.xbr.XBRAuthHandlerResolver">
</bean>

XBR Broadcaster
2. Specify the broadcaster endpointAddress parameter as needed.

3. Specify the encrypted username and password of the XBR server.
4. Set the handlerResolver property to use the XBRAuthHandlerResolver.
5. In xcenter-spring-beans.xml uncomment/add the XBR broadcaster bean
reference to the list below as necessary. The broadcaster will not run unless it is
added to this list.
<list value-type=


<ref bean="postTransactionXBR_1"/>
</list>
</property>
</bean>
6. Save the file.
Because XBR uses TLS for security, the public key must be exported from the XBR
Loader's keystore, and then imported into each Xstore Office system's truststore in order
to initialize the communication between the two systems.

Order Management System Cloud Service Broadcaster

You may only have a maximum of ONE Order Management System Cloud Service
broadcaster in the system; multiples are not supported. To configure and enable Order
Management System Cloud Service Broadcaster in an organization with an

Note: The name of the SerenadeServiceConfig bean MUST have a

bean Id of "serenadeServiceConfig"; do not alter this bean Id.
The default values for the optional parameters (“Optional Parameters

For Broadcasters”) can be used most installations.
<bean id="postTransactionSerenade" class="com.micros_retail.

xcenter.broadcast.serenade.SerenadeBroadcaster">

value="POST_TRANSACTION_SERENADE"/>
<constructor-arg name="config"
ref="serenadeServiceConfig"/>
<list value-type=
<ref bean="crossChannelReturnFilter" />
</list>
</property>

</bean>
<bean id="serenadeEndpoint" class=

"com.micros_retail.xcenter.serenade.SerenadeEndpoint">

<property name="configInfo" ref="serenadeServiceConfig" />

</bean>

<bean id="serenadeServiceConfig" class="com.micros_retail.
xcenter.serenade.config.SerenadeServiceConfig" >
<property name="url" value="http://HOSTNAME:8080/

CWDirectCPService/services/CWMessageIn" />
<property name="username"
<property name="password"


</bean>
2. Specify the Order Management System Cloud Service connection information in
senrenadeServiceConfig bean.
3. In xcenter-spring-beans.xml uncomment/add the Order Management System
Cloud Service broadcaster bean reference to the list below as necessary. The
broadcaster will not run unless it is added to this list.
<list value-type=

<ref bean="postTransactionSerenade"/>
</list>
</property>

Generic Object Broadcaster
</bean>
4. Save the file.

To configure and enable a Generic Object Broadcaster in an organization with an


<bean id="genericObjBroadcaster_1" class="com.micros_retail.

xcenter.broadcast.generic.v2.GenericPoslogObjBroadcaster">

value="GENERIC_POSLOG_OBJ_BROADCASTER"/>
ref="genericObjBroadcaster_1_jaxws"/>
<list value-type=
<ref bean="onlyIncludeRetailSaleTransactions" />
</list>
</property>
<list value-type=
</list>
</property>


</bean>
<bean id="genericObjBroadcaster_1_jaxws" class="com.

micros_retail.xcenter.broadcast.MrJaxWsPortProxyFactoryBean" >
<property name="endpointAddress" value="http://HOSTNAME:8080/

BASEURL/PoslogObjReceiverApiService" />
value="Pj4+MAAAAAARqsDet64PeZWB8ZqXMzjf" />
value="Pj4+MAAAAABJEgCcNmcmexHfJdgKH+5G" />
<property name="serviceInterface" value="com.micros_retail.

xcenter.poslog.poslogobj.v2.PoslogObjReceiverApi" />
<property name="wsdlDocumentUrl" value="classpath:wsdl/
generic_poslog_object_v2/PoslogObjReceiverApiService.wsdl" />
v2.ws.poslog.xcenter.dtv/" />
<property name="serviceName"
value="PoslogObjReceiverApiService" />
<property name="portName" value="PoslogObjReceiverApiPort" />
</bean>
2. Specify the broadcaster endpointAddress parameters as needed.
3. Specify an encrypted username and password as needed.
4. In xcenter-spring-beans.xml uncomment/add the Generic Object broadcaster
bean reference to the list below as necessary. The broadcaster will not run unless it is
added to this list.
<list value-type=


Generic String Broadcaster

<ref bean="genericObjBroadcaster_1"/>
</list>
</property>
</bean>
5. Save the file.

To configure and enable a Generic String Broadcaster in an organization with an


<bean id="genericStrBroadcaster_1" class="com.micros_retail.

xcenter.broadcast.generic.v2.GenericPoslogStrBroadcaster">

value="GENERIC_POSLOG_STR_BROADCASTER"/>
ref="genericStrBroadcaster_1_jaxws"/>
<list value-type=
</list>
</property>



</bean>
<bean id="genericStrBroadcaster_1_jaxws" class="com.

micros_retail.xcenter.broadcast.MrJaxWsPortProxyFactoryBean" >

BASEURL/PoslogStrReceiverApiService" />
value="Pj4+MAAAAAARqsDet64PeZWB8ZqXMzjf" />
value="Pj4+MAAAAABJEgCcNmcmexHfJdgKH+5G" />

xcenter.poslog.poslogstr.v1.PoslogStrReceiverApi" />
generic_poslog_string_v1/PoslogStrReceiverApiService.wsdl" />
value="PoslogStrReceiverApiService" />
<property name="portName" value="PoslogStrReceiverApiPort" />
</bean>
4. In xcenter-spring-beans.xml uncomment/add the Generic String broadcaster
bean reference to the list below as necessary. The broadcaster will not run unless it is
added to this list.
<list value-type=


Retail Sales Audit Broadcaster

<ref bean="genericStrBroadcaster_1"/>
</list>
</property>
</bean>
5. Save the file.

Note: The Retail Sales Audit (ReSA) Broadcaster uses a
GenericPoslogObjBroadcaster to broadcat data to RTLogGenerator, which
then creates flat files for ReSA. You must v3 of a GenericPoslogObjBroadcaster; it
will not work with v1 or v2.
To configure and enable a Retail Sales Audit (ReSA) broadcaster in an organization with
an organization_id of 1, perform the following steps.


<bean id="ReSA_Broadcaster" class="com.micros_retail.

xcenter.broadcast.generic.v3.GenericPoslogObjBroadcaster">

value="RESA_BROADCASTER"/>
ref="ReSA_Broadcaster_jaxws"/>
<list value-type=
</list>
</property>


</bean>
<bean id="ReSA_Broadcaster_jaxws" class="com.micros_retail.

xcenter.broadcast.MrJaxWsPortProxyFactoryBean" >

rtlog-generator/service" />
xcenter.poslog.poslogobj.v3.PoslogObjReceiverApi" />
generic_poslog_object_v3/PoslogObjReceiverApiService.wsdl" />
value="PoslogObjReceiverApiService" />
<property name="portName" value="PoslogObjReceiverApiPort" />
value="Pj4+MAAAAAC2beJl37rNn5Mq7bn0889b" />
value="Pj4+MAAAAACDjHCbGx7x67Xc+DeNRsEg" />
</bean>
4. In xcenter-spring-beans.xml uncomment/add the ReSA broadcaster bean
reference to the list below as necessary. The broadcaster will not run unless it is
added to this list.
<list value-type=

Broadcaster Configuration for a Multiple-instance (Cluster) Installation

<ref bean="ReSA_Broadcaster"/>
</list>
</property>
</bean>
5. Save the file.
Broadcaster Configuration for a Multiple-instance (Cluster)

Installation
It is very important that each instance of Xstore Office (and its respective xcenter-
spring-beans.xml config file) has the identical configuration setup for broadcasters.
Since the replication system is what feeds the broadcaster's trn_poslog_work_item
table, each instance of Xstore Office is only feeding its own subset of all of the data that
needs to be broadcast. Therefore, the same broadcasting configuration must be included
on each instance.
Multiple Broadcaster Configuration

Note: In any Xstore Point of Service installation, a single register/store
belongs only to a single Org Id, however an Xstore Office server may
serve multiple Org Ids.
Broadcasters are Org Id specific, so any single broadcaster can only

broadcast data from a single Org Id. This is in keeping with all Oracle
software products, where the concept of Org Id is intended to preserve
a very rigid separation of data across organizations.
The following examples show how to set up multiple broadcasters of the same type to
either multiple Org Ids or to a single Org Id.
To configure multiple broadcasters: same type, for multiple orgIds
Customer Engagement Cloud Service Example

If your Xstore Office installation services two org Ids, and you want to broadcast data for
both orgs (1 & 2 in this example) to Customer Engagement Cloud Service, there must be
two Customer Engagement Cloud Service server endpoints, one for each org Id.
1. Configure one Customer Engagement Cloud Service broadcaster bean with:
- id="postTransactionRelate_1",
- an orgId of 1,
- a broadcasterServiceId of "POST_TRANSACTION_RELATE",

Broadcaster Configuration for a Multiple-instance (Cluster) Installation
- and a jaxwsService of "postTransactionRelate_1_jaxws".

2. Copy/paste/modify the beans in step 1, creating a second set with:
- id="postTransactionRelate_2",
- an orgId of 2,
- a broadcasterServiceId of "POST_TRANSACTION_RELATE",
- and a jaxwsService of "postTransactionRelate_2_jaxws".
Even though the same broadcasterServiceId ("POST_TRANSACTION_RELATE") is used,
the two orgIds (1 vs. 2) will ensure that these are two distinct broadcasters. Each set of
broadcaster beans must be properly configured to send data to the appropriate
Customer Engagement Cloud Service Jaxws endpoint.
To configure multiple broadcasters: same type, same orgId
Generic Poslog Object Broadcaster Example

If you want to have two "generic poslog object broadcasters", within the same org Id,
broadcasting the same data to two separate servers, you can do so provided each
broadcaster has a unique broadcasterServiceId.
1. For example, given a typical single generic poslog object broadcaster with:
- orgId=1,
- the bean id "genericObjBroadcaster_1",
- a jaxwsService bean id of "genericObjBroadcaster_1_jaxws", and
- a broadcasterServiceId of "GENERIC_POSLOG_OBJ_BROADCASTER"
2. Copy/paste/modify the beans in step 1 as follows:
- leave the orgId=1,
- change the bean id to "genericObjBroadcaster_2",
- change the jaxwsService bean id to "genericObjBroadcaster_2_jaxws",
and
- invent a new broadcasterServiceId
For example "GENERIC_POSLOG_OBJ_BROADCASTER_2". Or, if the two remote
systems have particular names or purposes, you may invent more meaningfully
named broadcasterServiceIds, such as "POSLOG_OBJ_FOR_ABCDEF" and
"POSLOG_OBJ_FOR_VWXYZ".
Note: You can also rename the bean Ids to be more meaningful for
your installation since the bean Ids are arbitrary.
The broadcasterServiceIds are used in the Xstore Office replication

database table trn_poslog_work_item to identify the broadcaster. See “The
Broadcaster Database Table” for more information.

Broadcaster Processing
Jaxws Broadcaster Configuration

JaxWsPortProxyFactoryBean vs. MrJaxWsPortProxyFactoryBean
The current Xstore Office broadcasters communicate with a SOAP web service. A Spring
JaxWsPortProxyFactoryBean must be defined to contain all of the connection
configuration information necessary to talk to the service (the Order Management
System Cloud Service broadcaster is an exception).
Some SOAP web services may require "http basic authentication", which means a
username and password must be configured on the client (a broadcaster). The
JaxWsPortProxyFactoryBean does have "username" and "password" properties
which you may use to configure this information.
For this reason, Oracle created a modified version of JaxWsPortProxyFactoryBean
called "MrJaxWsPortProxyFactoryBean" which allows you to provide
"encryptedUsername" and "encryptedPassword" properties. The type of encryption is
the standard 2-way encryption used in various config files by Oracle Xstore Point of
Service/Oracle Retail Xstore Office products. This is the only difference between
MrJaxWsPortProxyFactoryBean and JaxWsPortProxyFactoryBean. The Oracle
MrJaxWsPortProxyFactoryBean works identically to
JaxWsPortProxyFactoryBean in all other respects. Refer to Spring's documentation
for more information on JaxWsPortProxyFactoryBean configuration and use.
Broadcaster Processing
Several things may happen during the broadcasting process. How the broadcaster
handles these situations is totally up to each implemented broadcaster. All current
broadcasters generally work as follows.
After attempting to broadcast a PosLog message, the attempt either succeeds or fails:
• Success - When the attempt succeeds, the broadcaster marks the
trn_poslog_work_item.work_status field as "COMPLETE" and moves on to
the next record.
• Failure - When the attempt fails, it needs to assess the kind of failure and either try
to broadcast it again, or give up.
Generally, the only type of failures that broadcasters attempt to try again are "failure
to establish communication" errors. This is the scenario where it appears that the
remote system did not receive the PosLog data. In this case, the broadcaster will
keep trying to send the data until communications are re-established.
Other types of failures are generally not re-tried, especially "application level" errors.
The Broadcaster will simply mark it with corresponding error information in the
trn_poslog_work_item.error_details field, status information in the
trn_poslog_work_item.work_status field, and no further processing is
attempted.
No Re‐try example:
The Customer Engagement Cloud Service broadcaster sends a PosLog to Customer
Engagement Cloud Service, and Customer Engagement Cloud Service sends back an error
code indicating ʺIllegal tender typeʺ (for example). The broadcaster will log this error code
into the work_status and error_details fields; however, the broadcaster will not try to send it
again because Customer Engagement Cloud Service did in fact receive the data. The
broadcasterʹs mission is complete at this point, so it moves on to the next record.

Monitoring Broadcaster Status
Monitoring Broadcaster Status

There is a "status servlet" for the broadcaster similar to the one for replication. To get
each broadcaster configuration and status information, see:
https://{xcenter hostname}:{port}/xcenter/showstatus/broadcaster
Following is a simple example for an Xstore Office instance that is running only a
Customer Engagement Cloud Service broadcaster:
************************************************************
Mon Feb 18 12:42:02 EST 20xx
Current Xcenter Instance : HOSTNAME-123
Members in cluster : 1
************************************************************
Cluster members for Organization ID 1

======================================
XST-BRDCST-100 *Designated Broadcaster*
Status & Configuration settings for Organization ID 1

=======================================================
Service ID : POST_TRANSACTION_RELATE
RETRY_SLEEP_MILLIS : 5000 (default)
WORK_QUEUE_BATCH_READ_SIZE : 100 (default)
POLLING_INTERVAL_MILLIS : 10000 (default)
Status : Running
Work Queue Status for Organization ID 1

=========================================
POST_TRANSACTION_RELATE ERROR : 1 NEW : 0 COMPLETE : 0

TOTAL : 1
Periodic Maintenance of the trn_poslog_work_item Table

Due to the high volume of constant inserting/deleting in the trn_poslog_work_item
table, periodic (daily) maintenance must be performed on this table.
Vendor-specific SQL scripts have been created to do this work. These scripts serve two
purposes:
• To keep the table and its indexes performing well, the indexes may need to be re-
created, the table may need to be "defragmented", etc. These things will be
dependent on which actual database (Oracle, SQL Server, etc.) is being used.

Testing and Debugging
• The scripts also delete replication records which have been fully, successfully
processed, and are "sufficiently old", which by default is 3 days, but is an easily
adjustable parameter in the script.
Essentially, the deletion script looks like this (SQL Server syntax, and defining
"sufficiently old" as 3 days):
delete from trn_poslog_work_item where work_status = 'COMPLETE'
and update_date < GETDATE()-3
Testing and Debugging

For testing and debugging purposes, change the logging level for the following log
category in xcenter-log4j.xml to DEBUG. This log category is used by all
broadcasters.
com.micros_retail.xcenter.broadcast
For example:
<category name="com.micros_retail.xcenter.broadcast" >
<level value="DEBUG"/>
</category>
Developer’s Notes
Developing a Custom Broadcaster
As a developer charged with creating a new broadcaster, you should be aware that one
of the primary things your broadcaster needs to do is to adapt Xstore Office PosLog data
to whatever format is required by the remote system.
The broadcaster system architecture is capable of providing Xstore Office PosLog data in
two formats: the raw XML string format, and an XSD-defined object format.
Raw XML String Format

If the remote system is going to receive the data using Xstore Office raw XML string
format (as is the case with the XBR broadcaster), you will probably want to implement
your broadcaster by subclassing Xstore Office's POSLogStringBroadcaster class.
This class gives your broadcaster the PosLog data directly in the raw XML string format,
so no adaptation of the data will be required. You only need to implement the
communications and error handling code.
XML Schema Definition Defined Object Format

If the remote system is going to receive the data as some kind of object, or as "a subset",
you will probably want to implement your broadcaster by subclassing Xstore Office's
POSLogObjectBroadcaster class. This class gives your broadcaster the PosLog data
as a Java object. This relieves you of needing to parse XML and allows you to treat the
data as a simple Java object. There are numerous strategies that can be taken to adapt
this data to whatever is needed by the remote server. Since the Xstore Office and
Customer Engagement Cloud Service PosLog objects are almost identical, Apache's
Dozer library is sufficient to copy the data from one object to the other. Or, if you're in a
“subset” scenario, it will be very convenient to extract the few pieces of PosLog data that
you need since they can be accessed from a simple Java object.

G
Replication
Overview
Replication is the process used to copy and distribute data from one database to another,
and to synchronize between the databases to maintain consistency.
Replication System Objectives:

• Data must never be lost in case of faults.
• The replication system must be flexible enough (i.e. scalable) to run in an installation
where there are multiple instances of Xstore Office set up, such as a load-balanced
cluster.
• The replication system must be reasonably performant.
Note: Reasonably performant does not imply "real time". High/peak

loads of replication throughout the day may result in a backlog of
replication data that must be processed by Xstore Office. The most
important objective is to not lose data, and to not keep Xstore Point of
Service registers waiting to save replication data. There may be some
delay between Xstore Point of Service sending data vs. its being saved
to the Xstore Office database and any further processing (such as being
sent to external systems by Xstore Office's "Broadcaster" system).
• The replication system must provide administrators with the ability to view
performance metrics, solve problems, and recover from faults.
• The replication system must reasonably preserve soft ordering of replication data
(especially in a multi-instance installation) to ensure the integrity of Xstore Office's
replicated database. Soft ordering means the chronological order of the replication
objects sent by the registers within each store should be preserved.
• Xstore Point of Service saves data to local ctl_replication_queue
• Xstore Point of Service replication process sends data to Xstore Office
• Replication data received by servlet
• Replication data is saved to the Xstore Office Replication DB (and into a table called
rpl_replication_data)
• Xstore Office replication queue processed and saved to Xstore Office DB
Replication G-1
Replication Design Overview
• (Any records which fail to be saved to the Xstore Office DB will simply remain
inside of the Replication DB (in the rpl_replication_data table), and will have
an appropriate error status code set)
Replication Design Overview

Replication data is sent directly to the replication database. This is the default setting.
The Xstore Office replication database is a SQL database, distinct and separate from the
Xstore Office and Xstore Point of Service databases. It contains a table for holding the
replication data, a table for the Xstore Office Broadcaster system, and another table for
logging information about some maintenance jobs related to replication. See “Xstore
Office Replication Database”.
Re-sequencing Publisher
The end goal of replication is to save replicated data to the Xstore Office database, and to
send some of that data to external systems using Xstore Office's Broadcaster system. (See
Appendix F: “Xstore Office Broadcaster System” for more information about Xstore
Office's Broadcaster system).
If multiple instances of Xstore Office are all receiving replication data, replicated data
may arrive into Xstore Office chronologically out-of-order, resulting in the need for "re-
sequencing".
To preserve order when multiple instances of Xstore Office are putting data into the
replication database, data partitioning—specifically by store IDs—is used. To assign
ranges of store IDs to each running re-sequencing publisher thread, the replication
system queries Xstore Office's loc_retail_loc table for a sorted list of store IDs, and
evenly (as much as possible) divides all of the stores IDs by the total number of running
threads.
Each re-sequencing publisher thread (including all such threads running across all
instances of Xstore Office) is automatically assigned a specific range of store IDs to
process. This ensures that any single store's replication data can only be processed by a
single re-sequencing publisher thread, and that the act of re-sequencing a store's
replication data cannot be affected by other threads.
The re-sequencing publisher process (including all related threads) can be individually
enabled/disabled on each instance of Xstore Office. See cluster.processes.enabled in the
“xcenter.properties Settings”.
The number of re-sequencing publisher threads running simultaneously on each
application server is set by the replication.publisher.threads_per_orgid configuration
option. See “xcenter.properties Settings”. As the property name suggests, each
organization id gets its own set of threads since data across organizations must be
segregated. The number of threads cannot be customized for each organization.
How data is re-sequenced

Each re-sequencing publisher thread polls the replication database for new replication
objects (for its assigned range of store IDs). It first gathers all the objects which arrived
into the replication database before a certain (configurable) time delay (for example, 5
minutes ago). See replication.publisher.resequencing_delay.seconds,
“xcenter.properties Settings”.
After re-sequencing (sorting) these objects by their original Xstore Point of Service
timestamp, the process can "peek into the future" and also include any additional objects
which have arrived after the delay (for example, within the last 5 minutes), but before
G-2 Implementation and Security Guide

Re-sequencing Publisher
the maximum Xstore Point of Service timestamp of all of the objects that arrived before
the delay.
Thus, the configured delay time is the maximum amount of "tolerance" Xstore Office
grants for un-ordered data to arrive into the replication database, while still being able to
keep its soft-ordering promise (see “Soft ordering - what can be expected?”).
Note: The Xstore Point of Service timestamp is used to re-sequence all

replication objects that are produced by all registers in a store. This
means that all of the registers in the store need to have "reasonably"
synchronized (within a second or two) system clocks.
Saving data to the Xstore Office database

Each replication object processed by the re-sequencing publisher is first saved to the
Xstore Office database. This is accomplished using standard DTX technology. Each
replication object contains a "payload" which is a JSON-encoded String that contains a
serialized DTX message. DTX will perform its standard insert/update/delete operations
as directed.
Sending data to the Broadcaster

After the re-sequencing publisher has safely saved the replication object to the Xstore
Office database, the replication object's payload is inspected to see if it contains "PosLog"
data. If it does, an appropriate notification is sent to the Broadcaster system's work
queue table (trn_poslog_work_item). See Appendix F: “Xstore Office Broadcaster
System” for more information.
Soft ordering - what can be expected?

• Order can only be restored to the order that was sent by Xstore Point of Service; i.e. if
Xstore Point of Service sends data in bad/wrong order, Xstore Office's replication
system does not fix it (garbage in, garbage out).
• Order cannot be ensured when faults occur during the replication process. Registers
go down, stores lose connectivity, instances of Xstore Office fail, databases go down,
network problems occur, etc. These types of faults can delay delivery of subsets of
replication records beyond the time delay configured in the re-sequencing publisher.
These types of problems cannot be fixed by the replication system.
• The top priority for the replication system is to not lose data. Ordering is considered
a secondary requirement, and problems of database integrity that arise from faults
that occur during the replication process are expected to be tolerated.
• Ordering is preserved only within each store. In other words, the order that data was
created within a store is the order that same data will be re-written into the Xstore
Office database as a result of going through the replication processes. There is
absolutely no guarantee that data across stores will be saved in the same order it was
produced.
Soft ordering - why is it important?

A customer in store X makes a purchase at register 10, and then returns an item shortly
after at the customer service desk (register 1). Imagine Xstore Office's Broadcaster
system is sending these PosLog's to Customer Engagement Cloud Service. It is important
that the purchase transaction be sent before the return transaction.
Implementation and Security Guide G-3

Running Multiple Xstore Office Instances in a Cluster
An Xstore Point of Service "customer account" table has a record for a customer's
running balance. If the DTX operations are not processed in Xstore Office (via
replication) in the same order that they were processed in the store, the computed
account balance may not match what was computed on Xstore Point of Service.
Running Multiple Xstore Office Instances in a Cluster

Since no two re-sequencing publisher threads (whether on a single Xstore Office
instance, or across multiple instances) may process the same store IDs, the members of
the cluster must communicate with each other and decide which members should be
assigned to which store IDs.
Any time an Xstore Office instance is started (and thus joins the cluster) or is shut down
or crashes (and thus leaves the cluster), the following series of events take place:
1. Each member is notified of a change to cluster membership.
2. Each member stops all of its own re-sequencing publisher threads.
3. Each member notifies the cluster when its publisher threads have stopped.
4. One member (the most recently joined) re-queries the Xstore Office database's
loc_retail_loc table to refresh the whole list of store IDs (per org id).
This member then sends the latest list of store IDs to all members of the cluster.
5. Each member waits to receive the latest list of store IDs, and also waits for all other
members to send their "stopped my publisher threads" notifications.
6. Once a member knows all cluster-wide publishing threads have stopped and the
new list of store IDs has been received, it evenly divides up the list of store IDs by
the number of members in the cluster. (Each member will perform this same
calculation, and each will produce the same exact results).
7. Each member knows which sub-range of store IDs it must now process by
considering its relative age in the cluster, for example, the oldest member uses the
first range of store IDs, the next younger uses the next range of store IDs, and so on,
up to the youngest member which uses the last range of store IDs.
8. Each member then further sub-divides its range of store IDs by the number of
configured threads for that instance of Xstore Office
(replication.publisher.threads_per_orgid).
9. Each member re-starts its re-sequencing publisher threads.
Note: This entire operation takes only a few moments to complete. It

is anticipated that cluster membership changes will occur very
infrequently, so the loss of performance incurred by having to shut
down/re-start all publishing threads should be negligible.
xcenter.properties Settings
See “Pre-Installation Configuration” of Chapter 3, “Install Xstore Office” for more
information about this file.
cluster.processes.enabled
This property controls whether this instance of Xstore Office will run any re-sequencing
publisher threads.

Xstore Office Replication Database
Valid Values: true/false
replication.publisher.resequencing_delay.seconds
This property defines the time delay used to allow re-sequencing to work. See “How
data is re-sequenced” for details. Many factors determine what this value should be; a
reasonable range could be from 5 to 300 seconds.
Valid Values: (number of seconds)
replication.publisher.polling_interval.milliseconds
This property defines how often the re-sequencing publisher will poll the
rpl_replication_data table for new objects to process. 3000 is a reasonable value
for this.
Note: As long as there are unprocessed records, the re-sequencing

publisher will continually retrieve and process these records. The
polling delay will not take effect until all records are processed, and
the thread needs to wait for new records to arrive.
Valid Values: (number of milliseconds)
replication.publisher.threads_per_orgid
This property defines how many replication re-sequencing publisher threads will be
running on this instance of Xstore Office. This same number is used for each
organization ID's data (for example, if this installation of Xstore Office manages 2
organization IDs of data, and replication.publisher.threads_per_orgid = 3,
then there will be 6 total threads running).
dtv.xcrepl.db.driver
JDBC driver to be used for the Xstore Office replication database.
dtv.xcrepl.db.url
JDBC connection URL to be used for the Xstore Office replication database.
dtv.xcrepl.db.user
Encrypted username string to connect to the Xstore Office replication database.
dtv.xcrepl.db.password
Encrypted password string to connect to the Xstore Office replication database.

The replication system is a replication "central storage" SQL database. This database is
intended to be separate and distinct from the Xstore Office and Xstore Point of Service
databases. This separation gives administrators flexibility in distributing data processing
loads and tuning the replication system for optimal performance in a way that doesn't
interfere with the rest of the system and the other databases. This replication database
experiences a pattern of usage that differs from the rest of the system, in that a relatively
high volume of data will continually be created, and quickly (usually within a few
business days) deleted.

The replication script is found in the InstallX package.
rpl_replication_data Table
Table G-1: rpl_replication_data Table
Data Type (SQL

Column Server syntax) Valid Values Description
organization_id NUMBER(10) Standard Oracle Part of primary key.

organization id
NOT NULL
rtl_loc_id NUMBER(10) Standard Oracle Part of primary key. Retail location

retail location id id
NOT NULL
wkstn_id NUMBER(19) Standard Oracle Part of primary key. Workstation id

workstation id
NOT NULL
timestamp_str CHAR(24) 20120829.133821.27 Part of primary key. This is the

9-0400 timestamp explained in “How data
NOT NULL
is re-sequenced”. The timestamp is
encoded as a string in the
following format:
yyyyMMdd.HHmmss.SSSZ (using
Java's SimpleDateFormat).
publish_status VARCHAR2(32) Any value from the This field is where the replication
Java enum process stores the processing status
ReplPublishStatus: of each replication object. Each
NEW, object starts as NEW, and is
REPROCESS, transitioned to either COMPLETE
UNBROADCASTE (fully processed),
D, COMPLETE, or UNBROADCASTED (saved to
ERROR. Xstore Office database but failed to
make it to the Broadcaster system),
or ERROR (failed to get saved to
Xstore Office database). Only
records marked as COMPLETE
may be safely deleted from this
table. When the ERROR record is
reprocessed, its status will be
changed to REPROCESS and be
picked up by replication system
again.
payload LONG (serialized DTX This is the replication data itself.

dao string)

Table G-1: rpl_replication_data Table (continued)
Data Type (SQL

Column Server syntax) Valid Values Description
payload_ VARCHAR2(254) This is a carry-over from the old

summary ctl_persist_failure table. It
is a summary (DTX object class
and primary key values) of the
DAOs contained in the replication
message. It is only initialized at the
time the re-sequencing publisher
attempts to publish a replication
object. (When the publish_status is
NEW, this value will not be
initialized). The intended use of
this is generally for diagnosing
problems (for example, when
publish_status is ERROR) and
provides a quick way to see
information contained in the
replication data.
error_details LONG This is a carry-over from the old

ctl_persist_failure table.
When a replication object fails to
be published (publish_status is
ERROR or UNBROADCASTED), a
formatted Java stack trace is saved
into this column for diagnostic
purposes.
orig_arrival_ DATE timestamp Records the timestamp of when a

timestamp replication object is initially
received in Xstore Office by the
make persistent servlet.
reprocess_user_ VARCHAR2(20) The user_id of the Xstore Point of

id Service user who performed the
reprocess.
reprocess_ DATE timestamp The last time a user performed the

timestamp reprocess.
reprocess_ NUMBER(10) 0 - max How many attempts have been

attempts made to reprocess the replication
data.
create_date DATE timestamp Standard Oracle table boilerplate.

Note: This timestamp is initialized to
the current Xstore Office time when
the record is saved to this table. It is
this timestamp which is used to offset
the ʺtime delayʺ described in “How
data is re‐sequenced”.
create_user_id VARCHAR2(30) n/a Standard Oracle table boilerplate.
update_date DATE timestamp Standard Oracle table boilerplate.
update_user_id VARCHAR2(30) n/a Standard Oracle table boilerplate.

Replication GUI - Oracle Retail Xstore Office
Periodic Maintenance of the rpl_replication_data Table

It is anticipated that due to the high volume of constant inserting/deleting in the
rpl_replication_data table, that periodic (daily) maintenance must be performed
on this table.
Vendor-specific SQL scripts have been created to do this work. These scripts serve two
purposes:
- One purpose is purely technical: to keep the table and its indexes performing
well, the indexes may need to be re-created, the table may need to be
"defragmented", etc. The actions required will be dependent on which actual
database (Oracle, SQL Server, etc.) is being used.
- The second purpose is related to business logic: since these scripts need to be
running periodically, it is also appropriate to install scripts that delete
replication records which have been fully, successfully processed, and are
"sufficiently old", which by default is 3 days, but is an easily adjustable
parameter in the script.
Essentially, the deletion script looks like this (SQL Server syntax, and defining
"sufficiently old" as 3 days):
delete from rpl_replication_data where publish_status =
'COMPLETE' and update_date < GETDATE()-3
Monitoring the Replication Processes

Each running instance of Xstore Office has a rudimentary status servlet:
https://{xcenter hostname}:{port}/xcenter/showstatus
The above servlet includes a new note directing users to another URL to see information
specific to replication:
https://{xcenter hostname}:{port}/xcenter/showstatus/replication
This servlet displays some basic information about the replication processes.

Users with proper security privileges can access the Replication Status page from
Support Tools -->Replication Status.
Figure G-1: Replication Status Page
Supported operations include:

Refresh/Search - Search for replication failures based store IDs and/or last update date.
- Update Date is ignored if the input parameters are not valid. For example, a date
in the future is considered to be invalid.
- Store # accepts only a valid store number, if specified.

- If no filters are specified, the system searches all that apply. The maximum
number of rows returned in the data table are 500, and a warning will be
displayed if the result set is more than that. The records in the data table are
sorted by update date (the last modified date) by default, and can be reordered
by clicking on the column headers.
Delete - Delete replication error.
Reprocess - Reprocess the replication error record.
A data table shows the search result. The detail information about each result (error
detail, system runtime stack trace) can be found by clicking on each row on the table. A
popup window opens to show these details. Reprocess information is also shown
(reprocess user id, last reprocess time, total reprocess attempts).
See the Oracle Retail Xstore Office User Guide for more information about this feature.


H
Tips & Troubleshooting
Restoring the Windows Shell

If, during Xenvironment installation, you replaced the Windows shell with
Xenvironment and need to revert back to the Windows shell, you can restore the shell by
editing the Windows registry.
The following registry key and value sets Xenvironment as the shell:
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows
NT\CurrentVersion\WinLogon
"Shell"="c:\windows\system32\wscript.exe //B
c:\environment\start_eng.vbs"
To return the shell program to Windows Explorer (explorer.exe), use REGEDIT to
manually reset the value of the Windows Registry setting back to:
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows
NT\CurrentVersion\WinLogon
"Shell"="explorer.exe"
Tips & Troubleshooting H-1

Opening a Command Prompt in a Location
Opening a Command Prompt in a Location

If you are using Windows 7, Windows 8, Windows 10, or Server 2008 R2, perform the
following steps to quickly open a command prompt in a folder/location:
1. Open the folder.
2. With nothing selected, press [Shift] and right-click the mouse.

3. Click “Open command window here” to open a command prompt in this location.
A command prompt is displayed for the location.
H-2 Implementation and Security Guide

Xstore Point of Service Email

There are some settings in the Xstore Point of Service SystemConfig.xml file that need
to be configured correctly for Xstore Point of Service to properly send emails.
Note: Speak with your product representative for assistance with

changing settings in SystemConfig.xml.
e-Receipts
If e-Receipts are not being sent by Xstore Point of Service, you may need to set the
<UseTLS> option to false in SystemConfig.xml. This option is highlighted in
Example.
Note: This configuration defaults to true. This setting is not an

option in the installer.
Example
<Email dtype="Default">

<DefaultMailHost dtype="String">server.company.abc</
DefaultMailHost>
...
<UseTLS dtype="Boolean">false</UseTLS>
...

<DefaultRecipient dtype="String">storeManager@thisOrg.abc</
DefaultRecipient>
...

<UseTestingMode dtype="Boolean">true</UseTestingMode>
...
</Email>
Implementation and Security Guide H-3

H-4 Implementation and Security Guide

I
Uninstall Procedures
Uninstall procedures for Jetty and Apache Tomcat are included in this appendix.
Uninstalling Jetty
Follow the procedure in this section if you need to uninstall Jetty for any reason.
Important: The uninstaller will permanently remove all traces of

both Jetty and xcenter-config.
1. Stop Jetty:
- Windows: Stop the service through the Services window (accessed through the
control panel).
- Linux: Kill the application.
2. On Windows, remove the service:
a. Navigate to the Jetty installation directory.
b. Run the file UninstallJetty.bat.
3. Remove the Jetty installation folder.
Uninstalling Apache Tomcat

Follow the procedure in this section if you need to uninstall Tomcat for any reason.
Important: The uninstaller will permanently remove all traces of

both Tomcat and xcenter-config.
1. Stop Tomcat:
- Windows: Stop the service through the Services window (accessed through the
control panel).
- Linux: Kill the application.
2. On Windows, remove the service.
a. Navigate to the Tomcat installation directory.
b. Run the command:
tomcat9.exe //DS//<service name>
Uninstall Procedures I-1

Uninstalling Apache Tomcat
where <service name> is the name of the Tomcat service.

3. Remove the Tomcat installation folder.
I-2 Implementation and Security Guide

J
Store Inventory Management Integration
Overview
Xstore Point of Service can use Oracle Store Inventory Management (SIM) to manage
inventory information. Xstore Point of Service uses the following functions in SIM:
• Inventory Inquiry: This feature is provided to enable Xstore Point of Service to
check the item inventory in Home Store, Buddy Store, Specific Store, and Transfer
zone. The Item Inventory feature is available to Xstore Point of Service client only
when the Xstore Point of Service client is in the Online mode.
• Item Basket: This feature is provided for line busting using the Store Inventory
Management handheld. The items in a customer basket are scanned using the Store
Inventory Management handheld and staged in the Store Inventory Management
database. Xstore Point of Service can then look up the basket details and add the line
items to the sell item screen.
• Serial Number Validation and Update: Xstore Point of Service supports serialized
items. The operator is prompted to enter/scan the serial number of the serialized
item on the Xstore Point of Service client. The serial number that is entered is then
validated by interfacing with Store Inventory Management. Once the transaction is
tendered, the serialized items along with the captured serial number are sent to
Store Inventory Management for updating the status of the particular serial number.
• Inventory Reservation: Xstore Point of Service interfaces with Store Inventory
Management to send the order transactions so that the items can be marked as
reserved in Store Inventory Management. Also, once the items are picked up or
delivered to the customer, the status needs to be updated in Store Inventory
Management.
• Real Time Inventory Status Update: This interface sends Xstore Point of Service
transactions to Store Inventory Management to update the inventory status based on
the transactions.
Xstore Point of Service communicates with SIM through web services. See “Integration
using a Web Service”..
Note: Though SIM provides batch file communication, Xstore Point

of Service does not use this interface.
Store Inventory Management Integration J-1

Integration using a Web Service

The following steps outline the Xstore Point of Service-to-Store Inventory Management
integration approach:
1. Expose the inventory features from Store Inventory Management in the form of a
web service.
2. Provide pluggable inventory web service interface to integrate Xstore Point of
Service-to-Store Inventory Management.
3. Xstore Point of Service uses the connector framework to achieve a pluggable and
extendable integration with Store Inventory Management.
The Xstore Point of Service to Store Inventory Management integration system is broken
into two main sub-systems:
• Store Inventory Management Server
• Store Inventory Management DB
Figure J-1: Xstore Point of Service Connector Framework Model
The MessageDispatcher is the core of the communication framework. Its primary

function is to dispatch messages to mapped routers. In addition, MessageDispatcher
performs administrative and control operations on the associated connectors. When
invoked, the MessageDispatcher delegates the message handling to a specific
MessageRouter.
The MessageRouter coordinates the processing of a message using the associated
routing rule and the RouterConnectors.
J-2 Implementation and Security Guide

A RouterConnector provides an association between a message type, connector, and

formatter. This decouples the formatting of the message from the chosen connector.
ConnectorIfc handles the communication between the application and the external
service. It is responsible for locating the service, establishing a connection, and
interacting with the service using appropriate protocols.
FormatterIfc translates the raw data from the message into the format expected by the
external service. It also translates the response from the remote service into the format
expected by the application.
Once a message has been sent with a request type to the MessageDispatcher it gets the
instance of MessageRouter that is configured for that request type from the instantiated
list. The processing is then delegated to the MessageRouter. The MessageRouter routes
the request message to the list of connectors that are configured for that request. There
can be multiple connectors that can be defined to process the same request message.
The connector framework provides all the building blocks to realize any integration
requirement with a combination of connectors, formatters, ChainedConnectors,
RoutingRules and JMX notifications. The XML configuration ties up the various blocks
to implement any integration requirement.
Store Inventory Management Server

Inventory web service component deployed in Store Inventory Management server
provides the entry point into the application for the various functions.
Store Inventory Management DB

Store Inventory Management inventory database.
Item Disposition
The retailer can map the SIM inventory adjustment reason codes with the Xstore Point of
Service reason codes and send it to SIM in the web service call.
SIM uses these reason codes to identify the item disposition against the reason code and
updates the inventory buckets appropriately. SIM processes the web service call and
increments the SOH, performing the inventory adjustment based on the disposition.
The following item dispositions are the valid mapped dispositions:
• Available to Sell (ATS) to TRBL -- This disposition moves the inventory from
Available to Unavailable. For the retailer, this means the stock is taken in and made
unavailable to sell.
• ATS to Distributed (DIST) -- This disposition moves the inventory from Available to
Out of inventory. End result the SOH is incremented and then again decremented.
For the store person, this means the return is accepted and the item which was
returned is not in a condition to keep it back on the rack and it is destroyed.
Error Handling
Error handling is limited to logging errors during the inventory lookup. The exceptions
such as IOException and invalidItem that occur during WSService communication are
re-thrown as WSException, as well as logged for error tracking and resolution.
Implementation and Security Guide J-3

Logging
Xstore Point of Service to Store Inventory Management uses Log4J for logging. The
following logging levels can be used:
• Info: For logging information messages.
• Debug: For logging all the debug messages.
• Error: For logging application errors.
The logging level can be configured with log4J.xml. See Configuring Logging in Xstore
Point of Service for more information.
J-4 Implementation and Security Guide

K
Installation Order
This section provides a guideline for the order in which the Oracle Retail applications
should be installed. If a retailer has chosen to use only some of the applications, the
order is still valid, less the applications not being installed.
Note: The installation order is not meant to imply integration

between products.
Enterprise Installation Order

1. Oracle Retail Merchandising System (RMS), Oracle Retail Trade Management (RTM)
2. Oracle Retail Sales Audit (ReSA)
3. Oracle Retail Extract, Transform, Load (RETL)
4. Oracle Retail Warehouse Management System (RWMS)
5. Oracle Retail Invoice Matching (ReIM)
6. Oracle Retail Price Management (RPM)
7. Oracle Retail Allocation
8. Oracle Retail Mobile Merchandising (ORMM)
9. Oracle Retail Customer Engagement (ORCE)
10. Oracle Retail Xstore Office
11. Oracle Retail Xstore Point-of-Service, including Xstore Point of Service Lane
Checkout User Interface, and including Xstore Point of Service Mobile
12. Oracle Retail Xstore Environment
13. Oracle Retail EFTLink
14. Oracle Retail Store Inventory Management (SIM), including Mobile SIM
15. Oracle Retail Predictive Application Server (RPAS)
16. Oracle Retail Predictive Application Server Batch Script Architecture (RPAS BSA)
17. Oracle Retail Demand Forecasting (RDF)
18. Oracle Retail Category Management Planning and Optimization/Macro Space
Optimization (CMPO/MSO)
19. Oracle Retail Replenishment Optimization (RO)
Installation Order K-1

Enterprise Installation Order
20. Oracle Retail Regular Price Optimization (RPO)

21. Oracle Retail Merchandise Financial Planning (MFP)
22. Oracle Retail Size Profile Optimization (SPO)
23. Oracle Retail Assortment Planning (AP)
24. Oracle Retail Item Planning (IP)
25. Oracle Retail Item Planning Configured for COE (IP COE)
26. Oracle Retail Advanced Inventory Planning (AIP)
27. Oracle Retail Integration Bus (RIB)
28. Oracle Retail Services Backbone (RSB)
29. Oracle Retail Financial Integration (ORFI)
30. Oracle Retail Bulk Data Integration (BDI)
31. Oracle Retail Integration Console (RIC)
32. Oracle Commerce Retail Extension Module (ORXM)
33. Oracle Retail Data Extractor for Merchandising
34. Oracle Retail Clearance Optimization Engine (COE)
35. Oracle Retail Analytic Parameter Calculator for Regular Price Optimization (APC-
RPO)
36. Oracle Retail Insights, including Retail Merchandising Insights (previously Retail
Merchandising Analytics) and Retail Customer Insights (previously Retail Customer
Analytics)
37. Oracle Retail Order Broker
K-2 Implementation and Security Guide

L
Revision History
Revision History 17.0.2, Revision 07
Oracle Retail Xstore Suite Version 17.0.2, Revision 07 Date 10/2019
Description of Change
All chapters • PI and CI cleanup
Chapter 4 - • Added Symbol CS4070 scanner to Xstore Point of Service

Prerequisites for Mobile Supported Devices
Installing Xstore Point
of Service
Appendix B - Public • Added information about Xstore Mobile certificates if

Key Certificates SAN=IP.
Chapter 5 - Install • Added section Desktop: Outbound Call to the

Xstore Point of Service Xcommerce Application
Revision History L-1

Chapter 4 - • Changed section Configure Workstation 610 (Workstation

Prerequisites for 610 Only) to Install Xstore Mobile on Windows 10
of Service
Added JAVA_OPTION • Menu Configuration - added JAVA_OPTIONS defined in

startWebLogic.cmd file (startWebLogic.sh on Linux):
extension=true
Added Fiscal Module • Added the Fiscal Module Unit (FMU) to table 4-3
Unit (FMU)
Chapter 2 - • Changed Oracle DB 12.2.0.1 to Oracle Database 12c.

Prerequisites for
Installing Xstore Office
Chapter 4 - • Changed Oracle DB 12.2.0.1 to Oracle Database 12c.

Prerequisites for
of Service
Chapter 9 - • Corrected the Doc ID for the Xstore Suite Configuration Accelerator

Internationalization Guide.
L-2 Implementation and Security Guide

Changed release nr. • -
Changed Xstore Office Changed Application Server to the following versions:

Supported Software
• Oracle WebLogic Server 12.2.1.3
• Tomcat 9.0.11
• Jetty 9.4.11
Changed PCI-DSS Changed PCI-DSS version from 3.2 to 3.2.1.

version

Changed certificate • Changed the following paths:

paths for Xenvironment
• md C:\cert\environment
• cd C:\cert\environment
• copy .keystore C:\environment\res\ssl
• copy .truststore C:\environment\res\ssl

Add Biometric devices • Added Eikon Touch 510 (SteelCoat)

supported by Xstore
Additional step added • Added an additional step to import HTTP server certificate into
when the HTTP server Xenvironment (\environment\res\ssl\.truststore or /opt/
certificate is generated environment/res/ssl/.truststore).
Removed all references • Removed all references to trusted.ca-bundle in Appendix B Public

to trusted.ca-bundle Key Certificates

Implementation and Security Guide L-3

Install WebLogic • Added exmple for theformat of the ssl block in the config.xml file
Enable Only Strong
Cipher Suites
openssl.cnf file • Added copy_extensions = copy so that certificate extensions are

honored and used by OpenSSL during the signing process
Appendix B Public Key • Added-ext SAN=DNS:<hostname> to keytool commands calling -

Certificates genkey or -certreq

Prerequisites for • Added Linea Pro 5 to supported peripherals for 5th and 6th
Installing Xstore Point generation iPods.
of Service
• Changed name of Jetty password obfuscation utility to jetty-util-
9.4.8.vXXXXXXXX.jar.
Public Key Certificates • Changed Jetty version to 9.x.x.
Revision History 17.0, Revision 06

Oracle Retail Xstore Suite Version 17.0, Revision 06 Date 05/2018
Enable Only Strong
Cipher Suites



Entire document • Changed SHA-1 to SHA-256.


Prerequisites for • Added Windows 10 IOT Enterprise LTSB 2016 (1607) to list of
Installing Xstore Office supported operating systems.
• Added “Backup and Recovery” section.
Prerequisites for • Added Windows 10 IOT Enterprise LTSB 2016 (1607) to list of
Installing Xstore Point supported operating systems.
of Service
• Added “Backup and Recovery” and “Geolocation and Device
Identifiers” sections.
Install Xstore Point of • Added step for adding the encrypted cash drawer credential to
Service the system.properties file to the “Enable Networked Cash
Drawers” section.

Prerequisites for • In “Xstore Point of Service Supported Oracle Products” table,

Installing Xstore Point changed supported version of Oracle Retail Order Broker Cloud
of Service Service to 16.0.
• Added Workstation 310 as a supported Thin Client system.
• Added section “Workstation 310 and 610 Supported Peripherals”.

Prerequisites for • Returned SQL Server 2012 SP1 and SQL Server 2014 SP1 to the list
Installing Xstore Office of supported databases.
Prerequisites for • Returned SQL Server 2012 SP1 and SQL Server 2014 SP1 to the list
Installing Xstore Point of supported databases.
of Service
Install Xstore Point of • Added “Configure Xenvironment for Thin Client” section.
Service


Prerequisites for • Moved list of system requirements to start of chapter.

• Added Oracle 12.2.0.1 and SQL Server 2016 to supported
databases.
• Removed all references to jvm.preferIPV4Stack.
• Removed all references to dtv.xadmin.server-number.
• Replaced replication.publisher.enabled with
cluster.processes.enabled.
Install Xstore Office • Removed all references to jvm.preferIPV4Stack.

• Updated sample xcenter.properties file.
Prerequisites for • Moved list of system requirements to start of chapter.

of Service • Removed Suse Linux Enterprise Desktop 11 SP3 as a supported
operating system.
• Added Oracle Enterprise Linux 6 and 7 as supported operating
systems.
• Added Oracle 12.2.0.1 and SQL Server 2016 to supported
databases.
• Added Epson TM88-IV to supported peripherals.
• Added iPad Mini 2, iPad Mini 3, Oracle DT 317BT 7-inch Tablet,
Workstation 610, and Zebra TC51 to supported Xstore POS
Mobile devices.
• Updated list of supported Xstore POS Mobile peripherals and
operating systems.
• Added Verifone e355 as a supported Xstore POS Mobile
peripheral.
• Added Android 6.0.1 (Marshmallow) as a supported operating
system for the Zebra TC70 handheld and Zebra ET55 tablet.
• Removed path to JCE zip file from JRE package creation.
• Changed name of Jetty password obfuscation utility to jetty-util-
9.4.2.v20170220.jar.

Install Xstore Point of • Added step for selecting the installation type.
Service
• Removed advanced installation option selection.
• Removed Disable Mobile startup? and Disable Tablet startup?
settings from installation procedure.
• Added RSA Private Key Path and RSA Private Key Password
settings for Xstore POS Mobile.
• Added Customer Engagement Auth. Token Name setting for
ORCE integration.
• Added Schema Creation Details step in installation
procedure.
• Added Xstore POS Lane Checkout Interface installation
procedure.
• Removed “Xenvironment System Password” section.
• Replaced specific version number for Jetty obfuscation password
utility with a <version> placeholder.
About Implementing • Removed the note in “Operating Systems: General

the Xstore Suite Considerations” about administrator privileges required for SQL
Server.
• Removed Dataserver IPC from list of firewall port exceptions.
• Removed Xstore Point of Service Dataserver IPC from
“Communication Ports” table.
Upgrading Xstore Suite • Removed information about

Components c:\BACKUPxstore\base-xstore.properties file.
Lane Checkout User • Removed Xstore POS Lane Checkout Interface installation
Interface procedure.
Replication • Removed all references to jvm.preferIPV4Stack.

Lane Checkout User • Moved this chapter to the Oracle Retail Xstore Point of Service

Interface Frameworks & Technologies Guide.
PCI Best Practices: • Added “Database Communication Encryption” section.

Implementation &
Configuration • Added “Data Privacy” section.


Enable Only Strong
Cipher Suites



Enable Only Strong
Cipher Suites



Enable Only Strong
Cipher Suites




Prerequisites for • Added DataLogic Magellan 1100i, Ingenico iSC250, and Toshiba
Installing Xstore Point TCxWave 6140-100 to table “Supported Hardware Peripherals for
of Service Xstore Point of Service “.

Prerequisites for • Removed DataLogic Magellan 1100i, Ingenico iSC250, and

Installing Xstore Point Toshiba TCxWave 6140-100 from table “Supported Hardware
of Service Peripherals for Xstore Point of Service “.
Entire document • Added Windows 10

Document • General proofreading and corrections.

Enable Only Strong
Cipher Suites




Install Xstore Office • In “Edit Batch File or Shell Script”, updated setting within
USER_MEM_ARGS to -Xms4096m.
• In “Edit Batch File or Shell Script”, now include Linux and
Windows versions of the file.
Prerequisites for • Added section “Synchronized System Clocks”.

of Service
Public Key Certificates • Corrected Xenvironment certificate creation.

Document • General proofreading and corrections.
Revision History 16.0.0.1, Revision 11

Oracle Retail Xstore Suite Version 16.0.0.1, Revision 11 Date 05/2018
Enable Only Strong
Cipher Suites



Install Xstore Point of • Added instructions for running Xenvironment as a service on

Service init.d versions of Linux.
• Added instructions for disabling Xenvironment from running as a
Service.

About Implementing • Removed mention of Express version of SQL Server.

Xstore

Install Xstore Point of • Added specific usernames for data sources.

Service
• Added “Xenvironment System Password” section.
• Changed field delimiters for the Xenvironment system password
from square brackets to parentheses.
Public Key Certificates • Corrected default_md setting in openssl.conf configuration

file in the “Create Certificate Authority” section.
• Added keyUsage setting to openssl.conf configuration file in the
“Create Certificate Authority” section.

Prerequisites for • Corrected list of supported payment processes in the section

Installing Xstore Point “Check Supported Payment Processors”.
of Service
Revision History 16.0.0.1

Oracle Retail Xstore Suite Version 16.0.0.1 Date 03/2017
Entire document • Changed “Xstore for Grocery” to “Xstore Point of Service Lane
Checkout User Interface User Guide”.


Enable Only Strong
Cipher Suites



Prerequisites for • Removed references to version 12.1.3 of Oracle WebLogic Server.

Prerequisites for • Removed references to version 12.1.3 of Oracle WebLogic Server.

of Service

Install Xstore Point of • Removed RXM Username and RXM Password from RXM step.
Service
• Added RXM Container Username, RXM Container Password,
RXM Application Username, RXM Application Password, and
RXM Site ID to configurations in the RXM step.

Prerequisites for • In section “Supported Oracle Retail Products”, updated the

Installing Xstore Point compatible version of Oracle Retail Customer Engagement Cloud
of Service Service to 16.0.
• In section “Supported Oracle Retail Products”, updated the
compatible version of Oracle Retail Order Broker Cloud Service to
16.0.


Getting Started • In Xstore Point of Service section, described why it is not eligible
for PA-DSS validation.
Prerequisites for • Replaced Micros WS5 MSR with Oracle Micros WS620/WS650
Installing Xstore Point MSR in list MSRs in Supported Peripherals.
of Service
• Removed IBM ANPOS MSR from list of MSRs in Support
Peripherals.
• Replaced Epson TM-T88IV with Epson TM-T88V to list of receipt
printers in Supported Peripherals.
• Added Epson TM-H6000IV to list of receipt printers in Supported
Peripherals.
• Added Ingenico iSC250 to list of supported signature capture/PIN
pad/MSR devices in Supported Peripherals.
• Replaced Micros 2010 Line Display with Oracle Micros
Workstation 620/650 Line Display in list of supported pole
displays in Supported Peripherals.
PCI Best Practices: • Changed PA-DSS version to 3.2 from 3.0.

Implementation &
Configuration • Deleted obsolete information about storing personal account
number (PAN) information.
• Removed obsolete references to iterations of PCI and PA-DSS
from PCI Compliant Remote Access section.
Revision History 16.0

Oracle Retail Xstore Suite Version 16.0, Date 12/2016
Prerequisites for • Changed JRE to 8.

• Changed JDK to 8.
• Changed JCE Policy to 8.
• Added information about configuring PATH variable.
Install Xstore Office • Reworked the database installation procedure.

• Removed database naming convention.
• Removed screens displaying warnings that Jetty and Tomcat are
being installed on 32-bit systems.
• Removed references to .driver configurations.
• Added .connectionfactory configurations.
• Updated database connection URLs.

Oracle Retail Xstore Suite Version 16.0, Date 12/2016
Prerequisites for • Removed Red Hat Linux 6 and 7 from list of supported operating
Installing Xstore Point systems.
of Service
• Removed Linea Pro 5 peripheral from Supported Hardware for
Xstore POS Mobile.
• Updated mobile operating systems for Xstore POS Mobile.
• Removed support for Workstation 610.
• Changed JRE to 8.
• Changed JDK to 8.
• Changed JCE Policy to 8.
• Removed step setting JAVA_HOME variable.
• Added Jetty Obfuscation Utility information.
• Updated operating systems for Xstore POS Mobile.
• Removed Epson TM-H6000 II, Epson TM-H6000 III, Epson TM-
T88III, Epson TM-T88V, IBM 4610 Suremark from list of
supported receipt printers.
• Removed Ingenico iSC250, VeriFone MX850, VeriFone MX860,
VeriFone MX870 (no keypad) from list of supported Signature
Capture/PIN Pad/MSR devices
Install Xstore Point of • Added additional information for Xstore POS Mobile installation.
Service
• Removed steps for PayPal integration.
• Updated fields for 16.0.
• Added RXM integration, including “Configure Xstore Point of
Service for Retail Extension Module” section.
• Added AVS integration, including “Configure Xstore Point of
Service for Address Verification Service” section.
• Added UFTP installation procedure.
• Removed steps and information for configuring Xstore Payment.
PCI Best Practices: • In section “Requirement 3: Protect stored cardholder data”,

Implementation & replaced paragraph describing methods for protecting cardholder
Configuration data with note explaining that Xstore POS is not eligible for PA-
DSS validation because it does not store cardholder data.
• In section “Requirement 3: Protect stored cardholder data”,
removed paragraph explaining that Xstore POS uses credit card
masking and AES-256 encryption to protect cardholder data.
• In section “Requirement 3: Protect stored cardholder data”,
removed list of tables where cardholder data is stored.
Xstore Office • Updated XML samples for xcenter-spring-beans.xml

Broadcaster System configuration file.
Installation Order • Updated installation order of software.
Entire document • General proofreading and corrections


Enable Only Strong
Cipher Suites



Enable Only Strong
Cipher Suites



Enable Only Strong
Cipher Suites




Entire document • General corrections and proofreading.



Install Xstore Point of • Added “Run Xenvironment as a Service” section.

Service
Internationalization • Removed “Country Packs” section


Prerequisites for • Removed NCR cash drawer from “Supported Peripherals”

Installing Xstore Point section.
of Service
• Removed HP RP5000, HP RP5700, IBM Surepos 700, Micros 2010,
and Micros 2015 PCs from “Supported Peripherals” section.
• Add Oracle Micros Workstation 620 and Oracle Micros
Workstation 650 PCs to “Supported Peripherals” section.
• In “Hardware Requirements” section, updated minimum
required processor for a lead register to Intel Core i5-5350U dual-
core processer >= 1.8GHz or equivalent.
• In “Hardware Requirements” section, updated minimum
required processor for a non-lead register to Intel Celeron 3765U
dual-core processer >= 1.9GHz or equivalent.

Install Xstore Office • Updated “xcenter.properties Sample” with new sample file
• Added “Configure WebLogic Server” section
Prerequisites for • Added “Workstation 610, 620 and 650 Systems with Oracle
Installing Xstore Point Databases” section
of Service
Internationalization • Added “Country Packs” section

• Added “Multi-Keystroke Character Entry” section

Updates for PA-DSS.

Oracle Retail Xstore Suite Version 15.0 Date 08/2015
Updated entire document and all procedures to reflect Oracle formatting and standards.
Installing Xstore Point • Removed Apache installation instructions.

of Service

Revision History 7.1, Doc Version 02
Oracle Retail Xstore Suite Version 15.0 Date 08/2015
PCI Best Practices • Removed version numbers list from first page.
• Added Overview of the Cardholder Data Environment diagram.
• Added Cardholder Data Flow Diagram diagram.
Added Chapter 9, “Xstore for Grocery”.
Removed appendix “Xenvironment Encryption Utility”.
Added appendix “Store Inventory Management Integration”.

Oracle Retail Xstore Point of Service Version 7.1, Doc Version 02 Date 07/2015
PA-DSS • Added new information required for PA-DSS.

Oracle Retail Xstore Point of Service Version 7.1 Date 03/2015
Asymmetric Encryption • Changed from 1024 to 2048 in Appendix C and D.

Key Size
Broadcaster • Added threadcount parameter.

• Added authentication requirements to Table G-3.
Oracle Script • Added the cwiusers role.
PCI Best Practices • Updated Table E1.
Resolve Pre-Flight • If Windows: set PATH=%PATH%;c:\jre\bin

Errors
• If Linux: export PATH=$PATH:/opt/jre/bin
Installation • New installation field for Relate Authorization.

• Added new property in the ant.install.properties - relate.Auth.

Oracle Retail Xstore Point of Service Version 7.0, Doc Version 02 Date 11/2014
License Key Appendix • Removed Appendix: Xstore License Key.


Xstore Version 7.0, Date 05/2014
Installing Xstore • Removed “Configuring Multiple Apache Servers [OPTIONAL]”

section. Now that the Apache installer supports UNC paths at
install time, there’s no need for the procedure.
• Added Oracle instructions for OPEN_CURSORS setup.
• Added Xstore Mobile settings information.
• Removed Deposit Bank and Bank Acct # from Location Settings
configuration.
• Added Locate Services install information.
Updating Xstore • Added pending deployments processing information.
Replication • Added information about placing a jgroups configuration file on

the Xcenter system to more precisely control the behavior of
JGroups if needed.
Oracle Script • Added Xadmin script information.
Implementing Xstore • Updated the recommended hardware requirements.

Xstore Version 6.5, Doc Version 05 Date 04/2014
The following changes were made to address the vulnerability (Heartbleed) in OpenSSL for
Apache:
Public Key Certificates • When installing on Linux, OpenSSL 1.0.1g (or a newer 1.0.1
version, if available) should be installed replacing OpenSSL
v1.0.0* Light.
Installing Xstore • 2013 C++ Runtimes have replaced Visual C++ 2010 SP1 Runtimes
(x86).

Public Key Certificates • Added new steps for adding Xcenter's cert in Xenvironment’s
trusted ca bundle. Xenvironment needs Xcenter's cert in its
trusted ca bundle because it directly requests deployments from
Xcenter. Certs are now required for both Xcenter and the Apache
server.


Installing Xstore • Removed references to configuring LDAP in xcenter.properties.

Functionality was not implemented, LDAP is only configured in
Xadmin Settings.

Installing Xstore • Removed “Configuring Multiple Apache Servers [OPTIONAL]”

section. Now that the Apache installer supports UNC paths at
install time, there’s no need for that procedure.

Xstore Version 6.5 Date 10/2013
General • Changed Xcenter Admin references to Xadmin

• Added Broadcaster Appendix
• Added Replication Appendix
Installing Xstore • Updated Xstore Install procedures

Components
• Added & updated broadcaster configuration information
• Removed all broadcaster configuration information from
xcenter.properties
• Added Xenvironment Silent Install section
• Xenvironment Install - added “Use Multicast FTP For Database
Distribution?” register option
• Added JDK prerequisite for Jetty/Tomcat install
• DataLoader Install - removed configuration options for an
application server datasource, no longer used
• Updated xcenter.properties information


CA Signed Certificates • openssl.cnf file, changed default_md = md5 to default_md = sha1

Upgrading Xstore • Xcenter/Xcenter Admin Upgrade - Added Tomcat information: If

Components using Tomcat, you must rename the xcenter and xcenter-admin
war files to xcenter.war and xcenter-admin.war before use.

Installing and • Added new database information (Xcenter Replication DB)

Upgrading Xstore
Components • Note: Xcenter has been repackaged as WAR instead of EAR.
• Removed JBoss install/upgrade instructions, replaced with Jetty
install/upgrade instructions and Apache Tomcat install/upgrade
instructions
• Removed the following from xcenter.properties:
#broadcaster.poslog.1000.POST_TRANSACTION_RELATE
.ORDERING_TIME_BUFFER_MILLIS=10000
• Removed references to Xsecure - GenKeys is no longer part of
InstallX.
• Added JRE and jrepackager component information.
• Added new information for IPv6 to xcenter.properties
section for Jetty install.
• Added new xcenter.properties information
• Added Oracle script information
• Added a new configuration path that must be included in
xcenter.properties when installing xcenter
About Implementation • Added Recommended Hardware Requirements section

Chapter
License Key Appendix • Added new License Key information
Public Key Certificates • Updated all instructions

• Added OpenSSL and Keytool instructions
PCI Best Practices: • Added Encrypt the pagefile.sys file instructions

Implementation &
Configuration

Xstore Version 6.0 Date 03/13 (continued)
Appendix: Oracle • New appendix for Oracle script

Script

Apache Install • Added configuration information for using multiple Apache

servers.

PCI Best Practices • Added information and procedures for deleting expired
certificates and keys once the keys and certificates reach the end
of their usable life.

Apache Install • Moved create upload folder step from prerequisite to post install.
JBoss Install • Added additional information about the xcenter.properties

file section. (The numbers are not ordered steps, they simply
correspond to a line in the xcenter.properties file).
• Added another reminder to make sure user names and passwords
are encrypted.
• Added format examples for JBoss and Xcenter Admin URLs.


Base PCI • Removed Base PCI Recommendations Appendix from book.

• Added new Appendix, PCI Best Practices: Implementation &
Configuration to book and updated all references accordingly.
The new appendix was created by combining PCI Configuration

Best Practices and PCI Implementation Best Practices into a single
Appendix within the Xstore Implementation Guide. Updated for PA
DSS Version 2.0 and Xstore version 5.5.
Xenvironment • Added new appendix, Xenvironment Password Encryption Utility.

Encryption Utility
• Added references to Xenvironment Password Encryption Utility
in Xenvironment Install procedure.

Communication Ports • Xstore JMX Console, port 2020 - removed recommendation for not
opening a firewall.
• Xpay Ports - added store location and notes.
JBoss Install • Added/updated xcenter.properties information.

• Added steps to explain how to open an archive and edit
information.
• Added steps to confirm Jboss and Xcenter Admin are running.
Apache Install • Added prerequisite for creating an upload folder in the htdocs
folder in the Apache install.
Uninstalling Appendix • Removed uninstall procedures from the main flow and added
them to a new appendix.
General • Formatting and flow changes.

• Added Installation Checklist.
• Updated “JRE 1.6.0 update 30” to “JRE 1.6.0 Use latest version.”
(Update 30 is no longer available).
DataLoader Install • Added “To Load Xcenter Admin User Records via DataLoader”
procedure.
Xenvironment • Removed certificate information from the install section and

moved it to the Public Key Certificates Appendix.
PCI Recommendations • Added references to the Payment Application Best Practices

Implementation Guide.


Xstore Version 5.5
Xenvironment • Added troubleshooting tip for Xstore version 4.8 and below.
• Updated install procedure.
Apache • Added section for Apache install.

• Added certificate information for Apache; CA-signed and Self-
signed.
Xpay • Removed procedure for configuring the Xpay Transaction Viewer

to Run On SSL
• Updated all Xpay sections
Xcenter DB build script • Updated instructions for script changes
JBoss Install • Removed the step for enabling authentication in the Xcenter EAR
file (no longer needed)
General Changes • Updated http://www.slproweb.com/download/Win32OpenSSL_Light‐

1_0_0g.exe to http://www.slproweb.com/products/Win32OpenSSL.html
and Added note to use latest version.
• Added communication port information.
Processors Added the following processors to base Xstore:

• Xpay+Paymentech - Xpay URLs, Timeout, merchantNumber
(credit, debit, and gift card), TerminalID (credit, debit, and gift
card), ClientID (credit, debit, and gift card)
• Xpay+MerchantWarehouse - Xpay URLs, Timeout,
merchantNumber (credit and debit), organizationName (credit
and debit), SiteID (credit and debit)
• Xpay+MerchantLink - Xpay URLs, Timeout, TerminalID (credit
and debit), organizationName (credit and debit), SiteID (credit
and debit)
• Tender Retail - Server URL
Supported Hardware • Removed from book (available under separate cover)

• Added Xenvironment Upgrade instructions


New document for Xstore version 5.0.

Consolidated the following procedures:
• Xenvironment installation instructions moved here from the
Xenvironment User Guide.
• Xcenter Admin installation instructions moved here from the
Xcenter Admin Installation Instructions document.
• Public Key Certificates Guide incorporated into this book.
• Cipher Key Generation Utility Guide incorporated into this book.

Xstore Suite-1702 - Implementation Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Xstore Suite-1702 - Implementation Guide

Uploaded by

Copyright:

Available Formats

Oracle® Retail Xstore Suite

Implementation and Security Guide

The passwords contained in this document are for example

2 Prerequisites for Installing Xstore Office ......................................2-1

3 Install Xstore Office .........................................................................3-1

4 Prerequisites for Installing Xstore Point of Service .....................4-1

5 Install Xstore Point of Service ........................................................5-1

6 About Implementing the Xstore Suite............................................6-1

7 Xstore Suite Data Architecture.......................................................7-1

8 Upgrading Xstore Suite Components............................................8-1

A String Encrypter Utility................................................................... A-1

B Public Key Certificates................................................................... B-1

C About Xstore Suite GenKeys......................................................... C-1

F Xstore Office Broadcaster System.................................................F-1

H Tips & Troubleshooting ................................................................. H-1

J Store Inventory Management Integration......................................J-1

K Installation Order ............................................................................ K-1

L Revision History ..............................................................................L-1

Implementation and Security Guide i-xviii

Send your comments to us using the electronic mail address: retail-doc_us@oracle.com

Access to Oracle Support

Review Patch Documentation

Improved Process for Oracle Retail Documentation

Oracle Retail Documentation on the Oracle Technology

Important: This document is intended only as a guide for a typical

Who Should Use This Guide

Getting Started 1-1

Xstore Point of Service Suite Components and Modules

Component Store Corporate Additional Information

Xstore Point of “Xstore Point of Service”

Xstore Point of “Xstore Point of Service Mobile”

Oracle Retail “Oracle Retail Xstore Settlement”

Oracle Retail Speak with your Oracle product representative for

Web Server Required for deployments from Oracle Retail

1-2 Implementation and Security Guide

Xstore Point of Service

Implementation and Security Guide 1-3

Xstore Point of Service Mobile

1-4 Implementation and Security Guide

Oracle Retail Xstore Settlement

Real-Time Product Integration with Xstore Point of Service

Note: Contact your Oracle representative for more information about

Implementation and Security Guide 1-5

1-6 Implementation and Security Guide

Table 2-1: Xstore Office Supported Software

Operating System Oracle Enterprise Linux 6

Oracle Enterprise Linux 7

Microsoft Windows Server 2012 R2

Microsoft Windows Server 2016

Database Oracle Database 12c

SQL Server 2012 SP1

SQL Server 2014 SP1

SQL Server 2016

Web Server Apache HTTPD

Microsoft Internet Information Services (IIS)

Application Server Oracle WebLogic Server 12.2.1.3

Prerequisites for Installing Xstore Office 2-1

Supported Web Browsers

Backup and Recovery

Install Web Server

2-2 Implementation and Security Guide

Xstore Office Installation .zip File

Installation File Directories