sap pos 2.3 services configuration guide

Services, Configuration Guide

SAP Point-of-Sale 2.3

Document Version: 1.6 – 2015-11-30

CUSTOMER

SAP POS 2.3 Services Configuration Guide

2

CUSTOMER

© 2015 SAP SE or an SAP affiliate company. All rights reserved.


Typographic Conventions

Typographic Conventions

Type Style Description

Example Words or characters quoted from the screen. These include field names, screen titles,

pushbuttons labels, menu names, menu paths, and menu options.

Textual cross-references to other documents.

Example Emphasized words or expressions.

EXAMPLE Technical names of system objects. These include report names, program names,

transaction codes, table names, and key concepts of a programming language when they

are surrounded by body text, for example, SELECT and INCLUDE.

Example Output on the screen. This includes file and directory names and their paths, messages,

names of variables and parameters, source text, and names of installation, upgrade and

database tools.

Example Exact user entry. These are words or characters that you enter in the system exactly as

they appear in the documentation.

<Example> Variable user entry. Angle brackets indicate that you replace these words and characters

with appropriate entries to make entries in the system.

EXAMPLE Keys on the keyboard, for example, F2 or ENTER .


Document History

CUSTOMER

© 2015 SAP SE or an SAP affiliate company. All rights reserved. 3

Document History

Version Date Change

1.1 2010-08-15 Initial version for SAP POS 2.3.

1.2 2010-08-23 Revised commands with additional options and created two new phases.

1.3 2010-12-06 Added new commands and parameters for some of the commands.

1.4 2012-02-27 Added new parameters and configuration for the Generic Services.

1.5 2013-08-01 Updated to reflect enhancements implemented in SAP POS 2.3 SP06 and

SP07.

1.6 2015-11-30 Updated document template. Minor clarifications.

4

CUSTOMER



Contents

Contents

1 Intended Audience ........................................................................................................................ 5

2 Glossary .......................................................................................................................................... 6

3 Solution Overview ......................................................................................................................... 7

4 Configuring the POS ..................................................................................................................... 8 Service Extension DLL ..................................................................................................................... 8 XML Configuration Files .................................................................................................................. 8 Configuring a Non-Merchandise Item as a Service ......................................................................... 8 Configuring a Merchandise Item as a Service ................................................................................. 9 Configuring a Manager Code as a Service ...................................................................................... 9 Configuring a UDT as a Service ..................................................................................................... 10 Configuring a Tender as a Service................................................................................................. 10

5 Configuring the Services ............................................................................................................ 12 <ServiceList> Node ........................................................................................................................12 <Service> Node ..............................................................................................................................12

5.2.1 <DataDictionary> Node ................................................................................................. 13 5.2.2 <Phase> Node ............................................................................................................... 14

Global Variables ............................................................................................................................. 63


Intended Audience

CUSTOMER


1 Intended Audience

This document is intended for:

Consultants

Service Configuration Script Developers

Partners

Customers

6

CUSTOMER



Glossary

2 Glossary

Term Definition

Cardholder Verification

Method (CVM)

The means by which the person presenting a payment card (such as a debit or

credit card) is confirmed to be the rightful owner of that card. Typical Cardholder

Verification Methods include the entry of a PIN using a PIN Pad Device or the

signing of a receipt.

Dynamic Link Library

(DLL)

A collection of software routines that is stored as a separate file from the main

application code. At runtime, a DLL is loaded into memory and its routines are

made available to an application either:

Automatically, by the operating system, because the application references

routines in the DLL

OR

Manually, under direct control of the application itself.

Personal Identification

Number (PIN)

A PIN is a secret numeric password shared between a user and a system that can

be used to authenticate the user to the system (source: Wikipedia). In the case of

EFT, a PIN is used to verify the identity of the person presenting a payment card for

tendering.

PIN Pad Device (or PIN

pad)

An MSR and PIN capable device that has no communication channel for EFT

authorization.

Service An external process (external to SAP POS) that allows customers to, for example,

add minutes to a cell phone, make an airline reservation, or make a payment for a

credit card bill.

Service Configuration

Script

An XML file containing elements that define the required processing steps for one

or more Services. The syntax of these scripts is defined by the Service Extension.

Service Extension The external engine that provides a means of implementing various Services

through the use of Service Configuration Scripts.

Service User Exit The SAP POS functions that interface with an external engine which will allow for

the implementation of various Services required by the customer.

Service An external process (external to SAP POS) that allows customers to, for example,

add minutes to a cell phone, make an airline reservation, or make a payment for a

credit card bill.

Service Configuration

Script

An XML file containing elements that define the required processing steps for one

or more Services. The syntax of these scripts is defined by the Service Extension.

Service Extension The external engine that provides a means of implementing various Services

through the use of Service Configuration Scripts.

Service User Exit The SAP POS functions that interface with an external engine which will allow for

the implementation of various Services required by the customer.


Solution Overview

CUSTOMER


3 Solution Overview

Services are external processes that allow retail customers to process non-standard transactions at the POS

terminal. For example, add minutes to a cell phone, pay a cell phone bill, pay for an airline flight, pay a credit card

bill, and so on. A Service usually requires the POS to perform a specific set of tasks such as getting input from the

user, communicating with a service provider/host, adding items to the transaction, capturing data in the TLOG

and printing a receipt.

This solution consists of Service Extension, Service User Exit, and Services Adapter components. Together, these

components allow the retailer to create new Services at the POS using XML configuration files.

This document describes the configurations necessary to implement Services using the Service Extension,

Service User Exit, and Services Adapter which enable the addition of services via XML configuration files.

8

CUSTOMER



Configuring the POS

4 Configuring the POS

Service Extension DLL

A new POS.INI option called SERVICEEXTENSIONDLL is created to enable the POS to determine the name and

location of the Service Extension DLL. POS uses this POS.INI option to determine if the Service Extension DLL

should be loaded. The default name of the Service Extension DLL is SrvcExtn.dll.

Example

SERVICEEXTENSIONDLL=C:\progra~1\sap\retail~1\pointo~1\SrvcExtn.dll

During startup, POS checks the value of the POS.INI option SERVICEEXTENSIONDLL

If this option is not set, POS will not perform any additional processing and continues with the current startup

procedure

If this option is set, POS loads the DLL specified by the POS.INI option and displays the FAILED TO LOAD

SERVICE EXTENSION message if an error occurs.

XML Configuration Files

The configuration or steps required to execute each service is specified using XML configuration files. The Service

Extension supports multiple XML configuration files. It is recommended to use one XML configuration file per

service.

The pattern of the names of the XML configuration files can be specified by using the POS.INI option

SERVICEXMLMASK.

Example

SERVICEXMLMASK=SExtn*.xml

The XML configuration files should be placed in the PARM folder of the Xpress Server. The POS will automatically

download the XML configuration files from the server.

Configuring a Non-Merchandise Item as a Service

A new field called Service Code is added to the Non-Merchandise configuration.

If this field is not set (if the field is zero), the POS will not perform any additional processing and will continue

to process the item as a regular non-merchandise item.

If the Service Code field is set, then the POS executes the service specified by the service code whenever the

non-merchandise item is scanned or entered.

The following illustration shows the Service Code setting in the Configurator.


Configuring the POS

CUSTOMER


Configuring a Merchandise Item as a Service

A new field called Service Code is added to the Merchandise configuration in the PLU Maintenance window.


to process the item as a regular merchandise item.


merchandise item is scanned or entered.


Configuring a Manager Code as a Service

A new field called Service Code is added to the Manager Code configuration in the Manager/POS Functions

Maintenance window.


with the normal processing of the Manager Code.


Manager Code is executed.


10

CUSTOMER



Configuring the POS

Configuring a UDT as a Service

A new field called Service Code is added to the UDT (User Defined Transaction) configuration in the User Defined

Transaction Maintenance window.


with the normal processing of the UDT.


UDT is executed.


Configuring a Tender as a Service

A new field called Service Code is added to the Tender configuration in the Tender Maintenance window.


with the normal processing of the Tender.


Tender is selected.



Configuring the POS

CUSTOMER


12

CUSTOMER



Configuring the Services

5 Configuring the Services

<ServiceList> Node

The ServiceList node is the top-most node of the XML configuration file. Multiple services can be defined under

the ServiceList node. For simplicity, it is recommended to define one service per XML file.

Example

<ServiceList>

<Service Code="05" Description="BlackHawk Sale"/>

<Service Code="25" Description="AeroPass"/>

</ServiceList>

<Service> Node

A Service node contains all of the information required by the Service Extension to create and execute an

individual service.

The Service node contains three attributes:

Attributes Description

Code This attribute specifies the Service Code that is used to identify this Service. Service Code

9999 is reserved and is used to specify a Generic Service.

Description This attribute contains the description of the Service.

LogLevel This attribute specifies the logging level. LogLevel can be one of the following:

