Xstorexenv 180 Ug

Oracle® Retail Xenvironment
User Guide
Release 18.0
F10695-01
December 2018
Oracle® Retail Xenvironment User Guide, Release 18.0
F10695-01
Copyright © 2018, Oracle and/or its affiliates. All rights reserved.

Primary Author: Gerlinde Rust
Contributors:
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 on 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.
Contents
Send Us Your Comments ................................................................................................ ix
Preface .............................................................................................................................. xi
Audience ................................................................................................................................ xi
Documentation Accessibility ............................................................................................... xi
Access to Oracle Support ...................................................................................... xi
Related Documents ............................................................................................................... xi
Customer Support ................................................................................................................. xi
Review Patch Documentation ............................................................................................ xii
Improved Process for Oracle Retail Documentation Corrections ................................. xii
Oracle Retail Documentation on the Oracle Technology Network............................... xii
Conventions ......................................................................................................................... xiii
1 Introduction .................................................................................................................. 1
Overview .................................................................................................................................. 1
How this User Guide Is Organized ............................................................................... 1
Who Should Use this Guide ........................................................................................... 2
Security ..................................................................................................................................... 2
TLS-Encrypted Communication ........................................................................................... 2
User Interface........................................................................................................................... 3
Oracle Retail Xenvironment Installation and Configuration ............................................ 3
Default Installation Path ................................................................................................. 4
Daily Maintenance Procedures ............................................................................................. 4
Software Updates ............................................................................................................. 4
Lead Register Responsibilities ....................................................................................... 5
Responsibilities of Both Lead and Non-Lead Registers ............................................. 5
Commonly Used Chains and Atoms.................................................................................... 5
2 Atoms and Chains ....................................................................................................... 7
Overview .................................................................................................................................. 7
About This Chapter ................................................................................................................ 7
Naming Rules .......................................................................................................................... 7
Atoms ....................................................................................................................................... 7
Example ............................................................................................................................. 8
Atom Aliases .................................................................................................................... 8
Permit or Prevent Atoms From Starting At Certain Times ........................................ 8
Permit Times..................................................................................................................... 9
Disallow Times ................................................................................................................. 9
Example #1 ...................................................................................................................... 10
Example #2 ...................................................................................................................... 10
Example #3 ...................................................................................................................... 10
Example #4 ...................................................................................................................... 10
v
Creating Atoms ..................................................................................................................... 10
LaunchMaster Configurations ..................................................................................... 14
Chains ..................................................................................................................................... 15
Example ........................................................................................................................... 15
Inserting an Atom or Chain Into a Chain ................................................................... 15
Example ........................................................................................................................... 16
Creating Chains.............................................................................................................. 16
Denymarkers ......................................................................................................................... 17
Allowmarkers ........................................................................................................................ 17
3 Configuring the Oracle Retail Xenvironment Engine ............................................. 19
Overview ................................................................................................................................ 19
About this Chapter ........................................................................................................ 19
Base Oracle Retail Xenvironment Directory Structure and Contents ............................ 19
The Main Directory: <root_directory>........................................................................ 19
Subdirectory: <root_directory>\bin ........................................................................... 19
Subdirectory: <root_directory>\cust_config\version1............................................ 20
Subdirectory: <root_directory>\res\data .................................................................. 20
Subdirectory: <root_directory>\download ............................................................... 20
Subdirectory: <root_directory>\ext ............................................................................ 20
Subdirectory: <root_directory>\log ........................................................................... 20
Subdirectory: <root_directory>\marker .................................................................... 20
Subdirectory: <root_directory>\poll .......................................................................... 20
Subdirectory: <root_directory>\res\ssl ..................................................................... 21
Subdirectory: <root_directory>\tmp .......................................................................... 21
Subdirectory: <root_directory>\wwwroot ................................................................ 21
Subdirectory: <root_directory>\ wwwroot \support .......................................... 21
Configuring the Oracle Retail Xenvironment Engine ...................................................... 21
environment.properties ................................................................................................ 21
local.properties ............................................................................................................... 22
Register-Specific Configurations ................................................................................. 23
System Configurations .................................................................................................. 23
actions.properties ........................................................................................................... 25
alerts.properties.............................................................................................................. 25
update.properties ........................................................................................................... 25
version.properties .......................................................................................................... 27
Running Xenvironment as a Service .................................................................................. 27
Windows ......................................................................................................................... 27
Managing the Windows Service .......................................................................... 27
Linux ................................................................................................................................ 28
4 Configuring Oracle Retail Xenvironment GUI ......................................................... 29
Overview ................................................................................................................................ 29
vi
Oracle Retail Xenvironment UI Directory Structure and Contents ............................... 29
Configuring the Oracle Retail Xenvironment UI .............................................................. 29
XenvContextConfig.xml ............................................................................................... 29
environment.properties ................................................................................................ 29
XenvAlertsConfig.xml................................................................................................... 30
Example................................................................................................................ 31
XenvMenuConfig.xml ................................................................................................... 31
Context Configuration .................................................................................................. 31
Pop-up Menu Configuration ........................................................................................ 32
Menu Key Configuration .............................................................................................. 32
Example................................................................................................................ 35
XenvPromptConfig.xml ................................................................................................ 35
Example................................................................................................................ 36
xenv-ui-dialog-config.properties ................................................................................. 37
Window Size and Location ........................................................................................... 37
XenvFontConfig.xml ..................................................................................................... 38
Example................................................................................................................ 38
xenv-ui-probers_{OS}.properties ................................................................................. 39
5 Oracle Retail Xenvironment Processing ................................................................. 41
Overview ................................................................................................................................ 41
Log Files ................................................................................................................................. 41
xenvironment.log ........................................................................................................... 41
Trickle Polling........................................................................................................................ 42
Uploads ........................................................................................................................... 43
Downloads ...................................................................................................................... 43
Deployment ........................................................................................................................... 44
Background Update .............................................................................................................. 45
The Daily Maintenance Process .......................................................................................... 45
Packaging of Upload Files (Creating pospoll.zip) ..................................................... 45
File Archive Updates ..................................................................................................... 46
Archive Structure ........................................................................................................... 46
update.properties ........................................................................................................... 47
Example................................................................................................................ 47
scripts............................................................................................................................... 47
Application Update Processing Example ................................................................... 47
Manual Closing Options ...................................................................................................... 48
Processing of Application Updates ............................................................................. 48
Processing of Cipher Files............................................................................................. 49
Processing of debit.txt File ............................................................................................ 49
6 Using Oracle Retail Xenvironment ........................................................................... 51
Overview ................................................................................................................................ 51
vii
Starting Oracle Retail Xenvironment ................................................................................. 51
Graphical User Interface (GUI) ........................................................................................... 52
On-Screen Keyboard ..................................................................................................... 52
Features ........................................................................................................................... 52
In-Window Keyboard ................................................................................................... 53
Message Screen .............................................................................................................. 54
View Message Details.................................................................................................... 54
Clear Message................................................................................................................. 54
POS Status .............................................................................................................................. 55
Register Status ................................................................................................................ 55
Process Steps................................................................................................................... 56
Alert Detail...................................................................................................................... 56
Apps................................................................................................................................. 56
About ............................................................................................................................... 57
Systems Support/Attention ................................................................................................ 57
Menu Buttons ........................................................................................................................ 58
Status Bar................................................................................................................................ 59
Support Menu........................................................................................................................ 60
System Menu ......................................................................................................................... 61
Capture Logs ......................................................................................................................... 62
Hotkeys .................................................................................................................................. 62
Password Protected Functions ..................................................................................... 64
Plugins .................................................................................................................................... 65
Run a Chain or Atom .................................................................................................... 65
Tech Support Menu ....................................................................................................... 65
Task List .......................................................................................................................... 66
View Marker Files .......................................................................................................... 67
7 Disaster Recovery ..................................................................................................... 69
Overview ................................................................................................................................ 69
Requirements.................................................................................................................. 69
Processing in Disaster Recovery Mode ....................................................................... 69
Convert a Register to Lead .................................................................................................. 70
Restore the Lead Register .................................................................................................... 71
Custom Actions ..................................................................................................................... 71
Convert a Register ......................................................................................................... 72
Restore the Lead Register ............................................................................................. 72
A The Daily Maintenance Process: Atom by Atom .................................................... 73
The BUSINESS_DATE_CHANGED Chain ....................................................................... 73
The UPDATES Chain ........................................................................................................... 79
viii
Send Us Your Comments
Oracle Retail Xenvironment, User Guide, Release 18.0
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.
ix
Preface
The Oracle Retail Xenvironment User Guide describes the installation, upgrade, and
configuration of Oracle Retail Xenvironment release 18.0.
Audience
This User Guide is intended for anyone responsible for the installation, upgrade, and
configuration of Oracle Retail Xenvironment 18.0.
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 that have purchased support 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 Oracle Retail Xstore Suite 18.0
documentation set:
 Xstore Suite Release Notes
 Xstore Suite Oracle Retail Xstore Suite 18.0/Merchandising 16.0.2. Implementation Guide
 Xstore Point-of-Service User Guide
 Xstore Point-of-Service Mobile User Guide
 Xstore Point-of-Service Reports Guide
 Xstore Point-of-Service Manager's Guide
 Xstore Point-of-Service Shipping, Receiving, and Inventory Guide
 Xstore Office User Guide
 Xstore Suite Implementation and Security Guide
 Xstore Point-of-Service Frameworks and Technologies Guide
 Xstore Suite Deal Pricing Guide
 Xstore Point-of-Service Services Guide
 Xstore Point-of-Service Technical Guide
 Xstore Point-of-Service Host Interface Guide
 Xstore Point-of-Service Database Dictionary Guide
 Xstore Point-of-Service POSLog Changes
 Xstore Office Database Dictionary Guide
Customer Support
To contact Oracle Customer Support, access My Oracle Support at the following URL:
xi
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
Review Patch Documentation

