Вы находитесь на странице: 1из 104
Oracle ® Retail Xenvironment User Guide Release 15.0 E69502-01 December 2015

Oracle ® Retail Xenvironment

User Guide

Release 15.0

E69502-01

December 2015

Oracle® Retail Xenvironment User Guide, Release 15.0

E69502-01

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

Primary Author:

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

xi

Preface

xiii

Audience

xiii

Documentation Accessibility

xiii

Access to Oracle Support

xiii

Customer Support

xiii

Review Patch Documentation

xiii

Improved Process for Oracle Retail Documentation Corrections

xiii

Oracle Retail Documentation on the Oracle Technology Network

xiv

Conventions

xiv

1 Introduction

1

Overview

1

How this User Guide is Organized

1

Who Should Use this Guide

2

Security

2

TLS-Encrypted Communication

2

Corporate Password Configuration

2

User Interface

3

Oracle Retail Xenvironment Installation and Configuration

4

Default Installation Path

4

Store Closing Procedures

4

Software Updates

5

Lead Register Responsibilities

5

Responsibilities of Both Lead and Non-Lead Registers

5

Commonly Used Chains and Atoms

6

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

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

20

Subdirectory:

<root_directory>\support

21

Subdirectory:

<root_directory>\tmp

21

Subdirectory:

<root_directory>\wwwroot

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

4 Configuring Oracle Retail Xenvironment GUI

29

Overview

29

About this Chapter

29

Oracle Retail Xenvironment UI Directory Structure and Contents

29

Subdirectory: <root_directory>\ui_config

29

Subdirectory: <root_directory>\ui_cust_config

29

Configuring the Oracle Retail Xenvironment UI

29

AppServices.properties

30

ContextConfig.xml

30

IPCClientConfig.xml

30

Example

31

Message Structure

32

SecurityConfig.xml

32

Example

33

system.properties

33

AlertsConfig.xml

34

Example

35

MenuConfig.xml

35

Context Configuration

35

Pop-up Menu Configuration

36

Menu Key Configuration

36

Example

39

PromptConfig.xml

40

Example

40

DialogConfig.properties

41

Button Graphics

41

Window

Size and Location

42

Window

Background

42

Button Type Configuration

43

FontConfig.xml

44

Example

44

 

probescripts_{OS}.properties

45

5

Oracle Retail Xenvironment Processing

47

Overview

47

About this Chapter

47

Log Files

47

xenvironment.log

47

Trickle Polling

48

Uploads

48

Downloads

49

Deployment

49

The Store Close Process

50

Packaging of Upload Files (Creating pospoll.zip)

51

File Archive Updates

51

Archive Structure

52

update.properties

52

 

Example

 

52

scripts

52

Application

Update Processing Example

53

Manual Closing Options

54

Processing of Application Updates

54

Processing of Cipher Files

55

Processing

of

debit.txt File

55

6

Using Oracle Retail Xenvironment

57

Overview

57

About this Chapter

57

 

Starting Oracle

Retail Xenvironment

57

Graphical User Interface (GUI)

58

On-Screen Keyboard

58

Features

59

In-Window Keyboard

59

Message Screen

60

View

Message Details

60

Clear

Message

 

60

POS Status

61

Register Status

61

Process Steps

62

Alert Detail

62

Apps

62

About

63

Systems Support/Attention

63

Menu

Buttons

64

Status

Bar

65

Support Menu

 

66

System Menu

67

Hotkeys

68

Password Protected Functions

69

Plugins

70

Run a Chain or Atom

70

Tech

Support Menu

 

71

Task

List

71

Switch to Task

72

Kill Task

73

View Marker Files

73

System Information

 

74

Overview

74

List

Services

 

75

List

Processes

75

 

List Printers

76

7 Disaster Recovery

 

77

Overview

77

Requirements

77

 

Processing

in Disaster Recovery Mode

77

About this

Chapter

77

Convert a Register to Lead

78

Restore the Lead Register

79

Custom Actions

79

Convert a Register

80

Restore the Lead Register

80

A Appendix: The Close Process: Atom by Atom

81

The

CLOSE_STORE Chain

81

The

UPDATES Chain

88

Send Us Your Comments

Oracle Retail Xenvironment, User Guide, Release 15.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.

Preface

Oracle Retail Xenvironment User Guide describes the installation, upgrade, and configuration of Oracle Retail Xenvironment release 15.0.

Audience

This User Guide is intended for anyone responsible for the installation, upgrade, and configuration of Oracle Retail Xenvironment 15.0.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit

hearing impaired.

Customer Support

To contact Oracle Customer Support, access My Oracle Support at the following URL:

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, 13.3) or a later patch release (for example, 13.3.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

Preface

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:

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.)

Conventions

The following text conventions are used in this document:

Convention

Meaning

Navigate:

Note:

Important:

code

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.”

This information is provided to improve your understanding, simplify a task, or point out special circumstances.

This information is important for the user to be aware of. For example, information that can help prevent the loss of data. This is a code sample. It is used to display examples of code.

1

Overview

Introduction

The main purpose for the Oracle Retail Xenvironment application consists of three important functions:

Help the point-of-sale (POS) software perform store closing 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, store closing 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.

Chapter 2, “Atoms and Chains” provides information about atoms and chains, what they do, how they are used, and how they are created and configured.

Chapter 3, Configuring the Oracle Retail Xenvironmentdescribes the files and directory structure for the Oracle Retail Xenvironment engine, and how they are used in configuration.

Chapter 4, Configuring the Oracle Retail Xenvironment UIdescribes the files and directory structure for the Oracle Retail Xenvironment UI, and how they are used in configuration.

Chapter 5, Oracle Retail Xenvironment Processingdescribes how Oracle Retail Xenvironment performs normal processing functions, such as processing updates, performing trickle polling, and processing archive files.

Chapter 6, Using Oracle Retail Xenvironmentdescribes how to use Oracle Retail Xenvironment. This includes a description of the UI and the screens and options found in it.

Chapter 7, Disaster Recoveryexplains disaster recovery procedures for Oracle Retail Xenvironment.

Introduction

Appendix A: “Appendix: The Close Process: Atom by Atomgoes through each atom and chain in the Close 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 15.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 15.0.

Corporate Password Configuration

Oracle Retail Xenvironment creates .conf files containing encrypted information that is used by Oracle Retail Xstore Point of Service and the Oracle Retail Xenvironment GUI to configure the corporate password. This allows all three programs to use the same corporate password without requiring each application to be configured individually. The .conf files are created each time Oracle Retail Xenvironment starts, to ensure that the information is current and accurate for all applications.

Oracle Retail Xenvironment 15.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.

Please Note POS Status System Support/ System Attention Menu Buttons Notification Area/Process Status Status Bar
Please Note
POS Status
System Support/
System Attention
Menu Buttons
Notification Area/Process Status
Status Bar

Figure 1-1: Oracle Retail Xenvironment Start Screen

Note: For a more complete description of the UI elements, see Using Oracle Retail Xenvironment, Chapter 6.

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.

Introduction

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 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, Chapter 3.

For more information about the directories created by the Oracle Retail Xenvironment GUI installation, see Oracle Retail Xenvironment UI Directory Structure and Contents, Chapter 4”.

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

Store Closing Procedures

In addition to locking down the Operating System and providing a basic set of menu options, Oracle Retail Xenvironment also performs store closing tasks. The functional requirements for closing a store may vary among different retail chains. For that reason, Oracle Retail Xenvironment is designed so that every step in the store closing process is configurable to meet customer requirements.

The store closing procedure is initiated when a user issues an Oracle Retail Xstore Point- of-Service command from the Lead Register. Before the process is started, the user is required to perform certain tasks, such as counting the cash drawer, clocking out employees, etc. After all tasks that require user intervention have been completed, Oracle Retail Xstore Point of Service sends a “Close Store” message to Oracle Retail Xenvironment through the internal communication framework.

Oracle Retail Xenvironment 15.0

When Oracle Retail Xenvironment receives this message, it assumes control and processes the closing steps that are defined in a configuration file. These steps are enumerated and described in The Store Close Process, Chapter 5.

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 the closing process.

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 automaticallyusually 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.

Introduction

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.

Table 1-1: Common Atoms and Descriptions

Atom Name

Description

start-xstore

shutdown-xstore

execute-dataloader

commandprompt

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.

Triggers Oracle Retail Xstore Point-of-Service application to exit.

Initiates DataLoader.

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

CLOSE_STORE

Initiates Oracle Retail Xenvironment’s Store Close 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.

2

Overview

Atoms and Chains

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, as part of the closing sequence. They may also be used for remote execution.

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 the close process, etc.

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.

Oracle Retail Xenvironment 15.0

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, Chapter 3) 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=

Oracle Retail Xenvironment 15.0

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.

Additional configurations:

.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.

Additional configurations:

 

.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:

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.)

 

.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.

Additional configurations:

 

.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:

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.)

 

Oracle Retail Xenvironment 15.0

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.

Additional configurations:

 

.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:

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.)

 

Unzip

This class extracts files from one or more .zip archives. Additional configurations:

.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.

Additional configurations:

.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.

Oracle Retail Xenvironment 15.0

.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, Chapter 3).

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, Chapter 3and actions.properties, Chapter 3for more information).

These configuration options have the following format:

Atoms and Chains

chain.<chain_name>.<insertbefore/insertafter>.<atom_name>=<new

_atom> [<new_atom2>

]

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.

Oracle Retail Xenvironment 15.0

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, Chapter 3” for more information).