0: Error Logging; only errors will be logged. This is the default LogLevel.

1: Info Logging; errors and critical information will be logged

2: Debug Logging; errors, critical information, and debug information will be logged.

Example

<Service Code="05" Description="BlackHawk Sale" LogLevel="2">

The Service node can contain two nodes:

1. <DataDictionary> node

2. <Phase> node



CUSTOMER


5.2.1 <DataDictionary> Node

Each Service node can contain one DataDictionary node. This node specifies the data required by a Service.

Each individual data item is specified by using the DataItem node.

DataItem names must start with a letter and can contain a combination of alphanumeric characters including

special characters.

The DataItem node has the following attribute:

Node Attribute Value Description

<DataItem> Type

(Optional)

Single Specifies that the DataItem can store only a single value

(this is the default).

List Specifies that the DataItem can store a list of values. Each

value in the list is identified by an index which starts at 1.

Example

<DataDictionary>

<DataItem>ServiceID</DataItem>

<DataItem>ServiceName</DataItem>

<DataItem>ServiceTitle</DataItem>

<DataItem>StoreNum</DataItem>

<DataItem>CashierNum</DataItem>

<DataItem>TransNum</DataItem>

<DataItem>DateOfBirth</DataItem>

<DataItem>ReferenceNum</DataItem>

<DataItem>PaymentAmount</DataItem>

<DataItem>ConfirmationNumber</DataItem>

<DataItem>Track1</DataItem>



<DataItem>ModeOfInput</DataItem>

<DataItem>SkuNum</DataItem>

<DataItem>SkuDesc</DataItem>

<DataItem>Str1</DataItem>

<DataItem>Str2</DataItem>

<DataItem Type="List">TransactionItems</DataItem>

<DataItem Type="List">SelectedItems</DataItem>

<DataItem>ItemCount</DataItem>

<DataItem>AccountNumber Length</DataItem>

</DataDictionary>

14

CUSTOMER




5.2.2 <Phase> Node

Each Service node can contain multiple Phase nodes. Each Phase node specifies the commands that must be

executed for the phase.

A Phase node contains the Name attribute which is a predefined value specifying the name of the Phase. The

following is the set of predefined names that can be used to identify each Phase:


<Phase> Name ItemVoidBe

gin

An Item Void is initiated for an Item containing a Service

Code. The ItemVoidBegin Phase of all existing Service

Objects will be executed.

ItemVoidEn

d

An Item Void has been performed on an Item containing a

Service Code. The ItemVoidEnd Phase of all existing

Service Objects will be executed.

ManagerCod

e

A Manager Code containing a Service Code was Executed.

If a Service Code Configuration is defined with this Phase, a

new Service Object will be created and the ManagerCode

Phase will be executed.

ManualAuth A tender authorization with the bank has failed with a

timeout, so a manual authorization will be requested of the

cashier.

Merch A merchandise item containing a Service Code was

scanned/entered. If a Service Code Configuration is

defined with this Phase, a new Service Object will be

created and the Merch Phase will be executed.

MerchValid

ate

A merchandise item was scanned/entered. The

MerchValidate Phase of all existing Service Objects will

be executed.

NonMerch A non-merchandise item containing a Service Code was

scanned/entered. If a Service Code Configuration is

defined with this Phase, a new Service Object will be

created and the NonMerch Phase will be executed.

NonMerchVa

lidate

A non-merchandise item was scanned/entered. The

NonMerchValidate Phase of all existing Service Objects

will be executed.

PINPadAuth

Complete

Added in

POS2.3 SP07

A tender authorization (where the PIN pad was involved in

gathering payment card details and in providing final

approval) has been completed.

PostVoidBe

gin

Transaction containing an item with a Service Code is being

post voided. If a Service Code Configuration is defined with

this Phase, a new Service Object will be created and the

PostVoidBegin Phase will be executed.



CUSTOMER



PostVoidEn

d

Transaction containing an item with a Service Code has

been post voided. The PostVoidEnd Phase of all existing

Service Objects (corresponding to the PostVoidBegin)

will be executed.

ReturnBegi

n

An item containing a Service Code is selected for return. If a

Service Code Configuration is defined with this Phase, a

new Service Object will be created and the ReturnBegin


ReturnEnd An item containing a Service Code has been returned. The

ReturnEnd Phase of all existing Service Objects

(corresponding to the ReturnBegin) will be executed.

Tender Tendering is initiated for a tender containing a Service

Code. If a Service Code Configuration is defined with this

Phase, a new Service Object will be created and the Tender


Total Total was pressed on the POS. The Total Phase of all

existing Service Objects will be executed.

Transactio

nEnd

The Transaction has ended. The TransactionEnd Phase

of all existing Service Objects will be executed.

Udt A User Defined Transaction containing a Service Code was

initiated. If a Service Code configuration is defined with this

Phase, a new Service Object will be created and the UDT


Example

<Phase Name="NonMerch">

<Command Name="ServiceStart" Type="Start"/>

<Command Name="ServiceCancel" Type="Cancel"/>

</Phase>

5.2.2.1 <Command> Node

Each Phase node can contain multiple Command nodes. Each Command node specifies a command/action to be

performed by the Service Extension.

Each Command node has two attributes.

Name: A user defined value specifying the name of the command.

Type: A predefined value specifying the action performed by the command. The following is a list of pre-

defined Command Types.

o AdapterRequest

o AddItem

16

CUSTOMER




o Append

o Assign

o Cancel

o CaptureTlog

o CashierAuthorize

o Close

o Compare

o ContinueOK

o DisableSignatureLines

o Display

o ExitOK

o GetOriginalTlog

o InputCapture

o InputMenu

o ItemSize

o ListClear

o ListRemove

o ListSelection

o ListSize

o Math

o NonMerchLookup

o PluLookup

o Print

o PrintServiceReceipts

o Start

o SupervisorAuthorize

o SupervisorKey

o VoidItem

Each command can contain various nodes depending on the type of the command, along with the following two

nodes:

<OKCommand>: This node specifies what command to execute next if the operation specified by this

command was successful

<FailCommand>: This node specifies what command to execute next if the operation specified by this

command has failed.

5.2.2.1.1 Command Type - AdapterRequest

This command will send a request message to the Services Adapter and get a response.



CUSTOMER



<RequestID

>

Specifies the Request Identifier. For a

HostAuthorization request, RequestID must be a

constant. For a ValidateAlgorithm request, to execute a

custom validation algorithm, RequestID must be a

numeric constant that is not one of the predefined

algorithm identifiers. The predefined identifiers include: 10,

20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140 and

150. The identifier must be an integer that is within the

range of a 32-bit signed integer.

RequestTyp

e

HostAuthor

ization

Specifies that the message containing the Request data

should be sent to the host (for example, Stratus) and a

message containing the Response data should be received

via the Services Adapter.

ValidateAl

gorithm

Specifies that an Algorithm Validation message containing

the Request data should be sent to the Services Adapter

and a message containing the Response data should be

received.

SubService xx xx is the sub service identifier.

HostName xx xx specifies the IP address of the Host. By default, the

AdapterRequest is routed to the Host via POS Store Data

Transfer for Retail (formerly Transnet). If the Host Name is

specified, the Adapter Request is routed to the IP address

specified by the HostName parameter.

PortNumber xx xx specifies the Port Number to be used when

communicating with the Host specified by the HostName

parameter. By default, the AdapterRequest is routed to

the Host via POS Store Data Transfer for Retail. If the Host

Name is specified, the Adapter Request is routed to the IP

address specified by the HostName parameter along with

the specified PortNumber.

<Request> Specifies a request field to be sent to the Services Adapter.

Name xxx Specifies the name of the request field. For a

ValidateAlgorithm request, there are 6 predefined

names:

TS – Store Number

TR – Register Number

CN – Cashier Number

TN – Transaction Number

RD – Transaction Date

RH – Transaction Time

The Request elements with these predefined names are

expected to be placed first and all these elements must be

18

CUSTOMER





present in the request. The remaining Request elements

are processed according to their position.

The Request element with the name ALG is expected to be

the first element following the 6 predefined elements listed

above. The Request element with the name ALG specifies

the class name of the implementation of the algorithm.

After the Request element with the name ALG, other

Request elements can be added for passing values to the

validation algorithm.

FieldType

(Optional)

Const Specifies that the Request node is a Constant. This is the

default.

Dict Specifies that the Request node is a DataItem.

Index

(Optional)

nn For List Type DataItems, Index specifies which item within

the list to use. nn can be a numeric value or a DataItem (for

example, Index="7" or Index="LastItem").

If the index is less than 1 or more than the items present in

the list, the command name specified by the

BadIndexCommand node will be called.

Default is 1.

Position

(Optional)

nn Specifies the start position. The data contained in the

Request Node will be extracted from this position. nn can

be a numeric value or a DataItem (For example,

Position="3" or Position="StartPosition").

If the data contained in Request Node is less than

