2 Server Mode
This chapter describes the configuration of running EFTLink within Server mode.
EFTLink Server
EFTLink is usually deployed as a service application running on each POS and connecting to a single payment device. To support environments where the POS runs as a thin-client application with restricted local device access, or where the hardware has limited processing power or memory, EFTLink can be deployed in Store Server mode.
A single EFTLink application runs on a designated server system and all POSs connect to that one server. EFTLink manages the connections to multiple payment terminals and routes payment requests from each POS on to the relevant device.
EFTLink Server has two distinct modes that offer different use cases. A static mapping where a 1-1 logical connection between POS and payment terminal is still used or for EFTLink to make a dynamic selection of payment terminal based on its availability and convenience. This is referred to as PED-pooling (PED - PIN entry Device).
EFTLink Server - (static one-to-one)
An EFTLink server is essentially multiple instances of EFTLink running where each instance is communicating over its own TCP socket. This allows for a POS/register and the EFTLink instance to have a static 1-1 mapping where each EFTLink instance can communicate using one or more active cores to the corresponding PSP’s.
Figure 2-1 EFTLink Server - static one-to-one
The diagram above shows EFTLink Server running 4 instances of EFTLink which bridges a POS to a dedicated PSP. This configuration can be achieved by following the below configuration steps.
Within the EFTLink installation directory (for example, c:\eftlink) you will need the following:
-
EFTLink is started using class:
manito.eft.opi.server.MultiServerLauncher -
Within the EFTLink installation directory 4 subfolders (Server<n>) are required and each folder will be used as a working directory for each instance.
C:\eftlink\Server1
C:\eftlink\Server2
C:\eftlink\Server3
C:\eftlink\Server4
The EFTLinkConfig.properties file within the root
of the EFTLink Installation directory is used to spin up the required
number of EFTLink Instances and to read-in the values specified within
theEFTLinkConfig.properties file. To achieve a four-server
configuration please ensure the property key NumServers value
is set to “4”.
For example, NumServers = 4
Once you have customised the EFTLinkConfig.properties file that exists in the root of the EFTLink installation directory.
It is necessary to copy this file to:
-
The root of the "xstore" Installation folder or "xstoredata\xstore" folder (for v22 or greater) as this is needed by the EFTLink (client) API library that xstore Interfaces with to build the requests and parse the EFTLink responses.
-
Each Server<n> folder. Once copied the file under the server<n> folder can be further modified for any specifics to that instance. For example, the active core being used such as EPSCore<n> property key.
An example (snippet) layout of how each configuration file would be is as follows:
|
Installation root and Xstore (Not applicable for communication over websockets)
ServerChannel0 = 10100 NumServers = 4 Xstore (ws1 – ws3)
Server 1
EPSCore0 = oracle.eftlink.opiretail.OPIRetailCore
EPSAddress = 192.168.1.11 EPSPort = 8443 Server 2
EPSCore0 = oracle.eftlink.opiretail.OPIRetailCore
EPSAddress = 192.168.1.12 EPSPort = 8443 |
Server 3
EPSCore0 = oracle.eftlink.opiretail.OPIRetailCore LineDisplayEnabled=false
EPSAddress = 192.168.1.13 EPSPort = 8443 Server 4
EPSCore0 = oracle.eftlink.opiretail.OPIRetailCore EPSCore1 = oracle.eftlink.paypal.PayPalCore LineDisplayEnabled=true DelegateLineDisplay = true LineDisplayDelegateList = 0 EwalletCore = 1
ServerChannel0 = 10100 NumServers = 1 Pos30 = 10140 PEDPoolEnabled = false
EPSAddress = 192.168.1.14 EPSPort = 8443 |
The above example illustrates that each server can differ its configuration. For example, Server 1 and 2 only differ in terms of core properties file where both point to their respective providers endpoint address and port.
Server 3 will automatically block any sale state notifications reaching the opiretail core.
Server 4 configuration harnesses the EFTLink rest-api service to interpret the websocket requests from the POS along with adding in an additional core to reroute any EWallet requests to core 1. Any sale state notifications coming in will only be forwarded to core 0.
EFTLink Server - PEDPooling
Many-to-many mapping between POS and payment system/terminal. Each POS is allocated a fixed pair of sockets (channel 0/1) that connect to a multiplexer/switch. The multiplexer implements rules and/or uses interactive dialogs with the POS operator to determine which EFTLink instance to pass the request on to.
Figure 2-2 EFTLink Server - PEDPool Remote Mode
The diagram above shows EFTLink Server running 3 instances of EFTLink which are serving four clients. Three of the clients are communicating directly by TCP sockets whereas the fourth client is using websockets so requires the EFTLink Rest-api-client to interpret the requests into EFTLink.
An example (Snippet) layout of how each configuration file would be as follows:
|
EFTLink Installation root and Xstore (Not applicable for communication over websockets)
ServerChannel0 = 10100 PEDPoolEnabled = true PEDPoolOneCatchAllChannel0 = true NumServers = 3 server1.description = EFT1 server2.description = EFT2 server3.description = EFT3 NumClients = 4 pos1.description = Desktop POS 1 pos2.description = Desktop POS 2 pos3.description = Desktop POS 3 pos30.description = Tablet POS 31 pos1.subpool = EFT1, EFT2, EFT3, EFT4 pos2.subpool = EFT1, EFT2, EFT3, EFT4 pos3.subpool = EFT1, EFT2, EFT3, EFT4 pos30.subpool = EFT1, EFT2, EFT3, EFT4 Xstore (ws 1 - ws3)
<Host dtype="String">socket://localhost:10110</Host> Server 1
EPSCore0 = oracle.eftlink.opiretail.OPIRetailCore
EPSAddress = 192.168.1.11 EPSPort = 8443 Server 2
EPSCore0 = oracle.eftlink.opiretail.OPIRetailCore
EPSAddress = 192.168.1.12 EPSPort = 8443 |
Server 3
EPSCore0 = oracle.eftlink.opiretail.OPIRetailCore LineDisplayEnabled=false
EPSAddress = 192.168.1.13 EPSPort = 8443 Server 4
EPSCore0 = oracle.eftlink.opiretail.OPIRetailCore EPSCore1 = oracle.eftlink.paypal.PayPalCore LineDisplayEnabled=true DelegateLineDisplay = true LineDisplayDelegateList = 0 EwalletCore = 1 EFTLink-rest-api.properties ServerChannel0 = 10100 NumServers = 3 pos1= 10110 pos2 = 10120 pos3 = 10130 pos30 = 10140 PEDPoolEnabled = true
EPSAddress = 192.168.1.14 EPSPort = 8443 |
Configuration of EFTLink Server (static) or PEDPooling (dynamic)
As a base, EFTLink should first be installed using the standard installation procedure. Please refer to the Oracle Retail EFTLink Framework Installation and Configuration Guide located on OHC and refer to the chapters “Runnable Installer/Upgrader Jar” or “Manual Installation” and Post Installation Steps before continuing. Now perform the additional steps:
Enabling Server
EFTLink Server requires a different starting class: manito.eft.opi.server.MultiServerLauncher
Please follow the step below to activate this class.
Use a text editor to edit EFTLink folder/wrapper/conf/eftlink.conf.
Replace: wrapper.app.parameter.1=manito.eft.opi.server.OPIServer
With: wrapper.app.parameter.1=manito.eft.opi.server.MultiServerLauncher
This can be done by commenting out all wrapper.app.parameter.1 and license details for manito.eft.opi.server.OPIServer and uncomment all license details for manito.eft.opi.server.MultiServerLauncher.
EFTLink - Server (static one-to-one)
Using the Oracle Retail EFTLink Framework Installation and Configuration Guide whereby the choice of the installation type was “server” then some of the configuration should have been completed automaticall. However, further configuration is still required.
Please confirm that there is a correct number of Server<n> folder
created and the eftlinkconfig.properties file and
the core properties file exist and configured to your needs.
You can assign a friendly name/description to each EFTLink instance
so that it is easier to trace through the logs. To do this please
edit the eftlinkconfig.properties within the EFTLink
installation root.
For the number servers specified (“NumServers”) ensure there is a server<n>.description key and that the value set is your preferred descriptive choice.
For example,
NumServers = 4
server1.description = EFT Server 1
server2.description = EFT Server 2
server3.description = EFT Server 3
server4.description = EFT Server 4
It is necessary to now copy the eftlinkconfig.properties file held within eftlink installation root to Xstore so they are
identical. Please refer to figure 2-2 example configuration for further
information.
EFTLink - Server – PEDPool (dynamic)
Note:
It is important to point out that the EFTLink PED pooling functionality is restricted by Core compatibility. Therefore please check the core guide documentation. Also note the following restrictions:
PED pooling is only applicable within the <CardServiceRequest> context, that is, this is when the actual payment is initiated and finalized.
<SaleStateNotification> are supported in limited capacity and only when a server instance is marked “*” as a dedicated default to a POS through the pos<ws Id>.subpool list
Using the Oracle Retail EFTLink Framework Installation and Configuration Guide whereby the choice of the installation type was “Server + PedPooling” then some of the configuration would have been completed automatically. However, further information is required.
Please confirm that there is a correct number of Server<n> folder
created and the eftlinkconfig.properties file and
the core properties file exist and configured to your needs.
In PED Pooling mode it is mandatory that you can assign a friendly name/description to each EFTLink instance as this is the text that will be display to the operator upon the pool list.
For the number servers specified (“NumServers”) ensure there is a “server<n>.description” key and that each value is set to your preferred descriptive choice.
To do this please edit the eftlinkconfig.properties within the EFTLink installation root.
For example,
NumServers = 4
server1.description = Menswear Suits - Terminal 1
server2.description = Menswear Suits - Terminal 2
server3.description = Menswear Suits - Terminal 3
server4.description = Menswear Suits - Terminal 4
When PED pooling has been enabled, the system uses the standard channel 1 display messages to present each POS operator with a list of available payment terminals. By default, the list will include all available terminals, but this can be confusing in a large store, so there is an option to limit each POS to a subset of the full list to show just the terminals in one department. The subset is defined using the descriptive names from EFTLink Instance Set Up and specified as a comma-separated list. A default association can be set by prefixing the descriptive name with '*'. If that payment terminal is available, it will be automatically used without any operator prompting.
For example,
pos1.subpool = *Menswear Suits - Terminal 1, Menswear Suits - Terminal 3, Menswear Suits - Terminal 4
pos2.subpool = *Menswear Suits - Terminal 2, Menswear Suits - Terminal 3, Menswear Suits - Terminal 4
pos3.subpool = Menswear Suits - Terminal 3, Menswear Suits - Terminal 4
…
pos10.subpool = Menswear Suits - Terminal 3, Menswear Suits - Terminal 4
POS Client Set Up
For the number of Clients (“NumClients”) specified in the eftlinkconfig.properties file ensure that you have a pos<n>.description
key and that its value is set to your preferred descriptive choice.
These are the names that will be shown in the EFTLink log to ease
tracking/debugging
To do this please editeftlinkconfig.properties within the EFTLink installation root.
For example,
NumClients = 10
pos1.description = Menswear-suits – register 1
pos2.description = Menswear-suits – register 2
…
pos10.description = Menswear-suits – register 10
Each POS must use a unique pair of ports for its connection to
EFTLink. These do not need to be further defined withineftlinkconfig.properties but the ports numbers and EFTLinkServer system IP must be set on
each POS. The numbering system is based on EFTLink base address (default
10100, configurable by the ServerChannel0 property) plus 10 x the
POS number. Two sequential ports are needed, one for each of channel
0 and 1.
For example,
POS1 - ServerChannel0 = 10110, ServerChannel1 = 10111
POS2 - ServerChannel0 = 10120, ServerChannel1 = 10121
POS3 - ServerChannel0 = 10130, ServerChannel1 = 10131
...
POS9 - ServerChannel0 = 10190, ServerChannel1 = 10191
POS10 - ServerChannel0 = 10200, ServerChannel1 = 10201
If this range of ports is not available, the base number can be changed via the ServerChannel0 setting. All POSs must then be changed to match.
Log4J2 Setup
The Log4j2.xml logging configuration file as standard is delivered configured for Single server mode. Alterations are required to the log4j2.xml file to ensure logging is performed per pos, and per server. To enable full logging, modify the standard log4j2file by performing the following steps:
-
Alter the <Properties> section, adding in the correct number of servers, and pos, ensuring each has a unique name and filename.
-
In the <Appenders> section, enable the RollingRandomAccessFile entries for each server/pos by removing the comment start <!-- and comment end --> for the marked MultiServerLauncher/PedPooling section.
-
Adjust the number of the RollingRandomAccessFile entries in the <Appenders> section by adding the relevant number of server{x}_log and pos{x}_log sections. Ensure each of these maps to the correct filename (defined in point 1) and adjust the filepattern to use the relevant server folder / server filename. The number of server{x}_log and pos{x}_log entries in the <Appenders> section should match the number of server{x}_log and pos{x}_log entries in the <Properties> section.
-
Also in the <Appenders> section, enable the Async entries for each server/pos by removing the comment start <!-- and comment end --> for the marked MultiServerLauncher/PedPooling section.
-
Adjust the number of the Async entries in the <Appenders> section by adding the relevant number of server{x}_log and pos{x}_log sections. Ensure each of these maps to the correct server{x}_log or pos{x}_log (defined in point 3).
-
In the <Loggers> section, enable the Logger entries for each multifile.server{x}/multifile.pos{x} by removing the comment start <!-- and comment end --> for the marked MultiServerLauncher/PedPooling section.
-
Adjust the number of the Logger entries in the <Loggers> section by adding the relevant number of multi-file.server{x} and multifile.pos{x} sections. Ensure each of these maps to the correct async_server{x}_log or async_pos{x}_log (defined in point 5).
Once fully configured, each pos request will write to a file in the main EFTLlink log folder named pos{x}.log. In addition, each server folder will contain its own log file showing server processing of the request - log files for each server will be in the path server{x}/log/server{x}.log.
Xstore Set Up
As noted above, each POS must use a unique pair of ports for its connection to EFTLink. Also, the POS is configured to access a remote EFTLink rather than a local one.
There are two different ways that Xstore can be set up to use with EFTLink in Server Mode.
-
One to One Port Mapping (applies to both Xstore and Xstore Mobile)
-
One to Many Port Mapping (applies to both Xstore and Xstore Mobile)
All configurations illustrated below are part of the Xstore
AuthConfig.xmlconfiguration file.
One to One Port Mapping
(Static Server Mode)
This is where there is one Xstore or Xstore Mobile client served from the Jetty instance. It will divert all requests to a single port pairing that is managed inside the EFTLink Server instance. If another POS client is configured to use the same port pairing, it will potentially be blocked out until the port pair becomes free. In this mode, EFTLink Server will allow a single device to use many PEDs through the PED pooling functionality. EFTLink Server does not support load balancing of requests through one port pair so this configuration is not recommended if there are many Xstore mobile clients in the store solution.
If this configuration is suitable then the Xstore Mobile configuration is identical to the standard Xstore configuration. The 'communicatorHosts' parameter is used to set the channel 0 URL and 'deviceCommChannel' is used to set the channel 1 URL, as illustrated below. In this configuration when Xstore or Xstore Mobile starts an authorization request EFTLink will process the authorization request in the expected way, or if PED pooling is enabled, it will send a list of available PEDs for an associate to choose. Once the associate has chosen a PED, the authorization will proceed in the expected way.
<AuthProcess name="EFT_LINK_HOST" Abstract="true">
<Parameter name="communicatorHosts">
<param_value dtype="List">
<Host dtype="String">socket://localhost:10100;timeout=1000</Host>
</param_value>
</Parameter>
<Parameter name="deviceCommChannel" value="socket://localhost:10101" />
...
...
<Parameter name="additionalWorkstationHostsMap">
<param_value dtype="Map">
<MapEntry>
<key dtype="Integer">1</key> <!-- workstation id -->
<value dtype="EFTLinkCommunicationChannels">
<Channel0 dtype="String">socket://localhost:10110</Channel0>
<Channel1 dtype="String">socket://localhost:10111</Channel1>
</value>
</MapEntry>
<MapEntry>
<key dtype="Integer">2</key> <!-- workstation id -->
<value dtype="EFTLinkCommunicationChannels">
<Channel0 dtype="String">socket://localhost:10120</Channel0>
<Channel1 dtype="String">socket://localhost:10121</Channel1>
</value>
</MapEntry>
</param_value>
</Parameter>
</AuthProcess>One to Many Port Mapping
(PED Pooling)
In order to setup Xstore this way, the EFTLinkConfig.properties in the main folder in EFTLink (for example, C:\eftlink) should be
copied in the working directory of Xstore or Xstore mobile (for example,
C:\xstore or C:\xstoremobile). The list of POS, should be the same
as in the EFTLink server side.
pos1.description = POS 1
pos2.description = POS 2
pos3.description = POS 3
The additional WorkstationHostsMap parameter is not needed anymore. If the default channel zero is used (for example, ServerChannel0 = 10100), then make sure to update the port in the Host section of the communicatorHosts to 10110. If ServerChannel0 is different, simply add 10 to it. Then deviceCommChannel's port is plus 1 of the Host's port.
<AuthProcess name="EFT_LINK_HOST" Abstract="true">
<Parameter name="communicatorHosts">
<param_value dtype="List">
<Host dtype="String">socket://localhost:10110;timeout=1000</Host>
</param_value>
</Parameter>
<Parameter name="deviceCommChannel" value="socket://localhost:10111" />
...
...
</AuthProcess>Included with EFTLink is an additional file EFTLinkConfig_XStore_Mobile.properties. This is a sample file demonstrating the required settings for the
file EFTLinkConfig.properties on the POS.
This file should be copied over to the POS Client as EFTLinkConfig.properties.