When you install the application for the first time, you install either a base release (for
example, 18.0) or a later patch release (for example, 18.0.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

Oracle Retail product documentation is available on the following web site:
http://www.oracle.com/technetwork/documentation/oracle-retail-100266.html
(Data Model documents are not available through Oracle Technology Network. You can
obtain them through My Oracle Support.)
xii
Conventions
The following text conventions are used in this document:
Convention Meaning
Navigate: This is a navigate statement. It tells you how to

get to the start of the procedure and ends with
a screen shot of the starting point and the
statement “the Window Name window
opens.”
Note: This information is provided to improve your

understanding, simplify a task, or point out
special circumstances.
Important: This information is important for the user to be

aware of. For example, information that can
help prevent the loss of data.
code This is a code sample. It is used to
display examples of code.
xiii
1
Introduction
Overview
The main purpose for the Oracle Retail Xenvironment application consists of three
important functions:
 Help the point-of-sale (POS) software perform daily maintenance procedures.
 Assist the POS software with software upgrades.
 Secure the operating system.
The Oracle Retail Xenvironment application is installed on a POS register and provides a
communication link between the lead and non-lead registers. (See “Responsibilities of
Both Lead and Non-Lead Registers”.) An internal messaging framework enables Oracle
Retail Xenvironment to send messages between the Oracle Retail Xenvironment engine
and the Oracle Retail Xenvironment UI, between a lead register and non-lead registers,
and between Oracle Retail Xenvironment and the Dataserver.
The messaging framework also allows messages to be sent back and forth between
Oracle Retail Xenvironment and the Oracle Retail Xstore Point-of-Service POS
application. Thus, Oracle Retail Xstore Point of Service can notify Oracle Retail
Xenvironment, by Xstore, or remotely via HTTPS messaging. when a specific task must
be completed. For example, daily maintenance processes handled by Oracle Retail
Xenvironment are started automatically when Oracle Retail Xstore Point of Service sends
a message through this communication link.
How this User Guide Is Organized

This chapter provides general information about Oracle Retail Xenvironment; including
an overview of the directories created during installation, the configuration files and how
they are used, TLS (Transport Layer Security) information for PCI compliance,
generalized properties files information, and information about the major functions that
Oracle Retail Xenvironment performs.
 “Atoms and Chains” provides information about atoms and chains, what they do,
how they are used, and how they are created and configured.
 “Configuring the Oracle Retail Xenvironment Engine” describes the files and
directory structure for the Oracle Retail Xenvironment engine, and how they are
used in configuration.
 “Configuring Oracle Retail Xenvironment GUI” describes the files and directory
structure for the Oracle Retail Xenvironment UI, and how they are used in
configuration.
 “Oracle Retail Xenvironment Processing” describes how Oracle Retail Xenvironment
performs normal processing functions, such as processing updates, performing
trickle polling, and processing archive files.
 “Using Oracle Retail Xenvironment” describes how to use Oracle Retail
Xenvironment. This includes a description of the UI and the screens and options
found in it.
 “Disaster Recovery” explains disaster recovery procedures for Oracle Retail
Xenvironment.
Oracle Retail Xenvironment User Guide 1

Introduction
 “The Daily Maintenance Process: Atom by Atom” goes through each atom and chain
in the Daily Maintenance store chain, describing the actions performed by each atom
and chain.
Who Should Use this Guide

This guide is intended for anyone responsible for the installation, upgrade, and
configuration of Oracle Retail Xenvironment 18.0. This guide assumes that the person
performing the installation has a working knowledge of XML, the Oracle or SQL Server
database, the Windows or Linux operating system, and the network system being used.
Security
On a register running Oracle Retail Xenvironment, the user is restricted to only the tasks
that are displayed and available through Oracle Retail Xenvironment's graphical user
interface (GUI). The tasks that you make available can be configured to be run from on-
screen buttons, keystrokes, and menus. All tasks can be password-protected to ensure
that only employees with the proper permission level can run security-restricted
commands.
TLS-Encrypted Communication
To ensure PCI compliance, Oracle Retail Xenvironment requires authenticated, TLS-
encrypted communications with Oracle Retail Xstore Point of Service and with other
systems running Oracle Retail Xenvironment. All systems must use TLS to communicate
with Oracle Retail Xenvironment 18.0.
2
Oracle Retail Xenvironment 18.0
User Interface
Oracle Retail Xenvironment uses a screen layout that is similar to Oracle Retail Xstore
Point of Service. Information is displayed in a focus bar, view port, and status bar.
Functions and actions can be performed through a row of menu buttons placed near the
bottom of the screen.
The Oracle Retail Xenvironment interface is intended to replace the default operating
system shell. Figure 1-1 shows the Start Screen of the Oracle Retail Xenvironment UI.
Figure 1-1: Oracle Retail Xenvironment – Start Screen
Note: For a more complete description of the UI elements,

see “Using Oracle Retail Xenvironment“.
The main features of the Start Screen, from top to bottom, are the Please Note section, the
POS Status, the System Support/Attention section, the Menu Buttons and the Status Bar.
 Please Note: Displays messages and alerts from Oracle Retail Xstore Point of Service
and Oracle Retail Xenvironment.
 POS Status: Displays store and register status information.
 Systems Support/Attention: Describes how to return focus to Oracle Retail Xstore
Point of Service or Oracle Retail Xenvironment.
 Menu Buttons: A row of buttons that are used to perform functions available in
Oracle Retail Xenvironment. To use the buttons, either touch them on a touchscreen
monitor, click them with the mouse cursor, or press the associated shortcut key.
Functions and actions can also be performed through hotkeys.
 Notification Area/Process Status: The Notification Area displays activity
information.
 Status Bar: Displays information describing the register system, store location, and
updates from processes run by the user through Oracle Retail Xenvironment.
Oracle Retail Xenvironment Installation and Configuration

When you install Oracle Retail Xenvironment, the files are generally installed in the
c:\environment directory on a Windows system and the /opt/environment

Introduction
directory on a Linux system. Even though the paths are configurable, it is best to use the
default location to ensure there are no problems resulting from cross-application updates
and user permissions.
Note: All paths shown in this document are default paths

(see below).
 For a description of Oracle Retail Xenvironment installation, see the Oracle Retail
Xstore Suite Implementation and Security Guide.
 For more information about the directories created by the Base Oracle Retail
Xenvironment installation, see “Base Oracle Retail Xenvironment Directory Structure
and Contents”.
 For more information about the directories created by the Oracle Retail
Xenvironment GUI installation, see “Oracle Retail Xenvironment UI Directory
Structure and Contents”.
Default Installation Path

The directory location for Oracle Retail Xenvironment contains all subdirectories and
files required to run the application. This directory location is configurable, but because
of cross-application updates and user permissions, it is best to use the default location.
The default location for the Oracle Retail Xenvironment application depends upon the
operating system:
 Windows: c:\environment
 Linux: /opt/environment
Another directory is used specifically for processing application updates:
 Windows: c:\updates
 Linux: /opt/updates
Daily Maintenance Procedures

In addition to locking down the Operating System and providing a basic set of menu
options, Oracle Retail Xenvironment also performs daily maintenance tasks. The
requirements vary among different retail chains, so Oracle Retail Xenvironment is
designed so that every step of daily maintenance is configurable to meet customer
requirements.
The daily maintenance procedure is initiated when the store is finished with a business
day. This would be either closing the store, or entering a new business period when
using rolling close. Oracle Retail Xstore Point of Service sends a "business date changed"
message to Oracle Xenvironment during either of these events, through an internal
communication framework.
When Oracle Retail Xenvironment receives this message, it assumes control and
processes the maintenance steps that are defined in a configuration file. These steps are
enumerated and described in “The Daily Maintenance Process”.
Software Updates
Oracle Retail Xenvironment has a built-in framework that can be used to perform
software upgrades. The primary purpose of this framework is to upgrade the Oracle
Retail Xstore Point of Service and Oracle Retail Xstore Payment software. However, it can
also be used to upgrade other software packages, such as applying Windows service
packs. This process runs as part of daily maintenance.
4
Note: Once the upgrade packages are downloaded to each

store location, no user intervention is required to start or
perform the upgrade process.
Lead Register Responsibilities

The Oracle Retail Xenvironment software on the Lead Register monitors certain
directories for downloaded upgrade packages. The atom update-feeds detects and
copies files to the locations defined in the update.properties file. Each register may
download the files from these locations. To automate the process, Oracle Retail
Xenvironment runs the update atoms automatically—usually during store closing.
During startup the update.properties file is read to determine which directories to
monitor for upgrade packages, and to determine the upgrade category of the files.
When a new file is detected, it is copied to the internal web server directory from which
all the registers can download it. This download directory also contains an XML file for
the update. The XML file is updated with certain information about the update file, to
ensure a successful download to each register.
For example, when an Oracle Retail Xstore Point-of-Service upgrade is sent down to a
store, Oracle Retail Xenvironment detects the new files in the update directory and copies
them to the web server's download directory. Next, Oracle Retail Xenvironment
determines the category type of the upgrade and updates the
xstore-rss.xml file with the appropriate information. Once the files are copied to this
directory, each register is responsible for retrieving them.
Responsibilities of Both Lead and Non-Lead Registers

The Oracle Retail Xenvironment software on both lead and non-lead registers checks for
upgrade packages by sending an HTTP request message to the Lead Register. The
check-and-apply-updates chain applies the upgrade packages on nonlead
registers. The steps contained within the check-and-apply-updates chain are also
run on the lead to carry out upgrade tasks.
Request messages are sent to the URL defined in the file update.properties. When a
register sends this request, a response message is sent back indicating whether or not
new upgrade packages are available. If new upgrades are available, the response
message will contain the URL of the download file. The register automatically
downloads the file(s) using the URL that was sent back in the response message.
Once the upgrade packages are downloaded to the local machine, Oracle Retail
Xenvironment applies the updates.
Commonly Used Chains and Atoms

Oracle Retail Xenvironment allows a user to run atoms or chains directly through an
option that prompts for an atom or chain name. This window is opened with the
[CTRL]+[ALT]+[R] key sequence.
All of the available atoms are defined in the actions.properties file. Most of the
defined atoms are used internally by Oracle Retail Xenvironment and are not normally
executed by a user. The following tables contain atoms and chains that are most likely to
be started by the user.
Note: All chain and atom commands are case-sensitive.

Introduction
Table 1-1: Common Atoms and Descriptions
Atom Name Description
start-xstore Starts the Oracle Retail Xstore Point-of-Service

application if it is not running. If Oracle Retail
Xstore Point of Service is running, sets focus to the
running instance of Oracle Retail Xstore Point of
Service.
shutdown-xstore Triggers Oracle Retail Xstore Point-of-Service
application to exit.
execute-dataloader Initiates DataLoader.
commandprompt Windows: Opens a DOS command prompt.
Linux: Opens an xterm window. If xterm is not
available, the person installing Oracle Retail
Xenvironment should configure this atom for a
line-command entry window that is available on
the system.
Table 1-2: Common Chains and Descriptions
Chain Name Description
BUSINESS_DATE_CHANGED Initiates Oracle Retail Xenvironment’s Daily

Maintenance process
check-and-apply-updates Checks for new updates, then applies the updates.
restore-nightly-db-backup Process in which the non-lead registers download
and restore the nightly backup from the Lead
Register.
6
2
Atoms and Chains
Overview
Oracle Retail Xenvironment actions are defined in components called “atoms” and
“chains”. These two components are the basic units that contain the actions executed by
Oracle Retail Xenvironment.
Atoms and chains may be triggered by the GUI, or they may be triggered by Hotkey
operations. They can be invoked on a schedule, as part of a startup sequence, or as part of
the daily maintenance sequence.
About This Chapter

This chapter contains the following information:
 “Atoms” - Describes what atoms are, what they do, and how to create and configure
them.
 “Chains” - Describes what chains are, what they do, and how to create and configure
them.
 “Denymarkers” - Describes what denymarkers are and how they are used.
 “Allowmarkers” - Describes what allowmarkers are and how they are used.
Naming Rules
Atom and chain names can include the following characters:
 Letters (A-Z, a-z)
 Numbers (0-9)
 Dashes (-)
 Underscores (_)
No other characters are permitted in the names of atoms or chains.
Note: Atom names frequently include suffixes that indicate

their intended use. An atom that ends in –trickle is
intended for use in trickle polling, -close is intended for
use during daily maintenance, and so on.
For example, the execute-downloads atom is intended
for use as part of processing, while the execute-
downloads-trickle atom is intended for use in trickle
polling.
Atoms
An atom is a single action that may be executed. An atom is a configurable component
that consists of a Java class (.class), any accompanying arguments, and any
configuration options. Atom configurations are found in the file actions.properties.

Atoms and Chains
Example
The atom shown below starts the Oracle Retail Xstore Point-of-Service application:
atom.start-xstore.class=LaunchMaster
windows.atom.start-xstore.args=%{s:xstore.dir.root}/xstore.bat
linux.atom.start-xstore.args=%{s:xstore.dir.root}/xstore.sh
atom.start-xstore.hide=True
atom.start-xstore.wait=False
atom.start-xstore.disabled=%{b:xstore.disabled}
atom.start-xstore.cwd=%{s:xstore.dir.root}
windows.atom.start-xstore.windowtitle=Oracle Retail Xstore
Point of Service
windows.atom.start-xstore.windowclass=SunAwtDialog
Invoking the start-xstore atom calls the LaunchMaster function using an argument
that contains the complete path to a shell script. In the example above, the atom's name is
start-xstore, and the atom's class is LaunchMaster.
The atom's argument in Windows and Linux:
%{s:xstore.dir.root}/xstore.bat (Windows)
%{s:xstore.dir.root}/xstore.sh. (Linux)
In addition the class and arguments, several configuration options are set in this atom.
The hide attribute is set to True, the wait attribute is set to False, and so on. And, on
Windows only, the windowtitle and windowclass configurations are used to
determine if Oracle Retail Xstore Point of Service is running already and, if it is running,
switch to it.
Atom Aliases
Aliases can be assigned to atoms, allowing an atom to be used multiple times in a given
chain (each atom in a single chain must have a unique name), as well as provide
shortened or simplified atom references. Aliases may be set for frequently referenced
functions.
For example, the following line in actions.properties creates an alias
dataserver-backup-xstore-pre-poll that, when called, will run the atom
dataserver-oracle-backup-xstore-pre-poll, when database.platform is
set to a value of oracle.
alias.dataserver-backup-xstore-pre-poll.action=
dataserver-%{s:database.platform}-backup-xstore-pre-poll
Note: The rules for atom alias names are the same as those
for atom names (see “Naming Rules”).
Permit or Prevent Atoms From Starting At Certain Times

Within Oracle Retail Xenvironment, atoms can be configured to either only start running
within, or not start during, certain time periods on certain days of the week. These
configurations are set up in the actions.properties file.
8
Note: These permit/disallow times only determine the times

when atoms can start. If atoms are still running during a
prohibited time, the atom will continue running until it
ends. Atoms will not be stopped if they continue running
outside an allowed time period, or into a prohibited time
period.
Permit Times
Permit times configure the days and times of the week when an atom can start running.
The times configured are the only times when the atom can start.
Permitted start times for atoms are configured using the following format:
atom.name.permitted_start_times=<day_of_week>,<time>,<duration
>[;...]
 name - The name of the atom.

 <day_of_week> - This configuration can have one of the following values:
 The first three letters of the day of the week being configured (all lower-case), for
example sun, mon, tue, wed, thu, fri, or sat.
 An asterisk (*) indicating that all the days of the week are being configured.
 <time> - The time of day the time period starts (in 24-hour clock).
 <duration> - The duration of the time period, in hours.
 [;...] - Use semicolons to separate additional day(s) of the week, time(s), and
duration(s) to the permit time period.
Disallow Times
Disallow times configure the days and times of the week when an atom cannot start
running. Atoms cannot start within the times configured.
Disallowed start times for atoms are configured using the following format:
atom.name.permitted_start_times=!<day_of_week>,<time>,<duratio
n>[;...]
 name - The name of the atom.

 ! - Include this NOT symbol to set times when the atom will NOT run.
 <day_of_week> - This configuration can have one of the following values:
 The first three letters of the day of the week being configured (all lower-case).
 An asterisk (*) indicating that all the days of the week are being configured.
 <time> - The time of day the time period starts (in 24-hour clock).
 <duration> - The duration of the time period, in hours.
 [;...] - Use semicolons to separate additional day(s) of the week, time(s), and
duration(s) to the disallow time period.

Atoms and Chains
Example #1
atom.example1.permitted_start_times=*,19:00,3
The example1 atom can start running at any time between 7:00 PM and 10:00 PM on any
day of the week.
Example #2
atom.example2.permitted_start_times=wed,4:00,3;thu,22:00,4
The example2 atom can start running at any time between 4:00 AM and 7:00 AM on
Wednesday, or any time between 10:00 PM Thursday and 2:00 AM Friday.
Example #3
atom.example3.permitted_start_times=!*,8:00,12
The example3 atom cannot start running at any time between 8:00 AM and 8:00 PM on
any day of the week.
In other words, the atom CAN start running at any time between 8:00 PM and 8:00 AM.
Example #4
atom.example4.permitted_start_times=!sat,19:00,3;!sun,19:00
,5
The example4 atom cannot start running at any time between 7:00 PM and midnight on
either Saturday or Sunday.
In other words, the atom CAN start running at any time Monday through Friday, or
anytime between 12:00 AM and 7:00 PM on either Saturday or Sunday.
Creating Atoms
It may be necessary to create a custom action to accomplish a task. You may configure a
new atom in the file actions.properties (see “actions.properties”) by following
these steps:
1. Assign a unique name to the new atom, such as my-new-atom.
a. Assign the atom to a class. Refer to Table 2-1: Common Classes for Creating
Custom Atoms for Class detail.
2. Determine the atom's required set of arguments. For information about the
arguments for each class, refer to Table 2-1: Common Classes for Creating Custom
Atoms below.
3. Within the actions.properties, add the atom using the correct prefix (atom.)
and suffix (.class and .args):
atom.theAtomName.class=
atom.theAtomName.args=
10
Sample New Atom:

atom.my-new-atom.class=the_class_used
atom.my-new-atom.args={list of arguments}
Table 2-1: Common Classes for Creating Custom Atoms
Class Description
LaunchMaster This class is used to execute a shell script or binary.

Arguments:
[directory to execute] [file to execute]
[script/binary arguments]
This class includes many configuration options. See
“LaunchMaster Configurations”.
CopyFiles This class is used to copy files from one location in the file
system to another.
Additional configurations:
.source - the source directory of files
.regex - a regular expression matching the file to copy
.destination - the destination directory
.filterflags - comma separated list of the following
options:
CANON_EQ, CASE_INSENSITIVE, COMMENTS,
DOTALL, LITERAL, MULTILINE,
UNICODE_CASE, UNICODE_CHARACTER_CASE,
UNIX_LINES
(See - javadoc for java.util.regex.Pattern for
more information.)
MakeDirectory This class is used to create a new directory tree. All the
directories within the configured path are created by this
class, including all intermediate directories.
.directory - The directory structure to be created.
.mode - The posix string representation of the permissions.
It has 9 characters that are interpreted as three sets of three.
The first set refers to the owner's permissions; the next to the
group permissions and the last to others. Within each set,
the first character is 'r' to indicate permission to read, the
second character is 'w' to indicate permission to write, and
the third character is 'x' for execute permission. Where a
permission is not set, the corresponding character is set to
'-'. ([DEFAULT] rwxr-x---).

Atoms and Chains
Class Description
MoveFiles This class is used to move files from one location to another.
.source - the source directory
.regex - a regular expression matching the file to move
.target - where to move the files
.filterflags – comma separated list of the following
options:
UNIX_LINES
(See - javadoc for java.util.regex.Pattern for
more information.)
.errmarker - The flag file to create, if an error is
generated by an atom or chain.
.drsafe - Determines whether the atom can be run while
the system is in disaster recovery mode.
.disabled - Indicates whether the atom is disabled
RemoveDirectory This class is used to remove a directory and all the
subdirectories and files within that directory tree.
.directory - directory to be removed.
.recreate - If true, a new directory will be created with
the name, once after removing the old directory.
RemoveFiles This class is used to remove files from the file system. It
gives the user the ability to remove individual files, or all
files in a directory.
Additional configuration:
.filepath – directory containing the files to remove.
.filefilter - regular expression used to match files
to remove.
.filterflags – comma separated list of the
following options:
UNIX_LINES
(See -javadoc for java.util.regex.Pattern for
more information.)
12
Class Description
RotateFiles This class is commonly used for rotation archive files. It

gives the user the ability to define how many files/archives
to keep.
.backup_count - number of archives to keep
.path - where we will look for files to rotate
.filter - regular expression used to match files to
rotate
.filterflags - comma separated list of the following
options:
UNIX_LINES
(See - javadoc for java.util.regex.Pattern
for more information.)
Unzip This class extracts files from one or more .zip archives.
.archive - a fully qualified path of a single ZIP file to
process. (If specified, .archives and .srcdir are
ignored)
.srcdir - used with .archives to indicate the
directory to search for ZIP files to extract
.archives - regular expression matching ZIP files to
extract
.filterflags - (same explanation as other locations)
DEFAULT: CASE_INSENSITIVE
.archives
.path - The directory into which the files in the .zip
archive(s) are extracted.
.srcdir - The location of the .zip archive(s).
.delete_unzipped_archives - [True/False]
Determines whether the .zip archives are deleted after they
are unzipped.

Atoms and Chains
Class Description
Zip This class places a set of files into a .zip archive.

.path - The directory location of the files to be placed in
the .zip archive.
.regex - The regular expression identifying the files in the
.path that will be included in the archive.
.archive - The directory location and filename of the
.zip file.
.traverse_subdirectories - [True/False]
Indicates whether the
.archive - File will contain the subdirectories of the .path
(True), or if it will include only the files in the .path.
.delete_files_after_archived - [True/False]
Determines whether the files are will be deleted after they
are archived.
LaunchMaster Configurations
The LaunchMaster class includes several important configurations, such as how an atom
is executed, the options used in its execution, and what LaunchMaster should do if there
are errors. The LaunchMaster class has the following configuration options:
 .args - The command to run including any arguments.
 .allowmarkers - Controls whether a chain or atom can be run (see
“Allowmarkers”).
 .cwd - Sets the current working directory used by the script during execution.
 .denymarkers - Controls whether a chain or atom can be run (see “Denymarkers”).
 .disabled - [True/False] Indicates whether the atom is disabled. If set to
True, the atom will not run.
 .drsafe - [True/False] Determines whether the atom can be run while the
system is in disaster recovery mode. Only atoms with this configuration set to “True”
can run while the system is in disaster recover mode.
 .errmarker - The flag file to create if an error is generated by an atom or chain.
This configuration applies to all atoms and chains.
 .hide - [True/False] Indicates whether the script execution should be hidden.
 .useretcode - [True/False] Determines whether a return code of 0 is
considered successful execution or an error.
 If set to True, the return value from the command is used. A value of 0 or 99
indicates successful execution and 20 indicates a warning; any other value
indicates an error.
 If set to False, a return value of 0 indicates successful execution; any other value
is an error.
 .wait - [True/False] Used in chains. Indicates whether execution of the chain
should wait for the atom to complete before running the next atom in the chain.
 .warnmarker - The flag file to create if a WARNING is generated by an atom or
chain. This configuration applies to all atoms and chains.
14
 .windowtitle - (Windows only) Defines the Windows window information. If this

configuration is specified, Oracle Retail Xenvironment will look for the window and
switch to it rather than attempting to start the application.
 .windowclass - (Windows only) used with windowtitle to locate an existing
window
 .xname - Displays a status message in Oracle Retail Xstore Point of Service. This
configuration applies to all atoms and chains.
 .xcode - Displays a status message in Oracle Retail Xstore Point of Service. This
configuration applies to all atoms and chains.
Chains
A chain is a component that includes multiple atoms or chains, each of which is an
action, and is listed in the sequence in which it should be performed. Chain
configurations are found in the actions.properties file (see “actions.properties”).
Example
This chain checks for updates and applies them:
lead.chain.trickle-polling.atoms=unzip-uploaded-trickle-
packages
create-final-trickle-polling-package poll-trickle
process-pre48-trickle-downloads execute-dataloader-trickle
The lead keyword at the start of the chain limits this chain to only run on the lead
register. If the chain only runs on nonlead registers, the chain would start with the
nonlead keyword. Chains that run on both lead and nonlead registers do not specify
either lead or nonlead.
In the example above, the chain’s name is trickle-polling and it executes the atoms
in the order that they are listed:
1. unzip-uploaded-trickle-packages - Unzips trickle packages uploaded to the
lead register.
2. create-final-trickle-polling-package - Combines the contents of all the
uploaded trickle packages into one final package.
3. poll-trickle - Uploads the final package to the corporate server.
4. process-pre48-trickle-downloads - Processes update files downloaded to the
system.
5. execute-dataloader-trickle - Downloads updates from the Dataloader.
Inserting an Atom or Chain Into a Chain

Atoms and chains can be added to chains without altering the default chain definition.
This is done using the .insertbefore and .insertafter chain configuration
settings in the cust_config/version1/actions.properties file (see
“Subdirectory: <root_directory>\cust_config\version1” and “actions.properties” for
more information).
These configuration options have the following format:
chain.<chain_name>.<insertbefore/insertafter>.<atom_name>=<new
_atom> [<new_atom2> ...]

Atoms and Chains
Multiple new atoms and chains can be inserted in the same location in a chain by listing
multiple, space-separated atoms.
Example
In this example, there is a chain named example. Its default configuration consists of the
atoms atom1, atom2,and atom3. The configuration of this chain would be the
following:
chain.example.atoms=atom1 atom2 atom3
Three atoms are to be added to the chain: begin,stop, and pause.
1. To insert the atom begin to the start of the chain, add the following configuration to
the cust_config/version1/actions.properties file:
chain.example.insertbefore.atom1=begin
2. The following configuration inserts the atom stop at the end of the chain:
chain.example.insertafter.atom3=stop
3. Either of the following configurations will insert the atoms pause and resume
between atom1 and atom2:
chain.example.insertafter.atom1=pause resume
-OR-
chain.example.insertbefore.atom2=pause resume
When the three configurations above are made, the chain will now be equivalent to the
following (note that the following line will not actually appear in any file):
chain.example.atoms=begin atom1 pause resume atom2 atom3
stop
Creating Chains
If you need to combine multiple atoms into a new chain, follow these steps:
1. Give the chain a unique name, such as my-new-chain. To avoid possible future
collision, include a unique prefix, like the retailer ID.
2. Identify the atoms and/or chains that will be included in the chain. Enter each atom
or chain in the order that it will be executed and separate it with a space from the
others. For example:
atom1 atom2 chain3 atom4
3. Enter the chain into the file actions.properties with the required chain prefix
(chain.) and suffix (.atoms).
For example:
chain.my-new-chain.atoms=atom1 atom2 chain3 atom4
Note: The “atoms=” and “chains=” lists are no longer

needed in the configuration file. xEnvironment now scans
the configuration file on startup.
If a non-existent atom is listed in a chain, an error will be
logged in the file xenvironment.log and execution of the
chain will abort.
16
Denymarkers
Denymarkers are used to prevent a chain or atom from running. If a denymarker is set
for a chain or atom, the chain or atom will not run if the marker file exists in the marker
directory (see “Subdirectory: <root_directory>\marker” for more information).
For example, if the following line exists in the actions.properties file:
chain.BUSINESS_DATE_CHANGED.denymarkers=close.err
the chain BUSINESS_DATE_CHANGED will not run if the marker file close.err exists in
the marker directory.
Wildcard characters are allowed. Space-separated lists of filenames can be used to
indicate multiple possible filenames. For example, if the following line exists in the
actions.properties file:
atom.start-xstore-auto.denymarkers=*.err *.wrn
xstore.running
the atom start-xstore-auto will not run if any file ending in either .err or .wrn
exists in the marker directory, or if the file xstore.running exists in the marker
directory.
Allowmarkers
Allowmarkers are used to control whether a chain or atom can be run. If an allowmarker
is set for a chain or atom, the chain or atom will only run if the marker file exists in the
marker directory (see “Subdirectory: <root_directory>\marker” for more information).
For example, if the following line exists in the actions.properties file:
chain.BUSINESS_DATE_CHANGED.allowmarkers=close.ready
the atom BUSINESS_DATE_CHANGED will not run unless the marker file close.ready
exists in the marker directory.
Wildcard characters are allowed. Space-separated lists of filenames can be used to
indicate multiple required files. For example, if the following line exists in the
actions.properties file:
atom.start-xstore-auto.allowmarkers=*.xst *.dta
xstore.installed
the atom start-xstore-auto would only run if at least one file ending in .xst, at
least one file ending in .dta, and the file xstore.installed exist in the marker
directory.

3
Configuring the Oracle Retail Xenvironment
Engine
Overview
This chapter describes the files used to configure the Oracle Retail Xenvironment engine.
This includes information about the directories and files used in configuration, the
content of those directories and files, and how configuration is performed.
Important: This chapter should only be used by customers

who have already installed Oracle Retail Xenvironment 18.0.
About this Chapter

This chapter includes the following information:
 “Base Oracle Retail Xenvironment Directory Structure and Contents” describes the
directory structure used by Oracle Retail Xenvironment.
 “Configuring the Oracle Retail Xenvironment Engine” explains how Oracle Retail
Xenvironment is configured for customers.
Base Oracle Retail Xenvironment Directory Structure and Contents

This section describes the contents of the directories and subdirectories that comprise the
directory structure for Base Oracle Retail Xenvironment.
The installation directory for the Oracle Retail Xenvironment application is indicated by
“<root_directory>”.
The default <root_directory> for Windows and Linux:
 c:\environment (for Windows)
 /opt/environment (for Linux)
The Main Directory: <root_directory>

This directory contains subdirectories used for different portions of Base Oracle Retail
Xenvironment The files version.properties - which is created when Oracle Retail
Xenvironment is started, and contains version information - and
cust_config/version1/local.properties—which contains store-specific and
register- specific settings used during installation—are in the installation directory. In
addition, the start_eng.bat and start_ui.bat files are in this folder.
The <root_directory> also contains the main directory for the Oracle Retail
Xenvironment GUI.
Subdirectory: <root_directory>\bin
This directory contains the native binaries used by Oracle Retail Xenvironment.

Configuring the Oracle Retail Xenvironment Engine
Subdirectory: <root_directory>\cust_config\version1
Configuration files containing customer-specific updates to the files in the
<root_directory>\config directory. Any configurations entered into files in this
directory override the configurations in the files in the <root_directory>\config
directory. All overrides are performed on a setting-by-setting basis, not a file-by-file
basis.
Important: Never make changes in the

<root_directory>\config directory. All configurations
changes must be made as overrides in the
<root_directory>\cust_config\version1 directory.
Subdirectory: <root_directory>\res\data
This directory stores .dat files containing details about updates that have been
processed, and one .dat file that tracks registration information. These files are accessed
during the update process. In some cases, additional subdirectories may be created in
this directory to store files or database backups.
Subdirectory: <root_directory>\download
This directory is used as a location for registers to place files that have been copied from
other registers. For example, when the Lead Register is preparing the PosLog files, it
copies them from each register to the directory <root_directory>\download\tmp
and then prepares the polling upload file(s).
Subdirectory: <root_directory>\ext
This directory contains miscellaneous shell and binary files. Directly under
<root_directory>\ext are shell scripts invoked by Oracle Retail Xenvironment
actions.
Within this directory is the subdirectory <root_directory>\ext\util. This subdirectory
contains binary files, most of which are troubleshooting and/or support tools.
Subdirectory: <root_directory>\log
This subdirectory contains the log files produced by the Oracle Retail Xenvironment
application.
Subdirectory: <root_directory>\marker
This directory is used for marker files. A marker file provides a way for a register to
“flag” (i.e. indicate) the status of a currently running process. One important marker file
is SYSCLOSE.XST, which is created on the Lead Register when the daily maintenance is
running.
Subdirectory: <root_directory>\poll
This directory is used to include additional files in the pospoll package. Oracle Retail
Xenvironment automatically copies files here for inclusion in the polling package, and
any additional files added to this directory will also be included in the package. This
directory also contains a trickle/ folder that is used for trickle polling.
20
Subdirectory: <root_directory>\res\ssl
This directory contains the TLS certificates.
Subdirectory: <root_directory>\tmp
This directory contains temporary files used by Oracle Retail Xenvironment.
Subdirectory: <root_directory>\wwwroot
This directory is used with the web server. It is the root directory for any “child” folders
to be made available for download through HTTPS.
Subdirectory: <root_directory>\ wwwroot \support

This directory contains packages generated by the “capture logs” function.

The Oracle Retail Xenvironment application may be configured for your specific
requirements by knowing how to edit the configuration file and understanding how to
create atoms and chains. In addition, knowledge of the software update process and the
log files will also be helpful.
A number of different “properties” files are used to configure Oracle Retail
Xenvironment. A detailed description of them is given in this section.
environment.properties
The environment.properties file defines the following properties used by Oracle
Retail Xenvironment:
 Available Roles - Defines the names of the roles to which registers can be assigned.
 Environment Variables - Defines paths used internally to locate certain files needed
for specific tasks in Oracle Retail Xenvironment.
 Root Directory - Indicates the root directory where Oracle Retail Xenvironment was
installed.
 Marker File Variables - Defines the names and paths for marker files used by Oracle
Retail Xenvironment.
 Zip File Database Configurations - Defines the names and paths of files in .zip
format that are used during various operations.
 Deployment Process Configuration - Determines the servers, connections,
destination directories, and other configurations required for the deployment
process.
 Operating System Options - Sets configuration options that affect the operating
system and the user’s ability to interact with it.
 Signature Validation - Determines whether Oracle Retail Xenvironment uses
security signature files to validate Oracle Retail Xstore Point-of-Service update files,
and the associated configurations if this option is enabled.
To turn off signature validation:
atom.apply-updates-xstore.allow_unsigned=false
atom.apply-updates-xstore-immediate.allow_unsigned=false
 POS Options - Configures properties that are specific to the point-of-sale software
running on the local register.

 Hostname for Registration - Forces a specific hostname for registration (this should
only be used in the rare case that the engine is unable to get the correct hostname).
 IPC Ports - Determines the default network ports used by Oracle Retail
Xenvironment client and server functions.
 Broadcast Markers - Defines marker files that are broadcast from any register to any
other register in the store (by default, the only file broadcast is the close.err
marker, which is created in the lead register). For more information about marker
files, see “Denymarkers” and “Allowmarkers”.
Automated installation methods are available to customers, but if the
environment.properties file must be configured manually for a customized version
of Oracle Retail Xstore Point of Service, the following customer-specific configurations
are required:
 marker.pollok: the directory and file used to flag the daily maintenance and indicate
that polling has been completed.
Example:
marker.reboot=%{s:environment.dir.root}/marker/ reboot.xst
(The space after /marker/ is intentional and must be included.)
 pos.dir.download: the destination directory for the update files that are distributed
to non-lead registers by the polling service.
Example:
pos.dir.download.src=%{s:xstore.dir.root}/download/
 pos.dir.db: the directory for the database data file(s) and/or database directory.
Example:
windows.pos.dir.db=c:/xstoredb
local.properties
This file configures register information for Oracle Retail Xenvironment. This
configuration file contains the following settings:
1. Register settings - properties defining the register, its connections to other systems,
and whether the system is a lead or non-lead register.
2. System settings - properties indicating whether the database is disabled and whether
Oracle Retail Xstore Point of Service is present on the register.
If a customized version of Oracle Retail Xstore Point of Service is installed, this file must
be configured “out of the box”. Automated installation methods are available to
customers, but if this file must be configured manually, you must perform “Register-
Specific Configurations” and “System Configurations”.
22
Register-Specific Configurations
Note:
- The lead register information must be configured
correctly for the non-lead registers to locate the other
registers.
- It may take up to an hour for all of the non-lead registers
to locate each other after they first boot up.
- Registers automatically become inactive when they shut
down or reboot.
- The registration data is retained and cached on all
registers so they have the information on the next boot.
This data is cached in the <root_directory>/
res/data/registrationdata.json file.
- Registers become inactive if they do not register for two
hours.
- Registers expire if they do not register for 19 days.
 environment.role - This register’s role in the network (e.g. “lead” or “nonlead”).

Example:
environment.role=lead
 environment.regnum - The register number in the store.
Example:
environment.regnum=1
 environment.lead.name - Computer name of the Lead Register.
Example:
environment.lead.name=REGISTER-1
 environment.storenum - Store number for the store.
Example:
environment.storenum=100
System Configurations
 xstore.disabled - Whether Oracle Retail Xstore Point of Service is installed on the
local system. When set to True, Oracle Retail Xenvironment does not attempt to start
Oracle Retail Xstore Point of Service or send status updates during daily
maintenance.
Example:
xstore.disabled=false

 xservices-hh.disabled - Whether Oracle Retail Xstore Point of Service Handheld

Services are available on the system. When set to True, Oracle Retail Xenvironment
will not support Oracle Retail Xstore Point-of-Service Handheld Services.
Example:
xservices-hh.disabled=false
 database.disabled - Whether the database is disabled on the local system. When set
to True, database-related functionality is disabled. Defaults to False if not specified.
Example:
database.disabled=false
 poll1.disabled - Whether Oracle Retail Xenvironment will wait for the pollok.xst
marker file to exist during daily maintenance and, when it does, execute any steps
related to the first polling session; this includes the CLOSE1 section of the
poll.bat/poll.sh file.
Example:
poll1.disabled=false
 poll2.disabled - Whether Oracle Retail Xenvironment will wait for the
pollend.xst marker file to exist during daily maintenance and, when it does,
execute any steps related to the second polling session; this includes the CLOSE2
section of the poll.bat/poll.sh file.
Example:
poll2.disabled=true
 database-notifications.disabled - Whether database notifications are disabled on the
local system.
Example:
database-notifications.disabled=true
 updates.disabled - Whether Oracle Retail Xenvironment will perform automatic
updates.
Example:
updates.disabled=false
 environment.polling.upload.url - Name of the Apache server used for polling (only
used if environment.polling.disabled=false).
Example:
environment.polling.upload.url=https://apacheserver/upload/
 environment.polling.upload.username - Encrypted username used for logging into
the Apache server (only used if environment.polling.disabled=false).
 environment.polling.upload.password - Encrypted password used for logging into
the Apache server (only used if environment.polling.disabled=false).
 database.platform - The type of database platform (only used if
database.disabled=false). Possible values are oracle and sqlserver.
Example:
database.platform=oracle
 db.service.name - Name of the database service (only used if
database.disabled=false).
Example:
db.service.name= OracleServiceXstore
24
 xstore-mobile.disabled – Whether Oracle Retail Xstore Point-of-Service Software

Mobile can use the system as a mobile server. When set to True, Oracle Retail
Xenvironment will not support Oracle Retail Xstore Point-of-Service Software
Mobile.
Example:
xstore-mobile.disabled=false
 environment.polling.disabled - Whether Oracle Retail Xenvironment will upload
pospoll files to an Apache web server.
Example:
environment.polling.disabled=false
actions.properties
The actions.properties file contains definitions of both “atoms” and “chains”.
An atom is an internal function that Oracle Retail Xenvironment can invoke. A chain is a
list of atoms that are executed sequentially to perform a task. For example, there is a
chain to perform the startup process in Oracle Retail Xenvironment and a chain to
perform daily maintenance. See “Atoms and Chains” for more information about atoms
and chains.
When an atom is added to the actions.properties file, the associated class must be
defined, including any parameters or arguments required by the atom. An example of an
atom definition in the actions.properties file follows. This atom checks to see if
there are any new updates:
atom.check-and-download-updates.class=CheckUpdates
atom.check-and-download-updates.errmarker=check-and-download-
updates.err
atom.check-and-download-updates.disabled=%{b:updates.disabled}
alerts.properties
The alerts.properties file determines which files are used to store alerts. The alerts
can be either errors or warnings. The internal name for the type of alert is assigned to
each associated file. For example, the following configuration indicates that
errClosingFailure alerts will be sent to the CLOSE.ERR file:
CLOSE.ERR=errClosingFailure
update.properties
Oracle Retail Xenvironment is responsible for distributing software upgrades. Normal
upgrades are downloaded from the home office and performed during daily
maintenance. The file update.properties is used by Oracle Retail Xenvironment on
all registers (lead and non-lead) to determine when the upgrade files are made available
for download, and the local destination directories used to store the files.
The Oracle Retail Xenvironment application running on the Lead Register is responsible
for recognizing that new files have been downloaded from the home office. When files
are found, the Lead Register makes the files available to all non-lead registers for
downloading. Therefore, the Lead Register acts as the file “producer”, while the non-lead
registers act as “consumers”.
As a consumer, each register is responsible for sending a request to the Lead Register to
determine whether update files are available. The file update.properties is used by
the non-lead register to determine where to send these requests.

Each RSS feed used for file distribution is configured using the following format:
rss.category.<feedname>.<property>
where:
 <feedname> is the name of the feed. This can be one of the following values:
– xstore - Feed for Oracle Retail Xstore Point-of-Service software updates.
– xadmin - Feed for Oracle Retail Xstore Office software updates.
– cipher - Feed for credit card .cipher file updates.
– debitbin - Feed for debit card .bin file updates.
 <property> is the property being set for the feed. This can be one of the following
values:
– filter: Specifies the naming convention of the download files that belong to a
specific download category. A filter value must be defined for each
<feedname>.
For example:
rss.category.cipher.filter=.*\\.cip$
– web_location: Determines the directory on the web server URL that Oracle
Retail Xenvironment will check for updates on the feed.
For example, using the configuration:
rss.category.cipher.web_location=/updates/cipher
And a webserver name of <hostname>, Oracle Retail Xenvironment will check
for updates at the URL https://<hostname>:9096/updates/cipher.
– source_directory: Determines the directory on the local system to which Oracle
Retail Xenvironment will download updates.
For example:
rss.category.xadmin.source_directory=
%{s:xstore.dir.root}/updates/staging
– unprocessed_directory: Determines the directory on the local system where
Oracle Retail Xenvironment will move files that it does not know how to process.
For example:
rss.category.xstore.unprocessed_directory=
%{s:updates.dir.root}/inbox/xstore/unprocessed
– ready_marker: Determines the path and filename of the marker file that is used
to indicate that a software upgrade is ready for processing. The marker file is
used to prevent multiple worker threads from processing the same software
upgrade more than once.
For example:
rss.category.debitbin.ready_marker=
%{s:rss.category.debitbin.source_directory}/update.ok
– destination_directory: Determines the directory to which files will be moved for
processing.
For example:
rss.category.cipher.destination_directory=
%{s:xstore.dir.root}/res/keys
– temp_directory: The local directory that Oracle Retail Xenvironment uses as a
temporary directory during the installation process.
26
For example:
rss.category.xstore.temp_directory=
%{s:updates.dir.root}/xstore/temp
version.properties
This file, located in the Oracle Retail Xenvironment root directory, contains application
version number information used by Oracle Retail Xenvironment during bootup. This
file is changed when Oracle Retail Xenvironment is updated.
Running Xenvironment as a Service

Xenvironment can be configured to run as a background service, allowing users to
interact directly with the operating system.
In the following steps, <xenv_directory> is the installation directory for Xenvironment.
The default installation directory for Xenvironment:
 Windows: C:\environment
 Linux: /opt/environment
To run Xenvironment as a service:
 In Windows
 In Linux
Windows
1. Stop Xenvironment.
2. Open a command prompt as an administrator.
3. Navigate to the <xenv_directory> in the command prompt.
Note: Enter cd C:\environment if Xenvironment is installed

in its default location.
4. Run the following command:

start_eng.bat install
5. Open the Windows Services panel (see Managing the Windows Service below).
6. Change the log-on user to xstore for the Oracle Xstore Point of Service Xenvironment
Engine service.
7. Open the file <xenv_directory>\cust_config\version1\environment.properties.
8. Add the following line to environment.properties:
environment.gui.disabled=true
9. Reboot the system.
Xenvironment should start automatically.
10. Check for the files <xenv_directory>\tmp\xenv_eng.anchor and
<xenv_directory>\tmp\xenv_eng.pid.
If these files exist, Xenvironment is running.
Managing the Windows Service

To manage the service, open the Services window. To open the Services window, do the
following:
1. Open the Control Panel from the Windows Start Menu.

If you are not using Categories in Control Panel, continue with step 4. Otherwise,
continue with the next step.
2. If you are using Categories in Control Panel, click System and Security.
3. Click Administrative Tools.
4. Double-click Services.
The Service Window opens.
Xenvironment is the Oracle Xstore Point of Service Xenvironment Engine.
For more information about using this window, see your Windows documentation.
Linux
1. Stop Xenvironment.
2. Save the following information into the file /etc/systemd/system/xenv_eng.service:
[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
3. Open a command prompt.
4. Execute the following command in the command prompt:
systemctl enable xenv_eng.service
5. Add the following line to the
<xenv_directory>/cust_config/version1/environment.properties file (this will
disable the Xenvironment user interface):
environment.gui.disabled=true
6. Reboot the system.
7. Check for the files <xenv_directory>\tmp\xenv_eng.anchor and
<xenv_directory>\tmp\xenv_eng.pid.
If these files exist, Xenvironment is running.
28
4
Configuring Oracle Retail Xenvironment GUI
Overview
This chapter describes the files used to configure the Oracle Retail Xenvironment GUI.
This includes information about the directories and files used in configuration, the
content of those directories and files, and how configuration is performed.
Important: This chapter should only be used by customers

About this Chapter

 “Oracle Retail Xenvironment UI Directory Structure and Contents” describes the
directory structure used by the Oracle Retail Xenvironment UI.
 “Configuring the Oracle Retail Xenvironment UI” explains how the Oracle Retail
Xenvironment UI is configured for customers.
Oracle Retail Xenvironment UI Directory Structure and Contents

This section describes the contents of the directories and subdirectories that comprise the
directory structure for the Oracle Retail Xenvironment UI.
The installation directory for the Oracle Retail Xenvironment application is indicated by
“<root_directory>”.
The default installation directories for Windows and Linus:
 c:\environment (for Windows)
 /opt/environment (for Linux)
Configuring the Oracle Retail Xenvironment UI

The Oracle Retail Xenvironment UI may be customized by creating configuration
override files in the <root_directory>/ui_cust_config directory.
The following files and directory structures are found in the
<root_directory>/ui_config directory:
XenvContextConfig.xml
This file defines Contexts in Oracle Retail Xenvironment. These Contexts determine the
configurations for the different Oracle Retail Xenvironment screens.
environment.properties
The environment.properties files defines configurations used by the Oracle Retail
Xenvironment UI.
The most commonly used configurations in the system.properties file are listed
below.

Note: If you need to make changes to any configuration not

found in the following list, speak with your Oracle product
representative.
 Frame.Style - Determines how the Oracle Retail Xenvironment frame is located on

the screen. This configuration has the following options:
– CENTERED - The frame is centered on the screen.
– POSITIONED - The frame is placed at a specific place on the screen.
– AUTO_RESOLUTION [DEFAULT] - Oracle Retail Xenvironment will
automatically fill the screen, using the screen resolution of the display on which
it is shown.
 Frame.Width - The width of the frame in pixels. Only used if the style is set to
CENTERED or POSITIONED.
[DEFAULT] - 1024
 Frame.Height - The height of the frame in pixels. Only used if the style is set to
CENTERED or POSITIONED.
[DEFAULT] - 768
 Frame.X - The x-coordinate location of the top-left corner of the frame, where 0 is the
left corner of the screen. Only used if the style is set to POSITIONED.
[DEFAULT] - 0
 Frame.Y - The y-coordinate location of the top-left corner of the frame, where 0 is the
top of the screen. Only used of the style is set to POSITIONED.
[DEFAULT] - 0
 HideMouse - Indicates whether the mouse cursor is displayed or hidden off of the
screen.
– true - Mouse cursor is hidden off of the screen.
– false – [DEFAULT] Mouse cursor is displayed.
 Locale.Country - The two-letter ISO-3166 country code for the location of the system.
[DEFAULT] - US
 Locale.Language - The two-letter ISO-639 language for the default language to be
used by the system.
[DEFAULT] - en
 PrintScreenFileName - The name of the image file created by a screen print
command.
[DEFAULT] - log/xenv_ps.jpg
XenvAlertsConfig.xml
The alerts displayed in the Oracle Retail Xenvironment UI are configured in the
XenvAlertsConfig.xml file. Each alert has the following elements:
 <alert> - This element delineates one alert configuration.
– <alert_key> - The key used to identify the alert.
– <main_msg_key> - The translation key displayed in the main alert.
– <sub_msg_key> - The translation key displayed in the alert.
– <priority> - The priority of the alert.
– <action> - The action performed when the alert occurs.
30
– <prompt_key> - The translation key displayed in the confirmation prompt.

– <bring_ui_to_foreground> - Bring Oracle Retail Xenvironment to the
foreground when this error occurs.
Example
<Alerts xmlns="http://oracle.com/retail/xstore/config/xenv"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://oracle.com/retail/xstore/config/xenv
../../../xenv-objects/templates/schemas/XenvAlertsConfig.xsd">
<alert>
<alert_key>ALERT_UNDEFINED</alert_key>
<main_msg_key>_ALERT_UNDEFINED</main_msg_key>
<sub_msg_key>_blank</sub_msg_key>
<priority>1</priority>
<action></action>
<prompt_key>SYSTEM_ERROR</prompt_key>
<bring_ui_to_foreground>false</bring_ui_to_foreground>
</alert>
...
</Alerts>
XenvMenuConfig.xml
The XenvMenuConfig.xml file determines the configuration of the menus displayed in
each Context in the Oracle Retail Xenvironment UI.
The XenvMenuConfig.xml file contains four sections that configure different portions
of the interface.
 Context Configuration - Configures the buttons along the bottom of the Oracle
Retail Xenvironment UI for each Context in the application.
 Hotkey Registration - Determines which hotkey combinations are available in
Oracle Retail Xenvironment.
 Pop-up Menu Configuration - Configures the buttons available on the Pop-up
Windows in Oracle Retail Xenvironment.
 Menu Key Configuration - Configures the buttons that are referenced by the
Context Configuration, Hotkey Registration, and Pop-up Menu Configuration
sections.
Context Configuration
In Oracle Retail Xenvironment, the buttons along the bottom of the main UI change
depending upon the current context of the application. All the context configurations are
contained within the <Application_Context> element.
The <Application_Context> element contains the following elements and attributes:
 <Context> - This element defines the set of configurations for one context.
id - This attribute defines the identifier used to refer to the context configuration.
– <ActionKey> - This element defines one button in the context.
menukey - This attribute contains the name of the MenuKey that is displayed
(see “Menu Key Configuration”).
sortOrder - This attribute determines the order in which the button appears
along the bottom of the screen.

Pop-up Menu Configuration

The Pop-up Menu Configuration section configures the buttons that are displayed on
Oracle Retail Xenvironment Pop-up windows. All the Pop-up Menu Configurations are
contained within the <PopupMenus> element.
The <PopupMenus> element contains the following elements and attributes:
 <PopupMenu> - This element defines the set of configurations for one pop-up
window.
name - This attributes defines the name used to refer to the pop-up window.
osType - This attribute determines the operating system on which the pop-up
window is displayed. A value of ALL indicates that the pop-up window is available
on all operating systems.
– <PopupMenuKey> - This element defines one button on the pop-up window.
name - This attribute contains the name of the MenuKey that is(see “Menu Key
Configuration”).
sortOrder - This attribute determines the order in which the button appears in
the pop-up window.
osType - This attribute determines the operating system on which the key is
displayed. A value of ALL indicates that the button is available on all operating
systems.
Menu Key Configuration

The Menu Key Configuration section configures the buttons and hotkeys that are
referenced in the Context Configuration, Hotkey Registration, and Pop-up Menu
Configuration sections. All the Menu Key Configurations are contained within the
<MenuKeys> element.
The <MenuKeys> element contains the following elements and attributes:
 <MenuKey> - This element defines one menu key in Oracle Retail Xenvironment.
name - This attribute defines the name used to refer to the Menu Key.
keyFunction - This attribute determines the translation key displayed on the Menu
Key.
keyLabel - This attribute defines the translation key displayed on the Menu Key or
Menu Option (if on a menu).
style - This attributes defines either the style of the button (if appsMenu is not set,
or is set to “false”) or the image file used as an icon (if appsMenu is set to “true”).
keyEventCode - This attribute defines the Java KeyEvent that selects the Menu Key.
keyMaskCTRL - If this attribute is set to “true”, it indicates that the [CTRL] key must
be pressed—along with the keyEventCode—to activate the Menu Key (used only for
hotkeys). This can be used in conjunction with the keyMaskALT and keyMaskSHIFT
attributes to create multiple-key hotkey combinations.
32
keyMaskALT - If this attribute is set to “true”, it indicates that the [ALT] key must
be pressed—along with the keyEventCode—to activate the Menu Key (used only
for hotkeys). This can be used in conjunction with the keyMaskCTRL and
keyMaskSHIFT attributes to create multiple-key hotkey combinations.
keyMaskSHIFT - If this attribute is set to “true”, it indicates that the [SHIFT] key
must be pressed—along with the keyEventCode—to activate the Menu Key (used
only for hotkeys). This can be used in conjunction with the keyMaskCTRL and
keyMaskALT attributes to create multiple-key hotkey combinations.
PromptConfirm - This attribute indicates whether a confirmation prompt is

displayed after selecting the Menu Key. If this attribute is set to “true”, Oracle Retail
Xenvironment will display a confirmation prompt ([DEFAULT] = “false”).
PromptConfirmMessageKey - This attribute defines the translation key displayed
in the confirmation prompt after selecting the Menu Key. This attribute is only valid
if PromptConfirm is set to “true”.
PromptPassword - This attribute indicates whether a password prompt is

displayed after selecting the Menu Key and, if PromptConfirm is set to “true”, after
the confirmation prompt. If this attribute is set to “true”, Oracle Retail Xenvironment
will prompt for a password ([DEFAULT] = “false”).
ActionCommand - This attribute determines the type of action that is run when the
Menu Key is selected. This attribute has the following possible values:
– No_Action - No action occurs.
– ALERT_DELETE - Deletes the alert currently in focus from the alert list.
– ALERT_NEXT - Moves to the next alert in the list.
– ALERT_PREVIOUS - Moves to the previous alert in the list.
– ALERT_VIEW - Opens the alert currently in focus.
– DIALOG_ACKNOWLEDGE - Sends an acknowledgement message to a pop-up
dialog window.
– DIALOG_CANCEL - Sends a cancel message to a pop-up dialog window.
– DIALOG_CONFIRM - Sends a confirmation message to a pop-up dialog window.
– DIALOG_DECLINE - Sends a decline message to a pop-up dialog window.
– EXECUTE - An executable file runs.
– HOT_KEY - Performs a hotkey operation.
– IPC_ATOM - Runs an Oracle Retail Xenvironment atom or chain without
arguments.
– IPC_RUN - Opens a dialog window that prompts the user to enter the name of an
atom or chain for Oracle Retail Xenvironment to run.
– PLUGIN_ACTION - A plugin runs.
– POPUP_MENU - A popup menu opens.
– SYSTEM_CONTEXT - Move Oracle Retail Xenvironment to a different context.
– VK_<keyname> - The specified KeyEvent is sent to Oracle Retail Xenvironment.
For example, VK_2 sends a KeyEvent.VK_2 to the system, VK_A sends a

KeyEvent.VK_A to the system, and VK_SPACE sends a KeyEvent.VK_SPACE

to the system.
– INFO_PRIOR - Moves to the previous information message.
– INFO_NEXT - Moves to the next information message.
Run - This attribute determines the action performed by the Menu Key. The action is
of the type defined by the ActionCommand attribute. For example, if
ActionCommand=”IPC_ATOM”, the Run attribute contains the name of the atom or
chain that is run. If ActionCommand=”EXECUTE”, Run contains the executable file
that is run.
Run.Arguments - This attribute defines the list of arguments that are sent to the
command defined by the Run attribute.
Wait.Millis - This attribute defines the number of milliseconds after running the
command that Oracle Retail Xenvironment will display the “Please Wait” message.
osType - This attribute determines the operating system in which the Menu Key is
available. A value of ALL indicates that the Menu Key is available on all operating
systems.
touchScreenOnly - This attribute determines whether the Menu Key is only

displayed on touchscreen systems, or if the Menu Key is displayed on all systems.
This attribute has the following possible values:
– true - The Menu Key is only available on touchscreen systems.
– false - [DEFAULT] The Menu Key is available on all systems.
appsMenu - This attribute determines whether the Menu Key is displayed in the
Apps area (see “Apps”) or on the row of buttons (see “Menu Buttons”). This attribute
has the following possible values:
– true - The Menu Key is displayed in the Apps area.
– false - [DEFAULT] The Menu Key is displayed as a button.
The Menu Key element includes the following sub-element:
<Role> - Determines a role that has permission to use the Menu Key.
id - The ID for the Role that has permission to use the Menu Key.
34
Example
<Menu xmlns="http://oracle.com/retail/xstore/config/xenv"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://oracle.com/retail/xstore/config/xenv
../../../xenv-objects/templates/schemas/XenvMenuConfig.xsd"
Debug.Outline="false">
<Application_Context>
<Context id="MAIN_CONTEXT">
<ActionKey menukey="VK_ESCAPE" sortOrder="1" />
<ActionKey menukey="VK_F1_BLANK" sortOrder="2" />
<ActionKey menukey="VK_F2" sortOrder="3" />
<ActionKey menukey="VK_F3" sortOrder="4" />
...
</Context>
...
</Application_Context>
<PopupMenus>
<PopupMenu name="SupportMenu">
<PopupMenuKey name="SUPPORT_MENU_STOP_XSTORE"
sortOrder="1"/>
<PopupMenuKey name="SYSTEMMENULOGOFF" sortOrder="2" />
<PopupMenuKey name="SYSTEMMENUSHUTDOWN" sortOrder="3" />
<PopupMenuKey name="SYSTEMMENUREBOOT" sortOrder="4" />
</PopupMenu>
...
</PopupMenus>
<MenuKeys>
<MenuKey name="SUPPORT_MENU_STOP_XSTORE" keyFunction="_blank"
keyLabel="_supportMenuStopXstore"
keyEventCode="KeyEvent.VK_UNDEFINED" keyMaskALT="true"
PromptConfirm="true"
PromptConfirmMessageKey="_confirmRunShutdownXstore"
PromptPassword="true" ActionCommand="IPC_ATOM"
Run="shutdown-xstore" Wait.Millis="1800">
<Role id="EVERYONE" />
</MenuKey>
<MenuKey name="APPS_SYSTEM_INFO" ActionCommand="SYSTEM_INFO"
keyLabel="_SystemInfoTouch" keyFunction="_blank"
PromptPassword="true" PromptConfirmMessageKey="_blank"
KeyEventCode="KeyEvent.VK_UNDEFINED" appsMenu="true">
<Role id="EVERYONE"/>
</MenuKey>
...
</MenuKeys>
</Menu>
XenvPromptConfig.xml
The XenvPromptConfig.xml file defines the UI Prompt windows. Each prompt has
the following elements:
 <Prompt> - This element delineates one Prompt configuration.
– <key> - This element defines the key used to identify the Prompt.

– <type> - This element determines the style of the Prompt window. This element
has the following possible values:
– ANNOUNCE_FOCUSBAR - Green window
– INFORMATION_FOCUSBAR - Yellow window
– ALERT_FOCUSBAR - Red window
– PROMPT_FOCUSBAR - Default-color window
– PASSWORD_PROMPT_FOCUSBAR - Default-color window, information
entered will not be displayed in the prompt
– <title> - Contains the translation key displayed in the window’s title.
– <majorMsgKey> - Contains the translation key used for the Prompt’s message.
Example
<PromptConfig>
<Prompts>
<Prompt>
<key>BLANK</key>
<type>ANNOUNCE_FOCUSBAR</type>
<title>_focusbarTitle</title>
<majorMsgKey>_blank</majorMsgKey>
</Prompt>
...
</Prompts>
</PromptConfig>
36
xenv-ui-dialog-config.properties
The xenv-ui-dialog-config.properties file defines window and button
configurations Oracle Retail Xenvironment dialog windows. For example, the xenv-ui-
dialog-config.properties configures the Cancel, Continue, Yes, and No buttons:
Figure 4-1: Select Menu Option
Figure 4-2: Confirmation
Window Size and Location

The size of the dialog window is determined by the following configurations:
Dialog.Width=<window_width>
Dialog.Height=<window_height>

where the setting

 Dialog.Width determines the width of the window and <window_width> is
replaced by the width of the window in pixels.
 Dialog.Height determines the height of the window and <window_height> is
replaced by the height of the window in pixels.
XenvFontConfig.xml
The XenvFontConfig.xml file configures Font styles for use by the Oracle Retail
Xenvironment UI. Each
Font style has the following element and attributes:
 <Font> - This element delineates one Font style configuration. This element has the
following attributes:
– name - This attribute defines the name used by the Oracle Retail Xenvironment
UI to refer to this Font style.
– family - This attribute defines the font family used by the Font style. This
attribute has the following possible configuration values:
o “Arial Unicode MS” - [DEFAULT] The Arial Unicode font
embedded in the application, which enables support for localization
into all languages.
o “SansSerif” - The standard sans serif font used by the system.
o “Serif” - The standard serif font used by the system.
o “Monospaced” - The standard monospaced font used by the
system.
o “<font_name>” - The name of a font installed on the local system.
 style - The type of font in the Font style. This attribute has the following possible
configuration values:
– “Bold” - Bold font.
– “Italic” - Italic font.
– “BoldItalic” - Bolded and italicized font.
– “Normal” - [DEFAULT] Normal font (neither bolded nor italicized).
 size - The point size of the font.
Example
<Fonts xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="FontConfig.xsd">
<Font name="XENV_SMALL" family="SansSerif" style="Bold"
size="12" />
<Font name="XENV_PLUGIN_UTILS" family="Monospaced"
style="Normal"
size="12" />
<Font name="XENV_VERSION_DIALOG_TITLE" family="Arial"
size="20" />
...
</Fonts>
38
xenv-ui-probers_{OS}.properties
These files are used to retrieve information displayed in the System Information screen.
For more information about these configurations, or if you need help changing these
files, speak with your Oracle product representative.

5
Oracle Retail Xenvironment Processing
Overview
This chapter describes how Oracle Retail Xenvironment processes files during regular
operation, and during daily maintenance.
About this Chapter

 “Log Files” describes the xenvironment.log file and the type of information it
contains.
 “Trickle Polling” describes the trickle polling process and its actions.
 “Deployment” describes the deployment process and the actions it performs.
 “The Daily Maintenance Process” provides a general overview of the actions
performed during daily maintenance.
 “Manual Closing Options” explains how to perform closing tasks manually, rather
than allowing the automated process to perform them.
Log Files
Oracle Retail Xenvironment generates the following log files:
 xenvironment.log
 xenvironment-ipc.log
contains IPC related messages within the engine process
 xenvironment-registration.log
contains registration related messages
 xenvironment-ui.log
 xenvironment-ui-ipc.log
contains IPC related messages within the UI process
All log entries show their logging levels. This helps users determine the logging level that
should be configured for Oracle Retail Xenvironment.
xenvironment.log
The main log file is xenvironment.log. Very little happens in Oracle Retail
Xenvironment without some part of it being logged here.
To locate an event in xenvironment.log, first navigate to the approximate date/time
of the event that you want to find. After you find the date/time, search for the name of
the atom in question. When an atom is executed, one of several possible action codes will
be generated and shown in the log.
To distinguish the hierarchy of atoms and chains within parent chains, the following
formats are used:
 ' ' (space) indicates the start of an action
 '+' (plus sign) indicates the successful completion of an action

 '!' (exclamation mark) indicates the completion of an action in error status

 '>' (greater than sign) indicates the completion of an action with a notable status, for
example, used for warning, bypass, or terminate success.
 SUCCESS:
For example:
@127.0.0.1]-4 INFO 2018-09-26 14:04:14,422
|+ConfigUpdate(ATOM) --> SUCCESS: Config update was
successful. :: oracle.retail.xenvironment.action.Action
[IPC[/127.0.0.1]-4]
 BYPASS:
For example:
@ startup INFO 2018-09-26 14:03:00,675 |>>>startup-
lead.RUN_INVASIVE_UPDATES_AFTER_XENV_UPGRADE.bypass-if-env-
upgrade-applied(ATOM) --> BYPASS: No files found matching
^env_upgrade_applied\.xst$ ::
oracle.retail.xenvironment.action.Action [startup]
Note: The BYPASS return value indicates that the atom

completed without an error, but if this atom is called from
within a chain, the chain will end. If the chain calling the
atom is a subchain of another chain, the subchain will end,
but the calling chain will continue processing.
ERROR:
For example:
@ exec-3 ERROR 2018-09-26 14:15:37,517
|!!START_XSTORE_SCO_APP.start-xstore-sco(ATOM) --> ERROR:
Error: 2 (The system cannot find the file specified.)
[exception=java.io.IOException: Error: 2 (The system cannot
find the file specified.)] ::
oracle.retail.xenvironment.action.Action [exec-3]
 WARNING:
For example:
@ exec-2 WARN 2018-09-26 14:13:47,622
|>>supportcapture.supportcap-wait-env-thread-dump(ATOM) -->
WARNING: Timeout expired. ::
oracle.retail.xenvironment.action.Action [exec-2]
Note: If a non-existent atom is listed in a chain, an error will

be logged in the file xenvironment.log and execution of
the chain will abort.
The numbers of chains and atoms defined in the
configuration are logged here for informational purposes.
Trickle Polling
Trickle polling can be used to upload files from the system and download update files
during the day. Trickle uploads and downloads are run on a schedule set in each
register’s scheduled task configuration.
42
Uploads
When enabled in both Oracle Retail Xenvironment and Oracle Retail Xstore Point of
Service, the system can generate and upload trickle data using third-party polling
solutions. Two chains are responsible for managing trickle uploads:
 gather-and-upload-trickle-files: This chain runs on all registers. It packages the
trickle files and uploads them to the lead register. This chain runs the following
atoms:
– move-hh-trickle-poslog-to-xst-trickle-dir: Moves POS Log from the handheld to
the trickle directory for Oracle Retail Xstore Point of Service.
– move-hh-trickle-relate-customer-to-xst-trickle-dir: Moves the customer
information from the handheld to the Oracle Retail Xstore Point-of-Service trickle
directory.
– move-hh-trickle-relate-cardcust-to-xst-trickle-dir: Moves card-related customer
information from the handheld to the Oracle Retail Xenvironment trickle
directory.
– zip-trickle-files-with-timestamp-and-hostname: Zips the files in the trickle
directory ([DEFAULT] /xstore/log/trickle) into one package file that
includes a timestamp and the system hostname in the filename.
– upload-trickle-files-to-lead: Uploads the trickle package to the lead register. The
trickle package is moved to the directory /environment/wwwroot/trickle,
from which it is uploaded. Then, when the file has been successfully uploaded, it
is moved to an archive directory.
– cleanup-old-trickle-archives: Deletes old trickle archives.
 trickle-polling: This chain runs only on the lead. It combines the trickle packages
uploaded from the nonleads and runs a trickle polling session to upload the file to
the home office. This chain runs the following atoms:
– unzip-uploaded-trickle-packages: This atom unzips the uploaded trickle
packages in the /environment/wwwroot/trickle directory into the
/environment/poll/trickle directory.
– create-final-trickle-polling-package: This atom combines all the unzipped files
in /environment/poll/trickle, with hostname and timestamp, into one
package file, then deletes all the package files uploaded from the nonlead
registers.
– poll-trickle: This atom calls, depending upon the operating system, the
poll.bat (Windows) or poll.sh (Linux) script with a parameter of
"TRICKLE", which runs all the processes in the TRICKLE section of the script.
This file is created by the Tech Services group for each customer.
– process-pre48-trickle-downloads: This atom processes any trickle downloads
that came from a version of Oracle Retail Xenvironment earlier than 4.8.
– unzip-dataloader-files: This atom unzips downloaded DataLoader files.
– execute-dataloader-trickle: This atom processes the unzipped DataLoader
updates.
Downloads
Oracle Retail Xenvironment is responsible for downloading the files on a schedule set in
the lead register’s scheduled task configuration and processing the updates in those files.

Deployment
The deployment process performs updates to the system by downloading and processing
updates from Xcenter (a part of Oracle Retail Xstore Office).
There are two times when updates can be deployed:
 Immediately - These configurations are deployed immediately upon being received
by Oracle Retail Xenvironment.
 Forced - Forced deployments run all deployments, both immediate and store-close,
that need to be run by Oracle Retail Xenvironment. A forced deployment runs during
the daily maintenance procedure initiated by an Oracle Retail Xenvironment
upgrade. See “The Daily Maintenance Process: Atom by Atom” for more
information.
 Daily Maintenance - These configurations are deployed by the daily maintenance
procedure, which is detailed in “The Daily Maintenance Process”. Software updates,
cipher keys, debit bin files, DataLoader files, and configurator changes can only be
deployed during daily maintenance. However, they can be uploaded immediately,
for processing at daily maintenance.
Note: Any immediate updates that have not yet been

applied will be applied during the daily maintenance
process.
The deployment process performs the following series of steps to update the system:
 Changes are initiated using Oracle Retail Xstore Office.
 At regular intervals (set by configuration), Oracle Retail Xstore Point of Service
checks whether there are any updates available for deployment.
 If updates are available Oracle Retail Xstore Office sends a deployment manifest to
Oracle Retail Xstore Point of Service.
 Oracle Retail Xstore Point of Service forwards the deployment manifest to Oracle
Retail Xenvironment for processing.
 If the Oracle Retail Xenvironment system is not the lead register, the non-lead
register sends the manifest file to the lead register.
 On the lead register, Oracle Retail Xenvironment checks the deployment manifest.
 Any updates that are to be applied and/or downloaded immediately are retrieved
from the Apache HTTP server where they are stored. The files are saved in the
download staging directory.
 <environment_directory>\deployment\download_staging\immediat
e for immediate deployments.
 <environment_directory>\deployment\download_staging\close for
daily maintenance deployments.
 Any updates that are to be downloaded and applied at daily maintenance are
scheduled for download from the Apache HTTP server during the daily
maintenance.
 For immediate updates, the updates are applied as soon as they are received.
Note: In case of emergency, immediate updates can be made

to underlying applications. The filenames for these updates
must have the format:
xstore-immediate-*.jar
44
 For daily maintenance updates, the daily maintenance applies the updates. See “The
Daily Maintenance Process” for a description of the process.
Background Update
In some cases, updates to Xenvironment, Xstore POS, Xstore POS Mobile, or DataLoader
must be performed outside of a standard register daily maintenance. In these cases,
background updates can be performed. These background updates perform the
following actions:
1. Xenvironment receives an update.
2. Xenvironment stages the update files across all registers.
3. Xenvironment notifies Xstore POS to start prompting users to perform the update.
 If the user selects Yes, the required period start immediately.
 If the user selects No, the user is given a grace period.
At the end of the grace period, the required period starts.
4. During the required period, in-process transactions can be completed, but no new
transactions may be started.
5. Once all transactions have been completed on the register, or the required period
ends, Xenvironment will apply the update.
The Daily Maintenance Process

One of the primary tasks of Oracle Retail Xenvironment is the daily maintenance process.
This process is initiated by a request that comes from Oracle Retail Xstore Point of
Service. Daily maintenance includes the following sequence of tasks:
1. Packaging of Upload files (creating the file pospoll.zip).
See “Packaging of Upload Files (Creating pospoll.zip)”.
2. Nightly end-of-day backup of the database.
3. Assist with Polling procedures.
4. Processing of Download files.
5. Processing Java updates.
6. Processing of Oracle Retail Xenvironment updates.
7. Processing of Application updates.
See “Application Update Processing Example”.
8. Processing of configuration updates from Oracle Retail Xstore Office.
9. If enabled, run DataPurger (this action is disabled in the default configuration).
10. A second database backup, post-download processing.
11. Distributing the Lead Register's database so that it may be restored on the non-lead
registers.
12. A nightly reboot of the registers.
Packaging of Upload Files (Creating pospoll.zip)

During daily maintenance, Oracle Retail Xenvironment packages several log files from all
registers and compiles them into one main file (pospoll.zip) that can be picked up by
the polling server.
The following types of files are packaged in the pospoll.zip file:
 Oracle Retail Xstore Point-of-Service transaction logs

 Oracle Retail Xstore Point-of-Service application logs

 Relate logs
 Oracle Retail Xenvironment application logs
 A comma-separated file (missing_registers.csv) listing any non-lead registers from
which the lead register was unable to retrieve data.
File Archive Updates

Oracle Retail Xenvironment can make updates using .tar.gz file archives. Through these
archives, files can be replaced, and updates can be made using shell scripts/batch files
and executable files.
The file archive is processed in the following order. For an explanation of each step, see
the sections below:
1. The script /scripts/preupd.[bat/sh] runs.
2. This file is located in the /scripts directory (see “scripts”).
3. The specified directories are backed up (see “update.properties”).
4. The directories are archived in the file
<environment_root>/backup/backup.tar.gz. The existing backup.tar.gz
file is moved to the file backup.tar.gz.001. The file backup.tar.gz.001 is
renamed to backup.tar.gz.002, etc. By default, five (5) backup files are kept.
5. The contents of the /extract directory are extracted to the specified directory (see
“update.properties”).
6. The updates to properties in the /configupdate directory are applied.
7. The script /scripts/postupd.[bat/sh] runs.
8. This file is located in the /scripts directory (see “scripts”).
Archive Structure
The archive within the .tar.gz file has the following structure, where / is the root
directory of the .tar.gz archive:
 /update.properties - File containing configurations for the update. See (see
“update.properties” for a description of the settings within this file.
 /extract - A directory that is extracted to the directory specified in the
update.properties file (see “update.properties”).
 /config - Adds or updates properties in the .properties file in the override directory
for the directory specified in the update.properties file.
For example, if the directory in the .tar.gz archive is
/configupdate/environment/config/actions.properties, the file
<environment_root>/cust_config/version1/actions.properties will
be updated through this directory.
 /scripts - Batch files and shell scripts that are run by the update process.
 /scripts/preupd.[bat|sh] - Runs before any other update is performed.
The .bat extension is used on Windows systems. The .sh extension is used on
Linux systems.
/scripts/postupd.[bat|sh] - Runs after all other updates are performed. The
.bat extension is used on Windows systems. The .sh extension is used on Linux
systems.
46
update.properties
This file contains the following configurations:
 dir.root - The directory to which the files will be extracted.
[DEFAULT] - c:\ on Windows, and /opt/ on Linux.
 dir.list.backup - Space-separated list of directories that will be backed up prior
the application of the update.
[DEFAULT] - The Oracle Retail Xenvironment and Oracle Retail Xstore Point-of-
Service folders.
Example
The following update.properties file will unpack the archive to the directory c:\temp and
will create backups of the c:\temp\env and c:\temp\env_install directories.
dir.root=c:\temp
dir.list.backup=c:\temp\env c:\temp\env_install
scripts
In the file archive, the /scripts directory contains the file preupd.bat (in Windows)
or predupd.sh (in Linux), and the file postupd.bat (in Windows) or postupd.sh (in
Linux), and all the appendant files used by those scripts.
 The script preupd.[bat/sh] runs before any other backup step, including the
directory backup step.
 The script postupd.[bat/sh] runs after all other update steps.
Application Update Processing Example

A highlight of Oracle Retail Xenvironment is its ability to process application updates.
This is done within a framework that employs a web server and the use of RSS feeds. The
primary purpose of this framework is to upgrade Oracle Retail Xstore Point of Service,
although it can also be used to upgrade other software packages by applying operating
system-specific updates. This update process runs every night as part of daily
maintenance.
Note: To remove a pending update and prevent it from

running, remove the file from the update directory prior to
daily maintenance.
For example if you remove the file
c:\environment\wwwroot\updates\xstore\xstore
-update.jar will prevent the current Oracle Retail Xstore
Point-of-Service update from being performed.
Application updates are delivered in Java-based .jar files. The .jar files updates are
built with Ant tasks (Ant is a Java project from Apache).
Oracle Retail Xenvironment can also be configured to include digital signature validation
files (.sig files) with the application updates. These files contain signed certificates used to
determine whether the update files are intended for the customer, and prevent malicious
software from being introduced on the system through update processing.
The following steps describe how the update is processed through the Oracle Retail
Xenvironment during daily maintenance. In the following example, the file xstore-
update.jar updates the Oracle Retail Xenvironment application. A detailed technical

description of the update process during daily maintenance is provided in Appendix A:

“The Daily Maintenance Process: Atom by Atom”.
1. During the polling session, the files xstore-update.jar and xstore-
update.jar.sig are downloaded by the Lead Register and placed in the update
directory (c:\updates\inbox\xstore in Windows, /opt/updates in
Linux).
2. A flag file named update.ok is created by the polling session. This indicates to the
Lead Register that the download of the update was completed. Processing will not
proceed without this file being present.
3. If the file update.ok is not present, the update was not downloaded successfully.
Therefore, the update will not be processed.
4. If validation is enabled, Oracle Retail Xenvironment performs validation tests once
the file is fully and successfully downloaded; Oracle Retail Xenvironment checks the
xstore-update.jar file against the digital signature in the file xstore-
update.jar.sig file.
5. During daily maintenance, the update is copied to the update upload directory
(<root_directory>/wwwroot/updates/xstore) to make it available to the
non-lead registers.
6. The RSS feed file xstore-rss.xml is updated with information about the new
update.
7. The Lead Register sends a message to the non-lead registers requesting that they
“check for and apply” new updates.
8. Upon receiving the message, the non-lead registers download the file xstore-
update.jar and place it in the update directory.
9. A command such as the following example executes the update:
java -jar xstore-update.jar
10. After each non-lead register successfully executes the update, the register deletes the
file xstore-update.jar from the update directory, and the file xstore-
update.sig from the certification directory.
11. After the Lead Register has completed processing the update, it sends out inquiry
messages to all of the other registers asking if they have completed the update
process.
12. When each non-lead register successfully executes the update, the register sends a
message acknowledging that the update has been completed.
13. The Lead Register continues with the rest of the daily maintenance procedures.
A copy of the original update is kept on the Lead Register in the update upload
directory. If a register was not online at the time of daily maintenance, that register
can download and process the update during the next daily maintenance.
Manual Closing Options

Normally, application update files are accessed from a server, processed, and distributed
to the individual registers during daily maintenance. In a similar way, cipher files are
usually handled automatically during daily maintenance. However, both application
updates and cipher files may also be manually placed in the appropriate “updates”
directory, and they will be picked up and processed during daily maintenance.
Processing of Application Updates

1. Copy the update .jar file(s) to the appropriate directory.
48
2. If signature validation is enabled, copy the signature .sig file(s) to the appropriate
directory.
3. Create a file named update.ok and place it into the appropriate directory. The file
is a simple text file that may be created with any text editor such as Notepad.
Note: The file update.ok can be empty. Oracle Retail

Xenvironment only looks to see if the file exists—it does not
open the file or read its contents.
4. Close the system through Oracle Retail Xstore Point of Service, and wait for the daily
maintenance process to complete. Update processing occurs late in the process, so it
might be a while before the updates are processed.
5. Once the daily maintenance process is complete, validate that the update was
processed:
6. Check to ensure that there are no files in the update directories.
7. Look for the update and signature file (if applicable) in the directory
<root_directory>/wwwroot/updates/<update_type>, where
<update_type> is the type of update.
8. Check to ensure that no registers have files in the directory
<update_directory>/<update_type>, where <update_type> is the type of
update.
Processing of Cipher Files

1. Copy all of the cipher files to the directory <update_directory>\inbox\cipher.
2. Create a file named update.ok and place it into the directory
<update_directory>/inbox/cipher. The file is a simple text file that may be
created with any text editor such as Notepad.
Note: The file files.ok can be empty. Oracle Retail

3. Close the system through Oracle Retail Xenvironment, and wait for the close to
complete. Cipher file propagation occurs late in daily maintenance, so it might be a
while before the files are processed.
4. Once the daily maintenance is complete, validate that the cipher files were processed:
a. Check to ensure that the new cipher files are found in the directory
<xstore_root>/res/keys on all systems.
b. Check to ensure that no cipher files are in the directory
<update_directory>/inbox/cipher.
c. Check to ensure that the cipher files are in the directory
<root_directory>/wwwroot/cipher.
Processing of debit.txt File

1. Copy the debit.txt file to the directory <update_directory>\inbox\debitbin.
2. Create a file named update.ok and place it into the directory
<update_directory>/inbox/debitbin. The file is a simple text file that may be
created with any text editor such as Notepad.

Note: The file files.ok can be empty. Oracle Retail

3. Close the system through Oracle Retail Xenvironment, and wait for the daily
maintenance to complete. Debit file propagation occurs late in the daily maintenance
process, so it might be a while before the files are processed.
4. Once the daily maintenance process is complete, validate that the debit.txt file
was processed:
a. Check to ensure that the new debit.txt file is found in the directory
<xstore_root>/res/keys on all systems.
b. Check to ensure that no debit.txt file is in the directory
<update_directory>/inbox/debitbin.
c. Check to ensure that the debit.txt file is in the directory
<root_directory>/wwwroot/debitbin.
50
6
Using Oracle Retail Xenvironment
Overview
This chapter describes the use of Oracle Retail Xenvironment. This includes information
about how to start Oracle Retail Xenvironment and how to use the graphical user
interface (GUI) that provides access to the Oracle Retail Xstore Point-of-Service
application and Windows functions.
Important: This chapter should be used only by customers

About this Chapter

 “Starting Oracle Retail Xenvironment” describes how Oracle Retail Xenvironment is
started and what you will see once it starts.
 “Graphical User Interface (GUI)” describes the Oracle Retail Xenvironment GUI and
how to use it.
Starting Oracle Retail Xenvironment

Oracle Retail Xenvironment is started by running the batch file start_eng.bat
(Windows), start_eng.vbs (Windows) , or start_eng.sh (Linux) in the Oracle
Retail Xenvironment installation directory.
When Oracle Retail Xenvironment is started, its graphical user interface is launched.
Oracle Retail Xenvironment can also be run as the system's shell, which secures the
desktop by making it inaccessible.

Graphical User Interface (GUI)

Oracle Retail Xenvironment comes with a GUI that is similar to Oracle Retail Xstore Point
of Service. Actions are performed through hotkey combinations or by using buttons near
the bottom of the screen. Information from the point-of-sale (POS) application is
displayed in the POS Status window on the right side of the screen. System information
is displayed in the status bar at the bottom of the screen. Additional information is
shown in other areas of the screen.
Figure 6-1: Graphical User Interface
On-Screen Keyboard
To provide touchscreen systems with the functionality available in a desktop system,
Oracle Retail Xenvironment can be used to launch the operating system’s on-screen
keyboard that can perform all the actions of a physical keyboard.
Figure 6-2: On-Screen Keyboard on Windows Operating System

This on-screen keyboard can be used to access hotkey functions, switch between
programs using [Alt]+[Tab] commands, or enter data into fields.
Features
 The on-screen keyboard always stays on top of all other windows and applications.
 To use the [Shift], [Ctrl], or [Alt] keys, touch that key on the on-screen keyboard,
then any other keys to be used with them.
52
For example, to use [Alt]+[Tab] to move through application, touch [Alt], then touch
[Tab] as many times as necessary to change to the proper application.
 When entering data, the on-screen keyboard will provide auto-complete options
along the top of the keyboard, based on the characters entered. To select an auto-
complete option, touch it.
Figure 6-3: On-Screen Keyboard – Auto-Complete Options
In-Window Keyboard
The in-window keyboard is different than the on-screen keyboard described above. The
in- window keyboard is only used to enter data into an Oracle Retail Xenvironment
window on a touchscreen system. This in-window keyboard can be used to enter a
password into a password prompt, or enter the name of a chain or atom into the Run a
Chain or Atom prompt.
Figure 6-4: Touchscreen Keyboard

This keyboard cannot be used to enter hotkey combinations, nor can [Alt]+[Tab]
commands move control from Oracle Retail Xstore Point of Service to Oracle Retail
Xenvironment.

Message Screen
The message screen in the upper left portion of the GUI displays messages for Oracle
Retail Xenvironment. These messages may be informational or they may indicate
problems. The message screen shows both the message and a count of the total number
of messages received by Oracle Retail Xenvironment. These messages are generally
related to polling or the daily maintenance process.
Figure 6-5: Message Screen – Clear
Figure 6-6: Message Screen - Error

If there is more than one message:
 Click the Previous button or press the [A] key to view the previous message.
 Click the Next button or press the [F] key to view the previous message.
View Message Details

To clear a message from the message screen, click the View Note button, or press the [S]
key. The details of the message are displayed in the alert detail area (see “Alert Detail”).
Clear Message
To clear a message from the message screen, do the following:
1. Click the Delete Note button, or press the [D] key.
2. Oracle Retail Xenvironment asks for your user name and password (see “Password
Protected Functions”).
54
3. Enter your user name and password, then click the Continue button, or press the
[Enter] key. This is the user name and password you use to log into Oracle Retail
Xstore Point of Service.
4. Oracle Retail Xenvironment asks for your username and password.
5. Enter your username and password, then click the Continue button, or press the
[Enter] key.
6. The message is cleared from Oracle Retail Xenvironment and the marker file for the
message is deleted from the system.
POS Status
The POS Status screen provides information describing the current state of the POS
system. The POS Status screen, located on the right side of the GUI, includes five
different status areas, each of which shows different information.
Figure 6-7: POS Status Screen

To see the information provided in the different status areas, click on or touch the title
bar for the status area, or use the [Page Up] and [Page Down] keys to navigate through
the status areas, or use the number keys to select a specific status area.
Register Status
The Register Status area shows the current status of the registers in the store.
Figure 6-8: Register Status Area

Process Steps
The Process Steps area is used during the daily maintenance and disaster recovery. It
displays the status of each step as it is performed.
Figure 6-9: Process Steps Area
Alert Detail
The Alert Detail area displays alerts that require attention. These alerts are found
through error and warning marker files (see “Subdirectory: <root_directory>\marker,
Chapter 3“for more information about marker files).
Figure 6-10: Alert Detail Area
Apps
The Apps area provides access to plugins and applications that can be accessed and used
through Oracle Retail Xenvironment. See “Menu Key Configuration” for information
about configuring this area.
56
Click an application or plugin to run it from the Apps area.
Figure 6-11: Apps Area
About
The About area contains the Copyright information and the general disclaimer.
Systems Support/Attention
The Systems Support/Attention screen, located in the lower left portion of the GUI,
displays Windows process navigation information. This screen provides the following
information:
 If Oracle Retail Xenvironment is currently in focus, the Systems Support screen
displays a message reminding the user how to return to Oracle Retail Xstore Point of
Service.
Figure 6-12: System Support – Activate Oracle Retail Xstore Point of Service

 If there is currently an error marker in the system, the System Support screen
displays a message alerting and notifying the user to review the error.
Figure 6-13: Systems Support - Error
Menu Buttons
Some of the operations and menus available in Oracle Retail Xenvironment are accessed
through the buttons located near the bottom of the screen. To access a menu or operation
through Oracle Retail Xenvironment button, press the button on a touchscreen monitor,
click the button using the mouse, or press the shortcut key indicated on the button.
Oracle Retail Xenvironment Buttons
The following buttons are typically found in Oracle Retail Xenvironment:

Table 6-1: Oracle Retail Xenvironment Buttons
Button Description
Support Opens the Support Menu.

See “Support Menu” for more information about
the Support Menu.
System Opens the System Menu.

See “System Menu” for more information about
the System.
Capture Logs Captures debugging and system information that
can be submitted to the help desk to assist in
troubleshooting.
See “Capture Logs” for more information.
This option requires password authentication. See
“Password Protected Functions”.
Start POS Starts the POS application (Oracle Retail Xstore
Point of Service).
Start Self Checkout Mode Starts the Self-Checkout mode of the Oracle Retail
Xstore Point-of-Service application that is running
on the local system.
Note: Only available, if you selected the Enable
Xstore Self-Checkout option during the
Xenvironment installation.
58
Status Bar
The status bar displays system information for the register running Oracle Retail
Xenvironment.
Figure 6-14: Status Bar
Table 6-2: Xenvironment Status Bar
Item Description
1 Notification Area/Process Status. After running an

atom or chain through the Oracle Retail
Xenvironment interface, the execution status of
the atom is displayed here. This can be an atom
run through a menu, or by running a chain or
atom manually (see ”Run a Chain or Atom”).
2 Register Role (that is Lead or Non-Lead).
3 Store name and store number.
The background color of this field indicates the
status of the store.
 Red background: Store is closed.
 Green background: Store is open.
4 The Register Number for the register. This is the
Register Number used in Oracle Retail Xstore
Point of Service.
The background color of this field indicates the
status of the register.
 Red background: Register is closed.
 Green background: Register is open.
5 Current system date used by the computer itself.
Note that this is not the business date used by
Oracle Retail Xstore Point of Service.
6 Current system time.

Support Menu
The Support Menu contains menu items that affect Oracle Retail Xstore Point of Service
and the Windows system that runs Oracle Retail Xenvironment. To select a menu option,
click the option with a mouse or touch it on a touchscreen monitor, then click or touch
the Continue button.
Figure 6-15: Support Menu

The Support Menu has the following options:
 Stop Xstore - Stops the Oracle Retail Xstore Point-of-Service application that is
running on the local system.
 Stop Xstore Self Checkout - Stops the Self-Checkout mode of the Oracle Retail
Xstore Point-of-Service application that is running on the local system.
Note: Only available, if you selected the Enable Xstore Self

Checkout option during the Xenvironment installation.
 Logoff System - (Windows only) Exits the Windows session for the currently logged-
in user and returns to the Windows login screen. Note that it does not shut down or
reboot the system.
 Reboot System - Reboots the system.
 Shutdown System - Shuts down the system entirely.
Note: For the Reboot System and Shutdown System

commands to work in Linux, the setuid bit on the
/sbin/shutdown command must be set. To do this, run
the following command as the root user:
chmod +s /sbin/shutdown
60
System Menu
The System Menu is used to interact with the operating system. Depending on your
system’s configuration, the System Menu might vary from the example below. To select a
menu option, click the option with a mouse or touch it on a touchscreen monitor, then
click or touch the Continue button.
Figure 6-16: System Menu

The System Menu has the following options:
 Explorer - (Windows only) Opens Internet Explorer.
 Control Panel - (Windows only) Opens the Windows Control Panel.
 Print Manager - (Windows only) Opens the Windows Print Manager.
 Management Console - Opens the Windows Management Console.
 Command Prompt - Opens a command prompt (Windows) or console (Linux).
 Run Atom - Run a chain or atom (see “Run a Chain or Atom”). This option only
displayed on systems with touchscreen support enabled.
 Plugins - Run a Plugin (see “Plugins”). This option only displayed on systems with
touchscreen support enabled.
 Tech Support - Open the Tech Services menu (see “Tech Support Menu”). This
option only displayed on systems with touchscreen support enabled.
 Disaster Recovery - Perform the Disaster Recovery procedure (see “Disaster
Recovery”). This option only displayed on systems with touchscreen support
enabled.
 Version - Display Oracle Retail Xenvironment version information.
 System Information - Displays the System Information screen (Error! Reference
source not found. on page Error! Bookmark not defined.).
 Task List - Open the Task List window. (See “Task List”).
 Marker File List - Display a list of marker files currently in use by Oracle Retail
Xenvironment (see “View Marker Files”).
 On-Screen Keyboard - Opens the On-Screen Keyboard (see “On-Screen Keyboard”).

Capture Logs
The Capture Logs function captures debugging and system information that can be
submitted to the help desk to assist in troubleshooting.
The system creates a support capture tar.gz file in the
<root_directory>/wwwroot/support folder.
Note: You can invoke a remote support capture by entering

https://(hostname):9096/env?methodName=supportcaptur
e in any web browser. To authenticate, enter an Xstore POS
user name and password of a user with the
“SYSTEM_ADMIN”privilege.
To download the support capture file:

1. Open any web browser.
2. Navigate to https://(hostname):9097, for example,https://localhost:9097/.
Download Support Link
3. Click the support link.
Download Support Capture tar.gz File
Note: The link will not exist until at least one support
capture has been created.
4. Click on the link to download the support capture file.
Hotkeys
Many of the actions and functions available in Oracle Retail Xenvironment are accessed
through Hotkey combinations. These Hotkey combinations are certain keys or
combinations of keys pressed simultaneously.
Note: Use the On-Screen Keyboard to use hotkeys on a

touchscreen system. See “On-Screen Keyboard”.
Hotkeys are configured in:

XenvMenuConfig.xml file
(See “XenvMenuConfig.xml” for more information about this file).
62
Table 6-3: Hotkeys
Item Description
Oracle Retail Xenvironment Version Displays Oracle Retail Xenvironment version

ALT + V information.
Switch to Oracle Retail Xstore Point of If Oracle Retail Xstore Point of Service is running,
Service changes the focus to the Oracle Retail Xstore Point-
F8 of-Service application.
Run… Allows you to enter the name of a chain or atom to

CTRL + ALT + R run in Oracle Retail Xenvironment.
For more information about using this option, see
“Run a Chain or Atom”.
Tech Services Opens the Tech Services menu.
CTRL + ALT + X For more information about using this option, see
“Tech Support Menu”.
Command Prompt
Command Prompt Opens a command prompt.
ALT + F1 After pressing this hotkey combination, you are
prompted to confirm that you want to run a
Command Prompt.
If the Oracle Retail Xenvironment Engine
is not running1:  To continue, click or touch Yes, or press the [Y]
key.
CTRL + ALT + Shift + F11
 To return to the main screen without running
the Command Prompt, click or touch No, or
press the [N] key.
Print Screen Performs a Print Screen function.
CTRL + ALT + P This function creates an image of the Oracle Retail
Xenvironment GUI screen and saves it in a file in
JPEG format. Both the destination path and
filename are configurable
Default Destination:
<environment_root>log/xenv_ps.jpg
System Information Displays information about the system that is

CTRL + ALT + I running Oracle Retail Xenvironment.
For more information about this option, see “Error!
Reference source not found. ”.
Task List Opens the Task List window.
CTRL + ALT + T For more information about this option, see “Task
List”.
View Marker Files Opens the View Marker Files screen.
CTRL + ALT + L For more information about this option, see “View
Marker Files”.
Plugins Displays a list of available plugins for Oracle Retail
CTRL + ALT + Y Xenvironment.
For more information about this option, see
“Plugins ”.

Item Description
Disaster Recovery Allows access to Disaster Recovery functions.

ALT + R For more information about this option, see
“Disaster Recovery”.
1
If the Oracle Retail Xenvironment Engine is not running, or if the Oracle Retail
Xenvironment GUI cannot communicate with the Engine, most hotkeys will not work.
Because of this, an additional Command Prompt hotkey combination is available,
allowing service personnel to access the system and perform maintenance. For example,
this “backdoor” can be used if there is a misconfiguration, or if a certificate expires.
Password Protected Functions

Some of the hotkey functions may require you to enter a username and password. If
prompted for a username and password, do the following:
1. Enter your user name and password. These are the user name and password you use
to log into Oracle Retail Xstore Point of Service.
2. Either select Continue or press [Enter].
64
Plugins
Oracle Retail Xenvironment can run custom utilities that are specially designed for
Oracle Retail Xenvironment, but are not part of the base software. These utilities are
accessed through the Plugin menu.
Note: For more information about plugins, speak with your

Oracle representative.
To use a plugin, do the following:

1. Press the [CTRL]+[ALT]+[Y] hotkey combination, or select Plugins from the System
menu to open the plugin menu.
Note: To use some plugins on a touchscreen system, you

may need to use the On-Screen Keyboard. See “On-Screen
Keyboard”.
If the system prompts you for your user name and password, enter the password
information. See “Password Protected Functions” for more information.
1. The plugin menu opens. All the plugins available for Oracle Retail Xenvironment are
listed in this menu.
2. Click the name of the plugin to select it.
3. Click Continue or press [Enter].
4. The plugin runs.
Run a Chain or Atom

In Oracle Retail Xenvironment, users can manually run individual chains and atoms.
These chains and atoms are configured in the file action.properties.
See “actions.properties” for more information about this file.
See “Atoms and Chains” for more information about chains and atoms.
To run a chain or atom manually through the Oracle Retail Xenvironment interface, do
the following:
1. In the Oracle Retail Xenvironment interface, press [Ctrl]+[Alt]+[R].
2. A confirmation window opens.
3. Select the Yes button, or press [Y] to continue.
4. A username and password prompt window opens.
5. Enter the proper password, then select Continue or press [Enter] to continue.
6. A window opens prompting for the name of the chain or atom to run.
7. Enter the name of the chain or atom you are running, then select Continue or press
[Enter] to run the chain or atom.
8. The chain or atom runs. The Run Status of the atom or chain will be displayed in the
center panel in the Status Bar (see “Status Bar”).
Tech Support Menu

The Tech Support menu provides options that involve system restart. This menu is
opened by selecting the Tech Support option in the System menu.

Figure 6-17: Tech Support Menu

This menu provides the following options:
 Stop Xstore - Stops the Oracle Retail Xstore Point-of-Service on the local system.
 Logoff System – Logs out from the Windows. (only available on Windows)
 Shutdown System – Shuts down the operating system.
 Reboot System – Reboots the operating system.
Task List
Users can open a Task List window that displays all the processes running on the system.
This window can be used to bring other applications to the front, and allows users to kill
processes from within Oracle Retail Xenvironment.
To use the Task List, do the following:
1. Press the [CTRL]+[ALT]+[T] hotkey combination, or select Task List from the
System menu to open the Task List window.
2. A username and password prompt window opens.
3. Enter the proper password, then select Continue or press [Enter] to continue.
4. The Task List window opens.
66
Figure 6-18: Task List
The following information is displayed for each process:

 Window Title - Text in the title bar of the application window.
 Name - Name of the application file.
 PID - Process ID number of the process.
 Memory - Amount of memory taken up by the process.
 CPU Time - Amount of CPU time used by the process.
Note: The Name, PID, Memory, and CPU Time fields will be
blank for some processes. These processes are child
processes of other applications.
View Marker Files

Marker files are used by Oracle Retail Xenvironment to indicate the status of a currently
running process (see “Subdirectory: <root_directory>\marker” for more information
about marker files). To view the marker files currently in the system, use the View
Marker Files screen.
To view marker files, do the following:
1. Press the hotkey combination [CTRL]+[ALT]+[L], or click Marker File List in the
System Menu (see “System Menu”).
2. The View Marker Files screen opens.

Figure 6-19: View Marker Files

3. Click the Get Marker Files button, or press the [F8] key.
4. The View Marker Files list is populated with the files in the marker file directory.
The files to be displayed will be found in the marker folder under the environment
installation.
68
7
Disaster Recovery
Overview
This chapter describes the disaster recovery procedure and the operations performed
during disaster recovery.
In Oracle Retail Xenvironment, disaster recovery is necessary when a lead register goes
down and a non- lead register needs to take over the lead register role.
Requirements
The disaster recovery procedure requires the following:
 The store or location has more than one register.
 Database backups and updates will not be performed while a non-lead register is
acting as the lead register.
Important: The Disaster Recovery procedure does not

reconfigure Oracle Retail Xstore Point of Service in any way.
It is assumed that appropriate provision are in place for
allowing Oracle Retail Xstore Point of Service to function, or
that additional steps are taken to correct any issues that
occur as a result of the normal lead register being down.
Processing in Disaster Recovery Mode

During the disaster recovery process, the following restrictions will be set on the lead and
nonlead systems:
 Only the atoms and chains with the .drsafe option set to “True” will run. All other
atoms and chains will be locked out (for more information, see “Atoms and Chains”).
 Every kind of event will have hooks.
 The only chain running on any system will be on the new lead register. All atoms run
on nonlead registers will be called by “notify” atoms on the lead register, and all
return values from these atoms will be interpreted by these “notify” atoms.
 All of the properties changed on the store systems will be saved in one file on the
lead register.
About this Chapter

 “Convert a Register to Lead” describes the procedure for converting a non- lead
register to a lead register.
 “Restore the Lead Register” describes the procedure for returning a temporary lead
register to the non-lead role.
 “Custom Actions” describes the method for configuring custom actions that will be
performed whenever a non-lead register in the store network is being converted to a
lead register, or actions that will be performed whenever the lead register is restored.

Disaster Recovery
Convert a Register to Lead

The following procedure describes how to convert a non-lead register to temporarily take
over the role of lead register. This allows the store to continue processing sales should the
configured lead register go down or lose network connectivity.
To convert a non-lead register to a lead register, do the following:
1. Press the [Alt]+[R] hotkey combination, or select the Disaster Recovery option from
the System menu.
2. The system prompts whether to continue to the Disaster Recovery menu.
3. Click Yes or press the [Y] key to continue.
4. A username and password prompt opens.
5. Enter your username and password, then click Continue or press the [Enter] key.
6. The Disaster Recovery Menu is displayed.
Figure 7-1: Disaster Recovery Menu

7. Select Convert this Register to Lead, then click Continue or press the [Enter] key.
8. The system prompts whether to continue.
10. The register is now the lead register.
70
Restore the Lead Register

Once the configured lead register is running again, the temporary lead register must be
returned to a non-lead register. This is done by restoring the lead register on the
temporary lead register.
To restore a lead register, do the following:
1. On the temporary lead register, press the [Alt]+[R] hotkey combination.
2. The system prompts whether to continue to the Disaster Recovery menu.
4. A username and password prompt opens.
5. Enter your username and password, then click Continue or press the [Enter] key.
6. The Disaster Recovery Menu is displayed.
Figure 7-2: Disaster Recovery Menu

7. Select Restore Original Lead Register, then click Continue or press the [Enter] key.
8. The system prompts whether to continue.
10. The temporary lead is no longer the lead register, allowing the configured lead
register to perform all lead register processing.
Custom Actions
During disaster recovery, Oracle Retail Xenvironment can perform custom actions that
add necessary functionality to the disaster recovery process. These actions are configured
through atoms that are run during the convert and restore processes.

Disaster Recovery
Convert a Register
The dr-custom-convert-action atom is run on each register in the store during the
process of converting a nonlead register to a lead register in disaster recovery mode. This
atom has the following default configurations:
lead.atom.dr-custom-convert-action.class=noop nonlead.atom.dr-
custom-convert-action.class=noop atom.dr-custom-convert-
action.drsafe=true
atom.dr-custom-convert-action.disabled=true
 To add custom actions to the convert process, configure the atom with all the
necessary settings (see “Atoms and Chains”), and set the .disabled configuration to
“False”.
Restore the Lead Register

The dr-custom-restore-action atom is run on each register in the store during the
process of restoring the lead register to lead status from disaster recovery mode. This
atom has the following default configurations:
lead.atom.dr-custom-restore-action.class=noop
nonlead.atom.dr-custom-restore-action.class=noop atom.dr-
custom-restore-action.drsafe=true
atom.dr-custom-restore-action.disabled=true
To add custom actions to the restore process, configure the atom with all the necessary
settings (see ”Atoms and Chains”), and set the .disabled configuration to “false”.
72
A
The Daily Maintenance Process: Atom by
Atom
This chapter describes the important functions performed by the daily maintenance
process, which is controlled by a chain named BUSINESS_DATE_CHANGED. This section
provides a sequential list of each atom that is called by the BUSINESS_DATE_CHANGED
chain on the lead register, and gives a brief description of the task the atom performs.
The BUSINESS_DATE_CHANGED Chain

The daily maintenance chain contains, in order, the following atoms:
1. notify-create-sysclose-marker: This atom notifies all systems that daily maintenance
is being performed and creates a marker file indicating the same.
2. BEGINNING_OF_SYSTEM_CYCLE_STATE – A chain containing the following
atoms:
a. notify-set-system-state-store-closing-if-not-rolling-close - This atom updates an
internal state in the non-lead registers to indicate that daily maintenance is
taking place if the system does not use rolling closes.
b. notify-set-system-state-store-open-if-rolling-close - This atom updates an
internal state in the non-lead registers to indicate that daily maintenance is
taking place if the system uses rolling closes.
3. remove-sysopen-marker: This atom removes the marker file indicating that the store
is open.
4. notify-remove-sysopen-marker: This atom informs all systems that the store-open
marker should be removed.
5. ForwardCallToStoreClose: Sends a message to all Oracle Retail Xstore Point-of-
Service registers instructing them to update their internal state to show that daily
maintenance is being performed. Upon receiving this message, the store status
indicator in the Oracle Retail Xstore Point-of-Service status bar turns red.
6. wait-for-trickle-and-updates-to-complete: This atom waits for trickle- polling
updates and updates to complete before the daily maintenance continues.
7. preclose-delay-ten-seconds: This atom provides a waiting period that gives the
process time to load.
8. rotate-polling-package: This atom “rotates” polling package files from previous days
by renaming files in the <root_directory>/download/tmp directory. In the file
rotation, files with the extensions .tgz and .tgz.NNN are renamed as follows: .tgz
becomes .tgz.001, .tgz.001 becomes .tgz.002, .tgz.002 becomes
.tgz.003, etc.
9. notify-prepare-polling-package: This atom sends a message to each non-lead
register to prepare the <xstore_root>/upload/package.tgz polling upload
package file. Upon receiving the message, each non-lead register does the following:
a. The existing *.tgz files in the directory <xstore_root>/upload are renamed
in the same manner as the files in step 9.

The Daily Maintenance Process: Atom by Atom
b. The following files in the directory <xstore_root>/log are copied to the

directory <xstore_root>/upload/ with their names changed from
<filename>.xml to <filename>.<register#>.xml:
– PosLog.xml
– CommissionLog.xml
– commonlog.xml
– customers.xml
– inventory.xml
– InventoryCount.xml
– payroll.xml
– remc.xml
– seclog.xml
– timecard.xml
– workers.xml
For example, on Register #3, the file poslog.xml is copied to poslog.3.xml.
c. All the files in the directory <xstore_root>/log/relate are copied to the
<filename>.relate.<extension> to
<filename>.relate.<register#>.<extension>.
d. The following files in the directory <xstore_root>/log are copied to the
directory
<xstore_root>/upload/ with their names changed from <filename>.log
to <filename>.<register#>.log:
– xstore.log
– dataserver.log
e. The following files in the directory <root_directory>/log are copied to the
<filename>.log to <filename>.<register#>.log:
– xenvironment.log
– xenvironment-ui.log
f. The files copied to <xstore_root>/upload/ in steps b-e are archived into the
file <xstore_root>/upload/package.tgz. Once the files are entered into
the archive, the files are removed from the directory.
10. log-xstore-log-dir: This atom logs the contents of the directory
<xstore_root>/log. This allows support personnel to see what files were present
in the directory at this point in the daily maintenance process.
11. copy-tlogs-to-polling-directory: This atom creates copies of Oracle Retail Xstore
Point-of-Service tltog files in the directory <xstore_root>/upload/. When the
files are copied, their names are changed from <filename>.xml to
<filename>.<register#>.xml.
The following files are copied:
– PosLog.xml
– commonlog.xml
– customers.xml
74
– inventory.xml
– payroll.xml
– remc.xml
– seclog.xml
– timecard.xml
– workers.xml
For example, on Register #2, the file poslog.xml is copied to poslog.2.xml.
12. copy-xstore-mobile-tlogs-to-polling-directory: This atom creates copies of Oracle
Retail Xstore Point-of-Service Mobile tlog files in the directory
<xstore_root>/upload/. When the files are copied, their names are changed
from <filename>.xml to <filename>.<register#>.xml.
– PosLog.xml
– commonlog.xml
– customers.xml
– inventory.xml
– payroll.xml
– remc.xml
– seclog.xml
– timecard.xml
– workers.xml
13. copy-xstore-tablet-tlogs-to-polling-directory: This atom performs the same actions
as copy-xstore-mobile-tlogs-to-polling-directory, except on the tlog files created
by tablets.
14. copy-xstore-thin-client-server-tlogs-to-polling-directory: This atom performs the
same actions as copy-xstore-mobile-tlogs-to-polling-directory, except on the tlog
files created by the thin client server.
15. copy-xstore-mobile-logs-to-polling-directory: This atom copies the log files for
Oracle Retail Xstore Point-of-Service Software Mobile to the polling directory.
16. copy-xstore-mobile-tablet-logs-to-polling-directory: This atom performs the same
actions as copy-xstore-mobile-logs-to-polling-directory, except on the log files
created by tablets.
17. copy-xstore-thin-client-server-logs-to-polling-directory: This atom performs the
same actions as copy-xstore-mobile-logs-to-polling-directory, except on the log
files created by the thin client server.
18. copy-rlogs-to-polling-directory: This atom copies all the files from the directory
<xstore_root>/log/relate to the directory <xstore_root>/upload/. When
the files are copied, their names are changed from <filename>.relate.<extension> to
<filename>.relate.<register#>.<extension>.
19. move-hh-files-to-polling-directory: Moves handheld-related files from the Xservices
directory to the polling directory.
20. move-hh-relate-customer-files-to-polling-directory: Moves handheld-related Relate
customer files from the Xservices directory to the polling directory.

21. move-hh-relate-cardcust-files-to-polling-directory: Moves handheld-related Relate

card files from the Xservices directory to the polling directory.
22. move-prior-xstlogs-to-polling-directory: This atom moves the .log files from the
directory <xstore_root>/log to the directory <xstore_root>/upload/. The
files are renamed from <filename>.log to <filename>.<register#>.log.
– xstore.log
– dataserver.log
23. copy-envlogs-to-polling-directory: This atom copies the files from the directory
<root_directory>/log to the directory <xstore_root>/upload/. The copies
of the files are renamed from <filename>.log to
<filename>.<register#>.log.
The following file is copied:
– xenvironment.log
24. log-update-inbox-xstore: This atom logs the contents of the directory
<update_directory>/inbox/xstore. This allows support personnel to see what
files were present in the directory at this point in the daily maintenance process.
25. log-update-inbox-xadmin: This atom logs the contents of the directory
<update_directory>/inbox/xadmin. This allows support personnel to see what
26. log-update-inbox-cipher: This atom logs the contents of the directory
<update_directory>/inbox/cipher. This allows support personnel to see what
27. log-update-inbox-debitbin: This atom logs the contents of the directory
<update_directory>/inbox/debitbin. This allows support personnel to see
what files were present in the directory at this point in the daily maintenance
process.
28. create-local-polling-package: The files copied into the directory
<xstore_root>/upload/ in steps 12-19 are archived into the file
<xstore_root>/upload/package.tgz.
Note: The daily maintenance process no longer rotates the

pospoll.zip file. If you are not using the new deployment
functionality (see “Deployment”), speak with your Oracle
representative for instructions on rotating the pospoll.zip
file.
29. remove-old-pospoll-files: This atom removes all the old pospoll files from the
directory <xstore_root>/upload.
30. cleanup-package-archive-directory: This atom removes all the old, archived package
files.
31. wait-for-polling-packages-complete: This atom allows the daily maintenance
process to wait until the polling packages in the non-lead registers have been created
before continuing.
32. get-polling-packages: In this atom, the Lead Register retrieves and labels the polling
package files from the non-lead registers by performing the following steps for each
register:
76
a. The Lead Register downloads the file <xstore_root>/upload/package.tgz

from a non-lead register and saves the file in the
<root_directory>/download/tmp directory.
b. When the file has been retrieved, the Lead Register renames the file with the
format <Register>-package.tgz.
For example, the package.tgz file downloaded from Register #2 is renamed
REGISTER2-package.tgz.
33. move-uploaded-polling-packages-to-tmp-directory: This atom moves the polling
packages (that were uploaded to the lead register) to the
34. unpack-polling-packages: This atom unzips the .tgz files in the
35. log-poll-dir: This atom logs the contents of the directory
<root_directory>/download/tmp. This allows support personnel to see what
36. build-pospoll: This atom packages all of the .xml files in the folder
<root_directory>/ download/tmp into the file
<xstore_root>/upload/pospoll.zip. This file stores all the log files
downloaded from the registers (e.g. poslog.1.xml, poslog.2.xml,
seclog.1.xml, seclog.2.xml, etc.).
37. cleanup-polling-directory: This atom removes all of the .xml files in the directory
<root_directory>/download/tmp. After this step is run, only files ending in
.tgz and .tgz.NNN remain there.
38. cleanup-polling-marker: This atom removes the POLLOK.XST marker file (if found)
prior to the polling attempt.
39. cleanup-pollend-marker: This atom removes the POLLEND.XST marker file (if
found) prior to the polling attempt.
40. poll-close1: This atom launches the “CLOSE1” section of the file
<root_directory>/ext/poll.bat. The file is created by the Tech Services
group for each customer.
41. wait-for-pollok: This atom waits for the system to poll. The poll ends when the
system receives the file POLLOK.XST in the directory <root_directory>/marker.
Polling expires at 5:30 A.M. the next morning if the system has not yet received the
file POLLOK.XST.
42. upload-pospolls: Uploads pospoll files to the Apache server.
43. poll-close2: This atom launches the “CLOSE2” section of the file
<root_directory>/ext/poll.bat. This is a custom file created for each
customer.
44. wait-for-pollend: This atom waits for the system to poll. The poll ends when the
system receives the file POLLEND.XST in the directory
<root_directory>/marker.
Polling expires at 5:30 A.M. the next morning if the system has not yet received the
file POLLEND.XST.
45. log-poll-dir-post-poll: This atom logs the contents of the directory
<root_directory>/download/tmp after polling was performed. This allows
support personnel to see what files were present in the directory at this point in the
daily maintenance process.

46. log-xstore-log-dir-post-poll: This atom logs the contents of the directory

<xstore_root>/log after polling was performed. This allows support personnel
to see what files were present in the directory at this point in the daily maintenance
process.
47. log-update-inbox-xstore-post-poll: This atom logs the contents of the directory
<update_directory>/inbox/xstore after polling was performed. This allows
48. log-update-inbox-xadmin-post-poll: This atom logs the contents of the directory
<update_directory>/inbox/xadmin after polling was performed. This allows
49. log-update-inbox-cipher-post-poll: This atom logs the contents of the directory
<update_directory>/inbox/cipher after polling was performed. This allows
daily maintenance.
50. log-update-inbox-debitbin-post-poll: This atom logs the contents of the directory
<update_directory>/inbox/debitbin after polling was performed. This
allows support personnel to see what files were present in the directory at this point
in the daily maintenance process.
51. rotate-pre-upd-db-backup: This atom renames/rotates existing .prepoll database
files in the backup directory in the Oracle Retail Xstore Point-of-Service database
directory.
52. delete-db-backup-1: This atom deletes the existing Oracle Retail Xstore Point-of-
Service database backup file.
53. dataserver-backup-xstore-pre-upd: This atom connects to Dataserver and backs up
the Oracle Retail Xstore Point-of-Service database to the configured backup file.
54. zip-db-backup-pre-upd: This atom zips/archives the Oracle Retail Xstore Point-of-
Service database backup file into the file prepolldb.zip. in the backup directory in
the Oracle Retail Xstore Point-of-Service database directory.
55. delete-db-backup-pre-upd: This atom deletes the existing Oracle Retail Xstore Point-
of-Service database backup file.
56. run-datapurger: If enabled, this atom runs the DataPurger. In the default
configuration, this atom is disabled.
57. process-pre48-downloads-rep: If the Oracle Retail Xstore Point-of-Service version is
less than 4.8, this atom copies .rep download files to the Oracle Retail Xstore Point-of-
Service download directory for processing; then, after processing the file, the process
repeats until all the files have been processed. If the Oracle Retail Xstore Point-of-
Service version is 4.8 or greater, this atom is disabled.
58. process-pre48-downloads-mnt: If the Oracle Retail Xstore Point-of-Service version is
less than 4.8, this atom copies .mnt download files to the Oracle Retail Xstore Point-
of-Service download directory for processing; then, after processing the file, the
process repeats until all the files have been processed. If the Oracle Retail Xstore
Point-of-Service version is 4.8 or greater, this atom is disabled.
59. UPDATES: This chain processes the updates that are ready to be performed. See
“The UPDATES Chain”.
60. END_OF_SYSTEM_CYCLE_STATE: A chain containing the following atoms:
a. notify-set-end-of-cycle-system-state: The atom notifies the Xenvironment
software on other registers to update their system date to the calendar date.
78
b. create-sysopen-marker-if-rolling-close: Creates a marker file indicating that the

system is open if rolling closes are enabled.
c. notify-create-sysopen-marker-if-rolling-close: Notifies other systems that store-
open marker files should be created.
61. bypass-if-updates-pending: If updates are pending, the chain will end. If this chain
is being run as part of a parent chain, the parent chain will continue.
62. DATABASE_BACKUP: This chain performs a backup of the database, copies the
backup to the non-lead registers and asks the non-lead registers to restore it.
The UPDATES Chain

1. force-download-deployment-file: This atom ensures that all the latest deployments
have been downloaded, ensuring that all pending updates are applied during the
2. download-immediate-deployments - This atom downloads, from Xcenter (part of
the Oracle Retail Xstore Office), the configuration deployment files that are to be
installed immediately.
3. download-close-deployments: This atom downloads, from Xcenter (part of the
Oracle Retail Xstore Office), the configuration deployment files that are to be
installed during the daily maintenance process.
4. unzip-dataloader-files: This atoms unzips the downloaded DataLoader files.
5. update-feeds: This atom updates the different feeds in Oracle Retail Xenvironment if
there are files in any of the update inboxes, along with the required flags.
6. check-and-download-updates: The register downloads the new files to their defined
locations.
This step is typically used so that the Lead Register can copy the cipher files to the
directory <xstore_root>/res/keys.
7. execute-dataloader: Run the DataLoader. The actions of this atom depend upon the
version of Oracle Retail Xstore Point of Service:
– If the Oracle Retail Xstore Point-of-Service version is 4.8 or greater, this atom
runs the DataLoader, which downloads, manages, processes, and archives all of
the download files.
– If the Oracle Retail Xstore Point-of-Service version is less than 4.8, this atom is
disabled.
8. process-deployment-downloads-immediate: This atom processes immediate
configuration deployment files that have not yet been processed.
9. process-deployment-downloads-close: This atom processes the configuration
deployment files downloaded in step 3.
10. remove-old-deployment-download-dat-files: This atoms removes old .dat files
that were previously deployed.
11. bypass-if-no-updates-to-apply: If there are no updates to apply, this chain will end.
If this chain is being run as part of a parent chain, the parent chain will continue.
12. PRE_UPD_DB_BACKUP: This chain backs up the database prior to performing
updates.
13. notify-create-update-pending-marker: This atom creates the update pending marker
file.

Xstorexenv 180 Ug

Uploaded by

Copyright:

Available Formats

You might also like

Xstorexenv 180 Ug

Uploaded by

Document Information

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

Xstorexenv 180 Ug

Uploaded by

Copyright:

Available Formats

Oracle® Retail Xenvironment

Copyright © 2018, Oracle and/or its affiliates. All rights reserved.

Oracle Retail VAR Applications

Note: Before sending us your comments, you might like to

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 Corrections

Oracle Retail Documentation on the Oracle Technology Network

Navigate: This is a navigate statement. It tells you how to

Note: This information is provided to improve your

Important: This information is important for the user to be

How this User Guide Is Organized

Oracle Retail Xenvironment User Guide 1

Who Should Use this Guide

Figure 1-1: Oracle Retail Xenvironment – Start Screen

Note: For a more complete description of the UI elements,

Oracle Retail Xenvironment Installation and Configuration

Oracle Retail Xenvironment User Guide 3

Note: All paths shown in this document are default paths

Default Installation Path

Daily Maintenance Procedures

Note: Once the upgrade packages are downloaded to each

Lead Register Responsibilities

Responsibilities of Both Lead and Non-Lead Registers

Commonly Used Chains and Atoms

Note: All chain and atom commands are case-sensitive.

Oracle Retail Xenvironment User Guide 5

Table 1-1: Common Atoms and Descriptions

Atom Name Description

start-xstore Starts the Oracle Retail Xstore Point-of-Service

Table 1-2: Common Chains and Descriptions

Chain Name Description

BUSINESS_DATE_CHANGED Initiates Oracle Retail Xenvironment’s Daily

About This Chapter

Note: Atom names frequently include suffixes that indicate

Oracle Retail Xenvironment User Guide 7

Permit or Prevent Atoms From Starting At Certain Times

Note: These permit/disallow times only determine the times

 name - The name of the atom.

 name - The name of the atom.

Oracle Retail Xenvironment User Guide 9

Sample New Atom:

Table 2-1: Common Classes for Creating Custom Atoms

LaunchMaster This class is used to execute a shell script or binary.

Oracle Retail Xenvironment User Guide 11

RotateFiles This class is commonly used for rotation archive files. It

Oracle Retail Xenvironment User Guide 13

Zip This class places a set of files into a .zip archive.

 .windowtitle - (Windows only) Defines the Windows window information. If this

Inserting an Atom or Chain Into a Chain

Oracle Retail Xenvironment User Guide 15

Note: The “atoms=” and “chains=” lists are no longer

Oracle Retail Xenvironment User Guide 17

Important: This chapter should only be used by customers

About this Chapter

Base Oracle Retail Xenvironment Directory Structure and Contents

The Main Directory: <root_directory>

Oracle Retail Xenvironment User Guide 19