Position, the command name specified by the

FailCommand node will be called.

Default is 1.

Length

(Optional)

nn Specifies the number of characters of data contained in the

Request Node to be extracted. nn can be a numeric value

or a DataItem (For example, Length="5" or

Length="CardNumLength").

If the data contained in Request Node is less than Length

(or Length plus Position), the command name specified

by the FailCommand node will be called.

Default length is the length of data contained in the

Reference Node (or remaining length of data if the

position is specified).

<Response> The response received from the Services Adapter will be

stored in the DataItem specified by this node.

Name xxx Specifies the name of the response field.

<Status> The status received from the external host will be stored in

the DataItem specified by this element.



CUSTOMER



<ErrorMess

age>

The error message received from the external host will be

stored in the DataItem specified by this element if the

operation is unsuccessful.

<OKCommand

>

Specifies what command to call if the operation is

successful.

<Timeout> Specifies what command to call if a timeout occurs.

<HostOffli

ne>

Specifies what command to call if the Host is offline.

<BadIndexC

ommand>

Specifies what command to call if an Invalid Index is

specified, if this node is not present, the FailCommand will

be called.

<FailComma

nd>

Specifies what command to call if the operation fails.

Example

<Command Name="SendToHost" Type="AdapterRequest">

<RequestID RequestType="HostAuthorization"

SubService="1">BlackHawk</RequestID>

<Request Name="ServiceID" FieldType="Dict">ServiceID</Request>

<Request Name="RefNum" FieldType="Dict">ReferenceNum</Request>

<Request Name="Amount" FieldType="Dict">PaymentAmount</Request>

<Request Name="Selection" FieldType="Dict" Index="ALL">SelectItems</Request>

<Response Name="Resp">ResponseCode</Response>

<Response Name="Auth">ConfirmationNumber</Response>

<Response Name="Sel">SelectedItems</Response>

<Status>Result</Status>

<ErrMesg>message</ErrMesg>

<Timeout>ServiceComplete</Timeout>

<HostOffline>ServiceComplete</HostOffline>

<OKCommand>ServiceComplete</OKCommand>

<FailCommand>ServiceComplete</FailCommand>

</Command>

5.2.2.1.2 Command Type - AddItem

This command will add an item to the current POS transaction.

20

CUSTOMER





<ItemID> Specifies item to be added, nonmerch ID if non-

merchandise or sku/plu number if adding a sku/plu.

ItemType NonMerch Specifies that a non-merchandise item needs to be added

to the transaction.

Merch Specifies that a merchandise item needs to be added to the

transaction.

Tender Specifies that a tender needs to be added to the

transaction.

ManualAuth Specifies that a manual authorization code will added for

the tender.

<Reference

>

Specifies the non-merch reference number or the

PLU/SKU number of a merchandise item, or the account

number.

FieldType

(Optional)

Const Specifies that the Reference node is a Constant (this is

the default).

Dict Specifies that the Reference node is a DataItem.

Index

(Optional)




If the index is less than 1 or more than the items present in

the list, the command name specified by the


Default is 1.

Position

(Optional)


Reference node will be extracted from this position. nn

can be a numeric value or a DataItem (for example,


If the data contained in Reference node is less than

Position, the command name specified by the

FailCommand node will be called.

Default is 1.

Length

(Optional)


Reference node to be extracted. nn can be a numeric value

or a DataItem (for example, Length="5" or


If the data contained in Reference node is less than

Length (or Length plus Position), the command name

specified by the FailCommand node will be called.

The default length is the length of data contained in the

Reference node (or remaining length of data if position is

specified).



CUSTOMER



<Amount> * Specifies the item’s amount or the amount to charge with

the tender (if a tender is added).

<Departmen

t>

* Specifies the item’s Department.

<Track2> * Specifies the Track2 data (for example, for a Gift Card type

Non-Merchandise item or a tender).

<Cardholde

rLName>

* Specifies the Card Holder’s Last Name (for example, for a

Gift Card type Non-Merchandise item or a tender).

<Cardholde

rFName>

* Specifies the Card Holder’s First Name (for example, for a

Gift Card type Non-Merchandise item or a tender).

<ExpiryDat

e>

* Specifies the Expiry Date of the Card (for example, for a Gift

Card type Non-Merchandise item or a tender).

<Authoriza

tion>

Specifies the Authorization number (for example, for a Gift

Card type Non-Merchandise item or a tender).

<InputSour

ce>

Specifies what input source will be reported in the tender.

<OKCommand

>


successful.

<BadIndexC

ommand>

Specifies what command to call if an Invalid Index is


be called.

<FailComma

nd>


*Attributes are the same as those listed for <Reference>.

Example

<Command Name="Adapter" Type="AddItem">

<ItemID ItemType="Tender">9</ItemID>

<Reference>7003000080803823</Reference>

<Amount>200.00</Amount>

<ExpiryDate>1212</ExpiryDate>

<Authorization>123456</Authorization>

<OKCommand>PrintConfirmation</OKCommand>

<FailCommand>ServiceFail</FailCommand>

</Command>

22

CUSTOMER




5.2.2.1.3 Command Type - Append

This command will append the Value nodes to the Target node. Multiple appends can be made using a single

Append command.


<Target> Specifies the destination DataItem. Target can be a Single

or a List Type DataItem. For a List Type DataItem, the data

is assigned to the next Index, starting from 1.

<Value> Specifies the data to be appended, multiple Value nodes

can be specified, the data in each Value node will be

extracted and formatted according to the attributes.

FieldType

(Optional)

Const Specifies that the Value node is a Constant (this is the

default).

Dict Specifies that the Value node is a DataItem.

Index

(Optional)




If the Index is less than 1 or more than the items present in

the list, the command name specified by


Default is 1.

Position

(Optional)


Value node will be extracted from this position. nn can be a

numeric value or a DataItem (for example, Position="3"

or Position="StartPosition").

If the data contained in the Value node is less than

Position, the command name specified by FailCommand

node will be called.

Default is 1.

Length

(Optional)


Value node to be extracted. nn can be a numeric value or a

DataItem (for example, Length="5" or


If the data contained in the Value node is less than Length


by FailCommand node will be called.

Default Length is the length of data contained in the Value

node (or remaining length of data if Position is specified).

Format

(Optional)

+.n Specifies that the Value node is formatted as a number by

adding n digits after the decimal point.

For example, if Value is 123456, and Format="+.2",

formatted value will be 123456.00.



CUSTOMER



For example, if Value is 123.456 and Format="+.2",

formatted value is 123.45.

-.n Specifies that the Value node should be formatted as a

number by inserting a decimal point before the last n digits.

For example, Value is 123456 and Format="-.2",


For example, Value is 123.456 and Format="-.2",


StripZeroe

s (Optional)

True Specifies that the leading zeroes should be removed from

the Value node.

False Specifies that the leading zeroes should be preserved in the

Value node. This is the default.

Stripspace

s (Optional)

True Specifies that the leading and trailing spaces should be

removed from the Value node.

False Specifies that the leading and trailing spaces should be

preserved in the Value node. This is the default.

Size

(Optional)

nn Specifies the final size of the Value node. nn can be a

numeric value or a DataItem (for example, Size="25" or

Size="LineSize").

If the data contained in the Value node is less than Size, it

will be padded with spaces based on the Align Parameter.

If the data contained in the Value node is greater than

Size, it will be truncated.

The default is the length of data contained in the Value

node.

Align

(Optional)

Left The data contained within the Value node will be aligned

left (for example, if data is xxx, size is 8, then the string will

be "xxx "). This is the default.

Right The data contained within the Value node will be aligned

right (for example, if data is xxx, size is 8, then the string

will be " xxx").

Center The data contained within the Value node will be aligned


will be " xxx ").

<OKCommand

>


successful.

<BadIndexC

ommand>

Specifies what command to call if an invalid index is


be called.

24

CUSTOMER





<FailComma

nd>


Example

<Command Name="SetPrompt" Type="Append">

<Target>Str1</Target>

<Value Size="13" Align="Left">Please Enter</Value>

<Value>Customer Number</Value>

<OKCommand>SetPrompt2</OKCommand>


</Command>

Example

<Command Name="SetPrompt2" Type="Append">

<Target>Str1</Target>

<Value Size="22" Align="Left">Do you wish to Cancel</Value>

<Value FieldType="Dict" Position="14" Length="14" Size="15"

Align="Left">ServiceTitle</Value>

<Value>processing?</Value>

<OKCommand>SetPayment</OKCommand>


</Command>

5.2.2.1.4 Command Type - Assign

This command will assign the Value node to the Target node. Multiple assignments can be made using a single

Assign command.





<Value> Specifies the data to be assigned; the data in the Value

node will be extracted and formatted according to the

attributes.

FieldType

(Optional)


default).




CUSTOMER



Index

(Optional)







Default is 1.

Position

(Optional)








Default is 1.

Length

(Optional)










Format

(Optional)













StripZeroe

s (Optional)


the Value node.



Stripspace

s (Optional)



26

CUSTOMER







Size

(Optional)



Size="LineSize").






