Oracle® Retail Xstore Point of Service

Technical Guide
Release 23.0.0
F81321-03

April 2024

NOTE: In the examples below, user details / company

name / address / email / telephone number represent a
fictitious sample. Any similarity to actual persons, living or
dead, is purely coincidental and not intended in any
manner.
Oracle® Retail Xstore Point of Service, Technical Guide, Release 23.0.0

F81321-03

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

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

1 Preface........................................................................................1-xxvii

1 Introduction......................................................................................1-1
Overview ....................................................................................................................... 1-1
Configuration Changes Using Xstore Office.......................................................... 1-2
Audience........................................................................................................................ 1-2
About this Guide ......................................................................................................... 1-2

2 Version Numbers .............................................................................2-1

Overview ....................................................................................................................... 2-1
About this Chapter ...................................................................................................... 2-2
Formats........................................................................................................................... 2-2
Base Version ........................................................................................................... 2-2
Customer Version.................................................................................................. 2-2
Marking the Transaction with the Current Version ......................................... 2-3
Where the Information is Stored .............................................................................. 2-3

3 Organization Hierarchy Configuration...........................................3-1

Overview ....................................................................................................................... 3-1
Organization Hierarchy Example ....................................................................... 3-2
Define a Hierarchy ...................................................................................................... 3-2
Set Up a Location Hierarchy ...................................................................................... 3-3
Set Up a Location-Based Pricing Hierarchy............................................................ 3-3
Location Based Hierarchical Pricing ........................................................................ 3-3
Sample Hierarchy .................................................................................................. 3-3
Extend the Hierarchical Price Provider.................................................................... 3-4

4 Tax Setup & Configuration .............................................................4-1

Overview ....................................................................................................................... 4-1
Introduction to the Tax Tables .................................................................................. 4-2
Generalized Tax Setup Procedure ............................................................................ 4-4
Other Tax Setup Options ...................................................................................... 4-5
Tax Location and Mapping Setup ............................................................................ 4-6
Tax Groups Setup ........................................................................................................ 4-6
Tax Authority Setup .................................................................................................... 4-7
Tax Rounding Rules for tax_tax_authority.rounding_code............................ 4-7
Tax Group Rules Setup............................................................................................... 4-7
Tax Rate Rule Setup .................................................................................................... 4-8
A Single Tax: Sample Setup Procedure................................................................... 4-9

iv
 Step #1 ..................................................................................................................... 4-9
Step #2 ................................................................................................................... 4-10
Step #3 ................................................................................................................... 4-10
Step #4 ................................................................................................................... 4-10
Step #5 ................................................................................................................... 4-11
Step #7 ................................................................................................................... 4-12
Multiple Taxes: Sample Setup Procedure............................................................. 4-12
Step #1 ................................................................................................................... 4-13
Step #2 ................................................................................................................... 4-13
Step #3 ................................................................................................................... 4-13
Step #4 ................................................................................................................... 4-14
Step #5 ................................................................................................................... 4-14
Step #6 ................................................................................................................... 4-14
Step #7 ................................................................................................................... 4-15
Automatic Tax Overrides: Sample Setup Procedure .......................................... 4-16
Tax Override Setup ............................................................................................. 4-16
When a User Makes a Tax Change: Configuring Reasons ................................ 4-17
Tax Change Reasons: XML Configuration ...................................................... 4-17
Tax Change Reasons: Sample Database Setup ................................................ 4-17
VAT Tax: Sample Setup Procedure........................................................................ 4-18
Step #1 ................................................................................................................... 4-18
Step #2 ................................................................................................................... 4-18
Step #3 ................................................................................................................... 4-19
Step #4 ................................................................................................................... 4-19
Step #5 ................................................................................................................... 4-19
Step #6 ................................................................................................................... 4-20
Step #7 ................................................................................................................... 4-20
Multiple VAT Taxation....................................................................................... 4-21
Compound Taxes ....................................................................................................... 4-22
How a Compound Tax is Applied: An Example ............................................ 4-22
Compound Taxes: Sample Setup Procedure ................................................... 4-22
Step #1 ............................................................................................................ 4-22
Step #2 ............................................................................................................ 4-23
Step #3 ............................................................................................................ 4-23
Step #4 ............................................................................................................ 4-23
Step #5 ............................................................................................................ 4-23
Step #6 ............................................................................................................ 4-24
Step #7 ............................................................................................................ 4-24
Threshold Taxes ......................................................................................................... 4-25
How a Threshold Tax is Applied: An Example .............................................. 4-25
Threshold Taxes: Sample Setup Procedure ..................................................... 4-26
Step #1 ............................................................................................................ 4-26
Step #2 ............................................................................................................ 4-26
Step #3 ............................................................................................................ 4-27
Step #4 ............................................................................................................ 4-27
Step #5 ............................................................................................................ 4-27
Step #6 ............................................................................................................ 4-28

v
 Step #7 ............................................................................................................ 4-28
Taxing in Send Sale/Remote Sale Transactions .................................................. 4-30
Database Configuration...................................................................................... 4-30
XML Configuration ............................................................................................. 4-30
Changing Tax in a Transaction ............................................................................... 4-31
Tax Exemption Database Setup .............................................................................. 4-31
Tax Exemption Configuration ........................................................................... 4-31
Tax Exemption Reason Codes ........................................................................... 4-32
Configuring the Tax Display................................................................................... 4-32
Tax Group Mapping Overrides Setup................................................................... 4-32
Tax Mapping Example: tax_tax_group_mapping Table ............................... 4-33
Tax Bracket Setup ...................................................................................................... 4-33
Examples E1 & E2: tax_tax_bracket table......................................................... 4-34

5 Item and Pricing Configuration ......................................................5-1

Overview ....................................................................................................................... 5-1
Item Pricing Overview................................................................................................ 5-1
Base Pricing Strategy in a hierarchy-based model ........................................... 5-1
Prerequisites and Assumptions ................................................................................ 5-1
Location-Based Hierarchy Pricing Structure .......................................................... 5-2
Customer Group Pricing ............................................................................................ 5-3
When there are multiple customer groups, which price is used? .................. 5-3
Item Setup Overview .................................................................................................. 5-3
Item Database Setup ................................................................................................... 5-5
Non-Physical Item Database Setup.......................................................................... 5-5
Hierarchy-based Pricing Database Setup ............................................................... 5-5
Item Merchandise Hierarchy Database Setup ....................................................... 5-5
Item Options Setup ..................................................................................................... 5-5
Style: Item Dimensions/Grid Setup......................................................................... 5-5
Deals at the Color Level........................................................................................ 5-6
Customer Engagement Cloud Services Changes Required ..................... 5-6
Setup Overview ..................................................................................................... 5-6
How to Set Up Item/Style-level Prompting and Grid...................................... 5-7
itm_item Table Setup ..................................................................................... 5-7
itm_item_dimension_type Table Setup ...................................................... 5-8
itm_item_dimension_value Table Setup................................................... 5-10
itm_item_dimension Table Setup .............................................................. 5-11
Style: Item Grid SysConfig.xml Setup .............................................................. 5-12
Xstore Point of Service Example - Entering a Style ID During a Sale... 5-13
Xstore Point of Service Example - Item Lookup By Style Using the Item Grid
5-13
Item Cross Reference Database Setup................................................................... 5-16
Item Vendor Database Setup................................................................................... 5-16
Attached Item Database Setup................................................................................ 5-16
Attached Items Setup in SysConfig.xml ............................................................... 5-16
Substitute Item Setup ............................................................................................... 5-17

vi
 Similar Item Setup..................................................................................................... 5-17
Item Prompting Database Setup............................................................................. 5-18
Item Lookup Configuration in SysConfig.xml.................................................... 5-18
Kit Item Setup ............................................................................................................ 5-20
Database Setup for Kits ............................................................................... 5-21
System Config Setup for Kits...................................................................... 5-21
Item Matrix.................................................................................................................. 5-23
Item Matrix Database Setup............................................................................... 5-23
Item Matrix System Configuration ................................................................... 5-24
Item Images................................................................................................................. 5-24
Database Setup..................................................................................................... 5-25
Quick Items Tab......................................................................................................... 5-25

6 Item Messaging Configuration .......................................................6-1

Overview ....................................................................................................................... 6-1
Item Message Detail Database Setup ...................................................................... 6-3
Transaction Type Database Setup............................................................................ 6-3
Message to Item Mapping Database Setup ............................................................ 6-3
Item Messaging Database Setup............................................................................... 6-3
Message Setup in translations.properties............................................................... 6-3
Setup Examples - HTML and Text Messages......................................................... 6-4
Setup Example - Composite Message ...................................................................... 6-6
The results... Composite Message Example....................................................... 6-8
Setup Example - Titled Image Message .................................................................. 6-8
Message Configuration Options in System Config............................................ 6-10

7 Tender Configuration ......................................................................7-1

Overview ....................................................................................................................... 7-1
Tender Type Database Setup .................................................................................... 7-2
Tender Database Setup............................................................................................... 7-2
Tender Options Database Setup............................................................................... 7-2
About Tender Authorization Components ................................................ 7-2
About Tender Franking Components ......................................................... 7-2
Tender Type/Tender Values...................................................................................... 7-3
Tender Denomination Setup..................................................................................... 7-4
Tender Availability Setup.......................................................................................... 7-4
Tender User Settings Setup ....................................................................................... 7-5
Tender Exchange Rate Setup ..................................................................................... 7-5
Check Tender Setup .................................................................................................... 7-6
Credit/Debit Card Setup............................................................................................. 7-6
Miscellaneous Tender Configuration Options...................................................... 7-6
SysConfig.xml ........................................................................................................ 7-6
Quick Cash Buttons............................................................................................... 7-7
System.Properties .................................................................................................. 7-8
Menu Config Configuration...................................................................................... 7-8
Credit Card Signatures Based on Tender Amount................................................ 7-9

vii
 Foreign Cash Currency As Change .......................................................................... 7-9
Upgrading From an Earlier Version of Xstore Point of Service.................... 7-10
Prior to version 7.0 ....................................................................................... 7-10
Version 7.0 and After ................................................................................... 7-10

8 Discount Configuration...................................................................8-1
Overview ....................................................................................................................... 8-1
Discount Database Setup ........................................................................................... 8-2
Associate a Customer Group to a Discount ............................................................ 8-2
Associate a Discount to a Transaction Type........................................................... 8-2
Associate Manufacturer's Coupon to a Discount .................................................. 8-2
Define Discount Item Exclusions and Inclusions ................................................. 8-2
Define Compatible Discounts................................................................................... 8-3
System Config Discount Options............................................................................. 8-3
Discounts in Return Transactions ....................................................................... 8-3
Discount Rounding Mode .................................................................................... 8-4
Line Item Discount Configuration Options....................................................... 8-4
Group Discount Configuration Options ............................................................ 8-5
You Saved Discount Options............................................................................... 8-5
Deal Data for Multiple Stores ................................................................................... 8-5
SysConfig.xml Settings ......................................................................................... 8-6

9 Commissioned Associate Configuration.......................................9-1

Overview ....................................................................................................................... 9-1
Assigning Commissioned Associates to a Sale Transaction ............................... 9-1
SysConfig.xml ........................................................................................................ 9-1
Commissioned Associates - Receipt Configuration.............................................. 9-4
Database Setup for Commission-Eligible Items ................................................... 9-4

10 Employee Configuration & Maintenance.....................................10-1

Overview ..................................................................................................................... 10-1
Employee Party Database Setup ............................................................................. 10-2
Employee E-mail Address Database Setup .......................................................... 10-2
ApplicabilityCondition....................................................................................... 10-2
Employee Address Database Setup ....................................................................... 10-2
Employee Telephone Information Database Setup............................................ 10-3
ApplicabilityConditions ..................................................................................... 10-3
Employee Password Database Setup ..................................................................... 10-5
Employee Detail Database Setup ........................................................................... 10-5
Assign the Employee to a Store............................................................................... 10-5
System Config Employee Configuration .............................................................. 10-5
Employee ID Number......................................................................................... 10-5
Employee List Display ........................................................................................ 10-5
Default Employee Group ................................................................................... 10-6
Default Customer Group for Employees .................................................. 10-6

viii
 Employee Search Location ................................................................................. 10-6
Employee Search Criteria ................................................................................... 10-6
Employee ID Length ........................................................................................... 10-6
Minimum Length ......................................................................................... 10-6
Maximum Length......................................................................................... 10-6
Employee Self-Sale .............................................................................................. 10-7
Employee Login Security ................................................................................... 10-7
Employee House Account ID ............................................................................ 10-7
Employee Security Groups ................................................................................ 10-7
Employee Challenge Questions Setup ............................................................. 10-7

11 Payroll, Timecard & Clock In/Out Configuration.........................11-1

Overview ..................................................................................................................... 11-1
Payroll and Timecard Work Code Database Setup............................................. 11-2
Payroll Category Database Setup ........................................................................... 11-2
Payroll Overtime Rule Configuration in System Config .................................. 11-2
Overtime Rule Type ............................................................................................ 11-2
Rule Examples .............................................................................................. 11-2
Payroll Options in System Config.......................................................................... 11-4
Process Payroll at Store Close............................................................................ 11-4
Payroll Options .................................................................................................... 11-4
Timecard Options in System Config ..................................................................... 11-7
Timecard Options ................................................................................................ 11-7
Timeclock Options............................................................................................... 11-8
Clock-in and Clock-out Restrictions Setup .......................................................... 11-9
Security Privilege Setup...................................................................................... 11-9
Setup Example: min_clock_in_duration ................................................. 11-10
Setup Example: min_clock_out_duration............................................... 11-10

12 Security Configuration ..................................................................12-1

Overview ..................................................................................................................... 12-1
Roles, Privileges, and Membership Groups......................................................... 12-1
Roles ...................................................................................................................... 12-1
Privileges............................................................................................................... 12-1
Membership Groups ........................................................................................... 12-2
Group Memberships With Multiple Group IDs ............................................. 12-2
The EVERYONE Group...................................................................................... 12-3
Technical Aspects of Group Memberships...................................................... 12-3
Speed .............................................................................................................. 12-3
Equivalent Values......................................................................................... 12-3
Employee Maintenance Security - Group Rank .................................................. 12-4
Sample Group Membership Settings................................................................ 12-5
Adding a New Group ID.................................................................................... 12-6
Assigning a Group Membership to a User in Xstore Point of Service......... 12-6
Security-Related Tables............................................................................................ 12-7
Security-Related Configuration: Menu Visibility .............................................. 12-7

ix
 Securing Forms and Fields....................................................................................... 12-7
sec_access_types Table........................................................................................ 12-8
User Login and Password Security......................................................................... 12-9
Requirements for Password Validation ......................................................... 12-10
Employee Challenge Questions Setup ................................................................ 12-11
SysConfig.xml Setup ......................................................................................... 12-11
Database Table Setup ........................................................................................ 12-12
Security Overrides & Secondary Approvals ...................................................... 12-12
sec_activity_log Table ....................................................................................... 12-12

13 Address Mapping...........................................................................13-1
Overview ..................................................................................................................... 13-1
Address Mapping ...................................................................................................... 13-1
Database Mapping............................................................................................... 13-1
File Mapping ........................................................................................................ 13-1
Database Tables ......................................................................................................... 13-2
Supported Address Service Modes ........................................................................ 13-2
Multiple Customer Addresses/Change Country ................................................. 13-2
Base Xstore Point of Service: General Considerations ................................... 13-2
Change Country ........................................................................................... 13-2
StoreLocationsAvailable.xml file ............................................................... 13-2
Addresses ..................................................................................................... 13-3

14 Shipping Fee Configuration..........................................................14-1

Overview ..................................................................................................................... 14-1
How Shipping Fees are Calculated ........................................................................ 14-1
Per Transaction Shipping Fee Calculation Strategy ....................................... 14-2
Per Item Shipping Fee Calculation Strategy.................................................... 14-3
Shipping Fee Setup ................................................................................................... 14-4
Configuration Files.............................................................................................. 14-4
SysConfig.xml ............................................................................................... 14-4
ShippingFeeConfig.xml............................................................................... 14-4
Database Tables ................................................................................................... 14-6
Shipping Fee Rules:...................................................................................... 14-6
FAQ: Shipping Fees .................................................................................................. 14-6
How do the minimum and maximum shipping prices work together? ..... 14-6
How are shipping fees calculated using the fee_type of SHIP_ITEM_PRICE?
14-6
If the rule_type column of the shipping fee record is blank, or the fee_value
= NULL, should Xstore Point of Service prompt for a shipping fee? .......... 14-7
If the fee_type column contains an invalid value or is blank, how are fees
processed?............................................................................................................. 14-7
When is the TRUE_RULE needed? ................................................................... 14-7
Do you have an example of where param1 and param2 are both filled in the
shipping_fee_tier table? ............................................................................ 14-7
Why are the TOTAL, AVERAGE, HIGHEST, and LOWEST aggregation methods

x
 used?...................................................................................................................... 14-7
What happens if multiple tiers have the same priority?................................ 14-7

15 Send Sale Configuration ...............................................................15-1

Overview ..................................................................................................................... 15-1
Send Sale Setup.......................................................................................................... 15-1
Create a Shipping Document............................................................................. 15-2
Automatically Generate a Shipping Fee ................................................... 15-2
Shipping Calculation Type ......................................................................... 15-2
Generate Weighted Shipping Fee .............................................................. 15-2
Use Customer as the Default Destination................................................. 15-3
Send Sale Tax Type ...................................................................................... 15-3
Use this Store as the Fail-Over Tax Rate ................................................... 15-3
Display Sold Item Count ............................................................................. 15-3
Print Send Sale Merchandise Ticket Per Item .......................................... 15-3
Unverified Returns: Prompt To Ask If Send Sale Item........................... 15-4
Shipping Document Type Used for Send Sale .................................................... 15-4

16 Warranty Setup & Configuration ..................................................16-1

Overview ..................................................................................................................... 16-1
Warranty Database Setup......................................................................................... 16-2
Warranty Configuration - System Config............................................................. 16-2
SysConfig.xml ...................................................................................................... 16-2
Autogenerate Warranty Id.......................................................................... 16-2
Customer Record Required ........................................................................ 16-2
Customer Acceptance Prompted ............................................................... 16-2
Notify When Any Warranty is Available ................................................. 16-3
Notify When No Warranty is Available ................................................... 16-3
Notify When One Warranty is Available.................................................. 16-3
Allow Warranty Not On File ...................................................................... 16-3
Warranty Configuration - Sequence Config......................................................... 16-4
SequenceConfig.xml............................................................................................ 16-4
WARRANTY................................................................................................. 16-4
WARRANTY_JOURNAL............................................................................ 16-4
Other Configuration Files ........................................................................................ 16-4

17 Return Transaction Configuration ...............................................17-1

Overview ..................................................................................................................... 17-1
Prorated Refund Amounts ....................................................................................... 17-2
Configuration File................................................................................................ 17-2
SysConfig.xml ............................................................................................... 17-2
Database Table ..................................................................................................... 17-2
How Prorated Amounts are Calculated........................................................... 17-2
Formula:......................................................................................................... 17-2
Example: ........................................................................................................ 17-3

xi
 Xstore Point of Service UI Prorated Refund Example ............................ 17-3
Returns from the Customer’s Purchase History .................................................. 17-4
Requirements ....................................................................................................... 17-4
Cross-Border Returns................................................................................................ 17-5
About Verified Returns....................................................................................... 17-5
About Unverified Returns.................................................................................. 17-5
SysConfig.xml Setup.................................................................................... 17-5
SysConfig.xml Configuration Options ................................................................. 17-7

18 Hardware/UI Configuration ...........................................................18-1

Overview ..................................................................................................................... 18-1
Hardware Options ..................................................................................................... 18-1
UI Options................................................................................................................... 18-1
Enable/Disable Hardware ........................................................................................ 18-2
Disable Device...................................................................................................... 18-2
Enable Device....................................................................................................... 18-2
HardwareConfig.xml File Example .................................................................. 18-3
To disable device(s)...................................................................................... 18-3
To enable device(s)....................................................................................... 18-3
Printer Selection......................................................................................................... 18-3
SysConfig.xml ...................................................................................................... 18-3
HardwareConfig.xml .......................................................................................... 18-4
QR Code Data Format......................................................................................... 18-4
Dual Monitor Setup .................................................................................................. 18-4
Setting Up Dual Monitors .................................................................................. 18-5
SysConfig.xml Example .............................................................................. 18-5
root system.properties File Configuration................................................ 18-5
UIConfig.xml & SubstituteComponentConfig.xml Setup...................... 18-5
View Type: AbstractListView..................................................................... 18-7
Virtual Signature Capture Setup ............................................................................ 18-8
TransArmor Registration ......................................................................................... 18-8
Operational Assumptions .................................................................................. 18-8
Touch-Screen Keyboard Setup................................................................................ 18-8
Keyboard Touch-Screen Functionality ............................................................. 18-9
Setting Up the Touch-Screen Keyboard ........................................................... 18-9
SysConfig.xml Setup.................................................................................... 18-9
KeyboardConfig.xml Setup ...................................................................... 18-10
Touch-Screen Configuration ................................................................................. 18-11
Touch-Screen Configuration Desktop and Thin Client................................... 18-11
UI Orientation Setup............................................................................................... 18-11
SysConfig.xml Setup ......................................................................................... 18-12
Color Theme ............................................................................................................. 18-12
Xstore Point of Service Self Checkout Classic ................................................... 18-13
OpChainConfig.xml .......................................................................................... 18-13
SysConfig.xml Configuration .......................................................................... 18-13
Xstore Point of Service Self Checkout ................................................................. 18-15

xii
 SysConfig.xml Configurations ........................................................................ 18-15
TableLayoutConfig.xml .................................................................................... 18-17
Styling and CSS Customization....................................................................... 18-19
Audio Files.......................................................................................................... 18-20
Start Button......................................................................................................... 18-21
PromptConfig.xml...................................................................................... 18-21
ActionConfig.xml ....................................................................................... 18-22
ui.properties ................................................................................................ 18-22
Self Checkout Console ...................................................................................... 18-23
How to Access............................................................................................. 18-23
Security ........................................................................................................ 18-23
Self Checkout Console Permissions......................................................... 18-23
Self Checkout Console's Activate Command......................................... 18-24
Open/Close Commands vs. Xstore's TRN_TRANSACTION .............. 18-24
Configurations ............................................................................................ 18-24
Self Checkout Console Customization .................................................... 18-25

19 ZPL II Label Configuration ............................................................19-1

Overview ..................................................................................................................... 19-1
Functional Assumptions..................................................................................... 19-1
Supported Printers..................................................................................................... 19-1
Fields and Layout....................................................................................................... 19-2
Fields available for printing........................................................................ 19-2
Base pre-defined templates......................................................................... 19-3
XML Configuration Files.......................................................................................... 19-5
SysConfig.xml ...................................................................................................... 19-5
HardwareConfig.xml .......................................................................................... 19-5
Database Tables ......................................................................................................... 19-5
Fields and Layout: XML Configuration File......................................................... 19-6

20 Store Sales Goals Setup ...............................................................20-1

Overview ..................................................................................................................... 20-1
Store Goals Tab .......................................................................................................... 20-2
Dashboard Store Goals Performance..................................................................... 20-2
Sales Goals Report..................................................................................................... 20-2
Configuration Options ............................................................................................. 20-3
SysConfig.xml ...................................................................................................... 20-3
Database Tables ......................................................................................................... 20-3

21 Store Replenishment Orders ........................................................21-1

Overview ..................................................................................................................... 21-1
Order Status.......................................................................................................... 21-1
Document Status.................................................................................................. 21-1
Line item status.................................................................................................... 21-2
Replenishment Order Setup Process ..................................................................... 21-2

xiii
 Database Setup........................................................................................................... 21-3
System Config Setup................................................................................................. 21-3
SysConfig.xml ...................................................................................................... 21-3
Non Merchandise Item Setup ................................................................................. 21-3
To Use Pack Size for Item Ordering ...................................................................... 21-4
To Search For Replenishment Documents By Source Entity ............................ 21-4
To Display The Source Of an Item......................................................................... 21-4

22 Workstation Configuration ...........................................................22-1

Overview ..................................................................................................................... 22-1
Workstation Database Setup ................................................................................... 22-1

23 Order Management System Options............................................23-1

Overview ..................................................................................................................... 23-1
Setup Required..................................................................................................... 23-1
Cross Channel Return Processing ..................................................................... 23-2

24 Customer Engagement Cloud Services Configuration..............24-1

Overview ..................................................................................................................... 24-1
Customer Records ............................................................................................... 24-1
Xstore Point of Service Transactions................................................................. 24-1
Service Handlers Settings ........................................................................................ 24-2
ServiceHandlers.xml ........................................................................................... 24-2
Example 1 ...................................................................................................... 24-2
Example 2 ...................................................................................................... 24-2
Example 3 ...................................................................................................... 24-3
Example 4 ...................................................................................................... 24-3
Example 5 ...................................................................................................... 24-4
Example 6 ...................................................................................................... 24-4
Example 7 ...................................................................................................... 24-4
Example 8 ...................................................................................................... 24-5
Example 9 ...................................................................................................... 24-5
Data Source Config Settings.................................................................................... 24-6
DataSourceConfig.xml........................................................................................ 24-6
Customer Engagement Cloud Services Security Settings ................................. 24-6
Security Access..................................................................................................... 24-6
System Properties Settings ................................................................................. 24-7
Customer Requests in Xstore Point of Service ................................................ 24-8
Customer Engagement Cloud Services Data Security in Xstore Point of Service
24-9
Posting Transactions to Customer Engagement Cloud Services in Real-time24-10
Customer Engagement Cloud Services Broadcaster ......................................... 24-10
Loyalty Card Setup .................................................................................................. 24-10
Sell/Renew Loyalty Cards ...................................................................................... 24-11
Customer Engagement Cloud Services Clienteling.......................................... 24-12

xiv
 Clienteling Customer Lookup ......................................................................... 24-12
FAQ: Customer Engagement Cloud Services real-time updates.................... 24-12
Oracle Retail Promotions Engine Integration .................................................... 24-13
Spring Files Configuration ............................................................................... 24-13
system.properties Settings................................................................................ 24-16
Xservices Settings .............................................................................................. 24-16
Additional Details ............................................................................................. 24-16

25 Order Broker Configuration..........................................................25-1

Overview ..................................................................................................................... 25-1
Order Functionality ................................................................................................... 25-1
Legacy ................................................................................................................... 25-1
New ....................................................................................................................... 25-1
Fulfillment Types ...................................................................................................... 25-2
Split Order Functionality ......................................................................................... 25-2
Email Functionality ............................................................................................. 25-3
Group Shipment ........................................................................................................ 25-3
Under Review Flag .................................................................................................... 25-4
Status Update Reason and Description................................................................. 25-4
Data That Must Be Populated in Xstore Office ................................................... 25-4
Xstore Point of Service Configurations ................................................................. 25-5
system.properties Settings.................................................................................. 25-5
ServiceHandlers.xml Settings ............................................................................ 25-5
SysConfig.xml Settings ....................................................................................... 25-6
Determining the Overall Order Status ................................................................ 25-10
Determining the Item Status ................................................................................. 25-11
Accepting an Order.................................................................................................. 25-12
Reserving an Order.................................................................................................. 25-12
Availability Update Message to Order Broker .................................................. 25-12

26 Collect and Receive (CaR) Configuration....................................26-1

Overview ..................................................................................................................... 26-1
Process Steps............................................................................................................... 26-1
Database Structures................................................................................................... 26-3
Spring Files Configuration ...................................................................................... 26-3
Data Settings for Shipper and Shipper Method.................................................. 26-4
Carton Label................................................................................................................ 26-5

27 Oracle Hospitality OPERA Property Management Configuration27-1

Overview ..................................................................................................................... 27-1
Enable the Room Charge and Room Charge Refund Tender ....................... 27-1
xstore.properties .................................................................................................. 27-1

28 Rotating Service Credentials for Integrated Systems................28-1

Overview ..................................................................................................................... 28-1

xv
 Rotating Credentials ................................................................................................. 28-1

29 Email Customer Receipts .............................................................29-1

Overview ..................................................................................................................... 29-1
About this Chapter .................................................................................................... 29-1
Set Up Email Receipts............................................................................................... 29-2
EmailReceipt.vm Example ................................................................................. 29-2
emailTemplate.properties Example .................................................................. 29-3
SysConfig.xml Example...................................................................................... 29-3
Always Send Email Receipts Flag .......................................................................... 29-4
Xstore Point of Service Setup ............................................................................. 29-5
Customer Engagement Cloud Services Setup................................................. 29-5
The Email Receipt Process in Xstore Point of Service ........................................ 29-6
Email Receipt method options........................................................................... 29-7
Send email receipt options ................................................................................. 29-7
Enhanced Email Receipt ........................................................................................... 29-8
Overview .............................................................................................................. 29-8
Xadmin - Enablement .................................................................................. 29-8
Xstore - Payload Creation ........................................................................... 29-8
Payload Detail............................................................................................... 29-8
Payload Implementation ............................................................................. 29-9
Xcenter - Long Poll Broadcaster ............................................................... 29-11

30 Rain Check Setup & Configuration ..............................................30-1

Overview ..................................................................................................................... 30-1
Assumptions ............................................................................................................... 30-1
Rain Check Configuration ....................................................................................... 30-2
SysConfig.xml Configuration ............................................................................ 30-2
Database Tables ................................................................................................... 30-2
sec_privilege Table ....................................................................................... 30-2
com_receipt_text Table ................................................................................ 30-2
itm_item Table .............................................................................................. 30-2
Receipt Setup........................................................................................................ 30-3

31 Customer Account Configuration ................................................31-1

Overview ..................................................................................................................... 31-1
Database Setup for CCA........................................................................................... 31-1
Configuration File Setup for CCA ......................................................................... 31-1
translations.properties ........................................................................................ 31-2
Add CCA-specific translations................................................................... 31-2
resources.properties ............................................................................................ 31-2
Add a help message reference from CustomerAccountConfig.xml ..... 31-2
MenuConfig.xml.................................................................................................. 31-2
Add a MenuOption reference to PRESALE action to
RETAIL::SPECIAL_ACCOUNTS menu.................................................... 31-2

xvi
 Add COMPLETE and CANCEL action references to
CUSTOMER_ACCOUNT menu ................................................................ 31-2
ActionConfig.xml ................................................................................................ 31-4
Add entries as shown below....................................................................... 31-4
OpChainConfig.xml ............................................................................................ 31-4
Add a starting point for a CCA .................................................................. 31-4
RcptConfig.xml .................................................................................................... 31-5
Add receipt copy rules ................................................................................ 31-5
Added receipts ..................................................................................................... 31-5
SequenceConfig.xml............................................................................................ 31-5
Add entry for CCA....................................................................................... 31-5
PreFlightQueryConfig.xml................................................................................. 31-5
Add entry for CCA....................................................................................... 31-5
InputConfig.xml .................................................................................................. 31-6
Add entry for barcode scan......................................................................... 31-6
Add entry in ProcessingOrder section ...................................................... 31-6
EventConfig.xml .................................................................................................. 31-6
Add entry to SELLING EventActionMap section ................................... 31-6
Add entry to CUST_ACCOUNT EventActionMap section ................... 31-7
CustomerAccountConfig.xml (PRESALE Example) ...................................... 31-7
ComponentGroupConfig.xml file ..................................................................... 31-8
ComponentPropertySetConfig.xml file.......................................................... 31-10
ContextConfig.xml file...................................................................................... 31-10

32 Customer Maintenance Configuration.........................................32-1

Overview ..................................................................................................................... 32-1
Customer Wish List ................................................................................................... 32-1
Customer Wish List Setup.................................................................................. 32-1
Item Setup...................................................................................................... 32-1
System Config Setup.................................................................................... 32-1
Customer Attributes.................................................................................................. 32-2
When Xstore Point of Service uses Customer Engagement Cloud Services32-2
When Xstore Point of Service uses Xstore Office (not Customer Engagement
Cloud Services) .................................................................................................... 32-3
Customer Attributes Database Setup ............................................................... 32-3
com_code_value Table................................................................................. 32-3
Activity Stream........................................................................................................... 32-4
Special Orders in the Activity Stream .............................................................. 32-4
Activity Stream Setup ......................................................................................... 32-4
SysConfig.xml Settings ................................................................................ 32-4
ActivityStreamConfig.xml Settings ........................................................... 32-5
Loyalty Expiration Display Setup ..................................................................... 32-6
Gift Registry ............................................................................................................... 32-6
Gift Registry Setup .............................................................................................. 32-7
system.properties Settings .......................................................................... 32-7
SysConfig.xml Settings ................................................................................ 32-7
Database Settings.......................................................................................... 32-8

xvii
 Customer Birthdate Options.................................................................................... 32-9
SysConfig.xml Setting......................................................................................... 32-9
Task Management ..................................................................................................... 32-9
Tasks Tab ............................................................................................................ 32-10
About the Tasks Tab .................................................................................. 32-10

33 SSL Cert Check at Startup ............................................................33-1

Overview ..................................................................................................................... 33-1
Where the information is logged ............................................................................ 33-1
Configuration Options ............................................................................................. 33-2
system.properties ....................................................................................................... 33-2
Spring Configuration................................................................................................ 33-2

34 Update Services & File Movement ...............................................34-1

Update Services Overview....................................................................................... 34-1
Update Services Setup .............................................................................................. 34-1
File Movement Between Xstore Office and Xenvironment............................... 34-2
File Movement Process Overview..................................................................... 34-2

35 Context-Sensitive Help..................................................................35-1
Overview ..................................................................................................................... 35-1
About this Chapter .................................................................................................... 35-1
Setting Up Context-Sensitive Help ........................................................................ 35-1
The Basic Elements .............................................................................................. 35-3

36 Translation Files ............................................................................36-1

Overview ..................................................................................................................... 36-1
For more information.......................................................................................... 36-1
Translation File Rules............................................................................................... 36-2
New line ................................................................................................................ 36-2
Spaces at the beginning or end of a line........................................................... 36-2
Key Code mappings............................................................................................ 36-2
Example ......................................................................................................... 36-2
Escaped Unicode characters ....................................................................... 36-3

37 Xstore Point of Service Log Files.................................................37-1

Overview ..................................................................................................................... 37-1
About this Chapter .................................................................................................... 37-1
Xstore Point of Service Wrapper Log Files ........................................................... 37-1
Logs Configured/Controlled in log4j2................................................................... 37-2
log4j2.xml.............................................................................................................. 37-2
DataPurger - Controlled By log4j2............................................................. 37-3
DataServer - Controlled By log4j2.............................................................. 37-3
DataProcessor - Controlled By log4j2........................................................ 37-3

xviii
 DataLoader - Controlled By log4j2 ............................................................ 37-3
Transaction replicator - Controlled By log4j2 .......................................... 37-4
Xstore Point of Service Log Files - Transactional Data ...................................... 37-4
Log Controlled By the VeriFone Driver ................................................................ 37-5
Other Logs ................................................................................................................... 37-5
Log Tables Controlled by Xstore Point of Service and log4j2 .......................... 37-6
Log Troubleshooting Tips - xstore.log................................................................... 37-6
xstore.log logging level examples ..................................................................... 37-6
Operations ..................................................................................................... 37-7
Version Info................................................................................................... 37-7
Location Info ................................................................................................. 37-8
Configuration File Loading......................................................................... 37-8
Logging for Validation Rules.................................................................................. 37-8

38 Menu & Tab Configuration............................................................38-1

Overview ..................................................................................................................... 38-1
Menu Configuration ................................................................................................ 38-1
Functional Areas.................................................................................................. 38-1
MenuConfig.xml Example: SEND_SALE ........................................................ 38-2
The Components .......................................................................................... 38-3
About Menu Navigation .......................................................................................... 38-6
How it works—Change Item Menu Example ................................................. 38-6
About this configuration .................................................................................... 38-7
Hide Menu Options Based on Security Privilege ............................................... 38-7
Configurable Button Layout.................................................................................... 38-7
SysConfig.xml example ...................................................................................... 38-8
system.properties example................................................................................. 38-8
UIConfig.xml example........................................................................................ 38-8
Button Layout Example: 10 Buttons in 2 Rows ............................................... 38-9
Set SysConfig.xml......................................................................................... 38-9
Set UIConfig.xml .......................................................................................... 38-9
Tab Setup .................................................................................................................... 38-9
Tab Library Options .......................................................................................... 38-10
TabConfig.xml Setup ........................................................................................ 38-12
Tab Component Property Set Example (MESSAGE_AREA)............... 38-12
ComponentPropertySetConfig.xml ................................................................ 38-13
ui-beans.xml Spring File ................................................................................... 38-13
SysConfig.xml Settings ..................................................................................... 38-14
Quick Items Tab.......................................................................................... 38-14
Associate Tasks Tab ................................................................................... 38-14
Tab Setup Options ............................................................................................. 38-15
Item Selection Grid ................................................................................................. 38-15
Enabling the Button Matrix.............................................................................. 38-16
com_button_grid Table..................................................................................... 38-16
Xstore Context and Button Matrix .................................................................. 38-16
Drilldown Button............................................................................................... 38-16
Button Coloring ................................................................................................. 38-16

xix
39 BIN Ranges.....................................................................................39-1
Overview ..................................................................................................................... 39-1
Specifications.............................................................................................................. 39-1
Examples............................................................................................................... 39-2
File Naming Conventions ........................................................................................ 39-2

40 Data Purger Overview ...................................................................40-1

Overview ..................................................................................................................... 40-1
Assumptions ............................................................................................................... 40-1
Specifications.............................................................................................................. 40-2
Data Purger Configuration ...................................................................................... 40-2
About Purge Config .................................................................................................. 40-3
PurgeConfig.xml.................................................................................................. 40-3
PurgeConfig.xml example .......................................................................... 40-4
purges.*.xml.......................................................................................................... 40-5
purges.xom.xml example ............................................................................ 40-5
Tables Available for Purging .................................................................................. 40-6
General Table Information ................................................................................. 40-6
Detail Table Information .................................................................................... 40-6
Transactional Purges........................................................................................... 40-7
Non-Transactional Purges................................................................................ 40-11

41 Xstore Point of Service Management Console ...........................41-1

Overview ..................................................................................................................... 41-1
Debug Domains ......................................................................................................... 41-2
Cache Status ......................................................................................................... 41-2
Data Source Status............................................................................................... 41-3
LogLevelConfig ................................................................................................... 41-4
PosDebugger ........................................................................................................ 41-5
ReceiptDebugger ................................................................................................. 41-6
General Domain......................................................................................................... 41-7
Tlog Generation ................................................................................................... 41-7
Information Domain ................................................................................................. 41-8
AuthManager ....................................................................................................... 41-8
ClassPathInformation ......................................................................................... 41-9
ConfigurationInformation................................................................................ 41-10
HardwareDeviceManager ................................................................................ 41-13
PrintQueueMgr.................................................................................................. 41-14

42 Transaction Replicator..................................................................42-1
Overview ..................................................................................................................... 42-1
Run the Transaction Replicator Utility ................................................................. 42-2

xx
 43 Internationalization........................................................................43-1
Overview ..................................................................................................................... 43-1
About this Chapter .............................................................................................. 43-1
Internationalization (i18n) ....................................................................................... 43-2
Implementing i18n .............................................................................................. 43-2
Applications of Internationalization in Xstore Point of Service ................... 43-2
Internationalization (i18n) and Localization (L10n) ....................................... 43-3
Multilingualization (m17n) ................................................................................ 43-3
Xstore Point of Service i18n Implementation....................................................... 43-3
Java Standards...................................................................................................... 43-3
Language Codes .................................................................................................. 43-3
Configure Languages in Xstore Point of Service ............................................ 43-4
Sample Entries in LocaleMap.xml: ............................................................ 43-4
Language Files ..................................................................................................... 43-4
Individual Customization .................................................................................. 43-5
Translation Resource Bundles ........................................................................... 43-6
Language and Country................................................................................ 43-6
Define Common Mappings for Different Keys........................................ 43-7
Xstore Office and SystemConfigMetadata.properties........................................ 43-8
i18n and the SystemConfigMetadata.properties File ..................................... 43-8
SystemConfigMetadata.properties File Example .................................... 43-9
Creating a "Stub" Metadata File for Other Languages............................ 43-9

44 Xstore Mobile Configuration.........................................................44-1

Overview ..................................................................................................................... 44-1
system.properties................................................................................................. 44-1
ctl_mobile_server Table ...................................................................................... 44-1
SysConfig.xml Settings ....................................................................................... 44-2
Sequences.............................................................................................................. 44-3

45 Temporary Store Configuration ...................................................45-1

Overview ..................................................................................................................... 45-1
Temporary Store Topology ...................................................................................... 45-1
Data Seeding............................................................................................................... 45-1
Deployments and Foundation Data ....................................................................... 45-1
Extension Store Configurations .............................................................................. 45-2
Temporary Store Mobile Server ........................................................................ 45-2
Xenvironment ............................................................................................... 45-2
Xstore Mobile Server.................................................................................... 45-2
Temporary Store Event Polling Interval .......................................................... 45-2
Websocket Heartbeat Interval ........................................................................... 45-3
Persistent Timeout............................................................................................... 45-3
Security/Authentication...................................................................................... 45-3
Security and Authentication Considerations ........................................... 45-4
IDCS Credentials .......................................................................................... 45-4

xxi
 Service IDs ............................................................................................................ 45-4
Operational Data ................................................................................................. 45-4
Replication..................................................................................................... 45-4
Creating a Temporary Store Request ........................................................ 45-6
Security Privileges........................................................................................ 45-7
Xcenter Temporary Store Services ............................................................. 45-7
Purging of Temporary Store Request Data........................................................... 45-7

46 Transaction Attachments..............................................................46-1
Overview ..................................................................................................................... 46-1
Additional Information on Different Attachment Types.................................. 46-2

47 Vertex Integration ..........................................................................47-1

Overview ..................................................................................................................... 47-1
Base Feature.......................................................................................................... 47-1
Installer.................................................................................................................. 47-1
xstore.properties ........................................................................................... 47-1
ant.install.properties .................................................................................... 47-1
SSL Certificates (If applicable).................................................................... 47-2
OAuth2 secrets (If applicable) .................................................................... 47-2
Standard Basic Authentication Credentials (If applicable) .................... 47-2
Sample Tax Calculation Request............................................................................ 47-2
Request.................................................................................................................. 47-2
Vertex to Xstore Request Mappings....................................................................... 47-4
Product Class and Value Mapping Configuration ......................................... 47-6
Sample Tax Calculation Response ......................................................................... 47-8
Response ............................................................................................................... 47-8
Vertex to Xstore Response Mapping.................................................................... 47-14
Sample Tax Area Lookup Request (Vertex Tax-Area-Lookup ) ..................... 47-15
Tax Area Lookup Request ................................................................................ 47-15
Vertex to Xstore Request Mappings..................................................................... 47-15
Sample Tax Area Lookup Response .................................................................... 47-16
VERTEX to Xstore Response Mappings.............................................................. 47-18
Logging ...................................................................................................................... 47-18
Store Configuration................................................................................................. 47-19

A Configuration Files ......................................................................... A-1

Overview ...................................................................................................................... A-1
Key XML Configuration Files .................................................................................. A-1
Initial Xstore Point of Service Configuration........................................................ A-4
system.properties.................................................................................................. A-4
System Config Metadata ........................................................................................... A-5
Overview - Xstore Office SysConfig GUI.......................................................... A-5
SystemConfigMetadata.properties ............................................................. A-5
Metadata Information .......................................................................................... A-5

xxii
 SystemConfigMetadata.properties sample ............................................... A-6
I18N Information .................................................................................................. A-6

B EFTLink............................................................................................ B-1
Overview .......................................................................................................................B-1
Xstore Point of Service, EFTLink, and Payment Service Provider Responsibilities
B-1
EFTLink and Xstore Point of Service .................................................................. B-1
Xstore Point of Service Setup to Use EFTLink.......................................................B-2
AuthConfig.xml ...........................................................................................................B-4
Parameters in AuthConfig.xml............................................................................ B-4
PED Pooling in EFTLink ............................................................................... B-4
Auth Request Map ......................................................................................... B-5
SysConfig.xml ..............................................................................................................B-6
Processing Overview...................................................................................................B-6

C Address, Email and Phone Number Verification ......................... C-1

Overview .......................................................................................................................C-1
Config Paths..................................................................................................................C-1
Experian Address Verification (Manual) ................................................................C-1
Enable/Disable the Address Lookup Function Globally .................................C-1
Enable/Disable the Address Lookup Function By Individual Country ........C-2
Setup and Maintain username/password ..........................................................C-3
Indicating Web Service End Point to be Used...................................................C-3
Parametrize the (Address Search) Field Prompts.............................................C-3
QAS Engine Properties and Country Code Conversion..................................C-4
Engine Properties ...........................................................................................C-4
Country Code Conversion, Engine Type and Address Layout AdaptersC-4
State Name to State Code Conversion................................................................C-7
system.properties - Experian Address Verification (Manual) ........................C-8
Experian Address Verification (Auto) .....................................................................C-9
Mobile Configuration............................................................................................C-9
Alternative Layout Configuration ......................................................................C-9
States Mapping Beans .........................................................................................C-10
Adding A New Country.....................................................................................C-11
system.properties - Experian Address Verification (Auto) ...........................C-12
Experian Email Address Verification ....................................................................C-13
Adding the QAS Email Validation....................................................................C-13
Web Service Configuration ................................................................................C-14
SysConfig.xml Settings - Experian Email Address Verification ...................C-14
system.properties - Experian Email Address Verification ............................C-15
Experian Phone Number Verification ...................................................................C-15
Adding the QAS Phone Validation...................................................................C-15
Web Service Configuration ................................................................................C-16
SysConfig.xml Settings - Experian Phone Number Verification ..................C-16
system.properties - Experian Phone Number Verification ...........................C-17

xxiii
D Xstore Point of Service Configuration Path ................................. D-1
Overview ...................................................................................................................... D-1
Configuration Path Retrieval Process..................................................................... D-1
Xstore Office Config Path Properties Assembly .................................................. D-2
Global Configurations Path Properties ............................................................. D-2
xstore.config.path.global.extensions........................................................... D-8
xstore.config.path.base.features .................................................................. D-8
Workstation Overrides Config Path Properties ............................................. D-10
xstore.config.path.workstation.overrides.X ............................................ D-11
xstore.config.path.overrides.store.Y ......................................................... D-11
Xstore Point of Service Config Path Assembly................................................... D-11
If Xcenter Is Not Used to Get the Config Path ............................................... D-12
Resource Bundle Path Consolidation ................................................................... D-13

E Xstore Point of Service Root Directories ..................................... E-1

Overview ....................................................................................................................... E-1
Xstore Point of Service Directories List................................................................... E-1
Xstore Point of Service Mobile Directory ............................................................... E-3

F Revision History ..............................................................................F-1

Version 23.0.0, Revision 03......................................................................................... F-1
Version 23.0.0, Revision 02......................................................................................... F-1
Version 23.0.0, Revision 01......................................................................................... F-1
Version 22.0, Revision 03............................................................................................ F-2
Version 22.0, Revision 02............................................................................................ F-2
Version 22.0, Revision 01............................................................................................ F-2
Version 21.0, Revision 02............................................................................................ F-3
Version 21.0, Revision 01............................................................................................ F-3
Version 20.0.1, Revision 02......................................................................................... F-4
Version 20.0.1, Revision 01......................................................................................... F-4
Version 20.0, Revision 03............................................................................................ F-4
Version 20.0, Revision 02............................................................................................ F-5
Version 20.0, Revision 01............................................................................................ F-5
Version 19.0.1, Revision 01......................................................................................... F-6
Version 19.0, Revision 05............................................................................................ F-6
Version 19.0, Revision 04............................................................................................ F-6
Version 19.0, Revision 03............................................................................................ F-6
Version 19.0, Revision 02............................................................................................ F-6
Version 19.0, Revision 01............................................................................................ F-7
Version 18.0.1, Revision 01......................................................................................... F-8
Version 18.0, Revision 05............................................................................................ F-8
Version 18.0, Revision 04............................................................................................ F-8
Version 18.0, Revision 03............................................................................................ F-8
Version 18.0, Revision 02............................................................................................ F-9
Version 18.0, Revision 01............................................................................................ F-9

xxiv
 Version 17.0, Revision 03............................................................................................ F-9
Version 17.0, Revision 02............................................................................................ F-9
Version 17.0, Revision 01.......................................................................................... F-10
Version 16.0.2, Revision 01....................................................................................... F-10
Version 16.0.0.1, Revision 03.................................................................................... F-10
Version 16.0.0.1, Revision 02.................................................................................... F-11
Version 16.0.0.1........................................................................................................... F-11
Version 16.0, Revision 02.......................................................................................... F-11
Version 16.0................................................................................................................. F-11
Version 15.0, Revision 02.......................................................................................... F-12

xxv
 Send Us Your Comments

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 Help Center (docs.oracle.com) 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

xxvi
 Preface

This guide describes the technical frameworks used in the development of Xstore Point
of Service.

Audience
This Technical Guide is for administrators and programmers of Oracle Retail Xstore
Point of Service.

Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility
Program website at http://www.oracle.com/pls/topic/
lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For
information, visit http://www.oracle.com/pls/topic/
lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/
lookup?ctx=acc&id=trs if you are hearing impaired.

Related Documents
For more information, see the following documents in the Xstore Point of Service 23.0.0
documentation set:
• Xstore Suite Release Notes
• Xstore Suite Implementation and Security Guide

Customer Support
To contact Oracle Customer Support, access My Oracle Support at the following URL:
https://support.oracle.com
When contacting Customer Support, please provide the following:
• Product version and program/module name
• Functional and technical description of the problem (include business impact)
• Detailed step-by-step instructions to re-create
• Exact error message received
• Screen shots of each step you take

Review Patch Documentation

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

xxvii
 patch releases can contain critical information related to the base release, as well as
information about code changes since the base release.

Oracle Retail Documentation on the Oracle Help Center (docs.oracle.com)

Oracle Retail product documentation is also available on the following Web site:
https://docs.oracle.com/en/industries/retail/index.html
(Data Model documents can be obtained through My Oracle Support.)

Conventions
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.”
This is a code sample
It is used to display examples of code

xxviii
xxix
 1
Introduction

Overview
Note: It is assumed Xstore Office will now be used to configure
Xstore Point of Service. The purpose of this guide is to provide
information about Xstore Point of Service’s features and the underlying
technology, as well as general troubleshooting information.
Refer to the Xstore Office User Guide for configuration information.

This guide provides fundamental information about Xstore Point of Service

configuration, and includes a technical description of many base Xstore Point of Service
functions. By describing these core functions, this guide has been designed to provide
the reader with a basic overview of Xstore Point of Service and the technology
underlying its design. This guide is not intended as a complete technical guide to every
facet of Xstore Point of Service; however, it includes information to provide a better
understanding of the software and how it works.
This guide contains the best information available at the time of publication, and was
created in order to provide a source of reference for Xstore Point of Service functionality
in the base environment. The information in this guide is for use by internal Oracle
personnel, and is intended to be a guide for QA Analysts, Development Engineers, and
Implementation Consultants.
All information in this guide is subject to interpretation based on internal test
methodologies which were used to derive the various performance criteria, and should
be reviewed with Oracle development staff prior to implementation in a live
environment.

Introduction 1-1
Configuration Changes Using Xstore Office

Configuration Changes Using Xstore Office

The Config Manager module in the Xstore Office application uses a wizard format to
make it easier to manage Xstore Point of Service configurations through Xstore Office.
When a user makes a change using the Configurator, the option is “marked up” to
indicate the configuration option has been changed. This makes overridden
configurations easily identifiable to the user.
This option replaces the standard process of manually managing the SysConfig.xml file.
See the Xstore Office User Guide for more information. It is assumed Xstore Office will be
used to configure Xstore Point of Service.

Note: If you use the Xstore Office configuration tool, SysConfig.xml

files should not be created manually and installed in any store/register
(via config path).
If any SysConfig.xml files are manually created and installed in any
store/register (via config path), the changes they contain will work in
Xstore Point of Service as they always have; however, these
configurations will be totally unknown to the Xstore Office System
Config feature and may possibly impair its ability to work properly.
See “System Config Metadata” in Appendix A: “Configuration Files”.

Audience
This guide is intended for technical personnel working with Xstore Point of Service. This
can include anyone responsible for altering or creating process flows, configuring Xstore
Point of Service, or those who are looking for a more fundamental understanding of
Xstore Point of Service. Anyone using this guide should have a working knowledge of
XML, SQL databases, the Windows or Linux operating systems, and the network system
being used.

About this Guide

• Chapter 2, “Version Numbers” - This chapter provides information about the Xstore
Point of Service version number components, what each number represents, and
where the version number appears in the application.
• Chapter 3, “Organization Hierarchy Configuration” - This chapter provides
information about setting up the retail location hierarchy. The hierarchy is based on
customer requirements, but commonly includes values such as CHAIN, REGION,
DISTRICT, and STORE. The levels are completely arbitrary; what is important is the
connection between the levels.
• Chapter 4, “Tax Setup & Configuration” - This chapter provides information about
the tax options, including tax schemes such as sales tax, VAT, and compound taxes.
All sales taxes are calculated using two parameters: where the store is located and
which item is being sold. The “where” is important in order to determine the taxing
authorities to which the store is subject. The “item” is significant, since authorities
may tax different items according to different rules.
• Chapter 5, “Item and Pricing Configuration” - This chapter provides information
about the “location-based hierarchical pricing” structure which provides prices to
Xstore Point of Service by looking up items in a location hierarchy. Since item setup
is closely tied to item pricing, both item setup and pricing setup processes are
covered in this chapter.

1-2 Technical Guide

 About this Guide

• Chapter 6, “Item Messaging Configuration” - This chapter provides information

about setting up messages that may be displayed in the information section of the
register screen during a sale transaction.
• Chapter 7, “Tender Configuration” - This chapter provides information about
setting up and managing tender types for your store.
• Chapter 8, “Discount Configuration” - This chapter provides information about the
discount setup process, using both database tables and configuration files.
• Chapter 9, “Commissioned Associate Configuration” - This chapter provides
information about the configurations that support the assignment of sales associates
from within a sale transaction. This configuration determines whether sales
commission can be distributed on line items within that sales transaction (including
returns, layaways etc.).
• Chapter 10, “Employee Configuration & Maintenance” - This chapter provides
information about the employee configurations available in Xstore Point of Service,
and includes the steps necessary to enter or update any information about the
employees who work for an organization. The amount of employee information you
maintain can be very basic or highly detailed, depending on your business needs.
• Chapter 11, “Payroll, Timecard & Clock In/Out Configuration” - This chapter
provides information about the process required to set up payroll and timecards for
your stores.
• Chapter 12, “Security Configuration” - This chapter provides information about
restricting user access to only those parts of the system that are needed to perform
the requirements of a role. Because Xstore Point of Service security is role-based,
user roles, membership groups, and privileges must be defined so that security may
be applied correctly.
• Chapter 13, “Address Mapping” - This chapter provides information about the
conversion of address mapping data from flat files to database records and
information about multiple customer addresses in Xstore Point of Service.
• Chapter 14, “Shipping Fee Configuration” - This chapter provides information about
specifying shipping fees for ship item accounts. Several elements can be taken into
account when determining shipping fees, including account type, retail location,
shipping method, and the item to be shipped. Shipping fees can be calculated on a
per-item basis, or a per-transaction basis, with several fee aggregation strategies.
• Chapter 15, “Send Sale Configuration” - This chapter provides information about
setting up the system for send sale processing. A send sale item is an item that must
be shipped to a customer-specified offsite location after it is purchased.
• Chapter 17, “Return Transaction Configuration” - This chapter provides information
about return processing enhancements including the ability to accept returns for
transactions processed by outside systems, the ability to locate items for return using
customer history, the ability to locate items for return using the credit card used in
the sale transaction, and the ability to allow refund amounts to be prorated on a per-
item basis.
• Chapter 16, “Warranty Setup & Configuration” - This chapter provides information
about the warranty setup process, using both database tables and configuration files.
• Chapter 18, “Hardware/UI Configuration” - This chapter provides information
about the process used to temporarily disable hardware devices.

Introduction 1-3
About this Guide

• Chapter 19, “ZPL II Label Configuration” - This chapter provides information about
using ZPL II (Zebra Programming Language) for communicating with label printers
for barcode label printing.
• Chapter 20, “Store Sales Goals Setup” - This chapter provides information about
importing store sales goals for a store into Xstore Point of Service where they can be
viewed by store associates.
• Chapter 21, “Store Replenishment Orders” - This chapter provides information
about store replenishment order management. This feature provides the ability for
stores to review and change inventory replenishment suggested orders that are
generated and downloaded from the home office or a third-party system. Stores may
also prepare new inventory replenishment and purchase order requests.
• Chapter 22, “Workstation Configuration” -This chapter provides information about
workstation configurations.
• Chapter 23, “Order Management System Options”- This chapter provides
information about using CW Order Management System as the System of Record
(SOR) for customer information.
• Chapter 24, “Customer Engagement Cloud Services Configuration” - This chapter
provides information about submitting a real-time add/update of a customer record
during a transaction to a 3rd party CRM system through the Web-service.
• Chapter 25, “Order Broker Configuration” - This chapter provides information
about the configurations that support the Oracle Retail Order Broker Cloud Service.
This optional module can be interfaced with Xstore Point of Service to provide
information about inventory availability across all sales channels.
• Chapter 27, “Oracle Hospitality OPERA Property Management Configuration”-
This chapter provides information about the configurations that support the Oracle
Hospitality OPERA Property Management. This optional module can be interfaced
with Xstore Point of Service.
• Chapter 28, “Rotating Service Credentials for Integrated Systems”- This chapter
provides information about how to rotate service credentials in Xstore Point of
Service for integrated systems.
• Chapter 29, “Email Customer Receipts” - This chapter provides information about
automatically sending receipts from a retail transaction to a customer’s valid email
address. After a retail transaction is completed, any receipts configured to be
emailed will be rendered as PDF documents, and sent to the customer's email
address as email attachments.
• Chapter 30, “Rain Check Setup & Configuration” - This chapter provides
information about setting up rain check functionality. Rain checks are issued to
customers that request an item that is out of stock. It allows the customer to
purchase the item at today's price at a later date (once stock is replenished).
• Chapter 31, “Customer Account Configuration” - This chapter provides information
about the configurations that support Configurable Customer Accounts (CCAs).
These accounts provide the ability to define unique customer account types, giving
retailers the flexibility to manage account types with different business rules.
• Chapter 32, “Customer Maintenance Configuration” - This chapter provides
information about implementing and maintaining the Customer Wish List and
Customer Attributes features.
• Chapter 33, “SSL Cert Check at Startup” - This chapter provides information about
the SSL check performed on the expiration dates of certificates used for SSL
communication with Xstore Office at startup.

1-4 Technical Guide

 About this Guide

• Chapter 34, “Update Services & File Movement” - This chapter provides summary
information at a high level about the Xstore Point of Service call made to the Update
Service on a scheduled interval to retrieve new manifests. Checking the update
service at regular intervals throughout the day provides the ability to pull down
data changes to stores in real time.
• Chapter 35, “Context-Sensitive Help” - This chapter provides information about
associating an HTML help file with an existing context. This chapter also provides
information about using dynamic flash content on the login screen.
• Chapter 36, “Country Pack Configuration” - This chapter provides information
about configurations available in country packs.
• Chapter 36, “Translation Files” - This chapter provides information about the Xstore
Point of Service translation files used for all messages and prompts in the system.
• Chapter 37, “Xstore Point of Service Log Files” - This chapter provides information
about the Xstore Point of Service log files, including a brief description of the file and
where it can be configured. The Log Troubleshooting Tips section briefly describes how
you can use the xstore.log file to troubleshoot an issue.
• Chapter 38, “Menu & Tab Configuration” - This chapter provides information about
hiding menu options based on security privilege, MenuConfig.xml options,
TabConfig.xml options, and configuring the menu button layout.
• Chapter 39, “BIN Ranges” - This chapter provides information about the BIN range
values that must be downloaded to Xstore Point of Service for authorized card
tenders.
• Chapter 40, “Data Purger Overview” - This chapter provides information about the
Data Purger application used for maintaining the database by deleting records
according to a set of configuration parameters.
• Chapter 41, “Xstore Point of Service Management Console” - This chapter provides
information about the Java Management Extensions (JMX) application that runs in
the background when Xstore Point of Service is running and allows users with the
appropriate security level to view system information about the application.
• Chapter 42, “Transaction Replicator” - This chapter provides information about the
Transaction Replicator utility which is used to retrieve transactions from the Store
Primary data source and add them to the replication queue on the system where the
utility is run.
• Chapter 43, “Internationalization”- This chapter provides a general overview of
internationalization, localization, and multilingualization, and describes how these
concepts are implemented and configured in Xstore Point of Service.
• Chapter 44, “Xstore Mobile Configuration” - This chapter provides information
about the Xstore Mobile configurations.
• Chapter 45, “Temporary Store Configuration” - This chapter provides information
about the temporary store configurations.
• Appendix A: “Configuration Files” - This appendix lists the various Xstore Point of
Service configuration files and directories, along with a brief description of their
effect on Xstore Point of Service processing.
• Appendix B: “EFTLink” - This appendix explains how to setup Xstore Point of
Service for EFTLink and provides an overview of the EFTLink process.

Introduction 1-5
About this Guide

• Appendix D: “Xstore Point of Service Configuration Path” - This appendix provides

information about config path retrieval and assembly in Xstore Point of Service and
Xstore Office.
• Appendix E: “Xstore Point of Service Root Directories” - This appendix lists the
Xstore Point of Service root directories and a brief description of the files contained
within them.

1-6 Technical Guide

 2
Version Numbers

Overview
Every modification to the Xstore Point of Service application results in a change to the
version number. To track these changes, the Xstore Point of Service version number
consists of three components:
1. Base Version
2. Customer Version
3. Patch Level
- For Xstore Office, the version number is visible in the following locations:
* On the splash screen.
* On the help screen.
* By pressing Alt+V.
* In the xstore.log file:
********************
VERSION INFORMATION
********************
Xstore version 18.0.0.0.414 - 0.0.0 - 0.0 (Tue Aug 21 22:10:32
CEST 2018)
Database [LOCAL] version 18.0.0.0.414 - 0.0.0 - 0.0 (2018-10-11
12:52:15.28)
Database [STORE] version 18.0.0.0.414 - 0.0.0 - 0.0 (2018-10-11
12:52:15.28)
Database [CENTRAL] version 18.0.0.0.414 - 0.0.0 - 0.0 (2018-10-11
12:52:15.28)
- For Xstore Office, the version number is visible in the following locations:
* In the Xstore Office version page.
* In the xcenter.log file:
2018-10,-11 11:37:19,178 INFO [WrapperSimpleAppMain]
[com.micros_retail.xcenter.bootstrap] Xcenter Version:
1.0.0.0.414 - 0.0.0 - 0.0

Version Numbers 2-1

About this Chapter

About this Chapter

This chapter describes what each component of the Xstore Point of Service version
number represents.

Formats
The version numbers are displayed in the format:
Base Version - Customer Version (including Patch Version)
Which displays as:
18.0.0.0.414 - 0.0.0 - 0.0

BASE CUSTOMER

Major # Maint. Release # Release # Customer Build # Patch #

A. B. C. D. E. F. G. H. I.

Minor # Build # Incremented each time code is Patch #

released to the customer

Base Version
The Base Version is made up of 4 components, separated by a decimal point.
A. Major Version
B. Minor Version
C. Maintenance (bug-fix) release number
D. Patch Release Number
Note: All subsequent version values are reset to 0 each time a new
major, minor, or maintenance release begins. For example, when the
Minor Version is incremented, both the Maintenance and Build
numbers are reset to 0.

Customer Version
The Customer Version is a series of 5 numbers in the format: 0.0.0 - 0.0. In order to
maintain consistent usage of the Customer Version for all customers, the following
versioning scheme is used:
E. Major Release Number - The Xstore Point of Service release for the customer. For a
pilot release, this will start at 1. This number corresponds to the project name. So while
working on the XYZ Release 6 project, the Major Release component of the customer
version would be 6. XYZ Release 2 would start with 2, and so on.

2-2 Technical Guide

 Where the Information is Stored

F. Customer Release Number - The number of releases to a customer lab for a given
Major Release. This will start at 1 for the first build delivered to a customer. As soon as
that build is delivered, the Customer Release version would change to 2. So the version
number of an initial pilot release on its 2nd release to a customer would start with 1.2.x.
G. Internal Build Number - The number of interim releases to the Oracle lab for a given
customer release. This will signify the number of times a customer release has been built
and delivered to Oracle QA for testing, without releasing it to the customer. For
example, if working on the 3rd internal build of the 2nd customer release for a
customer's initial pilot, the customer version would be 1.2.3.
H. and I. Patch Version - If a build is released to a customer or production, and
requires a patch, the 4th number is incremented. Each time a patch is released, that
number will increase. For a new release, that number will reset to 0. If there is ever a
need to patch a patch, the 5th number is incremented. So if the 1.0 patch had a fix issued
against it, the patch version would change to 1.1.

Marking the Transaction with the Current Version

When a transaction is created and saved to the database, it will automatically be marked
with the full version string in the format of:
Base Version - Customer Version - Patch Level
This information is stored in the table - trn_trans_version - that records both
application and database version/date information for each transaction.
The full application version for each transaction is reported in the PosLog as the value of
the dtv:AppVersion attribute attached to each Transaction element.
<Transaction xmlns:dtv="http://www.datavantagecorp.com/xstore/"
CancelFlag="false" OfflineFlag="false" TrainingModeFlag="false"
dtv:AppVersion="18.0.0.0.414 - 0.0.0 - 0.0"
dtv:TransactionType="RETAIL_SALE">

Where the Information is Stored

The version information is stored in the following database locations:
ctl_version_history.base_schema_version - Base version
ctl_version_history.customer_schema_version - Customer version

Version Numbers 2-3

Where the Information is Stored

2-4 Technical Guide

 3
Organization Hierarchy Configuration

Overview
Xstore Point of Service data can be segregated by hierarchy in a horizontal approach (in
addition to the standard vertical approach), providing additional support for an item
hierarchy structure similar to the Xstore Point of Service pricing hierarchy scheme. This
type of data segregation is useful for franchise implementations.
To support this feature, org_code/org_value fields exist in many tables that do not have a
rtl_loc_id field, providing the ability to differentiate items by org hierarchy node. The
default for org_code/org_value is "*/*" (null values are not valid).
The org_code is the organization level code based on the customer’s store structure.
For example, STORE, DISTRICT, REGION, CHAIN, etc.
The org_value distinguishes one node in a hierarchy level from another, identifying a
node amongst its siblings. For example, two nodes with an org code of STORE might
have org values of 700 and 800. In this case, this would be the store number.

Organization Hierarchy Configuration 3-1

Define a Hierarchy

Organization Hierarchy Example

Define a Hierarchy
While there may be one chain within an organization, each chain may have regions,
districts, and stores. By definition, stores must be at the lowest level of a hierarchy. The
levels are completely arbitrary; what is important is the connection between the levels.
For example, if a store belongs to a district, a district belongs to a region, and a region
belongs to a chain, you can define a relationship where one node may have an arbitrary
number of children but only one parent. This describes a tree. Each node on the tree is
encapsulated in one record in whichever table is used. A node contains information used
to find the node itself as well as its parent, and it is the table's self relationship that builds
the tree.
• The loc_org_hierarchy table is a general-purpose hierarchy table that is able to drive
pricing, as well as other functionality. (See “Set Up a Location Hierarchy”).
• The loc_pricing_hierarchy table is a hierarchy table that drives pricing. (See “Set Up
a Location-Based Pricing Hierarchy”).
In the scope of the price provider itself, the two tables are interchangeable. Either table
can be used for location-based pricing, see “Location Based Hierarchical Pricing”.

Note: The loc_pricing_hierarchy table is populated by the

PRICING_HIER record, and the loc_org_hierarchy table is populated
by the ORG_HIER record.

See Chapter 5, “Item and Pricing Configuration” for more information about item
pricing structure and setup.

3-2 Technical Guide

 Set Up a Location Hierarchy

Set Up a Location Hierarchy

The loc_org_hierarchy table is a general-purpose hierarchy table that is able to
drive pricing, as well as other functionality. For information about this table and the
Dataloader record used to populate it, see the Xstore Point of Service Database Dictionary
and the Xstore Point of Service Host Interface Guide.

Set Up a Location-Based Pricing Hierarchy

The loc_pricing_hierarchy table stores less information than the
loc_org_hierarchy table and is designed only for the price provider. The logic used
to determine the location based price is the same regardless of which table you use (see
“Location Based Hierarchical Pricing”). For information about this table and the
Dataloader record used to populate it, see the Xstore Point of Service Database Dictionary
and the Xstore Point of Service Host Interface Guide.

Location Based Hierarchical Pricing

Location Based Hierarchical Pricing (LHP) utilizes either hierarchy table
(loc_pricing_hierarchy or loc_org_hierarchy) to determine the price for an
item. Xstore Point of Service searches for all pricing records starting at the node for the
current store and “walking” upward to the top-level (“root”) node of the hierarchy. Of
the found pricing records, the most recently effective price that is not yet expired, based
on the current business date and quantity being sold, within the hierarchy (level code/
level value) is used (see Sample Hierarchy).

Note: Since the level code and level value provide no information on
ordering—only parent/child relationships—certain queries have
difficulty providing hierarchy nodes in order. (Specifically, querying a
price where the level code and level value are “IN” a list of nodes will
not give reliable results).
By joining the price table to one of the hierarchy tables, a user may
specify the “sort_order” field in the “ORDER BY” clause, allowing the
SQL engine to sort the results based on level code without using the
actual level code. This field is not necessary for the default
implementation but clients may wish to populate it anyway to
facilitate these types of queries.

Sample Hierarchy
If you sell an item while running LHP for Store 100 in the sample below, Xstore Point of
Service retrieves a price of $60 since it has the most recent effective date (today) within
the hierarchy (level code/level value).
REGION::NORTH_AMERICA
SUB_REGION::MIDWEST (price = $50 effective yesterday)
STATE::OHIO (price = $60 effective today)
COUNTY::SUMMIT (price = $70 expired today)
STORE::100 (price =$45 effective last week)

Organization Hierarchy Configuration 3-3

Extend the Hierarchical Price Provider

Extend the Hierarchical Price Provider

Clients may wish to alter the core functionality of the price provider. There is an abstract
base class that handles much of the functionality while leaving various settings to the
child classes:
AbstractHierarchicalPriceProvider<T extends IObjectId>
Extend this class, setting the generic type to the DAO object that your hierarchy table
uses. From here you can change the query that runs to get the price, implement a method
to get the flattened hierarchy list, massage query parameters, and even change the entire
query logic.

3-4 Technical Guide

 4
Tax Setup & Configuration

Overview
Xstore Point of Service supports a wide range of tax options, including tax schemes such
as sales tax, VAT, compound taxes, and bracketed taxes. Xstore Point of Service also has
the ability to look up tax rates by location, and to handle threshold taxing where the tax
rate varies by item amount or transaction amount. Xstore Point of Service may be
configured to add taxes to individual items or to a tax group for the entire transaction.
All of these tax scenarios rely on both database tables and configuration files.
In most cases, taxes are added automatically by the system. However, in cases where an
associate needs to change the tax rate for a specific item, or change the tax rate for an
entire transaction, Xstore Point of Service also supports making manual changes to the
taxes. Xstore Point of Service allows an associate to enter the tax change either as a
specific dollar amount, or as a tax percentage. Xstore Point of Service also supports
exempting tax on specific items or the entire transaction.
All sales taxes are calculated using three parameters: where the store is located, which
item is being sold, and when the tax is in effect. The “where” is important in order to
determine the taxing authorities to which the store is subject. The “item” is significant
since authorities may tax different items according to different rules. The “when” is
significant because tax rules all have effective and expiration dates that determine their
effectiveness.
Tax tables are populated to indicate the store’s tax location and the tax group to which
the item belongs. As an item is added to a transaction, the system knows which store it is
in (the tax location) and looks up the item to determine the associated tax group. The
system then puts these three pieces of data together to find the tax group information
and the associated rules.

Tax Setup & Configuration 4-1

Introduction to the Tax Tables

Introduction to the Tax Tables

Although tax configuration involves some XML files, most of the tax configuration is
based on data in the Xstore Point of Service tax tables. The following table lists, and
briefly describes, the tax-related tables and shows their relationships.
For more information about these tables and the Dataloader records used to populate
them, see the Xstore Point of Service Database Dictionary and the Xstore Point of Service Host
Interface Guide.

Table Name Brief Table Description Relationships

tax_tax_authority Defines the authorities that parent:

can collect a tax.
tax_tax_authority
child:
tax_tax_group_rule

tax_tax_bracket Contains the tax bracket See “Tax Bracket Setup”

definitions.

tax_tax_loc Contains information about parent:

each geographical area over
tax_tax_loc
which one or more tax
authorities have jurisdiction child:
(the physical location at
tax_postal_code_mapping
which items are taxed).
Multiple stores can be tax_tax_group_rule
assigned to a single tax
tax_rtl_loc_tax_mapping
location, simplifying the
taxing structure. trl_tax_lineitm

tax_rtl_loc_tax_mapping Associates a tax_loc_id with parent:

a rtl_loc_id (as defined in
loc_rtl_loc
the table loc_rtl_loc) so that
only the correct taxes are child:
applied at a retail location.
tax_rtl_loc_tax_mapping
parent:
tax_tax_loc
child:
tax_rtl_loc_tax_mapping

tax_postal_code_mapping Associates a tax_loc_id with parent:

a postal_code (as defined in
tax_tax_loc
the table loc_rtl_loc) so that
the correct taxes are applied child:
if an item is purchased from
tax_postal_code_mapping
a remote store with a
different set of tax rules.

tax_tax_group Defines the identifiers for parent:

groups of merchandise
tax_tax_group
items that are taxed in the
same way; a tax_group_id child:
may then be assigned to an
tax_tax_group_mapping
item ID in the table
itm_item. tax_tax_group_rule
trl_tax_lineitm

4-2 Technical Guide

 Introduction to the Tax Tables

Table Name Brief Table Description Relationships

tax_tax_group_rule Pairs a tax_group_id with a parent:

tax_loc_id so that individual
tax_tax_group
items are taxed according to
the rules for the location at child:
which they are sold. Each of
tax_tax_group_rule
these pairs is further
associated with a parent:
tax_authority_id which is
tax_tax_loc
used to properly identify
and display the tax child:
authority that imposes the
tax_tax_group_rule
tax.
parent:
tax_tax_authority
child:
tax_tax_group_rule
parent:
tax_tax_group_rule
child:
tax_tax_rate_rule

tax_tax_rate_rule Pairs a tax_group_id or parent:

tax_bracket_id with a
tax_tax_group_rule
tax_loc_id and assigns each
pair to the correct child:
percentage or amount, or
tax_tax_rate_rule
bracket definition that is
used to calculate the tax parent:
amount due. The same
tax_tax_rate_rule
tax_group_id may be used
at any number of different child:
tax_loc_id(s). Tax thresholds
tax_tax_rate_rule_override
and breakpoints can also be
specified here.
This table also has effective
and expiration dates that
can be used to control
effectiveness.

tax_tax_rate_rule_override This table defines parent:

temporary tax rates that will
tax_tax_rate_rule
be used during a range of
dates whenever an existing child:
tax rate or amount is
tax_tax_rate_rule_override
changed. The temporary
percentages and amounts
entered in this table will be
used until the specified
expiration date. Tax
thresholds and breakpoints
can also be specified here.

Tax Setup & Configuration 4-3

Generalized Tax Setup Procedure

Table Name Brief Table Description Relationships

tax_tax_exemption This table contains parent:

information that describes a
crm_party
tax exemption, including the
name of the holder, a child:
certificate ID, a tax
tax_tax_exemption
exemption ID, and other
data.

tax_tax_group_mapping This table maps a customer customer_group_id

group/store location and a
tax group to a different tax
group for a specified
location. The result is that a
different tax rate is applied
than would ordinarily be
used, but only at the retail
location specified in this
table.
If customer_group_id is populated
with the value of ʺALLʺ, then the
tax group mapping will apply to
every customer group for the given
organization/retail location.
If customer_group_id is populated
with a customer group identifier,
only the customer group will get the
tax override.
parent:
loc_rtl_loc
child:
tax_tax_group_mapping
parent:
tax_tax_group
child:
tax_tax_group_mapping

com_reason_code The table com_reason_code reason_typcode

is a table shared among
reason_code
many Xstore Point of
Service functions and description
activities. For taxing
purposes, it contains the list
of reasons for which a tax
exemption may be applied,
if a reason is required.

Generalized Tax Setup Procedure

The process required to set up taxes for your stores, and a link to each section for more
information, is provided below:
1. Set up the tax locations and tax mapping. The foundation table is tax_tax_loc; then,
set up the tax_rtl_loc_tax_mapping and tax_postal_code_mapping tables to assign
the tax location IDs to individual stores (“Tax Location and Mapping Setup”).
2. Set up tax groups in the tax_tax_group table (“Tax Groups Setup”).
3. Set up the tax_tax_authority table to identify the name of the authority that imposes
the tax, and also supplies the rounding rules that are used in the calculation (“Tax
Authority Setup”).
4. Set up the tax group rules in the tax_tax_group_rule and associate the tax group
rules with tax locations in the tax_tax_loc table and tax groups in the tax_tax_group
table (“Tax Group Rules Setup”).

4-4 Technical Guide

 Generalized Tax Setup Procedure

5. Define the specific details for the tax group rule. Set up the table tax_tax_rate_rule to
specify the tax percentage rate and the tax amount. In addition, set up the
tax_tax_rate_rule_override table to specify when and how the normal tax rates are
temporarily replaced with the rates (or amounts) in the tax_tax_rate_rule table (“Tax
Rate Rule Setup”).
6. Assign the tax groups to items in the itm_item table (“Item Database Setup”).

Other Tax Setup Options

7. If a user has the privileges to change the tax rate or tax amount during a sale
transaction, the system may require a reason for the change. Set up the reasons for
making a tax change in the com_reason_code table. In addition, set up the
configuration file SysConfig.xml <Tax> section to control whether Xstore Point of
Service will prompt for a reason or not. (See “When a User Makes a Tax Change:
Configuring Reasons”).
8. In Send Sale/Remote Sale transactions, the taxing is based on a location other than
where the buyer actually makes the transaction. Set up both the database tables and
SysConfig.xml if you use this sale type (“Taxing in Send Sale/Remote Sale
Transactions”).
9. Set up the tax_tax_exemption table to define tax exemption information (“Tax
Exemption Database Setup”).
10. Set up the screen-display format for taxes in SysConfig.xml (“Configuring the Tax
Display”).
11. Set up the tax_tax_group_mapping table to override (re-map) an assigned item tax
group based on membership in a customer group or based on a retail store location.
When based on a retail store location, overrides by store can be set up, preserving
the ability to have the same item file be distributed to all stores with the possibility of
different tax group mappings for easier compliance of certain state sales tax rules.
When based on membership in a customer group, tax overrides are applied based on
the customer’s group membership (“Tax Group Mapping Overrides Setup”).
12. If using tax tables (Bracket Tax Cards) instead of tax rates, set up the tax_tax_bracket
table to calculate sales tax (“Tax Bracket Setup”).

Tax Setup & Configuration 4-5

Tax Location and Mapping Setup

Tax Location and Mapping Setup

The first step for setting up taxes is to define the tax location identifiers in the
tax_tax_loc table that can be assigned to individual stores in the mapping tables as
explained below.
Tax is based on the store location when the sale occurs in the default store (which is
known by Xstore Point of Service). But if the sale occurs elsewhere, the tax is based on
the rate or amount at a different location which should be defined in the postal code
mapping table.

Figure 4-1: Tax Location Mapping Tables

For information about these tables and the Dataloader records used to populate them,
see the Xstore Point of Service Database Dictionary and the Xstore Point of Service Host
Interface Guide.

Tax Groups Setup

The next step is to set up tax groups and then assign the tax group to items. The table
tax_tax_group is used to define tax groups for items that are taxed according to the
same rules. For example, certain food products may belong to the same tax group. After
defining the tax groups, they may be assigned to individual items in the table
itm_item. (See “Item Database Setup” in Chapter 5, “Item and Pricing Configuration”
for more information about item setup).

Figure 4-2: Tax Group Tables

4-6 Technical Guide

 Tax Authority Setup

For information about these tables and the Dataloader records used to populate them,
see the Xstore Point of Service Database Dictionary and the Xstore Point of Service Host
Interface Guide.

Tax Authority Setup

Set up the tax_tax_authority table to identify the name of the authority that
imposes the tax, and to provide the rounding rules that are used in the calculation. For
information about this table and the Dataloader record used to populate it, see the Xstore
Point of Service Database Dictionary and the Xstore Point of Service Host Interface Guide.

Tax Rounding Rules for tax_tax_authority.rounding_code

Rounding Rule Description

HALF_UP Round to the nearest neighbor unless equidistant, then round up.

HALF_DOWN Round to the nearest neighbor unless equidistant, then round down.

HALF_EVEN Round to the nearest neighbor unless equidistant, then round to even
neighbor. Example; 2.5 rounds to 2 while 3.5 rounds to 4. Note: This
rounding method results in the least number of rounding errors during
repeat computations.

CEILING Round toward positive infinity. Note: This is the opposite of FLOOR
and never decreases the calculated value.

FLOOR Round down toward negative infinity. Note: This is the opposite of
CEILING and never increases the calculated value.

UP Round to the next digit; away from zero.

DOWN Round to the previous digit; toward zero.

For positive numbers, CEILING and UP result in the same outcome.

For negative numbers, CEILING and DOWN result in the same outcome.
Figure 4-3: Rounding Methods For Taxes

Tax Group Rules Setup

Set up the tax group rules and associate them with tax locations and tax groups. The
table tax_tax_group_rule is used to define a group rule. Each rule should have a
unique entry in the name column. Associate each group rule with a tax location from the
tax_tax_loc table and also with a tax group from the tax_tax_group table.

Tax Setup & Configuration 4-7

Tax Rate Rule Setup

Figure 4-4: Tax Group Rule Tables

For information about these tables and the Dataloader records used to populate them,
see the Xstore Point of Service Database Dictionary and the Xstore Point of Service Host
Interface Guide.

Tax Rate Rule Setup

The table tax_tax_rate_rule supplies several pieces of information such as the tax
percentage rate and the tax amount that enable the tax calculation to work. This table is
linked to the table tax_tax_group_rule by having the same tax group ID
(tax_group_id), the same tax location (tax_loc_id), and the same tax rule sequence
number (tax_rule_seq_nbr).
The tax_tax_rate_rule table is also linked to the table tax_tax_authority which
identifies the name of the authority that imposes the tax, and also supplies the rounding
rules that are used in the calculation.
If using bracketed taxes, the tax_bracket_id in the tax_tax_rate_rule table is
linked to the tax_tax_bracket table.
A related table, tax_tax_rate_rule_override is used to specify when and how the
normal tax rates are temporarily replaced with the rates (or amounts) in the
tax_tax_rate_rule table. This table is identical to the table tax_tax_rate_rule
except that it has a different primary key, which includes expr_datetime.

4-8 Technical Guide

 A Single Tax: Sample Setup Procedure

Figure 4-5: Tax Rate Rule & Tax Override Tables

For information about these tables and the Dataloader records used to populate them,
see the Xstore Point of Service Database Dictionary and the Xstore Point of Service Host
Interface Guide.

A Single Tax: Sample Setup Procedure

This example assumes the following values for the store where this tax is being
configured:
• organization_id = 1
• rtl_loc_id = 301

Step #1
In the tax_tax_loc table, create a tax_loc_id for the organization_id and provide a name
and brief description for the tax location.

Table: tax_tax_loc

Column Value

organization_id 1

tax_loc_id 100

name Solon

Tax Setup & Configuration 4-9

A Single Tax: Sample Setup Procedure

Table: tax_tax_loc

Column Value

description Tax Location for Solon, OH

org_code *

org_value *

Step #2
In the table tax_rtl_loc_tax_mapping, map the tax location ID to the retail location ID.

Table: tax_rtl_loc_tax_mapping

Column Value

organization_id 1

rtl_loc_id 301

tax_loc_id 100

Step #3
In the tax_tax_group table, create a tax_group_id for the organization_id and enter a
name and brief description for the new tax group.

Table: tax_tax_group

Column Value

organization_id 1

tax_group_id 1

name Sales Tax

description Sales Tax

org_code *

org_value *

Step #4
In the itm_item table, associate each item with a tax group by entering a tax_group_id
for it.

Table: itm_item

Column Value

organization_id 1

item_id 1002

tax_group_id 1

4-10 Technical Guide

 A Single Tax: Sample Setup Procedure

Step #5
In the tax_tax_authority table, define the rounding rules for the tax that is associated
with the same tax_authority_id.

Table: tax_tax_authority

Column Value

organization_id 1

tax_authority_id Test Auth

name Tax

rounding_code HALF_UP

rounding_digits_quantity 2

org_code *

org_value *

Step #6
Define the tax group rules that will apply to the tax group.

Table: tax_tax_group_rule

Column Value

organization_id 1

tax_group_id 1

tax_loc_id 100

tax_rule_seq_nbr 1

tax_authority_id Test Auth

name Sales Tax

description 5% Sales Tax

compound_seq_nbr <Null>

compound_flag False (0)

tax_at_trans_level_flag True (1)

tax_typcode SALES

org_code *

org_value *

Tax Setup & Configuration 4-11

Multiple Taxes: Sample Setup Procedure

Step #7
Define the specific details that will be used to calculate the tax for the tax group rule that
you set up in step #6.

Table: tax_tax_rate_rule

Column Value

organization_id 1

tax_group_id 1

tax_loc_id 100

tax_rule_seq_nbr 1

tax_rate_rule_seq 1

tax_rate_min_taxable_amt 0

effective_datetime <Null>

expr_datetime <Null>

percentage 0.05

amt <Null>

daily_start_time <Null>

daily_end_time <Null>

tax_rate_max_taxable_amt <Null>

breakpoint_typcode FULL

org_code *

org_value *

Multiple Taxes: Sample Setup Procedure

In the previous section, the tax setup procedure for a single tax was described. However,
in many cases, multiple taxes (such as city, county, state, etc.) are applied to a sale. The
instructions in this section are very similar to the setup for a single tax, but because
multiple taxes must be defined, some repetitive setup is required for each tax in steps 4-
7.
In this sample three taxes will be defined:
• 5% Sales Tax
• 3% Special Sales Tax
• 1% Local Use Tax
This example assumes the following values for the store where this tax is being
configured:
• organization_id = 1
• rtl_loc_id = 301

4-12 Technical Guide

 Multiple Taxes: Sample Setup Procedure

Step #1
In the tax_tax_loc table, create a tax_loc_id for the organization_id and provide a name
and brief description for the tax location.

Table: tax_tax_loc

Column Value

organization_id 1

tax_loc_id 100

name Solon

description Tax Location for Solon, OH

org_code *

org_value *

Step #2
In the table tax_rtl_loc_tax_mapping, map the tax location ID to the retail location ID.

Table: tax_rtl_loc_tax_mapping

Column Value

organization_id 1

tax_loc_id 100

rtl_loc_id 301

Step #3
In the tax_tax_group table, create a tax_group_id for the organization_id and enter a
name and brief description for the new tax group.

Table: tax_tax_group

Column Value

organization_id 1

tax_group_id 1

name Sales Tax

description Sales Tax

org_code *

org_value *

Tax Setup & Configuration 4-13

Multiple Taxes: Sample Setup Procedure

Step #4
In the itm_item table, associate each item with a tax group by entering a tax_group_id
for it.

Table: itm_item

Column Value

organization_id 1

Item_id 1002

tax_group_id 1

Step #5
In the tax_tax_authority table, define the rounding rules for the tax that is associated
with each tax_authority_id.

Table: tax_tax_authority

3% Special 1% Local Use

Column 5% Sales Tax Sales Tax Sales Tax

organization_id 1 1 1

tax_authority_id Auth 1 Auth 2 Auth 3

name Tax Authority Tax Authority Tax Authority

1 2 3

rounding_code HALF_UP HALF_UP HALF_UP

rounding_digits_quantity 2 2 2

org_code * * *

org_value * * *

Step #6
Define the tax group rules that will apply to the tax groups.

Table: tax_tax_group_rule

3% Special 1% Local Use

Column 5% Sales Tax Sales Tax Sales Tax

organization_id 1 1 1

tax_loc_id 100 100 100

tax_group_id 1 1 1

tax_rul_seq_nbr 1 2 3

tax_authority_id Auth 1 Auth 2 Auth 3

name Sales Tax Special Sales Local Use

Tax Sales Tax

4-14 Technical Guide

 Multiple Taxes: Sample Setup Procedure

Table: tax_tax_group_rule

3% Special 1% Local Use

Column 5% Sales Tax Sales Tax Sales Tax

description 5% Sales Tax 3% Special 1% Local Use

Sales Tax Sales Tax

compound_seq_nbr <Null> <Null> <Null>

compound_flag False (0) False (0) False (0)

tax_at_trans_level_flag True (1) True (1) True (1)

tax_typcode SALES SALES SALES

org_code * * *

org_value * * *

Step #7
Define the specific details that will be used to calculate the tax for each of the tax group
rules that you set up in step #6.

Table: tax_tax_rate_rule

3% Special 1% Local Use

Column 5% Sales Tax Sales Tax Sales Tax

organization_id 1 1 1

tax_group_id 1 1 1

tax_rule_seq_nbr 1 2 3

tax_rate_rule_seq 1 1 1

tax_loc_id 100 100 100

tax_rate_min_taxable_amt 0 0 0

effective_datetime <Null> <Null> <Null>

expr_datetime <Null> <Null> <Null>

percentage 0.05 0.03 0.01

amt <Null> <Null> <Null>

daily_start_time <Null> <Null> <Null>

daily_end_time <Null> <Null> <Null>

tax_rate_max_taxable_amt <Null> <Null> <Null>

breakpoint_typcode FULL FULL FULL

org_code * * *

org_value * * *

Tax Setup & Configuration 4-15

Automatic Tax Overrides: Sample Setup Procedure

Automatic Tax Overrides: Sample Setup Procedure

If a tax rate or amount changes temporarily for a specified period of time (a “tax
holiday”), you can configure a database table to accommodate that situation. This
section describes the setup work that you must do to define a temporary tax override.
The essential requirement is to define the dates and times between which the tax
override will be applied. The change is usually a decrease in the tax rate, or tax amount,
from the normal rates.
The result of setting up a temporary tax override is that Xstore Point of Service will
automatically calculate and display the override tax amount. No user interaction is
necessary during a transaction. This example assumes the following values for the store
where this tax is being configured:
• organization_id = 1
• rtl_loc_id = 301

Tax Override Setup

Define the temporary tax override in the table tax_tax_rate_rule_override. Note where
the column values have been changed in the sample data.

Table: tax_tax_rate_rule_override

Column Current Value Override Value

organization_id 1 1

tax_group_id 2 2

tax_rule_seq_nbr 1 1

tax_rate_rule_seq 1 1

tax_loc_id 100 100

tax_rate_min_taxable_ 0 0
amt

effective_datetime <Null> 7/13/2008 12:00:00

AM

expr_datetime <Null> 7/14/2008 12:00:00

AM

percentage 0.1 0

amt <Null> <Null>

daily_start_time <Null> <Null>

daily_end_time <Null> <Null>

tax_rate_max_taxable_amt <Null> <Null>

breakpoint_typcode FULL FULL

org_code *

org_value *

4-16 Technical Guide

 When a User Makes a Tax Change: Configuring Reasons

When a User Makes a Tax Change: Configuring Reasons

If a user has the privileges to change the tax rate or tax amount during a sale transaction,
the system may require a reason for the change. Reasons for making a tax change are
defined in the com_reason_code table and may be selected from a list that is displayed
on the screen.
The com_reason_code table is accessed by a variety of different Xstore Point of Service
functions, including tax changes.

Note: This is not the same as the automatic, temporary tax override
described in the previous section, which does not require a reason.

Tax Change Reasons: XML Configuration

The configuration file SysConfig.xml contains an option in the Tax section that controls
whether Xstore Point of Service will prompt for a reason or not:
<Setting name="Tax---PromptForTaxChangeReason">true</Setting>
- If true, Xstore Point of Service displays a list from which a reason may be
selected.
- If false, no reason for making a change in the tax is required.

Tax Change Reasons: Sample Database Setup

The table below shows and describes the significant columns in the database table
com_reason_code and provides a sample of the data for setting up tax change reason
codes.
Table 4-1 com_reason_code

Column Name Description Sample Data

reason_typcode Use TAX_CHANGE for reasons TAX_CHANGE

related to user-initiated tax
changes.

reason_code The reason that will be selectable MGR_APPR

by a user.

description Text explanation of the tax Manager Approval

change reason code.

comment_req REQUIRED: system requires a REQUIRED

reason.
PROMPT: system prompts for a
reason but allows an override.

sort_order A number indicating the display 1

order for reasons.

parent_code If there is a hierarchical <Null>

arrangement of codes, this entry
identifies the parent code.

gl_acct_nbr The reason code may be <Null>

associated with a number related
to the general ledger account.

Tax Setup & Configuration 4-17

VAT Tax: Sample Setup Procedure

Table 4-1 com_reason_code (continued)

Column Name Description Sample Data

minimum_amt Minimum amount for which the 5.00

code may be used.

maximum_amt Highest amount for which the 100.00

code may be used.

cust_msg Display message used if the code <Null>

is selected.

VAT Tax: Sample Setup Procedure

A Value-Added Tax, or VAT tax, is one in which the taxes are included in the price of the
item. From the perspective of the item, taxes are incorporated into the item price.
However, for the benefit of the buyer, receipts and invoices must show the amount of the
taxes in addition to the item price (which includes the taxes).
For a VAT tax to be calculated correctly, the tax type must be defined as “VAT” and not
“SALES”. This is done in the table tax_tax_group_rule. The following step-by-step
procedure shows the tables that must be configured to define a VAT tax in Xstore Point
of Service using the example of a 20% tax. This example assumes the following values for
the store where this tax is being configured:
• organization_id = 1
• rtl_loc_id = 301

Step #1
In the tax_tax_loc table, create a tax_loc_id for the organization_id and provide a name
and brief description for the tax location.

Table: tax_tax_loc

Column Value

organization_id 1

tax_loc_id 100

name BONN

description Tax Location-Bonn, DDR

org_code *

org_value *

Step #2
In the table tax_rtl_loc_tax_mapping, map the tax location ID to the retail location ID.

Table: tax_rtl_loc_tax_mapping

Column Value

organization_id 1

4-18 Technical Guide

 VAT Tax: Sample Setup Procedure

Table: tax_rtl_loc_tax_mapping

Column Value

tax_loc_id 100

rtl_loc_id 301

Step #3
In the tax_tax_group table, create a tax_group_id for the organization_id and enter a
name and brief description for the new tax group.

Table: tax_tax_group

Column Value

organization_id 1

tax_group_id 60

name VAT

description Value Added Tax

org_code *

org_value *

Step #4
In the itm_item table, associate each item with a tax group by entering a tax_group_id
for it.

Table: itm_item

Column Value

organization_id 1

item_id 1010

tax_group_id 60

Step #5
In the tax_tax_authority table, define the rounding rules for the tax that is associated
with the same tax_authority_id.

Table: tax_tax_authority

Column Value

organization_id 1

tax_authority_id VAT Auth

name VAT

Tax Setup & Configuration 4-19

VAT Tax: Sample Setup Procedure

Table: tax_tax_authority

Column Value

rounding_code HALF_UP

rounding_digits_quantity 2

org_code *

org_value *

Step #6
Define the tax group rules that will apply to the tax group.

Table: tax_tax_group_rule

Column Value

organization_id 1

tax_loc_id 100

tax_group_id 60

tax_rul_seq_nbr 1

tax_authority_id VAT Auth

name VAT

description 20% VAT

compound_seq_nbr <Null>

compound_flag False (0)

taxed_at_trans_level_flag True (1)

tax_typcode VAT

org_code *

org_value *

Step #7
Define the specific details that will be used to calculate the tax for the tax group rule that
you set up in step #6.

Table: tax_tax_rate_rule

Column Value

organization_id 1

tax_group_id 60

tax_rule_seq_nbr 1

4-20 Technical Guide

 VAT Tax: Sample Setup Procedure

Table: tax_tax_rate_rule

Column Value

tax_rate_rule_seq 1

tax_loc_id 100

tax_rate_min_taxable_amt 0

effective_datetime <Null>

expr_datetime <Null>

percentage 0.20

amt <Null>

daily_start_time <Null>

daily_end_time <Null>

tax_rate_max_taxable_amt <Null>

breakpoint_typcode FULL

org_code *

org_value *

Multiple VAT Taxation

VAT countries normally apply a single taxation. However, some countries apply more
than one VAT on the same item. For example, India applies more than one VAT.
The section below clarifies how such cases are managed in terms of calculation and
rounding.
1. Firstly, the percentage of the two taxes are summed.
2. Then this percentage is used to calculate the total tax value.
3. The result is pro-rated based on the single percentages.
4. Then they are separately rounded (at line or transaction level, depending on
configuration).
This could result in decimal discrepancies. For example, consider a price of 69.50 and a
taxation of 3% + 3% and a rounding configuration at line level with two digits. Following
the above:
1. 3+3=6
2. 69.50 / 1.06 * 0.06 = 3.933962 à 3.93
3. 3.93 / 6 * 3 = 1.965
4. 1.965 à 1.97 (for both taxes)
The sum of the two separate taxes (1.97 + 1.97 = 3.94) does not match the total tax
calculated as total percentage of the tax included price: however, this is expected.

Tax Setup & Configuration 4-21

Compound Taxes

Compound Taxes
A compound tax is a special kind of tax that is calculated by applying it to a previously
taxed item. The value of the compound tax is based on the sum of an item’s price plus the
tax that was previously applied to it.
A tax is defined as a compound tax in the table tax_tax_group_rule. A compound
tax must also have a sequence number that indicates the order in which compound taxes
are applied, in case more than one compound tax is applicable.

How a Compound Tax is Applied: An Example

Two items in the same tax group are taxed at the transaction level, and the subtotal
amount for the items is $49.96. First, a 6% Goods and Services tax (GST) is applied. After
that, a 10% Provincial Sales Tax (PST) is applied. Here’s how it works:
1. The 6% GST is applied to the subtotal ($49.96 X .06) resulting in a GST tax amount of
$3.00 after rounding. The total so far is $52.96.
2. The 10% PST is applied to the total of $52.96 resulting in a PST tax amount of $5.30
after rounding.
3. The final total is calculated by adding the $5.30 PST amount to the previous total of
$52.96 giving a result of $58.26. The total of the two taxes is $8.30 ($3.00 GST + $5.30
PST).
4. The final total for the transaction is $58.26 ($49.96 + $8.30)

Compound Taxes: Sample Setup Procedure

This example assumes the following values for the store where this tax is being
configured:
• organization_id = 1
• rtl_loc_id = 301

Step #1
In the tax_tax_loc table, create a tax_loc_id for the organization_id and provide a name
and brief description for the tax location.

Table: tax_tax_loc

Column Value

organization_id 1

tax_loc_id 100

name Ontario

description Tax Location for Ontario

org_code *

org_value *

4-22 Technical Guide

 Compound Taxes

Step #2
In the table tax_rtl_loc_tax_mapping, map the tax location ID to the retail location ID.

Table: tax_rtl_loc_tax_mapping

Column Value

organization_id 1

tax_loc_id 100

rtl_loc_id 301

Step #3
In the tax_tax_group table, create a tax_group_id for the organization_id and enter a
name and brief description for the new tax group.

Table: tax_tax_group

Column Value

organization_id 1

tax_group_id 75

name Compound Tax

description Compound Tax

org_code *

org_value *

Step #4
In the itm_item table, associate each item with a tax group by entering a tax_group_id
for it.

Table: itm_item

Column Value

organization_id 1

item_id 1005

tax_group_id 75

Step #5
In the tax_tax_authority table, define the rounding rules for the GST and PST taxes
associated with their respective authorities.

Table: tax_tax_authority

Column GST PST

organization_id 1 1

Tax Setup & Configuration 4-23

Compound Taxes

Table: tax_tax_authority

Column GST PST

tax_authority_id GST1 PST1

name Goods & Services Provincial Sales

rounding_code HALF_UP HALF_UP

rounding_digits_quantity 2 2

org_code * *

org_value * *

Step #6
Define the tax group rules for the GST and PST that will apply to the tax group.

Table: tax_tax_group_rule

Column 6% GST 10% PST

organization_id 1 1

tax_loc_id 100 100

tax_group_id 75 75

tax_rul_seq_nbr 1 2

tax_authority_id GST1 PST1

name Goods & Services Provincial Sales

description 6% GST 10% PST

compound_seq_nbr 1 2

compound_flag True (1) False (0)

tax_at_trans_level_flag True (1) True (1)

tax_typcode GST PST

org_code * *

org_value * *

Step #7
Define the specific details that will be used to calculate the GST and PST taxes for the tax
group rule that you set up in step #6.

Table: tax_tax_rate_rule

Column 6% GST 10% PST

organization_id 1 1

4-24 Technical Guide

 Threshold Taxes

Table: tax_tax_rate_rule

Column 6% GST 10% PST

tax_group_id 75 75

tax_rule_seq_nbr 1 2

tax_rate_rule_seq 1 1

tax_loc_id 100 100

tax_rate_min_taxable_ 0 0
amt

effective_datetime <Null> <Null>

expr_datetime <Null> <Null>

percentage 0.06 0.10

amt <Null> <Null>

daily_start_time <Null> <Null>

daily_end_time <Null> <Null>

tax_rate_max_taxable_amt <Null> <Null>

breakpoint_typcode FULL FULL

org_code * *

org_value * *

Threshold Taxes
A threshold tax is a tax applied only within a specified range of values. Its entry
threshold is the minimum transaction value or item value at which it may first be
applied. A maximum value indicates the highest transaction value or item value at
which the tax may be applied. After the maximum value is exceeded, a different tax may
be applied as specified by a new threshold amount.
A common usage of a threshold tax is its application for “luxury items”: high-priced,
non-essential merchandise. But a threshold tax may be applied to any item, so that part
of the item’s price is taxed at one rate, and the balance is taxed at another rate.

Note: Be sure that you designate “Part” in the breakpoint_typcode

column of the table tax_tax_rate_rule. Otherwise, the tax will be
applied to the entire price of the item instead of being restricted to the
minimum and maximum amounts.

How a Threshold Tax is Applied: An Example

Item #1010 is in Tax Group 33 and its price is $499.99. The first 10% tax is applicable up to
a maximum of $400.00. Above $400.00, the item is taxed at 20%. The threshold tax is
applied as follows:

Tax Setup & Configuration 4-25

Threshold Taxes

1. The 10% rate is applied on the first $400.00 of the item price ($400.00 X .10) resulting
in a tax amount of $40.00. The total so far is $440.00 ($400.00 + $40.00).
2. The 20% rate is applied on the remaining $99.99 of the item price ($99.99 X .20)
resulting in a tax amount of $20.00 after rounding, for a result of $119.99 ($20.00 +
$99.99).
3. The final item total is calculated by adding the tax amounts, resulting in a final item
price of $559.99. ($400.00 + $40.00 = 440.00 and $99.99 + $20.00 = 119.99)

Threshold Taxes: Sample Setup Procedure

This example assumes the following values for the store where this tax is being
configured:
• organization_id = 1
• rtl_loc_id = 301

Step #1
In the tax_tax_loc table, create a tax_loc_id for the organization_id and provide a name
and brief description for the tax location.

Table: tax_tax_loc

Column Value

organization_id 1

tax_loc_id 100

name Solon

description Tax Location for Solon, OH

org_code *

org_value *

Step #2
In the table tax_rtl_loc_tax_mapping, map the tax location ID to the retail location ID.

Table: tax_rtl_loc_tax_mapping

Column Value

organization_id 1

tax_loc_id 100

rtl_loc_id 301

4-26 Technical Guide

 Threshold Taxes

Step #3
In the tax_tax_group table, create a tax_group_id for the organization_id and enter a
name and brief description for the new tax group.

Table: tax_tax_group

Column Value

organization_id 1

tax_group_id 33

name Threshold Tax

description Threshold Tax

org_code *

org_value *

Step #4
In the itm_item table, associate each item with a tax group by entering a tax_group_id
for it.

Table: itm_item

Column Value

organization_id 1

item_id 1010

tax_group_id 33

Step #5
In the tax_tax_authority table, define the rounding rules for the threshold taxes that is
associated with their respective authorities.

Table: tax_tax_authority

Column Value

organization_id 1

tax_authority_id Auth 1

name Threshold

rounding_code HALF_UP

rounding_digits_quantity 2

org_code *

org_value *

Tax Setup & Configuration 4-27

Threshold Taxes

Step #6
Define the tax group rules that will apply to the tax group.

Table: tax_tax_group_rule

Column 10% to $400 20% above $400

organization_id 1 1

tax_loc_id 100 100

tax_group_id 33 33

tax_rul_seq_nbr 1 2

tax_authority_id Auth 1 Auth 1

name Threshold $400 Threshold Above $400

description 10% to $400.00 20% above $400.00

compound_seq_nbr <Null> <Null>

compound_flag False (0) False (0)

tax_at_trans_level_flag False (0) False (0)

tax_typcode SALES SALES

org_code * *

org_value * *

Step #7
Define the specific details that will be used to calculate the threshold taxes for the tax
group rule that you set up in step #6.

Table: tax_tax_rate_rule

Column 10% to $400 20% above $400

organization_id 1 1

tax_group_id 33 33

tax_rule_seq_nbr 1 2

tax_rate_rule_seq 1 1

tax_loc_id 100 100

tax_rate_min_taxable_amt 0 400.01

effective_datetime <Null> <Null>

expr_datetime <Null> <Null>

percentage 0.10 0.20

amt <Null> <Null>

4-28 Technical Guide

 Threshold Taxes

Table: tax_tax_rate_rule

Column 10% to $400 20% above $400

daily_start_time <Null> <Null>

daily_end_time <Null> <Null>

tax_rate_max_taxable_amt 400 999999

breakpoint_typcode PART PART

org_code * *

org_value * *

Tax Setup & Configuration 4-29

Taxing in Send Sale/Remote Sale Transactions

Taxing in Send Sale/Remote Sale Transactions

In a Send Sale/Remote Sale transaction, the taxing is based on a location other than
where the buyer actually makes the transaction. For these transactions, Xstore Point of
Service must look up the correct tax rate or amount for the item’s destination. The
lookup operation is based on data that the associate can enter, including retail location
ID, city, postal code, and other options. In a Send Sale/Remote Sale transaction, an in-
stock item is purchased and shipped to a location specified by the buyer.

Database Configuration
The table tax_tax_rate_rule includes the column tax_loc_id and it should
contain an entry that is matched to an entry in the table tax_postal_code_mapping.
In the example below, tax_loc_id “TL-1000” is associated with postal_code
“44117”.
tax_tax_rate_rule Table

tax_postal_code_mapping

XML Configuration
The configuration file SysConfig.xml contains some options that are specifically related
to Send Sale/Remote Sale transactions. The configuration is found within the SendSale
section.
<Setting name="SendSale---UseThisStoreAsFailOverTaxRate">true</
Setting>

When the system cannot find the appropriate tax location based on the ship-to postal
code of the send sale order, the system uses this configuration to determine taxing.
- true = Use the current store’s tax location when unable to find the ship-to postal
code tax location.
- false = The system will charge no tax if the system cannot find tax information
for the destination ZIP code.
<Setting name="SendSale---SendTaxType">DESTINATION</Setting>
This is the method the system uses to calculate sales tax for send sale orders.
- DESTINATION - Use the destination tax rate.
- SELLING - Use the selling store tax rate.
- DEST_INSTATE - Use the selling store tax rate if the destination is located in the
same state as the current store.

4-30 Technical Guide

 Changing Tax in a Transaction

Changing Tax in a Transaction

Xstore Point of Service provides the capability for an associate to manually change a tax
that is applied to an item or a transaction. Before allowing that to be done, validation
checks are performed to determine if a change is allowed, and to ensure that it is
performed on only the acceptable line item types.
The configuration file SysConfig.xml contains an option in the Tax section that controls
whether tax changes are applied to all line items on the transaction or only to one
selected line item:
<Setting name="Tax---ChangeIndividualTaxLines">false</Setting>
• If the configured value is true and multiple taxes apply (such as city, county, state),
Xstore Point of Service displays a list of the applicable taxes and the associate may
select the one that will be changed.
- If the tax to be changed is applied at the “item” level, Xstore Point of Service
displays all the taxes for the selected item.
- If the tax to be changed is applied at the “transaction” level, Xstore Point of
Service displays the taxes for all items on the transaction.
• If the configured value is false and multiple taxes apply, tax changes will be applied
to all of the taxes that are applicable.

Tax Exemption Database Setup

A tax exemption may be applied to an item during a transaction. The pertinent
information is stored in the database table tax_tax_exemption. Configuration
controls whether the exemption is applied to individual taxes or to all taxes for the
selected item.
During the process of exempting a tax, Xstore Point of Service ensures that a customer is
associated with the transaction and has a valid tax exemption certificate. If the customer
does not already have a tax exemption certificate, the associate must enter the required
information to establish a certificate before the exemption can be applied.
For information about this table and the Dataloader record used to populate it, see the
Xstore Point of Service Database Dictionary and the Xstore Point of Service Host Interface
Guide.

Tax Exemption Configuration

The configuration file SysConfig.xml contains options that allow you to configure how
tax exemptions are applied during a transaction. These options are in the Tax section of
the file.
The option below controls whether a tax exemption is applied to all of the taxes for a
selected item (value = false) or only to the taxes that are selected from a list that Xstore
Point of Service displays when applying the exemption (value = true).
<Setting name="Tax---ChangeIndividualTaxLines">false</Setting>
The following option determines whether or not transaction-level tax changes/
exemptions are applied to all tax authorities automatically. When true, selecting a
transaction-level tax change/exemption will automatically be applied to all tax
authorities. When false, the system will prompt with a list of tax authorities for the
associate to select from for the transaction-level tax change/exemption.
<Setting name="Tax---AllowExemptAllTaxLines">true</Setting>

Tax Setup & Configuration 4-31

Configuring the Tax Display

Another option determines whether or not Xstore Point of Service will prompt for a
reason for applying a tax exemption. When true, a prompt displays where a reason can
be selected from a list of possible exemptions.
<Setting name="Tax---PromptForTaxExemptReason">true</Setting>

Tax Exemption Reason Codes

Reason codes for assigning a tax exemption to a transaction are found in the database
table com_reason_code. If a reason code is required, a comment may also be required.
That is also controlled by the same database table.

Configuring the Tax Display

You may configure the number of tax lines that display in the viewport during a sales
transaction by editing the numeric value of the following option, which is found in the
Tax section in the file SysConfig.xml:
<Setting name="Tax---TaxGroupLines">1</Setting>
In the example above, three tax lines will be displayed. You might need a line for each of
several different taxes that will be applied such as a state tax, county tax, and a city tax.
If the value of the option is “1”, then all of the taxes are totaled and displayed on one
line.

Tax Group Mapping Overrides Setup

Xstore Point of Service allows an override (re-mapping) of an assigned item tax group
based on membership in a customer group. In addition, Xstore Point of Service allows
overrides by store to preserve the ability to have the same item file be distributed to all
stores with the possibility of different tax group mappings for easier compliance of
certain local sales tax rules.
Items in various departments may have different tax groups to allow for different tax
rates. The tax group designations in the item table are the same for all stores across the
chain, allowing the retailer to provide one item file to all store locations. When the items
are sold, the taxes are summarized by group. The tax rates that apply to the different
stores are configured in the tax tables using the tax group identifier as a component.
Tax group mapping override functionality is driven by the customer group id. This
allows the retailer to determine the override tax group id using the
tax_tax_group_mapping table as follows:
• By retail location — Populate the customer_group_id column with the value 'ALL'.
For example, if an item with tax group T1 is sold in store S100, change that item's tax
group to T4 when adding it to a transaction. The tax group mapping will apply to
every customer group for the given organization/retail location.
• By customer group membership — Populate the customer_group_id column with the
value of a customer group.
For example, if an item with tax group T1 is sold in store S100 to a customer
belonging to group G9, change that item's tax group to T4 when adding it to a
transaction. The tax group mapping will apply only to the specified customer group
for the given organization/retail location.
When a sale is rung, Xstore Point of Service evaluates the
tax_tax_group_mapping.customer_group_id field to determine if a retail
location tax override exists.

4-32 Technical Guide

 Tax Bracket Setup

• If a value of ALL is found, then the new tax group id will be applied to the
transaction. The items sold on the transaction are summed up to one single tax
group in the POS and on the receipt.
• If a Customer group value is found, then the new tax group id will be applied to the
transaction only if the customer is a member of the specified group. The items sold
on the transaction are summarized by group in the POS and on the receipt.

Tax Mapping Example: tax_tax_group_mapping Table

Table 4-2 tax_tax_group_mapping Table

Column By Retail Location By Customer Group

organization_id 1000 1000

rtl_loc_id 101 101

tax_group_id T1 (assigned to items) T1 (assigned to items)

customer_group_id ALL ELITE

priority 10 10

new_tax_group_id LOC101 GRPELITE

Tax Bracket Setup

This section provides information about the use of tax tables/brackets to calculate the
sales tax for an item or transaction. All tax percentage brackets have a base value. Since
each tax percentage bracket uses a different base value, Xstore Point of Service has been
designed to automatically determine the base value used for the sales tax calculations.
These calculations are based on the records loaded in the tax_tax_bracket table for
each tax_bracket_id. (The idea of this “base value” was designed to limit the number
of records needed in the tax_tax_bracket table, rather than load multiple records to
cover some arbitrary sales amount).

Note: The base value is the maximum amount in the tax_breakpoint

column, rounded to the nearest whole dollar. Refer to examples E1 and
E2.

For more information about this table and the Dataloader record used to populate it, see
the Xstore Point of Service Database Dictionary and the Xstore Point of Service Host Interface
Guide.

Tax Setup & Configuration 4-33

Tax Bracket Setup

Examples E1 & E2: tax_tax_bracket table

Table 4-3 E1: If the tax bracket is as follows

tax_breakpoint tax_amount Then...

column column

0.100000 0.010000 The maximum tax_breakpoint amount for the

tax_bracket_id is “0.860000”. The base value will be
0.150000 0.020000
rounded to “1.000000”, which is the nearest whole
0.290000 0.030000 dollar amount.
0.430000 0.040000 Using the Example E1 tax table, $.07 would be charged
for each $1.00 (base value) of the sale, plus the tax
0.580000 0.050000
amount due on the fractional part of $1.00 listed in the
0.720000 0.060000 table. For a sale of $10.30, a total of $.73 tax would be
assessed. This is calculated as follows:
0.860000 0.070000
$10.30 / $1 = $10.30, truncate to $10 (this is how many
whole $1 we have)
$10 * $.07 = $.70 tax (charge $.07 per each $1 of sale)
plus
$10.30 - $10 {$10 * $1} = $.30 left over (look tax up in the
table = $.03)
$.70 + $.03 = $.73 total tax

4-34 Technical Guide

 Tax Bracket Setup

Table 4-4 E2: If the tax bracket is as follows

tax_breakpoint tax_amount Then...

column column

0.100000 0.010000 The maximum tax_breakpoint amount for the

tax_bracket_id is “3.870000”. The base value will be
0.140000 .020000
rounded to “4.000000”, which is the nearest whole
0.280000 .030000 dollar amount.
0.420000 .040000 Using the Example E2 tax table, $.29 would be charged
for each $4.00 (base value) of the sale, plus the tax
0.560000 .050000
amount due on the fractional part of $4.00 listed in the
0.690000 .060000 table. For a sale of $150.25, a total of $10.90 tax would
be assessed. This is calculated as follows:
0.830000 .070000
$150.25 / $4 = $37.5625, truncate to $37 (this is how
0.970000 .080000
many whole $4 we have)
1.110000 .090000
$37 * $.29 = $10.73 tax (charge $.29 for each $4 of sale)
1.250000 .100000 plus
1.380000 .110000 $150.25-$148 {$37 * $4} = $2.25 left over (look tax up in
the table = $.17)
1.520000 .120000
$10.73 + $.17 = $10.90 total tax
1.660000 .130000
1.800000 .140000
1.940000 .150000
2.070000 .160000
2.210000 .170000
2.350000 .180000
2.490000 .190000
2.630000 .200000
2.760000 .210000
2.900000 .220000
3.040000 .230000
3.180000 .240000
3.320000 .250000
3.450000 .260000
3.590000 .270000
3.730000 .280000
3.870000 .290000

Also set up the tax_bracket_id in the tax_tax_rate_rule table.

Tax Setup & Configuration 4-35

Tax Bracket Setup

4-36 Technical Guide

 5
Item and Pricing Configuration

Overview
Item setup is closely tied to item pricing. For this reason, both item setup and pricing
setup processes will be covered in this chapter. Refer to the Item Pricing Overview
section below to learn more about the pricing structures supported in Xstore Point of
Service. “Item Setup Overview” defines the steps required to set up items and item
prices in your organization.

Item Pricing Overview

Xstore Point of Service uses a “location-based hierarchical pricing” structure which
provides prices to Xstore Point of Service by looking up items in a location-based
hierarchy. In this implementation, data is derived from two possible locations,
loc_org_hierarchy and loc_pricing_hierarchy.

Base Pricing Strategy in a hierarchy-based model

An item's base price for any given store system is the value configured in the
itm_item_prices table for that item AND appropriate for the hierarchy in which the
store is located, as well as a function of the date, and possibly quantity.
Customer-based pricing is also supported. In this pricing scheme prices are derived
based on customer groups, prices, and the effective date of prices.
This hierarchy-based model allows for a more manageable and granular control of
pricing. For example, the price of an item could be configured to be $19.99 throughout
the entire organization. Or, that definition could be further refined by configuring the
item's price in such a way that it costs $24.99 in the stores within a pre-defined "west
coast" region, to reflect cost-of-living differences.

Prerequisites and Assumptions

• Hierarchy data and prices must be loaded. Otherwise, Xstore Point of Service will
fail to find an item price.
• The following price provider must be specified in system.properties:
dtv.pricing2.PriceProvider=dtv.pos.pricing.LocationHierarchyPr
iceProvider
The Location Hierarchy price provider uses a location-based hierarchy, or tree
structure, where each node is a retail location used to determine an item price. This
allows item prices to be defined for an entire chain, districts, or specific locations.

Item and Pricing Configuration 5-1

Location-Based Hierarchy Pricing Structure

Location-Based Hierarchy Pricing Structure

In this pricing scheme, an item’s price is determined by consulting one or more key-
joined itm_item_prices records, which are selected by consulting the location
hierarchy populated by the ORG_HIER DataLoader record or the PRICING_HIER
DataLoader record.
To set up the pricing hierarchy you may use one of two tables: loc_org_hierarchy or
loc_pricing_hierarchy. These two tables store the same data for the purposes of
the price provider.
The loc_org_hierarchy table is a general-purpose hierarchy table that is able to
drive more functionality in addition to prices, while the loc_pricing_hierarchy
table stores less information, and is used only by the price provider. In the scope of the
price provider itself, the two tables are interchangeable.
The level code and level value fields in the itm_item_prices table are not specific to
either hierarchy table, and like the rest of the schema, there are no foreign keys or data
constraints. You may connect to either hierarchy (loc_org_hierarchy or
loc_pricing_hierarchy).
All item pricing at the download level must be accomplished through either the
PRICE_HISTORY_2 or the PRICE_UPDATE_2 records.
These two records populate the same table—itm_item_prices—with the following
differences:
• In the PRICE_HISTORY_2 record the "PropertyCode" field, which defines the
pricing type, is fixed to "REGULAR_PRICE" to denote the base/regular price for the
item in all cases.
• In the PRICE_UPDATE_2 record the "PropertyCode" field, which defines the
pricing type, allows/requires the pricing type to be specified in the download record.
These records provide full support for a variable pricing structure (hierarchy-based
pricing) by defining item prices and attaching them to a level code and level value.
Refer to the Xstore Point of Service Host Interface guide for more information about
download records.

Note: The pricing module in Xstore Office was designed without any
knowledge of the pricing_hierarchy, and is only aware of the
organization_hierarchy. Refer to the Xstore Office User Guide for
more information.

5-2 Technical Guide

 Customer Group Pricing

Customer Group Pricing

The system has the ability to derive “base” prices based on customer groups. This is
similar to customer-based deal pricing (through association between customer groups
and deal triggers) and customer-filtered discounting.
In addition to “REGULAR_PRICE” and “PROMO_PRICE” prices, Xstore Point of
Service also supports pricing based on the customer’s group affiliation. This is set up in
the property_code field of the itm_item_prices table.

Note: If not using REGULAR_PRICE or PROMO_PRICE, the

property_code value must be a valid value from
crm_customer_affiliation.cust_group_id

Because only a single base unit price for an item may be derived at any given time, the
rules for such a derivation, given an arbitrary number of pricing tiers, will usually be
client-specific.

When there are multiple customer groups, which price is used?

In this example, customer A is a member of the “VIP” and “EMPLOYEE_FAMILY”
groups:
- Which price do they receive for an item with prices associated with both groups,
and
- what if that item also has a “PROMO” price, and
- what if it has a regional price adjustment reflected in a “ZONE” tier?
In base Xstore Point of Service, it is assumed that the lowest applicable pricing tier is
applied. However, custom rule injection through code and/or configuration is also
supported.

Item Setup Overview

Now that you have a basic idea about item pricing, continue with setting up items. The
item setup process uses both database tables and configuration files. In this chapter, the
database table information and the DataLoader Record and fields are listed for each
table and column. The SysConfig.xml item lookup and messaging options are also listed
here.

Note: Before items can be set up, you must first set up taxing
information, including a unique identifier for the tax group in
tax_tax_group.tax_group_id. See Chapter 4, “Tax Setup &
Configuration”.

The process required to set up items for your stores is provided below, along with a link
that can be followed to each section for more information.
1. Define the item information in the itm_item table (“Item Database Setup”).
2. Define the item pricing information in the itm_item_prices table (“Hierarchy-
based Pricing Database Setup”).
3. Define the non-physical item information in the itm_non_phys_item table. Non-
physical item information must also be set up in the itm_item table (“Non-Physical
Item Database Setup”).

Item and Pricing Configuration 5-3

Item Setup Overview

4. Set up the item hierarchy in the itm_merch_hierarchy table (“Item Merchandise

Hierarchy Database Setup”).
5. Define the item options in the in the itm_item_options table (“Item Options
Setup”).
6. Define the item style characteristics such as dimension system, size, color, and width
in the itm_item, itm_item_dimension, itm_item_dimension_type, and
itm_item_dimension_value tables (“Style: Item Dimensions/Grid Setup”).
Configure the item lookup options in SysConfig.xml (“Style: Item Grid
SysConfig.xml Setup”).
7. Define the information required for item lookup by manufacturer's UPC, or other
alternate item identifiers, in the itm_item_cross_reference table.(“Item Cross
Reference Database Setup”).
8. Define information about a vendor that can be associated with items in the
itm_vendor table (“Item Vendor Database Setup”).
9. If applicable, set up a relationship between items for the purpose of automatically
adding an “attached” item to a transaction when another item is sold in the
itm_attached_items table (“Attached Item Database Setup”). Configure
additional attached item options in SysConfig.xml (“Attached Items Setup in
SysConfig.xml”).
10. If applicable, set up a cross reference of items that may be substituted or offered in
place of another item in the itm_substitute_items table (“Substitute Item
Setup”).
11. If applicable, set up the itm_item_prompt_properties table to provide the
ability to prompt for additional information as an item is sold (“Item Prompting
Database Setup”).
12. If applicable, configure additional item lookup options in SysConfig.xml (“Item
Lookup Configuration in SysConfig.xml”).
13. If creating a Kit, set up the parent kit item information in the itm_item table, then
set up the itm_kit_component table to map the kit component items to their
parent kit item. Specify the Kit configuration options in SysConfig.xml (“Kit Item
Setup”).
14. If setting up refund schedules for the amount to be refunded for a prorated returned
item, refer to Chapter 17, “Return Transaction Configuration”. Items are identified
as being prorated or not prorated on a per-item basis.
15. If setting up item messages, refer to Chapter 6, “Item Messaging Configuration”.
16. If setting up an item matrix (touch screen or mouse only), see “Item Matrix”.
17. If setting up item images, see “Item Images”.
18. If using the Quick Items tab, see “Quick Items Tab”.

5-4 Technical Guide

 Item Database Setup

Item Database Setup

Most of the item setup is done within the itm_item and itm_item_options tables.
For information about these tables and the Dataloader records used to populate them,
see the Xstore Point of Service Database Dictionary and the Xstore Point of Service Host
Interface Guide.

Note: Item pricing details are set up in the itm_item_prices table

for hierarchy-based pricing. See “Hierarchy-based Pricing Database
Setup” for more information about item pricing.

Non-Physical Item Database Setup

Non-physical item-specific information must be defined in the itm_non_phys_item
table. However, most of the non-physical item setup is done within the itm_item and
itm_item_options tables (see Item Setup Overview). For information about these
tables and the Dataloader records used to populate them, see the Xstore Point of Service
Database Dictionary and the Xstore Point of Service Host Interface Guide.

Note: All relevant item fields for non-physical items are loaded using
the NON_PHYSICAL_ITEM record. Refer to the Xstore Point of Service
Host Interface Guide for more information.

Hierarchy-based Pricing Database Setup

An item’s price is determined by consulting one or more key-joined itm_item_prices
records that are selected by consulting the location and/or pricing hierarchy. For
information about this table and the Dataloader record used to populate it, see the Xstore
Point of Service Database Dictionary and the Xstore Point of Service Host Interface Guide.

Note: You must set up either the loc_pricing_hierarchy table or

the loc_org_hierarchy table to use hierarchy-based (location)
pricing. See Chapter 3, “Organization Hierarchy Configuration” for
more information about hierarchy-based pricing.

Item Merchandise Hierarchy Database Setup

The itm_merch_hierarchy table provides information for each specific node on the
merchandise hierarchy tree. For information about this table and the Dataloader record
used to populate it, see the Xstore Point of Service Database Dictionary and the Xstore Point
of Service Host Interface Guide.

Item Options Setup

Item options define configuration options for individual items at each location where
they are sold. Item options are configured in the itm_item_options table. For
information about this table and the Dataloader record used to populate it, see the Xstore
Point of Service Database Dictionary and the Xstore Point of Service Host Interface Guide.

Style: Item Dimensions/Grid Setup

A style is a logical group of related items that has a unique style ID. You cannot buy a
style; however, you can buy an item within a style. When an associate enters a style ID

Item and Pricing Configuration 5-5

Style: Item Dimensions/Grid Setup

instead of an item ID during a sale transaction, the system automatically lists the
corresponding dimensions from the database tables and prompts the user to make
selections. By using this process, the system narrows the scope of the search, and
ultimately, allows the user to add the item with matching dimensions to the transaction.
In addition to using a style ID to identify a specific item ID in a sale transaction, setting
up the item dimensions in the database is also used to display the item grid in Item
Lookup functions.
Style setup is based on a “Dimension System”. A dimension system is a generic group of
dimension types and values with which one or more styles can be associated as a means
of specifying how items of a style are differentiated.

Deals at the Color Level

If you create deals in Customer Engagement Cloud Services that are at the Color level,
you must choose a dimension (i.e. dimension1, dimension2, or dimension3) for Color
and it must be the same across all styles. This is required because Customer
Engagement Cloud Services needs to know which dimension is Color for the purpose of
creating deals to that level.
For example, if you choose to set up Color as dimension1, then all styles must be set up
using dimension1 as Color in order for deals at the Color level to work as expected.

Customer Engagement Cloud Services Changes Required

In addition, you will need to make changes to the Xstore Point of Service promotion
export file in Customer Engagement Cloud Services:
Edit the XstorePromotionExport.bsh.java file located in the srv/relate-
services-deploy/apache-tomcat/shared/classes/config/xslt directory.
Change Line #191:
From: colortest.itemTestType = ʺCOLORʺ;
To: colortest.itemTestType = ʺDIMENSIONxʺ;
(where x = Xstore Point of Service attribute used for item Color: 1 – 3
X=whatever the client decides to use for the Color attribute (1-3 only) i.e. DIMENSION1,
DIMENSION2, DIMENSION3)
Refer to the Customer Engagement Cloud Services documentation for more information.

Setup Overview
1. Define a style:
- A style has a unique style ID that is stored in the item_id column of the
itm_item table and an item_lvlcode value of STYLE.
- Each style ID is linked to a dimension system in the dimension_system column
of the itm_item table.
For detailed information, see “itm_item Table Setup”.
2. Define the style dimension types and values:
- In the itm_item_dimension_type table, define the types of dimensions
associated with the dimension system and choose sequences and sort orders for
the dimensions.
For detailed information, see “itm_item_dimension_type Table Setup”.

5-6 Technical Guide

 Style: Item Dimensions/Grid Setup

- In the itm_item_dimension_value table, define all possible values for each

dimension in the dimension system and choose an order for the dimension
values so they are displayed properly.
For detailed information, see “itm_item_dimension_value Table Setup”.
3. Associate items with a style:
- In the itm_item table, use the parent_item_id column to associate the style_id
with an item.
For detailed information, see “itm_item Table Setup”.
- In the itm_item_dimension table, associate the item with the dimensions.
For detailed information, see “itm_item_dimension Table Setup”.
4. Configure item grid lookup options in SysConfig.xml:
For detailed information, see “Style: Item Grid SysConfig.xml Setup”.

How to Set Up Item/Style-level Prompting and Grid

The following information is required to trigger item/style-level prompting and to
populate the item grid in Item Lookup.

itm_item Table Setup

Table Description

itm_item Contains item information to the lowest merchandise level for which
inventory and sales records are retained within the retail store.

DataLoaderConfig.xml Records

<RecordType name="ITEM">

Table Detail: itm_item

Attribute Used to... DataLoader Field

item_id uniquely identify the style or <Field filePosition="03"

item. name="ItemId" />

item_lvlcode indicate whether this is a style <Field filePosition="04"

level or an item level. name="ItemLevelCode" />
For a style Id, value=STYLE
For an item Id, value=ITEM

Item and Pricing Configuration 5-7

Style: Item Dimensions/Grid Setup

Table Detail: itm_item (continued)

Attribute Used to... DataLoader Field

parent_item_id associate an item ID with a style <Field filePosition="05"

ID. name="ParentItemId" />
For the style ID, value=NULL
For the item ID, value=<the
item_id of the style item>
Note: Specifying NULL on the
style's ID will allow the system
to prompt for the various values
attached to the items under the
style. Specifying a value here
will cause no prompt to appear,
and this value will be applied
explicitly when filtering the
items in the style.

dimension_system specify the general dimension <Field filePosition="82"

structure an item belongs to. name="DimensionSystem" />
Note: The dimension system
information is stored on the
STYLE level, not on an ITEM
level.

Note: Other fields in the itm_item table should also be populated as

needed. Only the style-specific fields are shown here. For more
information about the itm_item table. See “Item Setup Overview” for
more information.

itm_item_dimension_type Table Setup

Table Description

itm_item_dimension_ Contains the types of dimensions associated with a dimension

type system.

DataLoaderConfig.xml Records

RecordType name="ITEM_DIMENSION_TYPE">

Table Detail: itm_item_dimension_type

Attribute Used to... DataLoader Field

dimension_system specify the general dimension <Field filePosition="03"

structure an item belongs to. For name="DimensionSystem" />
REQUIRED
example, MENS_TSHIRTS.

5-8 Technical Guide

 Style: Item Dimensions/Grid Setup

Table Detail: itm_item_dimension_type (continued)

Attribute Used to... DataLoader Field

dimension specify the code values <Field filePosition="04"

belonging to a dimension name="Dimension" />
REQUIRED
system. For example, COLOR,
SIZE, etc.

seq specify the number that <Field filePosition="05"

correlates this dimension type name="Sequence" />
REQUIRED
with one of the values associated
with an item in the
itm_item_dimension table.
For example, dimension COLOR
and sequence 1 in this record
means that dimension1 in
itm_item_dimension for an
item using this dimension
system is the color of that item.

sort_order determine the row/column/page <Field filePosition="06"

order represented in the grid name="SortOrder" />
view of inventories for that style.
The lowest value is the row
dimension, the next-highest
value is the column dimension,
and highest value is the page
dimension.
Also, when selling an item by
style, this value determines the
order in which the system
prompts for dimension values. If
not specified, the order will be
arbitrary; however, the default
will be the way in which the data
was retrieved from the database.

description define a text description for a <Field filePosition="07"

dimension code used for display. name="Description" />
If this description is not defined,
the system displays the
dimension code value.

prompt_msg define the message displayed to <Field filePosition="08"

the user when prompting for name="PromptMessage" />
values for this dimension type
when selling an item by style.
This value can be a literal value
or a translation key. If not
specified, a default message will
be used.

org_code specify the organization level <Field filePosition="09"

code based on the customer's name="orgCode"/>
store structure. Ex: STORE,
DISTRICT, REGION, CHAIN,
and so on (to be defined by
clients)
Default value set to *

Item and Pricing Configuration 5-9

Style: Item Dimensions/Grid Setup

Table Detail: itm_item_dimension_type (continued)

Attribute Used to... DataLoader Field

org_value specify the value for the <Field filePosition="10"

organization level code. Ex: for name="orgValue"/>
store 123, the org_code will be
STORE and the org_value will be
123
Default value set to *

itm_item_dimension_value Table Setup

Table Description

itm_item_dimension_ Contains all possible values associated with each dimension within a
value dimension system.

DataLoaderConfig.xml Records

<RecordType name="ITEM_DIMENSION_VALUE">

Table Detail: itm_item_dimension_value

Attribute Used to... DataLoader Field

dimension_system specify the general dimension <Field filePosition="03"

structure an item belongs to. name="DimensionSystem" />
REQUIRED

dimension specify the code values <Field filePosition="04"

belonging to a dimension name="Dimension" />
REQUIRED
system. This is a coded value.
For example, COLOR, SIZE, etc.

value specify the specific values <Field filePosition="05"

associated with a dimension for name="DimensionValue" />
REQUIRED
a dimension system. This is a
coded value. For example, RED,
BLUE, and so on for the
dimension COLOR.

5-10 Technical Guide

 Style: Item Dimensions/Grid Setup

Table Detail: itm_item_dimension_value (continued)

Attribute Used to... DataLoader Field

sort_order determine the order in which <Field filePosition="06"

dimension values appear in the name="SortOrder" />
item grid. Values sorted in
ascending order appear:
- Top to bottom for rows
- Left to right for columns
- First to last for page
When selling an item by style,
this determines the order in
which dimension values appear
in the prompt list. If not
specified, the order will be
arbitrary; however, the default
will be the way in which the data
was retrieved from the database.

description define a text description of the <Field filePosition="07"

value code. If this description is name="Description" />
not defined, the system displays
the value code itself.

org_code specify the organization level <Field filePosition="08"

code based on the customer's name="orgCode"/>
store structure. Ex: STORE,
DISTRICT, REGION, CHAIN,
etc. (to be defined by clients)
Default value set to *

org_value specify the value for the <Field filePosition="09"

organization level code. Ex: for name="orgValue"/>
store 123, the org_code will be
STORE and the org_value will be
123
Default value set to *

itm_item_dimension Table Setup

Table Description

itm_item_dimension Stores the specific dimensions associated with specific items.

DataLoaderConfig.xml Records

<RecordType name="ITEM_DIMENSION_2">

Item and Pricing Configuration 5-11

Style: Item Dimensions/Grid Setup

Table Detail: itm_item_dimension

Attribute Used to... DataLoader Field

item_id uniquely identify the item. <Field filePosition="03"

REQUIRED name="ItemId" />

dimension1 define the value for the first *<Field filePosition="04"

dimension. If present, this should name="Dimension1" />
correspond to one of the coded
values in
itm_item_dimension_value.

dimension2 define the value for the second *<Field filePosition="05"

dimension. If present, this should name="Dimension2" />
correspond to one of the coded
values in
itm_item_dimension_value.

dimension3 define the value for the third *<Field filePosition="06"

dimension. If present, this should name="Dimension3" />
correspond to one of the coded
values in
itm_item_dimension_value.

org_code specify the organization level code <Field filePosition="07"

based on the customer's store name="orgCode"/>
structure. Ex: STORE, DISTRICT,
REGION, CHAIN, etc. (to be defined
by clients)
Default value set to *

org_value specify the value for the organization <Field filePosition="08"

level code. Ex: for store 123, the name="orgValue"/>
org_code will be STORE and the
org_value will be 123
Default value set to *

Note: *If provided, these fields can be sent in with the following fields
on the ITEM record as well:
<Field filePosition="83" name="Dimension1" />
<Field filePosition="84" name="Dimension2" />
<Field filePosition="85" name="Dimension3" />
<Field filePosition="86" name="OrgCode" />
<Field filePosition="87" name="OrgValue" />

Style: Item Grid SysConfig.xml Setup

Set up the following configuration option for item lookup grid functionality in
SysConfig.xml.
<Setting name="ItemLookup---LoadGrid">true</Setting>
<Setting name="ItemLookup---LoadPriceHistory">true</Setting>

5-12 Technical Guide

 Style: Item Dimensions/Grid Setup

<Setting name="ItemLookup---LoadSalesHistory">true</Setting>
<Setting name="ItemLookup---LoadSimilar">true</Setting>
<Setting name="ItemLookup---LoadSubstitute">true</Setting>
<Setting name="ItemLookup---LoadUpcs">true</Setting>
<Setting name="ItemLookup---PriceHistoryDays">30</Setting>
<Setting name="ItemLookup---SalesHistoryWeeks">12</Setting>
<Setting name="ItemLookup---ShowAdvancedSearchForm">false</
Setting>
- LoadGrid - Determines whether or not the system displays the first item grid
page for the item lookup screen.
* When true, the first item grid page for the item is displayed on the lookup
screen.
* When false, the item grid page for the item is not displayed.

Xstore Point of Service Example - Entering a Style ID During a Sale

Once the tables and configuration option are set up as described above, the functionality
works as follows:
1. During a sale transaction the associate will be prompted to scan/enter an item ID.
2. At the prompt for an item ID, the associate enters the itm_item.item_id for the
style item.
3. Xstore Point of Service will iterate through a series of prompts, one for each
dimension, until the specific item within the style is identified.
The list of valid values to select for a given dimension is the union of all
itm_item_dimension.value values for every item within the style.
4. Once the specific item within the style is identified, the line item is added to the sale.

Xstore Point of Service Example - Item Lookup By Style Using the Item
Grid
1. When the associate selects the Item Lookup menu option, Xstore Point of Service
displays the Item Lookup form.
2. The associate enters the itm_item.item_id for the style item and Xstore Point of
Service displays the item detail screen.

Item and Pricing Configuration 5-13

Style: Item Dimensions/Grid Setup

3. The Style Grid tab shows the style dimension information.

Figure 5-1: Style Grid Tab Example

itm_item table Setup Example

parent_ dimension_
item_id name description item_lvlcode item_id system

330000 Tee Shirt Tee Shirt STYLE NULL MENS_TSHIRTS

330001 Blue S Tee Blue S Tee ITEM 330000 NULL

Shirt Shirt

330002 Blue M Tee Blue M Tee ITEM 330000 NULL

Shirt Shirt

330003 Blue L Tee Blue L Tee ITEM 330000 NULL

Shirt Shirt

330101 Red S Tee Red S Tee ITEM 330000 NULL

Shirt Shirt

Note: Not all table values are shown for the grid example.

itm_item_dimension_type Setup Example

dimension_system dimension seq sort_order description prompt_msg

MENS_TSHIRTS COLOR 1 10 Color NULL

MENS_TSHIRTS SIZE 2 20 Size NULL

5-14 Technical Guide

 Style: Item Dimensions/Grid Setup

itm_item_dimension_value Setup Example

dimension_system dimension value sort_order description

MENS_TSHIRTS COLOR BLACK 50 Black

MENS_TSHIRTS COLOR BLUE 10 Blue

MENS_TSHIRTS COLOR GREEN 30 Green

MENS_TSHIRTS COLOR RED 20 Red

MENS_TSHIRTS SIZE L 30 Large

MENS_TSHIRTS SIZE M 20 Medium

MENS_TSHIRTS SIZE S 10 Small

Note: Not all table values are shown for the grid example.

itm_item_dimension Setup Example

item_id dimension1 dimension2 dimension3

330001 BLUE S NULL

330002 BLUE M NULL

330003 BLUE L NULL

330101 RED S NULL

Note: Not all table values are shown for the grid example.

Item and Pricing Configuration 5-15

Item Cross Reference Database Setup

Item Cross Reference Database Setup

Set up the itm_item_cross_reference table to allow for item lookup by a manufacturer’s
UPC and other types of alternate IDs. There must be an item or non physical item record
for each Item ID specified in this table. For information about this table and the
Dataloader record used to populate it, see the Xstore Point of Service Database Dictionary
and the Xstore Point of Service Host Interface Guide.

Item Vendor Database Setup

Set up the itm_vendor table and the com_address table to define the vendor
information. For information about these tables and the Dataloader record used to
populate them, see the Xstore Point of Service Database Dictionary and the Xstore Point of
Service Host Interface Guide.

Attached Item Database Setup

Set up the itm_attached_items table to create a relationship between items for the
purpose of automatically adding an “attached” item to a transaction when an item with
an itm_item.attached_items_flag of true is sold.
When selling an item that has at least one attached item:
- If there is one attached item, display a prompt to ask if the attached item should
be added to the transaction (when
itm_attached_items.prompt_to_add_flag is set to true).
- If there are two or more attached items, prompt with the list of attached items
(when itm_attached_items.prompt_to_add_flag is set to true):
* The user can select one or more items from the list (multi-select list).
* All selected items will automatically be added to the sale transaction along
with the original item that was sold.
- Attached item functionality does not apply to returns, orders, and special
orders.

- The attached item icon displays next to an attached item on the View Port.
For information about this table and the Dataloader record used to populate it, see the
Xstore Point of Service Database Dictionary and the Xstore Point of Service Host Interface
Guide.

Attached Items Setup in SysConfig.xml

The following configuration options for attached items functionality are found in
SysConfig.xml. For more information about item messaging, refer to Chapter 6, “Item
Messaging Configuration”.
<Setting name="AttachedItems---AddWithMessage">true</Setting>
<Setting name="AttachedItems---EnableAttachedItems">true</
Setting>
<Setting name="AttachedItems---
MessageKey">_messageAssocItemAdded</Setting>
<Setting name="AttachedItems---
MessageTitle">_associatedItemMsgTitle</Setting>

5-16 Technical Guide

 Substitute Item Setup

<Setting name="AttachedItems---NotifyItemAdded">true</Setting>
- EnableAttachedItems - This configuration option turns on/off the attached
item functionality.
* When true, attached item functionality is enabled.
* When false, attached item functionality is disabled.
- NotifyItemAdded - Determines whether or not the system displays a prompt
whenever an attached item is added to the retail transaction.
* When true, a prompt is displayed whenever an attached item is added to the
retail transaction.
* When false, no prompt is displayed when an attached item is added to the
retail transaction.
- AddWithMessage - Determines whether or not the system notifies the associate
by displaying the message in the instruction area of the sale screen whenever an
attached item is added to the retail transaction.
* If true, a notification message is displayed in the instruction area of the sale
screen whenever an attached item is added to the retail transaction.
* If false, a notification message is not displayed in the instruction area of the
sale screen when an attached item is added to the retail transaction.
- MessageTitle - If AddWithMessage is true, the text attached to this value in
the translations.properties file will be displayed in the message title. See
Chapter 6, “Item Messaging Configuration” for more information about item
messaging setup.
- MessageKey - If AddWithMessage is true, the text attached to this value in the
translations.properties file will be displayed as the message. See
Chapter 6, “Item Messaging Configuration” for more information about item
messaging setup.

Substitute Item Setup

Set up the itm_substitute_items table to create a relationship between items for the
purpose of identifying items that may be substituted or offered in place of another item.
For substitute items to be displayed in item lookup, the following conditions must be
met:
- itm_item.substitute_available_flag must be true (1).
- In SysConfig.xml, Store/System/ItemLookup/LoadSubstitute must be set to true.
See “Item Lookup Configuration in SysConfig.xml”.
- An item must exist in the itm_substitute_items table where the
primary_item_id is the item_id of the item looked up.
For information about this table and the Dataloader record used to populate it, see the
Xstore Point of Service Database Dictionary and the Xstore Point of Service Host Interface
Guide.

Similar Item Setup

Similar items are items with the same Style ID. For similar items to be displayed in item
lookup, the following conditions must be met:

Item and Pricing Configuration 5-17

Item Prompting Database Setup

• In SysConfig.xml, Store/System/ItemLookup/LoadSimilar must be set to true.

</ItemLookup>
<Setting name="ItemLookup---LoadGrid">true</Setting>
<Setting name="ItemLookup---LoadPriceHistory">true</Setting>
<Setting name="ItemLookup---LoadSalesHistory">true</Setting>
<Setting name="ItemLookup---LoadSimilar">true</Setting>
<Setting name="ItemLookup---LoadSubstitute">true</Setting>
<Setting name="ItemLookup---LoadUpcs">true</Setting>
<Setting name="ItemLookup---PriceHistoryDays">30</Setting>
<Setting name="ItemLookup---SalesHistoryWeeks">12</Setting>
<Setting name="ItemLookup---ShowAdvancedSearchForm">false</
Setting>
• The itm_item.parent_item_id for the item is the Style ID.

Item Prompting Database Setup

Set up the itm_item_prompt_properties table to prompt for additional information
as an item is sold. For information about this table and the Dataloader record used to
populate it, see the Xstore Point of Service Database Dictionary and the Xstore Point of
Service Host Interface Guide.

Item Lookup Configuration in SysConfig.xml

The following configuration options found in SysConfig.xml pertain to item lookup
functionality.
<Setting name="ItemLookup---LoadGrid">true</Setting>
<Setting name="ItemLookup---LoadPriceHistory">true</Setting>
<Setting name="ItemLookup---LoadSalesHistory">true</Setting>
<Setting name="ItemLookup---LoadSimilar">true</Setting>
<Setting name="ItemLookup---LoadSubstitute">true</Setting>
<Setting name="ItemLookup---LoadUpcs">true</Setting>
<Setting name="ItemLookup---PriceHistoryDays">30</Setting>
<Setting name="ItemLookup---SalesHistoryWeeks">12</Setting>
<Setting name="ItemLookup---ShowAdvancedSearchForm">false</
Setting>
- PriceHistoryDays - Number of days for which the system retrieves price
history data for the lookup item to be displayed on the item lookup screen.
- LoadUpcs - Determines whether or not the system displays all UPC numbers
for this item.
* When true, the system displays all UPC numbers for this item.
* When false, the system does not display all UPC numbers for this item.

5-18 Technical Guide

 Item Lookup Configuration in SysConfig.xml

- LoadSimilar - Determines whether or not the system displays all items with
the same style as the current item.
* When true, the system displays all items with the same style as the current
item.
* When false, the system does not display items with the same style as the
current item.
- LoadSubstitute - Determines whether or not the system displays all
substitute items for the current item.
* When true, the system displays all substitute items for the current item.
* When false, the system does not display substitute items.
- LoadPriceHistory - Determines whether or not the system displays the price
history of the current item.
* When true, the price history of the current item is displayed.
* When false, the price history of the current item is not displayed.
- LoadSalesHistory - Determines whether or not the system displays the sales
history of the current item.
* When true, the sales history of the current item is displayed.
* When false, the sales history of the current item is not displayed.
- LoadGrid - Determines whether or not the system displays the first item grid
page for the item lookup screen.
* When true, the first item grid page for the item is displayed on the lookup
screen.
* When false, the item grid page for the item is not displayed.

Note: See “Style: Item Dimensions/Grid Setup” for more information

about setting up an item grid.

- LocatorDistanceUnit - Determines the unit of measure that will be used for

distance when using item lookup: MILE or KILOMETER.
- SalesHistoryWeeks - Indicates how many weeks of sales history will be
displayed when an item lookup is done in the replenishment module. Sales
history information is displayed in the Sales History tab.
- ShowAdvancedSearchForm - Determines whether or not Xstore Point of
Service will use advanced search criteria to find and view items in Item Lookup.

Item and Pricing Configuration 5-19

Kit Item Setup

Kit Item Setup

A Kit item is composed of other items (component items) found in the Xstore Point of
Service database.
• Kit items are set up in the itm_item table, just like any other item.
• Component items that make up a Kit must be valid items in the itm_item table,
and must also be set up in the itm_kit_component table. The
itm_kit_component table maps the kit component items to their parent Kit item
in the itm_item table.

Note: Kits can be sold through layaway, send sale, remote send, and
special order, but not through distributed orders.

When a Kit is added to a sale, the component items are displayed in rows below, and
part of, the parent kit line item. Component items are displayed as the quantity included
in the Kit line item, along with the component item description. The lines that identify
the kit components are not line items themselves and cannot be changed: they are
provided as a visual reminder of what items make up the Kit. The Kit item itself cannot
prompt for price and cannot contain any components that are set to prompt for price.
Taxes and discounts applied to the Kit ignore the component items of the Kit. In
addition, any deals available for the component items individually will not be taken into
account in deal calculations for the kit.
Once a Kit is sold and its transaction has been persisted, the record of the Kit being sold
and what components made up the Kit resides in the database.
The trl_kit_component_mod table contains the collection of all kit component
modifiers for all persisted Kit sale line items. (As such, it can be thought of as a child of
the trl_sale_lineitm table). The kit component modifier records each belong to a
sale line item that represents the sale or return of a Kit item.
The kit component modifier records contain:
• the item ID of the kit component item,

• the extended quantity1 of the kit component item,

• and the component item's description at the time of the sale.

Note: Refer to the Xstore Point of Service Database Dictionary for

more information about the trl_kit_component_mod table.

1.This value will always be the number of component items per Kit times the number of Kits sold and is not affected
by the LinkComponentQtyToKitQty setting in SysConfig.xml

5-20 Technical Guide

 Kit Item Setup

Database Setup for Kits

1. Set up the parent Kit item in the itm_item table. For information about this table
and the Dataloader record used to populate it, see the Xstore Point of Service Database
Dictionary and the Xstore Point of Service Host Interface Guide.
2. Set up the kit component items in the itm_kit_component table. For information
about this table and the Dataloader record used to populate it, see the Xstore Point of
Service Database Dictionary and the Xstore Point of Service Host Interface Guide.

Note: A kit component whose begin and end dates do not include the
current day of business will not be included in the kit. This will not
affect the sale/availability of the kit itself, just the components that
make up the kit.

System Config Setup for Kits

SysConfig.xml settings control the maximum number of component items to display,
whether the quantity displayed for a kit component line is a reflection of the quantity of
the parent kit line item's quantity or is the number of the component items per kit, how
the kit items are inventoried, and Xstore Point of Service behavior when a kit is returned.
<Setting name="Kits---InventoryKitComponents">true</Setting>
<Setting name="Kits---LinkComponentQtyToKitQty">true</
Setting>
<Setting name="Kits---NumKitComponentsToDisplay">5</Setting>
<Setting name="Kits---PromptKitComponentsAtReturn">true</
Setting>
- PromptKitComponentsAtReturn - Determines whether or not Xstore Point
of Service will display a prompt containing a list of the kit components. If set to
true, this allows the user to confirm that the entire kit is present before accepting
the return. The user may continue with the return, or cancel if all the kit
components are not present.

Note: Proceeding with the return is a secured option that requires the
user to have the RETURN_KIT privilege.

* When set to true, the prompt is displayed.

* When set to false, the prompt is not displayed and system will route directly
to the Xstore Point of Service return process. The security privilege of
RETURN_KIT will not be considered.

Note: Returns of items that are also components in one or more kits
are processed without consideration of their kit membership.

- LinkComponentQtyToKitQty - Determines whether or not the quantity of the

kit component rows on the virtual and real receipts are linked to the quantity of
the kit item.
* When true, the component item quantity displayed will be multiplied by the
quantity of the parent kit line item. For example, if there are 3 kits sold,

Item and Pricing Configuration 5-21

Kit Item Setup

component items are multiplied by 3. That is, they display the total number
of items in all kits.
* When false, the component item quantity will not change, regardless of the
parent kit line item's quantity. For example if there are 3 kits sold, the
component items are unchanged. That is, they display the number of items
in each kit.
- NumKitComponentsToDisplay - The maximum number of kit components to
display on the virtual receipt for a kit line item. If there are more kit components
than rows available for display, then the last row will be used to display a
continuation string, such as an ellipsis (...).
For example, if NumKitComponentsToDisplay is set to 5 and a kit has 5 items,
then all 5 items will be displayed. However, if the kit has 6 items, then 4 items
will be displayed and the fifth line will be used for “more...”.

Note: The receipt will show all items regardless of this value.

- InventoryKitComponents - Determines whether or not Xstore Point of

Service will inventory the components that make up a kit, or the kit items
themselves.
* When set to true, the kit components will be inventoried. Selling and
returning kits will update the inventoried quantity of each of the items
included in the kit, but not the kit item itself.
* When set to false, the kit items themselves will be inventoried. Selling and
returning kits will update the inventoried quantity for the kit item only.

5-22 Technical Guide

 Item Matrix

Item Matrix
Note: A touch-screen or mouse is required to use this feature.

The Item Matrix function displays an item touch grid that can be used during a sale to
find and add sale items to the current transaction. This feature is used to provide fast
access to a small subset of the item file.

Figure 5-2: Item Matrix Example

Item Matrix Database Setup

Note: Although the item matrix is configurable, it is not
recommended that you exceed 1,000 items.

Use the following “disallow_matrix_display_flag” flags to suppress items from

appearing in the matrix to ensure that only a subset of items (that is, less than 1000)
qualify for the matrix.

Note: A hierarchy above the item level (for example, departments or

classes) will not be displayed in the item matrix until items are
assigned to it.

• To exclude items from appearing on the item grid, set the following flag in the
itm_item table to true:
itm_item.disallow_matrix_display_flag

Item and Pricing Configuration 5-23

Item Images

• To exclude levels in the merch hierarchy from appearing on the item grid, set the
following flag in the itm_merch_hierarchy table to true:
itm_merch_hierarchy.disallow_matrix_display_flag
• Set up the color scheme in the com_code_value table.
Categories include the following:
ITEM_MATRIX_COLOR_CLASS
ITEM_MATRIX_COLOR_SUBCLASS
ITEM_MATRIX_COLOR_DEPT
ITEM_MATRIX_COLOR_ITEM
ITEM_MATRIX_COLOR_SUBDEPT
Supported colors include: DEFAULT, BLUE, AQUA, BRONZE, BROWN, GRAY,
GREEN, MAROON, ORANGE, PURPLE, RED, TEAL, and YELLOW

Item Matrix System Configuration

The following configuration options found in SysConfig.xml pertain to item matrix
functionality.
<Setting name="ItemMatrix---CacheEnabled">true</Setting>
<Setting name="ItemMatrix---Height">4</Setting>
<Setting name="ItemMatrix---Width">4</Setting>
CacheEnabled - Determines whether or not cache is enabled for the Item Matrix.
Height - The number of vertical buttons on the matrix (down). Based on the number
here, buttons will be scaled to fit the screen.
Width - The number of horizontal buttons on the matrix (across). Based on the number
here, buttons will be scaled to fit the screen.

Item Images
Xstore Point of Service provides a method to display multiple sizes of an item image as
they correspond to contextual areas of Xstore Point of Service. Using this method, you
can specify different sizes of an image to correspond to the display area in Xstore Point
of Service. For example, you can store a thumbnail sized picture, an item lookup sized
picture, and a purchase history sized picture to be used within the specific Xstore Point
of Service context.
Product images can be called from a file or from an “http address” that will produce the
image.
Recommended image sizes on 1024x768 resolution:

Context Area Image Size (pixels)

Quick Items tab 60x60

Customer Maintenance (Purchase History screen) 285x200

Item search result screen 327x343

Wish List screen 270x380

5-24 Technical Guide

 Quick Items Tab

Database Setup
The itm_item_images table stores image information for items. For information about
this table and the Dataloader record used to populate it, see the Xstore Point of Service
Database Dictionary and the Xstore Point of Service Host Interface Guide.

Quick Items Tab

The Quick Items tab provides a way for associates to quickly add commonly sold items
to a transaction. The items are simply identified by an image on the tab, and once
selected by the associate, the item is added to the transaction.

Figure 5-3: Tap the Image and the Item Information Displays in the View Port

The dot(s) at the bottom of the ITEMS page tab indicate the number of pages. (Only one
“dot” is shown in this example). If there are multiple dots, then there are multiple pages.
Swipe on the dots to get to the next available page.
The Quick Items tab displays items from the itm_quick_items table. It is populated
using DataLoader.
See Chapter 38, “Menu & Tab Configuration” for more information about setting up the
Quick Items tab.

Item and Pricing Configuration 5-25

Quick Items Tab

5-26 Technical Guide

 6
Item Messaging Configuration

Overview
There are several types of messages that may be displayed in the information section of
the register screen during a sale transaction: text messages, HTML messages, titled
image messages, and composite messages.
• Text messages consist of only text characters that will wrap within the confines of
the information section on the register screen. The text information will adjust to fit
within the information section according to the amount of text in the message. No
images can be included as part of a text message. Place the .txt file in the directory as
defined in <MessageFilePath> in SysConfig.xml.
• HTML messages may include both graphics and text. Often HTML messages are
used to show a picture of an item at the register as it is being sold. If an HTML
message is configured to display an image with embedded text, the text size and
picture size will always be the same when it displays. Place the HTML file in the
directory as defined in <MessageFilePath> in SysConfig.xml.
• Titled Image messages consist of an image displayed along with a title on the top of
the information section area. Place the graphic file in the directory as defined in
<MessageFilePath> in SysConfig.xml. Supported image types include: jpg, gif,
bmp, jpeg, png, wbmp.
• Composite messages include both graphics and text. An image and text message are
displayed together in the information section area. No title is displayed. The layout
of the image in relation to the text message is configured via four layout options
handled by four HTML templates. The templates are stored along with the item
message images in <MessageFilePath> in SysConfig.xml. Supported image types
include: jpg, gif, jpeg, png, wbmp (not bmp).
The procedure for setting up all types of messages is similar. If specific times or dates are
associated with an item, a message may be configured to display for just that period and
it must be associated with a specific transaction type.
The item message setup process uses both database tables and configuration files. In this
chapter, the database table information and the DataLoader Record and fields are listed
for each table and column. The SysConfig.xml item messaging options are also listed
here.
The process required to set up messages for items, and a link to each section for more
information, is provided below:
1. Set up the message detail in the itm_item_msg table to define messages that can be
specifically tied to items in a sale (“Item Message Detail Database Setup”).

Item Messaging Configuration 6-1

Overview

2. Specify the type of transaction (Sale, Return, etc.) during which the message should
appear in the itm_item_msg_types table (“Transaction Type Database Setup”).

Note: You can then further classify the specific sale transaction types
(Send Sale, Layaway, etc.) in SysConfig.xml. (“Message Configuration
Options in System Config”)

3. Map the message to the item(s) in the itm_item_msg_cross_reference table

(“Message to Item Mapping Database Setup”).
4. Enable the message for the item(s) in the itm_item table (“Item Messaging Database
Setup”).
5. Define the title key (if used) and the message key in the
translations.properties file (“Message Setup in translations.properties”).
6. Verify the path where the message files are placed: <MessageFilePath> in
SysConfig.xml. The default is ${user.dir}/res/html/msgs.

Note: The configuration value for the message path should not be
changed.

7. Place the html/text/graphic files in the appropriate directory as defined in

<MessageFilePath> in SysConfig.xml.
8. Set up additional message configuration options in SysConfig.xml as needed
(“Message Configuration Options in System Config”).

6-2 Technical Guide

 Item Message Detail Database Setup

Item Message Detail Database Setup

For each message, define the unique message identifier, effective date, expiration date (if
needed), the message key used for text translation in the
translations_en.properties file, the title key used for text translation for the title
of the message in the translations_en.properties file (if used) and the message
content type, the configure the message in the itm_item_msg table.
For information about the itm_item_msg table and the Dataloader record used to
populate it, see the Xstore Point of Service Database Dictionary and the Xstore Point of
Service Host Interface Guide.

Transaction Type Database Setup

Set up the itm_item_msg_types table to indicate the type of sale transaction during
which the message should appear. To further classify sale transaction types, configure
the “DisplayOn...” elements in the <ItemMessaging> section in SysConfig.xml. For
information about this table and the Dataloader record used to populate it, see the Xstore
Point of Service Database Dictionary and the Xstore Point of Service Host Interface Guide.

Message to Item Mapping Database Setup

Associate the message to an item, or items, in the itm_item_msg_cross_reference
table. For information about this table and the Dataloader record used to populate it, see
the Xstore Point of Service Database Dictionary and the Xstore Point of Service Host Interface
Guide.

Item Messaging Database Setup

To enable item messaging, set the itm_item_options.messages_flag to true.
When this flag is set to true, the application automatically looks for additional item
message detail. See Chapter 5, “Item and Pricing Configuration”, for more information
about item setup.

Message Setup in translations.properties

Define the message key (msg_key) and title key (title_key) in the
translations.properties file: translations_en.properties.

Note: A message can be translated into another language by entering

the message key and the title key into the appropriate language
properties file. For example, text messages for French-Canadian are
stored in the translations_fr_CA.properties file.
Database translations are also supported.

• The message key contains the name of the HTML or text file, or an i18n translation
containing the name of a text, html, or image file in
translations_en.properties file (or other translation file such as
translations_fr_CA.properties).
• The title key is a text translation or an i18n translation key name for the title of the
message or the message that appears in the message window. This is optional in
some message types.

Item Messaging Configuration 6-3

Setup Examples - HTML and Text Messages

The message key and title key must begin with the underscore character (_) and are case
sensitive. An equal sign (=) separates the key from the message. The message key and
title key in the file must match the corresponding entries in the itm_item_msg table.

Setup Examples - HTML and Text Messages

The following examples are provided to show sample item messages: HTML and text.
For both message types, the following setup options apply in the examples:
1: itm_item_msg Table

itm_item_msg Values:
message ID= SUM1
effective date= 01/15/2009
message key= _TESTItemMsg1Key
title key= _TESTItemMsg1Title
set content type to text/html
2: itm_item_msg_types Table

itm_item_msg_types Values:
message ID= SUM1
sale line item type code= SALE
3: itm_item_msg_cross_reference Table

itm_item_msg_cross_reference Values:
message ID= SUM1
item ID= 6015 (Charcoal Suit)
4: itm_item Table

itm_item Values:

6-4 Technical Guide

 Setup Examples - HTML and Text Messages

item messages flag= true for item ID 6015 (Charcoal Suit)

5: translations_en.properties
Define the message key and title key in translations_en.properties for each
message type:
For HTML Values:
_TESTItemMsg1Key=SuitSuggSellSized.htm
_TESTItemMsg1Title=FEATURED ITEM
For Text Values:
_TESTItemMsg1Key=Scarf.txt
_TESTItemMsg1Title=FEATURED ITEM

The results...HTML File Example

In translations_en.properties:
Message Key Example =_TESTItemMsg1Key=SuitSuggSellSized.htm

Note: No message title was specified in the example shown below.

Would result in this item HTML message displayed when the specified item (6015) is
sold:

The results... Text File Example

Note: The text will be centered in the display area and word-wrapped
as necessary. There is no ability to include sentence formatting within
the text. If formatting is required, use an HTML message.

In translations_en.properties:
Message Key Example =_TESTItemMsg1Key=Scarf.txt

Note: No message title was specified in the example shown below.

Item Messaging Configuration 6-5

Setup Example - Composite Message

Would result in this item text message displayed when the specified item (6015) is sold:

Setup Example - Composite Message

The following example is provided to show the setup required for a Composite type
item message.
1: itm_item_msg Table

itm_item_msg Values:
message ID= Reminder, effective date= 01/15/2009
message key= _ItemMessageReminderKey
title key=_ItemMessageReminderTitle
set content type to multipart/mixed

Note: The content_type field of the itm_item_msg table for the item
message must contain the value: multipart/mixed.

2: itm_item_msg_types Table

itm_item_msg_types Values:
message ID= Reminder
sale line item type code= SALE

6-6 Technical Guide

 Setup Example - Composite Message

3: itm_item_msg_cross_reference Table

itm_item_msg_cross_reference Values:
message ID= Reminder
item ID= 6022 (Silk Tie)
4: itm_item Table

itm_item Values:
item messages flag= true for item ID 6022 (Silk Tie)
5: translations_en.properties
Define the message key and title key in translations_en.properties.
translations_en.properties Values:
_ItemMessageReminderKey=Necktie.png

Note: Images larger than the message area will NOT be scaled down
to fit. Large images may push the text message out of the user's view.

.bmp images are not supported in this message type.

_ItemMessageReminderTitle= Attention Associates: Don't forget to

remove the security tag from this item.
6: Specify the image location in relation to the text in SysConfig.xml: top, bottom, left,
or right.
SysConfig.xml Value:
<Setting name="ItemMessaging---
CompositeMessageImagePosition">right</Setting>

Item Messaging Configuration 6-7

Setup Example - Titled Image Message

The results... Composite Message Example

The sold item (6022) is associated with the message ID (Reminder) in a SALE transaction.
Message Title Example=_ItemMessageReminderTitle= Attention Associates: Don't
forget to remove the security tag from this item

Note: No title is displayed in this message type; instead, the message

text from the i18n Key is shown in the position related to the image
location mapping.

Message Key Example =_ItemMessageReminderKey=Necktie.png (The message key

image in png format)
In this example, the image position is to the left of the message as defined in
SysConfig.xml.
<Setting name="ItemMessaging---
CompositeMessageImagePosition">right</Setting>

Setup Example - Titled Image Message

The following example is provided to show the setup required for a Titled Image type
item message.
1: itm_item_msg Table

itm_item_msg Values:
message ID= Adopt, effective date= 01/15/2009
message key= _ItemMessagePetAdoptionKey
title key=_ItemMessagePetAdoptionTitle
set content type to image/?

Note: The content_type field of the itm_item_msg record for the

item message must contain the value: image/? or image/<image type>?

6-8 Technical Guide

 Setup Example - Titled Image Message

2: itm_item_msg_types Table

itm_item_msg_types Values:
message ID= Adopt
sale line item type code= SALE
3: itm_item_msg_cross_reference Table

itm_item_msg_cross_reference Values:
message ID= Adopt
item ID= 7005 (Pet Adoption)
4: itm_item Table

itm_item Values:
item messages flag= true for item ID 7005 (Pet Adoption)
5: translations_en.properties
Define the message key and title key in translations_en.properties.
translations_en.properties Values:
_ItemMessagePetAdoptionKey=Pet.gif

Note: Images larger than the message area will be scaled down to fit.
However, when an image is configured to be on the right, it may be
cut off if it is too large to fit into the space reserved for images.

_ItemMessagePetAdoptionTitle=Thank You!

Item Messaging Configuration 6-9

Message Configuration Options in System Config

The results... Titled Message Example

The sold item (7005) is associated with the message ID (Adopt) in a SALE transaction.
Message Title Example=_ItemMessagePetAdoptionTitle=Thank You!
Message Key Example =_ItemMessagePetAdoptionKey=Pet.gif).
Images larger than the message area will be scaled down to fit.

Message Configuration Options in System Config

Set up the following item message options in SysConfig.xml as needed.
<Setting name="ItemMessaging---ClearViewOnBlankMessage">true</
Setting>
<Setting name="ItemMessaging---
CompositeMessageImagePosition">right</Setting>
<Setting name="ItemMessaging---
DefaultMessageTitle">_defaultItemMessageTitle</Setting>
<Setting name="ItemMessaging---
DefaultMessageURL">_defaultItemMessage</Setting>
<Setting name="ItemMessaging---DisplayMessage">true</Setting>
<Setting name="ItemMessaging---DisplayMessageAsNotify">false</
Setting>
<Setting name="ItemMessaging---DisplayOnReturnItem">false</
Setting>
<Setting name="ItemMessaging---DisplayOnSaleItem">true</Setting>
<Setting name="ItemMessaging---DisplayOnSendItem">false</Setting>
<Setting name="ItemMessaging---
InstructionalMsgIcon">classpath:graphics/attention.gif</Setting>
<Setting name="ItemMessaging---MessageFilePath">${user.dir}/res/
html/msgs/</Setting>
<Setting name="ItemMessaging---
RegisterInstructionalMsgTitle">_defaultItemMessageTitle</Setting>
<Setting name="ItemMessaging---StyleMessageSupersede">true</
Setting>
- DisplayMessage - Determines whether or not the system displays item
messages for the current sale item on the sales screen using the current thread. If

6-10 Technical Guide

 Message Configuration Options in System Config

both DisplayMessage and DisplayMessageThreaded are set to true,

DisplayMessageThreaded configuration takes priority.
- ClearViewOnBlankMessage - Determines whether or not the system clears
the item message view when the current sale item is not configured with any
item message. If true, the message is removed. If false, the message is not cleared
when the current sale item is not configured with any item message.
- StyleMessageSupersede - When the current item and the style of the current
item are configured with item messages, the system uses this configuration to
display the message configured for the style of the current item (true) instead of
displaying the message for the current item. If true, the system displays the
message configured for the style of the current item. If false, the system displays
the message configured for the current item.
- DisplayMessageAsNotify - When set to true, the system displays item
messages using verify prompts instead of displaying the message in the item
message area of the sales screen.

Note: Only plain-text messages (not HTML-based or other types of

messages) are displayed when this attribute is set to true.

- DisplayOnSaleItem - Determines whether or not the system displays item

messages for regular sale items. If true, display item messages for regular sale
items. If false, do not display item messages for regular sale items.
- DisplayOnSendItem - Determines whether or not the system displays item
messages for send sale items. If true, display item messages for send sale items.
If false, do not display item messages for send sale items.
- DisplayOnReturnItem - Determines whether or not the system displays item
messages for return items. If true, display item messages for return items. If
false, do not display item messages for return items.
- MessageFilePath - Specifies the file location for the HTML and .txt message
files to be placed.
- DefaultMessageTitle - Specifies the default item message title key in the
translations.properties file.
- DefaultMessageURL - Specifies the default message file key in the
translations.properties file to use when no other message is present.
- InstructionalMsgIcon - Specifies the file location for the icon to be
displayed next to the message.
- RegisterInstructionalMsgTitle - Specifies the register instructional
message title key in the translations.properties file.
- CompositeMessageImagePosition - Specifies which HTML template is
used for displaying composite, image/text item messages. There are four
standard templates that correspond to four different layouts for the text and
image of an item message. Supported values include:
* top – Maps to the template which orients item image above text message.
* bottom – Maps to the template which orients item image below text
message.
* right – Maps to the template which orients item image to the right of the text
message.

Item Messaging Configuration 6-11

Message Configuration Options in System Config

* left – Maps to the template which orients item image to the left of text
message.

6-12 Technical Guide

 7
Tender Configuration

Overview
This chapter is designed to assist you in managing the Xstore Point of Service tender
types. Use the following information to define and set up the valid tender types and
tenders for your store.
The tender setup process uses both database tables and configuration files. In addition to
the database table information, the DataLoader Record and fields are listed for each table
and column.
Register sale transactions, till counting, petty cash, vouchers and other tender-related
transactions are all based on your tender configuration setup. Every tender is identified
by a "tender type" and has a "tender ID" associated with it.
The process required to set up tenders for your stores, and a link to each section for more
information, is provided below:

Note: Refer to the Xstore Point of Service Host Interface guide for more
information about the download record formats.

1. Define the tender types in the tnd_tndr_typcode table (“Tender Type Database
Setup”).
2. Define the tenders for each tender type in the tnd_tndr table (“Tender Database
Setup”).
3. Define the tender options for each tender type in the tnd_tndr_options table
(“Tender Options Database Setup”).
4. Define the unique denominations that are associated with each tender within an
organization in the tnd_tndr_denomination table (“Tender Denomination
Setup”).
5. Define when tenders may be used within the system by association with an
availability code in the tnd_tndr_availability table (“Tender Availability
Setup”).
6. Define the tenders that will be available to employee groups for specific transaction
types and uses, and the limits for those groups, in the tnd_tndr_user_settings
table (“Tender User Settings Setup”).
7. Define and set up the tender exchange rates for all foreign tenders used in your store
using the tnd_exchange_rate table (“Tender Exchange Rate Setup”).
8. Set up configuration options in SysConfig.xml as needed (“Miscellaneous Tender
Configuration Options”).

Tender Configuration 7-1

Tender Type Database Setup

9. If needed, modify the MenuConfig.xml file to add new tenders or remove any
tenders that will not be used (“Menu Config Configuration”).
10. If needed, set up threshold limits for requiring a customer signature based on
transaction total (“Credit Card Signatures Based on Tender Amount”).
11. If applicable, set up additional configuration options if you support giving change
back to the customer in foreign cash currency (“Foreign Cash Currency As
Change”).

Tender Type Database Setup

The first step for setting up tenders is to define the tender types in the
tnd_tndr_typcode table. Tender types are used to group tenders that have common
characteristics. See “Tender Type/Tender Values” for tender type values. For information
about this table and the Dataloader record used to populate it, see the Xstore Point of
Service Database Dictionary and the Xstore Point of Service Host Interface Guide.

Tender Database Setup

The next step in the tender setup process is to define the tenders for each tender type in
the tnd_tndr table. For information about this table and the Dataloader record used to
populate it, see the Xstore Point of Service Database Dictionary and the Xstore Point of
Service Host Interface Guide.

Tender Options Database Setup

The next step in the tender setup process is to define many other related options to
configure the ways that tenders will be used in your organization. This is done through
the tnd_tndr_options table. For information about this table and the Dataloader record
used to populate it, see the Xstore Point of Service Database Dictionary and the Xstore Point
of Service Host Interface Guide.

About Tender Authorization Components

Tender authorizations are usually processed through messaging to a bank. The POS
usually will not communicate directly to a bank; instead, the POS will communicate
with an authorization engine. For gift cards, there is additional configuration required in
VoucherConfig.xml that ties the item for selling the gift card with a voucher category
and tenders used when redeeming the gift card.
In addition to the table settings, tender authorization uses the settings in
AuthConfig.xml. The auth_mthd_code field is used to look up entries in
AuthConfig.xml.
• For Customer Engagement Cloud Services, the auth_mthd_code column in the
tnd_tndr_options table must be set to GIFT_CARD_RELATE.
• For Paymentech, the auth_mthd_code column in the tnd_tndr_options table
must be set to GIFT_CARD_PAYMENTECH.
• There is also an AuthMethodCode parameter for the AuthorizeBalanceOp
operation that needs to be set accordingly as well. This is in the
XPAY_BALANCE_INQUIRY op chain section of opchainconfig.xml.

About Tender Franking Components

The endorsement_req_flag in the tnd_tndr_options table is used to enable the
printing of information on financial documents (franking). The financial documents that

7-2 Technical Guide

 Tender Type/Tender Values

are most typically franked are gift certificates and checks. To view the MICR in the
Electronic Journal, you must enable ShowMicrButtonOnTransactionSearchForm
in System Config.

Note: Franking layout must also be defined in RcptConfig.xml for

the document type and activity.

Tender Type/Tender Values

Note: The values shown here are provided as examples only.

Tender Type Tender

ACCOUNT ACCOUNT_RECEIVABLE

ACCOUNT_CREDIT ACCOUNT_CREDIT

CHECK CHECK

PAYROLL CHECK PAYROLL_CHECK

TRAVELERS_CHECK CAD_TRAVELERS_CHECK

USD_TRAVELERS_CHECK

COUPON COUPON

CREDIT_CARD AMERICAN_EXPRESS

DEBIT_CARD

DINERS_CARD

DISCOVER

JCB

MASTER_CARD

PRIVATE_LABEL

VISA

ROOM_CHARGE

VOUCHER MERCHANDISE_CREDIT_CARD

GIFT_CARD

GIFT_CERTIFICATE

STORE_CREDIT

AJB_GIFT_CARD

DACS_GIFT_CARD

Tender Configuration 7-3

Tender Denomination Setup

Tender Type Tender (continued)

RELOAD_DACS_GIFT_CARD

RELOAD_GIFT_CARD

RELOAD_MERCHANDISE_CREDIT_CARD

ISSUE_MERCHANDISE_CREDIT_CARD

ISSUE_GIFT_CARD

ISSUE_AJB_GIFT_CARD

ISSUE_DACS_GIFT_CARD

ISSUE_GIFT_CERTIFICATE

ISSUE_MERCHANDISE_CREDIT_CARD

ISSUE_STORE_CREDIT

ISSUE_XPAY_POINTS_CARD

CURRENCY USD_CURRENCY

CAD_CURRENCY

EUR_CURRENCY

LOCAL_CURRENCY_ROUNDING

GBP_CURRENCY

HOME_OFFICE_CHECK HOME_OFFICE_CHECK

MISCELLANEOUS MISC_TENDER_1

MANUFACTURER_COUPON

MISCELLANEOUS_VOUCHER MALL_CERTIFICATE

Tender Denomination Setup

The next step in the tender setup process is to define the unique denominations that are
associated with each currency tender (tender_id) within an organization in the
tnd_tndr_denomination table. For information about this table and the Dataloader
record used to populate it, see the Xstore Point of Service Database Dictionary and the
Xstore Point of Service Host Interface Guide.

Tender Availability Setup

The next step in the tender setup process is to define when tenders may be used within
the system by association with an availability code. This is done through the
tnd_tndr_availability table. A tender’s availability is specified by indicating the
transaction type/use with which it may be used in the availability_code column.
For information about this table and the Dataloader record used to populate it, see the
Xstore Point of Service Database Dictionary and the Xstore Point of Service Host Interface
Guide.

7-4 Technical Guide

 Tender User Settings Setup

Tender User Settings Setup

The next step in the tender setup process is to define the tenders that will be available to
employee groups for specific transaction types and uses, and to set limits for the use of
the tenders. This is done through the tnd_tndr_user_settings table. For
information about this table and the Dataloader record used to populate it, see the Xstore
Point of Service Database Dictionary and the Xstore Point of Service Host Interface Guide.

Note: The employee group IDs are set up in the sec_groups table.
See “Credit Card Signatures Based on Tender Amount” for more
information about eliminating the requirement for a customer
signature when the amount due is less than a pre-defined threshold
amount for a credit card tender.

Tender Exchange Rate Setup

The next step in the tender setup process is to define and set up the tender exchange
rates in the tnd_exchange_rates table for all foreign tenders used in your
organization/store. When a currency other than the local currency is used to tender a
transaction, the system converts the entered amount into the local currency using the
exchange rate defined here and displays the change due in local currency and prints the
information on the receipt. This functionality is also used to support returns.
The exchange rate with the base currency ID of the local currency ID is the value that is
used to calculate a converted currency amount. The exchange rate is stored as a factor of
the local exchange rate. The conversion is calculated by multiplying the local currency
by the exchange rate.
The Print as Inverted flag is used to print the exchange rate in the format 1/n on
receipts. This is used for countries where the value of the local currency is very low
compared with the target currency: instead of printing “1 XXX = 0.000123 YYY” the
value 1/0.000123  “1 YYY = 8130.08 XXX” is printed.
Xstore Point of Service supports the ability to override currency exchange rates at any
node in your organization so that different exchange rates can be maintained at different
hierarchy levels.
For example, you can create a record for USD-->CAD, and you can also create a
REGION:1 record for USD-->CAD. In this example, any store under the REGION:1
hierarchy level will use the REGION:1 record.

Note: This setup is different than the standard orgCode/orgValue

structure within Xstore Point of Service. The tnd_exchange_rate
table uses level_code and level_value rather than org_code
and org_value. This ensures that the “behind the scenes”
manipulation of queries involving tables that have org_code and
org_value columns will not affect exchange rates.

For information about this table and the Dataloader record used to populate it, see the
Xstore Point of Service Database Dictionary and the Xstore Point of Service Host Interface
Guide.

Tender Configuration 7-5

Check Tender Setup

Check Tender Setup

In addition to the database setup for checks, the following configuration options are
found in SysConfig.xml:
<Setting name="CheckTender---MinimumCheckNumber">1</Setting>
<Setting name="CheckTender---PromptForBirthday">true</Setting>
• Set the PromptForBirthday option to True if you want Xstore Point of Service to
display a prompt for the associate to enter the customer’s birth date.
• Specify the minimum check number you will accept in the MinimumCheckNumber
configuration. For example, this option may be used to only accept checks with
number 101 and greater to not allow “new” checking accounts to be used.

Credit/Debit Card Setup

In addition to the database setup for credit/debit cards, the following configuration
options are found in SysConfig.xml.
<Setting name="CreditDebitTender---
ExportHashedAccountNumber">false</Setting>
<Setting name="CreditDebitTender---
NoSignatureRequiredMessageEnabled">true</Setting>
<Setting name="CreditDebitTender---PinpadRequiredForDebit">true</
Setting>
- NoSignatureRequiredMessageEnabled - This option controls turning off/
on the information message displayed when processing a transaction below a
configured value. See “Credit Card Signatures Based on Tender Amount”.
- PinpadRequiredForDebit - Determines whether or not a pinpad device is
required for tendering with a debit card.

Credit/Debit Table
Xstore Point of Service persists a SHA-1 hash value in its credit/debit table for the
account # used. (This is provided in order to track same card use for Loss Prevention
concerns). This functionality is configured on or off via a config switch in
system.properties.

Miscellaneous Tender Configuration Options

SysConfig.xml
The following configuration options are found in the Tender section of SysConfig.xml:
<Setting name="Tender---BlindCouponTenderId">COUPON</Setting>
<Setting name="Tender---CashSuggestionButtonsEnabled">true</
Setting>
<Setting name="Tender---
CashSuggestionButtonsMinDenominationFactor">1</Setting>
<Setting name="Tender---
DefaultChangeTenderIdIfNoneFound">ISSUE_STORE_CREDIT</Setting>
<Setting name="Tender---ManualEnteredCreditCardImprint">true</
Setting>

7-6 Technical Guide

 Miscellaneous Tender Configuration Options

- ManualEnteredCreditCardImprint - Determines whether or not the

system prompts the associate to imprint the credit card when there is a manually
entered credit card tender in the completed sale transaction.
- BlindCouponTenderId - When using the Coupon tender option in Xstore
Point of Service, the value configured by this option determines the tender ID for
the coupon tender line item that is created. (This value needs to be in the tender
tables in the database and must be properly configured to use it).
- DefaultChangeTenderIdIfNoneFound - Determines the change tender ID
the system will use by default if the system cannot find the valid change tender
based on the sale tenders.
- CashSuggestionButtonsEnabled - Determines whether or not the Quick
Cash Button function is used.
- CashSuggestionButtonsMinDenominationFactor - If Quick Cash Button
functionality is used, the minimum denomination factor used to calculate the
button amounts available.

Quick Cash Buttons

The following configuration options are found in the CurrencyRounding section of

SysConfig.xml and determine the currency rounding method to use for local currency
(RoundingMode), and whether or not the system displays the Cash Total on the
viewport (CashTotalDisplay).
<Setting name="CurrencyRounding---
ApplyTenderRoundingAsDiscount">false</Setting>
<Setting name="CurrencyRounding---CashTotalDisplay">false</
Setting>
<Setting name="CurrencyRounding---RoundingMode">HALF_UP</Setting>
Currency Rounding refers to the process of rounding the cost of a purchase (which is to
be paid for in cash) to the nearest multiple of the smallest denomination of currency.
Rounding became necessary when low denomination coins in a currency were removed
from circulation and are no longer available. Since it may not be possible to make exact
change for a cash purchase, rounding the total bill to the lowest available denomination
of coinage is required. For these tenders, Xstore Point of Service automatically applies
rounding rules that enforce the minimum denomination value that can be accepted or
refunded.
- Rounding Mode Valid values:
* HALF_UP - Round to the nearest neighbor unless equidistant, then round
up.
* HALF_DOWN - Round to the nearest neighbor unless equidistant, then
round down.
* HALF_EVEN - Round to the nearest neighbor unless equidistant, then
round to even neighbor. Example: 2.5 rounds to 2 while 3.5 rounds to 4.
* CEILING - Round toward positive infinity. Note: This is the opposite of
FLOOR and never decreases the calculated value.

Tender Configuration 7-7

Menu Config Configuration

* DOWN - Round to the next digit; closer to zero.

* FLOOR - Round down toward negative infinity. Note: This is the opposite of
CEILING and never increases the calculated value.
* UP - Round to the next digit; away from zero.

Note: The minimum denomination amount is defined in the

database: tnd_tndr_options.min_denomination_amt.

If, for example, the minimum denomination amount is the nickel, enter
the value as 5.0, not .05

- Cash Total Display

Displays the Cash Total.
For example, in Australia, the 5 cent coin is the smallest-valued denomination
currently in circulation. Because of this, all transaction amounts using
Australian currency must be multiples of 5 cents.
A tender with a Minimum Cash Denomination Value of 5 cents ($0.05) results in
the following totals in a sale transaction:
* If the Transaction Total=$122.86, then the Cash Total is rounded down to
$122.85.
* If the Transaction Total=$122.88, then the Cash Total is rounded up to
$122.90.
• The following IRS (Internal Revenue Service) configuration options are found in
SysConfig.xml:
<Setting name="IrsIdentificationNumber">EIN 00-0000000</Setting>
<CashPaymentRequiringIrsReport dtype="BigDecimal">10000.00
</CashPaymentRequiringIrsReport>
<Setting name="CashPaymentRequiringIrsReport">10000.00</Setting>
- IrsIdentificationNumber - Used to identify the merchant to the IRS.
- CashPaymentRequiringIrsReport - Determines the threshold amount that
will trigger the system to display the IRS form used to gather additional
customer information if the amount of cash paid by a customer exceeds this
value.

System.Properties
The following configuration option is found in the system.properties file and
determines the local currency in use.
dtv.location.CurrencyId=USD

Menu Config Configuration

If needed, modify the MenuConfig.xml file to add any new tenders or to remove any
tenders that will not be used. For example, remove unused tenders from the following
sections:
SALE::TENDER_OPTIONS
TENDER::EXCAHNGE_IN

7-8 Technical Guide

 Credit Card Signatures Based on Tender Amount

TENDER::EXCHANGE_OUT
Refer to the following Oracle documentation for additional information:
• For a comprehensive listing of each table in the database, refer to the Xstore Point of
Service Database Dictionary.
• For more information about the files produced by the Xstore Point of Service
application for transmission to host systems and the files accepted for processing
updates to Xstore Point of Service operating tables, refer to the Xstore Point of Service
Host Interface guide.

Credit Card Signatures Based on Tender Amount

Set up the tnd_tndr_user_settings table as follows to only require a signature for
credit cards when the tender amount exceeds a configurable threshold. This feature
allows you to process low-value transactions more quickly. (This option does not affect
debit tender and does not apply to return transactions).
1. Add a record to tnd_tndr_user_settings table for a specific credit card
tender_id and group_id.
2. Set the usage code to SIGNATURE_REQ_FLOOR_LIMIT.

Note: Usage code SIGNATURE_REQ_FLOOR_LIMIT_NEG

determines the threshold amount for returns to credit card (if
supported).

3. Set the tnd_tndr_user_settings.min_accept_amt to whatever value is

required.
When the specified credit card type is used to tender a sale transaction, the customer will
not be prompted for a signature when the tender amount due is less than the amount
specified in the min_accept_amt field in the tnd_tndr_user_settings table.
4. Configure the following option in SysConfig.xml to determine whether or not a
message displays on the PinPad when the customer signature is not required.
<Setting name="CreditDebitTender---
NoSignatureRequiredMessageEnabled">true</Setting>
- true = Displays a message saying that no signature is required.
- false = Does not display the message and complete the operation.

Foreign Cash Currency As Change

Foreign Cash Currency can be provided to a customer as change. When this feature is
enabled, a prompt to either provide change in the Local Cash Currency or to provide
change in the Tendered Foreign Cash Currency is displayed to the cashier. If this
configuration is not enabled, the system does not prompt the cashier and will
automatically provide the local cash currency as change.
To enable the foreign cash currency as change functionality, do the following:
1. Set the tnd_tndr_options.change_allowed_when_foreign flag to true (see
“Tender Options Database Setup”).
2. Verify the security privilege OVERRIDE_FOREIGN_CHANGE_EXCEEDS_FUNDS
exists in sec_privilege.privilege_type. This privilege allows the user to

Tender Configuration 7-9

Foreign Cash Currency As Change

override the halt prompt scenario when foreign change due exceeds Xstore Point of
Service's available funds.

Upgrading From an Earlier Version of Xstore Point of Service

When upgrading from an earlier version of Xstore Point of Service, it is important to
understand that there was a change to the change calculation and database configuration
that may affect transaction processing.

Prior to version 7.0

• tnd_tndr_options.change_tndr_id served two purposes:
- If a specific change tender's cash_change_limit IS NOT exceeded, then that
tender's change_tndr_id also has to be set to LOCAL_CURRENCY to get
local currency back.
- If a specific change tender's cash_change_limit IS exceeded, then
change_tndr_id specifies a "fallback change tender id", as long as it is not set
to LOCAL_CURRENCY (that is, ISSUE_STORE_CREDIT).
• When tnd_tndr_options.cash_change_limit = NULL, it actually means a
limit of 0 (zero).

Version 7.0 and After

• The dual meaning of change_tndr_id (explained above) was removed and is now
only used to specify a "fallback change tender id" for when the
cash_change_limit IS exceeded.
• When the cash_change_limit for a specific tender IS NOT exceeded, the
change_tndr_id is not used at all.
• When tnd_tndr_options.cash_change_limit = NULL, this now means no
limit.

7-10 Technical Guide

 8
Discount Configuration

Overview
Discount configuration requires a few key parameters: discount type code, application
method code, calculation method code, associating discounts to groups, and associating
discounts to transaction types. Once the discounts are set up, the sale associate can apply
these pre-defined discounts during sale transactions.

Note: Deals differ from discounts because deals are applied

automatically when the deal triggers are satisfied in the sale
transaction, with no user input required. Discounts must be applied
manually by the associate.
(For deal setup information, refer to the Xstore Point of Service Deal
Pricing Guide).

The discount setup process uses both database tables and configuration files. In this
chapter, the database table information and the DataLoader Record and fields are listed
for each table and column. The SysConfig.xml discount options are also listed here.
The process required to set up discounts for your stores is provided below, along with
links to each section for more information:
1. Define discount code, discount type code, discount application method code,
calculation method code and other discount details in the dsc_discount table
(“Discount Database Setup”).
2. Associate customer groups to the discount in the dsc_discount_group_mapping
table (“Associate a Customer Group to a Discount”).
3. Associate the discount code to valid transaction types in the
dsc_discount_type_eligibility table (“Associate a Discount to a Transaction
Type”).
4. Associate a manufacturer's coupon to the discount code in the dsc_coupon_xref
table (“Associate Manufacturer's Coupon to a Discount”).
5. Define discount code item exclusions in dsc_discount_item_exclusions and
item inclusions in dsc_discount_item_inclusions (“Define Discount Item
Exclusions and Inclusions”).
6. Define compatible discounts in the dsc_discount_compatibility table
(“Define Compatible Discounts”).
7. Set the discount-related options in the SysConfig.xml configuration file as needed
(“System Config Discount Options”).

Discount Configuration 8-1

Discount Database Setup

Discount Database Setup

Most of the discount details are defined within the dsc_discount table. The discount
code must be unique among all other discount codes. The discount code is alphanumeric
and should not exceed 60 characters. For information about this table and the Dataloader
record used to populate it, see the Xstore Point of Service Database Dictionary and the
Xstore Point of Service Host Interface Guide.

Associate a Customer Group to a Discount

Once a discount has been defined, you can associate it with a specific customer group.
Only group members defined here will be eligible to receive the discount. The
combination of customer group ID and discount code is unique among all other such
combinations defined within the dsc_discount_group_mapping table. The customer
group ID and the discount code are alphanumeric and should not exceed 60 characters.
For information about this table and the Dataloader record used to populate it, see the
Xstore Point of Service Database Dictionary and the Xstore Point of Service Host Interface
Guide.

Note: The customer group id is defined in

com_code_value.category where
category=CUSTOMER_GROUPS.

Associate a Discount to a Transaction Type

Once the discount has been defined, you can associate it with a specific type of
transaction. The discount will only be available for the specific transaction type defined
here. The transaction type to discount code association is defined within the
dsc_discount_type_eligibility table. The combination of a valid transaction
type and a discount code is unique within the table. The transaction type code is
alphanumeric and should not exceed 30 characters. The discount code is alphanumeric
and should not exceed 60 characters. For information about this table and the Dataloader
record used to populate it, see the Xstore Point of Service Database Dictionary and the
Xstore Point of Service Host Interface Guide.

Associate Manufacturer's Coupon to a Discount

Once the discount has been defined, you can associate it with a specific manufacturer's
coupon, or coupons, in the dsc_coupon_xref table. For information about this table
and the Dataloader record used to populate it, see the Xstore Point of Service Database
Dictionary and the Xstore Point of Service Host Interface Guide.

Note: Only serialized coupons are sent to Customer Engagement

Cloud Services for redemption.

Define Discount Item Exclusions and Inclusions

Note: To disallow ALL discounts for a specific item, set
itm_item.disallow_discounts_flag to true.

Once the discount has been defined, you can specify items as invalid for it
(dsc_discount_item_exclusions), or specify items as eligible for it
(dsc_discount_item_inclusions). The combination of item ID and discount code

8-2 Technical Guide

 Define Compatible Discounts

is unique within each of the tables. For information about these tables and the
Dataloader records used to populate them, see the Xstore Point of Service Database
Dictionary and the Xstore Point of Service Host Interface Guide.

Define Compatible Discounts

Once multiple discounts have been defined, you can define which discounts are
compatible with each other and can therefore be applied concurrently.
• If a relationship exists in the dsc_discount_compatibility table for a new
discount (Primary Discount Code) being applied to an existing discount
(Compatible Discount Code), both discounts will be applied.
• If no relationship exists in the dsc_discount_compatibility table for a new
discount being applied, the first discount will be discarded and the new discount
will be applied.
For information about this table and the Dataloader record used to populate it, see the
Xstore Point of Service Database Dictionary and the Xstore Point of Service Host Interface
Guide.

System Config Discount Options

In addition to the database setup for discounts, the following configuration options for
discounts are found in SysConfig.xml.
The following configuration options apply only to line item and group discounts. These
configuration options do not apply to transaction discounts.

Note: Return items are not eligible for transaction discounts.

Discounts in Return Transactions

Set up the following SysConfig.xml configuration options to further classify discounts in
specific return transaction types.
<Setting name="ItemReturn---Discounts---
AllowDiscountsOnBlindReturn">true</Setting>
<Setting name="ItemReturn---Discounts---
AllowDiscountsOnUnverifiedReturn">true</Setting>
<Setting name="ItemReturn---Discounts---
AllowDiscountsOnVerifiedReturn">true</Setting>
<Setting name="ItemReturn---
ProRatedDiscountReturnsDisabled">false</Setting>
- AllowDiscountsOnBlindReturn - Customer does not have a sale receipt.
This configuration applies only to line item and group discounts. This
configuration does not apply to transaction discounts.
- AllowDiscountsOnUnverifiedReturn - Customer has a sale receipt;
however, the transaction cannot be found in the database. This configuration
applies only to line item and group discounts. This configuration does not apply
to transaction discounts.

Discount Configuration 8-3

System Config Discount Options

- AllowDiscountsOnVerifiedReturn - Customer has a sale receipt and it is

found in the database. This configuration applies only to line item and group
discounts. This configuration does not apply to transaction discounts.
- ProRatedDiscountReturnsDisabled - When this setting is enabled, Xstore
Point of Service will turn off the pro-ration of discounts for returns.

Discount Rounding Mode

The discount amount rounding method is used to define the rounding method to use for
discount calculations.
<Setting name="Discounts---RoundingMode">HALF_UP</Setting>
Valid values:
- HALF_UP - Round to the nearest neighbor unless equidistant, then round up.
- HALF_DOWN - Round to the nearest neighbor unless equidistant, then round
down.
- HALF_EVEN - Round to the nearest neighbor unless equidistant, then round to
even neighbor. Example: 2.5 rounds to 2 while 3.5 rounds to 4.
- CEILING - Round toward positive infinity. Note: This is the opposite of FLOOR
and never decreases the calculated value.
- DOWN - Round to the next digit; closer to zero.
- FLOOR - Round down toward negative infinity. Note: This is the opposite of
CEILING and never increases the calculated value.
- UP - Round to the next digit; away from zero.

Line Item Discount Configuration Options

Set up the following SysConfig.xml configuration options to specify line item discount
values.
<Setting name="LineItemDiscount---DiscountThreshold---
Amount">999999.99</Setting>
<Setting name="LineItemDiscount---DiscountThreshold---
Enabled">false</Setting>
<Setting name="LineItemDiscount---DiscountThreshold---
Percent">101</Setting>
<Setting name="LineItemDiscount---LineDiscountPrecision">3</
Setting>
<Setting name="LineItemDiscount---
LineDiscountUseConfiguredScale">false</Setting>
- LineDiscountUseConfiguredScale - Determines whether or not the
system uses LineDiscountPrecision scale (true) instead of the local
currency scale (false) to round the line item discount amount.
- LineDiscountPrecision - If LineDiscountUseConfiguredScale is set
to true, the system uses this scale instead of the local currency scale to round the
line item discount amount.
- DiscountThreshold

8-4 Technical Guide

 Deal Data for Multiple Stores

* Enabled - Determines whether or not the system validates the total

discount amount or percentage against a configured threshold. Note: The
thresholds establish the allowable operators for discounting; beyond these
thresholds, the DISCOUNT_EXCEED_MAX_THRESHOLD privilege is
activated.
* Amount - If Enabled is set to true, the system validates the total line item
discount amount against this threshold.
* Percent - If Enabled is set to true, the system validates the total line
item discount percent against this threshold.

Group Discount Configuration Options

Set up the following SysConfig.xml configuration options to specify group discount
values.
<Setting name="GroupDiscount---ConfirmItemVoid">true</Setting>
<Setting name="GroupDiscount---MinItemsRequired">2</Setting>
- ConfirmItemVoid - Determines whether or not the system prompts for
confirmation if the associate wants to remove an item with a group discount.
The group discount will be removed from other items as well.
- MinItemsRequired - The minimum number of items required in order to
allow application of a group discount.

You Saved Discount Options

Set up the following SysConfig.xml configuration options to specify “you saved”
message options.
<Setting name="YouSavedMessage---
MinYouSavedMessageThresholdAmount">0</Setting>
<Setting name="YouSavedMessage---ShowYouSavedMessage">true</
Setting>
- ShowYouSavedMessage - Determines whether or not the system prints
customer savings information on the sales receipt.
- MinYouSavedMessageThresholdAmount - The minimum amount of
customer savings required for the system to print the customer savings
information on the sales receipt.

Deal Data for Multiple Stores

To store deal data in one database for multiple stores is now supported by Xstore.
The prc_deal_loc table maps a deal ID (deal_id) to a retail location ID (rtl_loc_id). Each
deal_id can be mapped to several rtl_loc_id values if the deal is valid for several retail
locations. Deal data is typically inserted into the Xstore database with the use of
DataLoader. Flat files in particular formats are fed into DataLoader and processed.
When deal data is processed, the DataLoader populates the new prc_deal_loc table with
the deal_id from the flat file and the organization_id and rtl_loc_id from the
system.properties file. DataLoader can process deal data coming from the
following sources:
• Customer Engagement (CE)
• Retail Price Management (RPM)

Discount Configuration 8-5

Deal Data for Multiple Stores

• Omnichannel Cloud Data Service (OCDS)

When Xstore is started, it loads the available deals into memory. The query only selects
deal records for the appropriate retail location id. Deal data can also be refreshed in
memory either manually or automatically throughout the day.
For more information about SysConfig settings to refresh deal data, see the next section.
For more information about the prc_deal_loc table, see the Xstore Suite Database
Dictionary.

SysConfig.xml Settings
The following settings are used to determine if deal data should be automatically
refreshed after a certain time period has passed. If this is set to true, Xstore will check if
data in any deal table has been modified since the last time the data was loaded. If there
are changes, the deal data will be reloaded.
• RefreshPromotions—CheckingForNewCachedPromotions
The default for this value is false. Set to true if automatic refreshes are desired.
• RefreshPromotions—
TimeIntervalForCheckingForNewCachedPromotions
The default is 60 minutes and cannot be less than 10.

8-6 Technical Guide

 9
Commissioned Associate Configuration

Overview
This chapter provides information about the configurations that support the assignment
of sales associates from within a sale transaction. This configuration determines whether
sales commission can be distributed on line items within that sales transaction
(including returns, layaways etc.).

Assigning Commissioned Associates to a Sale Transaction

The Commissioned Associates section exists under the Store element section, within the
RegisterConfig section of the SysConfig.xml file.
The following options are available for configuring commissioned associates in Xstore
Point of Service:
• Whether the user assigns commissioned associates at the start of a sales transaction.
• If commissioned associates are assigned at the start of a sales transaction, whether
the system prompts for a commissioned associate when an item is added in a sale.
• Whether commissioned associate names are displayed with the line items on the
view port for sales and/or returns.
• Whether to assume and default the cashier as the first commissioned associate on a
sale.
• Whether the cashier may be allowed as a commissioned associate.
• The minimum number of commissioned associates allowed.
• The maximum number of commissioned associates allowed.
• Printed receipt options: first name, last name, and separate line for each associate.

SysConfig.xml
<Setting name="CommissionedAssociates---
AllowCashierAsCommissionedAssociate">true</Setting>
<Setting name="CommissionedAssociates---
DefaultCashierAsFirstCommissionedAssociate">true</Setting>
<Setting name="CommissionedAssociates---
DefaultCommissionMethod">CURRENT_CASHIER</Setting>
<Setting name="CommissionedAssociates---
DisplayPerItemOnReturn">false</Setting>

Commissioned Associate Configuration 9-1

Assigning Commissioned Associates to a Sale Transaction

<Setting name="CommissionedAssociates---
DisplayPerItemOnSale">false</Setting>
<Setting name="CommissionedAssociates---
MaxCommissionedAssociatesAllowed">3</Setting>
<Setting name="CommissionedAssociates---
MinCommissionedAssociatesAllowed">1</Setting>
<Setting name="CommissionedAssociates---
PromptForCommissionedAssociates">true</Setting>
<Setting name="CommissionedAssociates---PromptPerItem">false</
Setting>
<Setting name="CommissionedAssociates---PromptWithList">true</
Setting>
<Setting name="CommissionedAssociates---
RcptIncludeFirstName">true</Setting>
<Setting name="CommissionedAssociates---
RcptIncludeLastName">true</Setting>
<Setting name="CommissionedAssociates---
RcptNewLineBetween">true</Setting>
PromptForCommissionedAssociates - This flag determines whether or not the
system prompts the user to assign commissioned associates to the new sale transaction,
or to use the cashier as the only commissioned associate for the new sale transaction,
with no prompting.
- True - Configures the system to automatically prompt for commissioned
associates.
- False - Disables the automatic prompting for commissioned associates.

Note: The Pre-Sale Operation Chain containing the operation for

assignment of commissioned associates ultimately determines whether
the line item includes commissioned associates, regardless of the
prompting for assignment values.

PromptPerItem - When PromptForCommissionedAssociates is true, this flag

determines the prompting method to be used in a sale transaction.
- True - Configures the system to automatically prompt for commissioned
associates each time an item is sold.
- False - Configures the system to automatically prompt for associates to receive
commission once at the beginning of a transaction, and assign those associates to
each sold item by default.
DisplayPerItemOnSale - This flag determines the display method on the View Port
for commissioned sale/send sale/customer account transactions.
- True - Display separate lines for each commissioned associate for each sale/send
sale/customer account line displayed on the View Port.
- False - Do not display commissioned associate lines with each sale/send sale/
customer account line displayed on the View Port.
DisplayPerItemOnReturn - This flag determines the display method on the View
Port for commissioned verified original purchase/return lines.

9-2 Technical Guide

 Assigning Commissioned Associates to a Sale Transaction

- True - Display separate lines for each commissioned associate for each verified
original purchase/return line displayed on the View Port.
- False - Do not display commissioned associate lines with each verified original
purchase/return line displayed on the View Port.
PromptWithList - This configuration determines whether the user is presented with a
list of employee names in a multi-select list or with a focus bar prompt for entry of
commissioned associates’ IDs.
- True - Configures the system to prompt the user with a multi-select list of
employee names.
- False - Configures the system to prompt the user with a focus bar prompt.
DefaultCashierAsFirstCommissionedAssociate - This flag determines whether
or not the system will automatically assign the current system user/cashier as the first
default commissioned associate.
- True - Configures the system to automatically assign the current system user/
cashier as the first default commissioned associate.
- False - Disables the automatic assignment of the current system user/cashier as
the first default commissioned associate.
AllowCashierAsCommissionedAssociate - This flag determines whether or not
the system will allow the assignment of the cashier as a commissioned associate. Notice
that this configuration may conflict with the previous configuration that automatically
associates the cashier as the first commissioned associate. In addition, if the prompting
for commissioned associates is disabled, then the commissioned associate is assumed to
be the cashier and this flag is deemed irrelevant.
- True - Configures the system to allow the cashier as a commissioned associate.
- False - Disables the ability to use the cashier as a commissioned associate.
DefaultCommissionMethod - This value determines the default method used for
assigning commissions.
- CURRENT_CASHIER
- HOUSE_ACCOUNT
Any other values, or no value, will result in no commission being recorded. This
configuration only applies when prompting for commissioned associates is turned off.
PromptForCommissionedAssociates =False.
MinCommissionedAssociatesAllowed - This value determines the minimum
number of commissioned associates that may be assigned to the sales transaction. This
value must be a valid non-zero positive number.
MaxCommissionedAssociatesAllowed - This value determines the maximum
number of commissioned associates that may be assigned to the sales transaction. This
value must be a valid non-zero positive number.

Commissioned Associate Configuration 9-3

Commissioned Associates - Receipt Configuration

Commissioned Associates - Receipt Configuration

The following configuration options apply to the receipt elements for printing
commissioned associate information on the receipt.
RcptIncludeFirstName - This flag determines whether or not the commissioned
associate’s first name is printed on the receipt.
- True - Configures the system to print the commissioned associate’s first name on
the receipt.
- False - Does not print the commissioned associate’s first name on the receipt.
RcptIncludeLastName - This flag determines whether or not the commissioned
associate’s last name is printed on the receipt.
- True - Configures the system to print the commissioned associate’s last name on
the receipt.
- False - Does not print the commissioned associate’s last name on the receipt.
RcptNewLineBetween - This flag determines whether or not a a new line is inserted
between each commissioned associate name printed on the receipt.
- True - Configures the system to insert a new line between each commissioned
associate name printed on the receipt.
- False - Does not insert a new line between each commissioned associate name on
the receipt.
Receipt Examples:
• If <Setting name="CommissionedAssociates---RcptNewLineBetween">true</
Setting>:

• If <Setting name="CommissionedAssociates---RcptNewLineBetween">false</
Setting>:

Database Setup for Commission-Eligible Items

In addition to the configuration options in SysConfig.xml, whether or not an item allows
commissions can be specified in the itm_item table by setting the
disallow_commission_flag to True. For information about this table and the
Dataloader record used to populate it, see the Xstore Point of Service Database Dictionary
and the Xstore Point of Service Host Interface Guide.

9-4 Technical Guide

 10
Employee Configuration & Maintenance

Overview
Employee setup, configuration, and maintenance includes all of the steps necessary for
entering or updating any information about your employees. The amount of employee
information you maintain can be very basic or highly detailed, depending upon your
business needs.
Employee information is used for a number of purposes, such as providing the
information used for timecards, payroll, and reporting. It is also used for assigning
system privileges, work assignments, employee benefits, and employee status.

Note: In addition to the tables and SysConfig.xml values described

here, set up any user-selection code information in the
com_code_value table.

The employee setup, configuration, and maintenance processes use both database tables
and configuration files. In this chapter we will cover the database table information, the
DataLoader record and fields, and the SysConfig.xml employee options.
1. Set up crm_party table entries for the party_id and employee_id. (“Employee
Party Database Setup”)
2. Set up crm_party_locale_information table entries for the party_id. This
record contains the employee’s address information. (“Employee Address Database
Setup”)
3. Set up crm_party_email table entries for the party_id. This record contains the
employee’s email address information. (“Employee E-mail Address Database
Setup”)
4. Set up crm_party_telephone table information for the party_id. This record
contains the employee’s telephone contact information. (“Employee Telephone
Information Database Setup”)
5. Set up employee passwords in hrs_employee_password. (“Employee Password
Database Setup”)
6. Define employee detail: pay status, role code, status code, type code, marital status
code, group code, department code, and other employee-specific information in the
hrs_employee table. (“Employee Detail Database Setup”)
7. Assign each employee to a particular store or stores, providing the ability for him or
her to log on to Xstore Point of Service at the specified location(s) during the given
date range in the hrs_employee_store table. (“Assign the Employee to a Store”)

Employee Configuration & Maintenance 10-1

Employee Party Database Setup

8. Set the employee SysConfig.xml configuration file options as needed. (“System

Config Employee Configuration”)
9. (Optional) Set up the employee change-password challenge questions. (Chapter 12,
“Employee Challenge Questions Setup”)

Employee Party Database Setup

Party records are the basis for both a Customer and an Employee in Xstore Point of
Service. Party information is stored in the crm_party table. For information about this
table and the Dataloader record used to populate it, see the Xstore Point of Service
Database Dictionary and the Xstore Point of Service Host Interface Guide.

Employee E-mail Address Database Setup

The crm_party_email record is the basis for both a Customer and an Employee e-mail
address in Xstore Point of Service. For information about this table and the Dataloader
record used to populate it, see the Xstore Point of Service Database Dictionary and the
Xstore Point of Service Host Interface Guide.

ApplicabilityCondition
Determines if this record will be loaded based on whether or not a field value was
provided.
<Dao name="PartyEmail">
<ApplicabilityCondition
className="dtv.data2.dataloader.applicability.ValueApplicabilityC
ondition">
<Param key="testValue" value="filePosition=31" />
<Param key="applicableValue" value="" />
<Param key="invert" value="true" />
</ApplicabilityCondition>
<Field sysProp="dtv.dataloader.OrganizationId"
name="OrganizationId" />
<Field filePosition="03" name="PartyId" />
<Field literal="1" name="Sequence" />
<Field filePosition="31" name="EmailAddress" />
<Field literal="1" name="Primary" />
<Field literal="Home" name="EmailType" />
<Field filePosition="40" name="Contact" />
</Dao>

Employee Address Database Setup

The crm_party_locale_information table contains the employee’s address
information. For information about this table and the Dataloader record used to
populate it, see the Xstore Point of Service Database Dictionary and the Xstore Point of
Service Host Interface Guide.

10-2 Technical Guide

 Employee Telephone Information Database Setup

Employee Telephone Information Database Setup

The crm_party_telephone table contains the employee’s telephone information. For
information about this table and the Dataloader record used to populate it, see the Xstore
Point of Service Database Dictionary and the Xstore Point of Service Host Interface Guide.

ApplicabilityConditions
Determines if this record will be loaded based on whether or not a field value was
provided.
<Dao name="PartyTelephone">
<ApplicabilityCondition
className="dtv.data2.dataloader.applicability.ValueApplicabilityC
ondition">
<Param key="testValue" value="filePosition=27" />
<Param key="applicableValue" value="" />
<Param key="invert" value="true" />
</ApplicabilityCondition>
<Field sysProp="dtv.dataloader.OrganizationId"
name="OrganizationId" />
<Field filePosition="03" name="PartyId" />
<Field literal="Home" name="TelephoneType" />
<Field filePosition="27" name="TelephoneNumber" />
</Dao>

<Dao name="PartyTelephone">
<ApplicabilityCondition
className="dtv.data2.dataloader.applicability.ValueApplicabilityC
ondition">
<Param key="testValue" value="filePosition=28" />
<Param key="applicableValue" value="" />
<Param key="invert" value="true" />
</ApplicabilityCondition>
<Field sysProp="dtv.dataloader.OrganizationId"
name="OrganizationId" />
<Field filePosition="03" name="PartyId" />
<Field literal="Work" name="TelephoneType" />
<Field filePosition="28" name="TelephoneNumber" />
</Dao>

<Dao name="PartyTelephone">

Employee Configuration & Maintenance 10-3

Employee Telephone Information Database Setup

<ApplicabilityCondition
className="dtv.data2.dataloader.applicability.ValueApplicabilityC
ondition">
<Param key="testValue" value="filePosition=29" />
<Param key="applicableValue" value="" />
<Param key="invert" value="true" />
</ApplicabilityCondition>
<Field sysProp="dtv.dataloader.OrganizationId"
name="OrganizationId" />
<Field filePosition="03" name="PartyId" />
<Field literal="Mobile" name="TelephoneType" />
<Field filePosition="29" name="TelephoneNumber" />
</Dao>

<Dao name="PartyTelephone">
<ApplicabilityCondition
className="dtv.data2.dataloader.applicability.ValueApplicabilityC
ondition">
<Param key="testValue" value="filePosition=30" />
<Param key="applicableValue" value="" />
<Param key="invert" value="true" />
</ApplicabilityCondition>
<Field sysProp="dtv.dataloader.OrganizationId"
name="OrganizationId" />
<Field filePosition="03" name="PartyId" />
<Field literal="WorkFax" name="TelephoneType" />
<Field filePosition="30" name="TelephoneNumber" />
</Dao>

10-4 Technical Guide

 Employee Password Database Setup

Employee Password Database Setup

The hrs_employee_password table contains the employee’s password information.
Xstore Point of Service is able to detect which hashing algorithm was used for a given
record, so it is possible for a mix of algorithms to be stored in the same database. For
information about this table and the Dataloader record used to populate it, see the Xstore
Point of Service Database Dictionary and the Xstore Point of Service Host Interface Guide.

Employee Detail Database Setup

Most of the employee setup and maintenance details are stored within the
hrs_employee table. The employee information you choose to maintain can be very
basic, or highly detailed, depending on the requirements of your organization. For
information about this table and the Dataloader record used to populate it, see the Xstore
Point of Service Database Dictionary and the Xstore Point of Service Host Interface Guide.

Assign the Employee to a Store

Once the employee information has been set up, you must assign the employee to a
store. Assigning an employee to a store gives an employee the ability to log on to the
Xstore Point of Service system in the designated store during the given date range.
Without a valid employee store record, an employee will not be permitted to log on to
Xstore Point of Service. For information about this table and the Dataloader record used
to populate it, see the Xstore Point of Service Database Dictionary and the Xstore Point of
Service Host Interface Guide.

System Config Employee Configuration

In addition to the database setup for employee information, the following configuration
options for employee functions are found in SysConfig.xml.

Employee ID Number
Set up the following SysConfig.xml configuration option to specify whether or not the
system automatically generates an employee ID when creating a new employee record.
<Setting name="AutoGenerateEmployeeId">true</Setting>
- When set to True, the system automatically generates an employee ID when
creating a new employee record.
- When set to False, the system prompts the associate to enter the employee ID
when creating a new employee record.

Employee List Display

Set up the following SysConfig.xml configuration option to specify whether or not the
system displays the employee search result list even when only one employee is found.
<Setting name="ShowEmployeeListIfOne">true</Setting>
- When set to True, the system displays the employee search result list even when
only one employee is found.
- When set to False, the system only displays the employee search result list when
more than one employee is found.

Employee Configuration & Maintenance 10-5

System Config Employee Configuration

Default Employee Group

Note: Use caution before changing this configuration. The code and
various configurations are expecting at least this level of security to be
present on the employee record.

The following SysConfig.xml configuration option specifies the default employee group.
The EVERYONE group is included by default, and the Primary Group is set to the group
configured here.
<Setting name="DefaultEmployeeGroup">EVERYONE</Setting>

Default Customer Group for Employees

Set up the following SysConfig.xml configuration option to specify whether or not the
system always adds the DEFAULT customer group for employees.
<Setting name="IncludeEmployeeInDefaultGroup">false</Setting>
- When set to True, the employee is added to the DEFAULT customer group.
- When set to False, the employee is not added to the DEFAULT customer group.

Employee Search Location

Set up the following SysConfig.xml configuration option to specify whether or not the
system only performs an employee search for the current store.
<Setting name="EmployeeSearchCurrentLocationOnly">false</Setting>
- When set to True, only search for the employee in the current store.
- When set to False, search for the employee in all stores.

Employee Search Criteria

Set up the following SysConfig.xml configuration option to specify whether or not the
system requires that at least one search criterion is entered in order to perform an
employee search.
<Setting name="CriteriaRequiredForEmployeeSearch">true</Setting>
- When set to True, at least one search criterion required to initiate employee
search.
- When set to False, an employee search can be initiated with no criteria specified.

Employee ID Length
Set up the following SysConfig.xml configuration option to define the minimum and
maximum employee id lengths.

Minimum Length
<Setting name="MinimumEmployeeIdLength">5</Setting>

Maximum Length
<Setting name="MaximumEmployeeIdLength">20</Setting>

10-6 Technical Guide

 System Config Employee Configuration

Employee Self-Sale
Set up the following SysConfig.xml configuration option to specify whether or not the
system allows employees to ring retail transactions for themselves.
<Setting name="EmployeeSale---AllowSelfSale">false</Setting>
- When set to True, employees can ring retail transactions for themselves.
- When set to False, employees cannot ring retail transactions for themselves.

Employee Login Security

See “User Login and Password Security” for the SysConfig.xml configuration options to
specify employee login security options.

Employee House Account ID

Set up the following SysConfig.xml configuration option to specify an ID to be used for
the “house account” value. This value is often used in conjunction with employee
commissions on blind return transactions.
<Setting name="ItemReturn---HouseAccountEmployeeId">0</Setting>

Employee Security Groups

See Chapter 12, “Security Configuration” for more information about setting up the
security groups for employees.

Employee Challenge Questions Setup

Set up password challenge questions for employees when they use the “Forgot
Password?” functionality in Xstore Point of Service. This optional feature provides
employees with the ability to reset their forgotten passwords without manager
interaction.
See “Employee Challenge Questions Setup” for more information.

Employee Configuration & Maintenance 10-7

System Config Employee Configuration

10-8 Technical Guide

 11
Payroll, Timecard & Clock In/Out
Configuration

Overview
The payroll and timecard setup process uses both database tables and configuration
files. In this chapter, the database table information and the DataLoader Record and
fields are listed for each table and column. The SysConfig.xml and
PayrollOvertimeConfig.xml payroll and timecard options are also listed here.
In addition to setting up payroll and timecards for your stores, you can also set up clock-
in and clock-out restrictions for your employees to enforce minimum meal break
durations. This configuration is done in the hrs_work_codes table. The process required
to set up payroll and timecards for your stores, and a link to each section for more
information, is provided below.
1. Define the payroll category and the timecard work codes in the hrs_work_codes
table (“Payroll and Timecard Work Code Database Setup”).
2. Set up the payroll category code details in the thr_payroll_category table
(“Payroll Category Database Setup”).
3. To have the system calculate overtime hours in Payroll, configure the payroll
overtime rule in SysConfig.xml file using the <OvertimeRuleType> tag. The
overtime rules are defined in PayrollOvertimeConfig.xml and are set in
SysConfig.xml (“Payroll Overtime Rule Configuration in System Config”).
4. Set up other payroll and timecard configuration options in the SysConfig.xml file as
needed (“Payroll Options in System Config”) and (“Timecard Options in System
Config”).
5. Set up clock-in and clock-out restrictions for your employees to enforce minimum
meal break durations as needed (“Clock-in and Clock-out Restrictions Setup”).

Payroll, Timecard & Clock In/Out Configuration 11-1

Payroll and Timecard Work Code Database Setup

Payroll and Timecard Work Code Database Setup

Define the work codes and their descriptions that an employee may select when clocking
in to work. Each work code is associated with a privilege that determines if the work
code can be selected by the employee and is associated with a payroll category. The
hrs_work_codes.selling_flag column is used to designate whether a work code
is counted toward the number of hours spent selling merchandise rather than in non-
sales activities. For information about the hrs_work_codes table and the Dataloader
record used to populate it, see the Xstore Point of Service Database Dictionary and the
Xstore Point of Service Host Interface Guide.

Payroll Category Database Setup

Payroll categories can be used to group working and non-working hours together within
Payroll Maintenance. Non-working categories can be customized to match organization
time-off and payroll reporting requirements (i.e. Jury Duty, Vacation, PTO).
Payroll categories are configured through the thr_payroll_category table. For
information about this table and the Dataloader record used to populate it, see the Xstore
Point of Service Database Dictionary and the Xstore Point of Service Host Interface Guide.

Note: The payroll category order displayed in payroll maintenance is

based on the sort_order value in the thr_payroll_category table.
It is best to use a lower sort order for REGULAR than for all overtime
pay categories.

Payroll Overtime Rule Configuration in System Config

To calculate overtime hours in Payroll, the overtime rules are defined in
PayrollOvertimeConfig.xml and are set in SysConfig.xml. There are many
overtime rules to select from and they are all configured in
PayrollOvertimeConfig.xml. The most commonly used overtime rule is
WEEKLYOVER40. See PayrollOvertimeConfig.xml for the complete listing of
overtime rules.

Note: In the PayrollOvertimeConfig.xml configuration file, each

overtime rule contains the payroll category that this overtime hours
belongs to. Any values configured here must exist in the
thr_payroll_category table.

Overtime Rule Type

Overtime rules are defined in PayrollOvertimeConfig.xml and are set in
SysConfig.xml.
<Setting name="Location---OvertimeRuleType">WEEKLYOVER40</
Setting>

Rule Examples
- WEEKLYOVER40 - If associates work more than 40 hours in one week, they will
get time and one half for every hour over 40 (Base Default Value).
- DAILYOVER8 - If associates work more than 8 hours in one day, they will get
time and one half for every hour over 8.

11-2 Technical Guide

 Payroll Overtime Rule Configuration in System Config

- Multiple rule sets can be used together. For example, in the base configuration,
California uses this capability:

PayrollOvertimeConfig.xml, multiple rule set example

<PayrollOvertimeRuleSet name="CALIFORNIA">
<PayrollOvertimeRuleSetReference
dtype="String">WEEKLYOVER40</PayrollOvertimeRuleSetReference>
<PayrollOvertimeRuleSetReference
dtype="String">DAILY_OVER8_LESSTHAN12</
PayrollOvertimeRuleSetReference>
<PayrollOvertimeRuleSetReference
dtype="String">DAILY_OVER12_DT</PayrollOvertimeRuleSetReference>
<PayrollOvertimeRuleSetReference
dtype="String">7TH_DAY_OF_WEEK_OT</
PayrollOvertimeRuleSetReference>
<PayrollOvertimeRuleSetReference
dtype="String">7TH_DAY_OF_WEEK_OVER8</
PayrollOvertimeRuleSetReference>
</PayrollOvertimeRuleSet>

PayrollOvertimeConfig.xml Excerpt
<PayrollOvertimeRuleSet name="WEEKLYOVER40">
<PayrollOvertimeRule>
<PayrollCategory dtype="String">OT</PayrollCategory>
<Sequence dtype="Integer">99</Sequence>
<OvertimeRate dtype="BigDecimal">1.5</OvertimeRate>
<OTType dtype="String">WEEKLY</OTType>
<HoursOver dtype="BigDecimal">40</HoursOver>
</PayrollOvertimeRule>
</PayrollOvertimeRuleSet>
<PayrollOvertimeRuleSet name="DAILYOVER8">
<PayrollOvertimeRuleSetReference
dtype="String">WEEKLYOVER40</PayrollOvertimeRuleSetReference>
<PayrollOvertimeRule>
<PayrollCategory dtype="String">OT</PayrollCategory>
<Sequence dtype="Integer">90</Sequence>
<OvertimeRate dtype="BigDecimal">1.5</OvertimeRate>
<OTType dtype="String">DAILY</OTType>
<HoursOver dtype="BigDecimal">8</HoursOver>
</PayrollOvertimeRule>
</PayrollOvertimeRuleSet>
<PayrollOvertimeRuleSet name="DAILY_OVER8_LESSTHAN12">

Payroll, Timecard & Clock In/Out Configuration 11-3

Payroll Options in System Config

<PayrollOvertimeRule>
<PayrollCategory dtype="String">OT</PayrollCategory>
<Sequence dtype="Integer">85</Sequence>
<OvertimeRate dtype="BigDecimal">1.5</OvertimeRate>
<OTType dtype="String">DAILY</OTType>
<HoursOver dtype="BigDecimal">8</HoursOver>
<HoursUnder dtype="BigDecimal">12</HoursUnder>
</PayrollOvertimeRule>
</PayrollOvertimeRuleSet>

Payroll Options in System Config

In addition to the overtime rule, the following configuration options for payroll are also
found in SysConfig.xml.

Process Payroll at Store Close

Set up the following SysConfig.xml configuration option to specify whether or not the
system attempts to process payroll at store close.
- <Setting name="OpenClose---ProcessPayroll">false</
Setting>When set to true, the system will process payroll at store close.
- When set to false, the system will not attempt to process payroll at store close.

Payroll Options
Set up the following SysConfig.xml configuration options to further classify the way
payroll functions in your organization.
<Setting name="Payroll---AllowFuturePayrollEntry">true</Setting>
<Setting name="Payroll---AllowPostPayrollPerEmployee">true</
Setting>
<Setting name="Payroll---AllowRepostingPayroll">true</Setting>
<Setting name="Payroll---AssocAdvanceAuthNumber">false</Setting>
<Setting name="Payroll---AssocAdvanceRepaymentAmount">false</
Setting>
<Setting name="Payroll---BasicCalendarPayrollWeekendingDay">7</
Setting>
<Setting name="Payroll---
IsRegularPayrollHoursFromTimeCard">true</Setting>
<Setting name="Payroll---MaxAssociateAdvanceAmount">999.99</
Setting>
<Setting name="Payroll---MaxDailyTotalPayrollHours">24.0</
Setting>
<Setting name="Payroll---PayrollCalendar---
DisplayNumberOfPreviousWeek">10</Setting>

11-4 Technical Guide

 Payroll Options in System Config

<Setting name="Payroll---PayrollHoursRoundingMinutes">15</
Setting>
<Setting name="Payroll---PostPayroll---
AllowAutoPostWithError">true</Setting>
<Setting name="Payroll---PostPayroll---
DisplayPayrollNotYetPostMsgAtLoginIfPassPostDay">true</Setting>
<Setting name="Payroll---PostPayroll---
EnforcePostPayrollDateTime">false</Setting>
<Setting name="Payroll---PostPayroll---
OnlyWriteHourlyPayStatusEmpInPayrollLog">true</Setting>
<Setting name="Payroll---PostPayroll---PayrollPostDay">1</
Setting>
<Setting name="Payroll---PostPayroll---PayrollPostTime">12:00</
Setting>
<Setting name="Payroll---ReviewPayrollRequired">true</Setting>
• PayrollHoursRoundingMinutes - The system rounds payroll hours to the
nearest number of minutes specified here.
- 15: Minutes on a timesheet are rounded to the nearest 15-minute increment
- 30: Minutes on a timesheet are rounded to the nearest 30-minute increment
- 60: Minutes on a timesheet are rounded to the nearest hour
- NONE: Minutes on a timesheet are left as they are and not rounded at all
• PostPayroll - The system uses the payroll posting options specified here.
- EnforcePostPayrollDateTime - Determines whether or not the system
enforces the date and time to post payroll.
* When true, the date and time is enforced.
* When false, payroll posting date and time is not enforced.
- PayrollPostDay - If ProcessPayroll is set to True and payroll has not yet
been posted on this day of the week, the system automatically posts the payroll
at store close.
* 1= Sunday
* 2= Monday
* 3= Tuesday
* 4= Wednesday
* 5= Thursday
* 6= Friday
* 7= Saturday
- PayrollPostTime - If EnforcePostPayrollDateTime is set to True, the
system only allows posting payroll at this time. (format is hh:mm)
- DisplayPayrollNotYetPostMsgAtLoginIfPassPostDay - Determines
whether or not the system notifies the associate at application login when
payroll has not been posted and it’s past the payroll post day.

Payroll, Timecard & Clock In/Out Configuration 11-5

Payroll Options in System Config

* When true, the system displays a notification message to the associate.

* When false, a notification message is not displayed.
- OnlyWriteHourlyPayStatusEmpInPayrollLog - Determines whether or
not the system only writes payroll data to payroll.xml for hourly pay
employees.
* When true, the system only writes payroll data to payroll.xml for hourly
pay employees.
* When false, the system writes payroll data to payroll.xml for all
employees.
- AllowAutoPostWithError - Determines whether or not the system continues
to automatically post payroll if any payroll exception was found.
* When true, the system automatically posts payroll even if a payroll
exception is found.
* When false, the system does not automatically post payroll if a payroll
exception is found.
• PayrollCalendar
- DisplayNumberOfPreviousWeek - At the payroll maintenance week
selection list, the system displays this number of previous weeks for payroll
maintenance activities.
- DisplayNumberOfPreviousWeekinReport - At the payroll report week
search drop-down option, the system populates this number of previous weeks
for reviewing the payroll report.
• AllowRepostingPayroll - Determines whether or not the system allows
reposting a previously-posted payroll week.
- When true, the system allows reposting a previously-posted payroll week.
- When false, the system does not allow a previously-posted payroll week to be
reposted.
• MaxDailyTotalPayrollHours - The system marks the payroll for exception if
the total daily payroll hours exceed the number of hours specified here.
• ReviewPayrollRequired - Determines whether or not the system requires the
store manager to review all payroll records before the system allows payroll to be
posted.
- When true, payroll review is required before posting.
- When false, payroll review is not required before posting.
• AllowPostPayrollPerEmployee - Determines whether or not the system
enables the functionality to allow posting payroll for an individual employee rather
than all employees at once.
- When true, payroll can be posted for an individual employee.
- When false, payroll cannot be posted for an individual employee.
• BasicCalendarPayrollWeekendingDay - Defines the payroll week ending day
when the system is configured to use the Basic Calendar. The number entered
determines the day of the week on which payroll will be posted.
- 1= Sunday
- 2= Monday

11-6 Technical Guide

 Timecard Options in System Config

- 3= Tuesday
- 4= Wednesday
- 5= Thursday
- 6= Friday
- 7= Saturday
• MaxAssociateAdvanceAmount - The maximum amount of money an associate
can ask for as a pay advance.
• IsRegularPayrollHoursFromTimeCard - When set to TRUE, the system
automatically populates payroll regular hours with hours from the timecard and
does not allow the associate to edit the hours. When set to FALSE, the system allows
the associate to enter the payroll regular hours.
• AssocAdvanceAuthNumber - Determines whether or not the system prompts the
associate to enter an authorization number for an employee pay advance.
- When true, the system prompts the associate to enter an authorization number
for an employee pay advance.
- When false, the system does not prompt for an authorization number for an
employee pay advance.
• AllowFuturePayrollEntry - Determines whether or not the system allows
editing payroll for a future date.
- When true, the system will allow future payroll entries to be edited.
- When false, the system will not allow future payroll entries to be edited.
• AssocAdvanceRepaymentAmount - Determines whether or not the system
prompts for a “per paycheck” repayment amount for an employee pay advance.
- When true, the system prompts for a “per paycheck” repayment amount for an
employee pay advance.
- When false, the system does not prompt for a “per paycheck” repayment
amount for an employee pay advance.

Timecard Options in System Config

The following configuration options for timecards are found in SysConfig.xml.

Timecard Options
Set up the following SysConfig.xml configuration options to further classify the way
timecards are used in your organization.
<Setting name="Timecard---AllowFutureTimecardEntry">true</
Setting>
<Setting name="Timecard---
DefaultActiveEmployeeListSortType">LAST_NAME</Setting>
<Setting name="Timecard---DisplayDeletedTimecardEntry">true</
Setting>
<Setting name="Timecard---Exception---
TimecardHourGreaterThanHours">10</Setting>

Payroll, Timecard & Clock In/Out Configuration 11-7

Timecard Options in System Config

<Setting name="Timecard---Exception---
TimecardHourLessThanHours">1</Setting>
<Setting name="Timecard---PrintAcceptanceForm">true</Setting>
• DefaultActiveEmployeeListSortType - The default timecard maintenance
employee list sort type.
- LAST_NAME: The system will sort the active employee list by employee last
name.
- DEPARTMENT_ID: The system will sort the active employee list by department
ID.
- EMPLOYEE_ID: The system will sort the active employee list by employee ID.
• Exception - Timecard hour exception threshold options:
- TimecardHourGreaterThanHours - This number is used to set the
maximum number of hours allowed in a timecard entry. The system marks a
timecard entry for exception if the hours exceed this threshold. If there is no
limit to the number of hours permitted in a timecard entry, enter a number that
is large enough (such as 999999) to effectively assign no limit.
- TimecardHourLessThanHours - This number is used to set the minimum
number of hours permitted in a timecard entry. The system marks a timecard
entry for exception if the hour is lower than this threshold.
• PrintAcceptanceForm - Determines whether or not the system prints an
acceptance form when a timecard entry is modified, added, or deleted in timecard
maintenance.
- When true, the system will print the acceptance form when saving a timecard
entry.
- When false, the system does not print the acceptance form when saving a
timecard entry.
• DisplayDeletedTimecardEntry - Determines whether or not the system
displays deleted timecard entries on the timecard maintenance screen.
- When true, the system displays deleted timecard entries on the timecard
maintenance screen.
- When false, the system does not display deleted timecard entries on the
timecard maintenance screen.
• AllowFutureTimecardEntry - Determines whether or not the system allows
timecard entries to be added to future dates in timecard maintenance.
- When true, the system allows timecard entries to be added to future dates in
timecard maintenance.
- When false, the system does not allow timecard entries to be added to future
dates in timecard maintenance.

Timeclock Options
Set up the following SysConfig.xml configuration options to specify clock-in rules.
<Setting name="TimeClock---
ClockInNotRequiredOnCreateEmpFlag">false</Setting>
<Setting name="TimeClock---
ClockInRequiredForAuthorizationFlag">false</Setting>

11-8 Technical Guide

 Clock-in and Clock-out Restrictions Setup

• ClockInNotRequiredOnCreateEmpFlag - Determines whether or not newly

created employees must clock in to access the system.
- When true, newly created employees are not required to clock in to access the
system.
- When false, newly created employees must clock in to access the system.
• ClockInRequiredForAuthorizationFlag - Determines whether or not
employees must be clocked in to access the system, except for those employees who
were created with ClockInNotRequiredOnCreateEmpFlag set to True and those
employees with hrs_employee.clock_in_not_req_flag set to True.
- When true, the system requires employees to clock in before accessing the
system.
- When false, the system will not require employees to clock in to access the
system.

Clock-in and Clock-out Restrictions Setup

In addition to setting up payroll and timecards for your stores, you can also set up clock-
in and clock-out restrictions for your employees to enforce minimum meal break
durations. These restrictions are set up in the hrs_work_codes table;
min_clock_in_duration and min_clock_out_duration.
For example, you can set up the following restriction types:
• You must be clocked in for assignment X for at least Y minutes.
In this scenario, hrs_work_codes.min_clock_in_duration could be attached
to a “Lunch Break” work code to effectively say “Once you’ve clocked ‘in’ for your
lunch break, you cannot clock back ‘out’ for at least 30 minutes.”
• You must be clocked out for at least Y minutes before clocking in for assignment X.
In this scenario, hrs_work_codes.min_clock_out_duration could be
attached to a “Sales” work code to effectively say “Once you’ve clocked out during
your shift, you cannot clock back in to start selling again for at least 30 minutes.”
Both restrictions were created to enforce minimum meal break durations. The
min_clock_in_duration restriction type can be used to configure “lunch” as its own
work code (e.g. Meal Break work code). The min_clock_out_duration restriction
type can be used to treat an intra-day clock-out as a lunch break (e.g. there may only be a
single work code representing “I’m on the clock”).
More generally, though, you can assign restrictions for whatever reasons you want. The
settings also do not impact each other in any way because one is enforced only when
you’re trying to clock in for that work code, and the other is only enforced when you’re
trying to clock out from that work code.

Security Privilege Setup

To use clock-in and clock-out restrictions, you must also populate
sec_privilege.privilege_type with the security setting:
TIME_CLOCK_DURATION. This security setting governs the ability to override a
duration-based rejection of a clock-in/out.
Because Xstore Point of Service does not recognize an authenticated user during the
clock-in/out process (identifying who is clocking in/out is treated differently than
logging in to the system), this setting should always be set to "OVERRIDABLE".

Payroll, Timecard & Clock In/Out Configuration 11-9

Clock-in and Clock-out Restrictions Setup

Any validation failures will always produce a user/password security override prompt,
even when the person clocking in/out has sufficient security to perform the operation
based on this privilege. This is odd behavior compared to other security privileges
which allow the user to proceed uninterrupted when they have sufficient security rights,
but it is consistent with Xstore Point of Service's "special" handling of clock-ins.

Setup Example: min_clock_in_duration

This configuration prevents employees from clocking out from certain work codes until
they have been clocked in for at least a minimum duration.
EXAMPLE: You must be clocked in for your lunch break assignment for at least 30 minutes.
When you set hrs_work_codes.min_clock_in_duration to 30 minutes for the
LUNCH_BREAK work code, then the associate will be notified when it is too early to
clock out from the break. This restriction type can be used to configure “lunch” as its
own work code (e.g. a LUNCH_BREAK work code).
6. The associate selects the Clock In/Out button from the main menu, enters his/her ID
and password when prompted, and chooses the meal break option from the Work
Codes list.
The system automatically clocks the associate out from the current work code and
clocks the associate in to the Meal Break work code.
7. If the associate tries to clock out (or to clock in with a different work code) from the
meal break before 30 minutes have elapsed, then a message is displayed.

Setup Example: min_clock_out_duration

This configuration prevents employees from clocking in for certain work codes until
they have been clocked out for at least a minimum duration.
EXAMPLE: You must be clocked out for at least 30 minutes before clocking in for your Sales
assignment.
When you set hrs_work_codes.min_clock_out_duration to 30 minutes for the
SALES, INVENTORY, CASHIER, etc. work codes, then the associate will be notified
when it is too early to clock back in to any of these work codes.
1. At some point after the associate’s initial clock-in for the day, he/she selects the Clock
In/Out button from the main menu, enters his/her ID and password when
prompted, and chooses to clock out.
The associate is clocked out from the current work code.
2. If the associate tries to clock back in to the system before 30 minutes have elapsed,
then a message is displayed.

11-10 Technical Guide

 12
Security Configuration

Overview
Application security is a feature that restricts user access to only those parts of the
system that are needed to perform the requirements of a role. Because Xstore Point of
Service security is role-based, user roles, membership groups, and privileges must be
defined so that security may be applied correctly.
Additional security is maintained through passwords and challenge questions. See
“User Login and Password Security”.

Roles, Privileges, and Membership Groups

Roles
A role is a collection of related or similar job requirements that may be associated with
one or more users. A role may be defined very broadly or narrowly, depending on
security requirements. An example of a broadly-based role is “cashier” because of a
cashier’s need to access many portions of the system, especially in the Register
application.
A more narrowly defined role is “shipper-receiver”. In that role, the user may need
access to only certain parts of the inventory application in the Back Office. An individual
user may perform multiple roles and, therefore, be assigned to more than one defined
role.
Xstore Point of Service uses membership groups that define specific security
configurations and can encompass the descriptively named roles. Some of the security-
related tables provide columns that may be used to record role names for descriptive
purposes, but are not actually used to implement security.

Privileges
A privilege is the ability to do something in the application. For example, a privilege
may be assigned to a specific portion of the application such as a button that performs a
function, a menu that provides access to related features or reports, or to a group of
fields on a form for the purpose of viewing or entering data.
A privilege may be assigned to a membership group, and thus, to an individual user
who is a member of that group. Security may be assigned by configuring an
AccessCheck in the file MenuConfig.xml.

Security Configuration 12-1

Roles, Privileges, and Membership Groups

Membership Groups
A membership group consists of one or more group IDs that are defined in the
group_id column of the sec_groups table. Examples of a group ID are MANAGER
and CASHIER. You may define as many group IDs as your security requirements
dictate, but as a general rule, do not create groups that have identical privileges assigned
to them.
Each of the group IDs is assigned to a different “bitmap position” in a binary number
that is generated when a user is assigned to a membership group. Bitmap positions are
numbered starting with “1” in the right-most position (low order bit). The next position
to the left is “2”, then “3” and so on. Users are assigned to groups in Xstore Point of
Service’s Employee Maintenance module (Back Office application).

Figure 12-1: Sample sec_groups Table

The binary number is converted to a Base64 value because it can be represented using
ASCII (all printable) characters for the purpose of displaying the group membership.
Base64 characters include both upper case and lower case letters (52 characters), the
numbers zero through nine (0-9), and the characters “+” and “/”. As a result, Base64
includes a total of 64 characters.
If a user belongs to a membership group that includes only one group ID, then only the
bitmap position associated with that group ID is “turned on”, or has the value “1”. All of
the other bitmap positions in the group ID are “off”, that is, they all have the value of
“0”.
The following table represents the bitmap configuration for a membership group that
includes only a single group ID (using the group IDs in the sample sec_groups table,
Figure 12-1 above).

Group_id Bitmap_position Resulting binary

TRAINEE 2 0000010

KEYHOLDER 4 0001000

EVERYONE 1 0000001

CASHIER 3 0000100

MANAGER 5 0010000

Group Memberships With Multiple Group IDs

A user’s group membership consists of all of the group IDs that are assigned to the
person. If a user is assigned to more than just one group ID, then the resulting binary
value will have all of those bitmap positions “turned on”. For example, a user who is in
the groups EVERYONE and CASHIER would produce a membership group whose
binary value is “0000101” (bitmap positions “1” and “3” are on). The value of the binary
that represents a membership group depends upon the combination of group IDs to
which a user belongs.

12-2 Technical Guide

 Roles, Privileges, and Membership Groups

The EVERYONE Group

There is a special group ID in the sec_groups table that must be named “EVERYONE”.
The purpose of this group is to define a group that includes privileges that may be
accessed without logging in to Xstore Point of Service. For example, you may wish to
allow users to perform item lookups or to view a work schedule without having to log
in.

Note: The EVERYONE group must be assigned to bitmap position “1”.

To prevent an employee from accessing the system, remove the person
from all groups, including the EVERYONE group.

Technical Aspects of Group Memberships

There are two aspects worth noting about group memberships:
• The first one pertains to the speed with which a check for privileges can be
performed.
• The second point is about equivalent values that can be generated for membership
settings.

Speed
Because the binary value that represents a group ID is based on bit positions, extremely
fast integer math is used to check an employee’s privileges. The check uses a logical
AND comparison between the employee’s group membership and the group
membership associated with the privilege being checked. If the result of the comparison
is not zero, the employee is in a group that has the privilege.

Equivalent Values
Some different group_membership settings can be decoded from their Base64 value to
equivalent binary values. This is a result of the way that Base64 encoding works.
For example, the group membership settings BQ== and BQAAAAAAAAA= are different.
But BQ== decodes to 00000101 and the group membership BQAAAAAAAAA= decodes to
0000000000000000000000000000000000000000000000000000000000000101.
The leading zeros are ignored in both group memberships which produce equivalent
binary values.
When you edit a user’s group membership in Xstore Point of Service’s Employee
Maintenance module, the longer binary value with leading zeros will be generated
because Xstore Point of Service uses at least a 64-bit number for all comparisons.

Security Configuration 12-3

Employee Maintenance Security - Group Rank

Employee Maintenance Security - Group Rank

You can define a group rank for a given security group/role in the group_rank column
of the sec_groups table. The Employee Maintenance function looks to this value when
determining how to restrict the “create employee” and “edit employee” functions.
Security controls include the following:

Enforced in Xstore Point of Service

Security Control Employee Maintenance

An employee is able to view—but unable to This restriction is imposed by disabling the

edit—an employee with a higher group rank. Edit and Change Password functions.

An employee is unable to assign themselves to This restriction is enforced by filtering out

a higher-ranked security group. ineligible groups from the “primary group”
drop-down and the “security groups” multi-
select list.

An employee is unable to create a new This restriction is enforced by filtering out

employee assigned to a higher-ranked security ineligible groups from the “primary group”
group. drop-down and the “security groups” multi-
select list.

A global configuration flag (SysConfig.xml element

“AllowEqualSecurityRankAccess”) determines whether “higher-ranked” in this
context means “greater than” or “greater than or equal”.

<Setting name="AllowEqualSecurityRankAccess">true</Setting>
- When set to true, employees can add/edit employees within their own rank and
lower.
- When set to false, employees can only add/edit employees with a lower group
rank.
For example, this flag determines whether or not an assistant manager can edit other
assistant managers (=true), or only those of ranks lower than assistant manager (=false).

Note: Certain configuration combinations will not be supported. The

“EVERYONE” group, for example, is a hard-coded member of the
security groups set and is intended to always represent the greatest
degree of access. Assigning it a higher rank than any other group in
sec_groups is not a valid configuration. Similarly, arrangements that
result in an inability for an employee to assign any groups (e.g.
allowing lowest-ranked trainees to create/edit employees while setting
“AllowEqualSecurityRankAccess” to “false”) may result in arbitrary
behavior and is not supported.

12-4 Technical Guide

 Employee Maintenance Security - Group Rank

Sample Group Membership Settings

The table below shows the combination of group membership settings that may result
from all combinations of four different roles. The values in the table assume that the four
roles have the following assigned bitmap positions:
Role 1 Bitmap Position 1 Role 3 Bitmap Position 3
Role 2 Bitmap Position 2 Role 4 Bitmap Position 4

Roles Assigned Binary Value Group Membership (Base64)

None 0000 AA==

1 0001 AQ==

2 0010 Ag==

1,2 0011 Aw==

3 0100 BA==

1,3 0101 BQ==

2,3 0110 Bg==

1,2,3 0111 Bw==

4 1000 CA==

1,4 1001 CQ==

2,4 1010 Cg==

1,2,4 1011 Cw==

3,4 1100 DA==

1,3,4 1101 DQ==

2,3,4 1110 Dg==

1,2,3,4 1111 Dw==

Security Configuration 12-5

Employee Maintenance Security - Group Rank

Adding a New Group ID

New group IDs may be added at any time. No privileges are associated with a group
until they are assigned to it in the sec_privilege table. No users are associated with a
new group until they are assigned to it.

Note: If two job titles have the identical set of privileges, keep things
simple by using a single group for both job titles. For example, if both
store managers and regional managers are completely unrestricted, it
doesn't make sense to set up two separate security groups. There are
other fields in the table hrs_employee that can be used to distinguish
between the two if necessary for some future function.

Assigning a Group Membership to a User in Xstore Point of Service

The group IDs that are defined in the sec_groups table can be selected from a list in the
Employee Maintenance module of Xstore Point of Service. When an employee record is
saved and a user is assigned to one or more groups, the binary value that represents that
combination of groups is automatically generated. This binary value is then converted to
its Base64 equivalent and stored in the table hrs_employee in the
group_membership column.
Groups may be assigned to a user or deleted from a user at any time in the Employee
Maintenance module. The new combination of groups in the user’s group membership is
automatically updated in the table hrs_employee.
The screen below shows an example of a user who is being assigned to two groups:
Cashier and Manager. The group names that are available are based on the entries in the
description column in the sec_groups table.

Figure 12-2: Assigning Groups to a User in Employee Maintenance

12-6 Technical Guide

 Security-Related Tables

Security-Related Tables
Much of Xstore Point of Service security is implemented through the use of four
database tables:
• sec_groups
• hrs_employee
• sec_privilege
• sec_access_types
For information about these tables and the Dataloader records used to populate them,
see the Xstore Point of Service Database Dictionary and the Xstore Point of Service Host
Interface Guide.

Security-Related Configuration: Menu Visibility

In SysConfig.xml, the option “HideDeniedSecureOption” can be used to hide menu
options the user does not have security privileges to use.
Set up the following SysConfig.xml configuration option to specify whether or not the
system should hide an option to which access is denied due to a user having insufficient
privilege.
<Setting name="HideDeniedSecureOption">false</Setting>
- When set to true, do not
display the option for this
user based on security
privilege (hidden).
- When set to false, display the
option in disabled format for
this user based on security
privilege.

Securing Forms and Fields

Data entry forms and groups of fields on a form can be secured by defining secured
objects. A secured object may be a selected group of fields, such as those pertaining to
customers or employees. Within a form, a group of fields that are related (for example,
employee data such as name, address, phone, etc.) can be assigned a unique ID that is
defined in the file DaoEditMapping.xml.
A small section of DaoEditMapping.xml is shown below. The tag <DaoEditMapping
name> defines the name “EMPLOYEE”. The definition of the object named
“EMPLOYEE” includes a list of the fields that are part of the object and the tag
<secured_object> assigns the field to a secured object ID that is referenced in the
database table sec_access_types.
<DaoEditMapping name="EMPLOYEE">
<model_name dtype="Translatable">_employeeMaintenanceName</
model_name>
<edit_model_class
dtype="Class">dtv.pos.employee.EmployeeMaintenanceModel</
edit_model_class>

Security Configuration 12-7

Securing Forms and Fields

<description
dtype="Translatable">_employeeMaintenanceDescription</
description>
<data_object_ref dtype="String">EMPLOYEE</data_object_ref>
<data_object_ref dtype="String">EMPLOYEE_PASSWORD</
data_object_ref>
...
</DaoEditMapping>
<DataObjectDefinition name="EMPLOYEE">
<KeyFields>
...
</KeyFields>
<DataEditFieldList>
<DataEditField name="hireDate">
<Class>Date</Class>
<cardinality dtype="String">0..1</cardinality>
<secured_object dtype="String">EMPLOYEE_DATA</
secured_object>
</DataEditField>
<DataEditField name="activeDate">
<Class>Date</Class>
<cardinality dtype="String">0..1</cardinality>
<secured_object dtype="String">EMPLOYEE_DATA</
secured_object>
</DataEditField>
<DataEditField name="employeeStatusCode">
...

sec_access_types Table
In the table sec_access_types, a secured object ID (such as EMPLOYEE_DATA in the
example found in the section “Securing Forms and Fields”) may be assigned privileges
including CREATE, READ and UPDATE. Those privileges are assigned by entering
them in the access_typcode column.
If a user is in the membership group associated with a secured object ID, the user has the
security privileges of that membership group.

Figure 12-3: Sample sec_access_types Table

12-8 Technical Guide

 User Login and Password Security

User Login and Password Security

The first level of security is implemented by the user login process. After successfully
entering a login ID and password, the user’s password is checked against the entry in the
password column in the table hrs_employee_password. The password is an entry
that is stored in a hash table. The user’s ID must also be found in the employee_id
column of the hrs_employee_store table to complete the login.
Several different password requirements are controlled by settings in the file
SysConfig.xml.
The sample below shows the various password requirements that may be configured in
SysConfig.xml.
<Setting name="LoginSecurity---AccountLockout---Enabled">true</
Setting>
<Setting name="LoginSecurity---AccountLockout---Retries">3</
Setting>
<Setting name="LoginSecurity---ChallengeQuestionRetries">3</
Setting>
<Setting name="LoginSecurity---ChallengeQuestionsEnabled">true</
Setting>
<Setting name="LoginSecurity---IdType">employee_id</Setting>
<Setting name="LoginSecurity---LapseTimeBeforeUnlockingUser">30</
Setting>
<Setting name="LoginSecurity---NumberOfChallengeQuestions">3</
Setting>
<Setting name="LoginSecurity---PasswordExpiration---Days">90</
Setting>
<Setting name="LoginSecurity---PasswordExpiration---
Enabled">true</Setting>
<Setting name="LoginSecurity---PasswordHistoryLength">4</Setting>
- IdType: The security identification type the associates will use to log into the
system, Employee ID or Login ID.
- PasswordHistoryLength: Associates are not allowed to reuse the same
password within this number of password resets.
- AccountLockout: The settings in this tag indicate the rules for the account
lockout functionality.
* Enabled: Turns on/off the AccountLockout functionality where the
system locks out the associate’s account after a configured number of failed
login retries. If true, use failed login retries lock-out functionality. If false, do
not use failed login retries lock-out functionality.
* Retries: If AccountLockout functionality is enabled, the system locks
out the associate’s account after this number of failed login retries.
- PasswordExpiration: The settings in this tag indicate the rules for password
expiration.
* Enabled: Turns on/off PasswordExpiration functionality to expire an
employee login password after a specified number of days. If true, use
password expiration to expire an employee login password after a specified

Security Configuration 12-9

User Login and Password Security

number of days. If false, do not use password expiration to expire an

employee login password after a specified number of days.
* Days: If PasswordExpiration functionality is enabled, the system
expires an employee login password after this number of days. The date in
the effective_date column in the hrs_employee_password table is
used as the starting date.
* ChallengeQuestionsEnabled: Determines whether or not to use
employee password challenge questions when an employee forgets his/her
password. When true, challenge questions functionality is enabled. When
false, challenge question functionality is not used.
* NumberOfChallengeQuestions: When
ChallengeQuestionsEnabled is true, this is the number of questions
required to be answered when an employee forgets his/her password.
* ChallengeQuestionRetries: When ChallengeQuestionsEnabled
is true, this is the number of retry attempts allowed per question when
answering challenge questions.

Note: For more information about using challenge questions, see

“Employee Challenge Questions Setup”.

Requirements for Password Validation

The password requirements established in validations.xml. The example below
shows validation rules in validations.xml.
<bean id="newPasswordRules" parent="validationRuleList">
<property name="rules">
<list>
<ref bean="strongPasswordRule" />
<ref bean="ValidatePasswordReentryRule" />
</list>
</property>
</bean>

<bean id="newPasswordForExistingEmployeeRules"
parent="newPasswordRules">
<property name="rules">
<list merge="true">
<ref bean="passwordValidationEmpMaintenance" />
</list>
</property>
</bean>

<bean id="newPasswordForForcePasswordChange"
parent="newPasswordRules">

12-10 Technical Guide

 Employee Challenge Questions Setup

<property name="rules">
<list merge="true">
<ref bean="passwordValidationSecurity" />
</list>
</property>
</bean>

Employee Challenge Questions Setup

If enabled in Xstore Point of Service, associates will be able to reset their passwords by
first identifying themselves. This is accomplished by successfully answering password
challenge questions that the associate would have previously answered. After answering
the challenge questions correctly, the associate is free to reset his/her password.
If Xstore Point of Service has been configured to use password challenge questions,
Xstore Point of Service will recognize any associate that has not yet selected and
answered the challenge questions when the associate successfully logs into the Back
Office. After the successful login, Xstore Point of Service will prompt the user to select
and answer the questions. The user's selections are then saved to their employee profile.
This section explains how to set up password challenge questions for employees when
they use the “Forgot Password?” functionality in Xstore Point of Service. This optional
feature provides employees with the ability to reset their forgotten passwords without
manager interaction.
When this functionality is enabled, the following ten questions are available for use in
base Xstore Point of Service:
- In what city were you born?
- What is your mother's maiden name?
- What is your maternal grandmother's first name?
- What was the make of your first car?
- In what year did you graduate high school?
- What is the name of your childhood best friend?
- What was the name of your favorite teacher?
- What was the name of your first pet?
- What is your father's middle name?
- Which season is your favorite?

Note: These values are stored in the com_code_value table,

EMPLOYEE_CHALLENGE category.

SysConfig.xml Setup
Three configuration options control this functionality:
ChallengeQuestionsEnabled, NumberOfChallengeQuestions, and
ChallengeQuestionRetries. See “User Login and Password Security” for more
information about these configuration options.

Security Configuration 12-11

Security Overrides & Secondary Approvals

Database Table Setup

The hrs_employee_answers table stores employee answers (encrypted) to the
password challenge questions. For information about this table and the Dataloader
record used to populate it, see the Xstore Point of Service Database Dictionary and the
Xstore Point of Service Host Interface Guide.

Security Overrides & Secondary Approvals

Security overrides and second approvals is stored in database table
sec_activity_log.

Note: Refer to the Xstore Point of Service Database Dictionary for

more information.

sec_activity_log Table

Column Valid Values Description

rtl_loc_id loc_rtl_loc.rtl_loc_id The store number that logged the

activity.

wkstn_id integer The register that logged the activity.

business_date date The business date on which the

activity was logged.

trans_seq integer An identifier for transaction during

which the activity was logged.

activity_typcode AUTHENTICATE The type of activity that occurred.

AUTHORIZE
LOGIN
LOGOUT
OVERRIDE_AUTHENTICATE
OVERRIDE_AUTHORIZE
REAUTHENTICATE
SECOND_PROMPT

success_flag true A flag indicating whether or not the

activity resulted in success.
false

employee_id varchar(60) The employee that initiated the

activity.

overriding_ varchar(60) The employee that provided

employee_id credentials for an override when the
employee who initiated the activity
did not have sufficient privilege.

privilege_type varchar(255) The security privilege type that is

associated with this activity.

system_datetime datetime The system date and time on which

the activity occurred.

12-12 Technical Guide

 13
Address Mapping

Overview
This chapter provides information about the optional conversion of address mapping
data from flat files to database records.
The *.dat files included with Xstore Point of Service are used to determine valid address-
related values, and bind those values in geographical relationships. This allows Xstore
Point of Service to auto-populate some fields based on user entry and prevents the input
of invalid address combinations.
Xstore Point of Service allows porting the address data currently stored in the *.dat files
to the database and create download interfaces to populate the appropriate tables. This
enables clients to keep their store systems' address data in synch by downloading
DataLoader records.
The base distribution of Xstore Point of Service supports the *.dat file-based
implementation. The database address feature can be enabled through Spring
configuration.

Address Mapping
Address mapping is managed through Spring configurations in the
C:\xstoredata\lib\config.jar\dtv\res\config\spring\editmodels.xml
file.

Database Mapping
Database-based address mapping is enabled by setting the addressDataSource bean
to the following:
<bean id="addressDataSource"
class="dtv.xst.address.DtxAddressDataSource"
depends-on="dataFactoryAssistant"/>

File Mapping
File-based address mapping is enabled by setting the addressDataSource bean to the
following:
<bean id="addressDataSource"
class="dtv.util.address.datasource.FileAddressDataSource" />
When file-based address mapping is enabled, FileAddressDataSource retrieves
address mapping information from the *.dat files in the location specified in the
dtv.uti.address.FileLocation configuration in system.properties:
dtv.util.address.FileLocation=res/address/

Address Mapping 13-1

Database Tables

Database Tables
The following database tables contain the mapping data for address information:
• com_address_country
• com_address_postalcode
• com_address_state
For more information about these tables, refer to the Xstore Point of Service Database
Dictionary and the Xstore Point of Service Host Interface Guide.

Note: Changes to these database tables require a restart of Xstore

Point of Service before they take effect.

Supported Address Service Modes

SENDSALE – Receiving Documents, Send Sale
CUSTOMER – Customer Maintenance/Search, Credit Application, Large Cash
Payments
EMPLOYEE – Employee Maintenance
HOME_OFFICE_CHECK – Home office check info prompts
SHIPPING – Shipping Documents
TAX_EXEMPT – Editing tax exemptions
REPORTING – Reporting prompts
TENDER – Identity verification for tender operations
DEFAULT – Used if the data for more specific modes is not populated

Note: If not specified in download data or sql inserts, DEFAULT will

populate the address_mode field. For any of the address service tables,
the data for the DEFAULT mode will be used in place of any mode that
does not have any corresponding data of its own.

Multiple Customer Addresses/Change Country

Base Xstore Point of Service: General Considerations

Change Country
• The “Change Country” feature applies to Customer Maintenance, Customer
Addresses, Send Sale, Special Order, and Order.
• Base Xstore Point of Service is configured for US and Canada. Therefore, in base
Xstore Point of Service, users will always have the ability to switch between the US
and Canada. This is based on the StoreLocationsAvailable.xml file.

StoreLocationsAvailable.xml file
<LocationList>
<Region id="America">
<Country code="US" name="_countryUS"/>

13-2 Technical Guide

 Multiple Customer Addresses/Change Country

<Country code="CA" name="_countryCA"/>

</Region>
<Region id="Asia-Pacific"/>
<Region id="Africa"/>
<Region id="Europe"/>
</LocationList>

Note: For example, if a customer does not want Canada to be

available, the CA country reference can be removed from this file.

• The form name will not change when the Change Country menu option is selected
since the base forms for US and CA are the same on the customer lookup screen.
• A visibility rule supports the scenario in which a customer uses only one country
(i.e. US) so that the Change Country button is disabled.

Addresses
• If there is no country populated on the customer address in Customer Engagement
Cloud Services, then the country will be set to the default locale's country when the
customer record is retrieved.
• When using Customer Engagement Cloud Services, a delete for a given type of
address (e.g. "VACATION") will result in a delete of all addresses of that type.
• Only the primary address is written to the POS Log.

Address Mapping 13-3

Multiple Customer Addresses/Change Country

13-4 Technical Guide

 14
Shipping Fee Configuration

Overview
Specifying shipping fees for ship item accounts allows for more flexibility when
selecting the appropriate fee. Several elements can be taken into account when
determining shipping fees, including account type, retail location, shipping method, and
the item to be shipped. The actual calculation of the shipping fee itself includes the
ability to calculate the fee on a per-item basis or a per-transaction basis with several fee
aggregation strategies.

How Shipping Fees are Calculated

Xstore Point of Service determines the shipping fee value and shipping fee line item
number for the account using the process outlined here. Ship accounts in Xstore Point of
Service have a single shipping fee line item that is updated as items are added or
removed.
1. Xstore Point of Service selects an appropriate shipping fee record for the calculation.
See “Shipping Fee Setup” for more information about setting up shipping fees.
2. All shipping fee records for the organization ID of the current Xstore Point of Service
organization are collected and sorted in priority order, ascending.
3. Each shipping fee record is evaluated in turn. The first record to pass evaluation is
selected for the rest of the calculation.
- If all of the following conditions are met, a shipping fee record passes evaluation
and becomes the selected shipping fee:
i) The hierarchy level described by the shipping fee's
com_shipping_fee.org_code and com_shipping_fee.org_value
matches the current hierarchy level of the register <OR> the shipping fee's
hierarchy level is contained in the location hierarchy of the register <OR> the
shipping fee's hierarchy level is blank.
For example, if a register is open at STORE 101 which is part of the following
location hierarchy: *:*, REGION:Cleveland Metro, STORE:101; then, a
shipping rule with a hierarchy level of any of the hierarchy levels that make
up that location hierarchy will pass the hierarchy level condition.
ii) The rule specified in the com_shipping_fee.rule_type column of the
shipping fee record returns true when passed
com_shipping_fee.param1 and com_shipping_fee.param2 (see
“Shipping Fee Rules:”) <OR> the com_shipping_fee.rule_type is
blank. Note: Not all rules require both, or even either parameter. In these
cases, any values in those columns will be ignored.

Shipping Fee Configuration 14-1

How Shipping Fees are Calculated

For example, if a send sale account has a ship to address in Georgia and a
given shipping fee record has the rule_type of SHIP_TO_STATE_RULE,
(which compares the state of the ship to address to a state abbreviation in
the param1 column) and the shipping fee record has a value of "HI" in the
param1 column, then the rule will evaluate to false and the shipping fee
record will not become the selected shipping fee.
- If no shipping fee record is selected (in the scenario that none pass the
evaluation), then this process is interrupted and no shipping fee will be
assessed.
4. When a shipping fee record is selected, several key elements of the shipping fee
calculation become known: the item number of the shipping fee line item, the
aggregation type to use for per item calculations, and the collection of shipping fee
tier records to be evaluated in the next step.
5. Xstore Point of Service retrieves the selected shipping fee's corresponding shipping
fee tier records, known as the potential shipping fee tier records. The potential
shipping fee tier records are sorted in priority order, ascending.
6. Xstore Point of Service looks up the shipping fee calculation strategy to use based on
the account's type. This mapping of account type to strategy is defined in
SysConfig.xml. There are two possible shipping fee calculation strategies, Per
Transaction (“Per Transaction Shipping Fee Calculation Strategy”) and Per Item
(“Per Item Shipping Fee Calculation Strategy”).
7. Once the shipping fee has been calculated, the shipping fee line item for the account
is updated with the new price. If no shipping fee line item exists for the account, one
is added using the item specified by the selected shipping fee record in the
com_shipping_fee.ship_item_id column.

Per Transaction Shipping Fee Calculation Strategy

a. Xstore Point of Service calculates the shippable subtotal for the account based on
the prices of the physical items in the account.
b. Each potential shipping fee tier record is evaluated in turn with the first
shipping fee tier record to pass evaluation becoming the selected shipping fee
tier. If all of the following conditions are met, a shipping fee tier record passes
evaluation:
* The shippable subtotal of the account is greater than or equal to the
com_shipping_fee_tier.min_price of the shipping fee tier record
<OR> com_shipping_fee_tier.min_price is blank.
* The shippable subtotal of the account is less than the
com_shipping_fee_tier.max_price of the shipping fee tier record
<OR> com_shipping_fee_tier.max_price is blank.
* The rule specified in the com_shipping_fee_tier.rule_type column
of the shipping fee tier record returns true when passed
com_shipping_fee_tier.param1 and
com_shipping_fee_tier.param2 (see “Shipping Fee Rules:”) <OR> the
com_shipping_fee_tier.rule_type is blank. Note: Not all rules
require both or even either parameter. In these cases, any values in those
columns will be ignored.
c. The selected shipping fee tier record specifies several key elements of the
shipping fee calculation: the type of shipping fee and the fee value. Once known,
the shipping fee for the account can be determined. The fee calculation behavior
is based on the com_shipping_fee_tier.fee_type:

14-2 Technical Guide

 How Shipping Fees are Calculated

* FEE - A flat shipping fee will be assigned to the account, the fee assigned is
equal to the com_shipping_fee_tier.fee_value of the selected
shipping fee tier record.
* FEE_PERCENT - A fee will be calculated based on a percentage of the
shippable subtotal. The shippable subtotal is multiplied by
com_shipping_fee_tier.fee_value. Normally,
com_shipping_fee_tier.fee_value should have a value between 0
and 1.
* SHIP_ITEM_PRICE - The fee for the account will be equal to the price of the
shipping fee item specified by the selected shipping fee record. Any value in
com_shipping_fee_tier.fee_value is ignored.

Per Item Shipping Fee Calculation Strategy

a. Xstore Point of Service evaluates the potential shipping fee tier records for
EACH physical item in the account.
b. A shipping fee tier record is selected for a given item if all of the following
conditions are met:
* The price of the item is greater than or equal to the
com_shipping_fee_tier.min_price of the shipping fee tier record
<OR> com_shipping_fee_tier.min_price is blank.
* The price of the item is less than the
com_shipping_fee_tier.max_price of the shipping fee tier record
<OR> com_shipping_fee_tier.max_price is blank.
* The ship method selected for the item matches the
com_shipping_fee_tier.ship_method of the shipping fee tier record
<OR> com_shipping_fee_tier.ship_method is blank <OR> no
shipping method was selected for the item.
* The item number of the item matches the
com_shipping_fee_tier.item_id of the shipping fee tier record <OR>
com_shipping_fee_tier.item_id is blank. This provides the ability to
configure special tiers for specific items.
* The rule specified in the com_shipping_fee_tier.rule_type column
of the shipping fee tier record returns true when passed param1 and
param2 (see “Shipping Fee Rules:”) <OR> the
com_shipping_fee_tier.rule_type is blank. Note: Not all rules
require both or even either parameter. In these cases, any values in those
columns will be ignored.
c. Once a shipping fee tier record is selected for each physical item in the account, a
shipping fee will be calculated for each item. The fee calculation is based on the
fee type of the selected shipping fee tier records:
* FEE - A flat shipping fee will be assigned to the account, the fee assigned is
equal to the com_shipping_fee_tier.fee_value of the selected
shipping fee tier record.
* FEE_PERCENT - A fee will be calculated based on a percentage of the item
price. The item price is multiplied by
com_shipping_fee_tier.fee_value. Normally,
com_shipping_fee_tier.fee_value should have a value between 0
and 1.

Shipping Fee Configuration 14-3

Shipping Fee Setup

* SHIP_ITEM_PRICE - The fee for the account will be equal to the price of the
shipping fee item specified by the selected shipping fee record. Any value in
com_shipping_fee_tier.fee_value is ignored.
d. Once a shipping fee is calculated for each physical item in the account, the fees
will be aggregated according to the method specified by the selected shipping
fee record:
* TOTAL - Add all the fees together and make that sum the shipping fee for
the account
* AVERAGE - Take the average of all the fees and make that the shipping fee
for the account
* HIGHEST - Take the highest shipping fee among all the individual item fee
and make that the shipping fee for the account
* LOWEST - Take the lowest shipping fee among all the individual item fee
and make that the shipping fee for the account

Shipping Fee Setup

The following configuration files and database tables control the shipping fee
functionality.

Configuration Files

SysConfig.xml
<ShipCalcType dtype="String">PER_TRANSACTION</ShipCalcType>
This configuration applies to the following send sale types and defines whether these
accounts will have their shipping fee calculated on a per item or per transaction basis:
- SendSale
- SpecialOrder
- Order
Valid Values:
- PER_TRANSACTION - The calculation of the shipping fee will be based upon
properties of the account and current transaction, not taking into account the
values of the individual line items of the transaction. Examples of properties that
may be taken into consideration: transaction subtotal, ship to address.
- PER_ITEM - The calculation of the shipping fee for a transaction is based on an
aggregation of the shipping costs for the individual line items in the account.
The individual calculations of shipping cost may take into account properties of
the account and current transaction, along with properties of the item itself.
Examples of aggregations include: total shipping cost and greatest shipping
cost.

ShippingFeeConfig.xml
This configuration file contains the available shipping fee rules delivered with Xstore
Point of Service:
<ShippingFees xmlns:dtv="http://www.datavantagecorp.com/xstore"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="ShippingFeeConfig.xsd">

14-4 Technical Guide

 Shipping Fee Setup

<ShippingRule name="TRUE_RULE">
<Class>dtv.pos.shippingfee.rules.TrueRule</Class>
</ShippingRule>
<ShippingRule name="FALSE_RULE">
<Class>dtv.pos.shippingfee.rules.FalseRule</Class>
</ShippingRule>
<ShippingRule name="SHIP_TO_STATE_RULE">
<Class>dtv.pos.shippingfee.rules.ShipToStateCheckRule</Class>
</ShippingRule>
<ShippingRule name="SHIP_TO_ZIP_RULE">
<Class>dtv.pos.shippingfee.rules.ShipToZipCheckRule</Class>
</ShippingRule>
<ShippingRule name="ACCOUNT_TYPE_RULE">
<Class>dtv.pos.shippingfee.rules.AccountTypeRule</Class>
</ShippingRule>
<ShippingRule name="SPECIAL_ORDER_RULE">
<Class>dtv.pos.shippingfee.rules.SpecialOrderRule</Class>
</ShippingRule>
<FeeAggregation name="TOTAL">
<Class>dtv.pos.shippingfee.aggregation.TotalFeeAggregation</
Class>
</FeeAggregation>
<FeeAggregation name="AVERAGE">
<Class>dtv.pos.shippingfee.aggregation.AverageFeeAggregation</
Class>
</FeeAggregation>
<FeeAggregation name="HIGHEST">
<Class>dtv.pos.shippingfee.aggregation.HighestFeeAggregation</
Class>
</FeeAggregation>
<FeeAggregation name="LOWEST">
<Class>dtv.pos.shippingfee.aggregation.LowestFeeAggregation</
Class>
</FeeAggregation>
</ShippingFees>
• Shipping Rule Values: TRUE_RULE, FALSE_RULE, SHIP_TO_STATE_RULE,
SHIP_TO_ZIP_RULE, ACCOUNT_TYPE_RULE, SPECIAL_ORDER_RULE
• Fee Aggregation Values: TOTAL, AVERAGE, HIGHEST, LOWEST

Shipping Fee Configuration 14-5

FAQ: Shipping Fees

Database Tables
All shipping fee schedules are found within two database tables: com_shipping_fee
and com_shipping_fee_tier. For information about these tables and the Dataloader
records used to populate them, see the Xstore Point of Service Database Dictionary and the
Xstore Point of Service Host Interface Guide.

Shipping Fee Rules:

Rule Name Param1 Param2 Description

SHIP_TO_STATE_ state NA Evaluates to true if the state of the ship to

RULE abbreviation address for the account matches the state
abbreviation in param1.

SHIP_TO_ZIP_ Zip code NA Evaluates to true if the Zip code of the

RULE ship to address for the account matches
the Zip code in param1.

TRUE_RULE NA NA Always evaluates to true: Same as a blank

rule_type.

FALSE_RULE NA NA Always evaluates to false: Used for

turning shipping fees and shipping fee
tiers off.

ACCOUNT_ account type NA Evaluates to true if the account type of the

TYPE_RULE ship to address for the account matches
the account type in param1.

FAQ: Shipping Fees

How do the minimum and maximum shipping prices work together?
In the com_shipping_fee_tier table, the min_price column is inclusive and the
max_price column is exclusive.
SETUP EXAMPLE:
- Regular_Range_1: min_price=0.00 and max_price=15.00
- Regular_Range_2: min_price=15.00 min and max_price=25.00
Then, if the item costs $15.00, it will roll to the Regular_Range_2 shipping fee since it is
excluded as max, and included as min.

How are shipping fees calculated using the fee_type of

SHIP_ITEM_PRICE?
SHIP_ITEM_PRICE tells the shipping fee calculator to use the price of the shipping fee
line item instead of the value in com_shipping_fee_tier.fee_value for the
shipping fee. It is most often used with PER_TRANSACTION calculations where the
shipping fee line item (designated by the ship_item_id column of
com_shipping_fee) defines the shipping fee value desired. This is similar to how
shipping fees were calculated in previous Xstore Point of Service versions where the
shipping fee was set by the price of one of the default shipping fee items: 603 – 608. (Uses
the price in the itm_item_prices table for item_id 608, not the tiered pricing in the
com_shipping_fee_tier table.)

14-6 Technical Guide

 FAQ: Shipping Fees

If the rule_type column of the shipping fee record is blank, or the

fee_value = NULL, should Xstore Point of Service prompt for a shipping
fee?
Prompting for a shipping fee is not supported.

If the fee_type column contains an invalid value or is blank, how are

fees processed?
Fee processing behaves differently in each of these scenarios:
- If fee_type contains an invalid value, then no fee is added
- If fee_type is blank, then the fee_type = FEE

Note: With PER_ITEM calculations, one item falling into a tier with
an invalid fee type may not result in no fee if other items happen to fall
into tiers with valid fee types. The items with invalid fee types are just
ignored for the final aggregate calculation.

When is the TRUE_RULE needed?

A blank rule_type and TRUE_RULE are equivalent. The TRUE_RULE was simply
added for completeness sake to balance the FALSE_RULE, which is useful for turning
shipping fees and shipping fee tiers off.

Do you have an example of where param1 and param2 are both filled in
the shipping_fee_tier table?
All current rule_types require one or no parameters. param2 is for rule_types
developed in the future that may need more parameters.

Why are the TOTAL, AVERAGE, HIGHEST, and LOWEST aggregation

methods used?
For accounts configured to use PER_ITEM shipping fee calculations, each item in the
transaction is passed through the shipping fee tiers, which results in a shipping fee being
determined for each item. We only want Xstore Point of Service to display a single
shipping fee line item (cuts down on clutter), so those individual item shipping fees need
to be totaled up somehow. The aggregation type of the shipping fee record tells Xstore
Point of Service how to total those fees up.
EXAMPLE:
If the item prices are $10, $45, $75; the shipping fees for those items individually would
be $3.95, $9.95, $15.95 respectively (using the standard shipping fee ranges). If the
REGULAR_RANGE_SHIPPING_FEE shipping fee record has an aggregation type of:
• TOTAL, the shipping fee line item should have a price of $29.85 (3.95+9.95+15.95).
• AVERAGE, the shipping fee line item should have a price of $9.95 (29.85/3).
• HIGHEST, the shipping fee line item should have a price of $15.95 (15.95>9.95>3.95).

What happens if multiple tiers have the same priority?

Assuming all rules apply, the system will randomly pick an option. Also, priority 0 is
perfectly valid and will be evaluated before priority 1.

Shipping Fee Configuration 14-7

FAQ: Shipping Fees

14-8 Technical Guide

 15
Send Sale Configuration

Overview
A send sale item is an item that must be shipped to a customer-specified offsite location
after it is purchased.
A send sale transaction can be performed if the item is in the store’s saleable inventory
when the purchase is made.

Send Sale Setup

Setup for send sales is done in SysConfig.xml:
<Setting name="SendSale---AutoGenerateShippingFee">true</Setting>
<Setting name="SendSale---CreateShippingDocument">true</Setting>
<Setting name="SendSale---CustomerIsDefaultDestination">true</
Setting>
<Setting name="SendSale---DisplaySoldItemCount">false</Setting>
<Setting name="SendSale---GenerateWeightedShippingFee">false</
Setting>
<Setting name="SendSale---
PrintSendSaleMerchandiseTicketPerItem">false</Setting>
<Setting name="SendSale---SendTaxType">DESTINATION</Setting>
<Setting name="SendSale---ShipCalcType">PER_TRANSACTION</Setting>
<Setting name="SendSale---
UnverifiedReturnsPromptSendSale">false</Setting>
<Setting name="SendSale---UseThisStoreAsFailOverTaxRate">true</
Setting>

Send Sale Configuration 15-1

Send Sale Setup

Create a Shipping Document

This configuration determines whether shipping documents are generated for send sale
transactions.
Set up the following SysConfig.xml configuration option to specify whether a shipping
document is created.
<Setting name="SendSale---CreateShippingDocument">true</Setting>
- When set to True, the system automatically creates a shipping document for the
send sale order. The send sale must be shipped from the back office shipping
module.
- When set to False, a shipping document is not created for the send sale order
and the system closes the send sale immediately, marking the send sale as
shipped.

Automatically Generate a Shipping Fee

Set up the following SysConfig.xml configuration option to specify whether a shipping
fee is calculated automatically.
<Setting name="SendSale---AutoGenerateShippingFee">true</Setting>
- When set to True, the system automatically calculates the shipping fee for the
send sale order and applies it to the transaction.
- When set to False, a shipping fee is not automatically calculated for the send sale
order.

Shipping Calculation Type

Set up the following SysConfig.xml configuration option to specify the basis on which a
shipping fee is calculated:
<Setting name="SendSale---ShipCalcType">PER_TRANSACTION</Setting>
- PER_ITEM - The shipping fee is calculated for each item in the send sale
transaction.
- PER_TRANSACTION - The shipping fee is calculated for the send sale
transaction.

Note: See Chapter 14, “Shipping Fee Configuration” for more

information about shipping fees.

Generate Weighted Shipping Fee

Set up the following SysConfig.xml configuration option to specify whether a weighted
shipping fee is calculated for every send sale item in the send sale order.

Note: AutoGenerateShippingFee must also be set to TRUE. In

addition, data must be populated in com_shipping_cost table
(SHIPPING_COST record). See the Xstore Point of Service Host
Interface Guide for more information.

<Setting name="SendSale---GenerateWeightedShippingFee">false</
Setting>

15-2 Technical Guide

 Send Sale Setup

- When set to True, a weighted shipping fee is calculated for every send sale item
in the send sale order. The user will be prompted to enter the weight of the item.
- When set to False, a weighted shipping fee is not used for send sale items.

Use Customer as the Default Destination

Set up the following SysConfig.xml configuration option to specify whether the address
of the current customer associated with the send sale transaction is used as the default
shipping address on the Send Sale Destination form.
<Setting name="SendSale---CustomerIsDefaultDestination">true</
Setting>
- When set to True, the system automatically populates the Send Sale Destination
form with the current customer’s information.
- When set to False, the Send Sale Destination form is displayed with blank fields.

Send Sale Tax Type

Set up the following SysConfig.xml configuration option to specify the method used to
calculate sales tax for send sale orders.
<Setting name="SendSale---SendTaxType">DESTINATION</Setting>
- DESTINATION - Use the destination tax rate.
- SELLING - Use the selling store tax rate.
- DEST_INSTATE - Use the selling store tax rate if the destination is located in the
same state as the current store.

Use this Store as the Fail-Over Tax Rate

Set up the following SysConfig.xml configuration option to specify whether the system
uses the current store’s tax location when the system cannot find the appropriate tax
location based on the ship-to postal code of the send sale order.
<Setting name="SendSale---UseThisStoreAsFailOverTaxRate">true</
Setting>
- When set to True, the system uses the current store’s tax location when unable to
find the ship-to postal code tax location.
- When set to False, the system will charge no tax if the system cannot find tax
information for the destination ZIP code.

Display Sold Item Count

Set up the following SysConfig.xml configuration option to specify whether the system
includes send sale items as part of the total items sold count shown on the sale screen.
<<Setting name="SendSale---DisplaySoldItemCount">false</Setting>
- When set to True, send sale items are included in the total items sold count.
- When set to False, send sale items are not included in the total items sold count.

Print Send Sale Merchandise Ticket Per Item

Set up the following SysConfig.xml configuration option to specify whether the system
prints a merchandise ticket for each send sale item sold.

Send Sale Configuration 15-3

Shipping Document Type Used for Send Sale

<Setting name="SendSale---
PrintSendSaleMerchandiseTicketPerItem">false</Setting>
- When set to True, the system prints a merchandise ticket for each send sale item
sold.
- When set to False, the system prints a single merchandise ticket for all send sale
items sold.

Unverified Returns: Prompt To Ask If Send Sale Item

Set up the following SysConfig.xml configuration option to specify whether the system
prompts the associate to ask if the customer is returning a send sale item when entering
return mode (Unverified Return type).
<Setting name="SendSale---
UnverifiedReturnsPromptSendSale">false</Setting>
- When set to True, prompt the associate to ask if this is a send sale item.
- When set to False, do not prompt the associate to ask if this is a send sale item.

Shipping Document Type Used for Send Sale

A SALE shipping document type is used for shipping send sale items to recipients. This
shipping document type is created automatically during a send sale transaction when
using the two-step process (<CreateShippingDocument
dtype="Boolean">true</CreateShippingDocument>). The SALE Shipping
document can be used to ship the items from the store to the recipient using the Back
Office Shipping module. This type of document populates the counts automatically.
Refer to the Xstore Point of Service Shipping, Receiving, and Inventory Guide for more
information about shipping items from the store.

15-4 Technical Guide

 16
Warranty Setup & Configuration

Overview
Xstore Point of Service supports the attachment of warranty or service plans to
merchandise items.
The warranty setup process uses both database tables and configuration files. In this
chapter, the database table information and the DataLoader Record and fields are listed
for each table and column. The SysConfig.xml and SequenceConfig.xml warranty
options are also listed and defined here. Additional configuration files are referenced by
Xstore Point of Service's warranty module; however, due to their technical nature and/or
the infrequency with which they need to be modified, they are only listed here and are
outside the scope of this document. See “Other Configuration Files” for a list of these
files.
The following database tables and configuration files must be set up to enable warranty
functionality in Xstore Point of Service. The process required to set up warranty
information for your stores, and a link to each section for more information, is provided
below:
1. Define a warranty item SKU representing a single warranty in the itm_item table.
2. For each warranty item SKU representing a single warranty, define the display
order, typecode, and subtype in the itm_non_phys_item table.
3. For each warranty item SKU representing a single warranty, provide additional
warranty-specific information in the itm_warranty_item table. This is the
primary detail table supporting all warranty items.
4. If required, set up this tiered pricing table for warranty items having an
itm_warranty_item.pricing_mthd_code of either TIERED_REGULAR or
TIERED_EXTENDED in the itm_warranty_item_price table.
5. Identify the items that are eligible for a warranty or warranties in the itm_item
table.
6. Map a each warranty-eligible merchandise item to one or more warranty items in the
itm_warranty_item_xref table.
7. Set up the sec_privilege table to define security privileges for warranty
functions.
8. Set the warranty-related options in the SysConfig.xml configuration file as needed.
See “Warranty Configuration - System Config” for SysConfig.xml setup.
9. Set the warranty-related options in the SequenceConfig.xml configuration file as
needed. See “Warranty Configuration - Sequence Config” for
SequenceConfig.xml setup.

Warranty Setup & Configuration 16-1

Warranty Database Setup

Warranty Database Setup

Warranty items are configured in the following tables:
• itm_item
• itm_non_phys_item
• itm_warranty_item
• itm_warranty_item_price
• itm_item_options
• itm_warranty_item_xref
• sec_privilege
The tables are updated using the WARRANTY_ITEM, WARRANTY_ITEM_PRICE,
WARRANTY_ITEM_XREF, and SEC_PRIVILEGE Dataloader records.
For information about this table and the Dataloader record used to populate it, see the
Xstore Point of Service Database Dictionary and the Xstore Point of Service Host Interface
Guide.

Warranty Configuration - System Config

SysConfig.xml
The following configuration parameters can be found under the XML element hierarchy
defined by: Store > SystemConfig > Warranty.

Autogenerate Warranty Id
Set up the following SysConfig.xml configuration option to specify whether the system
automatically generates a warranty identifier.
<Setting name="Warranty---AutoGenerateWarrantyId">true</Setting>
- When true, the IDs of newly issued warranties are automatically generated by
Xstore Point of Service.
- When false, Xstore Point of Service prompts the user to enter a warranty ID.

Customer Record Required

Set up the following SysConfig.xml configuration option to specify whether a customer
must be attached to a transaction prior to the issuance of any warranties in that
transaction.
<Setting name="Warranty---CustomerRecordRequired">true</Setting>
- When true, customer association is required.
- When false, customer association is not required.

Customer Acceptance Prompted

Set up the following SysConfig.xml configuration option to specify whether, upon
issuing a warranty, the system prompts the user to specify whether a different customer
than the one assigned to the current transaction should be assigned.
<Setting name="Warranty---CustomerAcceptancePrompted">true</
Setting>

16-2 Technical Guide

 Warranty Configuration - System Config

- When true, prompt for the warranty customer (warranty owner) for a newly
added warranty.
- When false, the warranty owner is automatically defaulted to the customer
attached to the transaction.

Notify When Any Warranty is Available

Set up the following SysConfig.xml configuration option to specify whether the associate
will be notified when an item just added to a sale transaction qualifies for any warranty.
<Setting name="Warranty---NotifyWhenAnyWarranty">true</Setting>
- When true, the associate will be notified when any warranty is available.
- When false, the associate will not be notified that a warranty is available. The
sale and return of warranties may only be accomplished through explicit
request.

Notify When No Warranty is Available

Set up the following SysConfig.xml configuration option to specify whether the associate
will be notified when an item just added to a sale transaction is not eligible for any
warranty.

Note: This configuration is rarely used.

<Setting name="Warranty---NotifyWhenNoWarranty">false</Setting>
- When true, the system will notify the associate that no warranty is available.
- When false, the associate will not be notified that there is no warranty available.

Notify When One Warranty is Available

Set up the following SysConfig.xml configuration option to specify whether the associate
will be notified when an item just added to a sale transaction is eligible for only one
warranty. (Rarely used)
<Setting name="Warranty---NotifyWhenOneWarranty">true</Setting>
- When true, the system will notify the associate that exactly one warranty is
available.
- When false, the associate will not be notified that there is only one warranty
available.

Allow Warranty Not On File

Per each context (return or work order), when enabled, the system will allow the user to
apply existing warranties that cannot be verified (given appropriate security clearance).
When disabled, the application of unverifiable warranties will always be prohibited.
<Setting name="Warranty---
AllowWarrantyNotOnFile">RETURN,WORK_ORDER</Setting>

Warranty Setup & Configuration 16-3

Warranty Configuration - Sequence Config

Warranty Configuration - Sequence Config

SequenceConfig.xml
The file SequenceConfig.xml determines the structure of warranty-related IDs
automatically generated by Xstore Point of Service.
Sequence numbers are determined as follows:
"WA" + SSSS + RRR + ######
Where "S" represents a store digit, "R" represents a register digit, and "#" represents a
sequential digit.

WARRANTY
Defines the structure of IDs assigned to newly issued warranties. Values appear in
itm_warranty.warranty_nbr and itm_warranty_journal.warranty_nbr
fields as part of those tables' primary keys.
<Sequence name="WARRANTY" ref="_COMMON_">
<FileName dtype="String">warranty.seq</FileName>
<Prefix dtype="String">WA</Prefix>
</Sequence>

WARRANTY_JOURNAL
Defines the structure of IDs assigned to newly issued warranty journal entries created to
record activity against a given warranty. Values appear in
itm_warranty_journal.journal_seq as part of that table's primary key.
<Sequence name="WARRANTY_JOURNAL" ref="_COMMON_">
<FileName dtype="String">warrantyJournal.seq</FileName>
<Numeric dtype="Boolean">true</Numeric>
</Sequence>

Other Configuration Files

The following are configuration files referenced by Xstore Point of Service's warranty
module. Due to their technical nature and/or the infrequency with which they need to be
modified, these files are outside the scope of this document.
• ContextConfig.xml
• InputConfig.xml
• ListViewConfig.xml
• MenuConfig.xml
• OpChainConfig.xml
• PersistenceManagerConfig.xml
• PmTypeMappingConfig.xml
• PromptConfig.xml
• QueryConfig.xml
• RcptConfig.xml

16-4 Technical Guide

 Other Configuration Files

• calculators.xml
• validations.xml

Warranty Setup & Configuration 16-5

Other Configuration Files

16-6 Technical Guide

 17
Return Transaction Configuration

Overview
Xstore Point of Service return processing provides the ability to accept returns for
transactions processed by outside systems. This functionality allows items purchased on
the web to be returned in a store location. See “Overview” on page 1.
Xstore Point of Service return processing also allows refund amounts to be prorated on a
per-item basis. Specified items may be returned at a prorated value from the original
purchase price as determined by the number of days between the date of purchase and
the date of return. See “Prorated Refund Amounts” on page 2.
If the customer does not have the original sale receipt, Xstore Point of Service can be
configured to process the return based on the customer’s purchase history record. See
“Returns from the Customer’s Purchase History” on page 4.
The credit card used in the original sale transaction can be used to find the items for a
return transaction and create a verified return using this information. See “About
Verified Returns” on page 5.
If the item cannot be found in the customer’s history or the Returns from the Customer’s
Purchase History configuration is disabled, a blind return is then used. There are several
configurations for blind returns. Blind Return Amount Threshold configurations
provide the ability to disallow large blind returns without authorization. The Blind
Returns Lowest Price Return Enabled configuration uses the lowest price for
the returned item from the item’s price history for blind returns. See “SysConfig.xml
Configuration Options” on page 7.
Xstore Point of Service also supports cross-border returns, both verified and unverified.
This is used to allow or disallow the return of items that were purchased in another
country. When this feature is enabled, return policies can be defined by country codes.
See “Cross-Border Returns” on page 5.

17-1
Prorated Refund Amounts

Prorated Refund Amounts

The amount refunded for a prorated refund item is determined by the number of days
between the original date of purchase and the date of return. Items are identified as
being prorated or not prorated on a per-item basis. The prorated refund amounts
functionality requires both configuration file and database table setup.

Configuration File

SysConfig.xml

<Setting name="ItemReturn---
ProRatedDiscountReturnsDisabled">false</Setting>
<Setting name="ItemReturn---ProRatedTaxOnReturnsDisabled">true</
Setting>
• ProrationTimeUnit - This configuration determines whether the proration
schedule and computation are based on days or months from the original date of
purchase.
Valid values:
- DAY
- MONTH
• ProRatedDiscountReturnsDisabled - Determines whether Xstore Point of
Service proration of discounts for returns is enabled.
- True = Proration of discounts for returns is turned off (disabled).
- False = Proration of discounts for returns is turned on (enabled).

Database Table
Returns are configured through the itm_refund_schedule table. For information about
this table and the Dataloader record used to populate it, see the Xstore Point of Service
Database Dictionary and the Xstore Point of Service Host Interface Guide.

How Prorated Amounts are Calculated

The amount refunded for items is determined by the number of days between the
original date of purchase and the date of return.

Formula:
if (Td <= Tm) then Pr = Po (i.e. return at full purchase price)
else if (Td > Tm and Td <= T0) then Pr = (Po - (Po * (Td / T0));
else Pr = 0

Where:
• Po = the original purchase price
• Tu = the time units, days or months, to use when calculating prorated refund
amounts (Configured globally, see “Configuration File” on page 2).
• Td = the number of time units (Tu) between the original purchase date and the
returned-on date

17-2 Technical Guide

 Prorated Refund Amounts

• T0 = the minimum number of time units between the original purchase date and the
returned-on date (Td) after which refund amount = 0
(Configured on a per-item basis, see “Database Table” on page 2).
• Tm = the maximum number of time units (Tu) between the original purchase date
and the returned-on date (Td) where refund amount = original purchase price
(Configured on a per-item basis, see “Database Table” on page 2).
• Pr = the calculated prorated return amount

Example:
SKU 1231109 was originally purchased for $139.99 and is being returned 45 days later.
Per store policy, a full refund is given if the item is returned within 30 days. A reduced
refund is given, declining over time, for up to 180 days following the date of purchase,
after which no refund will be given.
Based on the formula above:
Po = 139.99
Td = 45
T0 = 180
Tm = 30

45 > 30 and 45 <= 180

Therefore...
Pr = (139.99 - (139.99 * (45 / 180)) = $104.9925
Rounded to the nearest cent = $104.99

Xstore Point of Service UI Prorated Refund Example

In this example, Item 1008 is set up as follows in
the itm_refund_schedule table:
itm_refund_schedule.max_full_refund_t
ime = 30
itm_refund_schedule.min_no_refund_tim
e = 90
In this scenario, the customer returned the item 51
days after purchasing it, exceeding the full refund
day limit of 30 days, but within the 90 day limit
where no refund would have been given.

Technical Guide 17-3

Returns from the Customer’s Purchase History

The receipts also show the prorated information.

Figure 17-1: Prorated Return Item Receipt Example

Returns from the Customer’s Purchase History

To enable this functionality, set EnableCustomerHistoryLookup to true in
SysConfig.xml. When set to true, during a blind return, every item the customer presents
for return that is found in the customer’s purchase history will result in a prompt listing
the valid retail transactions containing the returned item. Verified returns on these
transactions can then be initiated from this prompt.
If returns from the customer’s purchase history is enabled, the
PromptBeforeNotInHistoryReturn configuration option controls the process if the
item is not found in the customer’s purchase history.

Requirements
• EnableCustomerHistoryLookup is set to true in SysConfig.xml. (If the flag
is set to false, the return will be processed as a blind return).
• Only transactions containing matching items meeting all of the following criteria
will be shown in the valid transaction list:
- Item is of type “SALE”.
- Item is not flagged as “disallowing returns”.
- Item has available quantity to return.
- Purchase transaction occurred within the configured “maximum days after
purchase” base setting.
• A customer must be attached to the return transaction when using the Lookup
History functionality. (If a customer is not attached to the return transaction,
depending upon the system configurations of requiring a customer for returns, the
associate is presented with the standard Customer search form so as to determine
the purchase history).
• The refund tender list available for returns based on customer purchase history is
the same as the list available for returns with receipts. The existing rules regarding
credit card refunds are also applicable.
• The PromptBeforeNotInHistoryReturn configuration option in SysConfig.xml
determines the behavior when an item is not found in the customer's purchase
history:

17-4 Technical Guide

 Cross-Border Returns

- If set to False, automatically allow the item to be returned.

- If set to True, notify the user that the item is not found and provide the (secured)
option to continue with the return or reject it.
• If PromptBeforeNotInHistoryReturn is set to True, a security privilege,
RETURN_ITEM_NOT_IN_HISTORY controls whether a user is allowed to return an
item not in the customer's purchase history. This value is defaulted to only allow
managers to return such items, and the privilege can be overridden.

Cross-Border Returns
Cross-border returns functionality provides the ability to either allow or disallow
returns (verified and unverified) between different countries.
When this feature is enabled, it is also possible to further refine the return policy by
country in order to restrict cross-border returns between two countries using a mapping
table. For example, allow cross-border returns between all countries except the US and
Mexico. In this example, US and Mexico country codes would be specified in the
com_country_return_map table. If country codes are not explicitly specified in the
mapping table, it is assumed returns are permitted between countries.

About Verified Returns

If the customer has the original receipt or credit card, the system verifies that the receipt
that accompanies the return, or the original credit card used in the sale, is found either
on the local system or the home office system. When the original transaction is found,
the system displays the original sale information in the View Port.

About Unverified Returns

If the customer has a sale receipt, but it cannot be found in the database, or if the original
receipt is found in the database, but is missing any data required to process the return,
the transaction must be processed as an unverified return.

SysConfig.xml Setup
<CrossBorderReturnsEnabled dtype="Boolean">true
</CrossBorderReturnsEnabled>
<Setting name="ItemReturn---CrossBorderReturnsEnabled">true</
Setting>
CrossBorderReturnsEnabled - Indicates whether cross-border returns are
supported.
- If set to true, cross-border returns are allowed.

Note: When CrossBorderReturnsEnabled is set to true, cross-

border returns are allowed for all countries unless the country codes
are explicitly entered into the com_country_return_map mapping
table, and the disallow flag is set to “true” to disallow returns.

- If set to false, cross-border returns are not allowed.

When cross-border return functionality is enabled (true), the system automatically looks
to the country mapping table (com_country_return_map) to see if any country-to-
country exclusions apply:

Technical Guide 17-5

Cross-Border Returns

- If the country of purchase has an entry in the table that corresponds to the return
store’s country, Xstore Point of Service looks at the disallow flag for the sold/
return country combination. If the flag is set to false, then the return can
proceed. If the flag is set to true, the return is not allowed.
- If the country of purchase does not have an entry in the table, then the return
will be processed since there are no restrictions.

Database Setup
The com_country_return_map mapping table is used to set up specific country-to-
country return restrictions. This table will include entries for the country codes for each
purchase location/return location, and a flag indicating if returns are allowed for the
country-to-country combination. For information about this table and the Dataloader
record used to populate it, see the Xstore Point of Service Database Dictionary and the
Xstore Point of Service Host Interface Guide.

Note: When cross-border returns are enabled and there are no entries
in the mapping table, cross-border returns will be accepted for all
country-to-country combinations.

When the disallow_cross_border_flag is set to true for a country code

combination, the return cannot be processed. When false, Xstore Point of Service will
allow the cross-border return for that combination.
Example: To prevent any items purchased in the US from being returned in Mexico, and
to also prevent any purchases in Mexico from being returned in the US, the table setup is
as follows:

purchased_from return_to disallow_cross_border_flag

US MX true

MX US true

Security Overrides for Cross-Border Returns

A security privilege provides the ability to override the cross border return restrictions
defined by the cross-boarder restrictions configuration and the mapping file. If a user
has this privilege enabled, they will have the ability to override the cross-border
restrictions for both verified and unverified returns.

sec_privilege Table
The default expected behavior is that the security prompt will only be displayed when
the user that is currently logged in does not have the proper privilege, otherwise if a
manager is already logged in then the security prompt will not appear at all. "EA==" is
the privilege assumed to be used by managers only.
To allow overrides, set the security privilege for the privilege_type
"RETURN_CROSS_BORDER" to the following:
authentication_rqrd = False
overridable_flag = True
group_member = EA==

17-6 Technical Guide

 SysConfig.xml Configuration Options

SysConfig.xml Configuration Options

The following SysConfig.xml configuration options are available for returns.
<Setting name="ItemReturn---
AllowItemNotOnFileBlindReturn">false</Setting>
<Setting name="ItemReturn---AllowVerifiedReturnChanges">true</
Setting>
<Setting name="ItemReturn---
AlwaysPromptForItemPriceUponBlindReturn">false</Setting>
<Setting name="ItemReturn---
AlwaysPromptForItemPriceUponUnverifiedReturn">false</Setting>
<Setting name="ItemReturn---BlindReturns---AmountThreshold">0</
Setting>
<Setting name="ItemReturn---BlindReturns---
AmountThresholdEnabled">false</Setting>
<Setting name="ItemReturn---BlindReturns---
LowestPriceReturnEnabled">true</Setting>
<Setting name="ItemReturn---CreditCommissionedAsscMethod---
CreditBlindReturnSaleCommissionMethod">HOUSE_ACCOUNT</Setting>
<Setting name="ItemReturn---CreditCommissionedAsscMethod---
CreditUnverifiedReturnSaleCommissionMethod">HOUSE_ACCOUNT</
Setting>
<Setting name="ItemReturn---CreditCommissionedAsscMethod---
CreditVerifiedReturnSaleCommissionMethod">HOUSE_ACCOUNT</Setting>
<Setting name="ItemReturn---CrossBorderReturnsEnabled">true</
Setting>
<Setting name="ItemReturn---CrossChannelReturnsEnabled">false</
Setting>
<Setting name="ItemReturn---CrossStateReturnsEnabled">true</
Setting>
<Setting name="ItemReturn---CrossStoreReturnsEnabled">true</
Setting>
<Setting name="ItemReturn---CustomerHistoryReturn---
EnableCustomerHistoryLookup">true</Setting>
<Setting name="ItemReturn---CustomerHistoryReturn---
PromptBeforeNotInHistoryReturn">true</Setting>
<Setting name="ItemReturn---CustomerRecordRequired">true</
Setting>
<Setting name="ItemReturn---
CustomerRecordRequiredWhenNegativeBalance">false</Setting>
<Setting name="ItemReturn---
DisallowMultipleTransInReturns">false</Setting>
<Setting name="ItemReturn---Discounts---
AllowDiscountsOnBlindReturn">true</Setting>

Technical Guide 17-7

SysConfig.xml Configuration Options

<Setting name="ItemReturn---Discounts---
AllowDiscountsOnUnverifiedReturn">true</Setting>
<Setting name="ItemReturn---Discounts---
AllowDiscountsOnVerifiedReturn">true</Setting>
<Setting name="ItemReturn---HouseAccountEmployeeId">0</Setting>
<Setting name="ItemReturn---MaxDaysAfterPurchase">300</Setting>
<Setting name="ItemReturn---
MaxTotalTransactionRefundThreshold">10000</Setting>
<Setting name="ItemReturn---MaximumReturnItemPrice">5000</
Setting>
<Setting name="ItemReturn---MinimumReturnItemPrice">0</Setting>
<Setting name="ItemReturn---PriceHistory---
AutoCalculateHistoryPrice">false</Setting>
<Setting name="ItemReturn---PriceHistory---
LookupPriceHistory">true</Setting>
<Setting name="ItemReturn---PriceHistory---
LookupVerifiedPriceHistory">false</Setting>
<Setting name="ItemReturn---PriceHistory---
PriceHistoryLookupPreviousNumberOfDays">30</Setting>
<Setting name="ItemReturn---
ProRatedDiscountReturnsDisabled">false</Setting>
<Setting name="ItemReturn---ProRatedTaxOnReturnsDisabled">true</
Setting>
<Setting name="ItemReturn---PromptForCustomer">true</Setting>
<Setting name="ItemReturn---
PromptGiftRcptForVerifiedReturnBarcodeScan">false</Setting>
<Setting name="ItemReturn---
PromptOriginalTransactionListUponEntry">true</Setting>
<Setting name="ItemReturn---
PromptTndrAmtForOriginalCreditCardTender">true</Setting>
<Setting name="ItemReturn---ProrationTimeUnit">DAY</Setting>
<Setting name="ItemReturn---RestockingFee---
PromptApplyRestockingFeeMessage">true</Setting>
<Setting name="ItemReturn---ReturnVerification---
ReturnVerificationRequired">true</Setting>
<Setting name="ItemReturn---
ValidateReturnSerialNumberAgainstOriginalTrans">true</Setting>
• PromptForCustomer - Determines whether the system prompts for a customer
search when entering return mode.
• CustomerRecordRequired - Determines whether the system requires customer
association before entering return mode.
- CustomerRecordRequired and PromptForCustomer can be conflicting
configurations. If CustomerRecordRequired is set to True and

17-8 Technical Guide

 SysConfig.xml Configuration Options

PromptForCustomer is set to False, then a conflict can arise if no customer is

attached when initiating a return.
- CustomerRecordRequired overrides PromptForCustomer. Therefore, if
CustomerRecordRequired is set to True, then the user is prompted to add a
customer when initiating a return regardless of the PromptForCustomer
setting.
• CreditBlindReturnSaleCommissionMethod - Determines which associate will
be assigned as the commissioned associate for a blind return transaction. (Customer
does not present the original sales receipt.) Valid Values: CURRENT_CASHIER,
CURRENT_COMMISSIONED_ASSC, HOUSE_ACCOUNT
• CreditUnverifiedReturnSaleCommissionMethod - Determines which
associate will be assigned as the commissioned associate for an unverified return
transaction. (Customer presents the original sales receipt but the system is not able
to retrieve the original sales transaction.) Valid Values: CURRENT_CASHIER,
CURRENT_COMMISSIONED_ASSC, HOUSE_ACCOUNT
• CreditVerifiedReturnSaleCommissionMethod - Determines which associate
will be assigned as the commissioned associate for a verified return transaction.
(Customer presents the original sales receipt and the system is able to retrieve the
original sales transaction.) Valid Values: ORIGINAL_COMMISSIONED_ASSC,
CURRENT_CASHIER, CURRENT_COMMISSIONED_ASSC, HOUSE_ACCOUNT
• AllowItemNotOnFileBlindReturn - Determines whether the system allows
returning an item that cannot be found in the database when the customer does not
present the original sales receipt.
• AlwaysPromptForItemPriceUponUnverifiedReturn - Determines whether
the system always prompts for the item price for an unverified return. (Customer
presents the original sales receipt but the system is not able to retrieve the original
sales transaction.)
• AlwaysPromptForItemPriceUponBlindReturn - Determines whether the
system always prompts for the item price for a blind return. (Customer does not
present the original sales receipt.)
• LookupPriceHistory - Determines whether the system looks up the price history
for the return item and prompts the associate to select the appropriate price.
• AutoCalculateHistoryPrice - Determines whether the system calculates the
price based on price history data.
• LookupVerifiedPriceHistory - Determines whether the system looks up the
price history for the verified return item. (Customer presents the original sales
receipt and the system is able to retrieve the original sales transaction.) When true,
the user is prompted to select the price from a list.
• PriceHistoryLookupPreviousNumberOfDays - The system looks up the item's
previous price history for the number of days specified here.
• HouseAccountEmployeeId - The employee identifier used for the house account.
Note: This configuration value should not be changed.
• PromptApplyRestockingFeeMessage - Determines whether the system
prompts with a message whenever a return restocking fee is applied to a retail
transaction.
• ReturnVerificationRequired - Determines whether the system attempts to
retrieve the original retail transaction when returns are made with the receipt.

Technical Guide 17-9

SysConfig.xml Configuration Options

• CrossChannelReturnsEnabled - Determines whether the system uses cross

channel return functionality.
• MaxTotalTransactionRefundThreshold - The maximum total refund amount
allowed per retail transaction. If there is no limit on the total value of a refund
transaction, enter a number that is large enough (such as 9999999) to effectively
assign no limit.
• MinimumReturnItemPrice - The minimum return item price allowed by the
system. This decimal number represents the smallest value that an item can have
and still be returned. Any item that was sold below this price cannot be returned.
• MaximumReturnItemPrice - The maximum return item price allowed by the
system.
• MaxDaysAfterPurchase - The maximum number of days since the original
purchase that the system allows the items to be returned. After the specified number
of days has passed after purchase, the item can no longer be returned. If there is no
time limit on item returns, enter a number that is large enough (such as 99999) to
effectively assign no limit.

Note: The MaxDaysAfterPurchase configuration allows you to set

the maximum number of days that can elapse between the sale of the
original transaction and the attempted return. If the number of days
between the sale and the return exceeds the threshold, a manager must
enter their employee ID and password to override the return. If your
store does not allow overrides, the associate cannot complete the
return

• ValidateReturnSerialNumberAgainstOriginalTrans - Determines
whether the system validates the item serial number against the item serial number
from the original sales transaction in verified return mode. (Customer presents the
original sales receipt and the system is able to retrieve the original sales transaction.)
• PromptTndrAmtForOriginalCreditCardTender - Determines whether the
system prompts for refund tender amount to be credited back to the selected original
sale credit card (TRUE), or assumes all of the refund amount will be credited back to
the selected original credit card (FALSE).
• AllowDiscountsOnBlindReturn - Determines whether the system allows
applying a discount on a blind return (Customer does not present the original sales
receipt.) This configuration applies only to line item and group discounts. This
configuration does not apply to transaction discounts.
• AllowDiscountsOnUnverifiedReturn - Determines whether the system allows
applying a discount on an unverified return. (Customer presents the original sales
receipt but the system is not able to retrieve the original sales transaction.) This
configuration applies only to line item and group discounts. This configuration does
not apply to transaction discounts.
• AllowDiscountsOnVerifiedReturn - Determines whether the system allows
applying a discount on a verified return. (Customer presents the original sales
receipt and the system is able to retrieve the original sales transaction.) This
configuration applies only to line item and group discounts. This configuration does
not apply to transaction discounts.
• ProrationTimeUnit - Determines whether proration schedule and computation
are based on days or months from the original date of purchase. Note: because a
"month" is a fixed calendar period and not an arbitrary time span, a return/purchase

17-10 Technical Guide

 SysConfig.xml Configuration Options

difference computed in months is just (difference in days * 30). The proration

formula, however, will be much less volatile when computed in months rather than
in days because the former will yield the same result for 30-day spans. Valid Values:
- DAY - Schedule and computation are based on days from the original date of
purchase.
- MONTH - Schedule and computation are based on months from the original
date of purchase
Base Default Value=DAY
• ProRatedDiscountReturnsDisabled - When this setting is enabled Xstore
Point of Service will turn off the pro-ration of discounts for returns.
• ProRatedTaxOnReturnsDisabled - When this setting is enabled Xstore Point of
Service will turn off the pro-ration of taxes for returns.
• EnableCustomerHistoryLookup - Determines whether blind returns can be
processed as verified returns using the customer's purchase history. If True, during a
blind return, every item returned that is contained in the customer's purchase
history will result in a prompt listing valid retail transactions containing the
returned item. If found, verified returns on these transactions can be initiated from
this prompt. If False, blind returns are not processed using the customer’s purchase
history.
• PromptBeforeNotInHistoryReturn - In a Customer History Return
(EnableCustomerHistoryLookup is set to True) this value determines whether
the user is challenged when a blind return is attempted on an item that is not in the
customer's purchase history, or that no valid retail transactions containing the item
have quantity available for return.
- True=The user will be challenged when a blind return is attempted on an item
that is not in the customer's purchase history, or that no valid retail transactions
containing the item have quantity available for return. When prompted,
selecting “Yes” will continue with the blind return, although this requires
having the RETURN_ITEM_NOT_IN_HISTORY privilege. Selecting “No” will
cancel the blind return of the item and return to the return item scan prompt.
- False=The user is not prompted whether to continue with the blind return.
The following configurations apply specifically to blind returns. (A return without a
receipt.)
• AmountThresholdEnabled - When this setting is enabled Xstore Point of Service
will validate the sum total of blind return(s) against the configuration setting
amount (AmountThreshold).
Valid Values:
- True = validates the sum total of the blind return(s) against the configured
amount (in the example above $50).
- False = no blind return threshold.
• AmountThreshold - This value works in conjunction with the
AmountThresholdEnabled configuration setting. When the amount threshold
option is enabled, the sum total of the blind return(s) is evaluated against the

Technical Guide 17-11

SysConfig.xml Configuration Options

defined dollar amount set by this configuration option. Enter the dollar amount that
a blind return must not exceed.

Note: The Blind Return Amount Threshold configurations

(AmountThresholdEnabled and AmountThreshold) allow you to
define a limit on a blind return amount submitted so you can minimize
fraud. If the amount of the return exceeds the threshold, a manager
will need to enter their employee ID and password to override. If your
store does not allow overrides, the associate will be unable to complete
the return.

• LowestPriceReturnEnabled - Provides the ability to always return items at the

lowest price for blind returns within a configurable number of days. When this
setting is enabled, Xstore Point of Service will use the lowest price for the returned
item from the item's price history for blind returns. If this functionality is not
enabled, Xstore Point of Service shows the price history list of previous prices for the
item being returned and allows the associate to select a price from the list.
• PromptOriginalTransactionListUponEntry - When this setting is enabled
Xstore Point of Service will first display the list of originally purchased items when
starting a new verified return.
• PromptGiftRcptForVerifiedReturnBarcodeScan - When this setting is
enabled Xstore Point of Service will ask if the receipt being scanned for a verified
return is a gift receipt.
• AllowVerifiedReturnChanges - When this setting is enabled, the user is
allowed to change price or tax information on verified return lines.

17-12 Technical Guide

 18
Hardware/UI Configuration

Overview
This chapter provides information about Xstore Point of Service hardware and UI
options.

Hardware Options
• Xstore Point of Service provides the ability to temporarily enable/disable specific
hardware devices through a Back Office menu option, Enable/Disable Hardware.
This process writes out a temporary HardwareConfig.xml file to a patch directory
for the devices that have been disabled, reloads the hardware configurations, and
then re-initializes the hardware. See “Enable/Disable Hardware”.
• Xstore Point of Service supports dual monitors to provide a customer-facing display
in addition to the POS display. See “Dual Monitor Setup”.
• Xstore Point of Service also supports a “virtual sigcap” window to allow for
signature capture on tablets. See “TransArmor Registration”.
• If needed, register VeriFone-supported devices with the First Data TransArmor
solution via the Reinitialize Hardware option in the Back Office Main Menu. See
“TransArmor Registration”.

UI Options
• Xstore Point of Service supports touch-screen mode, including a touch keyboard.
This keyboard provides the ability to type letters, numbers, and symbol characters
into data fields while using a touch-screen. See “Touch-Screen Keyboard Setup”.
• UI configuration also includes the ability to set up the POS screen orientation of the
focus bar to support different environments, such as a PC environment and a tablet
environment. See “UI Orientation Setup”.
• The Item Selection User Interfaces enables a retailer to use a button grid to select
configurable menu options and items. See

Hardware/UI Configuration 18-1

Enable/Disable Hardware

Enable/Disable Hardware
After selecting the Enable/Disable Hardware option from the Back Office Main Menu,
Xstore Point of Service displays the Hardware Device Management screen, listing the
hardware devices supported for this functionality.

Figure 18-1: Hardware Device Management Screen

A green check mark next to the device description indicates the device is currently
enabled.

A red next to the device description indicates the device is currently disabled.

Disable Device
When a device is disabled, Xstore Point of Service writes out a temporary
hardwareconfig.xml file to a patch directory. See “To disable device(s)”.

Enable Device
When a device is currently disabled, there are two options available to enable a
hardware device:
- The Enable Device option enables only the selected device(s), without removing
any configuration overrides (patch file entries) that may exist for other devices.
- The Clear Hardware Configs option removes all overrides to the device
configuration file which will enable all disabled devices. The system removes
the hardware configuration overrides (patch file entries) that were created when
the devices were disabled.

18-2 Technical Guide

 Printer Selection

HardwareConfig.xml File Example

The configurations are set in the
\xstore\config\version1\patch\HardwareConfig.xml file.

To disable device(s)
This example disables two devices through the Disable Device option: POS Printer and
Scanner.
<Hardware>
<Device type="POSPrinter" use="RECEIPT">
<Enabled dtype="Boolean">false</Enabled>
<name dtype="String">Generic-Printer-Log4j</name>
</Device>
<Device type="Scanner" use="BARCODE_SCANNER">
<Enabled dtype="Boolean">false</Enabled>
<name dtype="String">Virtual-Scanner-Swing</name>
</Device>
</Hardware>

To enable device(s)
If only one device is enabled through the Enable Device option (a Barcode Scanner in
this example), the POS Printer is still disabled as shown below. Note that the scanner
entry has been removed from the configuration file.
<Hardware>
<Device type="POSPrinter" use="RECEIPT">
<Enabled dtype="Boolean">false</Enabled>
<name dtype="String">Generic-Printer-Log4j</name>
</Device>
</Hardware>
If all devices are enabled through the Clear Hardware Configs option, the entire
HardwareConfig.xml file is removed.

Printer Selection
Xstore prompts you to scan or select a printer from a list of available and configured A4/
report printers, if there are multiple A4/report printers in a store. A4/report printers are
used for luxury receipts, BIP reports, and tax free invoice printing.

Note: For more information about printer selection configuration,

refer to the Configurator section in the Xstore Office User Guide.

SysConfig.xml
<Setting name="Hardware---PromptPrinterSelectionList">true</
Setting>

Hardware/UI Configuration 18-3

Dual Monitor Setup

PromptPrinterSelectionList - If set to true, Xstore displays a list of printers

configured for the operating system.

HardwareConfig.xml
<ShowPrinterDialog dtype="Boolean">false</ShowPrinterDialog>
The ShowPrinter Dialog setting in the HardwareConfig.xml file must be set to
false, if the SysConfig.xml setting Hardware---PromptPrinterSelectionList
is set to true.

QR Code Data Format

The format for the printer selection is as follows:
PRINTER|<Operating system configured printer name>
Example:
PRINTER|Solon Printer 2

Dual Monitor Setup

Xstore Point of Service supports dual monitors in order to provide a customer-facing
display. The customer-facing monitor is a configurable grid layout of UI components to
display to the customer.

Note: Dual Monitor is only supported on Classic Desktop.

Base Xstore Point of Service supports three primary modes of display:

- Application idle display
- Training mode screen
- Retail transaction screen, including options such as:
* Transaction details
* A thank you panel, "Thank you for Shopping!"
* A media panel displaying videos, by referencing an HTML file which
embeds an mp4 or similar format.
Example: translations.properties change
_customerDisplay.browser.url1=file:///C:/xstore/res/
movies/sample.html

Example HTML file:

<!DOCTYPE html>
<html>
<head>
</head>
<body>
<video controls preload="auto" autoplay loop>
<source src="SampleVideo.mp4" type='video/mp4'>
</video>
</body>
</html>
* A customer activity stream that is related to the retail transaction to display
information to the user

18-4 Technical Guide

 Dual Monitor Setup

* Suggested selling messages for items

* Other configurable displays such as a Web page, additional animations,
static text, or graphic images such as a company logo

Note: There are no customer-interactive capabilities.The layout is

configurable, but not dynamic. Xstore Point of Service must be
restarted to see any changes in the UI definition of the customer facing
display.

Setting Up Dual Monitors

The dual screen functionality can be enabled in SysConfig.xml.

Note: Single screen is enabled by default.

SysConfig.xml Example
<Setting name="DualDisplay---EnableDualDisplay">false</Setting>
EnableDualDisplay - Determines whether the dual display is enabled.

root system.properties File Configuration

On systems that are using a second display, the appropriate section must be
uncommented in the root\system.properties file:
# UI controller implementation BEGIN
# use the property below for single display
#dtv.pos.framework.ui.UIController=dtv.pos.framework.ui.UIControl
lerImplModal
# use the 2 properties below to enable dual displays
dtv.pos.framework.ui.UIController=dtv.pos.framework.ui.dualscreen
.DualScreenUIControllerImpl
dtv.pos.modelfactory=dtv.pos.framework.ui.dualscreen.DualScreenMo
delFactory
# UI controller implementation END

UIConfig.xml & SubstituteComponentConfig.xml Setup

If Xstore Point of Service sees the SubstitutedPanel component in UIConfig.xml
while assembling the UI, it will swap it out for a different panel specified in
SubstituteComponentConfig.xml. Irrelevant config portions have been removed
from the following example for brevity:

Note: The UIConfig.xml and the SubstituteComponentConfig.xml

are only supported on Classic Desktop installations.

UIConfig.xml Example
<Name dtype="String">CUST_TRAINING_VIEW</Name>
<Component name="CUST_TRAINING_VIEW" type="TransparentPanel"
layout="dtv.ui.layout.TableLayout">

Hardware/UI Configuration 18-5

Dual Monitor Setup

...............edited for brevity............

<Component type="SubstitutedPanel">
<ComponentParameter name="setComponentId"
value="CUST_DISPLAY_TRAINING"/>
</Component>
</Component>
</UI>
The setComponentId parameter of the SubstitutedPanel accepts a string
parameter which is the name of the substituted component to load from
SubstituteComponentConfig.xml.

SubstituteComponentConfig.xml Example
<SubstituteComponent name="CUST_DISPLAY_TRAINING">
<Component type="PanelText" layoutLocation="15, 15, 70, 70">
<ComponentParameter name="setFont">
<param_value
dtype="FontRef">_fontCustomerDisplayTrainingPanel</param_value>
</ComponentParameter>
<ComponentParameter name="setMessage"
value="_trainingModeCustomerMessage"/>
</Component>
</SubstituteComponent>

The Panel Components

This section explains the panel components with a brief overview of how to configure
them. The following panel types are supported:
• A panel that displays a text value from a resource bundle. The resource key and the
bundle are configurable, similar to how text and phone numbers are configured in
AuthConfig.xml. If a translation bundle is selected, this works with DB
translations.
• A panel that displays an image value from a resource bundle. The same constraints
from the panel described above apply here.
• A panel that displays a list view.
• A panel that displays a form.
• A panel that displays the target of a URL in a browser. This supports common URL
schemes, such as http and file.

Note: These are hybrid panels for convenience; they contain

subcomponents to make configuration faster and easier.

18-6 Technical Guide

 Dual Monitor Setup

Panel Type Description

PanelBordered A basic bordered panel. Used to contain other components, or

may be subclassed. Can call setBackground or
setBorderColor with a ColorConfig parameter to
customize the background and border colors.

PanelText Set the setMessage property to a translation key. Can also call
setFont which references ui.properties for customizing
how the text is displayed. Can also call setFontColor with a
ColorConfig parameter to specify the color of the text.

PanelImage Set the setImage property to a key from ui.properties

which specifies the image. Panel will shrink to fit the image
relative to its layout position.

EmbeddedBrowserPanel Call the setBrowser method with two parameters (i.e.

value1="" value2=""). The first parameter is the name identifying
the browser instance in the browser manager. The second is the
URL which uses standard translation key logic. If it is a key,
resolve it in translations.properties or
com_translations. Otherwise, use the literal value.

View Type: AbstractListView

AbstractListView manages displaying arbitrary lists that are not tied to the
transaction or a list prompt. This is used in base Xstore Point of Service to display the
customer message list. This works using the following:
1. A concrete implementation of AbstractListView. This must specify an event
descriptor used to listen to model updates. There must be a model key used to
identify the list model that backs the view and a list view type which references
ListViewConfig.xml.
At the abstract level this functionality does not care about the specific elements
being displayed. However, most list views will be interested in displaying a list of
text elements, optionally with an icon.
2. TextViewElement: Abstract class used to represent an object in the list. This is
completely optional to use, but is a convenience. These list elements are created
using the TextViewElementFactory. The factory is highly extensible and allows
the customer layer to override how base elements are displayed without changing
the view or creation logic. Subclasses of TextViewElement handle converting
specific objects into an element, and the factory calls the correct constructor based on
the object.
3. Best practice is that operations, being transient objects, should not deal directly with
events. A list view needs a delegate to manage generating updates to the view. For
the customer message list, this is CustomerMessageViewListSubmitter. Other
views should have submitter objects that work similarly but with different event
types.
4. AbstractListPromptOp has a hook method handleBeforeDisplayList()
which can be used by subclasses to perform an action before displaying a list to the
user. This can be leveraged to take the items in the list and fire a second event to
display them to the customer on the second display.

Hardware/UI Configuration 18-7

Virtual Signature Capture Setup

Virtual Signature Capture Setup

A virtual signature capture window allows for signature capture on tablets. When
Virtual Sigcap is enabled, a window displays atop the Xstore Point of Service UI, waiting
for a signature.

Note: If the virtual sigcap is not capturing the entire signature, check
the touch-screen setting in the OS or in the touch-screen software and
disable the "Enable right click on hold" setting.

Virtual sigcap is enabled via HardwareConfig.xml:

<Device type="SignatureCapture" use="SIG_CAP">
<name dtype="String">Virtual-SigCap-Swing</name>
<width dtype="Integer">-1</width>
<height dtype="Integer">-1</height>
</Device>

Note: Set the width and height to -1 to cover the full screen. The
default value is -1.

TransArmor Registration
The TransArmor registration process in Xstore Point of Service allows VeriFone-
supported devices to be registered with the First Data TransAmor solution. Whenever a
VeriFone device moves from one lane to another, whether previously encrypting or not,
or is brand new out of the box, the VeriFone device must be registered (or re-registered)
to work with the First Data TransArmor solution.
The TransArmor registration process is included in the "Re-Initialize Hardware" option
from the Back Office Main Menu. Refer to the Xstore Point of Service Manager’s Guide for
procedural information.

Operational Assumptions
• Hardware must be a VeriFone device that is capable of supporting TransArmor
encryption.
• The VeriFone device must have the VeriShield Crypto Library (VCL) installed with a
key management methodology.
• The VeriFone device must be configured to allow Manual Key Entry on the Device.
• The MSR swipe on the POS Terminal must be disabled for Credit and Debit
transactions.
Credit Cards cannot be manually entered at the register. Xstore Point of Service will
force the customer to utilize the VeriFone Device for all Credit and Debit transactions.

Touch-Screen Keyboard Setup

Xstore Point of Service supports touch-screen mode, including a touch keyboard. This
keyboard provides the ability to type letters, numbers, and symbol characters into data
fields while using a touch-screen.

18-8 Technical Guide

 Touch-Screen Keyboard Setup

This keyboard takes the place of a physical keyboard, and will be accessible everywhere
within the Register and Back Office (including the store close procedure).
The keyboard is accessible via a button on the left side of the messages bar:

- Pressing the keyboard button slides the keyboard up from the bottom of
the screen.

- Pressing the keyboard button while the keyboard is visible slides the
keyboard down to hide it.

Note: While the primary use of the keyboard is in touch-screen

environments, it can also be used via a mouse click.

Keyboard Touch-Screen Functionality

The following touch functions are supported:
- Swiping up from the keyboard button region to launch the keyboard
- Swiping down when the keyboard is active to close the keyboard
- Tapping the keyboard button to launch the keyboard
- Tapping the keyboard button when the keyboard is active to close the keyboard
- Swiping left to switch to the next layout
- Swiping right to switch to the previous layout

Setting Up the Touch-Screen Keyboard

The touch-screen keyboard functionality can be enabled and configured by changing
SysConfig.xml and KeyboardConfig.xml as explained below.

SysConfig.xml Setup
<Setting name="OnScreenKeyboard---AutomaticCall">false</Setting>
<Setting name="OnScreenKeyboard---AutomaticCallDecimal">true</
Setting>
<Setting name="OnScreenKeyboard---Enabled">true</Setting>
<Setting name="OnScreenKeyboard---KeyClickEnabled">true</Setting>
Enabled - Determines whether the touch-screen keyboard is enabled.
- If true, the touch-screen keyboard is enabled.
- If false, the touch-screen keyboard is not enabled.
Layout - Determines the starting/default layout of the keyboard. Valid values: From
KeyboardConfig.xml
AutomaticCall - Determines whether Xstore Point of Service automatically displays
the keyboard when keyboard input is necessary. See “Overrides of the automatic call”.
- If true, Xstore Point of Service automatically displays the keyboard when
keyboard input is necessary.
- If false, the keyboard is not displayed automatically.

Hardware/UI Configuration 18-9

Touch-Screen Keyboard Setup

AutomaticCallDecimal - Determines whether Xstore Point of Service automatically

displays the decimal keyboard when decimal keyboard input is necessary. See
“Overrides of the automatic call”
- If true, Xstore Point of Service automatically displays the decimal keyboard
when decimal keyboard input is necessary.
- If false, the decimal keyboard is not displayed automatically.

Overrides of the automatic call

- To force the keyboard to pop up on a specific form/prompt, add the attribute
autoOnScreenKeyboard="true" to the prompt/form needed.
- To force the decimal keyboard to pop up on a specific form/prompt, add the
attribute autoOnScreenKeyboard="true" to the prompt/form needed.

KeyboardConfig.xml Setup
The KeyboardConfig.xml file is used to maintain the visual and functional aspect of
the keyboard. The file consists of definitions of one or more layouts, composed of
multiple panels containing rows of buttons.

Note: The KeyboardConfig.xml is only available for Classic Desktop

installations.

Example: Basic layout definition.

<Keyboard name="Virtual Keyboard" xmlns:xsi="http://www.w3.org/
2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="KeyboardConfig.xsd">
<layout name="qwerty">
<panel name="Auxiliary Panel">
<row>
<button keyStroke="."/>
<button keyStroke=","/>
<button keyStroke="-"/>
<button keyStroke="+"/>
</row>
<row>
...........................
</row>
<row>
<button background="_imgEnvironmentDefault"
backgroundPressed="_imgEnvironmentPressed"
keyAction="TOUCH::SHOW_ENVIRONMENT" horizontalSpan="true"/>
</row>
</panel>
To add a button that contains multiple characters use this syntax:

18-10 Technical Guide

 Touch-Screen Configuration

<button keyStroke=".COM" composite="true" />

Touch-Screen Configuration
The following touch-screen configurations are found in SysConfig.xml.
<Setting name="TouchConfiguration---EnableTapActionSound">false</
Setting>
<Setting name="TouchConfiguration---
StoreSwipeLoginToShowDashboard">false</Setting>
StoreSwipeLoginToShowDashboard - Set this configuration to true if the system
should prompt for authorization when a user swipes on the store name status cell before
invoking the dashboard.

Touch-Screen Configuration Desktop and Thin Client

There is a property available in the xstore.properties file -
xstore.electron.touchscreen.enabled. The Desktop and Thin Client may now only run
EITHER as touchscreen/virtual-on-screen-keyboard, OR with physical mouse/trackpad
and physical keyboard.
When xstore.electron.touchscreen.enabled=true,
• the UI will respond to actual screen touches.
• the UI will not respond to clicks from a physical mouse or trackpad.
• when the UI requires text or numeric input, it will pop-up an on screen keyboard.
When xstore.electron.touchscreen.enabled=false,
• the UI will not respond to any touchscreen input.
• the UI will respond to clicks from a physical mouse or trackpad.
• the UI will never pop-up an on screen keyboard; text or numeric entry must be
provided with a physical keyboard.

UI Orientation Setup
Xstore Point of Service supports the ability to easily configure the orientation of the focus
bar to support different environments such as a PC environment and a tablet
environment. With the majority of people being right-handed, a user will likely hold a
tablet with their left hand and enter data with their right hand. For this reason, you may
want to change the base, left-side UI orientation to put the focus bar, and the messages
area above it, on the right side of the screen.

Note: This configuration has no effect on systems using dual display.

This setting pertains to the display of Xstore Point of Service from a
user's perspective only.

Hardware/UI Configuration 18-11

Color Theme

Figure 18-2: LEFT Orientation Figure 18-3: RIGHT Orientation

The UI orientation can be set up in SysConfig.xml. Specify either LEFT (default value) or
RIGHT orientation in the UserInterface section: UIOrientation.

SysConfig.xml Setup
<Setting name="UserInterface---ShowKeyStrokeOnButton">false</
Setting>
<Setting name="UserInterface---TabletScreenRatio">AUTO</Setting>
<Setting name="UserInterface---UIOrientation">LEFT</Setting>

Color Theme
The default color theme for both Xstore Point of Service and Xstore Mobile Point of
Service is controlled by the SysConfig.xml setting UserInterface---ColorTheme.
Table 18-1 SysConfig.xml Settings

Setting Data Type Description

UserInterface--- CLASSIC:
ColorTheme Classic color theme where context-based
color applies to info tabs, prompt/form/
activity headers, focus bars, and so on.
MINIMAL:
Minimal color theme where context-based
color applies to main screen background
and everything else is one, static color.
Note: The classic theme uses bright,
primary colors while the minimal theme
uses a more subdued, modern, and
coordinated color palette.

Example:
<Setting name="UserInterface---ColorTheme">MINIMAL</Setting>

18-12 Technical Guide

 Xstore Point of Service Self Checkout Classic

Xstore Point of Service Self Checkout Classic

The following configuration options are available for the Xstore Point of Service Self-
Checkout (SCO) Classic.

OpChainConfig.xml
The following Self Checkout (SCO) configuration options are available in
<Xstore installation
directory>\lib\config.jar\selfcheckout\OpChainConfig.xml:
Table 18-2 OpChainConfig.xml SCO Settings

Setting Data Type Description

<OpChain Integer Configure the timeout in seconds to hold

name="PRINT_RECIP the screen before printing the receipt.
T">
The default value is 5.
<Parameter
name="TimeoutSeco
nds" value="5" />

Example:
<OpChain name="PRINT_RECIPT">
<Op
class="dtv.pos.register.selfcheckout.NotifyTransactionCompletedOp
">
<Parameter name="TimeoutSeconds" value="5" />
</Op>
<Op class="dtv.pos.hardware.op.PrintRcptsOp"
breakpoint="true" />
</OpChain>

SysConfig.xml Configuration
The following Self Checkout (SCO) configuration options are available:
Table 18-3 SysConfig.xml SCO Settings

Setting Data Type/Value Description

SelfCheckout Varchar Configure the employee ID for which all

EmployeeId transactions in Self Checkout mode are
saved.
The default value is 1.

EnableSelf Boolean Enables audio alerts to be played when

CheckoutAudioAler required.
ts
Audio file needs to be placed in
"config/res/audio/locale/en/
sample.file"
Configurable in config/config/
selfcheckout/ui.properties for
"_soundAction2"

ItemSale— Boolean Allows adding an item which is not on

AllowItemNotOn file to the cart with the help of a
File supervisor.

Hardware/UI Configuration 18-13

Xstore Point of Service Self Checkout Classic

Table 18-3 SysConfig.xml SCO Settings (continued)

Setting Data Type/Value Description

Email---Receipt— Boolean Sends the email receipt, based on the

SendEmailReceipts given value.

CommissionedAssoc False Must be set to false for the self check-out

iates—PromptFor mode.
Commissioned
Associates

PromptForCustomer Boolean Should always be true to support the

OnLogin prompt for the Loyalty scan.

SelfCheckout--- Boolean Prompts the user to enter the number of

PromptForBagsUsed bags used. If no bags are used, enter "0" in
the specified field.

PromptForLoyalty Boolean Prompts to the user to scan the loyalty

Scan card before starting the sale transaction.
Use the Skip button to skip scanning of
the loyalty card.

SupervisorOptionR Boolean System returns straight to the Sale screen,

eturnToSCOSale after an SCO supervisor action has been
completed.

SelfCheckout--- Integer The user can add the item ID for the
CarrierBagItemId carrier bag.

Example:
<SysConfig xmlns="http://micros.com/xstore/config/settings">
<Setting name="CommissionedAssociates---
DisplayPerItemOnSale">false</Setting>
<Setting name="CommissionedAssociates---
PromptForCommissionedAssociates">false</Setting>
<Setting name="Email---Receipt---AlwaysPromptToEmail">false</
Setting>
<Setting name="Email---Receipt---SendEmailReceipts">false</
Setting>
<Setting name="Help---HelpKey"></Setting>
<Setting name="ItemSale---AllowItemNotOnFile">true</Setting>
<Setting name="ItemSale---PromptUserForSaleCompletion">false</
Setting>
<Setting name="LocationBasedInventory---
QuantityUnavailableAction">ALLOW</Setting>
<Setting name="PromptForCustomerOnLogin">true</Setting>
<Setting name="SelfCheckout---CarrierBagItemId">1013</Setting>
<Setting name="SelfCheckout---PromptForBagsUsed">false</
Setting>
<Setting name="EnableSelfCheckoutAudioAlerts">false</Setting>

18-14 Technical Guide

 Xstore Point of Service Self Checkout

<Setting name="SelfCheckoutEmployeeId">1</Setting>
<Setting name="SaleEndingChain">REGISTER_SCO</Setting>
<Setting name="Terminal---MenuButtonCount">5</Setting>
<Setting name="UserInterface---UIOrientation">RIGHT</Setting>
<Setting name="PromptForLoyaltyScan">false</Setting>
</SysConfig>

Xstore Point of Service Self Checkout

This section contains configurations for the Xstore Point of Service Self Checkout
application.

Note: For more information about the Xstore Point of Service Self
Checkout, see the Oracle Retail Xstore Point of Service Self Checkout User
Guide and the Oracle Retail Xstore Suite Services Guide.

SysConfig.xml Configurations
The following configuration options are available:
Table 18-4 SysConfig.xml REST-based SCO Settings

Data Type/
Setting Value Description

SelfCheckout--- Varchar Configure the employee ID for which all

EmployeeId transactions in Self Checkout mode are
saved.
The default value is 1.

SelfCheckout--- When this configuration is set to true, the

DeferSerialNumberEntry self-checkout allows customers to add
serialized items to the transaction without
prompting for the serial number. But at
the checkout it will notify customers that
the sales associate will need to log in to
enter the serial number for the item,
before proceeding.
If set to false, it will prompt customers to
enter the serial number right away.

SelfCheckout--- If set to true, it suppress the signature

SuppressEftLinkSignature verify prompt in self-checkout.
VerifyPrompt

ItemSale--- Set this configuration to true to display

PromptUserForSaleComplet the Sale Complete dialog to the user.
ion
Note: Fore self checkout this value should
always be set to false.

Hardware/UI Configuration 18-15

Xstore Point of Service Self Checkout

Table 18-4 SysConfig.xml REST-based SCO Settings (continued)

Data Type/
Setting Value Description

SelfCheckout--- This setting presents or removes an

RemoveLastItemEnabled option on the self checkout customer sale
screen to remove the last item added to
the sale.
Note: This setting is used to remove the
last item added to the sale, for example, if
a customer accidentally adds wrong item
without an associate present. The setting
is only valid for the very last item that
was scanned and it cannot be used to
clear out a cart full of items.

SelfCheckout--- Used to configure the item ID for carrier

CarrierBagItemId bags, and when the PromptForBagsUsed
configuration is enabled.

SelfCheckout--- The number of seconds that the sale is

SaleCompleteMessageSecon complete message stays on the self
ds checkout screen before returning to the
start screen. A value of zero indicates that
such a message should not be shown.

SelfCheckout--- The number of seconds that a passive

PassiveNotificationSecon toast notification message stays on the
ds self checkout screen before disappearing.
A value of -1 will cause the message to
display until it is closed by the user. Any
other value should be greater than zero.

OpenClose--- true/false When the value of this configuration is set

PrintSystemCycleReceipts to true Xstore prints the system cycle
receipts at the store/workstation open and
close.

AutoPlaySound---Enabled true/false Determines whether or not the system

should automatically play a sound clip
after the idle time exceeds a configured
(WaitSeconds) number of seconds.

AutoPlaySound--- integer If auto play sound is enabled, the system

WaitSeconds automatically plays a sound clip after the
system idle time exceeds this number of
seconds.

CheckSaleComplete--- true/false Enables the use of a form to display the

UseSaleCompleteForm sale complete prompting at the end of a
sale.
If the flag is set to true, Xstore uses a form
as opposed to a prompt when displaying
the sale complete messages prompting for
receipt options

Receipts— true/false Existing configuration that is set to true

AllowReceiptNoPrint for Self Checkout.

18-16 Technical Guide

 Xstore Point of Service Self Checkout

TableLayoutConfig.xml
The TableLayoutConfig.xml file was created for use with the self checkout application.
Below find the XML schema for the TableLayoutConfig.xml file. This file is used to
define the layout for a collection of data whose content consists of records with a
homogeneous structure.
TableLayoutConfig.xsd:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns="http://micros.com/xstore/config/table"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:common="http://micros.com/xstore/config/common"
targetNamespace="http://micros.com/xstore/config/table"
jaxb:version="2.1"
attributeFormDefault="unqualified"
elementFormDefault="qualified">
<xs:element name="TableLayoutSet">
<xs:complexType>
<xs:sequence>
<xs:element name="TableLayout" type="TableLayout_Type"
maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name="TableLayout_Type">
<xs:sequence>
<xs:element name="Column" type="TableLayoutColumn_Type"
maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="name" type="xs:string" />
<xs:attribute name="targetClass" type="xs:string" />
</xs:complexType>
<xs:complexType name="TableLayoutColumn_Type">
<xs:attribute name="headerText" type="xs:string" />
<xs:attribute name="id" type="xs:string" use="required" />
<xs:attribute name="value" type="xs:string" />
<xs:attribute name="formatterRef" type="xs:string" />
<xs:attribute name="width" type="xs:int" />
<xs:attribute name="resizable" type="xs:boolean" />

Hardware/UI Configuration 18-17

Xstore Point of Service Self Checkout

</xs:complexType>
</xs:schema>
Some things to note:
• The "targetClass" attribute that is defined in the table layout serves for visibility and
acknowledgment. Xstore will check and issue a warning if the class of the data
objects is not an instance of the target class for the layout, but it will not fail straight
away if the type of object does not match the targetClass.
• "headerText" is the test that is intended to be used to label the column in the table.
• "id" provides a unique identifier for the column within the table.
• If there is a "value" expression (a method chain), then the system will use that.
Otherwise, it assumes that the "id" attribute represents the value and that there is a
bean-style getter for it on the model class that is being used for the table's data.
• "formatterRef" is a name reference to a standard Xstore formatter to use to format
the data in this column.
• "width" is the intended width of the column in the table, specified as a percentage of
100 (without the percent sign).
• "resizable" indicates if the column that is identified should be able to be resized in
the table that is rendered from this configuration.
Below is a sample of a TableLayoutConfig.xml file.
TableLayoutConfig.xml Sample:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TableLayoutSet xmlns="http://micros.com/xstore/config/table">
<TableLayout name="REASON_CODES"
targetClass="dtv.xst.dao.com.IReasonCode">
<Column headerText="_selectAnOption" id="Description"
formatterRef="Text" width="100" />
</TableLayout>
<TableLayout name="DISCOUNTS"
targetClass="dtv.xst.cleandto.dsc.Discount">
<Column headerText="_selectAnOption" id="Description"
formatterRef="Text" width="100" />
</TableLayout>
<TableLayout name="PRICE_MODIFIERS"
targetClass="dtv.xst.dao.trl.IRetailPriceModifier">
<Column headerText="_selectAnOption" id="Description"
formatterRef="Text" width="100" />
</TableLayout>
<TableLayout name="REPRINT_RECEIPT_SELECTION_LIST"
targetClass="dtv.pos.register.reprint.ReceiptReportModel">
<Column headerText="_receipts" id="DisplayName" width="100"
formatterRef="Text" />
</TableLayout>

18-18 Technical Guide

 Xstore Point of Service Self Checkout

<TableLayout name="TENDERS_TO_VOID"
targetClass="dtv.xst.dao.ttr.ITenderLineItem">
<Column headerText="_scoTenderType" id="TenderDescription"
formatterRef="Text" width="80" />
<Column headerText="_amount" id="Amount" formatterRef="Money"
width="20" />
</TableLayout>
<TableLayout name="COUPON_NOT_APPLIED"
targetClass="dtv.pos.coupon.CouponResult">
<Column headerText="_couponId" id="CouponId" width="20" />
<Column headerText="_commonDescription" id="Description"
width="80" />
</TableLayout>
<TableLayout name="SUSPENDED_TRANSACTIONS"
targetClass="dtv.xst.query.results.SuspendedTransSearchResult">
<Column headerText="_suspendTicket" id="TransactionSequence"
width="15" />
<Column headerText="_suspendRegisterId" id="WorkstationId"
width="15" />
<Column headerText="_suspendTranStartTime"
id="TransStartTime" formatterRef="TimeShort" width="10" />
<Column headerText="_selectcustomername"
id="CustomerDisplayName" formatterRef="Text" width="25" />
<Column headerText="_scoResumeTransItemCount" id="ItemCount"
formatterRef="Decimal" width="15" />
<Column headerText="_scoResumeTransTotal"
id="TransactionTotal" formatterRef="Money" width="20" />
</TableLayout>
</TableLayoutSet>

Styling and CSS Customization

The self checkout application is written using Oracle Javascript Extension Toolkit, or JET.
At its heart, it is a web application and, as such, it has many characteristics of a web
application. One of those characteristics is that almost all of the appearance of the self
checkout application is governed by CSS. Out of the box, the self checkout application
has a fully-realized color palette that is based on Oracle's corporate standards. In
addition to this, the JET-based self checkout application provides a new way of
customizing the application. For the most part, this involves being able to change the
general color palette to meet a retailer's needs by modifying a collection of CSS variables
to achieve the desired result.
To customize the application, you must obtain the sco-app-custom.css file from inside of
the self checkout application's WAR file. This file contains all of the CSS variables that
may be changed along with some brief descriptions of what the variables affect. At this
point, the changes are limited to colors. There are some general rules to the variable
names that were adopted from the way that JET names CSS variables.

Hardware/UI Configuration 18-19

Xstore Point of Service Self Checkout

• If the CSS variable name ends with "rgb", this means that the value of the variable
must be expressed in a comma-separated set of red, green, and blue values from 0 to
255. For example, a valid value for the variable name --sco-bg-sale-summary-rgb
would be 123, 74, 201. Changing the variable to that value would result in a shade of
purple for the sale summary section of the main shopping cart screen.
• If the CSS variable name does not end in "rgb", then you are expected to provide an
actual color object for the value. This can be obtained by the using the rgb() function
in the value definition. There are several examples of this within the sco-app-
custom.css file, but one that would make the general background of the application a
bright green would be:
--oj-body-bg-color: rgb(91, 238, 88);
One final point to note is the existence of the CSS selector .oj-color-invert. There are
certain places in the base application that have a dark background by nature. Any place
that a dark background is used in the base application, the colors are "inverted" using
this style selector. What this means is that, if you would like to change the color of
something that shows on a dark background in the base application, then you are going
to need to define the CSS variable for it within the selector .oj-color-invert. The variables
for things that support having their color inverted in the custom CSS are listed within
the file already. The same rules for naming and value specification for the standard
variables apply to the values specified within .oj-color-invert as well.
Once you have changed the values of all of the CSS variables in the sco-app-custom.css
file to your liking, then the self checkout application must load.
Take your customized sco-app-custom.css file and place it in your customer overlay
project in the res/sco-static/styles directory. When the overlay project and the
corresponding installer are built, the sco-app-custom.css file should end up in the res/
sco-static/styles directory in the Xstore Point of Service Mobile install directory. Special
instructions that are in place for self checkout will cause this file to be loaded in
preference over the base file and your customization will be applied.

Audio Files
Sound bite prompts assist customers withe the self checkout process.

Note: There may be additional accessibility requirements with use of

audio. Refer to your company policies for additional guidance.

Sound resource files are used to define the sound file to play, allowing for different
sound files based on locale to be defined as well. Supported audio file types are .wav,
.mp3, and .ogg. The audio files are located in the folder where the Mobile Server is
installed.
The soundKey gives indicates where the sound plays within the SCO application:
_scoStartSaleWelcome = When starting a new transaction by either scanning loyalty,
scanning an item, pressing one of the "Start" buttons, or by using help and selecting a
language
_scoAssistanceNeeded = When the Assistance button is pressed.
_scoTenderMenu = When the tender selection screen displays
_scoSaleCompleteThankYou = When the transaction is finished and the Done screen
displays

18-20 Technical Guide

 Xstore Point of Service Self Checkout

_scoAttentionRequired = When pressing Finish and Pay and there are items that require
attentions for such things like age restrictions, serial number entry, warranty
requirements, etc...
_scoVoucherTender = When the gift card tender is selected and it is not configured to use
EftLink
_scoEftlinkTender = When a tender is selected that uses EftLink
_scoContinueSuggestion = When a transaction is in process and an item has been
scanned, after a configurable wait time, sound will play
Example Files:
sounds.properties
_scoStartSaleWelcome=res/audio/startSaleWelcome1.mp3
_scoAssistanceNeeded=res/audio/assistanceNeeded1.mp3
_scoTenderMenu=res/audio/tenderMenu1.mp3
_scoSaleCompleteThankYou=res/audio/saleCompleteThankYou1.mp3
_scoAttentionRequired=res/audio/attentionRequired1.mp3
_scoVoucherTender=res/audio/voucherTender1.mp3
_scoEftlinkTender=res/audio/eftlinkTender1.mp3
_scoContinueSuggestion=res/audio/continueSuggestion1.mp3

sounds_fr.properties
_scoStartSaleWelcome=res/audio/startSaleWelcome2.mp3
_scoAssistanceNeeded=res/audio/assistanceNeeded2.mp3
_scoTenderMenu=res/audio/tenderMenu2.mp3
_scoSaleCompleteThankYou=res/audio/saleCompleteThankYou2.mp3
_scoAttentionRequired=res/audio/attentionRequired2.mp3
_scoVoucherTender=res/audio/voucherTender2.mp3
_scoEftlinkTender=res/audio/eftlinkTender2.mp3
_scoContinueSuggestion=res/audio/continueSuggestion2.mp3

Start Button
Xstore Point of Service Self Checkout allows for an icon to be included in the Start
button, for example, to identify the country with a flag to distinguish the various
language options on the home screen.

PromptConfig.xml
The <Prompt> tag showButtonImages determines if images are displayed on the buttons.
Example PromptConfig.xml
<Prompt name="SELF_CHECKOUT_START_SALE_MAIN" type="Notify"
title="_scoActivateSelfCheckoutTitle" message="_startViewMessage"
secondary_message="_scoHomeScreenSecondaryMessage"

Hardware/UI Configuration 18-21

Xstore Point of Service Self Checkout

textColorRef="_colorPromptTextScoHome" modal="false"
showButtonImages="true">
<IconGroup logo="_imageScoHomeLogo"
background="_imageScoHomeBackground" />
<Action ref="SELF_CHECKOUT::ASSOCIATE_LOGIN_SPECIAL" />
<Action ref="SELF_CHECKOUT::ASSOCIATE_HELP_SPECIAL" />
<Action ref="SELF_CHECKOUT::CHANGE_LANGUAGE_AND_START_SALE" /
>
<Action ref="SELF_CHECKOUT::START_SALE" primary="true" />
<Action ref="SELF_CHECKOUT::START_SALE_FR_FR" primary="true"
/>
<Action ref="SELF_CHECKOUT::START_SALE_ES_ES" primary="true"
/>
</Prompt>

ActionConfig.xml
If the <Prompt> tag showButtonImages in the PromptConfig.xml is set to true, then you
also need to supply an image to be shown, or supply a predefined Redwood icon name
by including an <IconGroup> tag to the action for the start buttons.
Specifying an icon value of "_imageScoStartUS" references a ui.properties entry that
references an image that resides on the server and is retrieved by the client application.
Specifying an icon value of "oj-ux-ico-flag-checkered" references a predefined Oracle
Redwood icon that comes with the client application.
Exmaple ActionConifg.xml
<Action name="SELF_CHECKOUT::START_SALE_EN_US"
ref="SELF_CHECKOUT::START_SALE">
<IconGroup icon="_imageScoStartUS" />
<Parameter name="Locale" value="en_US" />
</Action>

<Action name="SELF_CHECKOUT::START_SALE_EN_US"
ref="SELF_CHECKOUT::START_SALE">
<IconGroup icon="oj-ux-ico-flag-checkered" />
<Parameter name="Locale" value="en_US" />
</Action>

ui.properties
Images can be located on the Mobile Server file system in the same folder as the Mobile
Server.
Example:
_imageScoStartExample=res/graphics/NewImage.png

18-22 Technical Guide

 Xstore Point of Service Self Checkout

Self Checkout Console

This section describes the Self Checkout (SCO) Console.

How to Access
The Self Checkout Console can be accessed by any supported browser, as long as the
machine running the browser is on the store LAN with sufficient access to an Xstore
Mobile Server running in a store.
The URL depends on the hostname and port of the Xstore Mobile server:
https://{hostname}:{port}/xstorescoconsole
If a store has multiple Xstore Mobile Servers, you can connect to any server. The Self
Checkout Console application provides access to the status of all Self Checkout registers
in the store, regardless of which Self Checkout registers are connected to which servers.

Security
The Self Checkout Console completely relies on Xstore's authentication database and
permissions system, as configured in each store.
Users can log in to the Self Checkout Console and/or issue commands from the Self
Checkout Console, using their regular Xstore store credentials, provided they have the
necessary permissions configured.

Self Checkout Console Permissions

SCO_MGMT_CONSOLE_ADMIN
This is one of two permissions in Xstore specifically related to the Self Checkout Console.
Users must be associated to this privilege in order to log on to the Self Checkout Console.
This permission is also required to issue a Pause command from the Console. The
application does not re-prompt for credentials when issuing a PAUSE command; simply
being logged-in to the console is sufficient.

UNPAUSE_SELF_CHECKOUT
When the Self Checkout Console issues a Pause command to a Self Checkout
Workstation, the workstation is placed in a paused state and an employee is required to
enter their credentials to allow the workstation to continue. The employee must have
this new privilege in order to allow the workstation to continue. If they do not have this
privilege, the workstation will remain paused until an employee who does have this
privilege enters their credentials.

Note: This privilege has no effect on the Self Checkout Console itself;
however, it affects Self Checkout workstations that have been paused
by the Self Checkout Console.

ACTIVATE_SELF_CHECKOUT
This permission is required when attempting to Activate or Deactivate a Self Checkout
workstation, regardless of whether the activating/deactivating is being performed
directly on the Self Checkout register, or from the Self Checkout Console via its Activate
and Deactivate commands.

Hardware/UI Configuration 18-23

Xstore Point of Service Self Checkout

TILL_MANAGEMENT
This permission has long been a part of Xstore and is required when performing a
register open or register close operation for any Xstore POS system.
This permission is required regardless of whether the register open/close is being
performed directly on the Self Checkout register, or from the Self Checkout Console via
its Activate and Close commands.

Self Checkout Console's Activate Command

The Self Checkout Console's Activate command performs a combination of Open (if not
already open) and Activate.
When issuing an Activate command from the Self Checkout Console to multiple Self
Checkout registers, if any of the registers are closed, then the user issuing the command
must have both ACTIVATE_SELF_CHECKOUT and TILL_MANAGEMENT permissions, or
else the command request will be rejected.
However, if all of the targeted registers are open, the issuing user only needs the
ACTIVATE_SELF_CHECKOUT permission, since no register open functionality needs to
run.

Open/Close Commands vs. Xstore's TRN_TRANSACTION

On any Xstore POS, including a Self Checkout register, the Open and Close operations
typically produce a standard Xstore transaction record (that is, the TRN_* tables in the
Xstore database).
The Self Checkout Console's Activate, which opens a Self Checkout register if it is not
already opened, and Close command directs each targeted Self Checkout workstation to
run its usual op-chain to perform that function.

Note: The TRN_* transactions resulting from commands sent from

the Self Checkout Console are appropriately stamped with the ID of
the employee who issued the command from the Self Checkout
Console.

Configurations
Most configuration of the Self Checkout Console is controlled via Xstore's system
properties.
The properties can be found in xstore_mobile.properties.

Self Checkout Console Auto-Logout Minutes

xstore.puma.autologout.minutes=15
After a user logs in to the Self Checkout Console, if there is no user-input detected in the
user interface, for example, mouse-movements, clicks, touches, scrolling, key-presses,
and so on, then the user will automatically be logged out after the configured number of
minutes.

Prompt for Credentials on Each Command

xstore.puma.promptForCredentialsEachCommand=true
It may be common in an actual retail store setting to have a Self Checkout Console app
up and running on a terminal that might be unattended on the store floor.

18-24 Technical Guide

 Xstore Point of Service Self Checkout

By default, the Self Checkout Console is configured to always prompt the user to enter
their Xstore employee credentials each time they issue any command from the Console
(Open/Activate, Deactivate, Close). When prompted for credentials, the employee ID
and password does not need to match the logged-in user of the Self Checkout Console.
Any employee can issue a command from a running Self Checkout Console using their
own credentials.
This ensures that any command can only be issued by users with sufficient privileges. It
also allows the convenience of having a low-privilege user log-in to the Self Checkout
Console to see status, but require that only higher-privileged users may issue commands
to alter the state of Self Checkout registers.
If this configuration is disabled, then the Self Checkout Console will not prompt for
credentials. Instead, the logged-in user's privileges must be sufficient to issue any
commands.

Expiration Threshold for Expired Workstation Status

xstore.cluster.delete.expired.wkstnstatus.hours=24
This configuration determines the threshold, in hours, of considering a workstation as
being expired. Once expired, workstation status data can be eliminated from the Xstore
Mobile server(s).
This does not imply that the data will be eliminated as soon as the time period elapses.
Status data for all Self Checkout workstations is only checked for expiration when any
Xstore Mobile Server (re)starts. If the last-updated timestamp is older than the
configured hours, the status data for that workstation will be eliminated from all Xstore
Mobile Servers.
When workstation status data is removed from the server(s), this also does not imply
that those workstations will automatically be removed from any actively logged-in Self
Checkout Console UI. Removed workstations will only be removed from the UIs after
the user reloads the Self Checkout application (that is, hits reload in the browser).

Self Checkout Console Customization

Images
There are three images that are customizable in the SCO Console application. Two are on
the login screen and one is in the header section of the main screen. The location and
names of the images are defined in the ui.properties file. By default, after installation,
these images are defined as follows:
_imageScoConsoleLogo=classpath:graphics/selfcheckout/logo-oracle-
white.svg
_imageScoConsoleHomeBackground=classpath:graphics/selfcheckout/
image-start-screen-x2.jpg
_imageScoConsoleHeaderLogo=classpath:graphics/selfcheckout/
oracle-o-48.svg
To customize these images, change these values as follows:
_imageScoConsoleLogo=res/graphics/selfcheckout/my-logo.png
_imageScoConsoleHomeBackground=res/graphics/selfcheckout/my-
background.jpg
_imageScoConsoleHeaderLogo=res/graphics/selfcheckout/my-header-
logo.svg

Hardware/UI Configuration 18-25

Xstore Point of Service Self Checkout

Note the change in the beginning of the file path from classpath:graphics to
res/graphics. This is a required change. The custom images themselves should be
placed in the res/graphics/selfcheckout directory.
These values correspond to:
The Oracle logo on the login screen
The background image on the login screen
The Oracle "O" logo in the header section on the main screen

Translations
Text translations for the Self Checkout Console application are handled per Xstore's
current process. The translations can be found in the same file used for the Self Checkout
register application, which is located in config/formfactor/selfcheckout/
translations.properties.

18-26 Technical Guide

 19
ZPL II Label Configuration

Overview
Note: Only the IP-based printer is supported! USB printers are not
supported.

Xstore Point of Service supports ZPL II (Zebra Programming Language) for

communicating with label printers. Using ZPL II communication, it is possible to use
either a pre-defined stock type associated with an item, or to select the stock type to print
on.
Other features include saving and printing label batches, support for multiple label
types, and support for printing an alternate UPC barcode rather than a standard barcode
via an item property flag (Manufacturers UPC instead of the SKU).

Functional Assumptions
• Xstore Point of Service will prompt for the stock to be used if the item does not have
one defined.
• If an item has a default stock-type associated with it, it will bypass the option of
selecting the stock to print, but will allow the user to override the default setting.
• The customer is responsible for loading stock-type information associated with the
items into the Xstore Point of Service and Xstore Office database.
• It is the user's responsibility to load the appropriate stock into the printer, Xstore
Point of Service will not be checking for correct stock before printing.
• There is no mechanism to mark items that have had tickets printed, or to prevent
printing duplicate tickets.
• Existing validation for item entry will be used.
• Any stock type (that the printer can hold) can be used by updating the
LabelConfig.xml file accordingly. The following label sizes have been configured
in base: 1"x1" Label, 2"x1" Label, ¾"x½" Barbell Label, and2"x1¾" Rat Tail Label

Supported Printers
Note: Only the IP-based printer is supported! USB printers are not
supported.

• Any printer that supports ZPL II

ZPL II Label Configuration 19-1

Fields and Layout

Fields and Layout

All configuration information regarding fields and layouts are stored in an XML
formatted file. (See “Fields and Layout: XML Configuration File”).

Fields available for printing

Field table: field Method

Vendor ID itm_vendor: vendor_id getItem.getVendorId

Vendor Name itm_vendor: name getItem.getVendor.getName

Dept itm_merch_hierachy: getDepartmentDescription

description

Subdept itm_merch_hierachy: getSubdepartmentDescription

description

Class itm_merch_hierachy: getClassDescription

description

Subclass itm_merch_hierachy: getSubclassDescription

description

List price itm_item_prices: price getOriginalShelfPrice or

getShelfPrice (if price wasn’t
manually overridden in the label screen)

Current sales price getShelfPrice

(This will be the
price that can be
manually adjusted
from the Label
entry page).

Description of item itm_item: description getItem.getDescription

Item # itm_item: item_id getItem.getItemId

Part # itm_item: part_number getItem.getPartNumber

Vendor Item # itm_item_cross_reference: getItemUpc

manufacturer_upc

Color, Size, Width itm_item_dimension table getItem.getItemDimensions.ge

tDimension1
getItem.getItemDimensions.ge
tDimension2
getItem.getItemDimensions.ge
tDimension3

19-2 Technical Guide

 Fields and Layout

Field (continued) table: field Method

Primary UPC itm_item_cross_reference: getItemUpcOrItemId

manufacturer_upc
In order to get the item ID or
manufacturer upc according to the
manufacturer upc flag in the
itm_item_cross_reference table use
method: getItemUpcOrItemId
If there are multiples, this will use the
Primary Flag to decide which one to use.

Today's Date getTodaysDate

[Format of MM/
DD/YYYY]

Style Number getItem.getParentItemId

Base pre-defined templates

1x1 Standard 1x1 Sale

1x1 Was/Now
1x1 Inventory

ZPL II Label Configuration 19-3

Fields and Layout

2x1 Standard 2x1 Sale

2x1 Inventory 2x1 Was/Now

Barbell Standard
Rat Tail Standard

Barbell Sale

19-4 Technical Guide

 XML Configuration Files

XML Configuration Files

The following xml configuration files must be set up for ZPL II functionality:
SysConfig.xml and HardwareConfig.xml.

SysConfig.xml
This configuration option determines if the Save Batch prompt is displayed after each
printing session.
<Setting name="ShelfLabelsItemTags---SaveBatchPrompt">false</
Setting>
• true = The Save Batch prompt is displayed after labels are printed.
• false = The Save Batch prompt is not displayed after labels are printed.
Base Default Value = false

HardwareConfig.xml
The following section must be present in the HardwareConfig.xml file to enable ZPL
II. If this section is not found in the file, the process flow using a report printer for labels
will be used.
Substitute values as needed for your organization.
<Device type="LabelPrinter" use="LABELS">
<name dtype="String">IpZplLabelPrinter</name>
<RemoteHost dtype="String"><IP ADDRESS></RemoteHost>
<RemotePort dtype="Integer"><PORT></RemotePort>
</Device> -->

Database Tables
The following database tables support ZPL II functionality:
• itm_item_label_batch
• itm_item_label_properties
For information about these tables and the Dataloader record used to populate it, see the
Xstore Point of Service Database Dictionary and the Xstore Point of Service Host
Interface Guide.

ZPL II Label Configuration 19-5

Fields and Layout: XML Configuration File

Fields and Layout: XML Configuration File

The LabelConfig.xml file contains all the label configurations. This file is used to
configure the display of labels for the ZPL printers, and is similar to the
RcptConfig.xml file which is used to configure the receipts.
All dimensions are in pixels. Depending on the printer, 1 inch = 200 dots (if printer's
resolution is 200 dots per inch). The upper left corner of a label is 0, 0. The bottom right is
[width], [height].

Note: X value is along the horizontal axis (i.e. starting point left to
right) and Y value is the vertical axis (i.e. starting point top to bottom)

LabelConfig.xml
<?xml version="1.0" encoding="UTF-8"?>
<LabelSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="LabelConfig.xsd">
<FormatterMap>
<Formatter name="Money"
class="dtv.pos.i18n.format.MoneyFormatter"/>
<Formatter name="DateShort"
class="dtv.pos.i18n.format.DateFormatter"
formatterType="DateShort"/>
<Formatter name="DateMedium"
class="dtv.pos.i18n.format.DateFormatter"
formatterType="DateMedium"/>
<Formatter name="DateTimeMedium"
class="dtv.pos.i18n.format.DateFormatter"
formatterType="DateTimeMedium"/>
</FormatterMap>
<!-- Available printer fonts A-Z, 0-9 -->
<FontMap>
<LabelFont name="AXSmall" font="A" height="9" width="5"/>
<LabelFont name="0Small" font="0" height="20" width="14"/>
<LabelFont name="0XSmall" font="0" height="15" width="10"/>
<LabelFont name="XMedium" font="0" height="25" width="20"/>
<LabelFont name="Medium" font="0" height="30" width="25"/>
<LabelFont name="Large" font="0" height="50" width="25"/>
<LabelFont name="Xlarge" font="0" height="50" width="40"/>
</FontMap>
<label name="1x1-Standard" width="200" height="200"
font="XMedium">
<field x="5" y="15" width="190" height="70"
method="getItem.getDescription" align="C" font="Medium"/>

19-6 Technical Guide

 Fields and Layout: XML Configuration File

<field x="15" y="80" width="190" height="30"

method="getItem.getParentItemId" align="C"/>
<field x="15" y="100" width="100" height="30"
method="getItem" align="C">
<aggregate
class="dtv.pos.reporting.label.SizeWidthAggregateField"/>
</field>
<field x="115" y="100" width="85" height="30"
method="getShelfPrice" formatter="Money" align="C"/>
<field x="15" y="170" width="170" height="30"
method="getItem.getItemId" type="BARCODE" symbology="Code 93"
barcodeHeight="40"/>
<field x="15" y="180" width="185" height="30"
method="getItem.getItemId" align="C" font="Medium"/>
</label>
...............edited for brevity
</LabelSet>
LabelSet - The root of LabelConfig can have two optional children: FormatterMap and
FontMap; and multiple Label children. (At least one is required).
FormatterMap - A map of formatters that are used in the file to format data for display
purposes.

Child Min occurs Max occurs

Formatter 1 Unbounded

Formatter - A FormatterMap can have multiple Formatter children. A Formatter must

have a name and an implementation class. The formatterType attribute is optional. Any
formatter in RcptConfig can be used in the same manner here.

Attribute Required Description

name true Formatter name to be referenced across the file.

class true Formatter implementing class. (See RcptConfig.xml for

examples).

formatterType false Formatter type. (See FormatterType class).

FontMap - a map of fonts that are used in the file to display data.

Child Min occurs Max occurs

LabelFont 1 Unbounded

ZPL II Label Configuration 19-7

Fields and Layout: XML Configuration File

LabelFont - A font used across the file. The current version is ZPL specific. The fonts in
ZPL are named from A-Z and from 0 to 9.

Attribute Required Description

name true Font name to be referenced across the file.

font true ZPL font name. A-Z, 0-9. For more information about fonts,
refer to the ZPL Manual.

width true Font width. Some fonts might not respond to some values.

height true Font height. Some fonts might not respond to some values.

label - A single label configuration, or it may be called a template. A label will get a
source object and will be evaluated against it. A label must have at least one Field child.

Child Min occurs Max occurs

Field 1 Unbounded

Attribute Required Description

name true Label name that will be referenced from an item. Label
names should be unique.

font false References a previously declared font from the FontMap.

width false Label width.

height false Label height.

x false X location of upper left corner.

y false Y location of upper left corner

field - A field can get the source object from a label and evaluate against it.

Child Min occurs Max occurs

aggregate 0 1

line 0 1

Attribute Required Description

name false Field name.

value false Field value. Can be a literal or a translation.

method false A method that evaluates against the received source object.

formatter false A formatter to format the evaluated value.

font false A font reference. If not used the font from the label is used.

19-8 Technical Guide

 Fields and Layout: XML Configuration File

Attribute Required Description (continued)

width false Field width.

height false Field height.

x false X location of upper left corner.

y false Y location of upper left corner.

symbology false The symbology to be used with the barcode.

barcodeHeight false The height of the barcode. For more information, refer to the
ZPL Manual.

barcodeWidth false The width of the barcode. For more information, refer to the
ZPL Manual.

barcodeRatio false The ratio wide to narrow bar. 2.0 to 3.0 with 0.1 increments.
For more information, refer to the ZPL Manual.

align false Text alignment. Note that x, y, width, and height values
create a rectangle. The text is aligned in that rectangle. Also
note that barcodes do not center. You have to manually set
the x and y.

type false To indicate that the field is a barcode use type="BARCODE";

image - type = "Image"

aggregate - A class that takes the source object and does some predefined
manipulation with it, and then returns a string value.

Attribute Required Description

class true Class to manipulate the object.

line - Added as a workaround for the requirement to do a strike-through.

Attribute Required Description

orientation true Line orientation. H or V.

length true Line length.

x true X location of line start.

y true Y location of line start.

ZPL II Label Configuration 19-9

Fields and Layout: XML Configuration File

19-10 Technical Guide

 20
Store Sales Goals Setup

Overview
Sales goals for a store can be imported into Xstore Point of Service where they can be
viewed by employees. Goal progress can be viewed on the Goals tab, on the Dashboard,
and on the Store Goals Report.

Note: All goals are for individual stores, even if multiple stores are
included. For example, if a goal is $20k, that is the goal for each store
selected, it is not a collective goal.

Store sales goals are tracking Xstore Point of Service data only. No external data will be
looked at for this functionality.
The “Sales” value used in any calculations refers to Net Sales (total sales excluding tax),
not profits. If VAT is included in the price, then VAT is treated as part of the sales goal.
Goal status (% To Date) is based on the effective and/or end dates of the goal:
- “Completed” = today’s date > End Date
- “Completed, Met” = today’s date > End Date AND % to Goal >= 100
- “Completed, Not Met” = today’s date > End Date AND % to Goal < 100
- “Active” = today’s date is within the Effective Date and End Date range
- “Future” = today’s date < Effective Date
Completed goals are displayed based on the number of Completed Goals
(NumberCpltGoalsToDisplay) then all Active Goals are displayed, followed by any
Future Goals based on the number of future goals (NumberFutureGoalsToDisplay).

Store Sales Goals Setup 20-1

Store Goals Tab

Store Goals Tab

The goals are color-coded based on the following criteria:

- GREEN for goals completed and met
- RED for goals completed but not met
- Black for active/current and future goals
In addition, future goals display “N/A” in the %To Date column

Dashboard Store Goals Performance

On the Dashboard, only active goals are displayed. The goals are sorted by ascending
end date, ascending effective date, and then description. Five is the maximum number of
goals that can display in the table. If there are more than five active goals, the first five
goals are displayed based on the sorting rules defined above.

Sales Goals Report

Report filters include Status (All [default], Active, Completed, Completed-Met,
Completed-Not Met, Future) and Date Range. Goals are grouped by status, and within
each status they are sorted by Ascending End Date, Ascending Effective Date, and then
Description. Refer to the Xstore Point of Service Reports Guide for more information.

20-2 Technical Guide

 Configuration Options

Configuration Options
SysConfig.xml
There are two SysConfig.xml configuration options for Store Sales Goals:
<Setting name="SalesGoal---NumberCpltGoalsToDisplay">2</Setting>
<Setting name="SalesGoal---NumberFutureGoalsToDisplay">2</
Setting>
NumberFutureGoalsToDisplay - This is the number of goals that have not yet
started that will be displayed in the Xstore Point of Service Goals Tab. These goals are
displayed in ascending end date order, so the future goals with the earliest start date will
be displayed first.
NumberCpltGoalsToDisplay - This is the number of goals that are completed that
will be displayed in the Xstore Point of Service Goals Tab. The most recently completed
goals are displayed in ascending end date order.

Database Tables
The sls_sales_goal table contains the data for store goals information. For more
information about this table, refer to the Xstore Point of Service Database Dictionary and the
Xstore Point of Service Host Interface Guide.

Store Sales Goals Setup 20-3

Database Tables

20-4 Technical Guide

 21
Store Replenishment Orders

Overview
Store Replenishment Order management provides the ability for stores to review and
change inventory replenishment suggested orders that are generated and downloaded
from the home office or a third-party system. Stores may also prepare new inventory
replenishment and purchase order requests. The suggested order, replenishment
receiving document, and confirmations are communicated to Xstore Point of Service
using DataLoader.

Order Status
• When a suggested order is received in Xstore Point of Service, the status will be set
to "Open", and the created field will be "HOME_OFFICE". Processing is the same
functionality as a new or "Open" request created in Xstore Point of Service.
• The Corporate System may send down a Push Order that has no Open or Submitted
order status. When Xstore Point of Service receives the Push Order, the status of the
document will be "Confirmed" and the document line items will have a confirmed
quantity.
• Only items on OPEN orders may be voided. Items on already confirmed orders
cannot be voided.

Document Status
Document status is generally controlled by the Corporate System. The following list
shows document status as it relates to the item details.
• Open - Indicates the document is open and all items are considered open at this
point.
• Submitted - Indicates the document has been submitted and all items are also
considered submitted.
• Confirmed - Indicates the document has been confirmed by the Corporate System
and all the items on the document have been updated with a confirmed quantity. A
confirmed item quantity of zero is valid, and indicates that no merchandise will be
received at the store for that line item.

Note: The document may be “partially confirmed” (for example,

when an order is split into two fulfillment shipments). In this case, the
document status will remain “Submitted” until all line items have been
confirmed for the order. Once all line items have been confirmed, the
Corporate System will mark the document as “Confirmed.”

Store Replenishment Orders 21-1

Replenishment Order Setup Process

• Partially Received - Indicates at least one item on the document has been received,
but not all items.
• Cancelled - Indicates an order has been cancelled by the host or corporate system.
• Closed - Indicates the document is considered closed and all line items have been
received for the order.

Note: A confirmed item quantity of zero is valid. When receiving and

updating the order status, Xstore Point of Service must account for
items with a confirmed quantity of zero. These items must be
considered as closed (or the same as fully received) or they must be
excluded when closing the document.

Line item status

Line item status can be any of the statuses listed below, and can also be indicated by the
quantity field for a particular document status.
• Suggested lines - For corporate-created open documents, these lines will have the
status OPEN and will show suggested quantities.
• Open lines - These lines will have the status OPEN and will show requested
quantities.
• Closed lines - These lines will have the status CLOSED and will show received
quantities.
• Confirmed lines - These lines will have the status CONFIRMED and will show
confirmed and shipped quantities. Zero is a valid confirmed quantity and is used for
items that will not be filled or shipped to the store.
• Submitted lines - These lines will have the status SUBMITTED.

Replenishment Order Setup Process

The process required to set up replenishment order functionality, and a link to each
section for more information, when applicable, is provided below:
1. Set the itm_item. ITEM_AVAILABILITY_CODE to "AVAILABLE" for each item
that may be used on an order inventory document (“Item Database Setup” in
Chapter 5, “Item and Pricing Configuration”).
2. Set up replenishment order database tables (“Database Setup”).
3. Set up replenishment order configuration options in SysConfig.xml (“System Config
Setup”).
4. If applicable, set up non merchandise items for replenishment (“Non Merchandise
Item Setup”).
5. If using pack size for ordering quantities, populate itm_item.pack_size (“Item
Database Setup” in Chapter 5, “Item and Pricing Configuration” and “To Use Pack
Size for Item Ordering”).
6. Verify your system is set up for searching for replenishment documents by source
entity (“To Search For Replenishment Documents By Source Entity”).
7. Verify your system is set up to display the source of an item (“To Display The Source
Of an Item”).

21-2 Technical Guide

 Database Setup

Database Setup
Store replenishment orders are configured in the following tables:
• inv_invctl_document_xref
• inv_rep_document_lineitm
• inv_shipment
• inv_invctl_document
For information about this table and the Dataloader record used to populate it, see the
Xstore Point of Service Database Dictionary and the Xstore Point of Service Host Interface
Guide.

System Config Setup

There are two configuration options for inventory replenishment in SysConfig.xml, sales
history weeks and quantity confirmation threshold configuration options.

SysConfig.xml
<Setting name="ItemLookup---LoadGrid">true</Setting>
<Setting name="ItemLookup---LoadPriceHistory">true</Setting>
<Setting name="ItemLookup---LoadSalesHistory">true</Setting>
<Setting name="ItemLookup---LoadSimilar">true</Setting>
<Setting name="ItemLookup---LoadSubstitute">true</Setting>
<Setting name="ItemLookup---LoadUpcs">true</Setting>
<Setting name="ItemLookup---PriceHistoryDays">30</Setting>
<Setting name="ItemLookup---SalesHistoryWeeks">12</Setting>
<Setting name="ItemLookup---ShowAdvancedSearchForm">false</
Setting>
SalesHistoryWeeks - Indicates how many weeks of sales history will be displayed
when an Item Lookup is done in the replenishment module. Sales history information is
displayed in the “Sales History” tab.
<Setting name="Replenishment---ConfirmQuantityThreshold">3000</
Setting>
ConfirmQuantityThreshold - The quantity above which the user will be prompted
to confirm the value entered on the store replenishment order.

Non Merchandise Item Setup

See “Non-Physical Item Database Setup” of Chapter 5, “Item and Pricing Configuration”
for more information.
1. Specify the subtype code values in
itm_non_phys_item.non_phys_item_subtype.
2. Define the descriptions of categories in translation.properties (for example,
translations_en.properties). Examples include:
- _dtv.pos.register.type.NonPhysicalItemSubType.PRE_PAID_ADVERT
ISING=Pre Paid Advertising

Store Replenishment Orders 21-3

To Use Pack Size for Item Ordering

- _dtv.pos.register.type.NonPhysicalItemSubType.GIFT_WRAPPING=G
ift Wrapping

Note: PRE_PAID_ADVERTISING and GIFT_WRAPPING are specific

subtype codes defined in
itm_non_phys_item.non_phys_item_subtype.

3. Set the itm_non_phys_item.non_phys_item_typcode to REPLENISHMENT.

To Use Pack Size for Item Ordering

Using pack size for item ordering, the system will round order quantities to the nearest
pack size and will apply a “round half up” rounding rule.
The system sets the requested quantity for the current item equal to the quantity in one
pack for that item. A message will be displayed to the user indicating the quantity was
adjusted to meet pack size requirements.

Note: Pack size is enforced only when ordering from DC/warehouse

locations, and is not enforced when ordering from another store
location. For this reason, a partial pack may be sent when the source is
another store.

Pack Size If entered quantity= Then final quantity=

10 8 10

10 5 10

10 4 0

10 14 10

10 16 20

To Search For Replenishment Documents By Source Entity

There must be a reference in inv_rep_document_lineitm.sourceid to an entry in
the inv_valid_destinations table.
The entry must have the same document_typcode and organization_id as the
referencing entry of the inv_rep_document_lineitm table.

To Display The Source Of an Item

The source id in itm_item.default_source_id should reference an existing entry
in loc_rtl_loc.rtl_loc_id.
The itm_item.default_source_type can have these values: STORE, DC, and
VENDOR.

21-4 Technical Guide

 22
Workstation Configuration

Overview
In Xstore Point of Service, a workstation is any system running Xstore Point of Service.
This can be a register, a back-office system, or a handheld device. These workstations are
managed through the loc_wkstn table, and can be loaded into the database through
DataLoader.

Workstation Database Setup

Workstation setup is done within the loc_wkstn table. For information about this table
and the Dataloader record used to populate it, see the Xstore Point of Service Database
Dictionary and the Xstore Point of Service Host Interface Guide.

Workstation Configuration 22-1

Workstation Database Setup

22-2 Technical Guide

 23
Order Management System Options

Overview
Xstore Point of Service return processing provides the ability to accept returns for
transactions processed by outside systems. This functionality allows items purchased on
the web to be returned in a store location.
• A shipping document is required to process a cross-channel return. If the customer
does not have a shipping document, a standard blind return must be performed.
• The shipping document barcode is only accepted at the prompt for Web Order ID,
not at the item prompt. (Only transaction barcodes can initiate a return transaction
from the item prompt).
• If the OMS host is unreachable, Xstore Point of Service's existing unverified return
processing will be used.

Setup Required
• Items sold on the web must exist in the store database whether or not they are sold
in-store.
• In system.properties, add :crosschannelreturn to the config path
dtv.config.path.-500=:crosschannelreturn.
• Xstore Point of Service is communicating with the Order Management System for
cross-channel returns, for both OMS lookups and OMS returns, through the Xstore
services framework. The following three parameters must be included in the Order
Management System (OMS) service definition in the ServiceHandlers.xml:

Note: The ServiceHandlers.xml file is located in the following

directory:
<Xstore installation directory>\lib\config.jar\serenade\

Note: The values for the configurations below, may vary depending
on your Order Management System installation.

- XchReturnDefaultDisposition - The default value is 40. Each call Xstore

Point of Service makes to the OMS return web service specifies this value as the
disposition code.

Order Management System Options 23-1

Overview

- XchReturnDefaultReasonCode - The default value is 80. Each call Xstore

Point of Service makes to the OMS return web service specifies this value as the
reason code.

Note: Xstore Point of Service does not have the ability to translate the
Xstore return reason code to an equivalent OMS return reason code for
each item returned in Xstore Point of Service.

- XchReturnXstoreItemIdField - The default value is the item ID. When

Xstore Point of Service performs the OMS lookup call, the response data must
include the Xstore item ID, for the originally purchased items. Depending on
your system’s configuration, the item ID may appear in a number of different
XML attributes. This configuration may be one of the following four values: the
item_id, the retail_ref_number, the sku, or the short_sku_number.

Note: The sku option requires custom code in OMS.

Cross Channel Return Processing

1. The customer must provide the shipping document for the items to be returned.
2. At the Return Information prompt, the Web Order ID number can be keyed or
scanned. (See “Overview”).
3. Xstore Point of Service sends a CWCUSTHISTIN message passing in the order
number.

Note: If the lookup fails as unreachable, the user will be notified and
Xstore Point of Service will enter unverified return mode.

4. The Host returns a CWORDEROUT message:

- Tender IDs are decrypted.
- The actual_price field contains the individual unit price.
- Tax values are aggregate. Individual item taxes are computed by dividing the
tax values by the order_quantity.

Note: The available item quantity is the shipped_quantity - return

quantity. (It is possible that a return in advance of goods being
shipped\received was accepted).

5. Xstore Point of Service prompts for a return reason code. Return codes are mapped
to Disposition codes (that is. return to warehouse, re-sale in store, and so on). Both
disposition and reason codes are included in the CWRETURNIN message.
6. When the transaction is completed, a CWRETURNIN message is sent.
7. Xstore Point of Service accepts a CWRETURNOUT message to confirm receipt of the
return. If the success_flag = N, then the text description of the failure is written to the
Xstore Point of Service log and the user will not be notified of message failure.

23-2 Technical Guide

 24
Customer Engagement Cloud Services
Configuration

Overview
Customer Records
When using the certified Customer Engagement Cloud Services interface, Xstore Point of
Service submits real-time adds and updates of customer records to the CRM system
through its Web Services.
When a new customer record is added in Xstore Point of Service, it will immediately be
added to Customer Engagement Cloud Services. Replication will handle transporting
the customer record to Xstore Office. If a connection to Customer Engagement Cloud
Services cannot be established, the customer will be saved in the StorePrimary
DataSource (as configured by default), with replication handling persistence to both
Xstore Office and Customer Engagement Cloud Services. (As such, there is no need for a
backup write to relate.customers.xml because replication essentially guarantees
eventual delivery).
When a customer record is pulled down from Customer Engagement Cloud Services
and updated in Xstore Point of Service, the changes will be sent in real-time to all of the
destinations as described above (subject to replication delays).
There is no action required by the user to enable/disable this behavior since this is
standard Xstore Point of Service functionality.

Xstore Point of Service Transactions

Xstore Point of Service transactions are posted into Customer Engagement Cloud
Services using a near-real-time web service transaction broadcaster. This web service
provides the ability to broadcast to Customer Engagement Cloud Services in lieu of
sending batch-level PosLog.xml files.
To broadcast POS Log records as they are posted to Xstore Office through replication in
real-time, see “Posting Transactions to Customer Engagement Cloud Services in Real-
time”. All transaction types that Customer Engagement Cloud Services can currently
consume via batch POS Log processing are accepted from Xstore Office.

Note: Non-POS Log document records will be ignored as they come

through replication.

Customer Engagement Cloud Services Configuration 24-1

Service Handlers Settings

The following sections define the setup required to use the Customer Engagement Cloud
Services module.

Note: The Customer Engagement Cloud Services configurations have

been moved from pos.jar to \xstore\lib\config.jar\relate\.

Service Handlers Settings

ServiceHandlers.xml
These configurations are used to configure Customer Engagement Cloud Services's Web
Services in Xstore Point of Service. The Host name and Customer Engagement Cloud
Services Company ID (Org Name) in the ServiceURL or WsdlLocation tags (one or the
other) in each Service must be configured properly for the Customer Engagement Cloud
Services system that is being used.
In the following examples, the Host Name is “relate” and the Customer Engagement
Cloud Services Company ID is “mpk”.

Note: The URL is case sensitive.

Example 1
<Service name="RELATE_CUSTOMER_WS">
<Parameters dtype="Map">
<WsdlLocation dtype="String">https://orce:<PORT>/ocl/
OrceWebServices/v3_0/CustomerServicesApiService?wsdl</
WsdlLocation>
<ReadTimeout dtype="Integer">30</ReadTimeout>
<ConnectTimeout dtype="Integer">30</ConnectTimeout>
<PriorityCustomerSegmentId dtype="Integer">940</
PriorityCustomerSegmentId>
<Entry dtype="MapEntry" key="Auth">
<value cipher="config" encrypted="${dtv.relate.Auth}"/>
</Entry>
</Parameters>
</Service>

Example 2
<Service name="RELATE_CARD_WS">
<Parameters dtype="Map">
<WsdlLocation dtype="String">https://orce:<PORT>/ocl/
OrceWebServices/v3_1/CardServicesApiService?wsdl</WsdlLocation>
<ReadTimeout dtype="Integer">30</ReadTimeout>
<ConnectTimeout dtype="Integer">30</ConnectTimeout>
<LoyaltyUpdateRetryInterval dtype="Integer">15</
LoyaltyUpdateRetryInterval>

24-2 Technical Guide

 Service Handlers Settings

<Entry dtype="MapEntry" key="Auth">

<value cipher="config" encrypted="${dtv.relate.Auth}"/>
</Entry>
</Parameters>
</Service>

Example 3
<Service name="RELATE_LOYALTY_WS">
<Parameters dtype="Map">
<WsdlLocation dtype="String">https://orce:<PORT>/ocl/
OrceWebServices/v3_3/LoyaltyAccountServicesApiService?wsdl</
WsdlLocation>
<ReadTimeout dtype="Integer">30</ReadTimeout>
<ConnectTimeout dtype="Integer">30</ConnectTimeout>
<Entry dtype="MapEntry" key="Auth">
<value cipher="config" encrypted="${dtv.relate.Auth}"/>
</Entry>
</Parameters>
</Service>

Example 4
<Service name="RELATE_AWARD_WS">
<Parameters dtype="Map">
<WsdlLocation dtype="String">https://orce:<PORT>/ocl/
OrceWebServices/v3_1/AwardAccountServicesApiService?wsdl</
WsdlLocation>
<ReadTimeout dtype="Integer">30</ReadTimeout>
<ConnectTimeout dtype="Integer">30</ConnectTimeout>
<Entry dtype="MapEntry" key="Auth">
<value cipher="config" encrypted="${dtv.relate.Auth}"/>
</Entry>
</Parameters>
</Service>

Customer Engagement Cloud Services Configuration 24-3

Service Handlers Settings

Example 5
<Service name="RELATE_PROMOTION_WS">
<Parameters dtype="Map">
<WsdlLocation dtype="String">https://orce:<PORT>/ocl/
OrceWebServices/v1_0/SerializedCouponServiceService?wsdl</
WsdlLocation>
<ReadTimeout dtype="Integer">30</ReadTimeout>
<ConnectTimeout dtype="Integer">30</ConnectTimeout>
<Entry dtype="MapEntry" key="Auth">
<value cipher="config" encrypted="${dtv.relate.Auth}"/>
</Entry>
</Parameters>
</Service>

Example 6
<Service name="RELATE_REGISTRY_WS">
<Parameters dtype="Map">
<WsdlLocation dtype="String">https://orce:<PORT>/ocl/
OrceWebServices/v3_1/RegistryServicesApiService?wsdl</
WsdlLocation>
<ReadTimeout dtype="Integer">30</ReadTimeout>
<ConnectTimeout dtype="Integer">30</ConnectTimeout>
<PurchaseRetryInterval dtype="Integer">15</
PurchaseRetryInterval>
<Entry dtype="MapEntry" key="Auth">
<value cipher="config" encrypted="${dtv.relate.Auth}"/>
</Entry>
</Parameters>
</Service>

Example 7
<Service name="RELATE_ATTRIBUTE_WS">
<Parameters dtype="Map">
<WsdlLocation dtype="String">https://orce:<PORT>/ocl/
OrceWebServices/v3_2/AttributesServiceApiService?wsdl</
WsdlLocation>
<ReadTimeout dtype="Integer">30</ReadTimeout>
<ConnectTimeout dtype="Integer">30</ConnectTimeout>
<Entry dtype="MapEntry" key="Auth">
<value cipher="config" encrypted="${dtv.relate.Auth}"/>
</Entry>

24-4 Technical Guide

 Service Handlers Settings

</Parameters>
</Service>

Example 8
<Service name="RELATE_TASK_WS">
<Parameters dtype="Map">
<WsdlLocation dtype="String">https://orce:<PORT>/ocl/
OrceWebServices/v1_2/TaskServicesApiService?wsdl</WsdlLocation>
<ReadTimeout dtype="Integer">30</ReadTimeout>
<ConnectTimeout dtype="Integer">30</ConnectTimeout>
<Entry dtype="MapEntry" key="Auth">
<value cipher="config" encrypted="${dtv.relate.Auth}"/>
</Entry>
</Parameters>
</Service>

Example 9
<Service name="RELATE_GIFT_CARD_SVC_TRANSACTION_WS">
<Parameters dtype="Map">
<WsdlLocation dtype="String">https://orce:<PORT>/ocl/
OrceWebServices/v3_1/SvcTransactionServicesApiService?wsdl</
WsdlLocation>
<ReadTimeout dtype="Integer">30</ReadTimeout>
<ConnectTimeout dtype="Integer">30</ConnectTimeout>
<CardPrefix dtype="String">33333</CardPrefix>
<CardSeries dtype="String">01</CardSeries>
<Entry dtype="MapEntry" key="Auth">
<value cipher="config" encrypted="${dtv.relate.Auth}"/>
</Entry>
</Parameters>
</Service>

Customer Engagement Cloud Services Configuration 24-5

Data Source Config Settings

Data Source Config Settings

DataSourceConfig.xml
These settings configure the Customer Engagement Cloud Services DataSource in Xstore
Point of Service and handle determining if Customer Engagement Cloud Services is
online.
<DataSourceSet>
<DataSource name="ConcurrentStoreRelate" networkScope="LAN">
<Strategy dtype="String">concurrentWritePersistenceStrategy
</Strategy>
<Property key="DataSource1" value="Relate" />
<Property key="DataSource2" value="StorePrimary" />
</DataSource>
<DataSource name="Relate" enabled="true" />
</DataSourceSet>

Customer Engagement Cloud Services Security Settings

Xstore Point of Service sends the User ID of the Sales Associate to Customer Engagement
Cloud Services. With this functionality, Xstore Point of Service is able to recognize and
implement the data security setting that is returned from Customer Engagement Cloud
Services.

Security Access
• If Customer Engagement Cloud Services is offline, customer search fails over to the
store primary.
• Customer Engagement Cloud Services security rules work together with any Xstore
Point of Service security privileges for buttons or actions that are in place to give the
user the least amount of editing rights. For example, if Customer Engagement Cloud
Services sends a Read/Write setting, but Xstore Point of Service only allows viewing
for the user, then the user cannot edit customers. Or, if Customer Engagement Cloud
Services sends a Limited Read access, but Xstore Point of Service allows full editing
rights for the user, then the user will have Limited Read access with no editing
rights.
• Sales Associates can always create new customers (unless offline with Customer
Engagement Cloud Services or invalid user on Customer Engagement Cloud
Services).
• Security rights do not affect any customer data that is displayed in Xstore Point of
Service reports.

24-6 Technical Guide

 Customer Engagement Cloud Services Security Settings

System Properties Settings

Note: The Customer Engagement Cloud Services configurations have
been moved from
\xstore\lib\config.jar\relate\SystemConfig.xml to
system.properties. The properties are named
dtv.relate.security.Type and
dtv.relate.security.DefaultUserId.

There are three configuration options available for linking the Customer Engagement
Cloud Services security functionality to Xstore Point of Service:
- NO_SECURITY - Send the configured default user for every call. This option
will give the same security setting to everyone. The DefaultUserId value is
set up in Customer Engagement Cloud Services and in system.properties.
This guarantees that a user is always found. Customer Engagement Cloud
Services will send a security level in the response, but Xstore Point of Service
will not use it.
* Default user ID is passed for Security User on all Customer Engagement
Cloud Services requests.
* Logged in user ID is passed as Update User ID on all Customer Engagement
Cloud Services requests.
- USER_ID security - Send the actual user ID. For this option, every Xstore Point
of Service user must be set up in Customer Engagement Cloud Services. The
specific user ID is sent to Customer Engagement Cloud Services for all customer
requests. Customer Engagement Cloud Services will then take the user and
customer into account to determine the security rights that the user has for that
particular customer. (See “Customer Requests in Xstore Point of Service”).
* Logged in user ID is passed as Security User on all Customer Engagement
Cloud Services requests.
* Logged in user ID is passed as Update User ID on all Customer Engagement
Cloud Services requests.
- USER_ROLE security - Send the Primary Group ID of the user. For this option,
every Xstore Point of Service role must be set up as a user in Customer
Engagement Cloud Services. The user’s Primary Group ID is sent to Customer
Engagement Cloud Services for all customer requests. Customer Engagement
Cloud Services will then take the user role and customer into account to
determine the security rights that the user has for that particular customer. (See
“Customer Requests in Xstore Point of Service”).
* Primary group ID is passed as Security User on all requests to Customer
Engagement Cloud Services

Customer Engagement Cloud Services Configuration 24-7

Customer Engagement Cloud Services Security Settings

* Logged in user ID is passed as Update User ID on all Customer Engagement

Cloud Services requests

Note: If Customer Engagement Cloud Services has no reference to the

User ID passed from Xstore Point of Service during the web service
call; then the web service will provide an exception message of
INVALID_USER and no customer data will be included. Upon
receiving this message, Xstore Point of Service will notify the user that
their record is not set up in Customer Engagement Cloud Services and
that they cannot do any customer transactions until the issue is
resolved.

Customer Requests in Xstore Point of Service

The following features in Xstore Point of Service are associated with Customer requests.

Customer

Customer Search (Returns, Orders, Send Sales, Layaways, Special

Orders, Work Orders, Warranty)

Customer Retrieve

Add/Update Customer

Delete Customer

Get Customer Notes

Add Customer Notes

Get Visualizer Items

Add Wish List Items

Delete Wish List Items

Get Transaction History

Registry

Get Registry

Get Registry Detail

Add/Update Registry

Add/Update Registry Detail

Sell/Return Registry Items

24-8 Technical Guide

 Customer Engagement Cloud Services Security Settings

Customer Engagement Cloud Services does not currently do a security/privilege check

for the Card and Loyalty web services; however, Xstore Point of Service sends the User
ID to Customer Engagement Cloud Services.

Card Loyalty

Card Inquiry Data Get Loyalty Transaction Detail

Issue Loyalty Points

Recover Loyalty Points

Redeem Loyalty Points for

Award

Customer Engagement Cloud Services Data Security in Xstore Point of

Service
Xstore Point of Service recognizes the data security value sent in the Customer Retrieve
message from Customer Engagement Cloud Services so that the security features are
enforced in the Xstore Point of Service environment.
Read/Write - All customer data is visible and allowed to be edited.
Read Only - All customer data is visible, but cannot be edited.
- Edit Customer buttons are disabled.
- Associates are able to perform all functions related to Orders, Loyalty, etc.
- Associates are able to cancel Layaways, Special Orders, etc.
- Customer Options (Add New, Print, Tax Exemption, and Create House Account)
are available.
- Loyalty enrollment is not available.
- Wish List: Add Item, Purchase Item, and Delete Item buttons are disabled.
- Comment: Add Comment button is disabled.
Limited Read - Customer data is visible, but masked.
- Edit Customer buttons are disabled. No updates can be made to the customer.
- Data is masked exactly as it is in Customer Engagement Cloud Services.
- All non-Customer Engagement Cloud Services data is viewable.
- Associates will not be able to read or edit an address, but they are able to
perform functions that require address information (for example, orders, send
sales, etc.).
* The Ship To address screen will default to blanks (except for the country
field which defaults to their country and cannot be edited).
* Associates are required to enter the address in full again. This entered
address is used for that transaction only and will not be saved to the
customer profile.
- For Limited Read only, the masked customer data will not be saved to the local
database for Special Orders, Orders, etc.
- Associates are able to cancel Layaways, Special Orders, etc.

Customer Engagement Cloud Services Configuration 24-9

Posting Transactions to Customer Engagement Cloud Services in Real-time

- Customer Options (Add New, Print, Tax Exemption, and Create House Account)
are available.
- Wish List: Add Item, Purchase Item, and Delete Item buttons are disabled.
- Comment: Add Comment button is disabled.
No Access - No data is returned to Xstore Point of Service. Xstore Point of Service will
function as if the customer is not found and no name will display in the search results.

Posting Transactions to Customer Engagement Cloud

Services in Real-time
SOAP communication is logged (both request and response). When Xstore Office sends
data to Customer Engagement Cloud Services, it is using the same “Service Factory”
framework that Xstore Point of Service itself uses to communicate to outside services.
This framework supports logging via log4j2 configuration.
If connection to Customer Engagement Cloud Services is disabled, the transaction data
is not duplicated on Customer Engagement Cloud Services when the connection is
enabled. Customer Engagement Cloud Services will reject duplicate transactions.

Customer Engagement Cloud Services Broadcaster

The broadcaster system in Xstore Office provides a means to transmit PosLog data to
other systems.
The Customer Engagement Cloud Services broadcaster uses the Object format to
transmit PosLog data. Customer Engagement Cloud Services has a public SOAP web
service for accepting PosLog data. The service has a method which accepts an XSD-
defined PosLog object. This XSD is part of the web service's WSDL; it is defined and
controlled by the Customer Engagement Cloud Services project team. The Xstore Office
Customer Engagement Cloud Services broadcaster must convert each PosLog object that
needs to be sent to Customer Engagement Cloud Services into Customer Engagement
Cloud Services's PosLog XSD format before sending it.

Note: Customer Engagement Cloud Services broadcaster is disabled

by default. Refer to the Xstore Point of Service Implementation Guide for
more information about broadcasters.

Loyalty Card Setup

The following Loyalty options are found in SysConfig.xml,
\xstore\lib\config.jar\cust\loyalty\
<SysConfig xmlns="http://micros.com/xstore/config/settings">
<Setting name="Loyalty---CardExpirationDateRenewDays">365</
Setting>
<Setting name="Loyalty---CardExpirationNoticeThresholdDays">30</
Setting>
<Setting name="Loyalty---CouponExpirationNoticeThresholdDays">7</
Setting>
<Setting name="Loyalty---HistoryDaysToDisplay">365</Setting>

24-10 Technical Guide

 Sell/Renew Loyalty Cards

<Setting name="Loyalty---LoyaltyCardPurchaseItemId">1700</
Setting>
<Setting name="Loyalty---LoyaltyCardRenewalItemId">1701</Setting>
<Setting name="Loyalty---PurchaseLoyaltyCardEnabled">false</
Setting>
<Setting name="Loyalty---RegistrationMode">CARD_CENTRIC</Setting>
<Setting name="Loyalty---ShowCardExpirationDate">false</Setting>
</SysConfig>
RegistrationMode - Determines the method of distributing Loyalty cards to
customers:
- Card Centric (CARD_CENTRIC)- The store provides a physical card with a
Loyalty account number to the customer. The card's Loyalty number may be
entered manually or swiped in a device.
- Customer Centric (CUSTOMER_CENTRIC) - The store does not provide a
physical card to the customer. The Loyalty number is automatically assigned by
the system and associated with the customer record.
HistoryDaysToDisplay - The number of days the system will look back for a
customer's transaction history.
CouponExpirationNoticeThresholdDays - Determines the number of days before
a coupon expires in which users will receive warning of the expiration.
CardExpirationNoticeThresholdDays - Determines the number of days before a
card expires in which users will receive warning of the expiration.
CardExpirationDateRenewDays - Determines the number of days to renew a
Loyalty card for.
ShowCardExpirationDate - Determines whether to show the Loyalty card expiration
date in the display and on the receipt. If true, the Loyalty card expiration date will
display on the Xstore Point of Service screen and is printed on the receipt. If False,
Loyalty card expiration date will only be shown on the Loyalty Cards tab in customer
maintenance.
PurchaseLoyaltyCardEnabled - Determines whether Loyalty cards can be
purchased and renewed. When set to true, the ability to sell and renew Loyalty cards is
enabled. See Sell/Renew Loyalty Cards below for more information.
LoyaltyCardPurchaseItemId - If PurchaseLoyaltyCardEnabled is set to true,
this is the item identifier for the purchased-type Loyalty card.
LoyaltyCardRenewalItemId - If PurchaseLoyaltyCardEnabled is set to true,
this is the item identifier for the renewed-type Loyalty card.

Sell/Renew Loyalty Cards

A configuration setting in Xstore Point of Service (PurchaseLoyaltyCardEnabled)
determines whether Loyalty/Award cards are sold and/or renewed. When this feature is
enabled, retailers can support the sale of Loyalty/Award cards.
Both Loyalty types: CARD_CENTRIC and CUSTOMER_CENTRIC are supported. When
the customer confirms purchase or renewal of a Loyalty card, a non merchandise SKU is
added to the transaction: LoyaltyCardPurchaseItemId and
LoyaltyCardRenewalItemId. Refer to “Loyalty Card Setup” for more information.

Customer Engagement Cloud Services Configuration 24-11

Customer Engagement Cloud Services Clienteling

Requirements
• Customer Engagement Cloud Services requires an expiration date on the account.
• Selling and renewing Loyalty cards is restricted to the sale transaction mode:
- In mixed transactions such as layaway, hold, pre-sale, etc., the sale of the Loyalty
card (the non-merchandise SKU) will not be available when in the extended
transaction mode.
- Loyalty card sale and renew will be disabled in the Back Office customer
maintenance. Purchasing Loyalty cards can only occur in the sale transaction
mode, not customer maintenance.
- At the beginning of the transaction, if the customer declines the Loyalty prompt,
the associate can access customer maintenance from the sale and select customer
options to add the Loyalty card to the sales transaction.
• The transaction will be processed in real-time communication with Customer
Engagement Cloud Services.
• The sale of a Loyalty card requires a customer to be attached to the sale transaction.
• The associate will be unable to detach a customer from a sales transaction that has a
Loyalty card purchase included. The button that allows removal of the customer is
not active and the associate will be unable to swipe to remove the customer.
• If the line item associated with the Loyalty card SKU is voided from the transaction,
either by swiping or by using the button, the Loyalty card will be dissociated/
unassigned from the customer in the sales transaction. When the Loyalty purchase is
voided from the transaction, a real-time call is made to Customer Engagement
Cloud Services disassociating the Loyalty card from the customer account.
• Loyalty Cards cannot be returned. If necessary, the transaction can be post-voided to
disassociate the Loyalty card from the customer record when the post void is
processed.

Customer Engagement Cloud Services Clienteling

Tasks from the Customer Engagement Cloud Services Clienteling feature display in the
My Tasks screen and in the Tasks tab of the Customer Maintenance screen. Employees
and customers must be valid Customer Engagement Cloud Services user. Xstore Point of
Service stores a list of restricted task types in the base data. These tasks are not allowed
to be created or edited from within Xstore Point of Service (for example: Events and
Admin tasks from Customer Engagement Cloud Services are not editable).

Clienteling Customer Lookup

ServiceHandlers.xml defines the Segment Id of Customers in Customer
Engagement Cloud Services that meet certain, specified criteria. The parameter name is
PriorityCustomerSegmentId and is under RELATE_CUSTOMER_WS service name.
See “ServiceHandlers.xml” and “Task Management” in Chapter 32, “Customer
Maintenance Configuration” for more information.

FAQ: Customer Engagement Cloud Services real-time

updates
If a customer was not found in Customer Engagement Cloud Services and the fail-
over is to Xstore Office, and the customer is found and then is updated, how does this
change get to Customer Engagement Cloud Services?

24-12 Technical Guide

 Oracle Retail Promotions Engine Integration

The customer will be persisted with the transaction and subsequently replicated directly
to Customer Engagement Cloud Services and also replicated to Xstore Office, as
discussed above. No batch mode operation is needed.
If there is a customer that only exists in Xstore Office, and the customer is selected in
Xstore Point of Service (whether in a transaction or in Customer Maintenance), and no
updates are made to the customer, should the customer information be sent in real-
time to Customer Engagement Cloud Services?
No, customers will not be saved to Customer Engagement Cloud Services unless they
are newly created or modified. The assumption is that, as Customer Engagement Cloud
Services is the SOR (System of Record), any record pulled from another source should
have found its way to Customer Engagement Cloud Services at some point prior.
Writing an unmodified record would either be redundant, or worse, replace the SOR’s
“good” data with stale data from a secondary data source.

Oracle Retail Promotions Engine Integration

The Oracle Retail Promotions Engine is a set of REST-based services which facilitate the
creation, management, and applications of deals to retail transactions. A deal is
comprised of a set of conditions, or qualifiers, which must be satisfied in order for a
benefit to be conferred to the purchasing customer. Benefits may be discounts on items
in the same purchase, gift items automatically added to the purchase at no cost, or any
other reward with monetary value.
The Deals configuration is retrieved from an ORCE server and applied locally by a an
external library. The library is in charge of keeping the dealspace updated and to
calculate the actual deals.
The Oracle Retail Promotions Engine integration is a base feature that can be configured
in Xstore Office, see the Xstore Office User Guide for more information about the Xstore
Office Store Personalities feature and configuration paths.
The integration requires that an ORCE server has been correctly configured in Xstore.
The following paths must be available in xstore.config.path.base.features:
:relate:idcs:idcs/relate:promote

Spring Files Configuration

The configuration for the integration can be found in the promote-beans.xml file, in the
config project, in the folder /promote/spring.
There a bean with the name "promoteOfflineHelper" is defined, the parameters are set as
properties:
<bean id="promoteOfflineHelper"
class="dtv.pos.pricing.promote.PromoteOfflineHelper">
<property name="Enabled" value="true" />
<property name="DataFolderName" value="promote" />
<property name="HostUrl"
value="#{systemProperties['dtv.relate.PromoteWs']}" />
<property name="MaximumThreads"
value="#{systemProperties['oracle.retail.promote.maxthreads'] ?:
10}" />
</bean>

Customer Engagement Cloud Services Configuration 24-13

Oracle Retail Promotions Engine Integration

The following properties are used by Xstore:

Property Name Type Default Value Content

Enabled boolean false Defines if the Oracle

Retail Promotions
Engine integration is
enabled. If set to false,
the standard Xstore
Deal Engine is used.

DataFolderName string N/A Defines the name of the

folder in the Xstore
data folder where the
Oracle Retail
Promotions Engine
library saves the files
with the deal
definitions.

HostUrl string Property Defines the name of the

endpoint to call when
dtv.relate.PromoteWs
downloading the deal
definitions.
By default it is set to the
value of the property
dtv.relate.PromoteWs.
This property is set
during Xstore setup.

The following properties are used to initialize to the Oracle Retail Promotions Engine
offline library, they are not validated by Xstore. The default value of the properties is set
by the library when a value is not set in Xstore:

Property Name Type Default Value Content

EngineType string fixed_sort Defines the engine type

used to apply Deals,
either "fixed_sort",
"best_sort" or "default".

MaximumThreads integer 10 Defines the maximum

number of threads that
can simultaneously
execute a deal
calculation.
Additional threads wait
until one of the
executing threads is
terminated.
The value can be set
using the
system.properties
parameter
oracle.retail.promote.m
axthreads.

24-14 Technical Guide

 Oracle Retail Promotions Engine Integration

Property Name Type Default Value Content

FutureDays integer 7 Defines the number of

days to add to the
current end of day
when downloading
Deals from the Oracle
Retail Promotions
Engine, that is
download all Deals
which start before
(current end of day +
futureDays).

PastDays integer 0 Defines the number of

days to subtract from
the current start of day
when downloading
Deals from the Oracle
Retail Promotions
Engine, that is
download all Deals
which end after
(current start of day -
pastDays).

DownloadTimes list of strings 00:00:01 Defines the times (in

ISO-8601 format) at
which to download
Deals from the Oracle
Retail Promotions
Engine.
This format is used to
define a property with
multiple update times:
<property
name="DownloadTime
s">
<list value-
type="java.lang.String">
<value>00:00:01</
value>
<value>12:00:00</
value>
<value>16:00:00</
value>
</list>
</property>

Customer Engagement Cloud Services Configuration 24-15

Oracle Retail Promotions Engine Integration

system.properties Settings
The table below describes the system.properties settings.

New Setting Valid Values Description

oracle.retail.promote.m integer greater Define the maximum

axthreads or equal to 1 number of threads that
can simultaneously
execute a deal
calculation.

dtv.relate.PromoteWs URL This setting is usually

created during the
Xstore installation
when an ORCE server
is configured, it might
need to be added only
in a development
environment. It should
have the format:
dtv.relate.PromoteWs=[
ORCE_URL]/
[TENANT_ID]/
promote/services

Xservices Settings
When using Xservices, the above system.properties settings must be present in the
xservices.properties file.
In addition, the xstore.data.path setting should be added.
xstore.data.path=../xstoredata/xservices
In Xservices the initialization of the Oracle Retail Promotions Engine offline library is
delayed to allow the Jetty server to be fully started before the library downloads the deal
space. The default delay is 30 seconds. This value can be changed with the parameter
oracle.retail.promote.delayedStartTimeout.

Additional Details
Additional logging can be enabled by changing the level of the package
dtv.pos.pricing.promote in the log4j configuration.
<Logger name="dtv.pos.pricing.promote" level="debug" />
Xstore’s role in this integration is to correctly prepare the data for the Oracle Retail
Promotions Engine offline library and to apply the results to the sale.
If a deal is not applied as expected and it needs to be defined whether the issue is on the
Xstore side or on the Oracle Retail Promotions Engine library side, the log level can be
changed to "trace".
This level will write a JSON string in the Xstore log file with the request sent by Xstore
and the response returned by the library.

24-16 Technical Guide

 25
Order Broker Configuration

Overview
This chapter provides information about the configurations that support the Oracle
Retail Order Broker Cloud Service. This optional module can be interfaced with Xstore
Point of Service to provide information about inventory availability across all sales
channels.
Using this Order functionality, you can sell an item that is not in stock at your store and
Order Broker will automatically select the best location to fulfill the customer’s order
across the enterprise.

Important: Order Broker 5.0 and above is required to support the

Under Review flag. Order Broker 5.0 is also required to support
capturing a reason and description associated with any status update.

Order Functionality
There are two types of Order Broker order types: Legacy and New.

Legacy
With legacy order types, a Pick Up Other Store order contains items to be picked up
from a fulfilling store's inventory, and therefore never requires inventory transfer from
another store.
Legacy order types are enabled by setting the LegacyOrderType flag to true in
ServiceHandlers.xml.

New
With new order types, a Pick Up Other Store order can contain two kinds of items:
pickup items and ship for pickup items.
A pickup item is just like a Legacy Pick Up Other Store order. It is picked up from the
fulfilling store's inventory with no inventory transfer from another store.
A ship for pickup item is a new feature. It may not have available inventory in the
fulfilling store, and may need to be sourced and shipped from another store to the
fulfilling store to be picked up.
New order types are enabled by setting the LegacyOrderType flag to false in
ServiceHandlers.xml.

Order Broker Configuration 25-1

Fulfillment Types

Fulfillment Types
There are several ways in which an Order Broker order can be fulfilled:
• Fulfill By Order: A store associate fulfills an entire order from one location.
• Fulfill By Order Line: A store associate can select one or more eligible order lines to
fulfill.
• Split Line Fulfillment: When Order Broker is configured to allow split line orders,
an order line may be split into multiple lines if there is not enough inventory to
fulfill from a single store.
• Fulfill By Partial Quantity: For an order line with multiple quantities, a store
associate can choose to fulfill part of it. The order line will be split into two in this
case. A new order line is created with the partially fulfilled quantity in the new
status. The existing order line’s quantity is decremented to reflect the split. A
boolean system configuration AllowPartialUpdates is added to Xstore to enable
or disable this feature. By default it is disabled. When it is enabled, Order Broker’s
Allow Partial Updates and Allow Split Order settings must both be turned on.

Split Order Functionality

Xstore Point of Service supports split order functionality when brokering orders. With
split order functionality enabled, Order Broker will split an order across multiple
fulfilling locations if there is no single location that can fulfill all the items in the order.
When enabled in Order Broker, the split order functionality must also be enabled in
Xstore Point of Service (see “ServiceHandlers.xml Settings”).
When split order is enabled for Legacy orders, Xstore Point of Service makes one web
service call (SubmitOrder message) to Order Broker for Customer Delivery and Pick
Up This Store orders. In turn, there is only one request ID assigned to all items in the
order. When split order is disabled, one SubmitOrder request message is created for
each item in the order.
When split order is enabled for New orders, one SubmitOrder request is created for
each item regardless of the split order configuration for pickup items that require no
inventory transfer in Pick Up Other Store orders. For ship-for-pickup items in Pick Up
Other Store orders, one SubmitOrder request is created per fulfilling location: in this
case, one request ID is assigned to all ship for pickup items fulfilled from the same
location.
Cancel functionality is also supported:
- Pickup orders may be cancelled at originating and fulfilling locations. For Pick
Up This Store orders, the originating and fulfilling locations are the same. For
customer Delivery orders, the order can only be cancelled at the originating
store.
- If split order functionality is enabled, it is possible to cancel single line items in
an order that have not been fulfilled. If split order functionality is disabled, only
the entire order (or all items on the order that allow cancellation) can be
cancelled.
- Cancellation points, based on order status, are set up through configuration. See
“SysConfig.xml Settings”.
In Xstore Point of Service, three types of orders are supported:
• PICKUP - (Pick Up Other Store) The customer chooses the store at which to pick up
the merchandise. The merchandise may be in the pickup store or may be shipped

25-2 Technical Guide

 Group Shipment

from another location to the pickup store. On the Work List screen this type of order
may be labeled a Transfer Pickup.
• TRANSFER PICKUP - (Pick Up This Store) This type involves shipping the item to
the store where the order is placed (originating store) for pickup. This may involve
multiple shipments when the split order option is enabled and all items cannot be
sourced from one location.

Note: Note:The following names are used interchangeably in the

software/configuration files for the "TRANSFER PICKUP" order type:
Retail Pickup, Pick Up This Store, Pick Up My Store, Ship to My Store,
Delayed Pickup, and Transfer Pickup.

• DELIVERY - The items are shipped to the customer directly. This may also involve
multiple shipments when the split order option is enabled and all items cannot be
fulfilled by one store location.

Email Functionality
Xstore Point of Service sends emails to customers for Order Broker orders in the
scenarios described below. This email activity is not configurable.
• PICKUP - (Pick Up Other Store) An email is sent to the customer when the fulfilling
store picks/reserves the order.
• TRANSFER PICKUP - (Pick Up This Store) An email is sent to the customer when
the order is received by the originating store and the receiving document is closed.
• DELIVERY - An email is sent to the customer when the fulfilling store ships the
order.

Group Shipment
The “Group Shipment” configuration setting in Order Broker will indicate when
Customer Delivery and Pick Up This Store orders will be brokered by Order Broker or
when the Sales Associate will select the fulfilling location.
- When the “Group Shipment” setting in Order Broker is set to true, the response
web service sends back a 'v' flag for Virtual Inventory indicating that Order
Broker has the inventory and will be able to fulfill the order. Xstore Point of
Service will hand off the brokering process to the Order Broker.
- When the “Group Shipment” setting in Order Broker is set to false, the response
web service will send back no 'v' flag. The message response from Order Broker
will include the information on the location, items, inventory and the miles from
the originating store. The Sales Associate will pick the appropriate location
based on the information displayed.

Note: The Sales Associate must always pick the appropriate location
for Pick Up Other Store orders regardless of the Group Shipment
configuration.

Order Broker Configuration 25-3

Under Review Flag

Under Review Flag

Order Broker now allows an Under Review Flag to be passed with the order at the
header level when the order is submitted. This flag is used to indicate that Xstore Point
of Service needs to delay shipping or fulfilling the order until the flag is cleared. Updates
to this field (under_review_flag) in the xom_order table, are available in the
following messages:
• Fulfillment Response,
• Order Search Response, and
• Status Request Response.
The Under Review Flag does not interfere with shipping an order or picking up an in-
store pick up order. The idea is the order may be edited in the other channel and this flag
is an option to indicate there is a change in process. Future development by other
channels will take into consideration where the order is in the process flow to determine
if the flag can be changed.
- If the order has the xom_order.under_review_flag set to TRUE, the order
is displayed on the screen, but the associate cannot accept or reject the order, or
pick/reserve the order.
- If the xom_order.under_review_flag is blank, not passed, or set to
anything other than TRUE, the flag for the order is set to FALSE in the
xom_order table. The flag is also set to FALSE if the message version is lower
than 5.0.

Status Update Reason and Description

Order Broker now has the ability to capture a reason and description associated with any
status update. For example, if a fulfilling location rejects or cancels an order, a reason
code and description can be passed along with the status update.
In Xstore Point of Service, a message prompt is triggered when a sales associate cancels
an order/line item, or when an order is rejected. The message is captured at the header
level if the entire order has been cancelled or rejected, or at the line item level if a line
item is cancelled.
The current functionality and process flow in Xstore Point of Service has not changed,
the only modification is to capture the cancel/reject information and record the
information in the xom_order and the xom_order_line tables.
The following sections define the setup required to use the Order Broker module.

Data That Must Be Populated in Xstore Office

• Items – All items that will be used in Order Broker must be present in the itm_item
table. The inventory and item load processes get item data from this table.
Use the itm_item.disallow_order_flag to exclude an item from order
functionality.
• Stock Ledger – All items that will be used in Order Broker must have
inv_stock_ledger_acct records that represent accurate quantities of the items
at each location. The inventory and item availability processes get stock quantities
from this table.

25-4 Technical Guide

 Xstore Point of Service Configurations

• Inventory Control Document Line Item - Use

inv_invctl_document_lineitm.control_number to specify a general
control number to be associated with an inventory document line item. [OPTIONAL]

Xstore Point of Service Configurations

system.properties Settings
# -- Locate --
dtv.config.path.-390=:order:locate:version1\/provider\/locate
OrderServices=dtv.xst.xom.locate.impl.OrderServicesFactory
dtv.locate.XstoreSystemCode=XSTORE
• Config Path – To use Order Broker functionality, the dtv.config.path must
contain the :order and :locate config paths.
• OrderServices - This is the factory that creates the order services provider to use.
• System Code – Used to configure the system code that Xstore Point of Service will
be using in Order Broker. This value is defined in Order Broker and simply needs to
be specified in Xstore Point of Service.
dtv.locate.XstoreSystemCode=XSTORE

ServiceHandlers.xml Settings
<Service name="LOCATE">
<Parameters dtype="Map">
<WsdlLocation dtype="String">http://hostname/Locate/
LocateServices?wsdl</WsdlLocation>
<ConnectTimeout dtype="Integer">30</ConnectTimeout>
<Destination dtype="String">Locate</Destination>
<LocateVersion dtype="String">16.0</LocateVersion>
<AllowSplitOrder dtype="String">true</AllowSplitOrder>
<LegacyOrderType dtype="String">true</LegacyOrderType>
<AllowPartialUpdates dtype="String">false</
AllowPartialUpdates>
</Parameters>
</Service>
WsdlLocation – This configuration sets the URL of the Order Broker server’s WSDL.
ConnectTimeout – This configuration sets the connection timeout for requests that are
sent to Order Broker.
StatusUpdateRetryInterval - This configuration sets the number of minutes
between attempts to resend failed status updates.
OrderSubmitRetryInterval - This configuration sets the interval number between
attempts to resend failed order submissions.

Order Broker Configuration 25-5

Xstore Point of Service Configurations

Destination - This value identifies what should be sent to Order Broker as the
destination in a request message. This is set in Order Broker and dictated by Order
Broker.
LocateVersion - This value is passed in request messages sent to Order Broker, and is
used by Order Broker to determine the response message version to return. The
configured version number should not be increased beyond the default value included
in the base file.
AllowSplitOrder - If set to true, split order functionality is enabled. With split order
functionality enabled, Order Broker will split a delivery order across multiple fulfilling
locations if there is no single location that can fulfill all the items in the order. This setting
must match the configuration setting in Order Broker.
LegacyOrderType - If set to true (default value), Xstore Point of Service will use order
types used by earlier versions of Order Broker. If set to false, Xstore Point of Service will
use new Order Broker order types.

Note: The Enable Ship for Pickup setting in Order Broker Cloud
Service must match the functionality in this configuration. If they do
not match, Order Broker orders will not work.
• If LegacyOrderType is set to true, Enable Ship for Pickup must be set to
No.
• If LegacyOrderType is set to false, Enable Ship for Pickup must be set to
Yes.

• AllowPartialUpdates - Determines whether partial updates for order lines are

enabled.

Note: If this setting is set to true, partial updates must also be

enabled for the organization in Order Broker through the following:
• Allow Split Order must be enabled.
• Allow Partial Updates must be enabled.

SysConfig.xml Settings
In base Xstore Point of Service, this file is found in the
C:\xstoredata\lib\config.jar\order\ directory.
<Setting name="Order---AgedNotificationDays">2</Setting>
<Setting name="Order---AllowShipOrderWhileStoreIsClosed">true</
Setting>
<Setting name="Order---AutoPickInventoryUponAccept">false</
Setting>
<Setting name="Order---
CancellableOrderLineStatus">NEW,POLLED,ACCEPTED,RECEIVED,UNFULFIL
LABLE</Setting>
<Setting name="Order---CustomerOrderNoShowMessageRegister">1</
Setting>
<Setting name="Order---CustomerOrderNoShowNotificationDays">30</
Setting>

25-6 Technical Guide

 Xstore Point of Service Configurations

<Setting name="Order---DefaultLocateItemDistance">200</Setting>
<Setting name="Order---DepositBasis">ITEM</Setting>
<Setting name="Order---DepositCalculation">PERCENT</Setting>
<Setting name="Order---DepositValue">10</Setting>
<Setting name="Order---DisplaySoldItemCount">false</Setting>
<Setting name="Order---EnableBorderControl">false</Setting>
<Setting name="Order---EnablePickListScanning">false</Setting>
<Setting name="Order---EnableSameDayDelivery">false</Setting>
<Setting name="Order---LocateItemOnQuantityChange">true</Setting>
<Setting name="Order---LocationConfirmationPrompt"></Setting>
<Setting name="Order---ProcessDeliveryOrdersFirst">true</Setting>
<Setting name="Order---PromptForItemQuantity">false</Setting>
<Setting name="Order---PromptOrdersOnStoreClose">false</Setting>
<Setting name="Order---PromptOrdersOnStoreOpen">false</Setting>
<Setting name="Order---PromptShowOrderCancelReasonCode">true</
Setting>
<Setting name="Order---PromptShowOrderRejectReasonCode">true</
Setting>
<Setting name="Order---PromptShowPickedOrderItemWarning">true</
Setting>
<Setting name="Order---SameDayDeliveryMessageRegister">1</
Setting>
<Setting name="Order---SameDayDeliveryPickupWindowTime">120</
Setting>
<Setting name="Order---SetupFeeBasis">ITEM</Setting>
<Setting name="Order---SetupFeeCalculation">PERCENT</Setting>
<Setting name="Order---SetupFeeValue">0</Setting>
<Setting name="Order---ShipCalcType">PER_ITEM</Setting>
<Setting name="Order---ShippingFeeOnDelayedPickup">false</
Setting>
<Setting name="Order---SkipSearchFormIfCustomer">true</Setting>

Note: The following system settings have been moved to the

system.properties file:
The system setting Order—DownloadInterval was removed and
converted into the system property
dtv.locate.order.downloadInterval.
The system setting Order—StatusRequestInterval was removed
and converted into the system property
'dtv.locate.order.statusRequestInterval.

Order Broker Configuration 25-7

Xstore Point of Service Configurations

• AgedNotificationDays - The number of days after which an order will be shown

with a color change in the order work list to indicate order aging.
• AllowShipOrderWhileStoreIsClosed - Determines whether the order can be
shipped while the store is closed.
• AllowPickInventoryUponAccept - This setting will automatically
move inventory, for an order, into the Order_Pending bucket
when it is accepted.
• CancellableOrderLineStatus - Determines which order statuses allow for
cancellation.
Supported Values:
- New
- Polled
- Accepted
- Received
- Unfulfillable
- Reserved
If the Retailer wants to allow the cancellation of “Customer failed to pickup
orders” (CustomerOrderNoShowNotificationDays > 0) and allows to pickup
the order in another store, the “RESERVED” status shall be added to the list of
CancellableOrderLineStatus.
• CustomerOrderNoShowMessageRegister - Determines which store register
will receive the message that there are orders that have been flagged as 'Customer
Failed to Pickup'. If '0' is entered, then all store registers will receive the message.
• CustomerOrderNoShowNotificationDays - This setting determines the
number of days in between an order that is ready for the customer to pick it up from
the store and when the order should be set to 'Customer Failed to Pickup'. If '0' is
entered the functionality will be disabled.
• DefaultLocateItemDistance - The default distance that is to be used when
locating an item and the user is not given an option to choose the distance.
• DepositBasis - The foundation on which the required order deposit is based,
either on the items in an order or on the order total.
Supported Values:
- ITEM
- TRANSACTION
• DepositCalculation - The calculation method used to determine the required
deposit amount.
Supported Values:
- PERCENT
- AMOUNT
• DepositValue - The figure used to determine the required deposit amount.
Supported Values:
- For percent, a number between 0 and 100
- For amount, the dollar amount

25-8 Technical Guide

 Xstore Point of Service Configurations

• DisplaySoldItemCount - Determines whether the system includes order items as

part of the total items sold count shown on the sale screen. If true, include order
items in the total items sold count. If false, do not include order items in the total
items sold count.
• EnableBorderControl - Determines whether the locations returned when
finding an item should be filtered to include only the locations in the current store's
country. If true, filter locations to include only the locations in the current store's
country. If false, return all locations.
• EnablePickListScanning - This setting enables the ability to scan all of the
order items to be picked via a "virtual" pick list. Enabling this setting replaces the
printed pick slips.
• EnableSameDayDelivery - Determines if the Same Day delivery functionality is
available in Xstore.
• LocateItemOnQuantityChange - Determines whether a request to find an item
should be issued when a quantity change on an order line is performed. If true, a
request to find an item will be issued when a quantity change on an order line is
performed. If false, no request to find an item will be issued when a quantity change
on an order line is performed.
• LocationConfirmationPrompt - An order type-specific configuration that
determines if a confirmation message should be displayed when a location is
selected for an item.
Supported Values:
- Standard Delivery
- Standard Pickup
- Delayed Pickup (Pick Up From This Store)
• ProcessDeliveryOrdersFirst - Determines whether customer delivery orders
are processed first (that is, before customer pickup orders).
• PromptForItemQuantity - This global setting determines whether to prompt for
the quantity to order when adding an item to an order. If true, prompt for quantity. If
false, do not prompt for quantity. Note: If the value is false, the user may still be
prompted for quantity if the standard prompt_for_quantity_flag on the item
is set to true.
• PromptOrdersOnStoreClose - If true, a prompt is displayed during the store
close process informing the user that orders are ready to be processed.
• PromptOrdersOnStoreOpen - If true, a prompt is displayed during the store open
process informing the user that orders are ready to be processed.
• PromptShowOrderCancelReasonCode - Determines whether the system
prompts the associate to select a reason code while cancelling an order.
• PromptShowOrderRejectReasonCode - Determines whether the system
prompts the associate to select a reason code when rejecting an order.
• PromptShowPickedOrderItemWarning - Determines if a prompt is displayed
during the order cancellation process informing the user that reserved items cannot
be cancelled.
• SameDayDeliveryMessageRegister - Determines which store register will receive the
message that there are orders that have been flagged as 'Same Day Delivery'. If '0' is
entered, then all store registers will receive the message.

Order Broker Configuration 25-9

Determining the Overall Order Status

• SameDayDeliveryPickupWindowTime - Determines the window of time where a

store would like Same Day Orders to be picked up by a delivery driver after the
order is ready for driver pickup.
• SetupFeeBasis - The foundation on which the setup fee amount is based, either
on the items in an order or on the order total.
Supported Values:
- ITEM
- TRANSACTION
• SetupFeeCalculation - The calculation method used to determine the setup fee
amount.
Supported Values:
- PERCENT
- AMOUNT
• SetupFeeValue - The figure used to determine the setup fee amount. A value of
zero indicates that no setup fee should be added.
Supported Values:
- For percent, a number between 1 and 100
- For amount, the dollar amount
• ShipCalcType - The basis on which a shipping fee is calculated.
Supported Values:
- PER_ITEM
- PER_TRANSACTION
• ShippingFeeOnDelayedPickup - Determines whether a shipping fee is charged
for Pick Up From This Store type orders that are placed in Xstore Point of Service. If
true, a shipping fee is charged for Pick Up From This Store type orders. If false, no
shipping fee is charged for Pick Up From This Store type orders.
• SkipSearchFormIfCustomer - Determines whether the order search form should
be skipped when entering the order module in the register and a customer is
associated with the transaction. If true, the order search form should be skipped. If
false, the order search form should be displayed.
• LocateItemDistances - A list of whole number values that are used to determine
the possible distances that the customer is willing to travel when locating an item for
an order. Supported values are whole numbers representing distances.

Determining the Overall Order Status

Order Status Description

OPEN At least one of the items has one of the following statuses: NEW,
POLLED, ACCEPTED, IN_TRANSIT, IN_TRANSIT_POLLED.

25-10 Technical Guide

 Determining the Item Status

Order Status Description

READY_FOR_PICK_UP For Legacy orders:

All items are in RESERVED (for pickup from other store order)
or RECEIVED (for pick up from this store order) status. The
order can also include cancelled and picked up items. There will
be no items with an OPEN status.
For New orders:
• For a Pick Up This Store order, all items are RECEIVED.
• For a Pick up Other Store order, all pickup items with no
inventory transfer are RESERVED and all ship for pickup
items are RECEIVED.
The order can also include cancelled and picked up items, but no
items with an OPEN status.

READY_TO_SHIP For Legacy orders:

This is applicable only for customer delivery or pick up from
this store. For customer delivery, all items must be RESERVED.
For pick up from this store, at least one item must be RESERVED
and none in the OPEN category.
For New orders:
• For Customer Delivery and Pick Up This Store, at least one
item must be RESERVED, with no OPEN items.
• For Pick Up Other Store, at least one ship-for-pickup item
must be RESERVED, with no OPEN items.

COMPLETE There are no more actionable items. At least one of the items has
been fulfilled. All other items are either fulfilled or cancelled.

CANCELLED All items are in CANCELLED status.

UNFULFILLABLE All items are UNFULFILLABLE, or a mix of UNFULFILLABLE

and CANCELLED.

Note: The FULFILLMENT_READY status used in previous versions

has been replaced by READY_FOR_PICK_UP and READY_TO_SHIP.

Determining the Item Status

Item Status Description

NEW Item Ordered - Indicates the item has been added to the order.

POLLED Item Ordered - Indicates the source/fulfilling location got the item
request.

ACCEPTED Item Ordered - Indicates the source location has confirmed it can
satisfy the order request.

Order Broker Configuration 25-11

Accepting an Order

Item Status Description

PICKED/RESERVED Item Picked and Reserved - Indicates the item has been put aside at
the source/fulfilling location for the customer or to be shipped. In
Xstore Point of Service, the status is Reserved and the action is
Pick/Reserve. In Order Broker, the status is Picked.

IN TRANSIT Item In Transit - Indicates the item has been has been shipped to the
fulfilling location. This is to differentiate it from a Delivery order
whose status is Complete after it has been shipped.

IN_TRANSIT_POLLED Item in Transit - Indicates the fulfilling location is notified that the
item has been shipped and will arrive at the store to be picked up.

RECEIVED Item Received - Indicates the item has been received in the store.

FULFILLED Item Fulfilled - Indicates the item has been picked up/delivered.

UNFULFILLABLE Item Unfulfillable - Indicates the item cannot be fulfilled from any
location.

CANCELLED Item Cancelled - Indicates the item has been cancelled.

Accepting an Order
An order can be Accepted if at least one item is in the POLLED state.

Reserving an Order
An order can be picked/reserved if at least one item is in the ACCEPTED state.

Availability Update Message to Order Broker

Whenever the available inventory for an item is updated in an Xstore Point of Service
system integrated with Order Broker, Xstore Point of Service sends a message to Order
Broker indicating the new inventory count.
A message will be sent to Order Broker for any change in inventory, including a sale,
shipping, receiving, reserving an order, reserving for layaway, and so on.

25-12 Technical Guide

 26
Collect and Receive (CaR) Configuration

Overview
This implementation is an extension of the Oracle Retail Order Broker Cloud Service
project. There is a new type of order distinguished by the delivery_service_level column
of the xom_order table. Orders where CaR functions are applicable have the value
"SAME_DAY" in that field. Those orders will be created from an external platform (Web
Order) and forwarded to Xstore via Oracle Retail Order Broker Cloud Service.
During the different phases of the processing of the order, a call to the CaR platform is
performed. CaR forwards the call to the service provider to schedule a driver for the
pickup returning some information about the confirmation and the expected pickup
time.
A "SAME_DAY" order is expected to be processed in its integrity: it is not possible to
select single lines.
Additional documents are created in Xstore for SAME_DAY orders and a different path
is expected for them.

Process Steps
Process Step Delivery Orders Same Day Delivery Orders

Accept order (no changes) Header left "OPEN" No changes

Detail set to "ACCEPTED"
OROB set to "Accepted"
Inventory: nothing

Pick/Reserve order (no Header set to No changes

changes) "READY_TO_SHIP"
Detail set to "RESERVED"
OROB set to "Picked"
Inventory: –ON_HAND
+ORDER

Collect and Receive (CaR) Configuration 26-1

Process Steps
Process Step
Ship order (changes for
Same Day orders)
Unpack (only for Same Day
orders which are not yet
collected; see below)
Package collection (only for
Same Day orders)
26-2 Technical Guide
Delivery Orders Same Day Delivery Orders
Header set to "COMPLETE" Enter "Number of packages"
Detail set to "FULFILLED" Call CaR to make Driver
booking request
OROB set to "FULFILLED"
Header set to
Inventory: –ORDER
"AWAIT_DRIVER_COLLEC
Require tracking number TION"
Print Packing Slip and Note: The
Shipping label AWAIT_DRIVER_COLLEC
TION status in unknown on
OROB environment, so it is
not sent to Oracle Retail
Order Broker Cloud
Service. It is only persisted
in Xstore. When the order is
downloaded again, the local
"AWAIT_DRIVER_COLLEC
TION" status is preserved if
the order downloaded from
Xstore is in status "Picked".
Detail no changes
OROB no changes
Inventory: nothing
Do not require tracking
number
Print packing slip and new
Shipping/Package labels
Print new Courier Delivery
Handover document
NA Header set to
"CANCELLED"
Detail set to "CANCELLED"
OROB set to
"CANCELLED"
Inventory: –ORDER
+ON_HAND
NA Header set to "COMPLETE"
Detail set to "FULFILLED"
OROB set to "FULFILLED"
Inventory: –ORDER
 Database Structures

Process Step Delivery Orders Same Day Delivery Orders

Unpack (only for Same Day NA Header set to

orders which are already "CANCELLED"
collected; see above)
Detail set to "CANCELLED"
OROB remains
"FULFILLED" (2)
Note: Because the order is
already "COMPLETE" in
Oracle Retail Order
Broker Cloud Service, the
request of cancellation fails.
As result, the order in
Order Broker Cloud
Service remains
"FULFILLED". The Order
Broker Cloud Service
system logs the requests.
This will allow manual
activities to reimburse the
customers. There is a flag to
avoid downloading the
order again when cancelled,
so the local "CANCELLED"
status is preserved.
Inventory: +ON_HAND

Database Structures
For more information about the database tables, see the XOM domain in the Oracle Retail
Xstore Point of Service Software Database Dictionary.

Spring Files Configuration

The configuration for Same Day orders can be found in the file order-locate-
beans.xml, in the config project, in the folder /locate/spring.
A bean named sameDayOrderHelper is defined in this file, the parameters are set as
properties:

Property Name Type Default Value Content

SameDayDelivery String SAME_DAY Defines the value

Level of the attribute
delivery_service_l
evel that identifies
Same Day orders

IdPrefix String POS Defines the prefix

of the DeliveryId
of an order

Collect and Receive (CaR) Configuration 26-3

Data Settings for Shipper and Shipper Method

Property Name Type Default Value Content

IdStoreFill Integer 6 Defines the

minimum size of
the store id in the
DeliveryId of an
order.
If the store id
length is less than
this value, it is left
padded with
zeros.

IdRegisterFil Integer 4 Defines the

minimum size of
the register id in
the DeliveryId of
an order.
If the register id
length is less than
this value, it is left
padded with
zeros.

UnpackNoDriver String DFP1 Defines the

ReasonCode Reason Code used
when a Same Day
order is unpacked
because it was not
picked up by the
driver.
Must be defined
in the table
com_reason_code,
with
reason_typcode
ORDER_CANCEL
_BACKOFFICE

UnpackNoCusto String null Defines the

merReasonCode Reason Code used
when a Same Day
order is unpacked
because it was
undeliverable.
Must be defined
in the table
com_reason_code,
with
reason_typcode
ORDER_CANCEL
_BACKOFFICE

Data Settings for Shipper and Shipper Method

Be sure that the ship method used (see actual_ship_method in
xom_order_line_detail table) is present in the inv_shipper and in
inv_shipper_method tables.

26-4 Technical Guide

 Carton Label

Carton Label
A new specific label for SAME_DAY orders is created: sameDayShippingLabel. This
is used in the OpChain for SAME_DAY orders when they are shipped.

Collect and Receive (CaR) Configuration 26-5

Carton Label

26-6 Technical Guide

 27
Oracle Hospitality OPERA Property
Management Configuration

Overview
This chapter provides information about the configurations that support the Oracle
Retail OPERA Property Management. This optional module can be interfaced with
Xstore Point of Service to enable the Room Charge and the Room Charge Refund as
tender options in Xstore Point of Service.

Enable the Room Charge and Room Charge Refund Tender

Follow the steps below to enable the Room Charge and the Room Charge Refund as
tender options in Xstore Point of Service:
1. Add :opera to the configPath.properties file. The file is located in the Xstore
installation directory, for example, C:\xstoredata\.
2. Add the Room Charge tender and the Room Charge Refund tender entries to the
MenuConfig.xml file. The file is located in <Xstore installation
directory>\lib\config.jar\dtv\res\config\.
Example: Room Charge Tender
<MenuItem name="SALE::TENDER_OPTIONS" text="_menuSaleTender"
displayType="LIST" category="Tender" keywords="sale_tender">
edited for brevity..................................
<MenuOption ref="SALE::TENDER_ROOM_CHARGE" />
3. If required, enable the proxy setting in the system.properties file. The file is
located in the Xstore installation directory, for example, C:\xstoredata\.
Example: Proxy Settings
browser.connection.HttpProxyHost=myhost.us.example.com
browser.connection.HttpProxyPort=80
browser.connection.UseHttpProxy=
browser.connection.NonProxyHosts=[optional]

xstore.properties
The following information must be configured in the xstore.properties file with
the details provided by the Oracle Support team:

Note: The xstore.properties file is located in <Xstore

installation directory>, for example, C:\xstoredata.

Oracle Hospitality OPERA Property Management Configuration 27-1

Overview

dtv.opera.ConnectionURL - Enter the Web Service URL provided by the Oracle

Support team.

dtv.datasource.opera.Resort - Enter the resort code.

dtv.datasource.opera.RowId - Enter the Row ID.
oracle.retail.xstore.opera.username - Enter the encrypted user name.
oracle.retail.xstore.opera.password - Enter the encrypted password.

Example: xstore.properties File

dtv.opera.ConnectionURL=
dtv.datasource.opera.Timeout=
dtv.datasource.opera.Resort=
dtv.datasource.opera.RowId=
oracle.retail.xstore.opera.username=${opera.username}
oracle.retail.xstore.opera.password=${opera.password}

27-2 Technical Guide

 28
Rotating Service Credentials for Integrated
Systems

Overview
This chapter describes how to rotate service credentials in Xstore Point of Service for
integrated systems.

Rotating Credentials
Service credentials for systems integrated with Xstore Point of Service, like Customer
Engagement or Order Broker, are stored in the data base. You can update all stores from
Xstore Office/Xstore Office Cloud Service by deploying a data file (.mnt) with the new
credentials.

Note: For more information on how to deploy data files, see the
Oracle Retail Xstore Office/Xstore Office Cloud Service User Guide.

The encrypted credential data is loaded into the database table

sec_service_credentials through the DataLoader.

Note: For more information about the

sec_service_credentials database table, see the Oracle Retail
Xstore Office/Xstore Office Cloud Service Database Dictionary. For more
information on the DataLoader record type SERVICE_CREDENTIALS,
see the Oracle Retail Xstore Point of Service Host Interface Guide.

Each record needs to include the system/service, the effective and expiration date, the
encrypted user name and password. The effective and expiration dates allow you to load
the new credentials ahead of time for an easier rotation. Multiple credentials per system/
service can exist. Xstore Point of Service will use the most recently effective credentials
that are not yet expired when connecting to a system/service. A credential is considered
valid if its effective date is a date earlier than the current date and its expiration date is
after the current date.

Important: If one of the integrated services, like Customer

Engagement or Order Broker, is a cloud service the password needs to
be rotated every 120 days. If you do not rotate the password in time,
you will not be able to use the service.

Rotating Service Credentials for Integrated Systems 28-1

Rotating Credentials

Note: If the store is “Cloud” enabled, then the store’s OAuth Client
credentials will be rotated on a regular schedule.

If credentials are stored in both the database and the system.properties file for the
same service ID, Xstore Point of Service will use the credentials stored in the database. If
there are no credentials stored in the database, the system will retrieve the credentials
from the system.properties file, if available.
Valid entries for the service_id field in the sec_service_credentials table are
the service IDs defined in the ServiceHandlers.xml. However, it is possible for more
than one service to share the same credentials between them. In that case you need to
configure them in the following map, so that the credential provider knows how to map
a given service ID to a credential ID.

Note: This is not required if the service does not share its credentials
with other services.

Example: credeintialIdMapping
<!-- Note: This map is used to specify a set of services which share the
same authentication credentials. -->
<property name="credentialIdMapping">
<props>
<prop key="RELATE_CUSTOMER_WS">RELATE</prop>
<prop key="RELATE_CARD_WS">RELATE</prop>
<prop key="RELATE_LOYALTY_WS">RELATE</prop>
<prop key="RELATE_AWARD_WS">RELATE</prop>
<prop key="RELATE_PROMOTION_WS">RELATE</prop>
<prop key="RELATE_REGISTRY_WS">RELATE</prop>
<prop key="RELATE_ATTRIBUTE_WS">RELATE</prop>
<prop key="RELATE_TASK_WS">RELATE</prop>
<prop key="RELATE_GIFT_CARD_SVC_TRANSACTION_WS">RELATE</prop>
<prop key="RXM_DIGITAL_CART">RXM_APPLICATION</prop>
<prop key="RXM_ASSOCIATED_ITEMS">RXM_APPLICATION</prop>
<prop key="RXM_ITEM_INFORMATION">RXM_APPLICATION</prop>
<prop key="SIM_STORE_INVENTORY">SIM</prop>
<prop key="SIM_POS_TRANSACTION">SIM</prop>
<prop key="SIM_UIN_STORE_INVENTORY">SIM</prop>
</props>
</property>
...
If the credentials are still stored in the system.properties file (not recommended),
add a new entry to the alternativeServiceCredentialsMap property as shown
in the example below.
Example:

28-2 Technical Guide

 Rotating Credentials

<bean id="serviceCredentialProvider"
class="dtv.servicex.impl.ServiceCredentialProvider" init-method="init"
depends-on="dataFactoryAssistant">
...
...
<!-- AlternativeServiceCredentialMap is intended to use as an alternative
way to provide credentials for the services by retrieving them via system
properties. Note: This should only be used in Xstore version 17 and
older. -->
<property name="alternativeServiceCredentialMap">
<map>
<entry key="RELATE">
<bean
class="dtv.servicex.impl.ServiceCredentialProvider.ServiceCredentials">
<constructor-arg index="0"
value="#{systemProperties['dtv.test.username']}" />
<constructor-arg index="1"
value="#{systemProperties['dtv.test.password']}" />
</bean>
</entry>
</map>
</property>
</bean>

Rotating Service Credentials for Integrated Systems 28-3

Rotating Credentials

28-4 Technical Guide

 29
Email Customer Receipts

Overview
Xstore Point of Service provides the ability to automatically send specified receipts from
a retail transaction to a customer’s valid email address. After a retail transaction is
completed, any receipts configured to be emailed will be rendered as PDF documents,
and sent to the customer's email address as email attachments. If desired, a watermark
can be applied to the PDF receipt images, typically to note them as copies of the original
receipts. (Receipts may also be printed at the store).
The recipient of the email will receive it in a reasonable time following the transaction.
The sales receipt document can be printed using a standard document printer. This PDF
receipt cannot be edited and there is no mechanism in place for allowing the customer to
respond to the email.
To use this feature, the customer must have an active email address and permission to
receive email from the store on file. (These values can be set up and maintained in Xstore
Point of Service Customer Maintenance).

About this Chapter

This chapter describes how to set up Xstore Point of Service configuration files for email
sale receipts and describes the process Xstore Point of Service uses to determine whether
an email receipt should be created.

Email Customer Receipts 29-1

Set Up Email Receipts

Set Up Email Receipts

All the setup required for this function is handled in the configuration files.
1. In RcptConfig.xml, set email=”true” for the specific receipts to be emailed to
customers, regardless of transaction type.
<receipts>
<receipt document=”WARRANTY_RECEIPT"
sectionref="WARRANTY_RECEIPT" email="true"/>
<receipt document="TAXEXEMPT_STORECOPY"
sectionref="StoreCopy"/>
<receipt document="CUSTOMER" sectionref="CustomerCopy"
email="true"/>
edited for brevity..................................
</receipts>
When email is set to true, this receipt can be emailed to the customer, in addition to
being printed, if configured to do so.

Note: To avoid duplicate receipts (email and print), the Store Credit,
Gift Certificate, and Coupon receipt types should not be configured to
allow “email” and “email & print” options.

2. In config.jar\dtv\res\config\, configure the

emailTemplate.properties file. See “emailTemplate.properties Example” for
more information.
3. In config.jar\dtv\res\config\email, configure the EmailReceipt.vm file.

4. Set up the SysConfig.xml file. See “SysConfig.xml Example” for more information.

Note: Substitute appropriate values for the host, port, auth, user,
password, default sender and default recipient fields as needed for
your organization.

EmailReceipt.vm Example
#set ($subject = "Receipt from your recent purchase")
The receipts from your recent purchase are attached. Thank you for
shopping with us!

Figure 29-1: Email Contents

29-2 Technical Guide

 Set Up Email Receipts

emailTemplate.properties Example
_emailReceipt=dtv/res/config/email/EmailReceipt.vm
_emailErrorInfo=dtv/res/config/email/ErrorInfo.vm
_emailPriceOverride=dtv/res/config/email/PriceOverride.vm
_emailTaxOverride=dtv/res/config/email/TaxOverride.vm
_emailReceivedOrder=dtv/res/config/email/OrderReceived.vm
_emailAllocatedOrder=dtv/res/config/email/OrderAllocated.vm
_emailShippedOrder=dtv/res/config/email/OrderShipped.vm
_emailReservedOrder=dtv/res/config/email/OrderReceived.vm

SysConfig.xml Example
<Setting name="Email---
DefaultRecipient">storeManager@thisOrg.com</Setting>
<Setting name="Email---Receipt---AlwaysPromptToEmail">true</
Setting>
<Setting name="Email---Receipt---From">_receiptEmailFrom</
Setting>
<Setting name="Email---Receipt---LineCharacterCount">80</Setting>
<Setting name="Email---Receipt---LineStyle">Andale Duospace WT</
Setting>
<Setting name="Email---Receipt---
SaveUpdatedEmailAddressToCustomer">true</Setting>
<Setting name="Email---Receipt---SendEmailReceipts">true</
Setting>
<Setting name="Email---Receipt---Subject">_receiptEmailSubject</
Setting>
<Setting name="Email---SmtpDebug">false</Setting>
<Setting name="Email---TestingModeAddressFilter">@oracle.com,</
Setting>
<Setting name="Email---UseTLS">true</Setting>
<Setting name="Email---UseTestingMode">true</Setting>
• UseTLS - If true, Xstore Point of Service will use TLS keys to encrypt
communications with the mail server.
• DefaultMailUser - Username to use if making secure SMTP connections.
• DefaultMailPassword - Password to use if making secure SMTP connections.
• SmtpDebug - If true, and logger severity is set to DEBUG, Xstore Point of Service
will log SMTP debug messages to the console.
• DefaultRecipient - The default email recipient.
• UseTestingMode - USED FOR TESTING ENVIRONMENTS ONLY!---Set this
value to true for Dev and QA testing to ensure that emails are not sent to live
customer email addresses. When set to true, emails are only sent when the email

Email Customer Receipts 29-3

Always Send Email Receipts Flag

address contains any string from the TestingModeAddressFilter setting. When

set to false, all emails will be delivered regardless of the target email address.
• TestingModeAddressFilter - USED FOR TESTING ENVIRONMENTS ONLY!--
-A comma-separated string used when UseTestingMode is set to true to ensure
that only email addresses containing any of these sub-strings are delivered.
• SendEmailReceipts - The global on/off switch for sending email receipts. Set to
true to enable the functionality. Receipts are emailed to customers if the receipt is
configured as an email receipt (RcptConfig).
• AlwaysPromptToEmail - If true, always prompt to email if any emails need to be
emailed. (If true, it won’t matter if the customer’s email permission flag is set to “No”. The
customer will still be asked if they want an email receipt).
If false, check the customers "permission to email" flag:
- if “permission to email" flag is false, the email options are not displayed
- if “permission to email" flag is true, prompt for a receipt method
• SaveUpdatedEmailAddressToCustomer - If true, prompt to save updated email
address to the current Customer Profile. If false, do not prompt or save the updated
email address to the Customer Profile.
• Subject - Translation key for the subject line of receipt emails. Specify this value in
translations_en.properties.
• From - Translation key for the sender name of receipt emails. Specify this value in
translations_en.properties.
• LineStyle - Specifies the font family and size for email receipt text.
• Watermark - Path to BMP image to use as the watermark for receipt PDFs attached
to receipt emails. If empty, no watermark will be applied.

Always Send Email Receipts Flag

This functionality provides the ability to always have receipts emailed to a customer
when tendering by automatically triggering the email receipt process without
prompting for receipt options.
The transaction tender process checks crm_party.email_rcpts_flag on the
customer to determine if receipts should be emailed to the customer.
If this flag is "YES" then the receipt will automatically be emailed to the customer and the
associate will not need to ask the customer on every transaction. The email receipt
button will be hidden; however, the system will still ask if a receipt should be printed.
This option is set up in Xstore Point of Service Customer Maintenance. The default value
is "No" for new customers.

Figure 29-2: Email Receipts Field in Xstore Point of Service Customer maintenance

29-4 Technical Guide

 Always Send Email Receipts Flag

Xstore Point of Service Setup

This functionality is enabled when the crm_party.email_rcpts_flag is set to true.
If set to true for the customer, an additional sentence displays on the print receipt prompt
"A copy of the receipt will be emailed to the customer" when the associate is tendering
the transaction.
If set to false, then the system prompts the associate to email or print the receipts.

Customer Engagement Cloud Services Setup

Email receipt functionality must also be set up in Customer Engagement Cloud Services
as a customer attribute with the name EMAIL_RCPT_FLAG. It must be editable, set to
open access, and type of Character.
In addition, the “unique” flag in Customer Engagement Cloud Services should be set to
false on any attributes. (When set to true, only one customer can have a given value).
The email receipts attribute must be added to all customer records in Customer
Engagement Cloud Services so that when the customer is handed back and forth
between the systems, the flag will be maintained.

Email Customer Receipts 29-5

The Email Receipt Process in Xstore Point of Service

The Email Receipt Process in Xstore Point of Service

Note: We are assuming at this point that the customer has passed the
check for the Email Contact Flag if the system is configured to "Follow
the Permission Flag". (See AlwaysPromptToEmail on page 4).

After tendering the sale, the user is prompted to select a receipt method.

• If crm_party.email_rcpts_flag set to false • If crm_party.email_rcpts_flag set to true

Sale Complete Prompt Sale Complete Prompt

The choice made here applies to all receipts. (You Back = Return to the “Sale Complete?” prompt.
cannot print one receipt but email the other). Any Email Only = Send the email receipt, do not print
receipt types that are not supported for distribution in
one. Transaction is now complete.
an email will automatically print on the receipt
printer. Print & Email = Print the receipt and send the email.
Transaction is now complete.
• Print Only = Print the receipt(s) rather than
sending an email copy. All receipts will be printed
on the receipt printer and the transaction is
complete.
• Email = Email the receipt(s) to the customer.
Continue with “Email Receipt method
options”.

29-6 Technical Guide

 The Email Receipt Process in Xstore Point of Service

Email Receipt method options

When the Email option is selected, this prompt is displayed:

Figure 29-3: Send Email Receipt Prompt - Email Address On File Example

• If an email address is on file, it is displayed and allows edits.

• If there is no email address on file then “<enter email address>” is displayed.
The email address will be validated based on the following validation rules:
- must have 1 and only 1 @ sign
- text in front of the @ sign must have at least 1 legal character and cannot include
any of the following: <,>,(,),[,],,,;,:,@
- text in front of the @ sign cannot contain any spaces or tabs
- text in front of the @ sign can contain periods, but they must be preceded and
followed by a valid character and cannot be doubled up
- text after the @ sign must include a well-formed host name. A well-formed host
name must be made up of one or more repeating sections followed by an ending
section. The repeating sections must be made up of one or more letters (a-z, A-
Z), digits (0-9), and/or dashes (-) followed by a single period. The ending section
must contain at least two letters (a-z, A-Z)

Note: If a new email address is entered, or the existing email address

is updated, the system may prompt whether to save the email address
to the Customer Profile if configured to do so. (See
SaveUpdatedEmailAddressToCustomer on page 4).
This prompt displays only if configured and if there is a customer
attached to the transaction. If the system is not set up to prompt to save
the email address, the email address is not saved to the customer
profile.

Send email receipt options

Cancel Email = Return to the “Sale Complete?” prompt.
Ok Email Only = Send the email receipt, do not print one. Transaction is now complete.
Ok Print & Email = Print the receipt and send the email. Transaction is now complete.

Email Customer Receipts 29-7

Enhanced Email Receipt

Enhanced Email Receipt

This section describes the enhanced email receipt.

Overview
Numerous Third-Party Email Receipt providers are available for creating and emailing
professional digital receipts to customers.
Digital receipts are usually created starting from a dataset of information. If Xstore is
configured to manage third-party email receipts, the e-mail function is selected at
transaction completion, instead of sending the Xstore receipts via email to the customer,
a JSON payload will be stored as transaction attachment. This information is replicated,
as usual, in Xcenter. In this environment, a specific broadcasting function makes the
information available for third-parties to use for the enhanced e-mails.

Xadmin - Enablement
The new base feature can be enabled on Xadmin.

Figure 29-4: Xstore Office (Xadmin) - Base Features

The config path in ConfigPath.xml is: :enhancedemail.

Xstore - Payload Creation

When the new feature is enabled, the user experience does not change.
The only difference is that, instead of sending the Xstore receipts via mail, the
application will create a JSON payload which contains all the information required to
build the receipts.
The payload will be stored as transaction attachment (trn_trans_attachment table), with
attachment type JSON_EMAIL_RECEIPT. The attachment_data column will contain the
JSON payload.

Payload Detail
The payload has a main section which includes:
• The main transaction data (transaction key, totals, email address, barcode);
• The workstation\store\legal entity information;
• The customer information;

29-8 Technical Guide

 Enhanced Email Receipt

• The item lines (which include the line data, the item information, the tax detail of the
line, the discount detail of the line);
• The tender lines;
• The tax lines;
• The related transactions information;
• The oupons detail;
• The gift receipts detail;
• The customer accounts information (send sale, warranty, work order, layaway,
special order);
• The order information (header, lines, payments);
• The country specific data (transaction signature, fiscal number, QR code content, ...);
and
• The airport\flight specific data (if the airside function is enabled).
All the extended properties are included by default, but it is possible to change the
behavior acting on spring configuration (for detail see the Payload Implementation
section).
The JSON schema defined for the payload is available as enhancedEMail.schema.json
under res\json in the customer overlay folder.

Payload Implementation

Extended Properties
It is possible to customize the behavior of the payload creation for the extended
properties of the different objects.
Consult the file enhancedemail-beans.xml (config\config\enhancedemail\spring).
The bean emailReceiptProperties is used to define a list of extended properties
that will be excluded from (or included in) the payload creation.
If the value of the property excludedProperties is true, the properties in the list
will be excluded from the payload and all the properties not included in the list will be
exported; if the value is set to false, the properties in the list will be included in the
payload and all the properties not included in the list will be ignored.
The bean trnPropertyCustomerEmailUpdated is an example about how to create
custom beans for the properties that need to be included in the list.

Spring Configurations
<!-- List of extended properties to be included or excluded from
the payload¬->
<bean id="emailReceiptProperties"
class="oracle.retail.xstore.emailrcpt.properties.EmailReceiptProp
erties" scope="prototype">
<property name="excludedProperties" value="true" />
<property name="properties">
<list>

Email Customer Receipts 29-9

Enhanced Email Receipt

<ref bean="itemPropertyEsTaxFreeDivaCode" />

<ref bean="itemPropertyFrTaxFreeCustomsCode" />
<ref bean="itemPropertyPtTaxFreeCustomsCode" />
<ref bean="customerPropertyPromptToJoinLoyalty" />
<ref bean="trnPropertyFrDocSigVersion" />
<ref bean="trnPropertyFrPostFlag" />
<ref bean="trnPropertyFrSigSource" />
<ref bean="trnPropertyFrDocSig" />
<ref bean="trnPropertyFrDocNumber" />
<ref bean="trnPropertyFrDocType" />
<ref bean="trnPropertyFrIntDocType" />
<ref bean="trnPropertyFrSigSaleType" />
<ref bean="trnPropertyCustomerEmailUpdated" />
</list>
</property>
</bean>
<bean id="trnPropertyCustomerEmailUpdated"
class="oracle.retail.xstore.emailrcpt.properties.EmailReceiptProp
erty"> <property name="propertyObject"
value="dtv.xst.dao.trl.IRetailTransaction" />
<property name="propertyCode" value="CUSTOMER_EMAIL_UPDATED" />
</bean>

Price Modifiers
It is possible to configure a list of price modifiers that don't need to be exported.
Consult the file enhancedemail-beans.xml (config\config\enhancedemail\spring).
The bean excludedPriceModifiers is used to define the list of the price modifiers
reason codes that will not be exported.

Spring Configurations
<!-- List of price modifiers to be excluded from the payload-->
<util:list id="excludedPriceModifiers" value-
type="java.lang.String"
scope="prototype">
<value>PROMPT_PRICE_CHANGE</value>
<value>PRICE_OVERRIDE</value>
<value>REFUND_PRORATION</value>
<value>CALCULATED_WARRANTY_PRICE</value>
</util:list>

29-10 Technical Guide

 Enhanced Email Receipt

Xcenter - Long Poll Broadcaster

The JSON payload stored as transaction attachment will be accessible by third party only
via REST (long-poll broadcaster) and it will be done from Xcenter, not from Xstore.
Additional information can be found in the Oracle Retail Xstore Suite Service Guide.

Email Customer Receipts 29-11

Enhanced Email Receipt

29-12 Technical Guide

 30
Rain Check Setup & Configuration

Overview
This chapter provides information about setting up rain check functionality. Rain checks
are issued to customers that request an item that is out of stock. It allows the customer to
purchase the item at today's price at a later date (once stock is replenished). This is often
done because the retailer has temporarily sold out of an item that is/was selling at a
discounted price — this way, consumers can still receive the item and the discount.
In its physical form, a rain check is a slip of paper that identifies an item and its price.
This slip includes a barcode that can be scanned by a sales associate at the time of
redemption. It also includes the retailer's rain check policy and time limits.
Rain checks are consumable; meaning that once the customer uses the rain check, it
cannot be used again.

Assumptions
• Rain check functionality must be enabled.
• Rain checks are not issued as part of a transaction.
• Rain checks are consumable and can only be redeemed once.
• Rain checks are not issued for deals.
• Rain checks are printed from Item Lookup; therefore, only a single item is printed on
a rain check. Multiple items cannot exist on the same rain check.
• Rain checks are not allowed for items using prompt for price pricing.
• Rain checks are not allowed for items that do not have pricing available for a
quantity of one.
• Rain checks are not allowed for non-merchandise items.

Rain Check Setup & Configuration 30-1

Rain Check Configuration

Rain Check Configuration

SysConfig.xml Configuration
The following rain check configuration options are available in SysConfig.xml.
<Setting name="RainCheck---ExpirationDays">30</Setting>
<Setting name="RainCheck---FeatureEnabled">false</Setting>
<Setting name="RainCheck---QuantityLimit">1</Setting>
<Setting name="RainCheck---RedeemAnyStore">false</Setting>
FeatureEnabled - Determines whether an organization uses rain check functionality.
When set to true, rain check functionality is enabled. Base Default value = false.
ExpirationDays - Determines when the rain check will expire based on a length of
time—in days—from its initial print. An entry of 0 (zero) means that rain checks do not
expire. When > 0, the rain check expiration date is calculated by adding the specified
number of days to today's business date. Base Default value = 30 days.
RedeemAnyStore - Determines whether a rain check can be redeemed at stores other
than the store that issued it. When set to true, a rain check may be redeemed at any store
in the chain; when set to false, the rain check must be redeemed at the store where it was
issued. Base Default value = false.
QuantityLimit - Determines the limit for the item quantity on a rain check. When set
to greater than 0 (zero), the quantity of the specified item is limited to the value specified
here when the rain check is redeemed. When set to 0 (zero), no quantity limit is enforced.
Most commonly set to 1, for one item per rain check. Base Default value = 1.

Database Tables
The database tables trn_raincheck and trn_raincheck_trans store rain check
information. In addition, trn_trans, the standard base table for any Xstore Point of
Service transaction, also contains information about the rain check.

Note: Rain check information is also written to the POS Log.

For information about these tables, see the Xstore Point of Service Database Dictionary.

sec_privilege Table
In the table sec_privilege, “PRINT_RAIN_CHECKS” security privilege must be set
up to identify users with rain check privileges. See Chapter 12, “Security Configuration”
for more information.

com_receipt_text Table
In the table com_receipt_text, define any arbitrary text (typically "terms and
conditions") related to every rain check receipt.

itm_item Table
In the table itm_item, disallow_rain_check is used to determine whether an item
is eligible for a rain check. For example, this option can be used to prevent associates
from printing rain checks for items that may be discounted with the goal of depleting
stock and never reordering.

30-2 Technical Guide

 Rain Check Configuration

See “Item Setup Overview” in Chapter 5, “Item and Pricing Configuration” for more
information about this table/column.

Receipt Setup
Receipt text contains the following information:
- The information of the store that issued the rain check.
- The rain check's item ID and description.
- The rain check's item's price.
- The rain check's expiration date.
- The rain check's quantity limit (if one exists).
- A bar code containing the rain check ID.
- Rain check terms and conditions.
Rain check receipts are configured in RcptConfig.xml.
<receipt document="RAIN_CHECK" sectionref="RainCheck"/>
...
<ReceiptCopyRule name="RAIN_CHECK" document="RAIN_CHECK">
<Rule
class="dtv.pos.hardware.rcptbuilding.copyrules.TransactionTypeRul
e" type="RAIN_CHECK"/>
</ReceiptCopyRule>
...
<section name="RainCheck">
<sectionref>header</sectionref>
<row align="C" charsize="X2HW">
<field method="getTransactionTypeCode"
formatter="TranType"/>
</row>
<row/>
<row align="L">
<field text="_itemId"/>
<field text=": "/>
<field method="getRainCheck.getItemId"/>
</row>
<row align="L">
<field method="getRainCheck.getItemDescription"
formatter="ItemDescriptionLength"/>
</row>
<row align="L">
<field text="_price"/>

Rain Check Setup & Configuration 30-3

Rain Check Configuration

<field text=": "/>

<field method="getRainCheck.getSalePrice"
formatter="MONEY"/>
</row>
<sectionref>raincheck_expiration_date</sectionref>
<sectionref>raincheck_qty_limit</sectionref>
<row/>
<barcode symbology="Code 93">
<field method="getRainCheck.getRainCheckId"/>
</barcode>
<sectionref>system_mode</sectionref>
<sectionref>RAIN_CHECK_TERMS</sectionref>
<sectionref>page_break</sectionref>
</section>
<section name="raincheck_expiration_date">
<condition method="getRainCheck.getExpirationBusinessDate"
comparison="NOT_NULL"/>
<row align="L">
<field text="_receiptRainCheckExpirationDate"/>
<field text=": "/>
<field method="getRainCheck.getExpirationBusinessDate"
formatter="DateShort"/>
</row>
</section>
<section name="raincheck_qty_limit">
<condition method="getRainCheck.getQuantityLimit"
comparison="GREATER_THAN_ZERO"/>
<row align="L">
<field text="_receiptRainCheckQuantityLimit"/>
<field text=": "/>
<field method="getRainCheck.getQuantityLimit"/>
</row>
</section>
<section name="RAIN_CHECK_TERMS">
<row/>
<sectionref>RAIN_CHECK_TERMS_DB</sectionref>
<row/>
</section>

30-4 Technical Guide

 Rain Check Configuration

...
Database-driven receipt data:
<section name="RAIN_CHECK_TERMS_DB"
dbRef="RAIN_CHECK_TERMS::DEFAULT::getBusinessDate"/>

Rain Check Setup & Configuration 30-5

Rain Check Configuration

30-6 Technical Guide

 31
Customer Account Configuration

Overview
Configurable Customer Accounts (CCAs) provide the ability to define unique customer
account types, giving retailers the flexibility to manage account types with different
business rules.
For example, a PRESALE customer account type may be set up so that customers can
pay for items and “reserve” them before they officially go on sale.
Another example of a Configurable Customer Account is an ONHOLD customer
account type. This account can be used to offer customers the service of holding
merchandise for a short time so they can return to the store later to pick it up.
Setting up a Configurable Customer Account requires both database entries and
configuration file entries.

Note: PRESALE is used as an example throughout this chapter.

Database Setup for CCA

The following tables require data for CCAs:
• inv_bucket
• inv_location_bucket
• itm_item
• itm_non_phys_item
• itm_item_prices
• tnd_tndr_availability
• dsc_discount_type_eligibility
• sec_privilege
For information about these tables and the Dataloader records used to load them, see the
Xstore Point of Service Database Dictionary and the Xstore Point of Service Host Interface
Guide.

Configuration File Setup for CCA

This section provides information about setting up a sample CCA named “Pre-Sale”.

Customer Account Configuration 31-1

Configuration File Setup for CCA

Entries are required in the following configuration files:

• “translations.properties” • “SequenceConfig.xml”

• “resources.properties” • “PreFlightQueryConfig.xml”

• “MenuConfig.xml” • “InputConfig.xml”

• “ActionConfig.xml” • “EventConfig.xml”

• “OpChainConfig.xml” • “CustomerAccountConfig.xml (PRESALE

Example)”

• “RcptConfig.xml”

translations.properties

Add CCA-specific translations

_menuCustAcctPreSale=Pre-Sale (referenced in MenuConfig.xml)
_ccaPreSale=Pre-Sale (referenced in CustomerAccountConfig.xml)
_ccaPresaleComplete=Exit Pre-Sale (referenced in
ActionConfig.xml)
_ccaPresaleCancel=Cancel Pre-Sale (referenced in
ActionConfig.xml)
_dtv.pos.customer.account.type.CustomerAccountType.PRESALE=Pre-
Sale
_dtv.pos.customer.account.type.CustomerAccountType.PRESALE.sortOr
der=110
_emailReceiptType.PRESALE_ACCOUNT=PreSale
_emailReceiptType.PRESALE_ACCOUNT_MAIN_STORE=PreSaleStore

resources.properties

Add a help message reference from CustomerAccountConfig.xml

_helpMsg_cca_Presale=Pre-Sale_Account.htm

MenuConfig.xml

Add a MenuOption reference to PRESALE action to

RETAIL::SPECIAL_ACCOUNTS menu
<MenuOption ref="PRESALE" />

Add COMPLETE and CANCEL action references to

CUSTOMER_ACCOUNT menu
<MenuItem name="CUSTOMER_ACCOUNT" text="_menuCustomerAccount"
category="Retail"
keywords="universal,register_all,customer_account">
<MenuOption>
<Action ref="PRESALE::COMPLETE" />

31-2 Technical Guide

 Configuration File Setup for CCA

</MenuOption>
<MenuOption>
<Action ref="PRESALE::CANCEL" />
</MenuOption>
<SubMenu actionRef="CUSTOMER_ACCOUNT::MENU.MODIFY_ACCOUNT"
sticky="false">
<SubMenu actionRef="CUSTOMER_ACCOUNT::MENU.ADD_DISCOUNT"
displayType="LIST">
<MenuOption ref="CUSTOMER_ACCOUNT::ADD_DISCOUNT" />
<MenuOption ref="CUSTOMER_ACCOUNT::ADD_GROUP_DISCOUNT" />
<MenuOption ref="CUSTOMER_ACCOUNT::ADD_AWARD_DISCOUNT" />
</SubMenu>
<SubMenu actionRef="CUSTOMER_ACCOUNT::MENU.MODIFY_LINE">
<MenuOption ref="CUSTOMER_ACCOUNT::CHANGE_LINE_PRICE" />
<MenuOption ref="CUSTOMER_ACCOUNT::VOID_LINE" />
<MenuOption ref="CUSTOMER_ACCOUNT::VOID_DISCOUNT" />
</SubMenu>
</SubMenu>
<MenuOption ref="CUSTOMER_ACCOUNT::PICKUP_LINE" />
<MenuOption>
<Action ref="CUSTOMER_ACCOUNT::COMPLETE.TO_TENDERING" />
<Action ref="CUSTOMER_ACCOUNT::COMPLETE.NO_TENDERING" />
</MenuOption>
</MenuItem>

Customer Account Configuration 31-3

Configuration File Setup for CCA

ActionConfig.xml

Add entries as shown below

<Action name="PRESALE" category="Register" keywords="sale"
text="_menuCustAcctPreSale" chainKey="PRE_PRESALE_CHAIN" />
<Action name="PRESALE::COMPLETE" category="Customer Account"
keywords="customer_account" text="_ccaPresaleComplete"
ref="CUSTOMER_ACCOUNT::COMPLETE">
<VisibilityRule
class="dtv.pos.customeraccount.op.visibilityrules.CustomerAccount
TypeVisibilityRule" type="PRESALE" />
</Action>
<Action name="PRESALE::CANCEL" category="Customer Account"
keywords="customer_account" text="_ccaPresaleCancel"
ref="CUSTOMER_ACCOUNT::CANCEL">
<VisibilityRule
class="dtv.pos.customeraccount.op.visibilityrules.CustomerAccount
TypeVisibilityRule" type="PRESALE" />
<VisibilityRule
class="dtv.pos.customeraccount.op.visibilityrules.AllowCancelCust
omerAccountAccCheck" />
<VisibilityRule
class="dtv.pos.customeraccount.op.visibilityrules.CCAStatusVisibi
lityRule" status="NEW" inverted="true" />
</Action>

OpChainConfig.xml

Add a starting point for a CCA

<OpChain name="PRE_PRESALE_CHAIN">
<Command class="dtv.pos.customer.account.common.CustAcctCmd" />
<Operation
class="dtv.pos.customeraccount.op.InitCustAcctConfigCmdOp">
<Parameter name="CustomerAccountType" value="PRESALE" />
</Operation>
<OpChainLink chainKey="PRE_CUSTOMER_ACCOUNT_CHAIN" />
</OpChain>

31-4 Technical Guide

 Configuration File Setup for CCA

RcptConfig.xml

Add receipt copy rules

<ReceiptCopyRule name="PRESALE_ACCOUNT"
document="PRESALE_ACCOUNT">
<Rule
class="dtv.pos.hardware.rcptbuilding.copyrules.ConfigurableCustAc
ctTypeRule" type="PRESALE" />
</ReceiptCopyRule>
<ReceiptCopyRule name="PRESALE_ACCOUNT_MAIN_STORE"
document="PRESALE_ACCOUNT_MAIN_STORE">
<Rule
class="dtv.pos.hardware.rcptbuilding.copyrules.ConfigurableCustAc
ctTypeRule" type="PRESALE" />
</ReceiptCopyRule>

Added receipts
<receipt document="PRESALE_ACCOUNT"
sectionref="CONFIGURABLE_CUSTOMER_ACCOUNTS" email="true" />
<receipt document="PRESALE_ACCOUNT_MAIN_STORE"
sectionref="CONFIGURABLE_CUSTOMER_ACCOUNTS_MAIN_STORE" />

SequenceConfig.xml

Add entry for CCA

<Sequence name="PRESALE" ref="_COMMON_">
<FileName dtype="String">presale.seq</FileName>
<Prefix dtype="String">P</Prefix>
</Sequence>

PreFlightQueryConfig.xml

Add entry for CCA

<Query name="PREFLIGHT.SEQ_PRESALE" pmType="PREFLIGHT_SEQUENCE">
<QueryHandler
dtype="Class">dtv.data2.access.query.SqlQueryHandler</
QueryHandler>
<SQL>
<Statement dtype="String"><![CDATA[select cust_acct_id,
organization_id, cust_acct_code from cat_cust_acct where
organization_id = ? and cust_acct_code = 'PRESALE' and
cust_acct_id >= ? and cust_acct_id LIKE ?]]></Statement>
<Parameter name="argOrganizationId" />
<Parameter name="argNextSequence" />

Customer Account Configuration 31-5

Configuration File Setup for CCA

<Parameter name="argPattern" />

</SQL>
<Property value="1" key="MaxRows" />
<Suffix dtype="String"><![CDATA[order by cust_acct_id
desc]]></Suffix>
</Query>

InputConfig.xml

Add entry for barcode scan

<InputType name="PRESALE_SCAN">
<Event
dtype="Class">dtv.hardware.events.ConfigurableCustAcctScanEvent</
Event>
<Type dtype="String">INPUT_CCA_PRESALE_ID</Type>
<InputRuleList>
<InputRule RuleType="ScannerSourceRule"/>
<InputRule RuleType="RangeRule">
<Parameter name="range_start" value="P"/>
<Parameter name="range_end" value="P"/>
</InputRule>
<InputRule RuleType="LengthRule">
<Parameter name="length" value="14"/>
</InputRule>
</InputRuleList>
</InputType>

Add entry in ProcessingOrder section

<Name dtype="String">PRESALE_SCAN</Name>

EventConfig.xml

Add entry to SELLING EventActionMap section

<EventAction priority="60">
<Event class="dtv.hardware.types.InputType"
name="INPUT_CCA_PRESALE_ID" />

Note: Name must be in the format of: INPUT_CCA_<new CCA

name>_ID.

<Action chainKey="PRE_PRESALE_CHAIN" chainType="START" />

</EventAction>

31-6 Technical Guide

 Configuration File Setup for CCA

Add entry to CUST_ACCOUNT EventActionMap section

<EventAction priority="140">
<Event class="dtv.hardware.types.InputType"
name="INPUT_CCA_PRESALE_ID" />
<Action chainKey="PRE_PRESALE_CHAIN" chainType="START" />
</EventAction>

CustomerAccountConfig.xml (PRESALE Example)

<?xml version="1.0" encoding="UTF-8"?>
<CustomerAccounts dtype="Root" xmlns:xsi="http://www.w3.org/2001/
XMLSchema-instance"
xsi:noNamespaceSchemaLocation="CustomerAccountConfig.xsd">
<Account name="PRESALE">
<Text dtype="Translatable">_ccaPreSale</Text>
<HelpKey dtype="Translatable"
bundle="dtv.pos.i18n.help">_helpMsg_cca_Presale</HelpKey>
<ColorGroup bgColor="0x660066" bgColor2="0xB400B4"/>
<ComponentGroup ref="PURPLE"/>
<DepositFeeType dtype="String">TRANSACTION</DepositFeeType>
<DepositFixedAmount dtype="BigDecimal">0</
DepositFixedAmount>
<DepositPercentage dtype="BigDecimal">100</
DepositPercentage>
<AllowItemNotOnFile dtype="Boolean">false</
AllowItemNotOnFile>
<ItemNotOnFileDefaultId dtype="String">9999999</
ItemNotOnFileDefaultId>
<NotifyForItemNotOnFile dtype="Boolean">true</
NotifyForItemNotOnFile>
<AllowPartialPickups dtype="Boolean">false</
AllowPartialPickups>
<AllowInventoryBucketMovement dtype="Boolean">true</
AllowInventoryBucketMovement>
<InventoryBucketId dtype="String">PRESALE</
InventoryBucketId>
</Account>
</CustomerAccounts>
<Text> — A translation key corresponding to a translations_en.properties file
entry, used to display a description of the customer account type in various areas of the
system.
<HelpKey> — An optional entry for an htm help page specific to the configured
customer account type. This is a translation key that corresponds to an entry in the

Customer Account Configuration 31-7

Configuration File Setup for CCA

resources.properties file. (See Chapter 35, “Context-Sensitive Help” for more

information).
<ColorGroup> — The color to use throughout the system to represent this customer
account type.
<ComponentGroup> — The reference to a component group which defines the color of
various background panels, and the color of the focusbar to use for the customer account
type. (See ComponentGroupConfig.xml file below).
<DepositFeeType> — The deposit calculation method.
- TRANSACTION - Calculation method is based on the entire account
- ITEM - Calculation method is based on each item
<DepositFixedAmount> — The deposit amount the system requires when setting up
or adding items to the account. This fixed amount is charged per retail transaction per
CCA account.
<DepositPercentage> — The deposit amount the system requires when setting up or
adding items to a CCA account. The deposit amount is calculated based on this
percentage of the newly added items total.
<AllowItemNotOnFile> — Determines whether the system allows associates to sell
items that cannot be found in the database in a retail transaction.
<ItemNotOnFileDefaultId> — The default identifier used for items that cannot be
found in the database.
<NotifyForItemNotOnFile> — Determines whether the system notifies the
associates with a prompt message when they enter an item that cannot be found in the
database in a retail transaction.
<AllowPartialPickups> — Determines whether the system allows customers to pick
up some items from a CCA or if customers must pick up all the items at one time.
<AllowInventoryBucketMovement> — Determines if CCA item movement is
tracked by bucket.
<InventoryBucketId> — The identifier for the CCA inventory bucket.

ComponentGroupConfig.xml file
<ComponentGroupSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance"
xsi:noNamespaceSchemaLocation="ComponentGroupConfig.xsd"
xmlns="http://micros.com/xstore/config/componentgroup">
<ComponentGroup name="DEFAULT">
<ComponentPropertySet ref="FOCUS_BAR_BLACK" />
<ComponentPropertySet ref="TAB_BACKGROUND_BLACK" />
<ComponentPropertySet ref="TITLED_PANEL_BLACK" />
<ComponentPropertySet ref="INFORMATION_PANEL_BLACK" />
<ComponentPropertySet ref="CONTEXT_PANEL_HEADER_BLACK" />
<ComponentPropertySet ref="CONTEXT_PANEL_BLACK" />
<ComponentPropertySet ref="FORM_TAB_BACKGROUND_DEFAULT" />
<ComponentPropertySet ref="BUTTON" />

31-8 Technical Guide

 Configuration File Setup for CCA

<ComponentPropertySet ref="BUTTON_DRILL_DOWN_DEFAULT" />

<ComponentPropertySet ref="BUTTON_ITEM_DEFAULT" />
</ComponentGroup>
<ComponentGroup name="ORANGE">
<ComponentPropertySet ref="FOCUS_BAR_ORANGE" />
<ComponentPropertySet ref="TAB_BACKGROUND_ORANGE" />
<ComponentPropertySet ref="TITLED_PANEL_ORANGE" />
<ComponentPropertySet ref="INFORMATION_PANEL_ORANGE" />
<ComponentPropertySet ref="CONTEXT_PANEL_HEADER_ORANGE" />
<ComponentPropertySet ref="CONTEXT_PANEL_ORANGE" />
</ComponentGroup>
*****************Shortened for brevity************
<ComponentGroup name="PURPLE">
<ComponentPropertySet ref="FOCUS_BAR_PURPLE" />
<ComponentPropertySet ref="TAB_BACKGROUND_PURPLE" />
<ComponentPropertySet ref="TITLED_PANEL_PURPLE" />
<ComponentPropertySet ref="INFORMATION_PANEL_PURPLE" />
<ComponentPropertySet ref="CONTEXT_PANEL_HEADER_PURPLE" />
<ComponentPropertySet ref="CONTEXT_PANEL_PURPLE" />
</ComponentGroup>
<ComponentGroup name="TEAL">
<ComponentPropertySet ref="FOCUS_BAR_TEAL" />
<ComponentPropertySet ref="TAB_BACKGROUND_TEAL" />
<ComponentPropertySet ref="TITLED_PANEL_TEAL" />
<ComponentPropertySet ref="INFORMATION_PANEL_TEAL" />
<ComponentPropertySet ref="CONTEXT_PANEL_HEADER_TEAL" />
<ComponentPropertySet ref="CONTEXT_PANEL_TEAL" />
</ComponentGroup>
<ComponentGroup name="TRAINING">
<ComponentPropertySet ref="BACKGROUND_TRAINING" />
<ComponentPropertySet ref="BUTTON_TRAINING" />
</ComponentGroup>
<ComponentGroup name="NON_TRAINING">
<ComponentPropertySet ref="BACKGROUND" />
<ComponentPropertySet ref="BUTTON" />
</ComponentGroup>

Customer Account Configuration 31-9

Configuration File Setup for CCA

</ComponentGroupSet><ComponentGroup> — The name of the component group

to be referenced in other configuration files such as CustomerAccountConfig.xml
and ContextConfig.xml.
<ComponentPropertySet> — A reference to the component property set definition in
the ComponentPropertySetConfig.xml file. (See
ComponentPropertySetConfig.xml file below).

ComponentPropertySetConfig.xml file
<ComponentPropertySets xmlns:xsi="http://www.w3.org/2001/
XMLSchema-instance"
xsi:noNamespaceSchemaLocation="ComponentGroupConfig.xsd"
xmlns="http://micros.com/xstore/config/componentproperty">
<ComponentPropertySet name="INFORMATION_PANEL_TEAL" >
<ComponentID>TransactionInformationPanel</ComponentID>
<ComponentProperty>
<Property>background</Property>
<Value
dtype="ColorRef">_colorTransactionInformationPanelTeal</Value>
</ComponentProperty>
</ComponentPropertySet>
<ComponentPropertySet name="INFORMATION_PANEL_BLACK" >
<ComponentID>TransactionInformationPanel</ComponentID>
<ComponentProperty>
<Property>background</Property>
<Value
dtype="ColorRef">_colorTransactionInformationPanelBlack</Value>
</ComponentProperty>
</ComponentPropertySet>

*****************Shortened for brevity************

<ComponentPropertySet> - Tags shown here have unique names so they can be
referenced by the ComponentGroupConfig.xml file.

ContextConfig.xml file
<Context name=”DEFAULT”>
<SecondDisplayMode>OTHER</SecondDisplayMode>
<ColorGroup fgColorRef=”_colorContextSelectionfgWhite” />
<ComponentGroup ref=”DEFAULT” />
<ComponentPropertySet ref=”TABBED_PANE_DEFAULT” />
<!-- set the message view to enabled and visible -->
<Component>

31-10 Technical Guide

 Configuration File Setup for CCA

<Name>INPUT_CONTROL_AREA</Name>
<Visible>true</Visible>
<Enabled>true</Enabled>
</Component>
</Context>
*****************Shortened for brevity************
<Context name="SALE">
<ParentContext>REGISTER_TRANSACTION_LIST</ParentContext>
<MenuKey>SALE</MenuKey>
<ListModelKey>CURRENT_TRANSACTION</ListModelKey>
<Text1>_contextSale</Text1>
<HelpKey>_helpMsgSale</HelpKey>
<ColorGroup bgColorRef="_colorContextSelectionbgSale"
bgColor2Ref="_colorContextSelectionbg2Sale" />
<ComponentGroup ref="BLUE" />
</Context>
*****************Shortened for brevity************
<Context> tags have a <ComponentGroup> tag that references the group of
<ComponentPropertySet> tags defining the background panels and focusbar to use.
<ColorGroup> — The color to use throughout the system to represent this customer
account type.
<ComponentGroup> — The reference to a component group which defines the color of
various background panels, and the color of the focusbar to use for the customer account
type. (See “ComponentGroupConfig.xml file”).

Customer Account Configuration 31-11

Configuration File Setup for CCA

31-12 Technical Guide

 32
Customer Maintenance Configuration

Overview
The customer maintenance features described in this chapter include Customer Wish
List, Customer Attributes, Activity Stream, Gift Registry, Customer Birthdate Options,
and Task Management.

Customer Wish List

The customer Wish List tab in Xstore Point of Service Customer Maintenance displays
the customer's item wish list from Customer Engagement Cloud Services. A wish list can
also be initiated in Xstore Point of Service.
The Wish List tab is only available on systems that are configured to use Customer
Engagement Cloud Services.

Customer Wish List Setup

Item Setup
1. To display an item image in Xstore Point of Service, the item image must be stored
on the local machine in xstore\res\graphics\items.
2. The path for the item image must be in the item_url field in the
itm_item_images table.

Note: The same image can be set up for all item display features, or a
different image can be set up for display in a Wish List. This is
controlled through the use of the feature_id field in itm_item_images.
See “Item Images” in Chapter 5, “Item and Pricing Configuration” for
more information.

System Config Setup

1. To enable wish list functionality, set the following SysConfig.xml configuration to
true.
<Setting name="EnableCustomerWishList">true</Setting>

Customer Maintenance Configuration 32-1

Customer Attributes

2. Specify the user ID that will be sent to Customer Engagement Cloud Services for all
v2 customer messages.

Note: The Customer Engagement Cloud Services configurations have

been moved from
\xstore\lib\config.jar\relate\SystemConfig.xml to
system.properties. The properties are named
dtv.relate.security.Type and
dtv.relate.security.DefaultUserId.

See “Customer Engagement Cloud Services Security Settings” of Chapter 24,

“Customer Engagement Cloud Services Configuration” for more information..

Note: Customer Engagement Cloud Services configuration is also

required, but is out of scope for this document.
If an item is on file in Customer Engagement Cloud Services, but not
on file in Xstore Point of Service, you will see the item listed in the
customer’s wish list, but no other information about the item will be
available. These items can be selected for purchase from the wish list,
but will end up on the “Wish List Not Available” list and will not be
added to the sale. They will however remain on the wish list. Refer to
the Customer Engagement Cloud Services documentation for more
information about Customer Engagement Cloud Services features and
setup.

Customer Attributes
Use the customer attributes feature to assign custom attributes to customers that can be
displayed in Customer Maintenance. The attributes can be retrieved from a CRM system
such as Customer Engagement Cloud Services or from Xstore Office itself.

When Xstore Point of Service uses Customer Engagement Cloud

Services
All attributes returned by Customer Engagement Cloud Services that are not used
internally by Xstore Point of Service will be displayed in Customer Maintenance.
The following custom Customer Engagement Cloud Services attributes are used
internally by Xstore Point of Service’s custom attribute class and will not be displayed in
the customer attribute list in Customer Maintenance:
- CUSTOMER_GROUPS
- PARTY_TYPE_CODE

Note: The PROMPT_TO_JOIN_LOYALTY attribute is returned by

Customer Engagement Cloud Services and is converted to a party
property, but this attribute is configured in Xstore Point of Service’s
com_code_value table to be hidden per configuration.

32-2 Technical Guide

 Customer Attributes

When Xstore Point of Service uses Xstore Office (not Customer

Engagement Cloud Services)
Attributes displayed in Customer Maintenance will be those that exist in the
crm_party_properties table.
Using either Customer Engagement Cloud Services or Xstore Office, com_code_value
entries are not required.

Customer Attributes Database Setup

com_code_value Table
Entries in the com_code_value table are not required, but if one exists, the description
for the code will display in Customer Maintenance. Otherwise, the code itself is
displayed.
To specify any attributes that should not be displayed, set the hidden flag to “true”.
The attribute is defined in com_code_value.category where
category=PARTY_PROPERTY_DISPLAY.

When Using Customer Engagement Cloud Services

• If an attribute is assigned in Customer Engagement Cloud Services and matches a
property in the com_code_value table, then the description from the
com_code_value table is displayed.
• If an attribute is assigned in Customer Engagement Cloud Services, but does not
match any of the properties defined in the com_code_value table, then the
property code displays rather than the description.
• If no attributes are defined in Customer Engagement Cloud Services, then in the
absence of any non-hidden attributes on the customer record, the attributes defined
in the com_code_value table are displayed.

When Using Xstore Office

• If a customer has no party properties defined in crm_party_properties, the
Customer Attributes list will be empty.
• If a customer has a party property defined in crm_party_properties, and it
matches a property in the com_code_value table, then the description from the
com_code_value table is displayed.
• If a customer has a party property defined in crm_party_properties, but it does
not match any of the properties defined in the com_code_value table, then the
property_code displays rather than the description.

Customer Maintenance Configuration 32-3

Activity Stream

Activity Stream
The Activity Stream section on the Contact Information tab lists the customer's recent
transactions in chronological order by day.
Each transaction is associated with an icon that represents the transaction type such as
sale, special order, or return.
This feature encourages a dialog between the associate and the customer by showing
relevant information about the customer’s previous shopping experiences.
Messages can be shown in the Activity Stream when a customer is within X days of their
Loyalty card expiring, and within X days of a birthday or anniversary. These messages
always appear at the beginning of the activity stream.
Loyalty expiration display is a configurable option. See “Loyalty Expiration Display
Setup”.

Special Orders in the Activity Stream

Special orders for delivery and special order pickup transactions are displayed in the
Activity Stream. Setup transactions for special orders for pickup do not display in the
Activity stream.
Any service fees associated with the special order are not displayed in the Activity
Stream.

Activity Stream Setup

SysConfig.xml Settings
<Setting name="CustomerHistoryAgeLimitDays">365</Setting>
<Setting name="CustomerActivityStreamMaxItems">50</Setting>
<Setting name="ActivityStream---AnniversaryDateReminderDays">5</
Setting>
<Setting name="ActivityStream---BirthDateReminderDays">5</
Setting>
<Setting name="ActivityStream---
LoyaltyExpirationReminderDays">30</Setting>

Note: The combination of the CustomerActivityStreamMaxItems and

CustomerHistoryAgeLimitDays control what is seen in the activity
stream.

CustomerHistoryAgeLimitDays - The number of day of retail history detail to

display on the customer maintenance form.
CustomerActivityStreamMaxItems - The maximum number of items to display in
the customer activity stream.
BirthDateReminderDays - The number of days before and after the customer’s actual
birthday date to display a reminder message.
AnniversaryDateReminderDays - The number of days before and after the
customer’s actual anniversary date to display a reminder message.
LoyaltyExpirationReminderDays - The number of days before the actual card
expiration date to start displaying a reminder message.

32-4 Technical Guide

 Activity Stream

ActivityStreamConfig.xml Settings
ActivityStreamConfig.xml defines which data, and how the data is rendered, in
the activity stream. The configuration file, has basically 2 subdepartments: a DataSet
that defines where the data comes from and a RuleSet that defines how the data is
rendered.

DataSet example
<DataSet>
<Data
class="dtv.pos.customer.activitystream.dataretriever.ActivityStre
amModelBuilder">
<Parameter name="Rule" value="CUSTOMER_BIRTHDATE"/>
<Parameter name="Date">
<EvaluatedFormattable method="toDateWithinMargin">
<method_param>
<EvaluatedFormattable
method="getCurrentCmd.getParty.getBirthDate"/>
</method_param>
</EvaluatedFormattable>
</Parameter>
<Parameter name="Source">
<EvaluatedFormattable method="getCurrentCmd.getParty"/>
</Parameter>
<Parameter name="Icon">
<param_value dtype="IconRef">_imageIconHappyBirthday</
param_value>
</Parameter>
<Parameter name="DayMargin">
<EvaluatedFormattable
method="getConfigurationMgr.getActivityStreamBirthDateReminderDay
s"/>
</Parameter>
<VisibilityRule
class="dtv.pos.customer.activitystream.visibilityrules.YearDateIs
BeforeOrAfterVisibilityRule">
<Parameter name="Date">
<EvaluatedFormattable
method="getSource.getBirthDate"/>
</Parameter>
<Parameter name="DayMargin">

Customer Maintenance Configuration 32-5

Gift Registry

<EvaluatedFormattable
method="getConfigurationMgr.getActivityStreamBirthDateReminderDay
s"/>
</Parameter>
</VisibilityRule>
</Data>
</DataSet>

RuleSet example
<RuleSet>
<Rule name="CUSTOMER_BIRTHDATE">
<Parameter name="title">
<ParameterizedFormattable
translationKey="_activityStreamCustomerBirthdate">
<EvaluatedFormattable
method="getSource.getFirstName"/>
<EvaluatedFormattable method="getSource.getBirthDate"
formatter="DateMonthNameDay"/>
</ParameterizedFormattable>
</Parameter>
</Rule>
</RuleSet>

Loyalty Expiration Display Setup

Set up the following configuration option to define whether Loyalty card expiration
information is displayed on the Xstore Point of Service screen and on the receipt. See
“Loyalty Card Setup” in Chapter 24, “Customer Engagement Cloud Services
Configuration” for more information about Loyalty card configuration and setup.
This configuration is in the
xstore\lib\config.jar\cust\loyalty\SysConfig.xml file.
<Setting name="Loyalty---ShowCardExpirationDate">false</Setting>
ShowCardExpirationDate - Determines whether to show the loyalty card expiration
date in the display and receipt.

Gift Registry
The Gift Registry feature provides a communication channel between a person (or
persons) asking for gifts, and other people who wish to purchase gifts for that person (or
those persons). This feature allows them to manage that process.

32-6 Technical Guide

 Gift Registry

Gift Registry is available if you are using Customer Engagement Cloud Services. Gift
registries can be set up and maintained in the system from the Back Office. Items in a
sale transaction can then be associated to a registry.

Note: Customer Engagement Cloud Services is responsible for

tracking and aggregating the gift registry information.
Gift registry data is retrieved directly from, and persisted directly to,
Customer Engagement Cloud Services with no intermediate storage in
the Xstore Point of Service database. All persistence is real-time,
meaning that attempting to make any change/update/addition to an
existing registry or creating a new registry will either immediately
succeed or the user will receive an error.

The Gift Registry feature allows the Sales Associate to create gift registries within Xstore
Point of Service by accessing Customer Engagement Cloud Services WSDLs. The Gift
Registry is accessed in Xstore Point of Service using a function key from within the
Customer Maintenance screen or from the Transaction screen.

Note: If the customer record is not in Customer Engagement Cloud

Services, the Sales Associate must create a customer record first.

A call out to Customer Engagement Cloud Services using the addOrUpdateRegistry

WSDL is used to create a gift registry associated with a customer account. When a value
of zero is passed as a RegistryID, then a new registry is created associated to the
customer.
Once the registry has been added to the customer record, the Sales Associate will be able
to add items to the customer’s gift registry.

Gift Registry Setup

system.properties Settings

Setting Valid Values Description

AttributesServices dtv.xst.crm.relate.impl.AttributesServicesFactory Attributes services

factory implementation
class

RegistryServices dtv.xst.crm.relate.impl.RegistryServicesFactory Registry services

factory implementation
class

SysConfig.xml Settings
<Setting name="GiftRegistry---AutoTriggerGiftReceipts">true</
Setting>
<Setting name="GiftRegistry---HidePurchasedQuantity">false</
Setting>
AutoTriggerGiftReceipts - When true and a gift registry item is purchased, the
item is automatically flagged for a gift receipt.

Customer Maintenance Configuration 32-7

Gift Registry

HidePurchasedQuantity - When true, hides the purchased quantity values in the

back office gift registry maintenance view.

Database Settings

crm_gift_registry_journal Table
A row is persisted to this table for every change made to a gift registry in the Xstore
Point of Service back office. Examples of a "change" would be adding or removing an
item, attribute, or address, updating gift registry header information, etc.

Note: These records cannot be loaded via DataLoader.

Column Used to

journal_seq identify the journal sequence number for the journal entry.
REQUIRED

registry_id uniquely identify the gift registry that was created or modified.

action_code describe the change made to the gift registry. Valid Values:
CREATE_REGISTRY, UPDATE_DETAILS, ADD_ITEM,
CHANGE_ITEM_QUANTITY, DELETE_ITEM, ATTRIBUTE_ADD,
ATTRIBUTE_MODIFY, ATTRIBUTE_DELETE, ADDRESS_ADD,
ADDRESS_MODIFY, ADDRESS_DELETE, OWNER_ADD,
OWNER_MODIFY, OWNER_DELETE

registry_status specify the registry status returned from the system of record (i.e.
Customer Engagement Cloud Services) when the change was posted.

trans_rtl_loc_id specify the store number for the gift registry transaction associated with
the journal entry.

trans_wkstn_id specify the register number for the gift registry transaction associated
with the journal entry.

trans_business_ specify the business date for the gift registry transaction associated with
date the journal entry.

trans_trans_seq specify the transaction number for the gift registry transaction associated
with the journal entry.

trn_gift_registry_trans Table
A row is persisted to this table every time a gift registry is created or edited in the Xstore
Point of Service back office. One row per "editing session" is created.

Column Used to

rtl_loc_id specify the store number for the transaction.

REQUIRED

wkstn_id specify the register number for the transaction.

REQUIRED

business_date specify the business date for the transaction.

REQUIRED

32-8 Technical Guide

 Customer Birthdate Options

Column Used to

trans_seq specify the transaction number for the transaction.

REQUIRED

registry_id specify the unique ID of the gift registry that was created or modified.

Base Enumerations: com_code_value Table

Base Data Valid Values

GIFT_REGISTRY_ADDRESS_TYPE Enumeration of gift registry address types (VENUE,

BEFORE_EVENT, AFTER_EVENT as per Customer
Engagement Cloud Services) in com_code_value.

GIFT_REGISTRY_EVENT_TYPE Enumeration of gift registry event types (customer

defined) in com_code_value.

Customer Birthdate Options

Xstore Point of Service provides the ability to add and track a customer's birthday. Using
system configuration, it is possible to either collect the complete date including the
month, day, and year, or to only collect the month and day.

SysConfig.xml Setting
<Setting name="RequestCustomerBirthYear">true</Setting>
RequestCustomerBirthYear - Determines whether to collect the complete date
including the month, day, and year, or to only collect the month and day.
• When true, the user will be prompted to input the complete birth date: MM/dd/
yyyy.
• When false, only the MM/dd format is required. Note: A generic date for the year
(1900) will be appended to the MM/dd date.

Task Management
Note: Xstore Point of Service 15.0 has been certified with Customer
Engagement Cloud Services 11.4.

Task Management is a feature that combines store specific and customer related tasks
such as appointments into a single view. Task Management is designed to support both
Xstore Point of Service native tasks and those created within the Customer Engagement
Cloud Services system if configured.
The Task Services API Version 1.1 of Customer Engagement Cloud Services is integrated
with Xstore Point of Service to use this feature.
The URL for the WSDL is:
https://<localhost>:8443/soap/<companycode>/v1_1/
TaskServices?wsdl

Customer Maintenance Configuration 32-9

Task Management

where <localhost> is the name or address of the server, and <companycode> is the code
assigned to the company at installation.
Customer Engagement Cloud Services security is set in system.properties.

Note: The Customer Engagement Cloud Services configurations have

been moved from
\xstore\lib\config.jar\relate\SystemConfig.xml to
system.properties.
The properties are named dtv.relate.security.Type and
dtv.relate.security.DefaultUserId.

Tasks Tab
See “Tab Setup” in Chapter 38, “Menu & Tab Configuration” for setup and configuration
information. The Tasks tab is configured in the file:
C:\xstoredata\lib\config.jar\relate\uipropertysets\TabConfig.xml

About the Tasks Tab

• Displays tasks for the current business day. Expired appointments are not shown.
• Tasks for the selected customer can be added and edited from this screen but you
cannot update the status. Updates to the status must be made in the My Tasks
screen. See the Xstore Point of Service User Guide.
• Associates—as designated on the Tasks tab—are correlated between Customer
Engagement Cloud Services and Xstore Point of Service by Employee IDs, not Party
IDs. For everything to tie together, the following values must match up as follows:
- crm_party.party_id = hrs_employee.party_id
- crm_party.employee_id = hrs_employee.employee_id
- <Customer Engagement Cloud Services ID> =
crm_party.employee_id = hrs_employee.employee_id
• Associates—as designated on the Tasks tab—will display the name of the associate
as per the Xstore Point of Service crm_party record and not per the explicit
value returned in the Customer Engagement Cloud Services response. These names
should be identical to avoid confusion.

32-10 Technical Guide

 33
SSL Cert Check at Startup

Overview
When the first register is opened on the current system date, a check is performed on the
expiration dates of certificates used for SSL communication with Xstore Office and other
systems. At startup, a check is preformed based on the configuration to determine the
status of the SSL certificates. If any certificates are found to be near expiration,
information is logged detailing the issue.

Note: This check assumes HTTPS hosts are defined for Xstore Office
communications.

This check does not block startup, and no messages are displayed to the user. This
process simply logs information if the certificate is about to expire.

Where the information is logged

The code uses logger dtv.xstore.security.ssl. This means the message will be
written by the following loggers:
dtv.xstore.security.ssl
dtv.xstore.security
dtv.xstore
dtv
<root>
The results of the SSL cert check are displayed theXstore Office Alert Console, and in
the xstore.log so anyone connected to the system for troubleshooting purposes can see it.

SSL Cert Check at Startup 33-1

Configuration Options

Configuration Options
Note: The SSLCertificateCheck has been moved to the
system.properties file.

system.properties
The following configuration is set in the xstore\root\system.properties file.
ssl.certificate.check.enabled=true
Determines whether the check should be enabled or not.The SSL cert check has three
behaviors based on the calculation diff = currentTime – expirationTime (in days):
1. if diff < 0, then log ERROR indicating the certificate is expired
2. if diff = 0, then log WARN indicating today is the last day
3. if diff between 1 the configured parameter, then log WARN indicating that the
certificate will expire in XXX days.

Spring Configuration
In the /config/config/dtv/res/config/spring/workers.xml file the list of
the .keystore files and certificates to be validated are configured.
There are also country specific configurations which can be found in the respective
countrypack-XX.xml spring files.
The number of days is configured in the daysBeforeExpiration of workers.xml
spring file.

33-2 Technical Guide

 34
Update Services & File Movement

Update Services Overview

Xstore Point of Service does not make any direct polling requests to Xstore Office.
Xenvironment manages the actions necessary to retrieve and apply the associated file to
the appropriate systems in the store.
Xenvironment calls the Update Service on a scheduled interval to retrieve new manifests
that describe deployments that are scheduled to be downloaded to the store. Checking
the update service at regular intervals throughout the day provides the ability to pull
down data changes to stores in "real time". Each manifest represents either an
automatically-created or user-created deployment.
Xstore Office's GetUpdatesResource returns the deployment manifest as a ZIP file, a
204 NO CONTENT response when no updates are available, or 400 BAD REQUEST if
any lookup parameters are invalid.
The Open/Close option Check For Updates in Xstore Point of Service triggers an IPC call
to Xenvironment to tell it to poll Xstore Office for updates.
Feedback on deployments is published to Xstore Office by Xenvironment and can be
reviewed in Xstore Office.

Update Services Setup

The interval of the scheduled update service is set in Xenvironment’s
environment.properties:
xadmin.deployment.manifest.download_interval
The default value is 1800 seconds (30 minutes).

Update Services & File Movement 34-1

File Movement Between Xstore Office and Xenvironment

File Movement Between Xstore Office and Xenvironment

File Movement Process Overview
1. The user defines the deployment in Xstore Office.
2. The Xenvironment lead register periodically checks with Xstore Office to see if any
new deployments are available. If there are deployments available for the store, then
a manifest will be downloaded.

Note: Checks are also performed during closing, outside of this

schedule.

3. The deployment data that Xenvironment receives contains information about files
that need to be downloaded, including when the files should be downloaded
(immediately or during the store close) and when the files should be applied
(immediately or during the store close).
4. After a file is downloaded, Xenvironment reports the status of the file download to
Xstore Office.
5. After a file is applied, Xenvironment reports the status of the file applied to Xstore
Office.

34-2 Technical Guide

 35
Context-Sensitive Help

Overview
Context-sensitive help displays brief information describing the current condition, or
feature, of the software. When a user presses the [F1] key, Xstore Point of Service calls
and displays the HTML help file associated with the current context.

About this Chapter

Setting Up Context-Sensitive Help describes how to associate an HTML help file with an
existing context.

Note: Creating the HTML help files and creating a new context
within Xstore Point of Service is out of scope for this document.

Setting Up Context-Sensitive Help

Three Xstore Point of Service files must be set up for context sensitive help:
• ContextConfig.xml
• translations.properties
• resources.properties
The following section shows an example of an HTML help file and provides more
information about setting up the files. It is assumed that the HTML help file has been
created and is ready to be associated with an existing context. See Figure 35-1 for an
example of context-sensitive help in the “Register Locked” context.
The files are set up as follows.
1. HelpKey

Find the context in \dtv\res\config\ContextConfig.xml1, and define the

HelpKey as shown below.
<Context name="REGISTER_LOCKED">
<ParentContext>SALE</ParentContext>
<MenuKey>ADMIN::LOCKED_REGISTER_OPTIONS</MenuKey>
<Text1>_contextRegisterLocked</Text1>
<HelpKey>_helpMsgRegisterLocked</HelpKey>

1.The context for some features may be defined in other function-specific files rather than in ContextConfig.xml. For
example, the context for Customer Pre-sale Accounts is found in CustomerAccountConfig.xml.

Context-Sensitive Help 35-1

Setting Up Context-Sensitive Help

</Context>
...
<Account name="PRESALE">
<Text dtype="Translatable">_ccaPreSale</Text>
<HelpKey dtype="Translatable"
bundle="dtv.pos.i18n.help">_helpMsg_cca_Presale</HelpKey>
<ColorGroup bgColor="0x660066" bgColor2="0xB400B4"/>
<ComponentGroup ref="PURPLE"/>
<DepositFeeType dtype="String">TRANSACTION</DepositFeeType>
................Edited for brevity...............
</Account>
2. Translations Properties File
Set up the help file properties (translations.properties) in
\dtv\res\config\ to associate the HelpKey to the HTML file.
_defaultHelpMessage=No quick help is available for this
function.
_defaultHelpTitle=Help
3. Resources Properties File
_helpAboutXstore=aboutXstore.htm
_helpMsgRegisterLogin=Logging_In.htm
_helpMsgRegisterLocked=Locking_and_Unlocking_a_Register.htm
_helpMsgBackOfficeLogin=Logging_in_to_the_Back_Office.htm
_helpMsgRegisterOptionsLogin=Register_Options_Login.htm
_helpMsgToRegisterLogin=Logging_In.htm
_helpMsgClockInOut=Clocking_In_and_Out.htm
.........Edited for brevity..............
4. HTML Help File
Place the HTML help file in the HTML help file folder:
C:\xstoredata\res\html\help.
If the help includes an image, place the image in the folder too.

35-2 Technical Guide

 Setting Up Context-Sensitive Help

Figure 35-1: Context-Sensitive Help Example

The Basic Elements

• The name of the HTML file created by the user =
Locking_and_Unlocking_a_Register.htm
• The HelpKey as defined in ContextConfig.xml = _helpMsgRegisterLocked
Then, in resources.properties, these two elements are “linked” together:

_helpMsgRegisterLocked = Locking_and_Unlocking_a_Register.htm

The HelpKey The HTML File Name

See “Translations Properties File”.

Note: To specify a default message to be displayed when no context-

sensitive help is available for a function, set up the text in
translations.properties:
_defaultHelpMessage=No quick help is available for
this function.

Context-Sensitive Help 35-3

Setting Up Context-Sensitive Help

35-4 Technical Guide

 36
Translation Files

Overview
For each language available in Xstore Point of Service, there is one corresponding
language translation file using the naming format shown below. The file extension
indicates that the file is a “properties” file.
translations_[locale].properties
The file translations_[locale].properties is an example of a resource bundle.

Note: Resource bundles are properties files grouped together by a

common base name, but with a different locale suffix. This enables
different properties to be used by Xstore Point of Service dependent on
the user's locale settings.

In the file name above, “[locale]” represents a 2-letter code for the language used in a
geographic location/locale — “en” for English, “fr” for French, “zh” for Chinese, etc. A
capitalized 2-letter code indicates a country — CA for Canada, JP for Japan, etc. — in
which there may be variations of a specified language. The file name may include both a
locale and a country designation. For example, fr_CA = French Canadian.
The file contains the actual text strings that will be substituted for a corresponding
translation key whenever the application encounters that key.
In Xstore Point of Service, all translation keys must begin with the underscore (_)
character. The translation key is identical in all of the language-specific translation
properties files, but its corresponding translation varies by language.

For more information...

The information contained in this chapter is presented at a fundamental level. For more
detailed information about working with translation files, refer to the Xstore Point of
Service Frameworks and Technologies Guide.

Translation Files 36-1

Translation File Rules

Translation File Rules

New line
A new line is specified using the "\n" escape sequence. Using two “\n”s together
specifies two carriage returns, resulting in a blank line in between each line of text).
EXAMPLE from translations_en.properties
_promptmsg146=This item is not on file.\n \nDo you want to
continue anyway?
This message displays on three lines as shown
here: two text lines separated by a blank line.

Spaces at the beginning or end of a line

By design, values in resource bundles have any "space" (normal spaces and tab
characters) removed from the beginning and end of the values. To force a space to
appear, a "non-breaking space" (Unicode 0xA0) can be used. This would appear in the
resource bundle as \u00A0 or \u00a0.

Key Code mappings

The entries that begin with "_keyCode" must have values that match programatically
with values in Java. The numbers and letters following the "_keyCode" text are the
hexadecimal value for the key code. The value after the equals sign is the function that
keycode should perform.

Example
In the translations_en.properties file:
_keyCodeA=Enter

Note: Do not translate _keyCodeA=Enter unless you want the Enter

key on the keyboard to be mapped to some other function on the
keyboard.

36-2 Technical Guide

 Translation File Rules

Escaped Unicode characters

The Windows Character Map program can be used as a quick reference for looking up
Unicode values for a letter.
To open Character Map, click Start-->All Programs-->Accessories-->System Tools-->
Character Map.
When a given character is selected in the Character Map, the Unicode value for the
character will be displayed in the status bar in the format U+0000. Refer to the Character
Map examples below.
When text in the format \u0000 appears, the numbers
following the \u are the hexadecimal value for a single
Unicode letter. For example, the letter "A" could be
represented by "A" or "\u0041".

For non-ASCII characters, it is safest to specify the characters

using the escaped Unicode value. For example, \u00e9 or
\u00E9 instead of é.

Translation Files 36-3

Translation File Rules

36-4 Technical Guide

 37
Xstore Point of Service Log Files

Overview
Xstore Point of Service Log files are generated automatically and record Xstore Point of
Service application events. Viewing these log files provides valuable data about store
operations and troubleshooting information.

About this Chapter

This chapter provides information about Xstore Point of Service’s log files, including a
brief description of the files and where they can be configured. The section “Log
Troubleshooting Tips - xstore.log” briefly describes how you can use the xstore.log file to
troubleshoot an issue.

Xstore Point of Service Wrapper Log Files

The wrapper builds the classpath from wildcards, executes, and monitors Xstore Point of
Service and its related applications. It can also restart these applications if anything
causes them to exit unexpectedly. Log files are created for all of the wrapper-controlled
parts of Xstore Point of Service (dataloader, datapurger, dataserver, etc.). All have a
filename similar to the batch file that launches it, but with an extension of
.wrapper.log.YYYYMMDD instead of .bat.
Example:
Table 37-1 xstore.wrapper.log

Log File Description

xstore.wrapper.log.20130411 Logs info when the application is started or stopped, or info

from the JVM that is not captured by log4j2.

Xstore Point of Service Log Files 37-1

Logs Configured/Controlled in log4j2

Logs Configured/Controlled in log4j2

log4j2.xml
The primary log4j2.xml file used by Xstore Point of Service is located in the
xstore\config directory. This file is automatically used by log4j2 to configure logging
in Xstore Point of Service.
For more information about system.properties, refer to the Xstore Point of Service
Frameworks and Technologies guide.
Xstore Point of Service and its components (dataserver, dataprocessor, etc.) utilize
multiple log4j2.xml configuration files to determine the content of the various log
files (and other appenders).
There are separate files for dataserver, dataprocessor, datapurger, dataloader, and
transaction replicator in xstore\config\dataserver,
xstore\config\dataprocessor, xstore\config\purge,
xstore\config\dataloader, and xstore\config\transreplicate.
For those applications, the wrapper config file specifies an override
log4j2.configuration value that causes their specific files to be loaded instead of
the primary file. (See “Xstore Point of Service Wrapper Log Files”).

Note: Each time the application starts up, the log files are rotated.

Table 37-2 Xstore Point of Service Log Files

Log File Description

xstore.log Contains progress and error information for the Xstore Point of
Service process. The layout, rolling, and log levels are configured in
log4j2.xml. This file is continually rotated by system date. The
time that this log is kept for is configurable, and the default value is
set to 14 days (<DefaultRolloverStrategy max="14" />).

auth.log Contains debug logging messages for Oracle Retail Customer

Engagement Gift Card web services.

cashdrawer.log Logs each time the cash drawer opens, highlighting if the drawer
was not opened through software (e.g. a key was used) or if the
drawer state did not change (e.g. the drawer is faulty or locked).

ejournal.log Logs all text that is sent to the receipt printer. This log includes
information as it is displayed on the receipt, including paper cuts
and barcode text data.

jmxHttpAccess.log Logs all HTTP requests made of the JMX console. Failed
authentications are logged. All authentication attempts can be logged
with a configuration change. (This is similar to access.log on a web
server).

failedPersistence.log Contains error messages for any objects that could not be persisted
(saved to the database). An XML version of each failed object is also
logged.

replicationAudit.log Gives full detail as each replication item comes into the replication
queue and is processed.

37-2 Technical Guide

 Logs Configured/Controlled in log4j2

Table 37-2 Xstore Point of Service Log Files (continued)

Log File Description

repl.log A precursor to replicationAudit.log. (See replicationAudit.log

above).

xunit.out Written by xUnit.

biometric.log Logs biometric device information.

email.log Logs information/errors related to sending emails from the

application. For example, if an email receipt failed to send.

DataPurger - Controlled By log4j2

Table 37-3 DataPurger Log File

Log File Description

purge.log Controlled by xstore\config\purge\log4j2.xml. This log is used

exclusively by the datapurger.

DataServer - Controlled By log4j2

Table 37-4 DataServer Log File

Log File Description

dataserver.log Controlled by xstore\config\dataserver\log4j2.xml. This

log is used exclusively by the dataserver.

DataProcessor - Controlled By log4j2

Table 37-5 DataProcessor Log File

Log File Description

dataprocessor.log Controlled by xstore\config\dataprocessor\log4j2.xml. This

log is used exclusively by the dataprocessor.

DataLoader - Controlled By log4j2

Table 37-6 DataLoader Log Files

Log File Description

dataloader.log Logs everything the DataLoader does, from starting to completion, including
errors.

failures.dat Logs any failed download records lines, as well as an error indicating the
cause of the failure of those lines.

success.dat Logs completed, successful operations.

Xstore Point of Service Log Files 37-3

Xstore Point of Service Log Files - Transactional Data
Transaction replicator - Controlled By log4j2
Table 37-7 Transaction Replicator Log File
Log File Description
transreplicate.log Written by transaction replicator.
Xstore Point of Service Log Files - Transactional Data
All transactional data that Xstore Point of Service logs are kept in .xml files.
The following files are configured as listed in the "Where Configured" column. The
configs are found in xstore\lib\config.jar\dtv\res\config\log\.
Table 37-8 Xstore Point of Service Transaction Data Log Files
Log File Where Configured
remc.xml "log" directory of config path
(typically in files.xml and
MiscLogConfig.xml)
PosLog.xml or log/ "log" directory of config path
trickle (typically in files.xml and
TlogConfig.xml)
seclog.xml "log" directory of config path (in
SecLogConfig.xml by
default)
commonlog.xml "log" directory of config path
(typically in files.xml and
MiscLogConfig.xml)
customers.xml "log" directory of config path
(typically in files.xml and
CustLogConfig.xml)
workers.xml "log" directory of config path
(typically in files.xml and
EmpLogConfig.xml)
37-4 Technical Guide
Description
Logs any events that come from
a JavaPOS driver, including error
and status updates. This log is
based on the IXRetail Remote
Equipment Monitoring and
Control (REMC) log standard.
This log can be disabled with no
ill effect.
The transaction log (t-log) in the
ARTS POSLog format. (See
“Log Tables Controlled by
Xstore Point of Service and
log4j2” for more information).
Contains entries for each login,
authentication, override, or
receipt reprint. (Authentication
is re-entering ones password
after login to access a given
function). Both success and
failure are logged.
Contains some data entities that
didn't fit into other ARTS
defined files. Currently this
appears to be only transaction
notes.
Contains an entry for each
customer edit that takes place on
a given register. (Could be a new
or an existing customer). This
log is based on the ARTS
Customer log standard.
Contains an entry for each
employee edit that takes place
on a given register. This log is
based on the ARTS Worker log
standard.
 Log Controlled By the VeriFone Driver

Table 37-8 Xstore Point of Service Transaction Data Log Files (continued)

Log File Where Configured Description

timecard.xml "log" directory of config path Contains an entry for each clock-
(typically in files.xml and in or clock-out that takes place
TimeLogConfig.xml) on a given register.

payroll.xml "log" directory of config path Contains records for employee

(typically in files.xml and time when payroll is submitted.
PayrollLogConfig.xml)

inventory.xml "log" directory of config path Contains records updates for

(typically in files.xml and updates to inventory control
InventoryLogConfig.xml) documents. (Shipments, etc.)

inventoryCount.xml "log" directory of config path Contains records updates for

(typically in files.xml and inventory counts.
InventoryCountLogConfig. (inv_invctl_document records
xml) where document_typcode is
"INVENTORY_COUNT").

Log Controlled By the VeriFone Driver

Table 37-9 VeriFone Log File

Log File Description Where Configured

verifone.log Log created by the JavaPOS drivers xstore\lib\config.jar\com\verifone\

for Verifone Mx800-series hardware.
config\logserver.properties can be
extracted to
xstoredata\xstore\cust_config\com\
verifone\config\logserver.properties
for editing.

Other Logs
Table 37-10 Xstore Point of Service Log - Other

Log File Description Where Configured

epson-trace.log1 Log that can be enabled to jpos.xml

get detailed information
This file lives in
from Epson JavaPOS
xstore\config\dtv\res\config by default.
drivers. Not enabled by
default.

1.Written in Epson’s own directory.

Xstore Point of Service Log Files 37-5

Log Tables Controlled by Xstore Point of Service and log4j2

Log Tables Controlled by Xstore Point of Service and log4j2

Table 37-11 Xstore Point of Service Log Tables Controlled by Xstore Point of Service and
log4j2

Log File Description Where Configured

ttr_tndr_auth_log Table written to by authorization Retention is configured in

processes (credit, check, gift card, PurgeConfig.xml (if
etc.) for each authorization attempt. DataPurger is used).

ctl_event_log Table logged to at Xstore Point of Writing is configured in

Service start-up and shut-down, log4j2.xml.
version information, and any "help
Retention is configured in
desk" errors. Other events could also
PurgeConfig.xml (if
be configured to log here.
DataPurger is used).

trn_poslog_data PosLog data is written here. Writing is controlled by

files.xml.
Retention is configured in
PurgeConfig.xml (if
datapurger is used).

sec_activity_log Logs data about security activity that Configured via

has occurred in Xstore Point of SecLogConfig.xml.
Service.

Log Troubleshooting Tips - xstore.log

log4j2 levels2 - There are different logging levels available to help troubleshoot an issue
in Xstore Point of Service. Commonly used levels include:
• INFO - designates informational messages that highlight the progress of the
application at a coarse-grained level
• DEBUG - designates fine-grained informational events that are most useful to debug
an application
• WARN - designates potentially harmful situations
• ERROR - designates error events that might still allow the application to continue
running
• FATAL - designates very severe error events that will presumably lead the
application to abort

xstore.log logging level examples

INFO 2018-11-07 09:50:09,812 loading jar:file:/C:/
xstore/lib/config.jar!/dtv/res/config/DataSourceConfig.xml ::
dtv.util.config.ConfigHelper.initialize(ConfigHelper.java:152)
[startup]
WARN 2018-03-27 09:08:16,082 Datasource offline:
[Xcenter] EXPLANATION:
dtv.data2.access.exception.FailoverException: PING FAILED for
datasource: Xcenter - this datasource is offline. ::

2.Definitions from http://logging.apache.org/log4j2/1.2/apidocs/org/apache/log4j2/Level.html. Refer to this site for

more information about logging levels.

37-6 Technical Guide

 Log Troubleshooting Tips - xstore.log

dtv.data2.access.status.StatusMgr.logOffline(StatusMgr.java:377)
[startup]
ERROR 2018-03-27 09:08:21,883 Failed to load
environment properties file [c:\environment\version.properties]
because it does not exist ::
dtv.pos.common.EnvironmentHelper.readFile(EnvironmentHelper.java:
375) [startup]
FATAL 2018-12-20 14:21:05,028 HELP DESK ERROR ::
dtv.pos.framework.op.req.AbstractPromptReqHandler$1.run(AbstractP
romptReqHandler.java:71) [AWT-EventQueue-0]
DEBUG [- ] 2018-11-07 17:02:53,181 -[Rule]
class dtv.pos.commission.ValidateCommAssocsRule
@@ (jar:file:/C:/xstore/lib/config.jar!/dtv/res/config/
ValidationRuleConfig.xml:444) [REGISTER:OCP [User]]

Operations
Search for operations to find the beginning of the transactions:
- CHAIN - REGISTER_LOGIN
- CHAIN - BACK_OFFICE_STARTUP

REGISTER_LOGIN
INFO [- ] 2013-11-07 09:50:34,311 >> +[CHAIN] REGISTER_LOGIN
@@ (jar:file:/C:/xstore/lib/config.jar!/dtv/res/config/
OpChainConfig.xml:7434) [startup]

BACK_OFFICE_STARTUP
INFO [- ] 2013-11-07 12:12:55,103 >> +[CHAIN]
BACK_OFFICE_STARTUP
@@ (jar:file:/C:/xstore/lib/config.jar!/dtv/res/config/
OpChainConfig.xml:438) [startup]

Version Info
Displays build information. Xstore Point of Service posts its version information in the
xstore.log every time it is started or restarted.
********************
VERSION INFORMATION
********************

Xstore version 18.0.0.0.414 - 0.0.0 - 0.0 (Tue Aug 21 22:10:32

CEST 2018)
Database [LOCAL] version 18.0.0.0.414 - 0.0.0 - 0.0 (2018-10-11
12:52:15.28)
Database [STORE] version 18.0.0.0.414 - 0.0.0 - 0.0 (2018-10-11
12:52:15.28)
Database [CENTRAL] version 18.0.0.0.414 - 0.0.0 - 0.0 (2018-10-11
12:52:15.28)

Xstore Point of Service Log Files 37-7

Logging for Validation Rules

Location Info
Displays location and register information. Xstore Point of Service posts its location
information in the xstore.log every time it is started or restarted.
INFO 2015-11-07 09:50:17,266 LOCATION
IDENTIFICATION:
dtv.CustomerId: XST
OrganizationId: 1000
RetailLocationId: 110
WorkstationId: 1
BusinessDate: 2013-08-15 ::
dtv.pos.framework.StationController$StartupWorker.run(StationCont
roller.java:681) [startup]

Configuration File Loading

Shows which files are being loaded.
1-INFO 2014-05-29 10:52:18,820 loading jar:file:/C:/
xstore/lib/config.jar!/dtv/res/config/DtxReplicationConfig.xml ::
dtv.util.config.ConfigHelper.initialize(ConfigHelper.java:152)
[startup]
1-INFO 2014-05-29 10:52:18,897 loading jar:file:/C:/
xstore/lib/config.jar!/relate/DtxReplicationConfig.xml ::
dtv.util.config.ConfigHelper.initialize(ConfigHelper.java:152)
[startup]
1-INFO 2014-05-29 10:52:18,901 loading jar:file:/C:/
xstore/lib/xst-config.jar!/version1/DtxReplicationConfig.xml ::
dtv.util.config.ConfigHelper.initialize(ConfigHelper.java:152)
[startup]

Logging for Validation Rules

Passed rules only show up when the logging level is set to DEBUG. If you don't want to
see passed rules, change the level to INFO.
• A "dash" prefix indicates a passed rule,
DEBUG [- ] 2013-11-07 17:02:53,181 -[Rule]
class dtv.pos.commission.ValidateCommAssocsRule
@@ (jar:file:/C:/xstore/lib/config.jar!/dtv/res/config/
ValidationRuleConfig.xml:444) [REGISTER:OCP [User]]
• and an "X" (logged as a warning) indicates a failed rule.
WARN [- ] 2013-11-05 09:44:45,804 X[Rule]
class dtv.pos.raincheck.ValidateRaincheckRedeemableRule
@@ (jar:file:/C:/xstore/lib/config.jar!/dtv/res/config/
ValidationRuleConfig.xml:1302) [REGISTER:OCP [User]]

37-8 Technical Guide

 38
Menu & Tab Configuration

Overview
Menu configuration has been simplified by separating the technical details, such as Op
Chains and Visibility Rules, from the less technical options, such as button/menu option
name and location within the pre-defined menu structure. MenuConfig.xml has been
optimized to support configuration tools and to generally improve efficiency for menu
layout.
It is also possible to add tabs to the information area of screen by selecting from a pre-
configured set of tabs in the “Tab Library”. The Tab Library provides multiple options
for information tabs and web widgets, beyond the standard tabs traditionally provided
in the information area with base Xstore. See “Tab Setup”.

Note: For more information about menu and tab configuration, refer
to the Xstore Office User Guide. Menus and tabs can be maintained in
Xstore Office through an easy-to-use and intuitive GUI.

Menu Configuration
Note: For more information about menu configuration, refer to the
Xstore Office User Guide. Menus can be set up and maintained in Xstore
Office via an easy-to-use and intuitive GUI.

Technical details, such as Op Chains and Visibility Rules, are defined

in ActionConfig.xml.

Functional Areas
The menus have been organized by logical, functional areas.
• ADMIN - These menus contain items pertaining to general administrative tasks in
both the Register and the Back Office. (<MenuItem name="ADMIN::)
• BALANCE_INQUIRY - These menus contain items allowing Balance Inquiries
against stored-value tenders. (<MenuItem name="BALANCE_INQUIRY::)
• CUSTOMER - These menus contain items pertaining to Customer and CRM
functionality. (<MenuItem name="CUSTOMER::)
• EMPLOYEE - These menus contain items pertaining to Employee functionality,
including Payroll, Scheduling, and Timecard functions. (<MenuItem
name="EMPLOYEE::)

Menu & Tab Configuration 38-1

Menu Configuration

• INVENTORY - These menus contain items pertaining to general Inventory

functionality. (<MenuItem name="INVENTORY::)
• INVENTORY_ADJUSTMENT - These menus contain items pertaining to Inventory
Adjustments. (<MenuItem name="INVENTORY_ADJUSTMENT::)
• LAYAWAY - These menus contain items pertaining to the creation and
administration of Layaways. (<MenuItem name="LAYAWAY">)
• LOGIN - These menus contain items allowing user access to Xstore Point of Service
“applications” i.e. the Register and Back Office. (<MenuItem name=”?LOGIN?”>)
• ORDER - These menus contain items pertaining to the creation and administration
of Distributed Orders. (<MenuItem name="ORDER">)
• REMOTE_SEND - These menus contain items pertaining to the creation and
administration of Remote Sends. (<MenuItem name="REMOTE_SEND">) Note: Not
supported in base Xstore Point of Service
• RETAIL - These menus contain items pertaining to general/shared retail register
functionality. (<MenuItem name="RETAIL::)
• RETURN - These menus contain items pertaining to the Return of previously
purchased merchandise. (<MenuItem name="RETURN">)
• SALE - These menus contain items pertaining to the Sale of merchandise.
(<MenuItem name="SALE">)
• SEND_SALE - These menus contain items pertaining to the creation and
administration of Send Sales. (<MenuItem name="SEND_SALE">)
• SHELF_LABEL - These menus contain items pertaining to the generation of Item/
Shelf Labels. (<MenuItem name="SHELF_LABEL::)
• SHIPPING - These menus contain items pertaining to the creation and
administration of Shipping documents. (<MenuItem name="SHIPPING::)
• SPECIAL_ORDER - These menus contain items pertaining to the creation and
administration of Special Orders. (<MenuItem name="SPECIAL_ORDER">)
• TENDER_EXCHANGE - These menus contain items allowing one tender to be
exchanged for others. (<MenuItem name="TENDER_EXCHANGE::)
• TILL - These menus contain items pertaining to Till administration and accounting.
(<MenuItem name="TILL::)
• WORK_ORDER - These menus contain items pertaining to the creation and
administration of Work Orders. (<MenuItem name="WORK_ORDER">)

MenuConfig.xml Example: SEND_SALE

<MenuItem name="RETAIL::EXTENDED_TRANS"
text="_accountOptionsMenuText" category="Retail"
keywords="universal,sale,register_extended,register_all">
<MenuOption ref="ORDER"/>
<SubMenu actionRef="SEND_SALE::MENU.OPTIONS">
<MenuOption ref="SEND_SALE"/>
<MenuOption ref="SEND_SALE::EDIT"/>
</SubMenu>

38-2 Technical Guide

 Menu Configuration

<MenuItem name="SEND_SALE" text="_menuSendSale"

category="Retail"
keywords="universal,register_extended,register_all,send_sale">
<MenuOption ref="SEND_SALE::COMPLETE"/>
<MenuOption ref="SEND_SALE::EDIT_DESTINATION"/>
<SubMenu ref="RETAIL::CHANGE_LINE"/>
<SubMenu ref="RETAIL::ADD_DISCOUNT"/>
<SubMenu actionRef="RETAIL::MENU.ADD_NON_PHYSICAL"
sticky="false" displayType="LIST">
<MenuOption ref="SEND_SALE::ADD_GIFT_CARD"/>
<MenuOption ref="SEND_SALE::ADD_GIFT_CERTIFICATE"/>
</SubMenu>
<MenuOption ref="SEND_SALE::SEARCH_FOR_ITEM"/>
<MenuOption>
<Action ref="SEND_SALE::COMPLETE.TO_TENDERING"/>
<Action ref="SEND_SALE::COMPLETE.NO_TENDERING"/>
</MenuOption>
<MenuOption ref="RETAIL::ADD_LINE_COMMENT"/>
<MenuOption ref="SEND_SALE::ADD_COMMENT"/>
<MenuOption ref="SEND_SALE::VIEW_COMMENTS"/>
</MenuItem>
</MenuItem>

The Components

Element Description

MenuSet The root tag for the menu hierarchy.

MenuItem
The top-level named menu, grouping the following menu options:
MenuOption (MenuOption), MenuOptions (MenuOptions), SubMenu (SubMenu -
(SubMenu inherits everything from MenuItem))
Table 38-1 MenuItem Elements

Element Description

MenuOption See “MenuOption”

MenuOptions See “MenuOptions”

SubMenu See “SubMenu - (SubMenu inherits everything from

MenuItem)”

Menu & Tab Configuration 38-3

Menu Configuration

Table 38-1 MenuItem Elements (continued)

Element Description

StickyParent If set to false, causes the opchain processor to return to the first sticky
ancestor of the current menu when escaping out. Defaults to "true".
(All menus are “sticky” by default).
See “About Menu Navigation” for more information about the
“StickyParent” element and the “sticky” attribute.

Action The action to perform when the user selects this menu item which
has more than one associated action. (Retained for backwards
compatibility).

SubMenuReferenceKey A text reference to the submenu to display when the user chooses
this menu option. (Retained for backwards compatibility).

Table 38-2 MenuItem Attributes

Name Type Description

displayType displayType “DisplayType”.

sticky boolean This value is a flow control mechanism for menu

navigation. Defaults to "true". (All menus are “sticky” by
default).
See “About Menu Navigation” for more information
about the “StickyParent” element and the “sticky” attribute.

keyStroke string Specifies a key on a keyboard to trigger the function.

Note: A keystroke defined here will override an
ActionConfig.xml keystroke definition.

text string The pre-defined translation key in Xstore Point of Service

translations_XX.properties file for the text shown on the
menu option/button.

actionRef string References an action. Technical details, such as Op Chains

and Visibility Rules, are defined in ActionConfig.xml.

keywords string Specifies the key words.

category string Specifies the menu category.

MenuOption
The menu option for a function.
Table 38-3 MenuOption Element

Element Description

Action The business logic for the action to perform when the user selects this menu
item. Used when there is more than one option.
<MenuOption>
<Action ref="ADMIN::OPEN_REGISTER"/>
<Action ref="ADMIN::CLOSE_REGISTER"/>
</MenuOption>

38-4 Technical Guide

 Menu Configuration

Table 38-4 MenuOption Attributes

Name Type Description

keyStroke string Specifies a key on a keyboard to trigger the

function.
Note: A keystroke defined here will override an
ActionConfig.xml keystroke definition.

text string The pre-defined translation key in Xstore Point of

Service translations_XX.properties file for the text
shown on the menu option/button.

ref string The reference to an action.

breadCrumbsDisabled boolean Default=true

MenuOptions
Used when the same set of options are referenced in multiple menus.
<MenuItem name="LOGIN::REGISTER" text="_menuLoginRegister"
displayType="BUTTON">
<MenuOptions ref="?LOGIN?"/>
<MenuOption>
<Action ref="LOGIN::BACK_OFFICE"/>
<Action ref="LOGIN::BACK_OFFICE.FROM_OTHER.START"/>
</MenuOption>
</MenuItem>
<MenuItem name="LOGIN::BACK_OFFICE" text="_menuLoginBackOffice"
displayType="BUTTON">
<MenuOptions ref="?LOGIN?"/>
<MenuOption>
<Action ref="LOGIN::REGISTER"/>
<Action ref="LOGIN::REGISTER.FROM_OTHER.START"/>
</MenuOption>
</MenuItem>

Table 38-5 MenuOptions Attribute

Name Type Description

ref string References a group of menu options.

Menu & Tab Configuration 38-5

About Menu Navigation

SubMenu - (SubMenu inherits everything from MenuItem)

A sub-menu option.
SubMenu inherits all elements in MenuItem. See “MenuItem” for more information.
Table 38-6 SubMenu Attributes

Name Type Description

SubMenu inherits all attributes in MenuItem. See “MenuItem” for more information.

ref string Reference to another named menu.

DisplayType
The menu option format. This enumerated value has the following possible values:
• LIST - Display menu options in a list format.
• BUTTON - Display menu options in a button format.
• BUTTON_EXCLUSIVE - Not used in menu configuration. (Used for prompts to force a
given set of options to completely replace whatever is there rather than amend it).
• POPUP - Not used in menu configuration.

About Menu Navigation

In older Xstore Point of Service versions, menu navigation was controlled via the “sticky
parent” setting on the “leaf” menu options. In base Xstore Point of Service, there are no
actual cases where there are some items on a submenu with “sticky parent = true” and
others with “sticky parent = false”; the values are always homogenous across the option
set. For this reason, a “sticky” setting was added at the parent level to push the common
setting down to all the children rather than force someone to copy/paste the same setting
on each child.
When a submenu function completes, the menu is restored to the first “sticky” parent of
that function. Since all menus are sticky by default, this usually means that the same
menu from which the function was launched is reasserted. In some cases however —
usually when it’s unlikely that the user would want to perform multiple functions
concurrently from within the same menu — that parent is declared “non-sticky”, in
which case the first ancestor menu that is sticky is asserted instead.

How it works—Change Item Menu Example

Note: In this scenario, assume that the Change Item Menu only
contains the “Change Price” and “Change Qty” options.

• “Change Item” menu: sticky=true In this scenario, when “Change Price” is invoked
for a line and entry of the new price is completed, the user will be returned to the
same “Change Item” menu (with the same options as before). However, since it’s
unlikely that the user will be changing the price for more than one line, the user
must now manually escape out of the submenu(s) until he/she is returned to the
main sale function menu.
• “Change Item” menu: sticky=false In this scenario, when “Change Price” is invoked
for a line and entry of the new price is completed, then the menu asserted after the
“Change Price” operation will be whatever ancestor of “Change Item” is declared
(implicitly or otherwise) as “sticky”, thus eliminating the need to drill up.

38-6 Technical Guide

 Hide Menu Options Based on Security Privilege

Because we don’t need to invoke “Change Price” or “Change Qty” more than once, you
can either assign “sticky parent = false” to “Change Price” and “sticky parent = false” to
“Change Qty”, or you can just assign a single “sticky = false” to the parent “Change
Item” as shown below.
<MenuItem name="RETAIL::CHANGE_LINE"
actionRef="RETAIL::MENU.MODIFY_LINE" sticky="false"
category="Retail" keywords="universal,register_extended">
<MenuOption ref="RETAIL::CHANGE_LINE_QUANTITY"/>
<MenuOption ref="RETAIL::CHANGE_LINE_PRICE"/>
<SubMenu actionRef="RETAIL::MENU.MODIFY_LINE_TAX">
<MenuOption ref="RETAIL::TAX.CHANGE_LINE_LOCATION"/>
<MenuOption ref="RETAIL::TAX.EXEMPT_LINE"/>
<MenuOption ref="RETAIL::TAX.CHANGE_LINE_AMOUNT"/>
<MenuOption ref="RETAIL::TAX.CHANGE_LINE_PERCENT"/>
</SubMenu>
<MenuOption ref="RETAIL::VOID_LINE"/>
<MenuOption ref="RETAIL::CHANGE_DISCOUNT"/>
<MenuOption ref="RETAIL::CHANGE_COMMISSIONED_ASSOCIATES"/>
</MenuItem>

About this configuration

This configuration option was created to handle “Change X” operations since most of
these operations are only performed on a single item at a time, and the user should not
have to manually escape out of that menu to return to ringing items. Setting the options
on a “Change X” sub-menu to have non-sticky parents automatically backs the user out
of that sub-menu when one of those operations is completed.
“Sticky” pushes the “sticky parent” setting down onto all of the descendants of the menu
on which it is declared; the programmatic logic only cares about the “sticky parent”
setting because it’s declared at the level that actually governs whether an option is likely
to be invoked repeatedly.

Hide Menu Options Based on Security Privilege

In SysConfig.xml, the option “HideDeniedSecureOption” can be used to hide menu
options the user does not have security privileges to use. See “Security-Related
Configuration: Menu Visibility” in Chapter 12, “Security Configuration” for more
information.
<Setting name="HideDeniedSecureOption">false</Setting>

Configurable Button Layout

Changing the menu button layout is a configurable parameter in SysConfig.xml.

Note: These settings will not impact the Xmobile menu layout which
remains fixed at a 3x2 grid.

Menu & Tab Configuration 38-7

Configurable Button Layout

SysConfig.xml example
SysConfig.xml element "MenuButtonCount" dictates the number of buttons on a menu.
<Setting name="Terminal---MenuButtonCount">13</Setting>

Note: The primaryTerminalNumber can be configured in the

system.properties file. See system.properties example below.
The RegistrationUpdateInterval configuration has been
removed from the SysConfig.xml file. The configuration has been
moved to config.jar/dtv/res/config/spring/workers.xml
bean id startDeviceRegistrationWorker.

system.properties example
The primary terminal number can be configured in the system.properties file.
Example:
dtv.location.primaryTerminalNumber=1

UIConfig.xml example
In addition, a corresponding change is required to UIConfig.xml in the following
locations:
<Component name="MENU_VIEW" type="MenuView" layoutLocation="0,
616, 1024, 75" layoutLayer="30"
layout="dtv.ui.layout.CenteringLayout">
<LayoutParameters dtype="ParameterList">
<parameter name="setSize">
<param_value dtype="Integer">13</param_value>
<param_value dtype="Integer">1</param_value>
</parameter>
<parameter name="setGaps">
<param_value dtype="InsetsRef">_gapsButtonView</
param_value>
</parameter>
<parameter name="setMargins">
<param_value dtype="InsetsRef">_marginButtonView</
param_value>
</parameter>
</LayoutParameters>
</Component>

Note: There are two of these references in UIConfig.xml — both

must be changed.

• <param_value dtype="Integer">13</param_value> (represents columns)

• <param_value dtype="Integer">1</param_value> (represents rows)

38-8 Technical Guide

 Tab Setup

For example, the "13" shown in “UIConfig.xml example” needs to be changed to match
whatever value is assigned to the "MenuButtonCount" element in SysConfig.xml.

Note: The maximum button count is limited to 25. Java only

recognizes fkey mappings up to F24.

Button Layout Example: 10 Buttons in 2 Rows

Set SysConfig.xml
<Setting name="Terminal---MenuButtonCount">10</Setting>
<Setting name="Terminal---RegistrationHistoryDays">3</Setting>

Set UIConfig.xml
<Component name="MENU_VIEW" type="MenuView" layoutLocation="0,
616, 1024, 75" layoutLayer="30"
layout="dtv.ui.layout.CenteringLayout">
<LayoutParameters dtype="ParameterList">
<parameter name="setSize">
<param_value dtype="Integer">10</param_value>
<param_value dtype="Integer">2</param_value>
</parameter>
<parameter name="setGaps">
<param_value dtype="InsetsRef">_gapsButtonView</
param_value>
</parameter>
<parameter name="setMargins">
<param_value dtype="InsetsRef">_marginButtonView</
param_value>
</parameter>
</LayoutParameters>
</Component>

Tab Setup
The Tab Library provides multiple options for information tabs and web widgets,
beyond the standard tabs traditionally provided in the Information area with base
Xstore Point of Service.

Menu & Tab Configuration 38-9

Tab Setup

These tabs can be configured to work in different contexts. For example, tabs that display
in “login mode” may not be the same tabs that are available during “transaction mode”.
The base implementation
of Xstore Point of Service
displays five (5)
information tabs: Info,
Tasks, (Sales) Goals,
Messages, and Keypad. The tabs and widgets in the library can be used in place of—or in
addition to—the tabs provided with base Xstore Point of Service.

Note: Xstore Office can be used to easily manage the library. You
decide which tabs will be in use, and where they will be used. It is
possible to add more or less than the standard five tabs delivered in
base Xstore Point of Service; however, for best results a limit of five
tabs per context is recommended.

Tab Library Options

The following tabs are pre-configured and found in the Tab Library (TabConfig.xml):

Tab Description

ACTIVITY_STREAM This is a view-only tab that displays the activity stream for
the customer attached to the current transaction. This tab
allows the associate to quickly view information about the
customer without transitioning to customer maintenance.
The information shown here is the same activity stream
found in customer maintenance. This tab is only available
within the transaction context.

QUICK_LAUNCH This tab displays a set of retailer-defined "quick launch"

buttons that provide associates with quick and easy access
to commonly used programs and websites.

TRANSACTION_COUPONS
This tab lists all of the deal coupons scanned during a
transaction. In base Xstore Point of Service, the Sales
Goals tab will be replaced with this Coupons tab when an
associate is in the transaction context. A check mark next to
each coupon indicates whether it has been applied in the
transaction. For example, if a coupon is voided in the
transaction, the check mark will be removed from the
coupon in the list, indicating it has been scanned, but is not
currently applied.

SALES_GOAL This tab displays information about sales goals that are set
for the store by the corporate office. These goals are
available for all employees to view and are set for a
specified date range.

MESSAGE_AREA It is recommended to keep this tab in the message area as it

often contains important user instructions. Depending on
which screen the user is in, and the context/mode, the INFO
tab may display a message that is related to navigation
instructions, or product-specific information.

NUMERIC_KEYPAD This tab contains a numeric keypad that can be used to

enter numeric characters into Xstore Point of Service.
Often, touch screen users will benefit from setting system
configurations that will automatically display the Keypad
when it is most convenient for associates.

38-10 Technical Guide

 Tab Setup

Tab (continued) Description

EMPLOYEE_MESSAGES This tab displays messages sent from the corporate office, or
from store management. Messages require no action, and
may be store-specific or register-specific.

ORDER_WORKLIST This tab is view-only and displays information about

distributed orders. Associates can use this tab to quickly
view order information, even when they are not in a sale
transaction. Statistics shown here include the number of
Ship Orders, Pick Up Orders, Items Awaiting Pickup, and
Unfulfillable Orders. Other information includes the order
number and type, customer name and contact number, if
applicable, and the date and age of the order.

QUICK_ITEMS This tab displays images for commonly sold items,

providing associates with a quick and easy way to add an
item to a transaction by clicking on a graphic that represents
the item. For example, this tab can be used for convenience
items at the check-out counter. It could be as simple as a
shoe retailer putting various types of laces in this tab, or a
fashion retailer putting accessories on the tab. The items
placed on this tab are not restricted by the merchandise
hierarchy which means they can be placed in any order.
This offers an extra level of convenience at the check-out.
This tab is only available within the transaction context.
The dot(s) shown at the bottom of this tab indicate the
number of pages. If there are multiple dots, then there are
multiple pages. Swipe on the dots to get to the next
available page.

EMPLOYEE_SCHEDULE This tab is view-only and displays a list of the associates

that are currently clocked in at the store, and a list of the
associates scheduled to work today. Associates can use this
tab to see who is currently clocked in at the store so they
know who is around to help them now, and to know who
they can rely on in later shifts.

ASSOCIATE_TASKS This setting is for the Tasks tab. It is view-only and displays
open and in progress tasks for the current system day.

URL_NAVIGATOR_XYZ This tab provides the ability to display a designated URL

for the associate within the boundaries of the tab. For
example, specific URLs that associates need to access such
as a company policy intranet or a SharePoint site to perform
functions that are not facilitated by the POS system. Using
this tab, the associate does not have to leave the POS system
to open a browser or enter a URL (or keep bookmarks). This
creates a secure experience for the associates.

TabConfig.xml Setup
Note: TabConfig.xml is located in the uipropertysets folder.

TabConfig.xml contains a set of tab definitions available to use in the information area
of Xstore Point of Service. The TabConfig.xml tab definitions are represented by
ComponentPropertySet configs.
<ComponentPropertySet name="TABBED_PANE_DEFAULT">
<ComponentID>MessageAreaTabs</ComponentID>

Menu & Tab Configuration 38-11

Tab Setup

<ComponentProperty>
<Property>tab1</Property>
<Value>MESSAGE_AREA</Value>
</ComponentProperty>
<ComponentProperty>
<Property>tab2</Property>
<Value>ASSOCIATE_TASKS</Value>
</ComponentProperty>
<ComponentProperty>
<Property>tab3</Property>
<Value>SALES_GOAL</Value>
</ComponentProperty>
<ComponentProperty>
<Property>tab4</Property>
<Value>EMPLOYEE_MESSAGES</Value>
</ComponentProperty>
<ComponentProperty>
<Property>tab5</Property>
<Value>NUMERIC_KEYPAD</Value>
</ComponentProperty>
</ComponentPropertySet>

....Edited for brevity

Tab Component Property Set Example (MESSAGE_AREA)

<ComponentPropertySet name="MESSAGE_AREA" >
<ComponentProperty>
<Property>tab</Property>
<ComplexValue>
<Name>MESSAGE_AREA</Name>
<Type>ItemMessageView</Type>
</ComplexValue>
</ComponentProperty>
<ComponentProperty>
<Property>tabTitle</Property>
<Value>_infoTabTitle</Value>
</ComponentProperty>
<ComponentProperty>

38-12 Technical Guide

 Tab Setup

<Property>tabIcon</Property>
<ComplexValue>
<Icon>_imageInfoTab</Icon>
<Scale>false</Scale>
</ComplexValue>
</ComponentProperty>
</ComponentPropertySet>

ComponentPropertySetConfig.xml
Note: ComponentPropertySetConfig.xml is located in the
uipropertysets folder.

The ComponentPropertySetConfig.xml has defined two ComponentPropertySet

configurations, one used by default (TABBED_PANE_DEFAULT) and the other one
(TABBED_PANE_TRANSACTION) used in the transaction context.

ui-beans.xml Spring File

The tab refresh behaviors and intervals are configurable in the ui-beans.xml spring
file.
Examples:
<bean id="salesGoalHtmlContentInfo"
class="dtv.pos.framework.html.ContentInfo" init-method="init">
<constructor-arg value="SALES_GOAL" />
<property name="refreshInterval" value="60" />
</bean>

<bean id="associateTasksHtmlContentInfo"
class="dtv.pos.framework.html.ContentInfo" init-method="init">
<constructor-arg value="ASSOCIATE_TASKS" />
<property name="refreshInterval" value="5" />
</bean>

<bean id="transactionCouponsHtmlContentInfo"
class="dtv.pos.framework.html.ContentInfo" init-method="init">
<constructor-arg value="TRANSACTION_COUPONS" />
<property name="transactionBased" value="true" />
</bean>

<bean id="messageAreaHtmlContentInfo"
class="dtv.pos.framework.html.ContentInfo" init-method="init">

Menu & Tab Configuration 38-13

Tab Setup

<constructor-arg value="MESSAGE_AREA" />

<property name="dynamic" value="true" />
</bean>

<bean id="airsideMessagesHtmlContentInfo"
class="dtv.pos.framework.html.ContentInfo" init-method="init">
<constructor-arg value="AIRSIDE_MESSAGES" />
<property name="refreshSignals">
<list>
<value>TransactionComplete</value>
<value>TransactionCancelled</value>
<value>TransactionResumed</value>
</list>
</property>
</bean>

SysConfig.xml Settings
The following configuration options are available in SysConfig.xml:

Quick Items Tab

<Setting name="QuickItems---TabWidth">4</Setting>
TabWidth - Defines the number of columns (width) of the tab.

Associate Tasks Tab

<Setting name="AssociateTasks---FutureDaysAge">30</Setting>
<Setting name="AssociateTasks---PreviousDaysAge">30</Setting>
PreviousDaysAge - The number of days prior to the current business date to search
tasks.
FutureDaysAge - The number of days after the current business date to search tasks.

Tab Setup Options

Note: Xstore Office can be used to easily manage the library.
Additional setup and configuration information is provided in the
Xstore Office User Guide.

TabConfig.xml is located in config.jar\dtv\res\config\uipropertysets\

In TabConfig.xml, the tabs are referenced by name.
• To replace a current tab with a different tab:
<ComponentProperty>
<Property>tab3</Property>
<Value>SALES_GOAL</Value>

38-14 Technical Guide

 Item Selection Grid

</ComponentProperty>
a. Value - Type the name of the new tab (as specified in the TabConfig.xml) to
replace the name of the existing tab.
b. Save the file.
• To add another tab, add a new ComponentProperty in TabConfig.xml:
<ComponentProperty>
<Property>tab6</Property>
<Value>ORDER_WORKLIST</Value>
</ComponentProperty>
a. Property - Type the tab number.
b. Value - Type the tab name.
c. Save the file.

Note: It is possible to add more or less than the standard five tabs
delivered in base Xstore Point of Service; however, for best results, a
limit of six tabs is recommended.

Item Selection Grid

The Item Selection User Interfaces enables a retailer to use a button grid to select
configurable menu options and items. This feature enables a retailer to have buttons in
an 13 x 3 matrix. The following button types are available:
• ITEM
Item buttons are mapped to specific items in the database. These buttons allow you
to add items to your transaction more quickly.
• MENU
All sub menu buttons can be configured as menu buttons. The visibility rules of the
menu buttons are the same as the base Xstore visibility rules.Visibility rules are
defined in the ActionConfig.xml.
• DRILLDOWN
Drilldown buttons are used to go to next level in the button matrix. The next level
has its own set of item, menu and drilldown buttons.
Home and Back buttons are a mandatory part at each drilldown level to navigate
back and directly to the home screen.
For more information about drilldown buttons, see the Drilldown Button section.
For buttons to be displayed, the component ID for the button matrix should always be
BUTTON_GRID_MAIN.
Any value which is beyond the defined matrix will be ignored. For example, if a button
is placed outside of the specified row or column it will be ignored. Any overlapping
button will be ignored from button matrix. Overlapping buttons and buttons which are
beyond the matrix range are logged at startup.

Menu & Tab Configuration 38-15

Item Selection Grid

Enabling the Button Matrix

To enable the button matrix add :buttonmatrix to the config path base features in the
configPath.properties file.
xstore.config.path.base.features= :buttonmatrix

com_button_grid Table
The button grid configurations are stored in the com_button_grid table. For more
information on the table and the button grid record, see the Oracle Retail Xstore‐Point‐of‐
Service Software Database Dictionary and the Oracle Retail Xstore Point of Service Host
Interface Guide.

Xstore Context and Button Matrix

The buttons which are displayed on a particular screen are based on different contexts
present in Xstore. The ContextConfig.xml file contains all the contexts present in Xstore.
For example, for a button to be displayed on Sale screen the context is SALE and the
GRID_ID in the table com_button_grid is SALE.

Drilldown Button
A button with the KEY_NAME of DRILLDOWN will behave as drilldown option and will
drop one level down in the button matrix. Drilldown buttons should always have a
CHILD_ID. The CHILD_ID will be the GRID_ID for the next level down.
For example, if a drilldown button has a CHILD_ID of SALE_CHILD then all the
buttons, which need to be displayed in the next level down, should have SALE_CHILD
as the GRID_ID.

Button Coloring
There are different button colors available for different buttons. All the colors defined in
the ui.properties file.
• Action Buttons - These buttons are colored as per default Xstore.
• Item Button
The coloring options are:
_colorItemButtonNormal=127,0,0
_colorItemButtonDisabled=184,184,184
_colorItemButtonPressed=62,79,81
_colorItemButtonMouseover=127,50,49
• Drilldown Buttons
The coloring options are:
_colorDrilldownButtonNormal=4,14,215
_colorDrilldownButtonDisabled=184,184,184
_colorDrilldownButtonPressed=62,79,81
_colorDrilldownButtonMouseover=54,64,215

38-16 Technical Guide

 Item Selection Grid

Menu & Tab Configuration 38-17

Item Selection Grid

38-18 Technical Guide

 39
BIN Ranges

Overview
BIN (Bank Identification Number) range values for authorized card tenders must be
downloaded to Xstore Point of Service.
Card number specifications, as defined by the issuing authority, need to be loaded onto
POS systems to support card number differentiation. This drives authorization-related
functionality. The card number specification is based on BIN range prefix definition,
along with the length of the PAN (Primary Account Number).

Note: Debit BIN files can be downloaded to your registers using

Xstore Office.

Specifications
In Xstore Point of Service, the card number specifications are downloaded and stored in
a flat text format. A file is maintained for each separate card type such as debit, gift card
(also known as stored value), Discover, or VISA. The card number specifications for each
card type will need to be sorted within the file, first by PAN length and then by BIN
(prefix). Comments may be added to the file by starting a line with the “pound” sign (#).
Here are some theoretical examples for a file that would be named debit.txt:
00503223
12582322
13409449
13419002125
13500072
16412345
1641246
The format of the card number specification files is always:
XXYYYY...
where:
• XX = the number of digits in the card number (a.k.a., card number length)
• YYYY... = 1 or more digits of the card number prefix
Two zeros (00) can be used to signify any card number length.

BIN Ranges 39-1

File Naming Conventions

Examples
• 14121212 indicates a 14-digit number starting with “121212”
• 00503223 indicates a number of any length starting with “503223”.

File Naming Conventions

File names are case sensitive and should ALWAYS be created in all lower case and carry
the “.txt” extension. All card number specification files will be stored in the xstore/
res/binfile folder on each Xstore Point of Service workstation (register).
The following naming conventions have been adopted:
• Debit cards (from any issuer) – debit.txt
• Stored value cards (from any issuer) – svc.txt
May include gift cards and merchandise credit cards
• Merchandise credit cards (stored value card for refunds, only) – mcc.txt
To be used if need to be differentiated from gift cards
• Coupon gift cards (any issuer) – coupongiftcard.txt
• Private label / store-branded cards (any issuer) – privatelabel.txt
• Shopper / Loyalty cards – loyalty.txt
• VISA credit cards – visa.txt
• MasterCard credit cards* – mastercard.txt
• Discover Card credit cards* – discovercard.txt

• AMEX credit cards1 – amex.txt

• JCB credit cards – jcb.txt
• Employee swipe cards - emp-msr.txt
• Employee scan cards - emp-scan.txt

Note: Other tender instrument numbering ranges may be able to be

supported; to be determined on request.

1.Should include any co‐branded card types

39-2 Technical Guide

 40
Data Purger Overview

Important: This chapter provides a basic overview of Data Purger

and the technology underlying its design. The database purge process
requires extensive knowledge of the underlying data model and
should not be modified by anyone other than Oracle Xstore Point of
Service development staff.

Overview
The Data Purger is a database maintenance tool used to delete records according to a set
of configuration parameters. A base set of configuration options is provided with the
tool that will delete data from the database based on a configurable time period. For
example, retail sale transactions older than 365 days, or employee payroll records older
than 180 days can be scheduled for deletion.
There are two types of purges:
1. Transactional — Transactional purges are rooted at the primary transaction table
trn_trans and are handled by the purge group named “Transaction”. They alone
support the “type” parameter identifying the trn_trans.trans_typcode value
for records to be considered for purging.
2. Non-transactional — Non-transactional purges are defined by various criteria
outside a trn_trans-rooted hierarchy. They are defined by purge groups named
for the Xstore Point of Service schema domain whose tables they purge. For
example, the “HRS” group purges data from tables in the “hrs” domain. Specifically
in this case, it purges all hrs_employee records whose terminated_dates are a
specified number of days in the past, then purges all associated tables (e.g.
hrs_employee_password) that are left orphaned by the primary delete.

Note: Some purge groups represent tables from multiple domains.

This only occurs in cases where those domain-exterior tables don't
functionally belong in their own group. For example, the CAT group
includes some Work Order-related tables from the CWO domain
because those tables should be purged when all customer account
information is being purged.

Assumptions
Data Purger assumes the use of a standard base Xstore Point of Service database.
Custom, non-base Xstore Point of Service databases may require specialized
configuration, or possibly a customized version of the Data Purger.

Data Purger Overview 40-1

Specifications

Specifications
• The primary purge configuration set is defined in purge/PurgeConfig.xml.
• All queries referenced by PurgeConfig.xml can be found in
/purge/query/purges.*.xml, where * is a dash-separated list of three-letter
table domains located in that file. The exception is purges.transaction.xml,
which handles all purges rooted at the primary transaction table trn_trans.
• To run the Data Purge tool, run the datapurger.bat in the Xstore Point of Service
directory.
• Data Purger results are reported in log/purge.log.

Data Purger Configuration

The following files must be configured based on business requirements:
• PurgeConfig.xml — primary purge configuration set.
• purges.*.xml — All queries referenced by PurgeConfig.xml.
(Where * is a dash-separated list of three-letter table domains contained within that
file. For example, purges.cat-crm-cwo.xml and purges.tnd-tsn-ttr.xml)
The following can be enabled/disabled via a flag in PurgeConfig.xml. The default
value is FALSE.

Note: Individual queries can be disabled from within an enabled

group. However, if a group is disabled, all of its queries will be ignored
regardless of whether or not they are enabled.

When set to FALSE:

- CRM -> * // Do not purge any customers2

- DSC -> * // Do not purge any discounts
- HRS -> * // Do not purge any employees

- ITM ->* // Do not purge any items3

- PRC -> * // Do not purge any deals
- TND -> * // Do not purge any tenders

- TSN -> * // Do not purge any sessions4

2. If the CRM group purge is enabled (TRUE), there is a clause in the crm_party purge query that ensures only re-
cords without any corresponding customer accounts are deleted.
The CRM group has been assigned a higher order than the CAT group in PurgeConfig.xml so the CAT group can
run first and delete any customer accounts that satisfy specified criteria (e.g. CLOSED). The net effect is that a
crm_party record will not be purged if it has any corresponding customer accounts that do not qualify for purging.

3. itm_warranty_journal records are transactional and will be purged if their parent trn_trans records are
also purged.

4. TSN tables that are transactionalized will be purged if their parent trn_trans record is also purged. TSN tables
representing non-transactionalized session information (specifically: tsn_session, tsn_session_tndr, and
tsn_session_wkstn) will not be purged by default.

40-2 Technical Guide

 About Purge Config

About Purge Config

PurgeConfig.xml
PurgeConfig.xml controls the flow of Data Purger. The major categories are
implemented as Groups:
• The transactional purge Group is named “Transaction”.
• The non-transactional purge Groups are named for the Xstore Point of Service
schema domain whose tables they purge, allowing for a logical grouping and for
prioritization.
Table 40-1 PurgeConfig.xml Properties Definitions

Tag Description

Group

name Name of the purge group to run. For non-transactional purges, named for the
Xstore Point of Service schema domain whose tables they purge.

order The purge order for the group.

age Group records older than the number of days here will be purged.

status The status of records to be considered for purging. This value is ignored in
cases where status is irrelevant.

status1 See status.

status2 See status.

enabled If TRUE, this group is available for purging. If FALSE, this group will not be
purged. See “Data Purger Configuration” for a list of applicable groups.

Query

name The name of the query to be called.

key Identifies the query to run.

order The query order.

age Group records older than the number of days here will be queried.

status The status of records to be considered for purging.

status1 See status.

status2 See status.

Data Purger Overview 40-3

About Purge Config

PurgeConfig.xml example
..............Edited for brevity.........
<Group name="XOM" order="0" age="365" status1="COMPLETE"
status2="CANCELLED">
<Query name="xom_order" order="0"/>
<Query name="xom_order_line" key="xom_order.child" order="10"/
>
<Query name="xom_order_line_detail" key="xom_order.child"
order="10"/>
<Query name="xom_customer_mod" key="xom_order.child"
order="10"/>
<Query name="xom_address_mod" key="xom_order.child"
order="10"/>
<Query name="xom_fulfillment_mod" key="xom_order.child"
order="10"/>
<Query name="xom_source_mod" key="xom_order.child" order="10"/
>
<Query name="xom_item_mod" key="xom_order.child" order="10"/>
<Query name="xom_order_payment" key="xom_order.child"
order="10"/>
<Query name="xom_order_fee" key="xom_order.child" order="10"/>
<Query name="xom_balance_mod" key="xom_order.child"
order="10"/>
<Query name="xom_fee_mod" key="xom_order.child" order="10"/>
<Query name="xom_order_mod" key="xom_order.child" order="10"/>
</Group>
............Edited for brevity.........

40-4 Technical Guide

 About Purge Config

purges.*.xml
Note: In this section, * represents a dash-separated list of three-letter
table domains covered in that file. For example, purges.hrs-sch-
thr.xml

These files can be found in a query within the Xstore Point of Service config path (e.g. as
purge/query/purges.hrs-sch-thr.xml, purge/query/purges.xom.xml,
etc.). The query name is the same as referenced in the PurgeConfig.xml.
Table 40-2 purges.*.xml Properties Definitions

Tag Description

name The query name.

QueryHandler The SQL query handler

(dtv.data2.access.query.SqlQueryHandler) should always
be specified.

Property The key/value pair.

SQL: The SQL statement that will remove the targeted data.
Parameters: The arguments that will be passed to the query.

purges.xom.xml example
<Query name="xom_order">
<QueryHandler
dtype="Class">dtv.data2.access.query.SqlQueryHandler</
QueryHandler>
<SQL>
<Statement dtype="String"><![CDATA[
DELETE FROM xom_order
WHERE organization_id = ?
AND order_date < ?]]></Statement>
<Parameter name="argOrganizationId"/>
<Parameter name="argDate"/>
<Expression trigger="argStatus1" parameters="argStatus1,
argStatus2"><![CDATA[(status_code = ? OR status_code = ?)]]></
Expression>
</SQL>
</Query>
<Query name="xom_order.child">
<QueryHandler
dtype="Class">dtv.data2.access.query.SqlQueryHandler</
QueryHandler>
<SQL>
<Statement dtype="String"><![CDATA[

Data Purger Overview 40-5

Tables Available for Purging

DELETE {%ALIAS%} FROM {%TABLE%} c

WHERE organization_id = ?
AND NOT EXISTS
(Select p.* From xom_order p
Where p.organization_id = c.organization_id
And p.order_id = c.order_id)]]></Statement>
<Parameter name="argOrganizationId"/>
</SQL>
</Query>
</QuerySet>

Tables Available for Purging

General Table Information
• All tables that have a non-configured, non-audit date field (e.g. anything other than
create_date, update_date, or a “date value” configuration setting).
• All tables that have a delete_flag or void_flag.
• All tables that are “natural” associates of tables meeting any of the above criteria.
If, for example, table “X” has an expiration_date column that qualifies it for purging
and table “Z” can join with “X” via key or other reliable field relationships, then “Z”
will also be considered for purging. More specifically, the Data Purger will delete all
qualified “X” records and then delete all “Z” records that are now orphaned from
“X”.

Detail Table Information

The sections “Transactional Purges” and “Non-Transactional Purges” list the specific
tables purged by Data Purger. (The non-transactional purges are grouped by domain
and organized in alphabetical order).
Purge group - The default order, age, status (if applicable), and enabled flag (if
applicable) are shown for each group.
Tables within the purge group - The table name, default order, and key (if applicable)
are shown for each table in the purge group. An order of “0” (zero) indicates a root table.

40-6 Technical Guide

 Tables Available for Purging

Transactional Purges
Refer to “PurgeConfig.xml Properties Definitions” for an explanation of the purge
configuration values shown in the following tables for both Transactional and Non-
Transactional purges.

Note: A condition exists in the trn_trans query to exclude any

transactions with corresponding cat_cust_item_acct_activity
records from deletion. In addition, the Transaction group has been
assigned a higher order (10) so the CAT group purge will run first,
deleting any cat_cust_item_acct_activity records for accounts
which are eligible for purging. This ensures that no transactions are
deleted if they correspond to customer accounts which themselves are
not eligible for deletion.

Table 40-3 Transaction Tables Purged by Data Purger (Sheet 1 of 3)

Group Default Order Default Age Default Status

Transaction 10 365 NA

Table Name Key=1 Order=

trn_trans2 0

cat_authorizations trn_trans.child3 10

cwo_work_order_line_item trn_trans.child 10

inv_invctl_trans trn_trans.child 10

inv_invctl_trans_detail trn_trans.child 10

inv_inventory_journal trn_trans.child 10

inv_movement_pending trn_trans.child 10

inv_movement_pending_detail trn_trans.child 10

inv_mptrans_lineitm trn_trans.child 10

inv_sum_count_trans_dtl trn_trans.child 10

itm_warranty_journal4 10

rpt_sale_line trn_trans.child 10

thr_timeclk_trans trn_trans.child 10

trl_ar_sale_lineitm trn_trans.child 10

trl_commission_mod trn_trans.child 10

trl_correction_mod trn_trans.child 10

trl_coupon_lineitm trn_trans.child 10

trl_cust_item_acct_mod trn_trans.child 10

Data Purger Overview 40-7

Tables Available for Purging

Table 40-3 Transaction Tables Purged by Data Purger (Sheet 2 of 3)

Group Default Order Default Age Default Status

Transaction 10 365 NA

Table Name (continued) Key=1 Order=

trl_deal_lineitm trn_trans.child 10

trl_dimension_mod trn_trans.child 10

trl_discount_lineitm trn_trans.child 10

trl_escrow_trans trn_trans.child 10

trl_invctl_document_mod trn_trans.child 10

trl_inventory_loc_mod trn_trans.child 10

trl_returned_item_count trn_trans.child 10

trl_returned_item_journal trn_trans.child 10

trl_rtl_price_mod trn_trans.child 10

trl_rtrans trn_trans.child 10

tr._rtrans_flight_info trn_trans.child 10

trl_rtrans_lineitm trn_trans.child 10

trl_sale_lineitm trn_trans.child 10

trl_sale_tax_lineitm trn_trans.child 10

trl_tax_lineitm trn_trans.child 10

trl_voucher_discount_lineitm trn_trans.child 10

trl_voucher_sale_lineitm trn_trans.child 10

trl_warranty_modifier trn_trans.child 10

trn_generic_lineitm_storage trn_trans.child 10

trn_no_sale_trans trn_trans.child 10

trn_poslog_data trn_trans.child 10

trn_post_void_trans trn_trans.child 10

trn_raincheck_trans trn_trans.child 10

trn_receipt_data trn_trans.child 10

trn_receipt_lookup trn_trans.child 10

trn_trans_link trn_trans.child 10

trn_trans_notes trn_trans.child 10

trn_trans_p trn_trans.child 10

40-8 Technical Guide

 Tables Available for Purging

Table 40-3 Transaction Tables Purged by Data Purger (Sheet 3 of 3)

Group Default Order Default Age Default Status

Transaction 10 365 NA

Table Name (continued) Key=1 Order=

tsn_serialized_tndr_count trn_trans.child 10

tsn_session_control_trans trn_trans.child 10

tsn_till_control_trans trn_trans.child 10

tsn_till_ctrl_trans_detail trn_trans.child 10

tsn_tndr_control_trans trn_trans.child 10

tsn_tndr_denomination_cont trn_trans.child 10

tsn_tndr_tndr_count trn_trans.child 10

tsn_tndr_typcode_count trn_trans.child 10

tsn_xrtrans_lineitm trn_trans.child 10

ttr_acct_credit_tndr_lineitm trn_trans.child 10

ttr_ar_tndr_lineitm trn_trans.child 10

ttr_check_tndr_lineitm trn_trans.child 10

ttr_coupon_tndr_lineitm trn_trans.child 10

ttr_credit_debit_tndr_lineitm trn_trans.child 10

ttr_identity_verification trn_trans.child 10

ttr_send_check_tndr_lineitm trn_trans.child 10

ttr_signature trn_trans.child 10

ttr_tndr_auth_log trn_trans.child 10

ttr_tndr_lineitm trn_trans.child 10

ttr_voucher_tndr_lineitm trn_trans.child 10

xom_order_mod trn_trans.child 10

1. Where a key is not explicitly specified it is the same as the query name (e.g. the key for the
"trn_trans" query is "trn_trans").
2. WHERE business_date < ? AND
<no customer account activity exists for this transaction>
i.e. there is no row match joining:
organization_id = cat_cust_item_acct_activity.organization_id AND
rtl_loc_id = cat_cust_item_acct_activity.rtl_loc_id AND
wkstn_id = cat_cust_item_acct_activity.wkstn_id AND
business_date = cat_cust_item_acct_activity.business_date AND
trans_seq = cat_cust_item_acct_activity.trans_seq

Data Purger Overview 40-9

Tables Available for Purging

3. WHERE <no matching transaction exists>

i.e. there is no row match joining:
organization_id = trn_trans.organization_id AND
rtl_loc_id = trn_trans.rtl_loc_id AND
wkstn_id = trn_trans.wkstn_id AND
business_date = trn_trans.business_date AND
trans_seq = trn_trans.trans_seq
4.WHERE <no matching transaction exists for the journal record>
i.e. there is no row match joining:
organization_id = trn_trans.organization_id AND
trans_rtl_loc_id = trn_trans.rtl_loc_id AND
trans_wkstn_id = trn_trans.wkstn_id AND
trans_business_date = trn_trans.business_date AND
trans_trans_seq = trn_trans.trans_seq
OR
<no matching transaction exists for the warranty line associated with the journal record>
i.e. there is no row match joining:
organization_id = trn_trans.organization_id AND
warranty_line_rtl_loc_id = trn_trans.rtl_loc_id AND
warranty_line_wkstn_id = trn_trans.wkstn_id AND
warranty_line_business_date = trn_trans.business_date AND
warranty_line_trans_seq = trn_trans.trans_seq
OR
<no matching transaction exists for the merchandise line covered by the warranty associated with
the journal record>
i.e. there is no row match joining:
organization_id = trn_trans.organization_id AND
covered_line_rtl_loc_id = trn_trans.rtl_loc_id AND
covered_line_wkstn_id = trn_trans.wkstn_id AND
covered_line_business_date = trn_trans.business_date AND
covered_line_trans_seq = trn_trans.trans_seq

40-10 Technical Guide

 Tables Available for Purging

Non-Transactional Purges
Table 40-4 CAT Domain - Tables Purged by Data Purger (Sheet 1 of 2)

Group Default Order Default Age Default Status

CAT 0 365 CLOSED

Table Name Key=1 Order=

cat_cust_acct2 0

cat_cust_acct_card3 0

cat_cust_loyalty_acct4 0

cat_cust_acct_plan5 0

cat_escrow_acct6 0

cat_acct_note cat_cust_acct.child7 10

cat_charge_acct_history cat_cust_acct.child 10

cat_charge_acct_invoice cat_cust_acct.child 10

cat_charge_acct_users cat_cust_acct.child 10

cat_cust_acct_journal cat_cust_acct.child 10

cat_cust_acct_p cat_cust_acct.child 10

cat_cust_consumer_charge_acct cat_cust_acct.child 10

cat_cust_item_acct cat_cust_acct.child 10

cat_cust_item_acct_activity cat_cust_acct.child 10

cat_cust_item_acct_detail cat_cust_acct.child 10

cat_cust_item_acct_journal cat_cust_acct.child 10

cat_delivery_modifier cat_cust_acct.child 10

cat_payment_schedule cat_cust_acct.child 10

cwo_work_item cat_cust_acct.child 10

cwo_work_order_acct cat_cust_acct.child 10

cwo_work_order_acct_journal cat_cust_acct.child 10

cwo_invoice cwo_work_order 20
_acct.child8

cwo_invoice_lineitm cwo_work_order 20
_acct.child

cat_award_acct cat_cust_acct_ 10
card.child9

Data Purger Overview 40-11

Tables Available for Purging

Table 40-4 CAT Domain - Tables Purged by Data Purger (Sheet 2 of 2)

Group Default Order Default Age Default Status

CAT 0 365 CLOSED

Table Name (continued) Key=1 Order=

cat_award_acct_coupon cat_cust_acct_ 10
card.child

cat_cust_loyalty_acct cat_cust_acct_ 10
card.child

cat_escrow_acct_activity cat_escrow_acct.chi 10
ld10

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. WHERE last_activity_date < ?
3. WHERE expr_date < ?
4. WHERE expiration_date < ?
5. WHERE expiration_date < ?
6. WHERE last_activity_date < ?
7. WHERE <no matching customer account exists>
i.e. there is no row match joining:
organization_id = cat_cust_acct.organization_id AND
cust_acct_code = cat_cust_acct.cust_acct_code AND
cust_acct_id = cat_cust_acct.cust_acct_id
8. WHERE <no matching work order account exists>
i.e. there is no row match joining:
organization_id = cwo_work_order_acct.organization_id AND
service_loc_id = cwo_work_order_acct.service_loc_id AND
invoice_number = cwo_work_order_acct.invoice_number
9. WHERE <no matching customer card account exists>
i.e. there is no row match joining:
organization_id = cat_cust_acct_card.organization_id AND
cust_card_nbr = cat_cust_acct_card.cust_acct_card_nbr
10. WHERE <no matching escrow account exists>
i.e. there is no row match joining:
organization_id = cat_escrow_acct.organization_id AND
cust_acct_id = cat_escrow_acct.cust_acct_id

40-12 Technical Guide

 Tables Available for Purging

Table 40-5 CIVC Domain - Tables Purged by Data Purger

Group Default Order Default Age Default Status

CIVC 0 365 CLOSED

Table Name Key=1 Order=

civc_invoice2 0

civc_invoice_p civc_invoice.child3 10

civc_invoice_xref civc_invoice.child 10

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2.DELETE FROM civc_invoice WHERE organization_id = ? AND business_date < ?
3.DELETE {%ALIAS%} FROM {%TABLE%} c WHERE organization_id = ? AND NOT EXISTS
(Select p.* From civc_invoice p Where p.organization_id = c.organization_id And p.rtl_loc_id =
c.rtl_loc_id And p.wkstn_id = c.wkstn_id And p.business_year = c.business_year And p.se-
quence_id = c.sequence_id And p.sequence_nbr = c.sequence_nbr)

Table 40-6 COM Domain - Tables Purged by Data Purger

Group Default Order Default Age Default Status

COM 0 365 NA

Table Name Key=1 Order=

com_receipt_text2 0

com_report_data3 0

com_report_lookup4 0

com_trans_prompt_properties5 0

com_report_lookup com_report_data.c 10
hild6

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. WHERE expiration_date < ?
3. WHERE delete_flag = 1
4. WHERE delete_flag = 1
5. WHERE expiration_date < ?
6. WHERE <no matching report data exists>
i.e. there is no row match joining:
organization_id = com_report_data.organization_id AND
owner_type_enum = com_report_data.owner_type_enum AND
owner_id = com_report_data.owner_id AND
report_id = com_report_data.report_id

Data Purger Overview 40-13

Tables Available for Purging

Table 40-7 CRPT Domain - Tables Purged by Data Purger

Group Default Order Default Age Default Status

CRPT 0 365 NA

Table Name Key=1 Order=

crpt_daily_header2 0

crpt_daily_header_p crpt_daily_header. 10
child3

crpt_daily_detail crpt_daily_header. 10
child

crpt_daily_detail_p crpt_daily_header. 10
child

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. DELETE FROM crpt_daily_header WHERE organization_id = ? AND business_date < ?
3. DELETE {%ALIAS%} FROM {%TABLE%} c WHERE organization_id = ? AND NOT EXISTS
(Select p.* From crpt_daily_header p Where p.organization_id = c.organization_id And
p.rtl_loc_id = c.rtl_loc_id And p.wkstn_id = c.wkstn_id And p.business_date = c.business_date
And p.trans_seq = c.trans_seq)

The CRM purge group is assigned a higher order (10) so that a restriction may be
enforced ensuring that customer records are not purged if they correspond to customer
accounts which themselves are not eligible for purging. This requires the CAT group
purge to run first. When the “enabled” flag is set to FALSE, no customer records are
purged.

Table 40-8 CRM Domain - Tables Purged by Data Purger

Default Enabled
Group Default Order Value

CRM 10 FALSE

Table Name Key=1 Order=

crm_party2 0

crm_customer_affiliation crm_party.child3 10

crm_customer_notes crm_party.child 10

crm_party_cross_reference4 10

crm_party_id_xref crm_party.child 10

crm_party_locale_information crm_party.child 10

crm_party_p crm_party.child 10

crm_party_telephone crm_party.child 10

crm_party_email crm_party.child 10

40-14 Technical Guide

 Tables Available for Purging

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. WHERE void_flag = 1
AND
<no matching customer account exists>
i.e. there is no row match joining:
organization_id = cat_cust_acct.organization_id AND
party_id = cat_cust_acct.party_id
3. WHERE <no matching party exists>
i.e. there is no row match joining:
organization_id = crm_party.organization_id AND
party_id = crm_party.party_id
4. WHERE <no matching party exists for the parent record in the association>
i.e. there is no row match joining:
organization_id = crm_party.organization_id AND
parent_party_id = crm_party.party_id
OR
<no matching party exists for the parent record in the association>
i.e. there is no row match joining:
organization_id = crm_party.organization_id AND
child_party_id = crm_party.party_id

Table 40-9 CTL Domain - Tables Purged by Data Purger

Group Default Order Default Age Default Status

CTL 0 30 NA

Table Name Order=

ctl_device_registration1 0

ctl_event_log2 0

ctl_log_trickle3 0

1. WHERE business_date < ?

2. WHERE business_date < ?
3. WHERE business_date < ? AND posted_flag = 1

Table 40-10 DOC Domain - Tables Purged by Data Purger

Group Default Order Default Age Default Status

DOC 0 365 NA

Table Name Order=

doc_document1 0

doc_document_lineitm2 10

doc_document_p3 10

1. WHERE expiration_date < ?

Data Purger Overview 40-15

Tables Available for Purging

2. WHERE <no matching document exists>

i.e. there is no row match joining:
organization_id = doc_document.organization_id AND
document_type = doc_document.document_type AND
series_id = doc_document.series_id AND
document_id = doc_document.document_id
3. WHERE <no matching document exists>
i.e. there is no row match joining:
organization_id = doc_document.organization_id AND
document_id = doc_document.document_id

Note: When the “enabled” flag is set to FALSE, discount records are
not purged.

Table 40-11 DSC Domain - Tables Purged by Data Purger

Default Enabled
Group Default Order Default Age Value

DSC 0 365 FALSE

Table Name Key=1 Order=

dsc_discount2 0

dsc_discount_compatibility3 10

dsc_discount_group_mapping dsc_discount.child4 10

dsc_discount_item_exclusions dsc_discount.child 10

dsc_discount_item_inclusions dsc_discount.child 10

dsc_discount_type_eligibility dsc_discount.child 10

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. WHERE expr_datetime < ?
3. WHERE <no matching discount exists for the primary discount code>
i.e. there is no row match joining:
organization_id = dsc_discount.organization_id AND
primary_discount_code = dsc_discount.discount_code
OR
<no matching discount exists for the compatible discount code>
i.e. there is no row match joining:
organization_id = dsc_discount.organization_id AND
compatible_discount_code = dsc_discount.discount_code
4. WHERE <no matching discount exists>
i.e. there is no row match joining:
organization_id = dsc_discount.organization_id AND
discount_code = dsc_discount.discount_code

40-16 Technical Guide

 Tables Available for Purging

Note: When the “enabled” flag is set to FALSE, employee records are
not purged.

Table 40-12 HRS Domain - Tables Purged by Data Purger

Default Enabled
Group Default Order Default Age Value

HRS 0 365 FALSE

Table Name Key=1 Order=

hrs_employee2 0

hrs_employee_message3 0

hrs_employee_task4 0

hrs_employee_fingerprint hrs_employee.child5 10

hrs_employee_notes hrs_employee.child 10

hrs_employee_password hrs_employee.child 10

hrs_employee_store hrs_employee.child 10

hrs_employee_task_notes hrs_employee_task. 10
child6

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. WHERE terminated_date < ?
3. WHERE end_date < ?
4. WHERE due_date < ?
5. WHERE <no matching employee exists>
i.e. there is no row match joining:
organization_id = hrs_employee.organization_id AND
employee_id = hrs_employee.employee_id
6.DELETE {%ALIAS%} FROM {%TABLE%} c WHERE organization_id = ? AND NOT EXISTS
(Select p.* From hrs_employee_task p Where p.organization_id = c.organization_id And
p.rtl_loc_id = c.rtl_loc_id And p.task_id = c.task_id)

Data Purger Overview 40-17

Tables Available for Purging

Table 40-13 INV Domain - Tables Purged by Data Purger

Default
Group Default Order Default Age Status

INV 0 365 NA

Table Name Key=1 Order=

inv_invctl_document2 0

inv_count3 0

inv_carton inv_invctl_document.child4 10

inv_document_notes inv_invctl_document.child 10

inv_invctl_doc_lineserial inv_invctl_document.child 10

inv_invctl_document_lineitm inv_invctl_document.child 10

inv_invctl_document_p inv_invctl_document.child 10

inv_inventory_loc_mod inv_invctl_document.child2 10
5

inv_item_acct_mod inv_invctl_document.child 10

inv_shipment inv_invctl_document.child 10

inv_shipment_address inv_invctl_document.child 10

inv_shipment_lines inv_invctl_document.child 10

inv_invctl_trans inv_invctl_document.child 10

inv_invctl_trans_detail inv_invctl_document.child 10

inv_count_bucket inv_count.child 10

inv_count_sheet inv_count.child6 10

inv_count_sheet_lineitm inv_count.child 10

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. WHERE complete_date_timestamp < ?
3. WHERE end_date < ?
4. WHERE <no matching inventory document exists>
i.e. there is no row match joining:
organization_id = inv_invctl_document.organization_id AND
rtl_loc_id = inv_invctl_document.rtl_loc_id AND
document_typcode = inv_invctl_document.document_typcode AND
invctl_document_id = inv_invctl_document.invctl_document_id
5. WHERE <no matching inventory document exists>
i.e. there is no row match joining:
organization_id = inv_invctl_document.organization_id AND
rtl_loc_id = inv_invctl_document.rtl_loc_id AND
document_typcode = inv_invctl_document.document_typcode AND
document_id = inv_invctl_document.invctl_document_id

40-18 Technical Guide

 Tables Available for Purging

6. WHERE <no matching inventory count exists>

i.e. there is no row match joining:
organization_id = inv_count.organization_id AND
rtl_loc_id = inv_count.rtl_loc_id AND
inv_count_id = inv_count.inv_count_id

Note: When the “enabled” flag is set to FALSE, item records are not
purged.
Exception: itm_warranty_journal records are transactional and
will be purged if their parent trn_trans records are also purged.
(This table is referenced in both the “ITM” and “Transaction” groups).
Other than historical reporting—which should be impacted by
purges—the itm_warranty_journal is used for testing whether or
not a given transaction involving warranty activity may be post-
voided. Specifically, if the user attempts to post-void a transaction
involving warranty activity, it must be the most recent transaction
involving any activity for that warranty. Therefore, if a transaction
record is deemed “purgable”, its corresponding
itm_warranty_journal record is not needed.

Table 40-14 ITM Domain - Tables Purged by Data Purger

Default
Enabled
Group Default Order Default Age Default Status Value

ITM 0 365 NA FALSE

Table Name Key=1 Order= Status

itm_attached_items2 0

itm_item_msg3 0

itm_item_prices4 0

itm_item_deal_prop5 0

itm_item_restriction6 0

itm_item_restriction_calendar7 0

itm_refund_schedule8 0

itm_warranty9 0 CLOSED

itm_item_restrict_calendar itm_item_ 10
restriction.child10

itm_warranty_journal itm_warranty.child 10
11

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").

Data Purger Overview 40-19

Tables Available for Purging

2. WHERE end_datetime < ?

3. WHERE expr_datetime < ?
4. WHERE expiration_date < ?
5. DELETE FROM itm_item_deal_prop WHERE organization_id = ? AND expiration_date < ?
6. WHERE expiration_date < ?
7. WHERE expiration_date < ?
8. WHERE expiration_date < ?
9. WHERE warranty_expiration_date < ? OR status_code = ?
10. WHERE <no matching item restriction exists>
i.e. there is no row match joining:
organization_id = itm_item_restriction.organization_id AND
restriction_category = itm_item_restriction.restriction_category AND
restriction_code = itm_item_restriction.restriction_code
11. WHERE <no matching warranty exists>
i.e. there is no row match joining:
organization_id = itm_warranty.organization_id AND
warranty_typcode = itm_warranty.warranty_typcode AND
warranty_nbr = itm_warranty.warranty_nbr

Table 40-15 LOC Domain - Tables Purged by Data Purger

Default
Group Default Order Default Age Status

LOC 0 365 NA

Table Name Key=1 Order=

loc_cycle_question_answers2 0

loc_cycle_questions3 0

loc_state_journal4 0

loc_cycle_question_choices loc_cycle_questions.child5 10

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. WHERE answer_timestamp < ?
3. WHERE expiration_datetime < ?
4. WHERE time_stamp < ?
5. WHERE <no matching cycle question exists>
i.e. there is no row match joining:
organization_id = loc_cycle_questions.organization_id AND
question_id = loc_cycle_questions.question_id

40-20 Technical Guide

 Tables Available for Purging

Note: When the “enabled” flag is set to FALSE, deal records are not
purged.

Table 40-16 PRC Domain - Tables Purged by Data Purger

Default Enabled
Group Default Order Default Age Value

PRC 0 365 FALSE

Table Name Key=1 Order=

prc_deal2 0

prc_deal_cust_groups prc_deal.child3 10

prc_deal_document_xref prc_deal.child 10

prc_deal_field_test prc_deal.child 10

prc_deal_item prc_deal.child 10

prc_deal_trig prc_deal.child 10

prc_deal_week prc_deal.child 10

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. WHERE end_date < ?
3. WHERE <no matching deal exists>
i.e. there is no row match joining:
organization_id = prc_deal.organization_id AND
deal_id = prc_deal.deal_id

Table 40-17 RPT Domain - Tables Purged by Data Purger

Group Default Order Default Age Default Status

RPT 0 365 NA

Table Name Key=1 Order=

rpt_merchlvl1_sales rpt.general2 0

rpt_flash_sales rpt.general 0

rpt_flash_sales_goal rpt.general 0

rpt_sales_by_hour rpt.general 0

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. WHERE business_date < ?

Data Purger Overview 40-21

Tables Available for Purging

Table 40-18 SCH Domain - Tables Purged by Data Purger

Group Default Order Default Age Default Status

SCH 0 365 NA

Table Name Order=

sch_emp_time_off1 0

sch_schedule2 0

1. WHERE end_datetime < ?

2. WHERE business_date < ?

Table 40-19 TAX Domain - Tables Purged by Data Purger

Group Default Order Default Age Default Status

TAX 0 365 NA

Table Name Order=

tax_tax_exemption1 0

tax_tax_rate_rule2 0

tax_tax_rate_rule_override3 0

1. WHERE expiration_date < ?

2. WHERE expr_datetime < ?
3. WHERE expr_datetime < ?

Table 40-20 THR Domain - Tables Purged by Data Purger

Group Default Order Default Age Default Status

THR 0 365 NA

Table Name Order=

thr_payroll1 0

thr_payroll_header2 0

thr_payroll_notes3 0

thr_timecard_entry4 0

thr_timecard_entry_comment5 0

thr_timecard_journal6 0

1. WHERE business_date < ? AND posted_flag = 1

2. WHERE week_ending_date < ?
3. WHERE week_ending_date < ?
4. WHERE business_date < ? OR delete_flag = 1

40-22 Technical Guide

 Tables Available for Purging

5. WHERE week_ending_date < ?

6. WHERE business_date < ? OR delete_flag = 1

Note: When the “enabled” flag is set to FALSE, tender records are not
purged.

Table 40-21 TND Domain - Tables Purged by Data Purger

Default Enabled
Group Default Order Default Age Value

TND 0 365 FALSE

Table Name Key=1 Order=

tnd_tndr2 0

tnd_tndr_availability tnd_tndr.child3 10

tnd_tndr_denomination tnd_tndr.child 10

tnd_tndr_user_settings tnd_tndr.child 10

tnd_tndr_options tnd_tndr.child 10

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. WHERE expr_date < ?
3. WHERE <no matching tender exists>
i.e. there is no row match joining:
organization_id = tnd_tndr.organization_id AND
tndr_id = tnd_tndr.tndr_id

Data Purger Overview 40-23

Tables Available for Purging

Note: When the “enabled” flag is set to FALSE, session records are
not purged.
Exception: TSN tables that are transactionalized will be purged if their
parent trn_trans record is also purged. TSN tables representing
non-transactionalized session information (specifically:
tsn_session, tsn_session_tndr, and tsn_session_wkstn)
will not be purged by default.

Table 40-22 TSN Domain - Tables Purged by Data Purger

Default Enabled
Group Default Order Default Age Value

TSN 0 365 FALSE

Table Name Key=1 Order=

tsn_session2 0

tsn_session_tndr tsn_session.child3 10

tsn_session_wkstn tsn_session.child 10

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. WHERE end_datetime < ?
3. WHERE <no matching session exists>
i.e. there is no row match joining:
organization_id = tsn_session.organization_id AND
rtl_loc_id = tsn_session.rtl_loc_id AND
session_id = tsn_session.session_id

Table 40-23 TTR Domain - Tables Purged by Data Purger

Group Default Order Default Age Default Status

TTR 0 365 NA

Table Name Key=1 Order=

ttr_voucher2 0

ttr_voucher_history ttr_voucher.child3 10

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. WHERE expr_date < ?
3. WHERE <no matching voucher exists>
i.e. there is no row match joining:
organization_id = ttr_voucher.organization_id AND
voucher_typcode = ttr_voucher.voucher_typcode AND
serial_nbr = ttr_voucher.serial_nbr

40-24 Technical Guide

 Tables Available for Purging

Table 40-24 XOM Domain - Tables Purged by Data Purger

Group Default Order Default Age Default Status

XOM 0 365 status1="COMPLETE"

status2="CANCELLED

Table Name Key=1 Order=

xom_order2 0

xom_order_line xom_order.child3 10

xom_order_line_detail xom_order.child 10

xom_customer_mod xom_order.child 10

xom_address_mod xom_order.child 10

xom_fulfillment_mod xom_order.child 10

xom_source_mod xom_order.child 10

xom_item_mod xom_order.child 10

xom_order_payment xom_order.child 10

xom_order_fee xom_order.child 10

xom_balance_mod xom_order.child 10

xom_fee_mod xom_order.child 10

xom_order_mod xom_order.child 10

xom_customization_mod xom_order.child 10

1. Where a key is not explicitly specified it is the same as the query name (for example, the key
for the "trn_trans" query is "trn_trans").
2. WHERE order_date < ?
3. WHERE <no matching order exists>
i.e. there is no row match joining:
organization_id = xom_order.organization_id AND
order_id = xom_order.order_id

Data Purger Overview 40-25

Tables Available for Purging

Note: This email purge clears out the email addresses saved from the
Receipt/Transaction database without affecting the addresses stored in
customer profiles.

Table 40-25 Tables Purged by Data Purger

Default
Group Default Order Default Age Status

Email 0 30 NA

Table Name Key Order=

trn_trans_properties_email trn_trans_properties_email1 0

1. WHERE business_date < ? AND

property_code IN
('RECEIPT_DELIVERY_METHOD',
'RECEIPT_EMAIL_ADDRESS',
'CUSTOMER_EMAIL_UPDATED')

Table 40-26 Tables Purged by Data Purger

Default
Group Default Order Default Age Status

Air 0 30 NA

Table Name Key Order=

com_flight_info 0

DELETE {%ALIAS%} FROM com_flight_info c WHERE organization_id = ? AND scheduled_-date_time < ?

AND NOT EXISTS (SELECT p.* FROM trl_rtrans_flight_info p WHERE p.organi-zation_id = c.organization_id
AND /*UPPER*/ p.flight_number = c.flight_number)

Table 40-27 Tables Purged by Data Purger

Default
Group Default Order Default Age Status

TEMP_STORE 0 365 NA
_REQUEST

Table Name Key Order=

loc_temp_store_ 0
request 1)

1) DELETE FROM loc_temp_store_request WHERE organization_id = ? AND ((/*UPPER*/ end_date_str < ?

AND /*UPPER*/ status = 'APPROVED') OR (update_date < ? AND /*UPPER*/ status IN ('CANCELLED',
'REJECTED')))

40-26 Technical Guide

 41
Xstore Point of Service Management
Console

Overview
This Java Management Extensions (JMX) application runs in the background when
Xstore Point of Service is running and allows users with the appropriate security level to
view system information about the application. JMX allows developers to use
management beans to simplify management of processes and data. Xstore Point of
Service uses JMX to pull reports from the database as well as other back-office tasks.
When Xstore Point of Service is running, you can use the Xstore Point of Service
Management Console connect manage JMX configurations. Connect to port 2020 using
https and a web browser to access various management features.If you are connecting
from the same machine, the URL would be https://localhost:2020.

Note: This web interface is secured using the same logins that can be
used to log in to Xstore Point of Service. A security privilege is
required to access this console. Not all employee logins may have
access.

Once authorized, you will see the Xstore Point of Service Management Console.

Figure 41-1: Xstore Point of Service Management Console

Xstore Point of Service Management Console 41-1

Debug Domains

Debug Domains
Cache Status
Use this MBean to view information about JCS caches.

• To view cache status, click the getCacheStatus button to see the Cache Id, Status,
and where the cache is configured.

• To clear all caches, click the clearCaches button to send a clear request to the
CacheManager to clear all caches.

41-2 Technical Guide

 Debug Domains

Data Source Status

Use this MBean to view the status of all datasources referenced by
PersistenceManagerConfig.xml. This Xstore Point of Service Management
Console page is responsible for supplying the current status of the PM Types and
Datasources.

• To view datasource status click the getDataSourceStatus button.

The following information is returned:
- Datasources: Datasource Name and Source

- Connection Pool Status

- Replication Status

- PM Statuses: PM Type and Datasources

Xstore Point of Service Management Console 41-3

Debug Domains

LogLevelConfig
Use this MBean to configure runtime log levels.

• To configure runtime log levels:

a. Enter the target log category.
b. Enter the log level to set on the category. (Debug is the default).
c. Click the changelogLevel button to change the log level for log4j2 category.

41-4 Technical Guide

 Debug Domains

PosDebugger
Use this MBean to view information about the current system state.

• Click the debugMenu button to view information about the currently loaded menu.
(menu model, prompt action model, app change actions, and current form)
• Click the debugTransaction button to view information about the current
transaction.
• Click the debugAccountManager button to view information about current
customer accounts.
• Click the debugModel button to view information about the current model.
• Click the debugCurrentMemory button to view information about the current
memory usage. (total memory and free memory)
• Click the debugFocus button to view information about the current focus.
(focusedWindow, focusOwner, and permanentFocusOwner)
• Click the forceGarbageCollection button to force garbage collection. (The total
memory, the free memory, and the free memory after garbage collection).
• Click the debugOpChainProcessor button to view current state of op chain
processors. (USER OPCHAIN PROCESSOR and SYSTEM OPCHAIN PROCESSOR)

Xstore Point of Service Management Console 41-5

Debug Domains

ReceiptDebugger
Use this MBean to trace receipt configuration during a transaction.

• To generate the receipts for the current transaction, set up the following:
a. If Original is set to true, reprint text is not included.
b. If Suppress Tracing is set to true, tracing information is not included.
c. [OPTIONAL] Enter the line width in characters for the generated receipts.
(Defaults to 44 if left blank).
d. Click the viewReceipt button.
• To generate files that graphviz can turn into SVG files, set up the following:
a. [OPTIONAL] Specify the directory in which to save generated files.
b. [OPTIONAL] Specify the receipt type to generate. (Defaults to “all” if left blank).
c. Click the traceRcpt button.

41-6 Technical Guide

 General Domain

General Domain
Tlog Generation
Use this MBean to generate Tlogs. The Tlog Generator (dtv.pos.tools.TlogGenerator
class) was created to enable recreation of Tlog records for transactions. The Tlog
Generator supports an array of parameters for controlling which transactions will have
logs regenerated. All parameters are optional, but care should be taken in executing the
generator for a large set of transactions.

• To use the TLog generator:

a. Search for a specific value. Enter either a start or end value and leave the other
one blank. To use the default log file, leave the log filename blank.
* The business date or a date range
* The store number or a store number range
* The register number or a register number range
* The transaction sequence number or a transaction sequence number range
* The file to save the generated logs to
b. Click the generateTlog button.
The logs will be created based on the customer’s configuration in the files.xml,
either a single Tlog file containing all transactions, or one log per transaction.

Xstore Point of Service Management Console 41-7

Information Domain

Information Domain
AuthManager
Use this MBean to view and manage the status of authorization processors.
• View the AuthConfig.xml settings - You can modify the online/offline status of
each authorization type. For example, you can force gift card authorizations to be
processed offline just like you had started up with the setting
communicationEnabled=false in AuthConfig.xml. The change resets when
Xstore Point of Service is restarted.
• View the recent communications between Xstore Point of Service and the
authorization engine - For example, you can view credit card authorizations.
Sensitive information, such as the card number and track data, is masked in this
view.

The list of AuthManager attributes shows the name, description, and status value for
each authorization processor.

41-8 Technical Guide

 Information Domain

To view recent communications with the server,

click the viewRecentCommunications button.

ClassPathInformation
Use this MBean to explore the classpath. This is useful for determining conflicts between
jar files. You can view where a given file is found and view all locations of a given
package.

• To explore the classpath:

a. Type the package, then click the listPackageLocations button to list all locations
of the specified package.
b. Type the package, then click listPackageContents button to list all the contents
of the specified package.
c. Type the file name, then click the listConfigLocations button to list the locations
of the specified configuration file, taking dtv.config.path into account.

Xstore Point of Service Management Console 41-9

Information Domain

ConfigurationInformation
Use this MBean to view information about POS configuration. You can view each setting
in the SysConfig.xml file and which file specified the value.

• To view information about POS configuration:

a. Click the Version button to view version information and system properties.

41-10 Technical Guide

 Information Domain

b. Click the SystemConfig button to view configuration setting, value, and source
from SysConfig.xml.

c. Click the OpChainConfig button to view chain and source configuration

settings from OpChainConfig.xml.

d. Click the HardwareConfig button to view Configured Hardware information

including use, device, settings, and source and Port Information including type,
name, and owner configuration settings from HardwareConfig.xml.

Xstore Point of Service Management Console 41-11

Information Domain

e. Click the AuthConfig button to view auth_mthd_code, parameter name,

parameter value, configured on..., and configuration source configuration
settings from AuthConfig.xml.

f. Click the PreFlightChecks button to run the pre-flight checks and view each
result. Preflight checks are a way in Xstore Point of Service to check for common
problems at startup. If any of the problems are found, a warning dialog is
displayed.

41-12 Technical Guide

 Information Domain

HardwareDeviceManager
HardwareDeviceManager calls the same functionality as the Xstore Point of Service
Enable/Disable Hardware back office function. Refer to the Xstore Point of Service
Manager’s Guide for more information.
Use this MBean to view and manage the status of hardware devices. This option
provides a way to temporarily disable and then enable hardware devices. This process
writes out a hardwareconfig.xml file to a patch directory for the devices that have
been disabled, reloads the hardware configurations, and then re-initializes the hardware.
The configured hardware and COM ports visible by the JVM are listed.

The list of HardwareDeviceManager attributes shows the name, description, and status
value for each hardware device. If needed, change a hardware value, then click the
Apply button to enable/disable only the selected device(s), without removing any
configuration overrides (patch file entries) that may exist for other devices. For example,
this option can be used when you have disabled several devices and only want to enable
one device, not all of the disabled devices.
To clear recent hardware configurations, click the clearHardwareConfigs button to
remove all overrides to the device configuration file which enables all disabled devices.
For example, this option can be used when you want to enable all disabled devices at
once. The system removes the hardware configuration overrides (patch file entries) that
were created when the devices were disabled.

Xstore Point of Service Management Console 41-13

Information Domain

PrintQueueMgr
Use this MBean to manage the receipt print queue. A receipt printer under the control of
Xstore Point of Service becomes a shared device. A nearby register can be configured to
use another register's receipt printer as a backup. The Receipt Printer Manager allows
you administer the print queue used for this function.
You can also manually add jobs to the print queue from the web interface. This could be
used to print a barcode for use in a lab, or to allow a help desk to remotely print a
message that will be visible on the receipt printer.

The list of PrintQueueMgr attributes shows the port, whether remote queueing is
enabled, the pending count, and status of the print queue.
• To view print jobs that are in the queue, click the listJobs button.

• To create a print job, set up the following:

a. Enter the source of the print job.
b. Enter the data to print.

41-14 Technical Guide

 Information Domain

c. Click the print button.

• To use the barcode maker:
a. Scroll down to the printBarcode method.
b. Set up the parameters:
* The first parameter is the source. The source can be anything. (It will appear
as the source in the print queue).
* The second parameter is the encoding. Encoding is the symbology to use. (If
you don't specify a value, it uses Code 93 by default).
* The third parameter is the data that you want to encode.
c. After filling in the fields, click the printBarcode button
and the barcode will be printed on your receipt printer.

• To cancel a print job, enter the ID of the job to cancel, then click the cancelPrintJob
button.
• To start the queue, click the start button.
• To stop the queue, click the stop button.
• To pause the queue, click the pause button.
• To resume the queue, click the resume button.
• To flush the queue, click the flush button.

Xstore Point of Service Management Console 41-15

Information Domain

41-16 Technical Guide

 42
Transaction Replicator

Overview
The purpose of the Transaction Replicator utility is to fill in transactional gaps for sales
audit purposes.
The Transaction Replicator utility retrieves transactions from the default lookup location
for this type of data and adds them to the replication queue on the system where the
utility is run. The utility will run for the organization ID that is set in
system.properties.
The utility is found in C:\xstoredata on an installed system. Xstore Point of Service
must be running for the data to be replicated.
The Transaction Replicator only targets the mainline transaction graph (sale lines,
tenders, etc.) and not any ancillary data. This utility is not intended to fully recover any
and all data that may normally be replicated from the register. The following list shows
transactional data that will not be replicated using this tool.
- sec_activity_log data
- ttr_tndr_auth_log data
- trn_trans_version data
- Timecard-related data
- Receipt data
- Session Control transaction details

Transaction Replicator 42-1

Run the Transaction Replicator Utility

Run the Transaction Replicator Utility

Important: Transaction Replicator must be run on a system that has
Xstore Point of Service installed since it utilizes some of the Xstore
Point of Service code base.

1. Double-click the batch file named transreplicate.bat located in C:\xstoredata.

Note: On the Linux platform, this batch file is named

transreplicate.sh.

2. Enter criteria to determine a group of transactions that should be added to the

replication queue:

Figure 42-1: Transaction Replicator Criteria Window

- Start Date [REQUIRED] - The starting business date of the transactions to add.
- End Date - The ending business date of the transactions to add.
* Defaults to the current system date and must be greater than the start date.
* If not populated, assumes current date as end date.
- Store # - The retail location ID of transactions to add.
- Register # - The workstation ID of transactions to add.
- Transaction Id Start - The ID of the first transaction that should be added.
- Transaction Id End - The ID of the last transaction that should be added. This
must be higher than the starting transaction ID.
3. Click Process.

42-2 Technical Guide

 Run the Transaction Replicator Utility

Any transactions inclusively between the Start Date and the End Date, and
inclusively between the Transaction Id Start and the Transaction Id End (when
provided), will be included.

Figure 42-2: Transaction Replicator Criteria Window - Processing Complete

Transaction Replicator 42-3

Run the Transaction Replicator Utility

42-4 Technical Guide

 43
Internationalization

Overview
This chapter provides a general overview of internationalization, localization, and
multilingualization, and describes how these concepts are implemented and configured
in Xstore Point of Service.
Internationalization is a general term used to describe the ability of a software
application to be customized for use in different locations by people from different
cultures who speak different languages. The implementation of internationalization in
Xstore Point of Service allows it to be quickly customized to almost any language, even
though the developers may not know any language other than their own native
language.

Note: The Arial MS Unicode font is packaged and deployed with

Xstore Point of Service to ensure that register systems render all
languages correctly.

About this Chapter

This chapter contains the following information:
• “Internationalization (i18n)” provides a general overview of internationalization,
multilingualization, and localization. This sections also provides a general
description of the implementation of these concepts in Xstore Point of Service.
• “Xstore Point of Service i18n Implementation” provides a more extensive
description of the technologies and methods used to implement internationalization
in Xstore Point of Service.
• “Translation Resource Bundles” describes the files that contain the text translations
used in Xstore Point of Service, how they are located by the software, and how
Xstore Point of Service determines file priority.

Internationalization 43-1
Internationalization (i18n)

Internationalization (i18n)
Internationalization refers to the process and methods that enable an application to be
used in a variety of geographic locations that have different languages and cultural
requirements. Although the source code is developed in one language, such as English,
the user interface is presented in the local language with sensitivity to cultural
requirements.
The abbreviation “i18n” is frequently used to signify internationalization, with the “18”
in the middle of “i18n” signifying the number of letters that were removed.1

Implementing i18n
Xstore Point of Service delivers the benefits of internationalization without requiring
changes to the source code. Through various files that contain “key/translation” pairs,
language-specific translations can be implemented in software created by a developer
who is not multilingual.
Each pair consists of a text key in the developer’s language followed by the translated
word or phrase in a different language. The key is a unique identifier used by Xstore
Point of Service to access the corresponding translation. Xstore Point of Service accesses
the correct translation at runtime.

Note: In Xstore Point of Service, all translation keys must begin with
the underscore (_) character.

The translation key is identical in all of the language-specific translation properties files,
but its corresponding translation varies by language. Each language has its own file with
all of the required key/translation pairs.

Applications of Internationalization in Xstore Point of Service

i18n is widely used in Xstore Point of Service. It has applications across many functional
areas and is used in many ways that enhance the application’s ability to be used
throughout the world. The following list identifies some areas where i18n is used in
Xstore Point of Service:
• Keystroke mapping
• Screen prompts and system messages
• Menu texts
• Reports titles, headers, and parameters
• Franking messages
• IPC Messages from Xenvironment
• Device names
• Function-oriented terms

1. From the I18nGuy™ Web Site

43-2 Technical Guide

 Xstore Point of Service i18n Implementation

Internationalization (i18n) and Localization (L10n)

Localization, or “L10n”, is the process by which internationalized software is customized
to match the locale where the software will be used. While i18n provides software with
the ability to be useful in any locale, L10n is the method by which the software is readied
for use in a specific locale.

Multilingualization (m17n)
In cases where several languages and character sets are required, multilingualization, or
“m17n”, is required. This methodology makes several different character sets from
several different languages available to users. Implementing m17n typically requires the
software to use Unicode or UTF-8 character sets.

Xstore Point of Service i18n Implementation

This section describes the implementation of i18n in Xstore Point of Service, including
language options and character encoding.

Java Standards
Xstore Point of Service uses several Java standards in its implementation of i18n. Locales
are used to designate the language and country in which the application is to be used,
and Xstore Point of Service uses the language and country code standards defined by
Java. Xstore Point of Service also uses standard Java i18n methods and libraries.

Language Codes
Xstore Point of Service language codes combine an ISO-639-1 language code and an ISO-
3661-1 country code to identify the specific language files for the user interface. Samples
of some of the codes are specified in the table below:
Table 43-1 Sample Language CodesInternationalization.fm

Language and Country Language Code

English (US) en_US

French (France) fr_FR

Japanese ja_JP

Chinese zh_CN

Internationalization 43-3
Xstore Point of Service i18n Implementation

Configure Languages in Xstore Point of Service

Different areas of Xstore Point of Service may have their own language configurations,
which are designated in the file LocaleMap.xml. In this configuration file, each
MapEntry element has a key attribute that specifies an area of Xstore Point of Service,
and a corresponding value attribute that specifies the default language that it uses.

Sample Entries in LocaleMap.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Root dtype="Map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" xsi:noNamespaceSchemaLocation="LocaleMap.xsd">
<MapEntry key="Default" value="en_US"/>
<MapEntry key="Document" value="en_US"/>
<MapEntry key="PoleDisplay" value="en_US"/>
<MapEntry key="Receipt" value="en_US"/>
<MapEntry key="View" value="en_US"/>
<MapEntry key="Error" value="en_US"/>
<MapEntry key="Log" value="en_US"/>
<MapEntry key="FiscalExport" value="en_US"/>
<MapEntry key="FiscalDocument" value="en_US"/>
</Root>
The key attribute settings for each <MapEntry> element in the file LocaleMap.xml are
explained in the following table:
Table 43-2 MapEntry Keys for Areas of Xstore Point of Service Internationalization.fm

Key Xstore Point of Service Area

Default Used when specific key is not specified

Document Hard copy documents

PoleDisplay Customer display device

Receipt Printed receipts

View Xstore Point of Service on-screen user interface

Error Error messages

Log Log files

FiscalExport Used for the translation on the fiscal exports

FiscalDocument Used for the fiscal documents such as invoices

Language Files
For each language available in Xstore Point of Service, there is one corresponding file
that contains all the text items that a user will see. This includes all messages and

43-4 Technical Guide

 Xstore Point of Service i18n Implementation

prompts in the system. Each text item in the file is indexed so that different translations
of the same message are found in a consistent manner.
Each language translation file is named using the format shown below. The file extension
indicates that the file is a “properties” file.
translations_[language code].properties
The designation of [language code] is replaced by the proper language code as
shown in the table below. Samples of translations that use the same character data are
also shown. Xstore Point of Service uses the UTF-8 standard to encode character data.
Table 43-3 Sample TranslationsInternationalization.fm

File Sample Entry

translations_en.properties _pleaseWait=Please Wait

translations_fr.properties _pleaseWait=Attendre svp

translations_ja.properties _pleaseWait= \u304a\u5f85\u3061

\u304f\u3060\u3055\u3044

Note: The key (_pleaseWait) associated with each section of text

does not change. The Japanese translation file does not show actual
characters themselves, but lists the UTF-8 codes that correspond to the
Japanese characters.

Individual Customization
In addition to setting a default language for the Xstore Point of Service system, the
language can also be configured for each individual user. When a user logs in, the
interface’s language can be adjusted to match the needs or desires of that user. For
example, if a French-speaking Canadian were working in the United States, the system
could display prompts in French instead of the system’s default English language.

Note: To configure the language for a user, set the preferred locale for
an employee in the preferred_locale column in the crm_party
table. Also, verify the locale is listed in the AvailableLocales.xml
file.

In Xstore Point of Service, you can set up an employee’s preferred

locale in the Employee Maintenance General tab, Language field.

Internationalization 43-5
Xstore Point of Service i18n Implementation

Translation Resource Bundles

Resource bundles are properties files grouped together by a common base name, but
with a different locale suffix. This enables different properties to be used by Xstore Point
of Service dependent on the user's locale settings. Resource bundles are managed by the
config path.

Note: Resource-bundle-specific system.properties paths have been

eliminated. All bundles are now managed via the existing
dtv.config.path properties (whether obtained from Xadmin or
otherwise) so that profile groups/elements can be leveraged.

The following resource-bundle-specific system.properties paths found

in earlier Xstore Point of Service versions were eliminated:
dtv.pos.i18n.translation= dtv/i18n/
translations;cust/translations;cust/loyalty/
translations;cust/loyalty/award/translations;order/
translations
dtv.pos.i18n.hardware= dtv/i18n/hardware
dtv.pos.i18n.keyboard= dtv/i18n/keyboard
dtv.pos.i18n.phone= dtv/i18n/PhoneNumbers
dtv.pos.i18n.help= dtv/i18n/help
dtv.pos.i18n.emailTemplate= dtv/i18n/emailTemplate

Language and Country

The file translations_[locale].properties is an example of a resource bundle.
In the file name, “[locale]” represents a 2-letter code for the language used in a
geographic location/locale—”en” for English, “fr” for French, “zh” for Chinese, etc. A
capitalized 2-letter code indicates a country—CA for Canada, JA for Japan, etc.—in
which there may be variations of a specified language. The file name may include both a
locale and a country designation. The file contains the actual text strings that will be
substituted for a corresponding translation key whenever the application encounters
that key.

Translation Key Examples

_return=Return (from translations_en.properties for English)
_return=Retour (from translations_fr_CA.properties for French-
Canadian)
_return=\u8fd4\u5374 (Unicode, from translations_ja.properties
for Japanese)
Translations for English are in the file translations_en.properties, and
translations for French (as spoken in France) are in translations_fr.properties.
If the language has variations, depending on the country in which it is spoken, that may
be expressed in the file name. For example, translations_fr_CA.properties
would contain the translation for French as it is spoken in Canada.

Multi-Path Search Order for Translating a Key Into French-Canadian

This example uses the two search paths for translations defined in the preceding sample
directory path. The following table indicates the order in which the paths and the
translation files in those paths will be searched.

43-6 Technical Guide

 Xstore Point of Service i18n Implementation

Table 43-4 Search Order for a Multi-Path TranslationInternationalization.fm

Search Path (in Order) Comment

...version1/ the most specific locale; highest-

translations_fr_CA.properties priority search path.

...version1/ a less-specific locale; highest-priority

translations_fr.properties search path.

...version1/translations_[default the default locale; highest-priority

locale].properties search path.

...\dtv\res\config\translations_fr_ the most-specific locale; lower-

CA.properties priority search path.

...\dtv\res\config\translations_fr. a less-specific locale; lower-priority

properties search path.

...\dtv\res\config\translations_ the default locale; lower-priority

[default locale].properties search path.

The first translations file that contains the requested key also contains the corresponding
translation string that will be used as the resulting output in the application. If there is
no corresponding key mapping in any of the translation files that is searched, a string in
the form “mr@[invalid translation key]” is used as the output.

Note: “mr” is an abbreviation for “missing resource”.

Define Common Mappings for Different Keys

Each localized element in Xstore Point of Service should be assigned a unique key. Even
if the label “name” on a customer search form and the same label “name” on an
employee search form are intended to display the same text (e.g. “Name”), each of them
should be assigned a unique key (e.g. _customerSearchName and
_employeeSearchName). This policy enables similar translations to be differentiated
in the future (e.g. changing the “name” label on the employee search form to “Employee
Name”) without having to change the code or configuration sources from which the
keys are derived.
However, this policy would require a good deal of duplication in each translation file. In
the previous example, each locale-specific file would require a mapping for both
_customerSearchName and _employeeSearchName, even though both might
resolve to the identical localized value. When language translation providers charge per
word, the monetary cost of that duplication can be significant.
To ease the difficulty of managing a large number of keys with translated values that are
common across the application (name, city, state, country, etc.), the file
translations.map.properties is helpful to the application developer. Instead of
specifying key-to-translated value associations, the file
translations.map.properties enumerates a set of key-to-key pairings.
When the application tries to convert a translation key into a locale-specific literal string,
it first consults translations.map.properties to determine the correct key to use.
If such an entry exists, the searched-for key in the locale-specific translations files will be
used as the mapped key rather than the one identified by the application. If no such

Internationalization 43-7
Xstore Office and SystemConfigMetadata.properties

entry exists, then the application-specified key will serve as the effective key for
translation lookup purposes.

Example in translations.map.properties
_customerSearchName=_commonName
_employeeSearchName=_commonName

Example in translations_en.properties
_commonName=Name

Example in translations_es_MX.properties
_commonName=Nombre
In the preceding example, the principle of unique keys is preserved, but only a single
translation must be performed for each supported locale. Any number of labels, such as
“Name”, can similarly be accommodated by mapping their unique keys to the
_commonName effective key without requiring any additional translation work in any
language.
Whenever a divergent translation is needed for any of the commonly mapped keys,
those keys can be remapped in, or removed from, the
translations.map.properties file. If necessary, a new entry might also need to be
added to each locale-specific translation file.

Xstore Office and SystemConfigMetadata.properties

Note: For developer-level technical details, see the "base" copy of

dtv/res/config/SystemConfigMetadata.properties, which
contains extensive documentation in comments at the top of the file.

The SystemConfigMetadata.properties file contains critical information needed

by the Xstore Office System Config GUI. It is a counterpart to Xstore Point of Service
SysConfig.xml file, which is the main file for storing system configuration settings.
As there are multiple copies of SysConfig.xml in Xstore Point of Service which support
base configurations and customer overrides (via the Xstore Point of Service "config path"
system), there are also multiple SystemConfigMetadata.properties files.
However, unlike SysConfig.xml, these metadata files are not governed/configurable by
config path. In fact, there will only ever be exactly two copies of
SystemConfigMetadata.properties:
• dtv/res/config/SystemConfigMetadata.properties - the base definition
found in config.jar, and companion to SysConfig.xml in the same location
• version1/SystemConfigMetadata.properties - the Operations team's
"overrides", typically found in the customer jar. All customer-specific overrides for
metadata must be put into this file.

i18n and the SystemConfigMetadata.properties File

The SystemConfigMetadata.properties file is used in two different ways by
Xstore Office. First, it is used by custom code which parses all of the properties and
dynamically constructs the System Config GUI using its information in combination

43-8 Technical Guide

 Xstore Office and SystemConfigMetadata.properties

with the contents of SysConfig.xml. Also, it is separately loaded using the

DtvResourceBundle library, and its contents are treated as i18n translations.
If you look at a SystemConfigMetadata.properties file, you will notice that some
of the properties keys are prefixed with an underscore ("_"); any such property can and
will be treated as a translatable i18n resource. This allows an exhaustive amount of
System Configuration information to be fully internationalized.

SystemConfigMetadata.properties File Example

_Store---SystemConfig---EmployeeSale---AllowSelfSale.label=Allow User To Ring

His/Her Own Sale?
_Store---SystemConfig---EmployeeSale---AllowSelfSale.description=Determines
whether or not the system allows employees to ring retail transactions for
themselves.
Store---SystemConfig---EmployeeSale---AllowSelfSale.datatype=Bool
Store---SystemConfig---EmployeeSale---AllowSelfSale.category=_sales
Store---SystemConfig---EmployeeSale---AllowSelfSale.order=0
Store---SystemConfig---EmployeeSale---AllowSelfSale.tag.1=_register
Store---SystemConfig---EmployeeSale---AllowSelfSale.tag.2=_security
Store---SystemConfig---EmployeeSale---AllowSelfSale.tag.3=_sale

Creating a "Stub" Metadata File for Other Languages

Since a SystemConfigMetadata.properties file doubles as an i18n resource
bundle file, the easiest way to create a "stub" for a language translation is to "grep" the
base file for all lines which start with an underscore. Here's an example of a Unix
command which will filter out all of the i18n keys, and strip out certain items (the "do
not translate" ones), and create a stub for the French language:
grep ^_ SystemConfigMetadata.properties | grep -v "**DO NOT
TRANSLATE**" > SystemConfigMetadata.properties_fr_FR

Internationalization 43-9
Xstore Office and SystemConfigMetadata.properties

43-10 Technical Guide

 44
Xstore Mobile Configuration

Overview
This chapter provides information about the Xstore Mobile configurations.

system.properties
The following configuration is found in the system.properties file.
Table 44-1 system.properties

Setting Data Type Description

mobile.server.dis String This property is used to set an alias value

play.name for the Xstore mobile server. It is read by
the self reporting feature at the server
startup when it populates the DB with its
host name, port and alias information.
This value can be set via the installer
during the Xstore mobile server
installation. For more information about
installing Xstore Point of Service Mobile,
see the Oracle Retail Xstore Suite
Implementation and Security Guide.

ctl_mobile_server Table
The connection details of the available Xstore Point of Service Mobile servers are stored
in the ctl_mobile_server table.

Note: For more information on the ctl_mobile_server table, see the

Oracle Retail Xstore Point of Service Database Dictionary.

There are two different ways to populate the ctl_mobile_server table.

Note: The system should be configured to use only one of these

methods.

• During the Xstore Point of Service Mobile server startup, the server can register itself
by inserting a record to the database using its host name, port and alias. This is
configured in the mobile.server.display.name system property.
This feature can be disabled by overriding the
populateDBWithMobileServerConnectionInfo worker bean and setting the
enableSelfReporting property to false.

Xstore Mobile Configuration 44-1

Overview

Example:
<bean id="populateDBWithMobileServerConnectionInfo"
class="dtv.pos.common.PopulateDBWithMobileServerConnectInfoWor
ker" scope="prototype">
<property name="enableSelfReporting" value="false" />
</bean>
• When the system is configured to not to use the self reporting feature, users can
download data to the ctl_mobile_server table via dataloader.

Note: For more information about the Mobile Server Record, see the
Oracle Retail Xstore Point of Service Host Interface Guide.

SysConfig.xml Settings
This section describes Xstore Point of Service Mobile SysConfig settings.
Table 44-2 SysConfig.xml

Default
Setting Value Valid Values Description

Mobile--- 5 String The Mobile Device Quick Config

QuickConfig--- feature allows users with sufficient
ConfigCodeExpira security privileges to generate a QR
tionMinutes code for an Xstore Mobile device to
connect to the Xstore Mobile server.
Note: For more information about the
Mobile Device Quick Config feature, see
the Oracle Retail Xstore Point‐of‐Service
Mobile User Guide.
Upon creating a mobile quick config QR
code, this setting limits the number of
minutes the code can be used to quickly
configure a device using Xstore Mobile's
Quick Config feature. When scanning an
expired QR code, the configuration
information may still be applied to the
mobile device, however the server will
put the device into a pending status that
requires explicit approval from an
administrator.

UserInterface--- MINIM String See the“Hardware/UI Configuration”

ColorTheme AL chapter, section Color Theme.

OpenClose--- NA Boolean SysConfig.xml Setting for Mobile Only

RtlLocCycleFromPri Store:
maryWSOnly
The SysConfig.xml setting OpenClose--
-RtlLocCycleFromPrimaryWSOnly
must be set to false to allow Store Open
on devices.

44-2 Technical Guide

 Overview

Table 44-2 SysConfig.xml (continued)

Default
Setting Value Valid Values Description

Mobile--- Boolean This configuration controls the

EnableOfflineMod availability of the Offline POS mode.
e When the value is set to false, the
Offline POS mode will not be available in
the mobile client. The default value is set
to false.

Sequences
Xstore Mobile Point of Service now uses database sequences by default instead of file-
based sequences. To continue to use file-based sequences in a single mobile server
environment, set the following in the system.properties file:
dtv.util.sequence.useDbBasedSequenceStrategy=false

Note: If you use multiple servers in your store, it is recommended to

use the database sequences.

Xstore Mobile Configuration 44-3

Overview

44-4 Technical Guide

 45
Temporary Store Configuration

Overview
This chapter provides information about the temporary store configurations.
There are two types of temporary stores:
• The Event store has a separate store number from all brick-and-mortar locations.
• The Extension store shares a store number with a specific brick-and-mortar location.

Note: Only Xstore Mobile devices can be used in temporary stores.

Desktop registers are not supported, and can only be used in
traditional stores.

Note: For more information about how to request a mobile server for
an extension store, see the Xstore Point of Service Mobile User Guide. For
more information about how to manage mobile server requests for
event and extension stores, see the Xstore Office User Guide.

Temporary Store Topology

• There is one dedicated temporary store server (Xstore Mobile server instance) and
local temporary store database per store number.
• Each temporary store server downloads and data-loads its own deployments.
• All temporary store servers replicate to Xcenter while extension store servers also
replicate transactions to the home store.

Data Seeding
Retailers should send a full primary data refresh (that is, MNT files from systems of
record, not Xadmin Data Publisher) to a store in order to get store data loaded into the
temporary store database. This is valid for event stores as well as extension stores. For an
extension store, this means that the rest of the physical store registers also receive the
data refresh.

Deployments and Foundation Data

Every temporary store mobile server represents a single store number and downloads
deployments for that store.

Temporary Store Configuration 45-1

Extension Store Configurations

For extension stores, both the in-store lead register and the temporary store mobile
server will download deployments.
Each temporary store server has a dedicated local database.

Extension Store Configurations

This section describes the extension store configurations.

Temporary Store Mobile Server

When used as an extension store, the Temporary Store Mobile Server acts as a non-lead
register, but it does not point to the home store’s StorePrimary DB.

Xenvironment
During installation, the following configurations should be selected:
• Non-lead Workstation
• Xstore Present? - Unchecked
• Mobile Server Present – Checked
• Is Extension Store? - Checked
• All DB configurations should use localhost.
For more information, see the Oracle Retail Xstore Suite Implementation and Security Guide.
Once installation is complete, the following critical DB settings will be applied in
\environment\cust_config\version1\actions.properties:
• atom.get-remote-sql-server-backup.disabled = true
• chain.DATABASE_BACKUP_DOWNLOAD_AND_RESTORE.disabled = true

Xstore Mobile Server

During installation, the following settings should be used:
• Store # - Should match home store
• Xstore Configuration Path – Include “:extensionstore”

Note: Xstore Mobile servers running in an actual store location must

not add this to their config path.

• Mobile Server Register # - Must be unique from home store Mobile Server.
• Mobile Register Range Start/End – Must be unique from home store Mobile Server
range.
• All DB configurations should use localhost.
For more information, see the Oracle Retail Xstore Suite Implementation and Security Guide.

Temporary Store Event Polling Interval

All Xstore desktops/servers check once per hour to see if there is a temporary store event
currently in effect. If so, they establish connectivity to that store using information from
the temporary store request record.

45-2 Technical Guide

 Extension Store Configurations

This polling interval is defined as a Spring scheduled task, and can be found in the
spring.xml file, added to the springTaskScheduler bean:
<task:scheduled-tasks scheduler="springTaskScheduler">
[...]
<task:scheduled ref="extensionStoreConnectivityCheck"
method="check" fixed-delay="3600000" initial-delay="10000" />
</task:scheduled-tasks>

Websocket Heartbeat Interval

When the websocket connectivity is established to the extension store server, the client
side (home store) periodically sends a small heartbeat message.
By default, the heartbeat interval is 30 seconds.
This interval can be explicitly configured as a JVM system property on any home store
system.
xstore.dtxws.heartbeat.interval.seconds=120
For example, the above system property sets the interval to two minutes.

Persistent Timeout
The persistence strategy supports DTX replication in both directions (home store to
extension store and extension store to home store). Regardless of the direction, the
fundamental operation is the same: one end is sending a DTX object to the other end, so
that it will persist that DTX object on its behalf.
One end is waiting for the other end to perform the persistence. If no response is
received (either a successful response, or an error response), the request will timeout and
assume that the other end failed to perform the requested persistence.
By default, this timeout is 30 seconds.
This timeout can be configured as a JVM system property on any home store system, or
on the extension store mobile server.
xstore.dtxws.makepersistent.timeout.seconds=60
For example, the above system property sets the timeout to one minute.

Security/Authentication
In-store registers that need to connect to the extension store server use a secured
websocket. The websocket authentication leverages the Xstore security credentials
(sec_service_credentials) database table, which allows for preemptive (that is,
ahead of time) credential rotation.
When the retailer approves a temporary store event for an extension store in Xadmin, the
retailer needs to ensure that the necessary credentials are both configured at the
temporary store server (during staging) and loaded at the store.
A specific service ID is used for the credential records. The same service ID will be used
regardless of which temporary store server is hosting the event, however, the credentials
themselves may differ between temporary store servers.
The retailer should treat configuring and rotating these credentials as they would for any
other outbound service calls made from Xstore, for example, to Customer Engagement,
Order Broker, and so on.

Temporary Store Configuration 45-3

Extension Store Configurations

Security and Authentication Considerations

The websocket uses HTTPS for secure communications, the same SSL certificate that IPC
and other server components use.
For Authentication and Authorization, the HTTP BASIC authentication is used, with the
credentials being retrieved from the sec_service_credentials table in the
database.

IDCS Credentials
IDCS Credentials need to be shared between all registers in the store. This data is stored
in the StorePrimary database, and sharing is achieved by having the non-lead registers
access that data from that database. Because the extension store cannot access the
StorePrimary data source at the store, this information is transmitted over the websocket
to the extension store server so it can be stored in the extension store database.

Service IDs
Xstore and Xenvironment use their own individual service key when looking up
credentials from sec_service_credentials:
• Xstore uses EXTENSION_STORE_MOBILE_SERVER
• Xenvironment uses EXTENSION_STORE_XENV
However, in the default configuration, these keys are both mapped to the same actual
service ID: EXTENSION_STORE. The configuration for this can be found in the
services.xml file. For details, see the credentialIdMapping properties of the
serviceCredentialProvider bean.
Thus, a single record in sec_service_credentials table with a service ID of
EXTENSION_STORE can be shared by both Xstore and Xenvironment for authenticating
to their respective extension store servers.
If retailers want to have finer control over the credentials of their extension store servers,
they can configure the credentialIdMapping properties of the
serviceCredentialProvider bean in the services.xml file, and maintain the
credential records in sec_service_credentials table.

Operational Data
This section provides details on operational data within a home store/extension store
setup.

Replication

Extension Store to Home Store

Most data generated at the temporary store, including transactions, will replicate to the
home store, similar to a non-lead register replicating to a lead register. For default
configurations, see the "ExtensionStore->HomeStore" service in extensionstore/
DtxReplicationConfig.xml.

Home Store to Extension Store

By default, only a minimal amount of data is replicated to the temporary store from the
home store, by way of the "HomeStore->ExtensionStore" service. This includes data

45-4 Technical Guide

 Extension Store Configurations

critical for temporary store operations, such as retail location status and inventory stock
ledger updates.

Note: Retailers can control which types of operational data flow

between the home and extension stores by adding and removing
subscribers in the relevant DtxReplicationConfig.xml files.

Mobile Server Registrations

MobileServerDAO records in physical/home stores do not replicate to Xcenter, however,
MobileServerDAO records for extension store servers replicate to Xcenter. Xcenter needs
only to be aware of temporary store server registrations and not physical store server
registrations to support the temporary store request management functionality in
Xadmin. MobileServerDAO records for extension store servers do not replicate to the
home store, because this would potentially allow in-store mobile devices to connect to
the off-site extension store server.

Orders
Note that orders can be submitted from the extension store, however, preexisting orders
not created by the extension store cannot be accessed from the extension store. Order
pickup and fulfillment is expected to be managed from the home store.

Customer Accounts
Customer account (layaway, special order, work order, and so on) creation and
management can only be conducted from the home store at this time.

Inventory
For inventory counting purposes, home and extension stores should have different
default inventory locations. Under this setup, the home store would count in its
inventory location and the extension store would count in its inventory location, and
inventory count documents would not need to replicate between the home and
extension store. By default, home store workstations sell items out of the home store
default inventory location and extension workstations sell items out of the extension
inventory location.

Fiscal and Tax Free Invoices

Fiscal and tax free invoices require the use of a contiguous, store-centric sequence pool
which all registers in the store need to access in real-time to ensure that the sequence
numbers are used sequentially. This is currently not supported in the communication
framework between extension and home stores. Retailers have the following options:
• Do not use the extension store model in locations where fiscal and tax free invoices
are required. Instead use event stores (that is, standalone temporary stores with a
dedicated store number).
• Use the extension store model but require customers to visit the home store for
retroactive issuing of fiscal or tax free invoice when desired.

Note: This may result in a customer being reimbursed for exempted

VAT retroactively instead of having the VAT deducted at the point of
sale.

Temporary Store Configuration 45-5

Extension Store Configurations

Clock In/Out
Clocked in associates are only visible within the home and extension stores in isolation.
An associate cannot clock in at the home store and clock out at the extension store; the
associate would first have to clock out of the home store. Additionally, there are two
SysConfig.xml entries for clocking out associates during a store close:
• AutoClockOutOnRtlLocClose - Determines which associates will be
automatically clocked out at store close.
• ValidateAnyEmployeeNotClockOutYet - Determines whether or not the
system validates that all of the associates are clocked out prior to starting the store
close.
If these are enabled, when closing the store from the extension store, the validations only
apply to employees that were clocked in at the extension store. The extension store does
not have visibility of associates clocked in at the home store.

Sessions and Tills

Session and till data is not replicated between home and extension stores by default. It is
expected that tills and till sessions will be counted and reconciled in the location where
they were used, however, retailers have the ability to customize the flow of data between
home and extension stores in the DtxReplicationConfig.xml file.

Other
Certain back office functionality, for example, shipping/receiving, employee
maintenance, and so on, is reserved for the home store only. The extensionstore/
MenuConfig.xml file controls which base-supported features are available to the
extension store.

Creating a Temporary Store Request

An associate can request a mobile server to be setup for an extension store in the Xstore
back office menu. The request must contain a description, the start date and whether the
mobile server should use the home store's tax location when ringing transactions. An
end date can optionally be entered if the event has a set end date. Once the request data
has been entered, a service request will be sent to Xcenter Temporary Store Services
(endpoint tempstore) to submit the request and write it out to the
loc_temp_store_request table in the Xcenter database.
.

Note: For details about the endpoint tempstore, see the Xstore Suite
Services Guide.
For more details about the loc_temp_store_request table, see the Xstore
POS Database Dictionary.
For more information about how to request a mobile server for an
extension store, how to generate QR codes to quickly set up mobile
devices for temporary stores, and how to set a tax location during the
register open process for a temporary store, see the Xstore Point of
Service Mobile User Guide.

The request will also be written to the Store Primary database. It will not go through the
replication process. This functionality is also available in training mode, except for the
calls to the Xcenter service.

45-6 Technical Guide

 Purging of Temporary Store Request Data

Security Privileges
Security privileges were added to Xstore to handle viewing and creating/editing of
temporary store requests:
• VIEW_TEMP_STORE_REQUESTS - This privilege is used to determine if an associate
can see the list of temporary store requests or a specific request from that list.
• EDIT_TEMP_STORE_REQUESTS - This privilege is used to determine if an associate
can create a new request or edit an existing request

Xcenter Temporary Store Services

The Xcenter Temporary Store Services:
• submit the temporary store request to Xcenter
• update the status of an existing temporary store request
These REST services have a URI of http://localhost:8081/xcenter/rest/
{merchantCode}/{clientVersion}/tempstore. Sending a POST request to this
URI will submit a new request. Sending a PUT will update the status of an existing
request.
When Xstore calls these services and the call fails, the request will be placed in a retry
queue. The request will be retried until successful. The retry request is written to the
store's replication database in the table ctl_service_retry_queue. Once the request
is successful, the record is deleted from this table.
Once a service request is successful, the service will write a record to the Xcenter
ctl_event_log table. Using the data within this record, Xadmin will be able to send
an email notification that there are temporary store request changes that need to be
reviewed. The existing Alert Console functionality within Xadmin is used for this
purpose. Two logger_categories and alertable event types are displayed in Xadmin:
Logger Categories:
• dtv.xcenter.tempstorerequest.info
• dtv.xcenter.tempstorerequestupdate.info
Alertable Event Types:
• TEMP_STORE_REQUEST
• TEMP_STORE_UPDATE
These alertable events are displayed under the Application Alert module.
Xadmin sends an email as soon as the alert is created. This means that the critical
threshold of these new alert types should be set to 1, so Xadmin sends an email upon
recognizing one of these alerts exists. This threshold is maintainable in Xadmin as
currently exists with any other alert type.

Note: For details about the endpoint tempstore, see the Xstore Suite
Services Guide.
For more details about Application Alerts, see the Xstore Office User
Guide.

Purging of Temporary Store Request Data

Temporary store requests are only visible for one year in Xstore and Xadmin. Any
information older than that is purged.

Temporary Store Configuration 45-7

Purging of Temporary Store Request Data

For Xstore, DataPurge batch file runs and deletes data.

For Xadmin, a purge setting was added to remove temporary store requests data.

Note: For details about purge settings for temporary store requests,
see the Xstore Office User Guide.

45-8 Technical Guide

 46
Transaction Attachments

Overview
As part of the transaction, Xstore could create attachments in the table
trn_trans_attachments. They can be created for different reasons and the
attachment_type is used to distinguish them. The attachments are mainly exported from
Xcenter. See chapter Xcenter Attachment Export in Oracle Retail Xstore Office User Guide
for additional information on how to export the attachments from Xcenter.

Transaction Attachments 46-1

Additional Information on Different Attachment Types

Additional Information on Different Attachment Types

Table 46-1 Attachment Types

attachment_bytes
content (data are
saved as array of attachment_bytes
Attachment Type Function bytes) data extension

INVOICE_RESPONSE Electronic Document The invoice XML or JSON

webservice response (inherited from the
configuration)

INVOICE_PAYLOAD Electronic Document The invoice XML or JSON

webservice request (inherited from the
configuration)

ERECEIPT_RESPONS Electronic receipt The electronic XML or JSON

E document webservice (inherited from the
response configuration

ERECEIPT_PAYLOAD Electronic receipt The electronic XML or JSON

document webservice (inherited from the
request configuration

MX_PENDING_GLOBA MX Global Invoice The list of the CSV

L_INVOICES pending global
invoices

MX_INVOIC MX Invoice The MX invoice XML

webservice response

ES_REJECTED_TRAN ES transactions The list of the CSV

S transaction rejected
from the fiscal
authority

DSFINVK_STORAGE_ DE DSFINVK The DSFINVK files ZIP

BYTES archive

TSE_STORAGE_BYTE DE TSE The TSE files archive TAR.GZ

S

Additional information can be found in the Oracle Retail Country Accelerator Technical
Guide.

46-2 Technical Guide

 47
Vertex Integration

Overview
The integration with Vertex Tax Calculation APIs V2 replaces the Xstore Tax Engine. The
Vertex integration can be configured to use both the cloud and a local container.

Base Feature
To enable Vertex External Tax Integrations, add :vertex to your
xstore.config.path.base.features in the configPath.properties file. In case
OAuth2 authentication is required, add :vertex:vertex/oauth2.
Base features are managed through Xstore Office. For more information about base
features, see the Personality Maintenance section in the Oracle Retail Xstore Office User
Guide.
For more information about xstore.config.path.base.features in the
configPath.properties file, see the Xstore Point of Service Configuration Path chapter in
this guide.

Installer
Additionally, you need to define the Vertex Service Endpoint URL.

xstore.properties
#
#################################################################
############
# # Vertex External Tax Services Integration
#
#################################################################
############
oracle.retail.xstore.vertex.url=
oracle.retail.xstore.vertex.ServiceTimeout=

ant.install.properties
You can also define the Vertex Service Endpoint URL during the installation process as
ant.install.properties or through the Xstore Point of Service Installer in GUI mode.
ant.install.properties
#----------------------------------------------------------------
# # Vertex External Tax Services Integration

Vertex Integration 47-1

Sample Tax Calculation Request

#----------------------------------------------------------------
vertex.protocol = https
vertex.host = localhost
vertex.port = 443
vertex.ServiceTimeout = 30

SSL Certificates (If applicable)

Depending on how the Vertex Service is integrated you may need to include the
endpoint's SSL certificates into your .trustore file.
In case of a Vertex private sandbox, you can download the SSL certificates from the
endpoint you setup in your xstore.properties file and download the 3 PEM certificates
locally.

OAuth2 secrets (If applicable)

Depending on how the Vertex Service is integrated you may need to include your client
secrets that have been generated through a Vertex admin account.

Standard Basic Authentication Credentials (If applicable)

User name and password are the same as any user defined in Vertex which has the "API
User" role.

Sample Tax Calculation Request

Request
{
"currency": {
"isoCurrencyCodeAlpha": "USD"
},
"documentDate": "2023-03-10",
"documentNumber": "111",
"lineItems": [
{
"customer": {
"destination": {
"city": "<CITY>",
"country": "US",
"latitude": "<LATITUDE>",
"longitude": "-<LONGITUDE>",
"mainDivision": "OH",
"postalCode": "<POSTALCODE>",
"streetAddress1": "<STREETADDRESS1>"

47-2 Technical Guide

 Sample Tax Calculation Request

}
},
"lineItemId": "<LINEITEMID>",
"lineItemNumber": 1,
"product": {
"productClass": "1"
},
"quantity": {
"value": 1.0
},
"taxIncludedIndicator": false,
"unitPrice": 79.99
}
],
"roundAtLineLevel": true,
"saleMessageType": "QUOTATION",
"seller": {
"company": "US_LEGAL_ENTITY_TEST",
"physicalOrigin": {
"city": "<CITY>",
"country": "US",
"latitude": "<LATITUDE>",
"longitude": "-<LONGITUDE>,
"mainDivision": "OH",
"postalCode": "<POSTALCODE>",
"streetAddress1": "<STREETADDRESS1>"
}
},
"transactionId": "<TRANSACTIONID>",
"transactionType": "SALE"
}

Vertex Integration 47-3

Vertex to Xstore Request Mappings

Vertex to Xstore Request Mappings

Table 47-1 Header Information (SaleRequestType):

Vertex Xstore Description

currency.isoCurrencyCodeAl dtv.location.CurrencyId Currency decimal digits are

pha driving calculated tax
amounts decimals.

documentDate trn_trans.trans_date This date drives the date on

which tax rates are calculated
if any at line item level.

documentNumber trn_trans.trans_seq Not required, since

transactions are not posted in
the Vertex cloud.

roundAtLineLevel true Fixed value. Please refers to

Vertex documentation.

saleMessageType QUOTATION Fixed value. Please refers to

the Vertex documentation.

seller loc_legal_entity/loc_rtl_loc NA
tables

seller.company loc_legal_entity.external_tax_ This code identifies Vertex

system_company_id TaxPayer.

seller.physicalOrigin loc_rtl_loc address info NA

transactionId trn_trans object id Vertex maximum field size is

40. It is left truncated. Not
required, since transactions
are not posted in the Vertex
cloud.

transactionType SALE Fixed value. Please refers to

Vertex documentation.

Table 47-2 Line Item Information (“lineItems” SaleRequestLineItemType):

Vertex Xstore Description

lineItemId trl_sale_lineitm object id Vertex max field size is 40. It

is left truncated. Not
required, since transactions
are not posted in the Vertex
cloud.

lineItemNumber trl_sale_lineitm.rtrans_lineit Used to match request line

m_seq items to response line items.

taxIncludedIndicator false Fixed value. Xstore only

manages SALES taxes.

47-4 Technical Guide

 Vertex to Xstore Request Mappings

Table 47-2 Line Item Information (“lineItems” SaleRequestLineItemType):

Vertex Xstore Description

customer NA No party information are

sent to Vertex (like party_id,
first_name, last_name,
email_address...)

customer.destination loc_rtl_loc address info if no For returns loc_rtl_loc is

ship to customer. from
cat_delivery_modifier trl_sale_lineitm.original_rtl_l
address info if ship to oc_id if set instead of
customer (send sales, special trl_sale_lineitm.rtl_loc_id
orders)
xom_address_mod address
info if ship to customer
(orders)

product itm_item_options/ NA
itm_non_phys_item

product.productClass itm_item_options.tax_group By default mapped to Xstore

_id tax group id. Vertex
Product_Class Taxability
drivers allow to map to a
Vertex Taxability category.

product.value itm_non_phys_item.non_phy By default mapped only for

s_item_subtype Xstore non merchandise
items. Vertex Product value
supersedes Product Class
information.

quantity NA NA

quantity.value 1 Fixed value. Always set as

single quantity in order to
avoid tax amount cents
differences when selling item
with multiple quantities vs.
multiple single quantities
items.
Vertex response adapter will
then multiply the single
quantity calculated tax
amount per the line item
quantity.

quantity.unitOfMeasure itm_item_options.unit_of_m NA
easure_code and
com_measurement.code

unitPrice trl_sale_lineitm.unit_price Unit price at the net

discounts amount.

taxDate trl_sale_lineitm.original_busi Set only for returns.

ness_date if not null

Vertex Integration 47-5

Vertex to Xstore Request Mappings

Product Class and Value Mapping Configuration

It is possible to adopt different predefined configurations for the product/item mapping
between Xstore and Vertex. Refer to config/vertex/spring/vertex-bean.xml spring file for
reference. The default settings are:

vertex-beans.xml
<util:constant id="VERTEX_ITEM_NONE"
static-
field="dtv.pos.register.tax.ext.vertex.VertexTaxSystemConfig.ITE
M_NONE" />
<util:constant id="VERTEX_ITEM_ITEM_ID"
static-
field="dtv.pos.register.tax.ext.vertex.VertexTaxSystemConfig.ITE
M_ITEM_ID" />
<util:constant id="VERTEX_ITEM_MERCH_LEVEL_CONCAT"
static-
field="dtv.pos.register.tax.ext.vertex.VertexTaxSystemConfig.ITE
M_MERCH_LEVEL_CONCAT" />
<util:constant id="VERTEX_ITEM_MERCH_LEVEL_FIRST_NOT_NULL"
static-
field="dtv.pos.register.tax.ext.vertex.VertexTaxSystemConfig.ITE
M_MERCH_LEVEL_FIRST_NOT_NULL" />
<util:constant id="VERTEX_ITEM_TAX_GROUP_ID"
static-
field="dtv.pos.register.tax.ext.vertex.VertexTaxSystemConfig.ITE
M_TAX_GROUP_ID" />
<util:constant id="VERTEX_ITEM_NP_SUBTYPE"
static-
field="dtv.pos.register.tax.ext.vertex.VertexTaxSystemConfig.ITE
M_NP_SUBTYPE" />
<util:constant id="VERTEX_ITEM_NP_TYPE"
static-
field="dtv.pos.register.tax.ext.vertex.VertexTaxSystemConfig.ITE
M_NP_TYPE" />
<util:constant id="VERTEX_ITEM_NP_TYPE_CONCAT"
static-
field="dtv.pos.register.tax.ext.vertex.VertexTaxSystemConfig.ITE
M_NP_TYPE_CONCAT" />

<bean id="vertexTaxSystemConfig"
class="dtv.pos.register.tax.ext.vertex.VertexTaxSystemConfig">
<property name="itemMerchCodeType" ref="VERTEX_ITEM_NONE" />
<property name="itemNonMerchCodeType"
ref="VERTEX_ITEM_NP_SUBTYPE" />

47-6 Technical Guide

 Vertex to Xstore Request Mappings

<property name="itemMerchTaxCodeType"
ref="VERTEX_ITEM_TAX_GROUP_ID" />
<property name="itemNonMerchTaxCodeType"
ref="VERTEX_ITEM_TAX_GROUP_ID" />
</bean>

The table below summarizes the values that can be configured.

Note: The Vertex maximal field length is 40, therefore the result could
be truncated.

Constant Setting Description

VERTEX_ITEM_NONE
VERTEX_ITEM_ITEM_ID
VERTEX_ITEM_MERCH_LEVEL_CONC
AT
VERTEX_ITEM_MERCH_LEVEL_FIRST_
NOT_NULL
VERTEX_ITEM_TAX_GROUP_ID
VERTEX_ITEM_NP_SUBTYPE
VERTEX_ITEM_NP_TYPE
VERTEX_ITEM_NP_TYPE_CONCAT
Returns a null value. The information is not
sent to Vertex.
Returns itm_item.item_id.
Returns the concatenation ('::' is the separator
between the values) of the four
itm_item.merch_level_X by adding a "NULL"
string constant for every merch level is null or
empty.
Returns the first non null
itm_item.merch_level_X by starting to
process it from itm_item.merch_level_4 to
itm_item.merch_level_1.
Returns trl_sale_lineitm.tax_group_id.
Returns
itm_non_phys_item.non_phys_item_subty
pe.
Returns
itm_non_phys_item.non_phys_item_typco
de.
Returns the concatenation of
itm_non_phys_item.non_phys_item_typc
ode + "::"
+itm_non_phys_item.non_phys_item_subt
ype.

Each of the following four vertexTaxSystemConfig properties can be configured

with any of the values above:

Property Name Description

itemMerchCodeType
itemNonMerchCodeType
itemMerchTaxCodeType
This applies to Xstore merchandise items
and it results to Vertex product.value.
This applies to Xstore non-merchandise
items and it results to Vertex product.value.
This applies to Xstore merchandise items
and it results to Vertex
product.productClass.

Vertex Integration 47-7

Sample Tax Calculation Response

Property Name Description

itemNonMerchTaxCodeType This applies to Xstore non-merchandise
items and it results to Vertex
product.productClass.

Sample Tax Calculation Response

Response
{
"data": {
"currency": {
"isoCurrencyCodeAlpha": "USD",
"isoCurrencyCodeNum": 0,
"isoCurrencyName": "US Dollar"
},
"documentDate": "2023-03-10",
"documentNumber": "111",
"lineItems": [
{
"customer": {
"destination": {
"city": "<CITY>",
"country": "US",
"latitude": "<LATITUDE>",
"longitude": "<LONGITUDE>",
"mainDivision": "OH",
"postalCode": "<POSTALCODE>",
"streetAddress1": "<ADDRESS>",
"taxAreaId": "<TAXAREAID>"
}
},
"extendedPrice": 79.99,
"fairMarketValue": 79.99,
"lineItemId":
"<LINEITEMID>",
"lineItemNumber": 1,

47-8 Technical Guide

 Sample Tax Calculation Response

"product": {
"productClass": "1"
},
"quantity": {
"value": 1.0
},
"seller": {
"company": "US_LEGAL_ENTITY_TEST",
"physicalOrigin": {
"city": "<CITY>",
"country": "US",
"latitude": "<LATITUDE>",
"longitude": "<LONGITUDE>",
"mainDivision": "OH",
"postalCode": "<POSTALCODE>",
"streetAddress1": "<ADDRESS>",
"taxAreaId": "<TAXAREAID>"
},
"taxRegistrations": []
},
"taxIncludedIndicator": false,
"taxes": [
{
"calculatedTax": 4.6,
"calculationRuleId": {
"salesTaxHolidayIndicator": false,
"userDefined": false,
"value": "v516381"
},
"effectiveRate": 0.0575,
"exempt": 0.0,
"imposition": {
"impositionId": "v1j28101",
"userDefined": false,

Vertex Integration 47-9

Sample Tax Calculation Response

"value": "Sales and Use Tax"

},
"impositionType": {
"impositionTypeId": "v1",
"userDefined": false,
"value": "General Sales and Use Tax"
},
"inclusionRuleId": {
"salesTaxHolidayIndicator": false,
"userDefined": false,
"value": "v1280926"

},
"isService": false,
"jurisdiction": {
"effectiveDate": "1900-01-01", "expirationDate": "9999-12-
31", "jurisdictionId": "28101", "jurisdictionType":
"STATE", "value": "OHIO"

},
"maxTaxIndicator": false, "nominalRate": 0.0575,
"nonTaxable": 0.0, "notRegisteredIndicator": false,
"situs": "DESTINATION", "taxCollectedFromParty": "BUYER",
"taxResult": "TAXABLE", "taxStructure": "SINGLE_RATE",
"taxType": "SELLER_USE",
"taxable": 79.99

},
{
"calculatedTax": 1.0,
"calculationRuleId": {
"salesTaxHolidayIndicator": false,
"userDefined": false,
"value": "v144561"
},
"effectiveRate": 0.0125,
"exempt": 0.0,

"imposition": {

47-10 Technical Guide

 Sample Tax Calculation Response

"impositionId": "v1j28405",
"userDefined": false,
"value": "Local Sales and Use Tax"
},
"impositionType": {
"impositionTypeId": "v1",
"userDefined": false,
"value": "General Sales and Use Tax"
},
"inclusionRuleId": {
"salesTaxHolidayIndicator": false,
"userDefined": false,
"value": "v1286088"
},
"isService": false,
"jurisdiction": {
"effectiveDate": "1900-01-
01", "expirationDate": "9999-
12-31", "jurisdictionId":
"28405", "jurisdictionType":
"COUNTY", "value": "CUYAHOGA"

},
"maxTaxIndicator": false,
"nominalRate": 0.0125,
"nonTaxable": 0.0,
"notRegisteredIndicator":
false, "situs": "DESTINATION",
"taxCollectedFromParty":
"BUYER", "taxResult":
"TAXABLE", "taxStructure":
"SINGLE_RATE",
"taxType":
"SELLER_USE",
"taxable": 79.99

},
{

Vertex Integration 47-11

Sample Tax Calculation Response

"calculatedTax": 0.8,
"calculationRuleId": {

"salesTaxHolidayIndicator": false,
"userDefined":
false, "value":
"v14822"

},
"effectiveRate": 0.01,
"exempt": 0.0,
"imposition": {

"impositionId": "v1j28406",
"userDefined": false,
"value": "Local Sales and Use Tax"

},
"impositionType": {
"impositionTypeId": "v1",
"userDefined": false,
"value": "General Sales and Use Tax"

},
"inclusionRuleId": {
"salesTaxHolidayIndicator": false,
"userDefined": false,
"value": "v1284340"

},
"isService": false,
"jurisdiction": {
"effectiveDate": "1900-01-01",
"expirationDate": "9999-12-31",
"jurisdictionId": "28406",
"jurisdictionType": "DISTRICT",
"value": "GREATER CLEVELAND TRANSIT
AUTHORITY TAX"

},
"maxTaxIndicator": false,
"nominalRate": 0.01,

47-12 Technical Guide

 Sample Tax Calculation Response

"nonTaxable": 0.0,
"notRegisteredIndicator":
false, "situs": "DESTINATION",
"taxCollectedFromParty":
"BUYER", "taxResult":
"TAXABLE",

"taxStructure": "SINGLE_RATE",
"taxType": "SELLER_USE",
"taxable": 79.99
}
],
"totalTax": 6.4,
"transactionType": "SALE",
"unitPrice": 79.99

}
],
"returnAssistedParametersIndicator": true,
"roundAtLineLevel": false,
"saleMessageType": "QUOTATION",
"seller": {
"company": "US_LEGAL_ENTITY_TEST",
"physicalOrigin": {
"city": "<CITY>",
"country": "US",
"latitude": "<LATITUDE>",
"longitude": "<LONGITUDE>",
"mainDivision": "OH",
"postalCode": "<POSTALCODE>",
"streetAddress1": "<ADDRESS>",
"taxAreaId": "<TAXAREAID>"

},
"taxRegistrations": []

},
"subTotal": 79.99,

Vertex Integration 47-13

Vertex to Xstore Response Mapping

"total": 86.39,
"totalTax": 6.4,
"transactionId": "1000::101::1678406400000::1::111",
"transactionType": "SALE"
},
"meta": {
"app": "vertex-ws.war v9.0.11.2.6",
"timeElapsed(ms)": 109,
"timeReceived": "2023-03-10T11:38:53.505Z"
}
}

Vertex to Xstore Response Mapping

Line Item information ("lineItems" SaleResponseLineItemType):

Vertex Xstore Description

lineItemNumber trl_sale_lineitm Used to match XStore line item
request.

Taxes information ("taxes" SaleResponseLineItemType). For each TaxesType a tax

modfier (trl_sale_tax_lineitm) is created:

TaxInfoResponse
Vertex object Xstore notes
calculatedTax TaxAmount trl_sale_tax_lineitm.ra Vertex calculatedTax
w_tax_amountif not amount is multiplied
exempt or override by Xstore line item
trl_sale_tax_lineitm.tax quantity.
_amt
taxable TaxableAmount if not exempt or Vertex taxable amount
override is multiplied by Xstore
trl_sale_tax_lineitm.tax line item quantity.
able_amt
effectiveRate TaxPercentage trl_sale_tax_lineitm.ra NA
w_tax_percentage
jurisdiction.value AuthorityId trl_sale_tax_lineitm.aut NA
hority_id
imposition.value AuthorityName trl_sale_tax_lineitm.aut For Canada contains
hority_name GST/HST.
jurisdiction.jurisdiction AuthorityType trl_sale_tax_lineitm.aut NA
Type hority_type

47-14 Technical Guide

 Sample Tax Area Lookup Request (Vertex Tax-Area-Lookup )

TaxInfoResponse
Vertex object Xstore notes
jurisdiction.jurisdiction TaxLocationId trl_sale_tax_lineitm.tax This fills tax modifiers
Id _loc_id tax_loc_id with the
external Tax
Calculation Service
jurisdiction id to ensure
the uniquess of tax
group rules
jusrisdiction/authority.
filingCategoryCode TaxType TaxGroupRule.TaxType Fixed to
dtv.pos.register.tax.Tax
Type.SALES.
For Canada for tax
which belongs to
COUNTRY jurisdiction
type based on
filingCategoryCode is
present or not, it will
return TaxType.HST or
TaxType.GST.
For tax which belongs
to PROVINCE
jurisdiction type it
returns TaxType.PST.

Sample Tax Area Lookup Request (Vertex Tax-Area-Lookup )

Tax Area Lookup Request
{
"asOfDate": "2023-03-12",
"postalAddress": {
"city": "Solon",
"country": "US",
"mainDivision": "OH",
"postalCode": "<POSTALCODE>",
"streetAddress1": "<ADDRESS>"
}
}

Vertex to Xstore Request Mappings

(AddressLookupRequestType)

Vertex Xstore Notes

asOfDate Current Business Date NA

Vertex Integration 47-15

Sample Tax Area Lookup Response
Vertex
postalAddress.country
postalAddress.mainDivision
postalAddress.subDivision
postalAddress.city
postalAddress.postalCode
postalAddress.streetAddress1
postalAddress.streetAddress2
Sample Tax Area Lookup Response
{
"data": {
"lookupResults": [
{
"addressCleansingResultMessages": [
{}
],
"asOfDate": "2023-03-12",
"confidenceIndicator": "86",
"jurisdictions": [
{
47-16 Technical Guide
Xstore Notes
loc_rtl_loc.country The source is from different
cat_delivery_modifier.country tables depending on the
xom_address_mod.country current process flow. For
example, a preflight check for
a current store location or
delivery address for ship to
customer accounts validation.
loc_rtl_loc.state NA
cat_delivery_modifier.state
xom_address_mod.state
loc_rtl_loc.county NA
cat_delivery_modifier.county
xom_address_mod.county
loc_rtl_loc.city NA
cat_delivery_modifier.city
xom_address_mod.city
loc_rtl_loc.postal_code Used also for tax location
cat_delivery_modifier.postal_c change for tax overrides
ode validation together with
xom_address_mod.postal_cod current store country.
e
loc_rtl_loc.address1 NA
cat_delivery_modifier.address
1
xom_address_mod.address1
loc_rtl_loc.address2 NA
cat_delivery_modifier.address
2
xom_address_mod.address2
"effectiveDate": "1900-01-01",
"expirationDate": "9999-12-31",
"jurisdictionId": "1",
"jurisdictionType": "COUNTRY",
 Sample Tax Area Lookup Response

"value": "UNITED STATES"

},
{
"effectiveDate": "1900-01-01",
"expirationDate": "9999-12-31",
"jurisdictionId": "28101",
"jurisdictionType": "STATE",
"value": "OHIO"
},
{
"effectiveDate": "1900-01-01",
"expirationDate": "9999-12-31",
"jurisdictionId": "28405",
"jurisdictionType": "COUNTY",
"value": "CUYAHOGA"
},
{
"effectiveDate": "1900-01-01",
"expirationDate": "9999-12-31",
"jurisdictionId": "<JURISDICTIONID>",
"jurisdictionType": "<JURISDICTIONTYPE>",
"value": "<CITY>"
},
{
"effectiveDate": "1900-01-01",
"expirationDate": "9999-12-31",
"jurisdictionId": "28406",
"jurisdictionType": "DISTRICT",
"value": "<COMPANYNAME>"
}
],
"postalAddresses": [],
"statuses": [
{
"lookupResult": "NORMAL",
"value": "Successful lookup. (lookup region
types=\"Postal Code,City,Sub Division,Main Division,Country\",

Vertex Integration 47-17

VERTEX to Xstore Response Mappings

address fields=\"Street Information=30500 BRUCE INDUSTRIAL PKWY,

Street Information 2=null, Postal Code=44139, City=SOLON, Sub
Division=null, Main Division=OH, Country=USA\")"
}
],
"taxAreaId": "<TAXAREAID>"
}

#################################
...OMITTED MULTIPLE LOOKUP RESULT
#################################

]
},
"meta": {
"app": "vertex-ws.war v9.0.11.2.6",
"timeElapsed(ms)": 31,
"timeReceived": "2023-03-16T10:01:23.593Z"
}
}

VERTEX to Xstore Response Mappings

(TaxAreaLookupResponseType.lookupResults)

Vertex Xstore Description

TaxAreaLookupResultType.tax No real usage Used only to perform a
AreaId validity check that a value is
present.

Logging
Vertex integrations takes advantage of the base service framework capabilities.
log4j2.xml
<Logger
name="dtv.servicex.impl.WSLoggingHandler.VERTEX_TAX_AREA_LOOKUP_S
ERVICE" level="trace" />
<Logger
name="dtv.servicex.impl.WSLoggingHandler.VERTEX_CALCULATE_TAX_SER
VICE" level="trace" />
Based on how much information (size) you want to log of the entity you need to set the
above logging level to debug or trace for your services ID.
In order to log the message entity you need to change the services bean configuration.
There are two properties you can set on your service spring bean:

47-18 Technical Guide

 Store Configuration

logEntity: If set to true, the system will log the message entity content. This boolean
property value is mapped into Vertex spring beans to a system.property that can be
defined in the xstore.properties to set the value instead of overriding the spring bean
definition:
xstore.properties
oracle.retail.xstore.vertex.logEntity=true
logMaxEntitySize: If not defined, the system will use the default based on log4j logging
level. If defined, the system will override the default max entity size.
Additional debug traces about tax calculation process can be obtained by enabling these
logging categories:
log4j2.xml
<Logger name="dtv.pos.register.tax.ext" level="debug" />
<Logger name="oracle.retail.xstore.tax.ext" level="debug" />

Store Configuration
If you are using standard basic authentication, that is :vertex configuration path only,
valid service credentials must be configured in the sec_service_credentials table for
VERTEX_CALCULATE_TAX_SERVICE and
VERTEX_TAX_AREA_LOOKUP_SERVICE. Implemented as a preflight check.
If you are using OAuth2 authentication, that is :vertex:vertex/oauth2 configuration path,
valid service credentials must be configured in the sec_service_credentials table for the
service id configured as parameter of the dtv.pos.services.CredentialsTokenManager
bean class in the services-vertex.xml (VERTEX_TAX_SERVICES). Implemented as a
preflight check.
A valid store location address must be configured for the store. This is validated through
the Vertex Tax-Area-Lookup API. A location is valid as long as the Vertex service can be
contacted and returns at least one tax area ID for the configured address. Implemented
as a preflight check.
Tax locations for a current store needs to be configured, note that this is a mandatory
field in the Xstore Office store configuration. It is already part of the base preflight
checks.
No active tax group rules for the current tax location have to be found. Implemented as a
preflight check. Ideally the tax_tax_group_rule and tax_tax_rate_rule tables should be
empty but it is not a constraint as long as no tax rates are active.
A legal entity must be defined for the current store, the
loc_legal_entity.external_tax_system_company_id is identifying the Vertex Tax Payer.
Implemented as a preflight check.
The DisallowCountryChangeForShippingInExtendedTransactions
SysConfig.xml flag must be set to true, this is already set to true in the ":vertex" base
feature config.path.
The ItemReturn---AllowVerifiedReturnChanges SysConfig.xml flag needs to
be set to false, this is already set to true in the ":vertex" base feature config.path.

Vertex Integration 47-19

Store Configuration

47-20 Technical Guide

 A
Configuration Files

Overview
This section lists the various Xstore Point of Service configuration files and directories,
along with a brief description of their effect on Xstore Point of Service processing.
Once the customer-specific values for any of Xstore Point of Service’s operations are
defined, they can be specified in an XML configuration file. Each XML configuration file
contains the settings for some aspect of Xstore Point of Service’s operation or function.
Within each configuration file, each individual property of that function is paired with
the customer-specific value to be used.

Key XML Configuration Files

The table below lists many (but not all) significant XML configuration files that allow
you to control Xstore Point of Service’s behavior.
Table A-1 XML Configuration Files

XML File Name Description

ActionConfig.xml Defines menu action details such as Op Chains

and Visibility Rules.

ActivityStreamConfig.xml Defines what data, and how the data is rendered

in the Activity Stream.

ApplicationConfig.xml Defines operations and screens that run when

Xstore Point of Service enters or exits the
Register application and the Back Office
application.

AuthConfig.xml Defines all aspects of transaction authorization,

such as prompting, authorization methods, retry
attempts, error handling, online, and offline
procedures.

AvailableLocales.xml Specifies local language and internationalization

features that may be used in Xstore Point of
Service.

ContextConfig.xml Used to add context to areas in the application

so that help/message information can be tailored
to them.

Configuration Files A-1

Key XML Configuration Files

Table A-1 XML Configuration Files (continued)

XML File Name Description

DataLoaderConfig.xml Maps fields from the flat file to fields on Java

data objects, which can then be persisted to the
database via Xstore Point of Service’s persistence
framework (DTX). Any modification or
transformation of the data that is required is
specified in this configuration file. Also,
completely custom SQL statements can be
written in order to load the data in an
appropriate fashion.

DataSourceConfig.xml Identifies the various online and offline data

sources available to Xstore Point of Service.

DtxReplicationConfig.xml Used by Xstore Point of Service’s persistence

framework (DTX). The replication queue is used
to store and retrieve replication data that has not
yet been successfully replicated to its
destination.

EnvironmentConfig.xml Used to configure the hostname and port for the

xEnvironment, as well as to enable/disable
communications with it. This file also contains
configuration options for selecting the client
authentication method, and for specifying the
locations of environment configuration files and
the marker folder.

HardwareConfig.xml Identifies the peripheral hardware devices used

by Xstore Point of Service such as printers, data
displays, PIN pads, readers and, others.

InputConfig.xml Defines the rules for identifying and validating

information entered, scanned, or swiped into
Xstore Point of Service. Most of the input rules
revolve around identifying and validating
tender information (card numbers, pin numbers,
etc.), but it is also used to validate and interpret
information from barcodes on receipts, shipping
documents, and items.

KeyboardConfig.xml Used to maintain the visual and functional

aspect of the keyboard. The file consists of
definitions of one or more layouts, composed of
multiple panels that contains rows of buttons.

LabelConfig.xml Used for configuring the layout of labels,

providing support for the zpl printers.

LocaleMap.xml Defines the language configurations for different

areas of Xstore Point of Service. In this
configuration file, each MapEntry element has a
key attribute that specifies an area of Xstore
Point of Service, and a corresponding value
attribute that specifies the default language that
it uses.

MenuConfig.xml Specifies the placement and availability of

function and report buttons in Xstore Point of
Service.

A-2 Technical Guide

 Key XML Configuration Files

Table A-1 XML Configuration Files (continued)

XML File Name Description

OpChainConfig.xml Defines the operation chains that define function

processes and behavior.

PayrollOvertimeConfig.xml Specifies each overtime rule containing the

payroll category that overtime hours belong to.

PersistenceManagerConfig.xml Identifies the online and offline persistence

manager types that are used with each data
source identified in DataSourceConfig.xml.

PmTypeMappingConfig.xml Maps Java objects to persistence manager types.

These mappings create one-to-many
relationships between PM Types and Java
objects. This organizes the Java objects into
logical, intuitively named groups, and allows
multiple Java objects to be configured to access
the same data sources.

PromptConfig.xml Defines the on-screen prompts, messages, and

buttons that are displayed when events occur in
specific Xstore Point of Service functions.

RcptConfig.xml Defines the layout for output from the receipt

printer, including franking layouts.

SysConfig.xml Defines the values for Xstore Point of Service

function settings. These setting values determine
how the application behaves when an Xstore
Point of Service event occurs. They also specify
key global identifiers, such as the organization,
store, and register.
To use the Xstore Office SysConfig GUI, the
SystemConfigMetadata.properties file
must be maintained along with all
SysConfig.xml changes.
See “System Config Metadata”.

ServiceHandlers.xml Defines endpoints for Web service URLs and

identifies which Java classes are used to prepare
the Web service request object and unwrap/
interpret the Web service response object for
each service call.

SubstituteComponentConfig.xml Used to externalize configurations in the

UIConfig.xml, making it easy to override a
single UI without affecting other UI
customization.

UIConfig.xml Defines the UI layout.

validations.xml Defines the type of validation required for each

event in Xstore Point of Service.

VoucherConfig.xml Defines the options for voucher activities,

processes and behavior.

Configuration Files A-3

Initial Xstore Point of Service Configuration

Initial Xstore Point of Service Configuration

The application of overtime in the payroll function is a good example of where
configuration is important. Overtime rules vary widely; for example, overtime pay may
be mandated in some locations when an employee works over eight hours per day, and
in other locations, overtime may be earned only after the total weekly hours exceed forty.
To handle these different requirements, a named rule may be established in the
SysConfig.xml file to define the conditions when overtime pay is applied.

system.properties
When Xstore Point of Service starts, it opens the system.properties file, which
contains the directory path where the configuration settings are stored. These settings
affect many aspects of Xstore Point of Service’s operation, such as data sources, operating
processes (business logic), and hardware configurations.
In Xstore Point of Service, each brand, store, and terminal can be uniquely identified.
This enables configuration settings to be applied at the appropriate level according to
business or legal requirements. An example of this identification is seen here:

#----------------------------------------------------------------
----------------------------
# SYSTEM IDENTITY
#----------------------------------------------------------------
----------------------------
dtv.location.organizationId=1000
dtv.location.storeNumber=101
dtv.location.terminalNumber=1
dtv.location.primaryTerminalNumber=1
dtv.location.CurrencyId=USD
dtv.location.device.formfactor=desktop

A-4 Technical Guide

 System Config Metadata

System Config Metadata

Important: If any SysConfig.xml files are manually created and
installed on any store/register (via configuration path), the changes
they contain will work in Xstore Point of Service as they always have;
however these configurations will be totally unknown to the Xstore
Office System Config GUI, and may possibly impair its ability to work
properly. Hence, this practice should be avoided if Xstore Office is
expected to allow total control over system configuration.

Overview - Xstore Office SysConfig GUI

SystemConfigMetadata.properties
To use the Xstore Office SysConfig GUI, the SystemConfigMetadata.properties
file must be maintained along with all SysConfig.xml changes.
The SystemConfigMetadata.properties file contains critical information needed
by the Xstore Office System Config GUI. This file is a counterpart to Xstore Point of
Service's SysConfig.xml file, which is the main file for storing system configuration
settings.
As there are multiple copies of SysConfig.xml in Xstore Point of Service which support
base configurations and customer overrides (via the Xstore Point of Service "config path"
system), there are also multiple SystemConfigMetadata.properties files.
However, unlike SysConfig.xml, these metadata files are not governed/configurable by
config path. In fact, there will only ever be exactly two copies of
SystemConfigMetadata.properties:
- dtv/res/config/SystemConfigMetadata.properties - The base
definition found in config.jar, and companion to SysConfig.xml in the same
location.
- version1/SystemConfigMetadata.properties - The Operations team's
"overrides", typically found in the customer jar. All customer-specific overrides
for metadata must be put into this file.

Metadata Information
The metadata provides the following additional information for each configurable item
in SysConfig.xml:
• Category - Each configuration is assigned to a single category. Configurations in the
GUI are organized/grouped by this category. This category is separate from the
structure imposed by the SysConfig.xml file itself. Categories can be altered at any
time and are also I18N translatable.
• Label - Each configuration has an I18N descriptive title, often presented in the form
of a question (ex. Allow Cashier to be Eligible as Commissioned Associate?).
• Description - This is an I18N long description (generally a paragraph) that details
the meaning, impact, etc. of each configuration.
• Order - This is a way to optionally force the order in which each group of
configurations within a given category will be sorted in the GUI. Configurations are
sorted first by this order setting, and then alphabetically.
• Module(s)/Tag(s) - each configuration has at least one (and possibly more)
associated modules/tags. These modules/tags can be simply thought of as

Configuration Files A-5

System Config Metadata

"keywords". The GUI uses this information to provide a filtering function that lets
the user zero-in on configurations which are pertinent to the task at hand (or weed
out configurations which are not pertinent).
• Datatype - Although each configuration in SysConfig.xml is already associated to a
"dtype", these datatypes are very rudimentary and are intended to be a convenience
for Xstore Point of Service developers. In comparison, the metadata Datatype has
additional capabilities that allow the GUI to much more strictly control and validate
the user's input.
• Privilege - This is an optional attribute that refers to an Xstore Office (not Xstore
Point of Service) privilege. When a configuration is associated to an Xstore Office
privilege, the Xstore Office user's role must have that privilege in order for that
configuration to be available in the System Config GUI. In base, most configurations
are unprotected (i.e. have no associated privilege) and are therefore available in the
GUI; however, a small number of configurations are intentionally hidden. If needed,
privileges may be added to prevent certain types of Xstore Office users from
accessing certain system configurations. (For example, for chains that have
"franchisee" stores, where a franchisee store needs to be able to make certain system
configuration changes, but must not be allowed full access to all system
configurations).

Note: For developer-level technical details, refer to the "base" copy of

dtv/res/config/SystemConfigMetadata.properties, which contains
extensive documentation in comments at the top of the file.

SystemConfigMetadata.properties sample
_Store---SystemConfig---ItemSale---
RequireItemVoidReasonCode.label=Prompt For Line Item Void Reason
Code?
_Store---SystemConfig---ItemSale---
RequireItemVoidReasonCode.description=Determines whether or not
the system prompts the associate to select a reason code when
voiding an item.
Store---SystemConfig---ItemSale---
RequireItemVoidReasonCode.datatype=Bool
Store---SystemConfig---ItemSale---
RequireItemVoidReasonCode.category=_sales
Store---SystemConfig---ItemSale---
RequireItemVoidReasonCode.order=0
Store---SystemConfig---ItemSale---
RequireItemVoidReasonCode.tag.1=_sale

I18N Information
The SystemConfigMetadata.properties file is used in two different ways by
Xstore Office. First, it is used by custom code which parses all of the properties and
dynamically constructs the System Config GUI using its information in combination
with the contents of SysConfig.xml.
Also, it is separately loaded using the DtvResourceBundle library, and its contents are
treated as Xstore Point of Service-style I18N translations.

A-6 Technical Guide

 System Config Metadata

In the SystemConfigMetadata.properties file, some of the properties keys are

prefixed with an underscore ("_"); any such property can and will be treated as a
translatable I18N resource. This allows an exhaustive amount of System Configuration
information to be fully internationalizable.

Configuration Files A-7

System Config Metadata

A-8 Technical Guide

 B
EFTLink

Overview
EFTLink is a middleware application used to communicate with authorization
processors. With EFTLink, the communication protocol and data exchange is handled by
the payment service provider (PSP) instead of Xstore Point of Service. Credit and Debit
messages are supported.

Note: For more information about EFTLink, contact your product

representative.

Xstore Point of Service, EFTLink, and Payment Service Provider

Responsibilities
• Xstore Point of Service sends the applicable authorization requests to EFTLink, and
handles the authorization responses back from EFTLink.
• EFTLink handles the communication between the PIN Entry Device (PED) and
Xstore Point of Service.
• The payment service provider (PSP) handles the communication protocol between
the system and the processor.

EFTLink and Xstore Point of Service

• All standard Credit Card types are supported (VISA, MasterCard, Discover and
AMEX).
• Credit and Debit cards cannot be swiped via the MSR when the EFTLink solution is
implemented. Other types of cards such as gift cards, loyalty cards, private label, etc.
may be swiped on the MSR.
• For issues with time-outs or errors, it is assumed the associate will use an alternative
form of tender, or retry the same tender.
• In a Return transaction, searching for a transaction with the customer's credit card
number is not available when the EFTLink solution is implemented.
• Connectivity (for example, Dial Up, IP, SSL, and so on) is determined between the
payment service provider and the retailer.
• The payment service provider will process a reversal for failed or time out attempts
during a transaction.
• Calls for authorization will only be approved for the amount requested. Insufficient
funds/partial authorization is not supported on phone authorizations.

EFTLink B-1
Xstore Point of Service Setup to Use EFTLink

• The Cash Back feature is not supported at this time.

• Since the customer can swipe any type of card, Smart Prompt functionality is out of
scope for this implementation.
• Store and Forward (SAF) functionality is not supported in Xstore Point of Service
when authorizing via EFTLink.
• The STAN number sent by EFTLink to Xstore Point of Service is stored in the
ttr_credit_debit_tndr_lineitm.orig_STAN column.

Xstore Point of Service Setup to Use EFTLink

Follow the steps below to set up Xstore Point of Service to use EFTLink for
authorizations.
1. Install the EFTLink application.

Note: EFTLink installation instructions are out of scope for this

document. Please refer to Eftlink Deployment Guide for more
information.

2. Append the following entries to the xstore.config.path.base.features in

the configPath.properties file.

Note: EFTLink can be enabled through the Personality Maintenance

feature in Xstore Office/Xstore Office Cloud Service. For more
information about Personality Maintenance, see the Xstore Office/Xstore
Office Cloud Service User Guide.

- If you want to use EFTLink for credit card authorization add

:authprocessor/eftlink to the xstore.config.path.base.features
in the configPath.properties file.
Example:
xstore.config.path.base.features=:authprocessor/eftlink
If you are using SQL Server, edit this property as follows to run SQL Server
customer-related queries:
xstore.config.path.base.features=:authprocessor/
eftlink:dtv/sql/mssql
- If you want to use both credit card and gift card authorizations then add
:authprocessor/eftlink:authprocessor/eftlink/giftcard to the
xstore.config.path.base.features in the configPath.properties
file.
Example:
xstore.config.path.base.features=:authprocessor/eftlink/
giftcard
If you are using SQL Server, edit this property as follows to run SQL Server
customer-related queries:
xstore.config.path.base.features=:authprocessor/eftlink/
giftcards:dtv/sql/mssql

B-2 Technical Guide

 Xstore Point of Service Setup to Use EFTLink

3. In the SysConfig.xml file set EnableGiftCardSupportForEftLink to True

to swipe gift cards through the EFTLink controlled pinpad.
4. In config/authprocessor/eftlink/AuthConfig.xml, modify DialHost
and deviceCommChannel to match the ports defined in EFTLink when setting it
up.
<Parameter name="communicatorHosts">
<param_value dtype="List">
<DialHost dtype="String">socket://
localhost:<PORT>;timeout=1000</DialHost>
</param_value>
</Parameter>
<Parameter name="deviceCommChannel" value="socket://
localhost:<PORT>"/>
DialHost contains the primary port and deviceCommChannel contains the
secondary port. See AuthConfig.xml below.
5. In the tnd_tndr_options table, set the auth_mthd_code for all credit card
tenders (for example, VISA, MASTERCARD, AMEX etc.) to EFT_LINK_CREDIT.

EFTLink B-3
AuthConfig.xml

AuthConfig.xml
The following auth processes are found in config/eftlink/AuthConfig.xml:
EFT_LINK_HOST, EFT_LINK_STORE_SETTINGS, EFT_LINK_CREDIT and auth
request map EFT_LINK.

Parameters in AuthConfig.xml
<Parameter name="deviceCommChannel" value="socket://
localhost:10101"/>
• Defines the port for the secondary channel EFTLink will use to communicate to get
user inputs (EFT_LINK_HOST). For base Xstore Point of Service, the server will
always be 'localhost' since this port is opened on the system where the Xstore Point
of Service is installed.
<Parameter name="communicatorHosts">
<param_value dtype="List">
<Host dtype="String">socket://localhost:<PORT>;timeout=1000
</Host>
• Defines the standard settings Xstore Point of Service will use when supplying the list
of EFTLink hosts.
<Parameter name="displayTimeout" value="1000"/>

Note: Since EFTLink supports PED pooling, the

additionalWorkstationHostsMap parameter has been removed
from the AuthConfig.xml file.
See the PED Pooling in EFTLink section for more information on how
to use PED Pooling in EFTLink.

• Defines how many milliseconds the EFTLink information messages will display on
the screen.
<parameter name="RequestType" value="PAYMENT"/>
• Defines the request type Xstore Point of Service will use when it sends the
authorization request to EFTLink.
<Parameter name="DisableCashback" value="false" />
• When set to true, this setting disables the cashback functionality in EFTLink.
EFTLink will not give the customer an option to select a cashback during the
authorization. For Xstore, the default value is set to false and for the SelfCheckout
mode the default value is set to true.

PED Pooling in EFTLink

To use PED pooling in EFTLink, the file
xstoredata\xstore\EftlinkConfig.properties is needed in the installation
directory of Xstore Point of Service or in its class path.
Define the following minimum settings in the PED pooling section of the
EFTlinkConfig.properties file:
# Whether to enable PED pooling.
PEDPoolOneCatchAllChannel0 = true
ServerChannel0 = 10100

B-4 Technical Guide

 AuthConfig.xml

TLSEnabled = true
pos1.description = POS 1
pos2.description = POS 2

PEDPoolOneCatchAllChannel0:
• true - to enable the PED pooling support.
• false - for a stand alone mode setup for EFTLink
ServerChannel0 - This is the default base channel of EFTLink.
pos clients - To add a new client, add a new line using the following format:
pos[register rumber].description = [name of the client]
Example:
pos1.description = POS 1
pos2.description = POS 2
pos35.description = Handheld
pos36.description = Tablet

Auth Request Map

<AuthRequestMap name="EFT_LINK">
<AuthRequest key="TENDER"
class="dtv.tenderauth.impl.eftlink.request.EftLinkCreditDebitRequ
est" enabled="true">
<parameter name="TerminalID" ref="TerminalID"/>
<parameter name="RequestType" value="PAYMENT"/>
</AuthRequest>
<AuthRequest key="REFUND_TENDER"
class="dtv.tenderauth.impl.eftlink.request.EftLinkCreditDebitRequ
est" enabled="true">
<parameter name="TerminalID" ref="TerminalID"/>
<Parameter name="RequestType" value="REFUND"/>
</AuthRequest>
<AuthRequest key="VOID_TENDER"
class="dtv.tenderauth.impl.eftlink.request.EftLinkCreditDebitRequ
est" enabled="true">
<parameter name="TerminalID" ref="TerminalID"/>
<parameter name="RequestType" value="REVERSAL"/>
</AuthRequest>
<AuthRequest key="VOID_REFUND_TENDER"
class="dtv.tenderauth.impl.eftlink.request.EftLinkCreditDebitRequ
est" enabled="true">
<parameter name="TerminalID" ref="TerminalID"/>

EFTLink B-5
SysConfig.xml

<parameter name="RequestType" value="REVERSAL"/>

</AuthRequest>
</AuthRequestMap>

SysConfig.xml
This section describes EFTLink SysConfig settings.
Table B-1 SysConfig.xml

Default
Setting Value Valid Values Description

EFTLink--- NA True/False If set to true, this setting enables the

SavePaymentCards Save payment cards for future use
ForFutureUse feature. Xstore adds an additional
checkbox to the Contact Information Tab,
which can be checked if the customer
wishes to give consent to save his/her
payment card details. It also controls the
availability of the tender option Saved
Payment Card and Xstore's ability to save
the payment card details to the database.

EFTLink--- NA True/False If set to true, Xstore will show a prompt

EnablePaymentDev instructing the user to scan the QR code
iceScan on a PED (pin entry device) to initate the
use of the PED during an EFTLink
payment.

EFTLink--- NA True/False When set to true, Xstore will prompt the

AllowGiftCardOrE user to scan the eVoucher or gift card.
VoucherScan

Processing Overview
1. At tendering, Xstore Point of Service sends an authorization request for the amount
tendered to EFTLink.
2. Xstore Point of Service effectively goes into a listening state waiting for relevant
responses from the EFTLink system.
3. EFTLink sends a request for payment to the payment service provider (PSP).
4. The PSP prompts the customer to swipe their credit/debit card on the PIN Entry
Device (PED).
5. The customer swipes the credit/debit card:
- If the card swipe cannot be read by the PED, then the customer is prompted to
key in the credit card number and expiration date.
- If the card being used requires a PIN, then the PSP will prompt the customer for
the PIN number on the PED.
6. Response from the PSP:

B-6 Technical Guide

 Processing Overview

- If an approval is sent from the PSP, an approval will be sent back to Xstore Point
of Service from EFTLink for the amount authorized (partial payment is allowed
for Debit and Credit).

Note: If approval is sent for an amount less than the requested

amount, Xstore Point of Service will prompt for another form of
payment for the remaining balance.

- If a decline is sent from the PSP, the decline will be sent back to Xstore Point of
Service from EFTLink. In Xstore Point of Service the tender is declined and
Xstore Point of Service will prompt for another form of tender.
- If a call center message is sent from the PSP, a call center message is displayed on
the PED to call for verification and to enter an approval code:
* If an approval code is provided, the approval code is entered on the PED
and the approval is sent back to Xstore Point of Service from EFTLink for the
amount tendered.
* If no approval code is provided, then the tender is declined by the PSP and
the decline is sent back to Xstore Point of Service from EFTLink.
7. If EFTLink times out, EFTLink returns the failure to Xstore Point of Service and
displays the appropriate message.
8. Once the tender is approved, the merchant and customer copy of the Credit/Debit
card receipt prints.

EFTLink B-7
Processing Overview

B-8 Technical Guide

 C
Address, Email and Phone Number
Verification

Overview
This chapter contains technical details for the Xstore integration with QAS services,
including Address Verification (REST and SOAP), Email Verification and Phone Number
verification.
Implementation details for each QAS functionality are described below.
Xadmin offers the following features:
• Experian Address Verification (Manual) - for the SOAP version
• Experian Address Verification (Auto) - for the REST version
• Experian Email Address Verification
• Experian Phone Number Verification

Config Paths
For more information about the config paths, see Appendix D: “Xstore Point of Service
Configuration Path”.

Experian Address Verification (Manual)

This section describes the configurations for the Experian Address Verification (Manual).

Enable/Disable the Address Lookup Function Globally

"Address Verification" and "Experian Address Verification
(Manual)" is added with "Experian Address Verification" depending on
"Address Verification". Add the following insert statements to xcenter-
admin\src\main\SQL\data\xcenter_admin\dataupdate-all.sql:
INSERT
INTO cfg_base_feature (feature_id, description,
depends_on_feature_id, sort_order)
VALUES ('avs', 'Address Verification', null, 140);
INSERT
INTO cfg_base_feature (feature_id, description,
depends_on_feature_id, sort_order)

Address, Email and Phone Number Verification C-1

Experian Address Verification (Manual)

VALUES ('qas/addressmanual', 'Experian Address Verification

(Manual)', 'avs', 140);

Enable/Disable the Address Lookup Function By Individual Country

The Address lookup availability by country is configured by the System Integrator in
config/qas/addressmanual/StoreLocationsAvailable.xml. A boolean attribute is added to
the Country element.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<!-- This file is used for the customer to set the store
locations(countries) available -->
<LocationList>
<Region id="America">
<Country code="US" name="_countryUS"
addressVerificationEnabled="true"/>
<Country code="CA" name="_countryCA"
addressVerificationEnabled="true" />
<Country code="MX" name="_countryMX"
addressVerificationEnabled="true" />
<Country code="BR" name="_countryBR"
addressVerificationEnabled="true" />
</Region>
<Region id="Asia-Pacific">
</Region>
<Region id="Africa" />
<Region id="Europe">
<Country code="DE" name="_countryDE"
addressVerificationEnabled="true"/>
<Country code="FR" name="_countryFR"
addressVerificationEnabled="true" />
<Country code="GB" name="_countryGB"
addressVerificationEnabled="true" />
<Country code="ES" name="_countryES"
addressVerificationEnabled="true" />
<Country code="NL" name="_countryNL"
addressVerificationEnabled="true" />
<Country code="IT" name="_countryIT"
addressVerificationEnabled="true" />
<Country code="PT" name="_countryPT"
addressVerificationEnabled="true" />
<Country code="SE" name="_countrySE"
addressVerificationEnabled="true" />
</Region>

C-2 Technical Guide

 Experian Address Verification (Manual)

</LocationList>

Note: This parameter is not available for distribution from Xadmin/

Xstore Office.

Setup and Maintain username/password

While QAS supports username/password in the SOAP API for backward compatibility,
in new implementations the preferred approach is to use a token for authentication. Due
to protocol considerations, the token approach can be used in both SOAP and REST. The
current approach is to use the token with no provision to support username/password.
In production all web services run with a secure protocol (https) and have some
additional authentication such as username/password or, as in the case of QAS, a token.
The user needs to provide the authentication values for encryption at installation time.
The installer stores the value in a system.properties file.

Note: This parameter is not available for distribution from Xadmin/

Xstore Office.

Indicating Web Service End Point to be Used

QAS provides three web service end points which support different geographical areas:
• ws - EMEA
• ws2 - North America
• ws3 - APAC
The user needs to provide the end point values at installation time. The installer stores
the value in the ServiceHandlers.xml file.

Note: This parameter is not available for distribution from Xadmin/

Xstore Office.

Parametrize the (Address Search) Field Prompts

Any text that appears in the Xstore UI must be localized. The standard Java approach to
localization is to add localized text to property bundle files where there is one bundle file
per language. The bundle files are built during development and distributed with the
implementer release, product release or patch.
For many countries a QAS web service will provide prompt suggestions; however, these
suggestions are not localized. Therefore, localized text are provided. For example, the
following is added to the avs version of the translations.properties file:
_usAddressLineLabelTag=Enter street address, zip code.
_caAddressLineLabelTag=Enter building number or name, postal
code.
_gbAddressLineLabelTag=Enter building number or name, postcode.
_frAddressLineLabelTag=Enter address number and street name,
postal code.
_deAddressLineLabelTag=Enter address number and street name,
postal code.

Address, Email and Phone Number Verification C-3

Experian Address Verification (Manual)

_esAddressLineLabelTag=Enter street name and number, postal code.

_nlAddressLineLabelTag=Enter street name and number, postal code.
_itAddressLineLabelTag=Enter street name and number, postal code.
_mxAddressLineLabelTag=Enter street name and number, postal code.
_brAddressLineLabelTag=Enter street name and number, postal code.
_ptAddressLineLabelTag=Enter street name and number, postal code.
_seAddressLineLabelTag=Enter street name and number, postal code.
Additional entries for each supported country are added. Then the standard translation
process adds each entry to the supported language bundles.
There will be prompts for the search refinement in the bundle:
_streetNumberNeeded=Enter the street number.
_premiseNumberNeeded=Enter an apartment or suite number.
_unspecifiedValueNeeded=Enter value in the expected range.

Note: This parameter is not available for distribution from Xadmin/

Xstore Office.

QAS Engine Properties and Country Code Conversion

Engine Properties
There are a number of QAS search engine properties that either select the engine or
influence the way the selected engine behaves:
1. QasEngineTimeout (timeout) - The amount of time the search has to perform the
search
2. QasResponseLimit (threshold) - The maximum number of search results to return
3. Engine value(value) - This feature supports two different search engines:
Singleline and Verification; few countries, such as Great Britain work best with the
Singleline engine; all other countries should use the Verification engine.
The first two are independent of the country selected and are stored in a
ServiceHandlers.xml file. The engine value is country dependent and is covered in the
next section.

Country Code Conversion, Engine Type and Address Layout Adapters

The base version of this XML resides in /config/qas/addressmanual/spring/
countryconfig-qas.xml.
Xstore uses the two character (ISO) country code set; QAS (for the most part) uses the
three character (UN/ISO) country code set. A configurable conversion mechanism has
been provided in form a of spring loaded class. Any number of these classes can be
configured in one or more Spring files and they are used by the Address Verification
feature. The Spring configuration is as follows:
The QASCountryConversionBean class was moved from
oracle.retail.avs.qas.impl to the oracle.retail.avs.qas.soap.impl
package.

C-4 Technical Guide

 Experian Address Verification (Manual)

<bean id="usaQasCountryConversion"
class="oracle.retail.avs.qas.soap.impl.QASCountryConversionBean"
init-method="init">
<property name="countryUNCode" value="USA" />
<property name="countryISOCode" value="US" />
<property name="engineType" value="Verification" />
<property name="addressLinesToLocaleAdapter"
ref="usaAddressLinesAdapter" />
<property name="stateNameToCodeEnum" value="NoReplacement" />
</bean>
There are three additional properties:
1. engineType - This value must contain either "Verification" or "Singleline", which
indicates which engine type is associated with a country. Product values are
"Verification", "Singleline", and "MexVerification".
2. addressLinesToLocaleAdapter - This is a reference to another spring bean.
This bean is responsible for converting a QAS address layout into an
IPartyLocaleInformation (Xstore address) object.
3. stateNameToCodeEnum - This refers to type of state code processing that should
be performed. This will be covered in the next section.
Experain/QAS provides addresses in the form of a series of text lines that contain the
equivalent of address lines, city, state, country, and so on. These lines can be identified by
a label value or by the their position in the list. Customers can request their own specific
layouts. It is possible that customers will have specific address layout requirements for
specific countries. The addressLinesToLocaleAdapter supports the current lack of
a standard layout and possible future customer extension requirements. It also supports
the fact that the "Database Layout" actually turns one of two formats, depending on the
country data set.
Following are examples of the two addressLinesToLocaleAdapter spring bean
definitions available for the "Database Layout":
The DatabaseLayoutToLocaleAdapter class was moved from
oracle.retail.avs.qas.impl.format to
oracle.retail.avs.qas.soap.impl.format package
<bean id="nldAddressLinesAdapter"
class="oracle.retail.avs.qas.soap.impl.format.DatabaseLayoutToLoc
aleAdapter">
<property name="layout" value="Database Layout" />
<property name="cityLabel" value="NEN town/city" />
<property name="stateLabel" value="Province" />
<property name="postalCodeLabel" value="Postcode" />
</bean>

<bean id="altAddressLinesAdapter"
class="oracle.retail.avs.qas.soap.impl.format.AltDatabaseLayoutLa
youtToLocaleAdapter">

Address, Email and Phone Number Verification C-5

Experian Address Verification (Manual)

<property name="layout" value="Database Layout" />

<property name="addressLine1Label" value="Delivery address line
1" />
<property name="addressLine2Label" value="Delivery address line
2" />
<property name="addressLine3Label" value="Delivery address line
3" />
</bean>
The DatabaseLayoutToLocaleAdapter class expects the address lines to have
labels for city, state and postal code; the street address lines must be inferred from their
position in the list.
The AltDatabaseLayoutLayoutToLocaleAdapter class expects the address lines
to have labels for address line 1, 2 and 3; the city, state and postal code must be inferred
from their position in the list.
The Address Layout adapters implement
oracle.retail.avs.qas.soap.IAddressLinesToLocaleAdapter which
defines two methods:
Table C-1 Address Layout Adapters - Methodes

Methode Name Parameters Return

adapt List<AddressLineType> - a list of IPartyLocaleIn

address text and associated label formation
IAddressVerificationRequest - the
request that retrieved the lines
IDataServices - used to instantiate the
IPartyLocaleInformation object

getLayout String
containing the
name of the
layout

An Address Layout adapter can extend

oracle.retail.avs.qas.soap.AbstractLocaleAdapter, which provides the
following properties:
The AbstractLocaleAdapter class was moved from oracle.retail.avs.qas to
oracle.retail.avs.qas.soap package.
layout
addressLine1Label
addressLine2Label
addressLine3Label
addressLine4Label
cityLabel
stateLabel
postalCodeLabel

C-6 Technical Guide

 Experian Address Verification (Manual)

State Name to State Code Conversion

The base version of this XLM resides in /config/qas/addressmanual/spring/statecodes-
qas.xml.
Most countries have an equivalent of a US state: province, department, county and so on.
The Xstore requires the "state" to be the 1 to 2 character ISO 3166-2 code. QAS returns
this code for the US, Canada, Italy and Brazil. For 6 of the 8 other supported countries,
QAS returns the state name or some other code. Sweden does not return the state
(county) and Great Brittan returns the state (county) sometimes and sometimes not.
For those countries that return a name or other code the application maps the name/code
to the ISO 3166-2 code. There are three types of mapping, which is controlled by the
"stateNameToCodeEnum" property in the CountryConversionBean Spring bean
definiton (see above). The valid values for this property are:
Table C-2 Address Layout Adapters - Methods

Property Value Parameters

NoReplacement QAS returns the ISO 3166-2 code; the feature performs no
replacement.

PartialReplaceme QAS returns the ISO 3166-2 code in some cases. The feature attempts
nt to map the QAS value; if not found, it uses the QAS value.

CompleteRepaceme QAS returns values, none of which are the ISO 3166-2 code. The
nt application expects to map all values; if not found, the feature logs a
warning and returns null value in the state field.

There must be a QASStateNameConversionBean configured for each country that has

a "stateNameToCodeEnum" value of either PartialReplacement or
CompleteRepacement. The XML for the state name to state code for Germany (note
"countryISOCode" is "DE"), for example, is as follows:
The QASStateNameConversionBean class was moved from
oracle.retail.avs.qas.impl to oracle.retail.avs.qas.soap.imp package
<bean id="deuQasStateNameConversion"
class="oracle.retail.avs.qas.soap.impl.QASStateNameConversionBean
">
<property name="countryISOCode" value="DE" />
<property name="nameToCodeMap">
<map>
<entry key="Brandenburg" value="BB"/>
<entry key="Berlin" value="BE"/>
<!-- &#252; = Small Letter U with diaeresis -->
<entry key="Baden-W&#252;rttemberg" value="BW"/>
<entry key="Bayern" value="BY"/>
<entry key="Bremen" value="HB"/>
<entry key="Hessen" value="HE"/>
<entry key="Hamburg" value="HH"/>
<entry key="Niedersachsen" value="NI"/>

Address, Email and Phone Number Verification C-7

Experian Address Verification (Manual)

<entry key="Mecklenburg-Vorpommern" value="MV"/>

<entry key="Nordrhein-Westfalen" value="NW"/>
<entry key="Rheinland-Pfalz" value="RP"/>
<entry key="Schleswig-Holstein" value="SH"/>
<entry key="Saarland" value="SL"/>
<entry key="Sachsen" value="SN"/>
<entry key="Sachsen-Anhalt" value="ST"/>
<!-- &#252; = Small Letter U with diaeresis -->
<entry key="Th&#252;ringen" value="TH"/>
</map>
</property>
</bean>
Note the key values that contain "&#252;" (Baden-W&#252;rttemberg and
Th&#252;ringen). The "&#252;" is a character entity reference for the non-English
language character "ü". The actual value returned by QAS is Baden-Württemberg, but
this is the propose Xstore standard for accented characters in XML.
Below find web sites that can be used to determine which values should be:
• A chart listing character entity references
https://en.wikipedia.org/wiki/
List_of_XML_and_HTML_character_entity_references
• An online utility that converts between characters and references
http://coderstoolbox.net/string/#!encoding=xml&action=encode&charset=us_ascii

system.properties - Experian Address Verification (Manual)

This section describes Experian Address Verification (Manual) system properties
settings.
Table C-3 system.properties - Experian Address Verification (Manual)

Setting Valid Values Description

dtv.config.path. :avs:qas Defines the locations of the generic

-425 application Address Verification
configuration files and the locations of
QAS specific Address Verification
configuration files

oracle.retail.xs alphanumeric not used in Experian/QAS

tore.avs.user

oracle.retail.xs alphanumeric The encrypted Experian/QAS token

tore.avs.passwor
d

oracle.retail.xs alphanumeric The WSDL location URL

tore.avs.WsdlLoc
ation

oracle.retail.xs numeric The connection timeout

tore.avs.Service
Timeout

C-8 Technical Guide

 Experian Address Verification (Auto)

Experian Address Verification (Auto)

This section contains configurations for the Experian Address Verification (Auto)
functionality.

Mobile Configuration
The type-ahead feature is available for mobile devices. This function must be configured
in the FieldDefinitionConfig.xml file as shown below:
<Field name="addressLine" type="Search" resource="addressLine" >
<Parameter name="SearchType" value="ADDRESS_LOOKUP" />
</Field>
The search is triggered immediately each time the user types a single character in the
address lookup view.

Note: The "Addres lookup" action, used on the desktop version, is no

longer needed. The type-ahead feature is not available for desktop
versions.

The configuration file for mobile devices is located in the following directory /config/
config/mobile/forms/ADDRESS_LOOKUP.xml.

Alternative Layout Configuration

For some countries, like Mexico and Brazil, it is required to have the street name and the
street number in separated field. This can be configured by including the country code in
the alternativeAddressLayoutCountries property list in the service handler
configuration bean defined in the /config/qas/addressauto/spring/services-qas-
address.xml file.
For example, by default MX and BR are included:
<bean id="GET_ADDRESS"
class="oracle.retail.avs.qas.address.impl.format.QASFormatAddress
ServiceHandler" >
<property name="serviceConfigHelper"
ref="serviceConfigHelper" />
<property name="serviceId" value="ADDRESS_VERIFICATION" />
<property name="servicePath" value="/address/format/v1" />
<property name="exceptionHandler"
ref="standardJaxRsExceptionHandler" />
<property name="authToken"
value="#{systemProperties['oracle.retail.xstore.avs.qas.address.t
oken']}" />
<property name="alternativeAddressLayoutCountries" >
<list value-type="java.lang.String">
<value>MX</value>
<value>BR</value>
</list>

Address, Email and Phone Number Verification C-9

Experian Address Verification (Auto)

</property>
<property name="timeoutSeconds" value="5" />
<property name="statesCountryMap" ref="qasStateCountryMap" />
</bean>

States Mapping Beans

Since QAS services are not using the same state codes as Xstore (Xstore is using the ISO
3166-2), it is necessary to create a special state mapping for each country, in order to map
the QAS subdivision code (or descriptions) to the Xstore states code (found in states.dat
or in the DB).
The states mapping beans are placed in the spring file: /config/config/qas/addressauto/
spring/statecodes-qas-address.xml.
Follow the steps below:
1. Create a new bean of type
org.springframework.beans.factory.config.MapFactoryBean, and set
the sourceMap property with the states mapping information. In the key field you
must set the QAS states code and in the value field set the Xstore state code (found in
the state.dat or DB).
For example, if we want to add the Argentinean states: Buenos Aires and Las
Pampas. Map the Xstore states codes ARC and ARL with the QAS codes "Ciudad de
Buenos Aires" for ARC and, "Pampas" for ARL. Create the new bean (called
arQasStateNameMap) as follows:
<bean id="arQasStateNameMap"
class="org.springframework.beans.factory.config.MapFactoryBean
">
<property name="sourceMap">
<map
<entry key="Ciudad de Buenos Aires"
value="ARC"/>
<entry key="Pampas"
value="ARL"/>
</map>
</property>
</bean>
2. In the qasStateCountryMap (same spring file than above) add an entry for the
new mapping bean, using the ISO country code (two characters) for the keymap. For
example:
<bean id="qasStateCountryMap"
class="org.springframework.beans.factory.config.MapFactoryBean
">
<property name="sourceMap">
<map>
<entry key="AT" value-ref="atQasStateNameMap" />

C-10 Technical Guide

 Experian Address Verification (Auto)

<entry key="AR" value-ref="arQasStateNameMap" /> <!--

New entry added for Argentina! -->
<entry key="AU" value-ref="auQasStateNameMap" />
<entry key="BE" value-ref="beQasStateNameMap" />
<entry key="BR" value-ref="brQasStateNameMap" />
<entry key="CH" value-ref="chQasStateNameMap" />
<entry key="CL" value-ref="clQasStateNameMap" />
<entry key="CN" value-ref="cnQasStateNameMap" />
<entry key="DE" value-ref="deQasStateNameMap" />
<entry key="ES" value-ref="esQasStateNameMap" />
<entry key="FR" value-ref="frQasStateNameMap" />
<entry key="IE" value-ref="ieQasStateNameMap" />
<entry key="IN" value-ref="inQasStateNameMap" />
<entry key="IT" value-ref="itQasStateNameMap" />
<entry key="JP" value-ref="jpQasStateNameMap" />
<entry key="MX" value-ref="mxQasStateNameMap" />
<entry key="NL" value-ref="nlQasStateNameMap" />
<entry key="NZ" value-ref="nzQasStateNameMap" />
<entry key="PT" value-ref="ptQasStateNameMap" />
<entry key="PL" value-ref="plQasStateNameMap" />
<entry key="SE" value-ref="seQasStateNameMap" />
<entry key="ZA" value-ref="zaQasStateNameMap" />
</map>
</property>
</bean>

Adding A New Country

To enable a new country for address verification auto you must follow these steps:
1. Add the corresponding entry in the /config/config/qas/addressauto/
StoreLocationsAvailable.xml. For example, if you want to add Argentina, you
should add this entry in the American region, make sure the
addressVerificationEnabled property is set to true:
<Country code="AR" name="_countryAR"
addressVerificationEnabled="true" />
2. In some cases it is necessary to add the states (or subdivision) bean mapping. Allow
the Address Lookup function to be enabled/disabled by individual country.
<?xml version="1.0" encoding="UTF-8"?>
<!-- This file is used for the customer to set the store
locations(countries) available -->
<LocationList>

Address, Email and Phone Number Verification C-11

Experian Address Verification (Auto)

<Region id="America">
<Country code="US" name="_countryUS"
addressVerificationEnabled="true"/>
<Country code="CA" name="_countryCA"
addressVerificationEnabled="true" />
<Country code="MX" name="_countryMX"
addressVerificationEnabled="true" />
<Country code="BR" name="_countryBR"
addressVerificationEnabled="true" />
</Region>
<Region id="Asia-Pacific">
</Region>
<Region id="Africa" />
<Region id="Europe">
<Country code="DE" name="_countryDE"
addressVerificationEnabled="true"/>
<Country code="FR" name="_countryFR"
addressVerificationEnabled="true" />
<Country code="GB" name="_countryGB"
addressVerificationEnabled="true" />
<Country code="ES" name="_countryES"
addressVerificationEnabled="true" />
<Country code="NL" name="_countryNL"
addressVerificationEnabled="true" />
<Country code="IT" name="_countryIT"
addressVerificationEnabled="true" />
<Country code="PT" name="_countryPT"
addressVerificationEnabled="true" />
<Country code="SE" name="_countrySE"
addressVerificationEnabled="true" />
</Region>
</LocationList>

system.properties - Experian Address Verification (Auto)

This section describes Experian Address Verification (Auto) system properties settings.
Table C-4 system.properties - Experian Address Verification (Auto)

Setting Valid Values Description

xstore.config.pa :quas/ Defines the locations of the generic

th.base.features addressauto application Address Verification
configuration files and the locations of
QAS specific Address Verification
configuration files

C-12 Technical Guide

 Experian Email Address Verification

Table C-4 system.properties - Experian Address Verification (Auto)

Setting Valid Values Description

oracle.retail.xs alphanumeric Experian/QAS authentication token used

tore.avs.qas.add to consume the Address verification WS
ress.token

oracle.retail.xs alphanumeric Experian/QAS target URL

tore.avs.address
.TargetUri

Experian Email Address Verification

This section describes the Experian Email Address Verification.

Adding the QAS Email Validation

For the email validation the framework validation approach is used, which means, the
factory validation bean should be injected in the model. Once determined, add a new
entry (only if not already available), for the email field in the Model Field Validators
bean. Then use the standard email validator bean, called
emailAddressFieldValidator, to validate the email address field.
For example, if we want to validate an email field called "emailAddressUser", you
need to create an entry to validate it in the corresponding validators beans (the one used
in a factory which is injected into the model), as shown in the example below:
<bean id="emailAddressModelFieldValidators"
class="org.springframework.beans.factory.config.MapFactoryBean"
scope="prototype">
<property name="sourceMap">
<map>
<entry key="emailAddressUser" value-
ref="emailAddressFieldValidator" />
</map>
</property>
</bean>
Using the configuration above the QAS validation will be triggered when the QAS email
validation is enabled, since the standard email validator bean
"emailAddressFieldValidator" is overriden in the qas/email path in the spring
file:
Example:
/config/config/qas/email/spring/editmodels-qas-email.xml
<bean id="emailAddressFieldValidator"
class="oracle.retail.xstore.avs.email.validators.AVSEmailAddressF
ieldValidator" scope="prototype" />
In the validator class AVSEmailAddressFieldValidator, the necessary code to
invoke the AVS validation services (independent of the provider) was implemented,
which in this case is the QAS provider.

Address, Email and Phone Number Verification C-13

Experian Email Address Verification

Web Service Configuration

The service configuration with the service ID "VALIDATE_EMAIL" is located in /config/
config/qas/email/spring/services-qas-email.xml.
Example:
<bean id="VALIDATE_EMAIL"
class="oracle.retail.avs.qas.email.impl.QASEmailValidationService
Handler" scope="prototype">
<property name="serviceConfigHelper"
ref="serviceConfigHelper" />
<property name="serviceId" value="EMAIL_VALIDATION" />
<property name="servicePath" value="/email/validation/v1" />
<property name="exceptionHandler"
ref="standardJaxRsExceptionHandler" />
<property name="authToken"
value="#{systemProperties['oracle.retail.xstore.avs.qas.email.tok
en']}" />
<property name="timeoutSeconds" value="5" />
<property name="standardBasicAuth" value="false" />
</bean>
The service handler name "EMAIL_VALIDATION" can be found in the file: config/
config/avs/ServiceHandlers.xml.
Example:
<Service name="EMAIL_VALIDATION">
<Parameters dtype="Map">
<TargetUri
dtype="String">${oracle.retail.xstore.avs.email.TargetUri}</
TargetUri>
<ReadTimeout dtype="Integer">30</ReadTimeout>
<ConnectTimeout dtype="Integer">90</ConnectTimeout>
</Parameters>
</Service>

SysConfig.xml Settings - Experian Email Address Verification

AVS---EmailValidation—Timeout
The maximum time you are prepared to wait for a response, expressed in seconds.
Acceptable values are 2-15. If a timeout occurs, an HTTP status code of 408 - Request
Timeout will be returned. This parameter is sent as a header in the request to QAS.

C-14 Technical Guide

 Experian Phone Number Verification

system.properties - Experian Email Address Verification

This section describes Experian Email Address Verification system properties settings.
Table C-5 system.properties - Experian Email Address Verification

Setting Valid Values Description

xstore.config.pa :qas/email Defines the locations of the generic

th.base.features application Email Verification
configuration files and the locations of
QAS specific Email Verification
configuration files

oracle.retail.xs alphanumeric Experian/QAS authentication token used

tore.avs.qas.ema to consume the Email verification WS
il.token

oracle.retail.xs alphanumeric Experian/QAS email verification target

tore.avs.email.T URL
argetUri

Experian Phone Number Verification

This section describes the configuration for the Experian Phone Number Verification.

Adding the QAS Phone Validation

For the phone validation the framework validation approach is used, which means, the
factory validation bean should be injected in the model. Once determined, add a new
entry (only if not already available), for the phone field in the Model Field Validators
bean. Then use the standard phone validator bean, called phoneFieldValidator, to
validate phone number field. For example, if we want to validate the phone field called
"telephone", create an entry to validate it in the corresponding validators beans (the one
used in a factory which is injected into the model), as is shown in the example below:
<bean id="nfeMaintModelFieldValidators"
class="org.springframework.beans.factory.config.MapFactoryBean"
scope="prototype">
<property name="sourceMap">
<map>
<entry key="telephone" value-ref="phoneFieldValidator" />
</map>
</property>
</bean>
Using the configuration above the phone QAS validation will be triggered when the
QAS phone validation is enabled, since the standard email validator bean
"phoneFieldValidator" is overridden in the qas/phone path in the spring file:
/config/config/qas/phone/spring/editmodels-qas-phone.xml, it look like:
<bean id="phoneFieldValidator"
class="oracle.retail.xstore.avs.phone.validators.AVSTelephoneFiel
dValidator" scope="prototype" />

Address, Email and Phone Number Verification C-15

Experian Phone Number Verification

In the validator class AVSTelephoneFieldValidator, the necessary code to invoke

the AVS validation services (independent of the provider), which in this case is the QAS
provider, has been implemented.

Web Service Configuration

The service configuration is located in /config/config/qas/phone/spring/services-qas-
phone.xml, with the service ID "VALIDATE_TELEPHONE".
Example:
<bean id="VALIDATE_TELEPHONE"
class="oracle.retail.avs.qas.phone.impl.QASTelephoneValidationSer
viceHandler" scope="prototype">
<property name="serviceConfigHelper" ref="serviceConfigHelper"
/>
<property name="serviceId" value="TELEPHONE_VALIDATION" />
<property name="servicePath" value="/phone/validation/v2" />
<property name="exceptionHandler"
ref="standardJaxRsExceptionHandler" />
<property name="authToken"
value="#{systemProperties['oracle.retail.xstore.avs.qas.phone.tok
en']}" />
<property name="timeoutSeconds" value="5" />
<property name="standardBasicAuth" value="false" />
</bean>
The service handler name is "TELEPHONE_VALIDATION", it can be found in the file:
config/config/avs/ServiceHandlers.xml.
Example:
<Service name="TELEPHONE_VALIDATION">
<Parameters dtype="Map">
<TargetUri
dtype="String">${oracle.retail.xstore.avs.phone.TargetUri}</
TargetUri>
<ReadTimeout dtype="Integer">30</ReadTimeout>
<ConnectTimeout dtype="Integer">90</ConnectTimeout>
</Parameters>
</Service>

SysConfig.xml Settings - Experian Phone Number Verification

AVS---TelephoneValidation---Timeout
The maximum time you are prepared to wait for a response, expressed in seconds.
Acceptable values are 2-15. If a timeout occurs, an HTTP status code of 408 - Request
Timeout will be returned. This parameter is sent as a header in the request to QAS.

C-16 Technical Guide

 Experian Phone Number Verification

system.properties - Experian Phone Number Verification

This section describes Experian Phone Number Verification system properties settings.
Table C-6 system.properties - Experian Phone Number Verification

Setting Valid Values Description

xstore.config.pa :qas/phone Defines the locations of the generic

th.base.features application Phone number Verification
configuration files and the locations of
QAS specific Phone Verification
configuration files.

oracle.retail.xs alphanumeric Experian/QAS authentication token used

tore.avs.qas.pho to consume the Phone verification WS
ne.token

oracle.retail.xs alphanumeric Experian/QAS phone verification target

tore.avs.phone.T URL
argetUri

Address, Email and Phone Number Verification C-17

Experian Phone Number Verification

C-18 Technical Guide

 D
Xstore Point of Service Configuration
Path

Overview
Xstore Point of Service can be configured to check Xstore Office for updates to its config
path and update configPath.properties accordingly for updates generated by the
Xstore Office Store Personalities feature. (Store Personalities identify a store based on
attributes that define the store and the store's config path). See the Xstore Office User
Guide for more information about the Xstore Office Store Personalities feature and
configuration paths.

Configuration Path Retrieval Process

An empty configPath.properties file is part of the POS overlay and can be found
in xstore/configPath.properties after the installation. When Xenvironment is
started for the first time after Xstore Point of Service is installed, the
configPath.properties file is copied to environment/res/data/
configPath.properties.
When Xenvironment is used to start Xstore POS or Xstore Mobile (including during
Xenvironment startup), Xenvironment will contact Xcenter to check for any updates to
the config path settings. If any changes are found, the file in environment/res/data
will be updated. Xenvironment will update copies of the file in xstore/
configPath.properties and xstore-mobile/configPath.properties.
Before retrieving updates, Xenvironment will read the values of
xstore.location.mobile.workstationId.range.start and
xstore.location.mobile.workstationId.range.end from xstore-
mobile/system_mobile.properties. This range will be forwarded to Xcenter to
retrieve settings for mobile registers in addition to the current register.
Retrieving updates to configPath.properties from Xcenter is enabled by default.
To disable the feature, the following setting can be added to the Xenvironment overlay in
version1/actions.properties:
chain.RETRIEVE_CONFIG_PATH.disabled=true
If set to true, Oracle Retail Xstore Point of Service will use its current values, for more
information, see the If Xcenter Is Not Used to Get the Config Path section.
Retrieving config path properties from Xcenter will overwrite any of the same-named
properties that already were present in the configPath.properties file.

Xstore Point of Service Configuration Path D-1

Xstore Office Config Path Properties Assembly

• For the desktop application, the global config path properties and the workstation
override property for the specific workstation the system represents are retrieved
from Xcenter and written to the configPath.properties file.
• For the Xstore Mobile server, the global config path properties and the workstation
override properties for the entire range of mobile device workstations are retrieved
from Xcenter and written to the configPath.properties file. The range of
mobile device workstation IDs is defined in the system.properties file using
the properties xstore.location.mobile.workstationId.range.start
and xstore.location.mobile.workstationId.range.end.

Xstore Office Config Path Properties Assembly

This section describes the assembly of the config path properties.

Global Configurations Path Properties

Global config path elements are configurations that are loaded once for the entire
application and do not differ from workstation to workstation. They define standard
features and functionality for instances of the application.
The global config path is made up by the elements of the GlobalConfigPathElement
enumeration. This enumeration contains both the individual global config element
definitions as well as the ability to build the currently applicable global config path.
• Every element defined in the GlobalConfigPathElement enum is considered to
be a global config path element, meaning it is not workstation-specific.
• The order of the enumeration instances dictates their relative priority in the config
path. This order is used for building the global config path. It is indicated in the
javadoc for the enum.
• The enum covers "version1" and "MASTER/DEFAULT".
• The enum instances BASE_FEATURES and GLOBAL_CONFIG_PATH_EXTENSIONS
point to properties in the configPath.properties file. The instances substitute
their values with the properties xstore.config.path.base.features and
xstore.config.path.global.extensions when building the global config
path. For more details about these properties, see the
xstore.config.path.global.extensions section and the
xstore.config.path.base.features section.
• GlobalConfigPathElement instances have the concept of applicability based on
the system property xstore.application.type. Any instance can specify an
application type as a restriction. The available application types are defined in
dtv.util.common.CommonConstants.ApplicationType. Instances which do
not specify an application type are considered to "always load."
* If an xstore.application.type system property is specified, the
GlobalConfigPathElement enum instances specifying the application
type are loaded as well.
* If no xstore.application.type system property is specified, only the
default enum instances, that is enum instances without application
restriction type, will be loaded.
• Form factor-specific config path elements, like handheld, tablet or thin client are
considered to be global elements, since they need to be loaded in a specific place
within the config path and the same configurations apply to all devices of a
particular form factor.

D-2 Technical Guide

 Xstore Office Config Path Properties Assembly

The table below contains all available base global config path elements. Each element
indicates the value of the xstore.application.type VM argument that must be
specified in order for the element to apply. The order in which they are listed, is the
order in which they appear in the config path. Elements with an application type
DEFAULT are always included in the config path.
Table D-1 Base Global Config Path Elements

xstore.application.
Type Config Path Entries type Description

Reference dtv/res/config DEFAULT The element that

Configurations contains the reference
configuration location
for all configurations
in the application.
Every possible config
file in the application
should exist in the
represented path.

Standard Base The value of the DEFAULT This element contains

Features xstore.config.pa standard application
th. features that can be
base.features turned on and off,
config path property, such as loyalty,
excluding form orders, different
factor-specific entries. authorization
processors, and so on.
This only includes
entries from the base
features property that
do not contain "/
$FORM_FACTOR".
For example, the base
feature paths for SIM
indicate :sim/sim/
$FORM_FACTOR; the
configurations in the
sim directory would
be included at this
point, but not the
configurations in the
sim/$FORM_FACTOR
directory.

Base base DEFAULT This is an

implementation/
global customization
level element that
puts a layer of
configuration right
above the defaults
and before anything
else (form factors,
countries, and so on)

Xstore Point of Service Configuration Path D-3

Xstore Office Config Path Properties Assembly

Table D-1 Base Global Config Path Elements

xstore.application.
Type Config Path Entries type Description

Data Loader dataloader DATA_LOADER This element

represents the
configurations to be
included when the
DataLoader
application is
running.

Data Purger purge DATA_PURGER This element

represents the
configurations to be
included when the
DataPurger
application is
running.

Transaction transreplicate TRANSACTION_REPL This element

Replication ICATOR represents the
configurations to be
included when the
Transaction
Replicator utility
application is
running.

Self Checkout Mode selfcheckout SELF_CHECKOUT This element

represents the special
configurations that
need to be included
when Xstore Point of
Service is running in
self-checkout mode,
as opposed to
running as normal
desktop version.

Mobile Overrides mobile MOBILE_SERVER This element

represents the
standard override
that is used for all
mobile devices. It is
included only for
mobile server
instances.

Handheld Mobile formfactor/ MOBILE_SERVER This element

Devices handheld represents
configuration
overrides that are
specific to mobile
handheld devices. It
is added to the config
path only on mobile
servers when the
form factor of the
device is handheld.

D-4 Technical Guide

 Xstore Office Config Path Properties Assembly

Table D-1 Base Global Config Path Elements

xstore.application.
Type Config Path Entries type Description

Tablet Mobile Devices formfactor/ MOBILE_SERVER This element

tablet represents
configuration
overrides that are
specific to mobile
tablet devices. It is
added to the config
path only on mobile
servers when the
device form factor of
the device is tablet.

Thin Client Mobile formfactor/ MOBILE_SERVER This element

Devices tablet:formfacto represents
r/thin configuration
overrides that are
specific to thin client
devices.
Note: This includes
all configurations for
the tablet form factor
along with a few
additions for the thin
client. This element is
added to the config
path.

Form Factor Base The value of the MOBILE_SERVER This element

Features xstore.config.pa represents things that
th. appear in the
base.features xstore.config.pa
config path property, th.
including only form base features
factor-specifc entries. property and contain
a placeholder for
substituting the
current form factor,
$FORM_FACTOR.
For example, the base
feature paths for SIM
indicate :sim/sim/
$FORM_FACTOR; the
configurations in the
sim directory would
not be included at this
point, but the
configurations in the
sim/$FORM_FACTOR
directory would be
included.

Xstore Point of Service Configuration Path D-5

Xstore Office Config Path Properties Assembly

Table D-1 Base Global Config Path Elements

xstore.application.
Type Config Path Entries type Description

Country Pack countrypack/ Default This element

Overrides ${dtv.location.C represents
ountryId} configuration
overrides that are
specific to a particular
country in which the
application is
running.
${dtv.location.C
ountryId} is a
reference to a VM
property indicating
the country in which
the application is
running.

Country Pack countrypack/ DEFAULT This element

Overrides for ${dtv.location.C represents a
Handheld Devices ountryId}/ specialization that is
handheld needed for defining
configuration
overrides for mobile
handheld devices that
are used to run the
application in a
particular country.
${dtv.location.C
ountryId} is a
reference to a VM
property that
indicates the country
in which the
application is
running.

Country Pack countrypack/ DEFAULT This element

Overrides for Mobile ${dtv.location.C represents a
Tablet Devices ountryId}/tablet specialization that is
needed for defining
configuration
overrides for mobile
tablet devices that are
used to run the
application in a
particular country.
${dtv.location.C
ountryId} is a
reference to a VM
property that
indicates the country
in which the
application is
running.

D-6 Technical Guide

 Xstore Office Config Path Properties Assembly

Table D-1 Base Global Config Path Elements

xstore.application.
Type Config Path Entries type Description

Country Pack countrypack/ DEFAULT This element

Overrides for Thin ${dtv.location.C represents a
Client Devices ountryId}/tablet specialization that is
countrypack/ needed for defining
${dtv.location.C configuration
ountryId}/thin overrides for mobile
thin client devices
that are used to run
the application in a
particular country.
${dtv.location.C
ountryId} is a
reference to a VM
property that
indicates the country
in which the
application is
running.

Customer Global version1 DEFAULT The standard global

Overrides override location for a
customer overlay in
which all
configuration
overrides that apply
to a retailer's entire
organization are
specified.

Xadmin Global MASTER/DEFAULT DEFAULT A special, reserved

Overrides config path element
that is used to extend
the global, static
config path by
allowing the addition
of config path entries
that may not exist in
base Xstore, but that a
retailer may want to
apply to their entire
organization as global
overrides.

Xstore Point of Service Configuration Path D-7

Xstore Office Config Path Properties Assembly

Table D-1 Base Global Config Path Elements

xstore.application.
Type Config Path Entries type Description

Overrides for a version1/patch DEFAULT A reserved config

Config Patch path element that is
used to include
changes that need to
be patched to address
issues in the
application. This is
the highest priority
config path and
anything that exists in
it always will take
precedence over
anything that is
defined at any other
level. That being said,
this only is to be used
for "emergency"
situations that require
such a significant
override in order to
address a critical
issue within the
application. It is not a
path where one
typically should
expect to see
configurations.

xstore.config.path.global.extensions
Config path global extensions indicate non-standard config directories that are applied
globally and are included in the config path between static retailer global overrides
(version1) and Xstore Office-controlled global overrides (MASTER/DEFAULT). The
config path global extensions are controlled by the
xstore.config.path.global.extensions property in the
configPath.properties file. Since the global extensions property is more of a
hidden feature, the property is not maintainable through Xstore Office and must be set
manually on any workstation that uses it.

xstore.config.path.base.features
Base features represent config path elements that are used to enable a certain
functionality or feature within the application, such as loyalty, a payment processor or
integration with external applications such as Customer Engagement, Order Broker, and
others.
The base features can be enabled and disabled through the Personality Maintenance
feature in Xstore Office. For more information on Personality Maintenance, see the Xstore
Office User guide.
The table below lists all Xstore Point of Service base features that can be enabled and
disabled as well as their corresponding config path entries. The enabled base features are

D-8 Technical Guide

 Xstore Office Config Path Properties Assembly

represented in the xstore.config.path.base.features property in the

configPath.properties file.
Table 4-1 Base Features and Config Path Entries

Feature Sub-Feature Config Path Entries

Loyalty NA :cust/loyalty

Loyalty Awards :cust/loyalty/award

Collect and Receive Service NA :rds:idcs/rds

Integration

Customer Engagement NA :relate

Gift Registry :cust/registry

Use Identity Provider for :idcs/relate

Authorization

Use Oracle Retail Promotions :promote

Engine

Order Broker (Cloud) NA :order:locate

Use Identity Provider for :idcs/locate

Authorization

Order Management System NA :crosschannelreturn:s

erenade

Use Identity Provider for :idcs/serenade

Authorization

Opera Guest Services NA :opera

Store Inventory Operations NA sim:sim/

Cloud Service (SIOCS) $FORM_FACTOR$:idcs/
sim

Retail Extension Module NA :rxm:rxm/

(RXM) $FORM_FACTOR$

Address Verification NA :avs

Experian AddressVerification :qas/addressmanual

(Manual)

Experian Phone Number :qas/phone

Verification

Experian Email Address :qas/email

Verification

Experian Address :qas/addressauto

Verification (Auto)

Xcommerce NA :xcommerce

Microsoft SQL Server NA :dtv/sql/mssql

Support

Xstore Point of Service Configuration Path D-9

Xstore Office Config Path Properties Assembly

Table 4-1 Base Features and Config Path Entries

Feature Sub-Feature Config Path Entries

EFTLink Authorizations NA :authprocessor/

eftlink

EFT Link Gift Cards :authprocessor/

eftlink/giftcard

Payment by Link Tenders :paybylink

24 x 7 (No Store Closing) NA :24x7

Functionality

Item Selection Grid (cannot NA :buttonmatrix

be used with Self Checkout)

Financial Daily Report NA :dailyreport

Invoice NA :invoice

Global Blue Tax Free (cannot :invoice/globalblue

be combined with Planet Tax
Free)

Panet Tax Free (cannot be :invoice/fintrax

combined with Global Blue
Tax Free)

Luxury receipts NA :luxuryreceipt

Taxed vouchers NA :vouchers

Enhanced Email Receipt NA :enhancedemail

Extension Store NA :extensionstore

Note: Xstore Mobile servers
running in a home store (that
is, an actual store location)
must not add this to their
config path).
For more information on
temporary store
configurations, see the
Temporary Store
Configuration chapter.

Vertex Tax Engine NA :vertex

Note: The Vertex Tax Engine
is currently only available for
the country pack USA and
Canada.

Vertex Tax Engine using the :vertex/oauth2

OAuth2 authentication

Workstation Overrides Config Path Properties

The elements for workstation-level configuration overrides are controlled by another
property, or a set of properties for mobile servers, in the configPath.properties
file. Since one of these properties indicates all of the override elements for a particular

D-10 Technical Guide

 Xstore Point of Service Config Path Assembly

workstation, each override path property name contains the workstation ID to which it
applies. The primary purpose of workstation overrides is to support profile group/
element pairs that are defined in Xstore Office as part of the profile maintenance. Profile
groups and elements are defined and associated with personalities, landscapes, and
store personalities in Xstore Office and then each register (or mobile server) in a store
downloads its own workstation override config path properties from Xcenter just prior
to startup.

xstore.config.path.workstation.overrides.X
The properties containing the workstation overrides config path are
xstore.config.path.workstation.overrides.X, where X is the workstation ID
to which the property applies. The workstation overrides property only contains the
profile group and element pairs that make up the landscape for a particular workstation.
The following configuration files support workstation-level overrides. All other
configurations will load files only from global config path elements.
• SysConfig.xml
• ActionConfig.xml
• OpChainConfig.xml
• MenuConfig.xml
• PromptConfig.xml
• DataFieldConfig.xml
• forms" directory-based configurations
• FieldLayoutConfig.xml
• FieldDefinitionConfig.xml
• FontConfig.xml
• ListViewConfig.xml
• ContextConfig.xml
• "componentPropertySet" directory-based configurations
• translations.properties

xstore.config.path.overrides.store.Y
The config path property, xstore.config.path.overrides.store.Y, where Y is the store
number, is created. This property contains the profile group and element pairs that make
up the personality for a particular store. The files that are located in any of the config
path entries defined in this property will be loaded at the global (application) level.

Xstore Point of Service Config Path Assembly

The default file Xstore Point of Service uses for its config path properties is called
configPath.properties. The file is located in the root directory on an installed
register. As mentioned in the section above, the following three properties form the
config path for a given register:
• xstore.config.path.global.extensions
• xstore.config.path.base.feature
• xstore.config.path.overrides.workstation.[workstation ID]

Xstore Point of Service Configuration Path D-11

Xstore Point of Service Config Path Assembly

A configPath.properties file for a traditional Xstore Point of Service desktop

system will have only one xstore.config.path.workstation.overrides
property and it will be for the workstation ID that is assigned to that system.
For an Xstore Mobile server, the configPath.properties file will contain
xstore.config.path.workstation.overrides properties for all of the mobile
devices in the store.
The sample below shows the configPath.properties file of the base Xstore Point of
Service application.
Sample: configPath.properties file
# The contents of this file determine the config path overrides.
It may be manually changed, but be aware that
# its contents also may be manually updated via calls to the
Xcenter application if the automatic config path
# updating from Xcenter is enabled (ideally this central
management via Xadmin would be enabled).

# Indicates non-standard config directories that are intended to

be applied globally and will be included
# in the config path between static retailer global overrides
(version1) and Xadmin-controlled global
# overrides (MASTER/DEFAULT).
xstore.config.path.global.extensions=

# Indicates standard Xstore features that are enabled by adding

certain config path entries
xstore.config.path.base.features=

# Workstation level overrides, primarily used for the inclusion

of profile group/element pairs that are
# maintained within the Xadmin application. The numnber at the end
indicates the workstation ID. There is no
# limit to the number of workstations that can be represented
here. These only are for an example of what
# the property names would be.
xstore.config.path.overrides.workstation.1=
xstore.config.path.overrides.workstation.2=
xstore.config.path.overrides.workstation.3=

If Xcenter Is Not Used to Get the Config Path

If retrieval of the config path from Xcenter is not being used, the config path is still
assembled in the same manner. The difference is that the
xstore.config.path.base.feature and the
xstore.config.path.overrides.workstation.[workstation ID]
properties are not retrieved from Xcenter.

D-12 Technical Guide

 Resource Bundle Path Consolidation

If Xstore Point of Service ever used Xcenter to obtain the config path, and the
configPath.properties file contains properties, those properties will continue to be
used, even if updating from Xcenter is turned off. They will no longer be updated from
Xcenter.

Resource Bundle Path Consolidation

Resource bundles are based on the config path instead of separate bundle-specific paths.
When upgrading to a new Xstore Point of Service version, move any resource bundle
files to a config path location or adjust the config path accordingly.
• Translations (was dtv.pos.i18n.translation)
• Phone numbers (was dtv.pos.i18n.phone)
• Hardware (was dtv.pos.i18n.hardware)
• Help (was dtv.pos.i18n.help)
• Email (was dtv.pos.i18n.email)
• Format display (was dtv.i18n.formatDisplay)

Xstore Point of Service Configuration Path D-13

Resource Bundle Path Consolidation

D-14 Technical Guide

 E
Xstore Point of Service Root Directories

Overview
A list of Xstore Point of Service’s root directories and a brief description of the files
contained within them is found in the Xstore Point of Service Directories List section
below.

Xstore Point of Service Directories List

Table E-1 below identifies many of the Xstore Point of Service directories and their
contents that may provide additional information for troubleshooting purposes.
Table E-1 Xstore Point of Service Directories

Directory Description

C:\xstore\config General config space, contains files read into the classpath.

C:\xstore\database Contains database SQL files.

C:\xstoredata\xstore Used by the nightly polling process. This is the directory

\download where Xstore Point of Service will look for files that were
downloaded from the polling server. All files will be
processed unless excluded in the readme.txt file.
The readme.txt file is the location where any file name
patterns for files that should not be processed during a
DataLoader run are declared. Wildcards are supported as "*".
Each exclusion must be on its own line: *.txt, *.bak, *.doc,
*.lst
This directory also contains the summary.ini properties file
that contains information pertaining to the files DataLoader
processes so that Xenvironment can process those results and
send them to Xstore Office.

C:\xstore\installx Installx places its log files here.

C:\xstore\lib Contains .jar files that Xstore Point of Service loads at

startup. These .jar files contain variables that are dependent
on the information contained in
c:\xstoredata\system.properties and/or
c:\xstoredata\root\system.properties.

C:\xstore\license Contains the Apache Open Source licenses files.

C:\xstore\linux Stores Java runtime and platform-specific libraries for Linux

(32-bit).

Xstore Point of Service Root Directories E-1

Xstore Point of Service Directories List

Table E-1 Xstore Point of Service Directories (continued)

Directory Description

C:\xstore\linux_64 Stores Java runtime and platform-specific libraries for Linux

(64-bit).

C:\xstore\log Xstore Point of Service log directory. The Xstore Point of

Service log files are written in this directory.

C:\xstore\res Stores resource information.

C:\xstore\root Stores infrequently-modified system.properties.

C:\xstore\sequence This directory has two folders that contain the sequence files
used in preflight checks: “active” for active Xstore Point of
Service mode and “train” for training mode. Upon startup
Xstore Point of Service checks a set of sequence files against
values located in the database. If values in these text files do
not match what is in the database, then it will throw a
preflight error, or fix the files automatically if configured to do
so.

C:\xstore\tmp This directory is used for temporary file processing. It

contains the .trn files that had problems persisting to the
database. If a transaction does not get accepted into the
database on the first insert/update, then the transaction will be
written to a .trn file. When in this directory, it will attempt to
be added to the database several times. Once completed,
depending on the result, it will be moved to either
c:\xstoredata\tmp\completed or
c:\xstoredata\tmp\failed.
Files used for the SAF queue are also created and managed in
this folder.
The xstore.anchor and .pid files are kept here:
xstore.anchor exists only while Xstore Point of Service is
running. This file monitors all of the wrapper-controlled
functions for deletion. Deleting this file will cause Xstore Point
of Service to exit gracefully.
PID (process ID) files are created for both the java process
(xstore.java.pid) and the wrapper process
(xstore.wrapper.pid) for each application that is started
using launcher. These files monitor the application for
abnormal exits and lock ups.
A .status file is created here for these processes as well.

C:\xstore\updates Contains the Xstore Point of Service properties files used by

Installx. If any changes are made to these files, Xstore Point of
Service must be stopped and the
c:\xstoredata\configure.bat must be run before the
changes will take effect. baseconfigure.bat also looks to
this folder.

C:\xstore\upload This directory is used by Xenvironment to build the polling

package.

C:\xstore\windows Stores Java runtime and platform-specific libraries for

Windows (32-bit).,

C:\xstore\windows Stores Java runtime and platform-specific libraries for

Windows (32-bit).,

E-2 Technical Guide

 Xstore Point of Service Mobile Directory

Table E-1 Xstore Point of Service Directories (continued)

Directory Description

C:\xstore\windows_64 Stores Java runtime and platform-specific libraries for

Windows (64-bit).,

C:\xstore\wrapper Contains the wrapper components and the configuration files

for the wrapper.

Xstore Point of Service Mobile Directory

The Xstore Point of Service Mobile install includes the following mobile directory:

Directory Description

c:\xstore-mobile1 Includes the mobile web application and associated

configuration files.

1./opt/xstore-mobile directory in Linux.

Xstore Point of Service Root Directories E-3

Xstore Point of Service Mobile Directory

E-4 Technical Guide

 F
Revision History

Version 23.0.0, Revision 03

Chapter Change

Chapter 25 - Order removed review comment

Broker Configuration

Version 23.0.0, Revision 02

Chapter Change

Chapter 47- Vertex Added info that Vertex integration can be configured to use both the
Integration Cloud and a local container.

Version 23.0.0, Revision 01

Chapter Change

Chapter 18 - Hardware/ added the following settings to the SysConfig Settings in the Xstore
UI Configuration Point of Service Self Checkout section:
• OpenClose---PrintSystemCycleReceipts
• AutoPlaySound---Enabled,
• AutoPlaySound---WaitSeconds,
• CheckSaleComplete---UseSaleCompleteForm,
• Receipts—AllowReceiptNoPrint,
added Audio Files section:
• added note for possible additional accessibility requirements
• Start Button section,
• added SCO Console,

Chapter 25 - Order updated SysConfig section

Broker Configurations

Chapter 26 - CaR added chapter

Configurations

Revision History F-1

Version 22.0, Revision 03

Chapter Change

Chapter 27 - OPERA removed dtv.datasource.opera.ConnectionString,

Property Management
removed 4. Verify that the encrypted user name and password are
Configuration
entered in the com_code_value table in the Xstore database.

Chapter 47- Vertex added chapter

Integration

Appendix D - Xstore added base features:

Point of Service
• Collect and Receive Service Integration,
Configuration Path
• Vertex Tax Engine and Vertex Tax Engine using OAuth2
authentication,
• Enhanced Email Receipt,
• Payment by Link Tenders,
• updated Store Inventory Operations Cloud Service SIOCS config
path;

Version 22.0, Revision 03

Chapter Change

Chapter 25 – Order moved AllowPartialUpdates setting from SysConfig to

Broker Configuration ServiceHandlers.xml

Version 22.0, Revision 02

Chapter Change

Chapter 17 – Return added note for MaxDaysAfterPurchase that override prompt will
Transaction occur
Configuration

Chapter 28 - Email Added Enhanced Email Receipt section

Customer Receipts

Version 22.0, Revision 01

Chapter Change

Chapter 18 - Hardware/ updated SCO Classic and SCO SysConfig settings

UI Configuration

Chapter 24 - Customer added Promote Deal Engine Integration section and changed
Engagement Cloud Promote Deal Engine to Oracle Retail Promotions Engine
Services Configuration

Appendix D - Xstore added base feature for the Oracle Retail Promotions Engine
Point of Service
Configuration Path

F-2 Technical Guide

 Version 21.0, Revision 02

Chapter Change

all chapters updated directories from xstore\ to xstoredata\xstore

Version 21.0, Revision 02

Chapter Change

Chapter 35 – Airside removed chapter from Technical Guide, moved to CA Technical

Sale Transaction Guide

Chapter 36 – Tax-Free removed chapter from Technical Guide, moved to CA Technical

Shopping Guide

Chapter 37 – Taxed removed chapter from Technical Guide, moved to CA Technical

Voucher Guide

Version 21.0, Revision 01

Chapter Change

all chapters SysConfig.xml settings removed:

Payroll---PayrollCalendar---
DisplayNumberOfPreviousWeekinReport, 11-5
Email---Receipt---BodyMimeType, 28-3
Email—DefaultMailHost 28-3
Email—DefaultMailPort 28-3
Email—DefaultSender 28-3
Email---UseSmtpAuth 28-3
MeasurementUnits---Length, 40-14
MeasurementUnits---Temperature
OnScreenKeyboard---KeyClickDuration
OnScreenKeyboard---KeyClickFrequency
OnScreenKeyboard---KeyClickVolume
OnScreenKeyboard---Layout
OnScreenKeyboard---Sliding
OnScreenKeyboard---SlidingEndBump
OnScreenKeyboard---SwipeDownToClose
OnScreenKeyboard---SwipeSideToSwitchLayout,18-10
LoginSecurity---UnlockUserRepeatInterval, 12-9
Loyalty---CustomerRecordRequired, 24-10

Hardware/UI Added SysConfig.xml setting SelfCheckout---

Configuration SupervisorOptionReturnToSCOSale, 18-13
added Touch-Screen Configuration Desktop and Thin Client section,
18-11
added notes for Thin Client and Desktop Configurations

Revision History F-3

Version 20.0.1, Revision 02

Chapter Change

Oracle Hospitality Changed base-xstore.properties to xstore.properties, 26-2

OPERA Property
Management
Configuration

Tax Free Shopping updated chapter

Temporary Store updated Temporary Store Mobile Server section, 47-2

Configuration

Transaction added chapter

Attachments

Configuration Files removed InstallX Process Description, A-7

Appendix: Personality • changed Experian Address Verification to Address Verificaiton

Maintenance and and added:
Config Paths
:qas/addressmanual
:qas/addressauto
:qas/email
:qas/phone

Appendix: Address, • added chapter

Email and Phone
Number Verification

Version 20.0.1, Revision 02

Chapter Change

Tax Free Shopping updated chapter

Xstore POS added new config path property, xstore.config.path.overrides.store.Y

Configuration Path

Version 20.0.1, Revision 01

Chapter Change

Tax Free updated chapter

Data Purger removed CIVC_INVOICE_REPORT from Table 42-5 CIVC Domain -

Tables Purged by Data Purger

Version 20.0, Revision 03

Chapter Change

all chapters lang updates

F-4 Technical Guide

 Version 20.0, Revision 02

Chapter Change

Order Management changed Serenade to Order Management System (OMS)

System

Version 20.0, Revision 02

Chapter Change

Appendix B - EFTLink Changed the EFTLink---EnableEftLinkGiftCardSupport to

EFTLink---EnableGiftCardSupportForEftLink.

Tender Configurations Removed the following settings:

CreditDebitTender---BINSmartLookup---
AuthMethodCode">XPAY_BINSMART_LOOKUP_MWHSE
CreditDebitTender---BINSmartLookup---Enabled
CreditDebitTender---BINSmartLookup---
PreferredDefaultOnError

Version 20.0, Revision 01

Chapter Change

Tax Configuration added Multiple VAT Taxation section

Discount Configuration added Deal Data for Multiple Stores section

Hardware/UI added Printer Selection section

Configuration

SSL Checks updated system.properties and added Spring Configuration

Airside Sale updated transaction properties

Transactions

Taxed Vouchers updated Overall Approach/Configuration section

Data Purger added loc_temp_store_request table

Xstore Mobile added SysConfig.xml setting Mobile---Enable OfflineMode

Configuration

Temporary Store added chapter

Configuration

Appendix EFT-Link added AuthConfig.xml and SysConfig.xml settings

Xstore POS added base feature Extension Store

Configuration Path

Revision History F-5

Version 19.0.1, Revision 01

Version 19.0.1, Revision 01

Chapter Change

Tax-Free Shopping Updated Country Requirement

Internationalization Updated LocaleMap.xml

Version 19.0, Revision 05

Chapter Change

Item Messaging Updated Item Messaging Database Setup section, changed itm_item
Configuration to itm_item_options

Version 19.0, Revision 04

Chapter Change

Menu & Tab Removed Weather Tab and added ui-beans.xml Spring File section
Configurations Chapter

Version 19.0, Revision 03

Chapter Change

Tax Free Chapter Updated Country Requirements Config in Spring Files

Version 19.0, Revision 02

Chapter Change

Context-Sensitive-Help Updated chapter

Chapter

Customer Account Updated chapter

Configuration Chapter

Order Broker Updated LocateVersion description.

Configuration

F-6 Technical Guide

 Version 19.0, Revision 01

Version 19.0, Revision 01

Chapter Change

Chapter 11 - Payroll, SysConfig.xml:

Timecard & Clock in/
removed 'Timecard—TimecardEntryRoundingMinutes
Out Configuration

Chapter 18 - Hardware/ added SysConfig.xml setting UserInterface---ColorTheme

UI Configuration

Chapter 25 - Order SysConfig.xml:

Broker
removed:
Order---DownloadInterval
Order---StatusRequestInterval
Order---CreateReceivingDocument
added:
Order---AutoPickInventoryUponAccept
Order---EnablePickListScanning

Chapter 35 - Airside Tax Free:

Stores Tax-Free
CreditNote Settings:
Transactions
• removed TaxFreeConfig---Sequence---CrediteNote---
ResetDay
• removed TaxFreeConfig---Sequence---CreditNote---
ResetMonth
Invoice Settings:
• removed TaxFreeConfig---Sequence---CrediteNote---
ResetDay
• removed TaxFreeConfig---Sequence---CreditNote---
ResetMonth
Added Resetting TaxFree Invoices section
Database Settings Global Blue::
• added TAXFREE_ACCESS_PTS
system.properties:
• added oracle.retail.xstore.taxfree.globalblue.host
• oracle.retail.xstore.taxfree.globalblue.pts.host
• oracle.retail.xstore.taxfree.fintrax.host
renamed chapter from Airside Stores Tax-Free Transactions to
Airside Sale Transactions and Tax-Free Sale Transactions
added civic_taxfree_counrty table content from Country Pack
Configuration chapter to Airside Sale Transaction and Tax-Free Sale
Transactions chapter

Chapter 36 - Country removed chapter - Country Pack Configurations moved to separate

Pack Configuration guide

Revision History F-7

Version 18.0.1, Revision 01

Chapter Change

Chapter 39 - Menu & SysConfig.xml:

Tab Configuration
removed Terminal---RegistrationHistoryDays
Added Item Selection Grid section

Chapter 45 - Xstore added chapter

Mobile Configurations

Appendix C - Xstore Added IDCS access config path settings for sim,serenade and locate.
Point of Service
Configuration Path

Chapter - Taxed Added chapter

Vouchers

Version 18.0.1, Revision 01

Chapter Change

Appendix C - Xstore Added IDCS access config path settings for CE.
Point of Service
Configuration Path

Version 18.0, Revision 05

Chapter Change

Chapter 33 - Update Updated Update Services Overview section

Services & File
Movement

Appendix B - EFTLink Updated config path for EFTLink

Version 18.0, Revision 04

Chapter Change

Chapter 4 - Tax Setup & Removed references to tax_code

Configuration

Version 18.0, Revision 03

Chapter Change

Rotating Service added new chapter

Credentials for
Integrated Systems

F-8 Technical Guide

 Version 18.0, Revision 02

Version 18.0, Revision 02

Chapter Change

Appendix C - Xstore Changed system.properties to configPath.properties.

Point of Service
Configuration Path

Version 18.0, Revision 01

Chapter Change

All Chapters Changed SystemConfig.xml to SysConfig.xml.

Order Management Updated ServiceHandlers.xml changes

System Options

Oracle Hospitality Added chapter

OPERA Property
Management
Configuration

Appendix C - Xstore Removed config path servlet section.

Point of Service
Updated confi path retrieval and assembly section.
Configuration Path

Version 17.0, Revision 03

Chapter Change

Airside Stores Tax-Free Changed name from “Airside Stores & Tax-Free Transactions” to
Transactions reflect that the section describes only the tax-free transactions
performed at airside stores.

Location Hierarchy Updated Location Based Hierarchical Pricing section.

Config

Version 17.0, Revision 02

Chapter Change

Address Mapping Updated document to reflect a change from system.properties

controls to a Spring configuration.

Locate Configuration Added “Fulfillment Types” section.

Revision History F-9

Version 17.0, Revision 01

Chapter Change

Airside Stores & Tax- Changed zone_id code to airport_code in the table
Free Transactions loc_rtl_loc.
Removed line saying that transactions cannot be suspended and
resumed in airside stores.
Rewrote section “How tax mode is determined from the flight
information” to reflect changes in 17.0.
Rewrote “Airside Tax-Free Configuration & Setup” section to include
new configurations.

Version 17.0, Revision 01

Chapter Change

Entire document Removed database tables and Dataloader records. Referred to Xstore
Point of Service Database Dictionary and Xstore Point of Service Host
Interface Guide for the information.

Order Broker Updated order types to describe Transfer Pickup functionality.

Configuration
Added section “Availability Update Message to Order Broker”.
Added information for New order types, and differentiated between
New and Legacy order types.

Country Pack Removed information in the “Brazil Country Pack” section and
Configuration added note explaining that Brazil is not supported in 17.0.

EFTLink Added <Parameter name="communicatorHosts"> and

<Parameter name="additionalWorkstationHostsMap">
settings to section “Parameters in AuthConfig.xml”.

Version 16.0.2, Revision 01

Chapter Change

Country Pack Added “Configurations” subsection to “Brazil Country Pack”

Configuration section.

Version 16.0.0.1, Revision 03

Chapter Change

ZPL II Label In “Fields and Layout” section, removed getStoreName method.

Configuration

Order Management Removed references to Order Management as a System of Record

System Options (SOR).

F-10 Technical Guide

 Version 16.0.0.1, Revision 02

Version 16.0.0.1, Revision 02

Chapter Change

Xstore Point of Service Added auth.log file to the table “Xstore Point of Service Log Files” in
Log Files the “Logs Configured/Controlled in log4j2” section.
Corrected table names.

Entire document Removed references to Xstore Payment.

Version 16.0.0.1
Chapter Change

Send Us Your Changed name of Xstore Point of Service for Grocery User Guide to
Comments Oracle Retail Xstore Point‐of‐Service, Lane Checkout User Interface User
Guide.

Version 16.0, Revision 02

Chapter Change

Customer Engagement Updated URLs for ORCE web services in the example configurations
Cloud Services for the ServiceHandlers.xml file.
Configuration

Order Broker In the “ServiceHandlers.xml Settings” section within “Xstore Point of

Configuration Service Configurations”, added the LegacyOrderType configuration.

Version 16.0
Chapter Change

Item and Pricing Removed restriction_category and tare_typecode from ITEM record.
Configuration
Added tare_value and tare_unit_of_measure to ITEM record.
Removed restriction_category and tare_typecode from
ITEM_OPTIONS record.
Added tare_value and tare_unit_of_measure to ITEM_OPTIONS
record.
Removed restriction_category from NON_PHYSICAL_ITEM record.

Item Messaging Corrected the list of valid values for sale_lineitm_typcode.

Configuration

Tender Configuration Removed “UNNECESSARY” from list of valid rounding modes.

Discount Configuration Corrected the list of valid values for sale_lineitm_typcode.

Removed “UNNECESSARY” from list of valid rounding modes.

Revision History F-11

Version 15.0, Revision 02

Chapter Change

Airside Stores & Tax- Removed note indicating that a generic boarding pass must be used
Free Transactions for tax-free shopping by employees or arriving passengers.
Removed zone_id from RETAIL_LOCATION record.
Added airport_code to RETAIL_LOCATION record.
Removed destination_country, destination_eu_code, via_1_country,
via_1_eu_code, via_2_country, via_2_eu_code, via_3_country,
via_3_eu_code, final_flight_eu_code, expiration_date,
destination_airport_name, and employee_flag from
FLIGHT_INFORMATION record.
Removed com_airport_zone_mapping table and
AIRPORT_ZONE_MAPPING record.
Added com_airport table and AIRPORT record.

Country Pack New chapter.

Configuration

Warranty Setup & Removed restriction_category from WARRANTY_ITEM record.

Configuration

Data Purger Overview Updates throughout to reflect current configuration.

Removed “Xstore Payment Payment Processor Configuration” appendix.

Removed all references to PayPal tender throughout document.

Version 15.0, Revision 02

Chapter Change

Xstore Point of Service Corrected image of Xstore Point of Service Management Console.
Management Console
Put domains into correct order.
Removed “AutoLogoutTimer” and “Environment Re-Poll” sections.

Entire Document General proofreading and corrections.

F-12 Technical Guide