For example, if the following line exists in the actions.properties file:

chain.CLOSE_STORE.denymarkers=close.err

the chain CLOSE_STORE 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, Chapter 3” for more information).

For example, if the following line exists in the actions.properties file:

chain.CLOSE_STORE.allowmarkers=close.ready

the atom CLOSE_STORE 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.

Atoms and Chains

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 15.0.

About this Chapter

This chapter includes the following information:

Base Oracle Retail Xenvironment Directory Structure and Contentsdescribes the directory structure used by Oracle Retail Xenvironment.

Configuring the Oracle Retail Xenvironment Engineexplains 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 installation directories 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 cut_config/version1/local.propertieswhich contains store-specific and register- specific settings used during installationare in the installation directory. In addition, the environment.bat file is in this folder.

The installation 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.

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\win32\util (on Windows) or <root_directory>\ext\win32\util (on Linux). 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 closing process 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.

Subdirectory: <root_directory>\res\ssl

This directory contains the TLS certificates.

Oracle Retail Xenvironment 15.0

Subdirectory: <root_directory>\support

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

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.

Configuring the Oracle Retail Xenvironment Engine

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.

Dataserver Options - Defines properties specific to the Dataserver application.

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.

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.

Configuring the Oracle Retail Xenvironment Engine

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, Chapter 2and Allowmarkers, Chapter 2.

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 closing process 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 Configurationsand System Configurations.

Oracle Retail Xenvironment 15.0

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/registration.xml 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.lead.port - Port number to use when connecting to Lead Register.

Example:

environment.lead.port=9096

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 the close.

Example:

xstore.disabled=False

Configuring the Oracle Retail Xenvironment Engine

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 the close process 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 the close process 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

Oracle Retail Xenvironment 15.0

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 the close process. See Atoms and Chains, Chapter 2for 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 the store closing process. 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”.

Configuring the Oracle Retail Xenvironment Engine

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.

jre - Feed for Java Runtime Environment (JRE) 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.jre.filter=^.*-jre-.*-.*\\.zip$

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.

Oracle Retail Xenvironment 15.0

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.

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.

Configuring the Oracle Retail Xenvironment Engine

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 who have already installed Oracle Retail Xenvironment 15.0.

About this Chapter

This chapter includes the following information:

Oracle Retail Xenvironment UI Directory Structure and Contentsdescribes the directory structure used by the Oracle Retail Xenvironment UI.

Configuring the Oracle Retail Xenvironment UIexplains 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)

Subdirectory: <root_directory>\ui_config

This subdirectory contains all of the default configurations for the Oracle Retail Xenvironment UI.

Subdirectory: <root_directory>\ui_cust_config

Configuration files containing customer-specific updates to the files in the

<root_directory>\ui_config directory. Any configurations entered into files in this directory override the configurations in the files in the <root_directory>\ui_config directory.

Overrides can only be performed on some of the files in the <root_directory>\ui_config directory, not all of them.

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.

Configuring Oracle Retail Xenvironment GUI

The following files and directory structures are found in the <root_directory>/ui_config directory:

AppServices.properties

This file determines which GUI application services are available in Oracle Retail Xenvironment. Each setting takes the form of ServiceName.PLATFORM=true/false, where:

ServiceName is the name of the service.

PLATFORM is the operating system that is being configured.

WINDOWS - Microsoft Windows operating system

LINUX - Linux operating system

true/false determines whether the application service is available.

true - The service is available

false - The service is not available

For example:

TaskSchedulerService.WINDOWS=true

SystemLogMonitorService.LINUX=false

Note: When changing the application services availability, be sure to set the property for the operating system on which Oracle Retail Xenvironment runs. Oracle Retail Xenvironment will only read the services settings for the correct operating system.

ContextConfig.xml

This file defines Contexts in Oracle Retail Xenvironment. These Contexts determine the configurations for the different Oracle Retail Xenvironment screens.

IPCClientConfig.xml

This file defines the IPC messages sent to the Oracle Retail Xenvironment engine from the Oracle Retail Xenvironment GUI. These messages are used by the Oracle Retail Xenvironment GUI to communicate with the Oracle Retail Xenvironment engine. All IPC messages configurations are defined within the

<IPCClientConfigs> element.

The <IPCClientConfigs> element contains the following elements and attributes:

<client_config> - This element defines one IPC message.

servicename - This attribute defines the name used to refer to the IPC message.

address - This attribute determines the network address to which the IPC message is sent. This attribute should have a value of https://127.0.0.1.

port - This attribute determines the network port to which the IPC message is sent. On most systems, this will have a value of 9096.

extension - This attribute determines the destination directory to which the IPC message is sent.

enabled - This attribute determines whether the IPC message is enabled. If this value is true, the IPC message is enabled.

Oracle Retail Xenvironment 15.0