node.

Align

(Optional)






will be " xxx").



will be " xxx ").

<OKCommand

>


successful.

<BadIndexC

ommand>



be called.

<FailComma

nd>


Example

Single Assignment

<Command Name="SetSetviceInfo" Type="Assign">

<Target>ServiceID</Target>

<Value>05</Value>

<OKCommand>SetServiceInfo2</OKCommand>

<FailCommand>ServiceFail</FailComand>

</Command>

Example

Multiple Assignment

<Command Name="SetSetviceInfo" Type="Assign">



CUSTOMER


<Target>ServiceID</Target>

<Value>5</Value>

<Target>PaymentAmount</Target>

<Value Format="-.2">0012.753</Value>

<Target>ModeOfInput</Target>

<Value>Msr</Value>

<Target>AccountNumber</Target>

<Value>12345678901234567890</Value>

<Target>ServiceName</Target>

<Value>BlackHawk Sale</Value>

<Target>ServiceTitle</Target>

<ValueFieldType="Const" Size="40" Align="Center>BlackHawk Sale</Value>

<Target>TransactionItems</Target>

<Value>1111</Value>


<Value>2222</Value>


<Value>3333</Value>


<Value>4444</Value>

</Command>

5.2.2.1.5 Command Type - Cancel

This command will cancel the execution of the current service, reset the data for the service and send a

cancellation message to the Service User Exit. This command specifies the end of command execution and will

not have an OKCommand node or a FailCommand node.

Example

<Command Name="ServiceCancel" Type="Cancel"/>

5.2.2.1.6 Command Type - CaptureTlog

This command requests that the POS store the specified data in the Tlog.


<TlogDateI

D>

Specifies the Tlog Data Identifier. TlogDataID must be a

Constant. A new Tlog record type will be created to store

28

CUSTOMER





User Exit Tlog data. TlogDataID will specify the sub-

record type for a particular service.

<TlogData> Specifies a field to be stored within the Tlog record.

Name xxx Specifies the name of the Tlog Data field.

FieldType

(Optional)

Const Specifies that the TlogData node is a Constant (this is the

default).

Dict Specifies that the TlogData node is a DataItem.

Index

(Optional)







Default is 1.

Position

(Optional)


TlogData node will be extracted from this position. nn can

be a numeric value or a DataItem (for example,


If the data contained in the TlogData node is less than



Default is 1.

Length

(Optional)


TlogData node to be extracted. nn can be a numeric value



If the data contained in the TlogData node is less than


specified by FailCommand node will be called.

Default Length is the length of data contained in the

TlogData node (or remaining length of data if Position is

specified).

<OKCommand

>


successful.

<BadIndexC

ommand>



be called.

<FailComma

nd>




CUSTOMER


Example

<Command Name="SaveToTlog" Type="CaptureTlog">

<TlogDataID>1001</TlogDataID>

<TlogData Name="ServiceID" FieldType="Dict">ServiceID</TlogData>

<TlogData Name="RefNum" FieldType="Dict">ReferenceNum</TlogData>

<TlogData Name="Amount" FieldType="Dict">PaymentAmount</TlogData>

<TlogData Name="AuthNum" FieldType="Dict">ConfirmationNumber</TlogData>


<FailCommand>ServiceFail</FaileCommand>

</Command>

5.2.2.1.7 Command Type - CashierAuthorize

This command will prompt the currently logged on cashier to enter the password and validates it.

Node Description

<Prompt2> This is the secondary prompt (help/tip displayed on the POS).

<OKCommand> Specifies what command to call if the operation is successful.

<FailCommand> Specifies what command to call if the operation fails.

Example

<Command Name="VerifyCashierPassword1" Type="CashierAuthorize">

<Prompt2>enter cashier password</Prompt2>

<OKCommand>GetSupervisorAuth</OKCommand>


</Command>

5.2.2.1.8 Command Type - Close

This command will finish the execution of the current service, store the required data, and send a Close message

to the Service User Exit. The Service User Exit will not continue to process the remaining steps for the current

POS function and will attempt to close the current transaction. This command specifies the end of command

execution and will not have an OKCommand node or a FailCommand node.

Example

<Command Name="ServiceCancel" Type="Close"/>

30

CUSTOMER




5.2.2.1.9 Command Type - Compare

This command performs the comparison operation for each Criteria set and calls the OKCommand for the first

matching criteria or the NoMatchCommand if none of the criteria are true.


<Criteria> Specifies the criteria for each comparison operation.

Multiple Criteria nodes can be specified. Each Criteria

node should contain an OKCommand node. The command

name specified by the OKCommand node will be called if the

comparison is true.

<Value> Specifies the data to be compared; the data in the Value

node will be extracted and formatted according to the

attributes.

FieldType

(Optional)


default).


Index

(Optional)







Default is 1.

Position

(Optional)








Default is 1.

Length

(Optional)










Format

(Optional)





CUSTOMER













StripZeroe

s (Optional)


the Value node.



Stripspace

s (Optional)





Size

(Optional)



Size="LineSize").






node.

Align

(Optional)






will be " xxx").



will be " xxx ").

<Operator> Specifies the operation to perform.

== Comparison operation - True if the data in the first Value

node is equal to the second.

32

CUSTOMER





G Comparison operation - True if the data in the first Value

node is greater than the second.

L Comparison operation - True if the data in the first Value

node is less than the second.

G= Comparison operation - True if the data in the first Value

node is greater than or equal to the second.

L= Comparison operation - True if the data in the first Value

node is less than or equal to the second.

N= Comparison operation - True if the data in the first Value

node is not equal to the second.

S== Comparison operation - True if the size of data in the first

Value node is equal to the second.

SG Comparison operation - True if the size of data in the first

Value node is greater than the second.

SL Comparison operation - True if the size of data in the first

Value node is less than the second.

SG= Comparison operation - True if the size of data in the first

Value node is greater than or equal to the second.

SL= Comparison operation - True if the size of data in the first

Value node is less than or equal to the second.

SN= Comparison operation - True if the size of data in the first

Value node is not equal to the second.

<OKCommand

>


successful (once a criterion matches, its OKCommand will be

called, and the remaining criteria are not evaluated).

<NoMatchCo

mmand>

Specifies what command to call if the criterion does not

match.

<BadIndexC

ommand>



be called.

<FailComma

nd>


Example

<Command Name="CheckAmountLength" Type="Compare">

<Criteria>

<Value FieldType="Dict">AccountNumber</Value>

<Operator>S==</Operator>

<Value>16</Value>



CUSTOMER


<OKCommand>GetPaymentAmount</OKCommand>

</Criteria>

<FailCommand>ShowAccountError</FailCommand>

</Command>

Example

<Command Name="CheckInputMethod" Type="Compare">

<Criteria>

<Value FieldType="Dict">ModeOfInput</Value>

<Operator>==</Operator>

<Value>Keyboard</Value>

<OKCommand>ReEnterAccountNumber</OKCommand>

</Criteria>

<Criteria>



<Value>Scanner</Value>

<OKCommand>ServiceFail</OKCommand>

</Criteria>

<Criteria>



<Value>Msr</Value>

<OKCommand>GetCustomerName</OKCommand>


</Command>

5.2.2.1.10 Command Type - ContinueOK

This command will finish the execution of the current service, store the required data, and send a ContinueOK

message to the Service User Exit. The Service User Exit will continue to process the remaining steps for the

current POS function. This command specifies the end of command execution and will not have an OKCommand

node or a FailCommand node.

Example

<Command Name="ServiceEnd" Type="ContinueOK"/>

34

CUSTOMER




5.2.2.1.11 Command Type – DisableSignatureLines

Added in POS 2.3 SP07.

This command will turn off signature line printing for the current tender. Any signature lines configured either

directly for the tender or in a profile associated with the tender will not be printed. This command does not affect

the printing of electronically captured signatures, only the printing of lines where a customer would be expected

to sign their name directly on the receipt is affected.

Since this command operates on the current tender, it is only valid during phases where a tender is being

processed (Tender and PINPadAuthComplete phases). If used during any other phase, the command will fail.

Example

<Command Name="HideSignatureLine" Type="DisableSignatureLines">

<OKCommand>CheckCVM</OKCommand>

<FailCommand>CancelCommand</FailCommand>

</Command>

5.2.2.1.12 Command Type - Display

This command will display a message on the POS screen.


<Prompt1> This is the primary prompt displayed to the cashier.

<DisplayOp

tion>

Specifies the display options.

DisplayTyp

e (Optional)

AnyKey Wait for the user to press any key (this is the default

option).

YesNo Prompt the user to press Yes or No, OKCommand will be

called if the response is Yes, FailCommand if no.

DisplayTyp

