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.

Generally, using Server mode, there is still a 1-1 logical connection between POS and payment terminal, but it is also possible for EFTLink to make a dynamic selection of payment terminal based on availability and convenience. This is referred to as PED-pooling (PED - PIN entry Device).

Similarly, the EFTLink Server can be used to manage a pool of printers shared between the POSs and allocated dynamically. This is referred to as Print-pooling.

This solution is only possible with IP-based payment terminals and printers. The server system should be in a secure room, and the terminals/printers spread around the store, so direct wired connections are not practical.

The standard EFTLinkConfig.properties will ensure EFTLink is configured for use as an EFTLink Server.

• EFTLink Server - Remote Mode

• MultiJVM

• EFTLink Server - PEDPool Remote Mode

• Configuring EFTLink Server

EFTLink Server - Remote Mode

1-1 mapping between the POS and payment system/terminal. Each POS is allocated a fixed pair of sockets (channel 0/1) that connect to a dedicated EFTLink instance.

Figure 2-1 EFTLink Server - Remote Mode

Included with EFTLink is an additional file EFTLinkConfig_Static_Server.properties. This is a sample file demonstrating EFTLink configuration in this mode.

EFTLinkConfig_Static_Server.properties can be used in place of the standard EFTLinkConfig.properties by renaming this file to EFTLinkConfig.properties. A manual comparison of the files will be necessary to ensure core configuration which is set during installation is copied over to the RemoteMode configuration.

MultiJVM

Note:

This functionality is currently incompatible with the PEDPoolEnabled property.

This property is used to launch each OPIServer in their own Java Virtual Machine (JVM) process when the NumServers property is set to greater than 0.

Each server's channel 0 and channel 1 ports are based on the ServerChannel0 setting. For example, if the ServerChannel0 is set to 10100 and NumServers is set to 3, the additional servers will be created on channel 0 ports 10110, 10120, 10130 and the corresponding channel 1 ports will be 10111, 10121, 10131 therefore, you must ensure that these ports are available for use with EFTLink.

For each server defined under NumServers; EFTLink looks for a corresponding server folder. For example, if NumServers is set to 3, EFTLink looks for server folders named server1, server2 and server3 under the EFTLink directory. These folders must contain their own configuration files, that is; EftLinkConfig.properties and so on.

In order to use this property, you must use the MultiServerLauncher application rather than the OPIServer application.

EFTLink Server - PEDPool Remote Mode

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

Included with EFTLink is an additional file EFTLinkConfig_PED_Pool.properties. This is a sample file demonstrating EFTLink configuration in this mode.

EFTLinkConfig_PED_Pool.properties can be used in place of the standard EFTLinkConfig.properties by renaming this file to EFTLinkConfig.properties. A manual comparison of the files will be necessary to ensure core configuration which is set during installation is copied over to the PEDPool configuration.

Configuring EFTLink Server

Configuring/deploying EFTLink Server is rather more complicated that standard EFTLink and is currently only possible as a manual procedure.

As a base, EFTLink should first be installed on the chosen server system using the standard installation procedure.

• Enabling Server Mode

• EFTLink Instance Set Up

• PED Pooling Set Up

• Xstore Set Up

Enabling Server Mode

EFTLink Server uses a different main class from normal.

When not using the standard Tanuki wrapper / eftlink.bat file to start eftlink, replace the following lines where applicable in the startup file:

Windows

Replace: java manito.eft.opi.server.OPIServer

With: java manito.eft.opi.server.MultiServerLauncher

Linux

Replace: java -cp $CLASSPATH manito.eft.opi.server.OPIServer

With: java -cp $CLASSPATH manito.eft.opi.server.MultiServerLauncher

Tanuki Wrapper Configuration

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 sone 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 in the section below.

PED Pool

Replace: PEDPoolEnabled = false

With: PEDPoolEnabled = true

Replace: PEDPoolOneCatchAllChannel0 = false

With: PEDPoolOneCatchAllChannel0 = true

See PED Pooling Set Up for more information.

EFTLink Instance Set Up

Each instance of EFTLink is identified by a unique sequence number starting from 1.

For each instance of EFTLink required (that is, for each payment terminal):

1. In the main eftlink folder, run installcore.bat as if configuring standalone EFTLink. This will setup the EftlinkConfig.properties file.

2. Create a subfolder under the main eftlink folder named serverN, where N is the sequence number.

3. Copy all properties files (*.properties) from the main eftlink folder into the new serverN folder.

   This excludes the sample files EftlinkConfig_PED_Pool.properties, EftlinkConfig_Static_Server.properties and EftlinkConfig_Xstore_Mobile.properties. EFTLink and core specific files are required, including language files. For some cores, additional files may also need to be copied over (such as receipt.txt files) - to see the full list of required files, refer to the cores\[corename] sub-folder.

4. Using a text editor, edit the core-specific properties file in the subfolder to set any properties that are unique for each core instance for example, the terminal IP.

5. Using a text editor edit EftlinkConfig.properties in the main eftlink folder:

   Find the NumServers setting and change it to be the number of EFTLink instances to be used. Un-comment (that is, remove the leading '#' if present) if necessary. For example, NumServers = 2.

6. For each EFTLink instance, assign a descriptive title. These are the names that will be presented to the operator and should identify the relevant payment terminal in some way such as by its location, for example:

   server1.description = Menswear-suits

   server2.description = Menswear-paydesk #2 till 1

   Note:

   Spaces are allowed in the descriptive names, but not commas if PED pooling is to be used.

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:

1. Alter the <Properties> section, adding in the correct number of servers, and pos, ensuring each has a unique name and filename.

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

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

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

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

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

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

POS Client Set Up

Each POS client is identified by a unique sequence number starting from 1.

1. Use a text editor to edit EftlinkConfig.properties in the main eftlink folder:

   Find the NumClients setting and change it to be the number of POSs that will be using EFTLink. Un-comment (that is, remove the leading '#' if present) if necessary. For example, NumClients = 2

2. For each POS, assign a descriptive title. These are the names will be shown in the EFTLink log to ease tracking/debugging, for example:

   pos1.description = Menswear-suits

   pos2.description = Menswear-mobile#1

3. Each POS must use a unique pair of ports for its connection to EFTLink. These do not need to be further defined within EftlinkConfig.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. This gives a default allocation of:

   POS1 - 10110/10111

   POS2 - 10120/10121

   POS3 - 10130/10131

   ...

   POS9 - 10190/10191

   POS10 - 10200/10201

   POS11 - 10210/10211

   and so on

   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.

PED Pooling Set Up

If 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

pos2.subpool = Menswear-suits, *Menswear-paydesk #2 till 1, Menswear-paydesk #2 till 2

Note:

It is important to point out that the EFTLink PED pooling functionality is restricted by Core compatibility. Please 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.

PED pooling is not currently applicable within the <SaleStateNotification> context, that is, if the EPS supports a device that is dependent on a line display, this functionality will need to be suppressed by Xstore or the Core (depending on configuration).

PED pooling is not possible where the EPS requires the register to be paired with a single device thereby forcing a one-to-one relationship between the register and the device.

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.xml configuration 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 the POS Client as EFTLinkConfig.properties.