<message> - This element contains the message that is sent. This message must be contained within a CDATA section to prevent parsing by the local XML parser. For a sample IPC message, see Message Structure.

Example

<IPCClientConfigs xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance"> <client_config servicename="PythonInitialization" address="https://127.0.0.1" port="9096" extension="/gui/pyinit" enabled="true"> <message>

<![CDATA[<ns0:Envelope

xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/"><ns0:Header

><xhead><msg_id>0001</msg_id><msg_type>IPCRequest</msg_type><dest

ination>SERVER</destination><priority>1</priority><source>POS</so

urce><create_timestamp

/><charset>850</charset></xhead></ns0:Header><ns0:Body><methodCal

l><methodName>Initialize</methodName><params><param><name>Initial ize</name><value>Initialize</value></param></params></methodCall>

</ns0:Body></ns0:Envelope>]]>

</message>

</client_config>

</IPCClientConfigs>

Configuring Oracle Retail Xenvironment GUI

Message Structure

The message information contained in a <message> element’s CDATA section consists almost entirely of standard formatting information. The information that must be configured is highlighted in the following structure example:

<ns0:Header>

<xhead>

<msg_id>0001</msg_id>

<msg_type>IPCRequest</msg_type> <destination>SERVER</destination>

<priority>1</priority>

<source>POS</source> <create_timestamp />

<charset>850</charset>

</xhead>

</ns0:Header>

<ns0:Body>

<methodCall>

<methodName>ATOM_NAME</methodName>

<params>

<param>

<name>PARAMETER_NAME</name>

<value>PARAMETER_VALUE</value>

</param>

</params> </methodCall>

</ns0:Body>

</ns0:Envelope>

In the example above,

ATOM_NAME is the name of the atom to be run.

PARAMETER_NAME is the name of a parameter to be sent to the atom.

PARAMETER_VALUE is the value of the parameter to be sent to the atom.

one <param> element for each parameter to be sent to the atom (containing <name> and <value> subelements) must be included within the parent <params> element.

all the other information in the formatting sample is static and must be included in the message as shown above.

SecurityConfig.xml

This file defines the security configurations for the Oracle Retail Xenvironment GUI. Each security configuration has the following elements:

<SecurityConfig> - This element delineates one security configuration.

<type> - The type of security configuration; used to refer to the security configuration.

<classname> - The classname called when the security configuration is used in Oracle Retail Xenvironment.

<passwordPrompt> - The translation key for the prompt displayed when the security configuration is called.

Oracle Retail Xenvironment 15.0

<failMessageKey> - The translation key for the messages that is displayed when the security login fails.

<encrypted_formula> - The encrypted login information.

decrypter - The method used to encrypt login information.

<interactive> - Determines whether a password prompt appears for the security configuration.

Example

<SecurityConfigs xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance"> <SecurityConfig> <type>SYSTEM_PASSWORD</type>

<classname>dtv.env.security.validate.SystemPasswordValidator </classname> <passwordPrompt>_systemPasswordPrompt</passwordPrompt> <failMessageKey>_systemPasswordInvalid</failMessageKey> <encrypted_formula decrypter="Encrypter" /> <interactive>true</interactive> </SecurityConfig>

</SecurityConfigs>

system.properties

The UI version of the system.properties files defines system information, display information, and general 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.

Format.Time - The format of the time. This configuration has the following options:

h:mm a - United States AM/PM style.

H:mm - [DEFAULT] International 24-hour format.

Format.Date - The format of the date. This configuration has the following options:

yyyy-MM-dd - [DEFAULT]

MM/dd/yyyy - United States date style.

dd/MM/yyyy - European date style.

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.

Configuring Oracle Retail Xenvironment GUI

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

AlertsConfig.xml

The alerts displayed in the Oracle Retail Xenvironment UI are configured in the AlertsConfig.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.

<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.

Oracle Retail Xenvironment 15.0

Example

<Alerts xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <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>

MenuConfig.xml

The MenuConfig.xml file determines the configuration of the menus displayed in each Context in the Oracle Retail Xenvironment UI.

The MenuConfig.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 <ApplicationContext> element.

The <ApplicationContext> 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.

roleid - This attribute determines the Role ID that a user must be assigned to access the context. A Role ID of EVERYONE allows all users to access the context.

osType - This attributes determines the operating system in which the context is available.

<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.

Configuring Oracle Retail Xenvironment GUI

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 pressedalong with the keyEventCodeto 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.

Oracle Retail Xenvironment 15.0

keyMaskALT - If this attribute is set to “true”, it indicates that the [ALT] key must be pressedalong with the keyEventCodeto 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 pressedalong with the keyEventCodeto 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”).

PromptPasswordStyle - This attribute refers to the password that must be entered in the password prompt (see SecurityConfig.xmlfor more information). This attribute is only valid if PromptPassword is set to “true”.

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.