e (Optional)

WaitMS Flashes the message on the POS screen for the specified

milliseconds, does not require the user to press a key.

Status Displays a status message on the POS entry window.

<DisplayLi

ne>

Specifies each full line to be displayed (maximum 40

characters).

FieldType

(Optional)

Const Specifies that the DisplayLine node is a Constant (this is

the default).

Dict Specifies that the DisplayLine node is a DataItem.

Index

(Optional)






CUSTOMER






Default is 1.

Position

(Optional)


DisplayLine node will be extracted from this position. nn



If the data contained in the DisplayLine node is less than



Default is 1.

Length

(Optional)


DisplayLine node to be extracted. nn can be a numeric

value or a DataItem (for example, Length="5" or


If the data contained in the DisplayLine node is less than




DisplayLine node (or remaining length of data if

Position is specified).

DisplayLab

el (Optional)

xxx Specifies a Label to be displayed along with the

DisplayLine.

<OKCommand

>


successful.

<BadIndexC

ommand>



be called.

<FailComma

nd>


Example

<Command Name="ServiceFail2" Type="Display">

<Prompt1>Re-Enter PIN?</Prompt1>

<DisplayOption DisplayType="YesNo"/>

<OKCommand>ServiceFail3</OKCommand>

<FailCommand>ServiceFail3</FailCommand>

</Command>

<Command Name="ServiceFail3" Type="Display">

<Prompt1>Re-Enter?</Prompt1>

<DisplayOption DisplayType="YesNo"/>

36

CUSTOMER




<DisplayLine FieldType="Dict" DisplayLabel="Item Number

:">TransactionItem</DisplayLine>

<DisplayLine>Items do not match</DisplayLine>

<DisplayLine>Do you want to re-try?</DisplayLine>

<OKCommand>ServiceRetry</OKCommand>


</Command>

<Command Name="ServiceRetry" Type="Display">

<DisplayOption DisplayType="WaitMS">1000</DisplayOption>

<DisplayLine FieldType="Dict">ServiceName</DisplayLine>

<DisplayLine>!! Retrying !!</DisplayLine>

<OKCommand>PrintConfirmation</OKCommand>

<FailCommand>PrintConfirmation</FailCommand>

</Command>

5.2.2.1.13 Command Type - ExitOK

This command will finish the execution of the current service, store the required data, and send an ExitOK

message to the Service User Exit. The Service User Exit will not continue to process the remaining steps for the

current POS function and will return a DONE. This command specifies the end of command execution and will not

have an OKCommand node or a FailCommand node.

Example

<Command Name="ServiceComplete" Type="ExitOK"/>

5.2.2.1.14 Command Type - GetOriginalTlog


This command will retrieve custom data stored in User Exit (UE) TLog records. In the UE TLog records, the

custom data fields are stored in a list of name-value pairs.

The name-value pair has the following format:

Field Size (in Bytes) Description

Name of the Field 10 Identifier for the user defined name-value pair. It is the same

as the Name attribute of the TlogData element from the

CaptureTlog command originally used to capture the

data.

Value of the Field 40 Value of the user defined data.



CUSTOMER



<TlogDateI

D>

Specifies the ID that was used for this TLog data when it

was originally stored. TlogDataID must be a constant.

TlogDataID will specify the sub-record-type for a

particular service.

<TlogData> Specifies the TLog data to be retrieved and then stored in

the DataItem specified by this element. This element can

be repeated multiple times, once for each field to be

retrieved.

Name xxx Specifies the name of the field of the UE TLog data to be

retrieved.

<OKCommand

>


successful.

<FailComma

nd>


Example

<Command Name="ReadTLog" Type="GetOriginalTlog">

<TlogDataID>1001</TlogDataID>

<TlogData Name="ServiceID">ServiceID</TlogData>

<TlogData Name="RefNum">ReferenceNum</TlogData>

<TlogData Name="Amount">PaymentAmount</TlogData>

<TlogData Name="AuthNum">ConfirmationNumber</TlogData>



</Command>

5.2.2.1.15 Command Type - InputCapture

This command will request input from the POS and store it in the Target node.


<Target> Input entered/scanned by the user will be stored in the

DataItem specified by this node. Target can be a Single or

a List Type DataItem. For a List Type DataItem, the data is

assigned to the next Index, starting from 1.

InputType Specifies what kind of data needs to be input from the POS.

38

CUSTOMER





ItemList [POS automatically fills this value] A list of current

merchandise/non-merchandise items. Each line contains

one record formatted as show below:

Record Identifier: 1 Char (Value M – Merchandise, N –

Non-Merchandise item)

o Merchandise Record format:

o PLU Number: 20 Chars

o Department Number: 4 Chars

o Amount: 8 Chars

o Non-Merchandise Record Format:

o Reference Number: 20 Chars

o Non-Merchandise ID: 4 Chars

o Amount: 8 Chars

NumService

Receipts

[POS automatically fills this value] The number of service

receipts currently set for printing. See command

PrintServiceReceipts. Added in POS 2.3 SP06.

OriginalTend

erList

[POS automatically fills this value] A list of tender items of

the original transaction. Added in POS 2.3 SP06.

Each line contains one record formatted as show below:

Record Identifier: 1 Char (Value T – Tender item)

o Tender Record format:


o Tender ID: 4 Chars

o Amount: 8 Chars

o Tender Description: 20 Chars

PosAmountD

ue

[POS automatically fills this value] The current POS

balance amount (Total amount minus any amounts already

paid).

PosBusines

sDate

[POS automatically fills this value] The POS business date

formatted according to the POS date format and the Date

Format Separator as specified in the Configurator.

PosCardExp

iryDate

[POS automatically fills this value] The expiry date of the

current payment card.

PosCardhol

derName

[POS automatically fills this value] The card holder name

associated with the current payment card.

PosCardTra

ck2

[POS automatically fills this value] The track2 data from the

current payment card, if the card data was read

automatically.

PosCashier

Num

[POS automatically fills this value] The currently logged on

cashier number.



CUSTOMER



PosCurrent

Date

[POS automatically fills this value] The current POS date

formatted according to the POS date format and the Date


PosCurrent

Time

[POS automatically fills this value] The current POS time

formatted according to the POS time format and the time


PosInputSo

urce

[POS automatically fills this value] The source of the most

recent input data. See the description of the InputSource

element, below, for a list of possible values.

PosMgrID [POS automatically fills this value] The current manager

code ID if available, 0 if not.

PosNonMerc

hAmount

[POS automatically fills this value] The price of the current

non-merchandise item if available, 0 if not.

PosNonMerc

hID

[POS automatically fills this value] The non-merchandise ID

of the current item if available, 0 if not.

PosNonMerc

hRefNum

[POS automatically fills this value] The non-merchandise

reference number of the current item if available, 0 if not.

PosOrigina

lBusinessD

ate

[POS automatically fills this value] The POS business date

of the original transaction formatted according to the POS

date format and the Date Format Separator as specified in

the Configurator. Added in POS 2.3 SP06.

PosOrigina

lCashierNu

m

[POS automatically fills this value] The logged on cashier

number of the original transaction. Added in POS 2.3 SP06.

PosOrigina

lRegisterN

um

[POS automatically fills this value] The POS register

number of the original transaction. Added in POS 2.3 SP06.

PosOrigina

lStoreNum

[POS automatically fills this value] The POS store number

of the original transaction. Added in POS 2.3 SP06.

PosOrigina

lTxnDate

[POS automatically fills this value] The current POS date of

the original transaction formatted according to the POS

date format and the Date Format Separator as specified in


PosOrigina

lTxnNum

[POS automatically fills this value] The transaction number

of the original transaction. Added in POS 2.3 SP06.

PosOrigina

lTxnTime

[POS automatically fills this value] The current POS time of

the original transaction formatted according to the POS

time format and the time Format Separator as specified in


40

CUSTOMER





PosPluDept [POS automatically fills this value] The department number

of the current item if available, 0 if not.

PosPluNum [POS automatically fills this value] The PLU number of the

current item if available, 0 if not.

PosPluPric

e

[POS automatically fills this value] The price of the current

merchandise item if available, 0 if not.

PosRegiste

rNum

[POS automatically fills this value] The POS register

number.

PosStoreNu

m

[POS automatically fills this value] The POS store number.

PosTenderA

mount

[POS automatically fills this value] The amount to be paid

using the current tender (this value is only available in the

tender phase).

PosTenderC

VM

[POS automatically fills this value] The CVM user for the

current tender (this value is only valid when a tender is

being processed). Added in POS 2.3 SP07.

The CVM value is the total of one or more of the following

values:

1 = Cardholder entered a PIN.

2 = Cardholder provided a signature.

4 = Cardholder provided a CVV.

8 = Cardholder provided a fingerprint scan.

16 = Cardholder provided other biometric data (such as

a retina scan).

32 = Custom verification method 1 (implementation

specific).


specific).


specific).

If no CVM has been provided, the value will be 0.

PosTenderF

xAmount

[POS automatically fills this value] The amount to be paid in

local currency using the current tender. Only available

during the tender validation phase.

PosTenderI

D

[POS automatically fills this value] The ID number of the

current tender.

PosTenderN

eedsSignat

ure

[POS automatically fills this value] A flag (0 or 1) indicating

whether a signature should be obtained for the current

tender (this value is only valid when a tender is being

processed). Added in POS 2.3 SP07.



CUSTOMER



PosTenderR

efNum

[POS automatically fills this value] The authorization

reference number for the current tender, if available, 0 if

not.

PosTxnMgrC

ode

[POS automatically fills this value] The current transaction

Manager Code if available, 0 if not.

PosTxnNum [POS automatically fills this value] The current transaction

number.

PosTxnSubT

otal


transaction subtotal.

PosTxnTota

l


transaction total.

PosUDTID [POS automatically fills this value] The current UDT ID if

available, 0 if not.

TenderList [POS automatically fills this value] A list of current tender

items. Each line contains one record formatted as show

below:

Record Identifier:1 Char (Value T: Tender item)

o Tender Record format:


o Tender ID: 4 Chars

o Amount: 8 Chars

o Tender Description: 20 Chars

UserInput Input needed from the user/cashier, A message (specified

by Prompt1 and Prompt2) will be displayed on the POS

screen and the user/cashier will be asked to enter the

information.

Source

(Optional)

Specifies the allowed source of input (how data can be

entered). Only valid with the InputType=”UserInput”.

Multiple sources can be specified using the '|' separator.

The default is to allow all sources (PIN pad, Scanner, and

MSR).

For example,

<Target InputType="UserInput"

Source="Pinpad|Scanner|Msr">AcntNum</Targe

t>

Keyboard Specifies that input data can be entered using the POS

keyboard.

For example,


Source="Keyboard">AcntNum</Target>

42

CUSTOMER





Scanner Specifies that input data can be entered using the POS

barcode scanner.

Msr Specifies that input data can be entered using the POS

Magnetic Stripe Reader.

Pinpad Specifies that input data can be entered using a PIN pad.

<TrackData

1>

If a card is swiped on the MSR, the track1 data (if available)

will be stored in the DataItem specified by this node.

<TrackData

2>



<TrackData

3>



<InputSour

ce>

The source of input (how the data was entered) will be

stored in the DataItem specified by this node. Input Source

will be one of:

Keyboard: Data was entered by using the POS

Keyboard.

Msr: Data was entered by using the POS Magnetic

Stripe Reader.

PinpadChip: Data was entered using the chip reader

on the PIN pad.

PinpadChipFailSwiped: Data was entered using the

MSR on the PIN pad after the payment card chip could

not be read.

PinpadSwiped: Data was entered using the MSR on

the PIN pad.

Scanner: Data was entered by using the POS barcode

scanner

<MinLength

>

The minimum number of digits allowed in the input. Only

valid with InputType=” UserInput”.

InputMetho

d (Optional)

The minimum number of digits will be validated only for the

specified InputMethod(s). The default is to allow all

sources (Keyboard, Scanner, MSR, and PIN pad).

For example,



t>


Keyboard.

For example,





CUSTOMER




Scanner.




Multiple InputMethods can be specified using the '|'

separator.

StripZeroe

s (Optional)

Specifies whether the leading zeroes should be ignored

while performing the maximum value checking.

True Leading zeroes will be ignored while performing the

maximum value validation. The target will still contain any

leading zeroes that the user has entered.

False Leading zeroes will not be removed before performing the

maximum value validation. This is the default.

<MaxLength

>

The maximum number of digits allowed in the input. Only

valid with InputType=” UserInput”.

InputMetho

d (Optional)

The maximum number of digits will be validated only for the

specified InputMethod(s). The default is to allow all

sources (Keyboard, Scanner, MSR, and PIN pad).

For example,



t>


Keyboard.

For example,




Scanner.





separator.

StripZeroe

s (Optional)






44

CUSTOMER







<MinValue> The entered input should be greater than or equal to this

value. Only valid with InputType=”UserInput”.

InputMetho

d (Optional)

The minimum value will be validated only for the specified

InputMethod(s). The default is to allow all sources

(Keyboard, Scanner, MSR, and PIN pad).

For example,



t>


Keyboard.

For example,




Scanner.





separator.

StripZeroe

s (Optional)








<MaxValue> The entered input should be lesser than or equal to this

value. Only valid with InputType=” UserInput”.

InputMetho

d (Optional)

The maximum value will be validated only for the specified

InputMethod(s). The default is to allow all sources

(Keyboard, Scanner, MSR, and PIN pad).


Keyboard.

For example,





CUSTOMER




Scanner.





separator.

StripZeroe

s (Optional)








<Mask> Specifies how the input data should be masked. Only valid

with InputType="UserInput" and

Source=”Keyboard”.

Type General The input will have a general mask, which will be specified in

the Mask node. The following masking characters apply for

General mask:

9 Numeric character

a Lower case alphabet

A Upper case alphabet

X Alphanumeric character

For example,

<Mask Type="General">9999999999<Mask> (all

the characters must be numeric).

<Mask Type="General">XXAA99aa<Mask> (The

first two characters must be alphanumeric, the next

two characters must be upper case alphabet, the next

two characters must be numeric, the next two

characters must be lower case alphabet).

Date The input date will have a mask, which will be specified in

the Mask node. The following masking characters apply for

Date mask:

D Day of month (Example: 1, 15, 31)

DD Two digit day of month (Example: 01, 15, 31)

M Month (Example: 1, 12)

MM Two digit month (Example: 01, 12)

YY Two digit year (Example: 95, 99, 05, 12)

46

CUSTOMER





YYYY Four digit year (Example: 1995, 1999,

2010, 2012)

For example,

<Mask Type="Date">D/M/YYYY</Mask>

Phone The phone number input will have a mask, which will be

determined by the Mask node:

N Numeric character

For example,

<Mask Type="Phone">(NNN)-NNN-NNNN</Mask>

<Mask Type="Phone">NNN-NNN-NNNN</Mask>

<Mask Type="Phone">(NN)-NN-NNNNNN</Mask>

Money The input will be an amount, the number of decimal digits

will be determined by the POS’s Currency Decimals

parameter.

Password The input will be hidden, POS will display asterisks ‘*’

instead of the typed characters.

DataOnly

(Optional)

True Masking characters will be stripped out of the input. For

example, if the Mask node is MM/DD/YYYY and input is

12/12/2010, then 12122010 will be stored in the target.

False The masking characters will be preserved in the input. For

example, if the Mask node is MM/DD/YYYY and input is

12/12/2010, then 12/12/2010 will be stored in the target.

The default is False.

<Default> This is the default/initial value. Only valid with

InputType=" UserInput".

Editable

(Optional)

True The user will be allowed to edit the default value shown

when prompting for the input capture.

False The user will not be allowed to edit the default value shown

when prompting for input capture. When the user starts to

type, the default value will be removed. The default is

False.

<Prompt1> This is the primary prompt displayed to the cashier. Only

valid with InputType=" UserInput".

<Prompt2> This is the secondary prompt (help/tip displayed on the

POS). Only valid with InputType=" UserInput".

<OKCommand

>


successful.

<FailComma

nd>




CUSTOMER


Example

<Command Name="GetStoreNumber" Type="InputCapture">

<Target Input Type="PosStoreNumber">StoreNum</Target>

<OKCommand>GetRegisterNumber">StoreNum</Target>


</Command>

<CommandName="GetAmount" Type="InputCapture">

<Target InputType="UserInput" Source="Keyboard">PaymentAmount</Target>

<Mask Type="Money" />

<OKCommand>GetAccountNumber">StoreNum</Target>


</Command>

<Command Name="GetPhoneNumber" Type="InputCapture">


Source="Keyboard|Scanner">PaymentAmount</Target>

<Mask Type="Phone" DataOnly="False">(999)999-9999</Mask>

<MinLength>10</MinLength>

<MaxLength>12</MaxLength>

<MinValue>(416)000-0001</MinValue>

<MaxValue>(416)999-9999</MaxValue>

<Default Editable="True">(416)000-0001</Default>

<Prompt1>Phone Number</Prompt1>

<Prompt2>Type PhoneNumber and press Enter</Prompt2>

<OKCommand>GetBirthDate1</OKCommand>


</Command>

<Command Name="GetBirthDate" Type="InputCapture">



<Mask Type="Date" DataOnly="False">DD/MM/YYYY</Mask>

<MinLength>8</MinLength>

<MaxLength>10</MaxLength>

<MinValue>13/12/1999</MinValue>

<MaxValue>13/01/2000</MaxValue>

<Default Editable="True">12/12/1999</Default>

<Prompt1>Reservation Date</Prompt1>

<Prompt2>Type Date and press Enter</Prompt2>

48

CUSTOMER




<OKCommand>GetAccountNumber1</OKCommand>


</Command>

<Command Name=" GetAccountNumber" Type="InputCapture">



<Mask Type="Date" DataOnly="False">DD/MM/YYYY</Mask>

<TrackData1>Track1</TrackData1>



<InputSource>ModeOfInput</InputSource>

<MinLength InputMethod="Keyboard">12</MinLength>

<MaxLength InputMethod="Keyboard">12</MaxLength>

<MinLength InputMethod="Msr">12</MinLength>

<MaxLength InputMethod="Msr">12</MaxLength>

<MaxValue InputMethod="Keyboard">111111111111</MaxValue>

<MaxValue InputMethod="Keyboard">199999999999</MaxValue>

<MaxValue InputMethod="Msr">111111111111</MaxValue>

<MaxValue InputMethod="Msr">199999999999</MaxValue>

<Mask Type="General" DateOnly="False">999999999999</Mask>

<Prompt1>Account Number</Prompt1>

<Prompt2>Enter/Swipe Account number</Prompt2>

<Default Editable="True">111111111111</Default>

<OKCommand>SendToHost1</OKCommand>

<FailCommand>SendToHost</FailCommand>

</Command>

5.2.2.1.16 Command Type - InputMenu

This command will display a menu and prompt the cashier to choose an option, and based on the cashier

response, the command corresponding to the option will be called.


<Prompt1> This is the primary prompt displayed to the cashier.

<Prompt2> This is the secondary prompt (help/tip displayed on the

POS).

<Target> The value of the menu item (specified by the MenuValue

attribute) will be assigned to this item.

<MenuItem> Specifies the description of the menu option.



CUSTOMER



FieldType

(Optional)

Const Specifies that the MenuItem node is a Constant (this is the

default).

Dict Specifies that the MenuItem node is a DataItem.

Index

(Optional)







Default is 1.

Position

(Optional)


MenuItem node will be extracted from this position. nn can

be a numeric value or a DataItem (for example,


If the data contained in the MenuItem node is less than



Default is 1.

Length

(Optional)


MenuItem node to be extracted. nn can be a numeric value



If the data contained in the MenuItem node is less than





StripZeroe

s (Optional)


the Value node.



Stripspace

s (Optional)





Command xxx Specifies the name of the command to be called when the

option specified in this node is selected.

MenuValue xxx Specifies the value of the MenuItem. If the item is selected,

the MenuValue specified for the item will be assigned to

the Target.

50

CUSTOMER





<BadIndexC

ommand>



be called.

<FailComma

nd>


Example

<Command Name="PromptPaymentMethod" Type="InputMenu">

<Prompt1>Select Preferred</Prompt1>

<Prompt2>Payment Method</Prompt2>

<Target>GiftCardAmount</Target>

<MenuItem FieldType="Const" Command="GetAccountNumber1"

MenuValue="10.00">Visa $10.00</MenuItem>






</Command>

5.2.2.1.17 Command Type - ItemSize

This command will count the number of characters in a DataItem and store it in the Target node.





Index

(Optional)







Default is 1.

<DataItemN

ame>

Specifies the name of the source DataItem.

<OKCommand

>


successful.



CUSTOMER



<BadIndexC

ommand>

Specifies what command to call if an invalid Index is


be called.

<FailComma

nd>


Example

<Command Name="AccountNumberDigits" Type="ItemSize">

<Target>AccountNumberLength</Target>

<DataItemName>AccountNum</DataItemName>



</Command>

5.2.2.1.18 Command Type - ListClear

This command will remove all items from a List Type DataItem.

Node Description

<DataItemName> Specifies the name of the source DataItem. If the DataItem is not List Type, the

FailCommand will be called.



Example

<Command Name="ClearItems" Type="ListClear">

<DataItemName>SelectedItems</DataItemName>



</Command>

5.2.2.1.19 Command Type - ListRemove

This command will remove an item from a List Type DataItem.


<DataItemN

ame>

Specifies the name of the source DataItem. If the DataItem

is not List Type, the FailCommand will be called.

52

CUSTOMER





Index

(Optional)







Default is 1.

<OKCommand

>


successful.

<BadIndexC

ommand>



be called.

<FailComma

nd>


Example

<Command Name="RemoveItem" Type="ListRemove">

<DataItemName Index="3">SelectedItems</DataItemName>



</Command>

5.2.2.1.20 Command Type - ListSelection

This command will display a list of items on the POS and prompt the cashier to select an item from the list. The list

of selected items is stored in the Target node.

Node Description

<Target> Specifies the destination DataItem. Target must be a List Type DataItem. If the

Target DataItem is not List Type, the FailCommand will be called.

<ListItem> Specifies the name of the source DataItem. This DataItem contains a list of items

that will be displayed on the POS. If the DataItem is not List Type, the


<SelectionLimit> Specifies the maximum items that can be selected.


<BadIndexCommand> Specifies what command to call if an invalid Index is specified, if this node is not

present, the FailCommand will be called.




CUSTOMER


Example

<Command Name="GetItemSelection" Type="ListSelection">

<Target>SelectedItems</Target>

<ListItem>1111</ListItem>

<ListItem FieldType="Dict" Index="ALL">TransactionItems</ListItems>

<ListItem>2222</ListItem>

<SelectionLimit>2</SelectionLimit>

<Prompt1>Select Items From List</Promot1>

<Prompt2>Press Enter to Select, Done if Finished</Promot2>

<OKCommand>ProcessItems</OKCommand>


</Command>

5.2.2.1.21 Command Type - ListSize

This command will count the number of items in a List Type DataItem and store it in the Target node.

Node Description

<Target> Specifies the destination DataItem. Target can be a Single or a List Type DataItem. For a

List Type DataItem, the data is assigned to the next Index, starting from 1.

<DataItemName> Specifies the name of the source DataItem. If the DataItem is not List Type, the




Example

<Command Name="CountItems" Type="ListSize">

<Target>ItemCount</Target>

<DataItemName>TransactionItems</DataItemName>



</Command>

5.2.2.1.22 Command Type - Math

This command will perform a numeric operation on two Value nodes and store the result in the Target node.

54

CUSTOMER








<Value> Specifies the data to be used, if the data extracted from

both Value nodes is not numeric, the FailCommand will be

called. Data in each Value node will be extracted and

formatted according to the following parameters:

FieldType

(Optional)


default).


Index

(Optional)

nn For List Type Value, Index specifies which item within the

list to use. nn can be a numeric value or a DataItem (for





Default is 1.

Position

(Optional)








Default is 1.

Length

(Optional)










Format

(Optional)











CUSTOMER







StripZeroe

s (Optional)


the Value node.



Stripspace

s (Optional)





<Operator> Specifies the operation to perform.

+ Numeric addition

* Numeric multiplication

- Numeric subtraction

/ Numeric division

% Numeric modulus

<OKCommand

>




<BadIndexC

ommand>



be called.

<FailComma

nd>


Multiple math operations can be performed using a single Math command. The math operations will be performed

in the order that they are specified.

Example

Single Math Operation

<Command Name="SetPayment" Type="Math"


<Value>500.15</Value>

<Operator>+</Operator>

<Value>600.75</Value>

<OKCommand>GetStoreNumber</OKCommand>


56

CUSTOMER




</Command>

Example

Multiple Math Operations

<Command Name="SetPayment" Type="Math"


<Value FieldType="Dict">PaymentAmount</Value>


<Value FieldType="Dict" Format="-.2">FeeAmount</Value>


<Value FieldType="Dict" Format="-.2">TipAmount</Value>

<OKCommand>AuthorizePayment</OKCommand>


</Command>

5.2.2.1.23 Command Type - NonMerchLookup

This command will perform a NonMerch Lookup in the POS configuration file.

Node Description

<NonMerchID> NonMerch ID for lookup.

<NonMerchDescription> This node will contain the Description of the NonMerch.

<AuthorityLevel> This node will contain the Authority Level required for the NonMerch.

<PresetAmount> This node will contain the Present Amount for the NonMerch.

<FeeAmount> This node will contain the Fee Amount for the NonMerch.



Example

<Command Name="PerformNonMerchLookup" Type="NonMerchLookup">

<NonMerchID>65</NonMerchID>

<NonMerchDescription>NonMerchDesc</NonMerchDescription>

<AuthorityLevel>RequiredAuthLevel</AuthorityLevel>

<PresetAmount>NonMerchPrice</PresetAmount>

<FeeAmount>ServiceCharge</FeeAmount>



</Command>



CUSTOMER


5.2.2.1.24 Command Type - PluLookup

This command will perform a PLU Lookup in the local store database.

Node Description

<PluNumber> PLU/SKU number for lookup.

<PluDescription> This node will contain the PLU Description.

<PluPrice> This node will contain the PLU Price.

<PluDepartment> This node will contain the Department of the PLU.



Example

<Command Name="PerformPluLookup" Tyoe="PluLookup">

<PluNumber FieldType="Dict">SkuNum</PluNumber>

<PluDescription>SkuDesc</PluDescription>

<PluDepartment>SkuDept</PluDepartment>

<PluPrice>SkuPrice</PluPrice>

<OKCommand>PerformNonMerchLookup</OKCommand>

<FailCommand>PerformNonMerchLookup</FailCommand>

</Command>

5.2.2.1.25 Command Type - Print

This command will print one Full Line on the specified print stations.


<PrintOpti

on>

Specifies the print options.

PrintStati

on (Optional)

Receipt Print the message on the Receipt printer.

Slip Print the message on the Slip printer.

Journal Print the message on the Electronic Journal.

Screen Print the message on the POS Screen. The default is

Receipt|Journal|Screen (prints on Receipt, Journal, and

POS Screen).

PrintMode

(Optional)

Normal Print the message using the Normal font.

Double Print the message using Double wide format.

58

CUSTOMER





UniqueID

(Optional)

xx Specifies the unique identifier for the printed lines. Items

with the same unique ID are only printed once for each

service.

PrintRecTy

pe (Optional)

Tender Specifies that the printing will be done over the tender

information (available during tender phase only).

TenderSigL

ine

Specifies that the lines will be printed just below where the

signature lines associated with the current tender appear

(or where they would normally appear, if they have been

disabled using the DisableSignatureLines command).

Available during tender-related phases only. Added in POS

2.3 SP07.

NonMerch Specifies that the printing will be done below the non-

merch description.

RegSaleOnl

y (Optional)

True Specifies that printing will appear on the sale, the legend

will not appear on post void or return.

<PrintLine

>

Specifies the line to be printed.

FieldType

(Optional)

Const Specifies that the PrintLine node is a Constant (this is

the default).

Dict Specifies that the PrintLine node is a DataItem.

Index

(Optional)







Default is 1.

Position

(Optional)


PrintLine node will be extracted from this position. nn



If the data contained in the PrintLine node is less than



Default is 1.

Length

(Optional)


PrintLine node to be extracted. nn can be a numeric

value or a DataItem (for example, Length="5" or







CUSTOMER




PrintLine node (or remaining length of data if Position

is specified).

Size

(Optional)

nn Specifies the final size of the PrintLine node. nn can be a


Size="LineSize").


Size, it will be padded with spaces based on the Align

Parameter.

If the data contained in the PrintLine node is greater than


The default is the length of data contained in the

PrintLine node.

Align

(Optional)

Left The data contained within the PrintLine node will be

aligned left (for example, if data is xxx, size is 8, then the

string will be "xxx "). This is the default.

Right The data contained within the PrintLine node will be

aligned right (for example, if data is xxx, size is 8, then the

string will be " xxx").

Center The data contained within the PrintLine node will be

aligned right (for example, if data is xxx, size is 8, then the

string will be " xxx ").

Margin

(Optional)

nn Specifies the left Margin for the PrintLine.

PrintLabel

(Optional)

xx Specifies the label to be printed before the PrintLine.

<OKCommand

>




<BadIndexC

ommand>



be called.

<FailComma

nd>


Example

<Command Name="PrintConfirmation" Type="Print">

<PrintOption PrintStation="Journal|Receipt|Screen|Slip" PrintMode="Normal"

UniqueID="1"/>

<PrintLine Size="40" Align="Center">BlackHawk Confirmation</PrintLine>

<PrintLine FieldType="Dict" Margin="5" Index="ALL" PrintLabel="Item

:">TransactionItems</PrintLine>

60

CUSTOMER




<OKCommand>VerifyCashierPassword</OKCommand>


</Command>

Example

<Command Name="ShowPolicy" Type="Print">

<PrintOption PrintStation="Journal|Receipt|Screen|Slip" PrintMode="Normal"

UniqueID="9"/>

<PrintLine AllowBlanks="True"/>

<PrintLine Size="40" Align="Center">-- BLACKHAWK POLICY --</PrintLine>

<PrintLine Size="40" Align="Center">-- FINAL SALE --</PrintLine>

<PrintLine Size="40" Align="Center">-- NORETURNS OR REFUNDS --</PrintLine>

<PrintLine AllowBlanks="True"/>

<OKCommand>SaveTlog</OKCommand>

<FailCommand>CancelService</FailCommand>

</Command>

5.2.2.1.26 Command Type – PrintServiceReceipts


This command will indicate how many service receipts are to be printed by the POS at the end of the transaction.

The layout of these service receipts is the same as that provided currently by the POS’s Dual Receipt Configurator

option which produces a store copy. During the printing process, the POS will print the number of service receipts

before any Dual receipts.

The POS will keep one number of service receipts variable which can be changed by all Service Configuration

Scripts (XMLs).

Only Services can trigger the printing of service receipts.

The POS literal Service Copy can be used to change the title on the service receipt.

The POS.INI option SERVICEMAXRECEIPTS=# can be used to set the maximum number of service receipts

to print. This value cannot be greater than 10.


<NumOfCoie

s>

Specifies the number of service copies to print.

<Action>

(Optional)

Specifies the Action. If this element is missing then the

command behaves as if the Action element is OVERRIDE.

ADD Adds the number of copies to the POS‘s number of service

receipts to print.

SUBTRACT Subtracts the number of copies from the POS’s number of

service receipts to print.



CUSTOMER



If an attempt is made to subtract below zero, the POS’s

number of service receipts is set to zero and the XML

command will fail.

OVERRIDE Indicates the number of service copies to print. The POS’s

number of service receipts will be set to this value.

Example

<Command Name="GenerateReceiptCopies"Type="PrintServiceReceipts">

<NumOfCopies>2</NumOfCopies>

<Action>ADD</Action>

<OKCommand>NextCommand</OKCommand>

<FailCommand>CancelCommand</FailCommand>

</Command>

5.2.2.1.27 Command Type - Start

Each phase should contain one Start type command. This command specifies the starting point of execution for

a phase.

Example

<Command Name="StartService" Type="Start">

<OKCommand>SetServiceInfo</OKCommand>

</Command>

5.2.2.1.28 Command Type - SupervisorAuthorize

This command will prompt for the Supervisor authorization.

Node Description


<Target> Specifies the destination DataItem. This node will contain the ID of the authorizing

supervisor. Target can be a Single or a List Type DataItem. For a List Type DataItem,

the data is assigned to the next Index, starting from 1.

<AuthorityLevel> Required authority level.



62

CUSTOMER




Example

<Command Name="GetSupervisorAuth2" Type="SupervisorAuthorize">

<Prompt2>enter Supervisor password</Prompt2>

<Target>SupervisorID</Target>

<AuthorityLevel>4</AuthorityLevel>

<OKCommand>GetSuperviroKey</OKCommand>


</Command>

5.2.2.1.29 Command Type - SupervisorKey

This command will prompt for the Supervisor key.

Node Description




Example

<Command Name="GetSupervisorKey" Type="SupervisorKey">

<Prompt2>Turn key to Supervisor mode</Prompt2>

<OKCommand>GetItemSelection</OKCommand>

<FailCommand>Addanitem</FailCommand>

</Command>

5.2.2.1.30 Command Type - VoidItem

This command will void an item from the current POS transaction.


<ItemID> Specifies the item to be voided, non-merch ID if voiding a

non-merchandise or SKU/PLU number if voiding a

merchandise item.

ItemType NonMerch Specifies that a non-merchandise item needs to be voided

from the transaction.

Merch Specifies that a merchandise item needs to be voided from

the transaction.



CUSTOMER



<OKCommand

>


successful.

<BadIndexC

ommand>



be called.

<FailComma

nd>


Global Variables

The following Global variables can be used within the XML configuration.

Global Variable Description

@STORE Current POS Store number

@REGISTER Current POS Terminal/Register number

@CASHIER Current Signed on Cashier number

@TRANSACTION Current POS Transaction number

@BUSINESSDATE Current POS Business Date in DDMMYYYY format.

@CURRENTDATE Current POS Date in DDMMYYYY format.

@CURRENTTIME Current POS Time in HHMMSS format.

www.sap.com/contactsap


No part of this publication may be reproduced or transmitted in any

form or for any purpose without the express permission of SAP SE

or an SAP affiliate company.

SAP and other SAP products and services mentioned herein as well

as their respective logos are trademarks or registered trademarks of

SAP SE (or an SAP affiliate company) in Germany and other

countries. All other product and service names mentioned are the

trademarks of their respective companies. Please see http://www.

sap.com/corporate-en/legal/copyright/index.epx#trademark for

additional trademark information and notices.

http://www.sap.com/corporate-en/legal/copyright/index.epx#trademark

http://www.sap.com/corporate-en/legal/copyright/index.epx#trademark

sap pos 2.3 services configuration guide

Documents