| Oracle® Retail EFTLink Framework Installation and Configuration Guide Release 20.0.1 F43333-01 |
|
 Previous |
 Next |
| Oracle® Retail EFTLink Framework Installation and Configuration Guide Release 20.0.1 F43333-01 |
|
Previous |
Next |
This chapter describes the installation of EFTLink and covers the following topics:
To install EFTLink successfully system implementers must:
Understand the requirements of the specific EFT system being used, and the POS software that will be connecting to EFTLink.
Understand the configuration settings held in property files which control how EFTLink and the selected core behave. System implementers must know how to add or modify properties within property files with their chosen text editor.
Java properties are case sensitive, and never contain spaces in the property name. They usually do not contain spaces in the property value – there are sometimes exceptions in lists.
A space is allowed before and after the = that separates the property from its value.
Case sensitivity does not apply to Boolean values – True is the same as true.
Each property = value is a separate line.
Lines prefixed with # are comments.
EFTLink can be installed on Windows or Linux operating systems, but the procedure will differ accordingly.
|
Note: Oracle Retail assumes that the retailer has ensured its Operating System has been patched with all applicable Windows updates. |
The POS system should meet the following minimum requirements.
256MB RAM
Intel Celeron 1GHz or equivalent CPU
1GB disk space.
EFTLink is supported on the following Operating Systems:
Oracle Enterprise Linux 7
Windows POSReady 7
Windows 7
Windows 10
Windows 10 IOT Enterprise LTSB 2016 (1607)
EFTLink framework will run with any version of Java from 1. 8 whereas all strategic cores are binary compatible to Java 1.7.
EFTLink by default expects Java jre to exist in the folder location C:\jre (on Windows) or /opt/jre (on a Linux kernel).
To change the default location of java you will need to update either include-eftlink-windows.conf or include-eftlink-linux.conf which are located in <installation directory>\wrapper\conf.
This may be required in situations where a specific version of jre is required, such as where a different version of the jre is required to that which is being used by the POS, which may also be using the location c:\jre. See the Oracle Retail EFTLink Core Configuration Guide for any core jre requirements.
|
Note: This section describes how to install EFTLink using the installer jar.Follow the steps below to install EFTLink. |
The eftlink-20.x-installer.jar and eftlink-20.x-upgrader.jar are runnable and if executed will perform a silent installation/upgrade by default.
To perform a silent installation requires a pre-populated ant.install.properties file to exist within the same directory as the runnable jars.
Lists each mandatory setting for the ant.install.properties file.
Table 2-1 Mandatory Installer Settings
| Setting | Description | Default | Example |
|---|---|---|---|
|
installDir |
Installs EFTLink to the directory specified. Note: When upgrading EFTLink the installDir property setting must point to the existing directory where EFTLink is installed. |
C\:\\eftlink |
|
|
eftlinkChannelZeroPortNumber |
Configures EFTLink eftlinkConfig.properties ServerChannel0 property setting. Note: Not applicable when running the |
10100 |
|
|
eftlinkChannelOnePortNumber |
Configures EFTLink eftlinkConfig.properties ServerChannel1 property setting. Note: Not applicable when running the |
10101 |
|
|
selectedCore |
EFTLink will install and automatically configure itself to use the class path entered here. Note: Not applicable when running the |
|
Unzip the vxx.x.x.xxx.installer.zip file somewhere other than the desired target directory which is typically C:\eftlink or /opt/eftlink for Linux.
Make sure that Java is on the path of the system. In Linux, JAVA_HOME is also required to be set.
Navigate to the path where you extracted the installer zip file.
For example, C:\<user>\Downloads or ~/Downloads).
Review the supplied ant.install.properties file and make changes if necessary. For example if performing an upgrade then ensure the installDir property setting points to the existing directory where EFTLink is currently installed.
Open a terminal (using elevated privilege) ensuring the directory is set to where the install/upgrader jars are located.
Running the installer:
Command to launch the installer.
*(Windows) java -jar eftlink-(xx.x.x.x)-installer.jar or
(Linux) sudo . java -jar eftlink-(xx.x.x.x)-installer.jar
* Please ensure the property key "selectedCore" is populated with the desired core clashpath within the ant.install.properties file before running the jar. If preferred the installer jar has a graphical user interface which can be accessed during installation by adding "gui" to the end of the command statement (separated by a space). For example eftlink-(xx.x.x.x)-installer.jar gui.
The installation will end with the OPI Service being installed.
Within the EFTLink installation directory, copy from C:\<eftlink installation folder>\keys folder the pos.private.jks and eftlink.public.jks files to the POS (for example C:\xstore\keys).
Running the upgrader:
Command to launch the upgrader.
*(Windows) java -jar eftlink-(xx.x.x.x)-upgrader.jar or
(Linux) sudo . java -jar eftlink-(xx.x.x.x)-upgrader.jar
Once the upgrade is complete your eftlink installation directory should be updated but all configuration properties settings should have been retained.
Close down the terminal and remove installations files / backup files if necessary.
Start EFTLink. In the terminal, navigate to the installation directory, for example, C:\eftlink or /opt/eftlink.
*Windows: start eftlink.bat
Linux: ./eftlink.sh start
*In Windows, you can also start the OPI Server in the services panel.
This section describes the installation sequence of EFTLink.
A folder should be created or designated for the EFTLink package. This folder can be any name and location, the only restriction is that there should be no spaces in the path. Conventionally you may wish to use the name eftlink.
EFTLink is supplied as a zip file, eftlink_v20.0.zip, and should be unzipped into the designated folder. All files needed, including the entire set of core files are included.
Once unzipped, the following files and folders should be present in the designated EFTLink folder:
Table 2-2 List of Unzipped Files and Folders
| Files/Folder | Comment |
|---|---|
|
apidocs |
Folder containing the API documentation for the framework. |
|
linux |
Folder containing files for tanuki wrapper. |
|
linux_64 |
Folder containing files for tanuki wrapper. |
|
windows |
|
|
windows 64 |
|
|
wrapper |
|
|
cores |
Each core sub-directory contains the core jar file, and reference copies of that core's property file(s). |
|
lib |
The lib folder contains supporting files for EFTLink. |
|
log |
Folder containing the log files. |
|
tmp |
Working folder for EFTLink. |
|
CardRange.xml |
The default tender mapping and card identification file. |
|
CreateKeys.bat |
A batch file used to create encryption keys to ensure secure communications between POS and EFTLink. |
|
CreateKeys.sh |
A Linux script used to create encryption keys to ensure secure communications between POS and EFTLink. |
|
eftlink.bat |
A batch file used to launch the eftlink application. |
|
eftlink.sh |
A Linux script used to launch the eftlink application. |
|
eftlink.jar |
The main executable code of the EFTLink framework. |
|
EftLinkConfig.properties |
Carries the settings for the framework. |
|
EftlinkConfig_PED_Pool.properties |
Carries the framework settings for use with PED pooling mode. |
|
EftlinkConfig_Static_Server.properties |
|
|
EftlinkXstore_Mobile.properties |
|
|
Eftlink-rest-api.bat |
A batch file used to launch the rest API application. |
|
Eftlink-rest-api.jar |
Executable code of the rest API application. |
|
Eftlink-rest-api.properties |
|
|
Eftlink-rest-api.sh |
A Linux shell script used to launch the rest API application. |
|
Eftlink-rest-api-log4j2.xml |
Log4j2 configuration file. |
|
installcore.bat |
A windows batch file script which sets one of cores (contained within the cores folder) as active. |
|
installcore.sh |
A Linux shell script which sets one of cores (contained within the cores folder) as active. |
|
Jetty.xml |
|
|
LangCN.properties |
Language files. |
|
LangDE.properties |
|
|
LangEN.properties |
|
|
LangES.properties |
|
|
LangFR.properties |
|
|
LangIT.properties |
|
|
LangJP.properties |
|
|
LangNL.properties |
|
|
LangPT.properties |
|
|
LangRU.properties |
|
|
LangSV.properties |
|
|
Log4j2.xml |
Log4j2 configuration file. |
To set an active core open a terminal and change the directory to the EFTLink installation path and type:
For Windows, installcore.bat <core name>
For Linux run installcore.sh <core name>
For example, installcore pointus would set the PointUS core as the active core.
|
Note: The core name is not case sensitive in the batch file or Linux script. |
The batch or script file does two things:
Configures EftlinkConfig.properties:
EPSCore0=manito.eft.pointus.PointUSCore
Copies the selected core property file from the specific core folder to the main EFTLink folder, where it will be the active file, in this instance pointus.properties.
If this is done manually you would need to edit EftLinkConfig.properties.
EPSCore0=
The value is the full classpath to the selected core application. These are the valid classpaths:
Table 2-3 Core Classpath
| Core | Classpath |
|---|---|
|
Adyen |
manito.eft.adyen.AdyenCore |
|
AJB FIPay |
manito.eft.ajb.FIPayCore |
|
Cayan |
manito.eft.cayan.CayanCore |
|
Merchant Link |
manito.eft.poslynx.PoslynxCore |
|
OPI Retail |
oracle.eftlink.opiretail.OPIRetailCore |
|
PayPal |
oracle.eftlink.paypal.PayPalCore |
|
Six Payment Services MPD |
manito.eft.sixpay.SixpayMPDOPIClient |
|
Tender Retail |
manito.eft.tenderretail.TenderRetailCore |
|
The Logic Group SolveConnect |
manito.eft.solveconnect.SolveConnectCore |
|
Verifone Ocius Sentinel |
manito.eft.ocius_sentinel.OciusSentinelCore |
|
Verifone Point US |
manito.eft.pointus.PointUSCore |
|
WorldPay |
manito.eft.worldpay.WorldPayCore |
This section describes how to install EFTLink as a service.
It is possible to install EFTLink as a windows service, using a third party wrapper. EFTLink is distributed with a version of Tanuki Software Limited Java Service Wrapper.
Follow the steps below on how to configure EFTLink to run as a Windows service.
Download and install Java.
Ensure you have the correct version of Java installed.
For example: if the target machine has a 64 bit OS with default 64 bit Java active but you want to use a 32 bit service wrapper, then ensure you also have the required 32 bit Java installed.
Installing the Service.
From a command line (with administrative privileges) change to the root directory for EFTLink. For example, type cd /eftlink.
If not already done, run installcore.bat to install the desired core which also creates and copies the necessary wrapper to .\bin. For example, type installcore.bat adyen.
To install EFTLink as a window service, type eftlink install.
If there are problems during install, it is possible to remove the service by typing eftlink remove. This may be necessary if the service is previously installed in a different folder. The service may then be reinstalled at the correct location by entering eftlink install.
Once installed the service can be started and stopped from a command line:
eftlink start
eftlink stop
The service can also be controlled from the Windows Services Control Panel applet ("OPI Server").
Examine the log file ”Wrapper.log”.
The log file can be found in the designated EFTLink folder\log\eftlink_wrapper.log
Installing, starting the service, stopping the service, and uninstalling the service are all briefly logged in wrapper.log, and this can be used to diagnose any problems.
It is possible to run EFTLink as a service, using a third party wrapper. EFTLink is distributed with a version of Tanuki Software Limited Java Service Wrapper.
|
Note: You may be required to give script file(s) execution rights. This can be accomplish by opening a terminal window and typing:
For example, |
Follow the steps below on how to configure EFTLink to run as a service.
Download and install Java:
Ensure you have the correct version of Java installed.
For example: if the target machine has a 64 bit OS with default 64 bit Java active but you want to use a 32 bit service wrapper, then ensure you also have the required 32 bit Java installed.
Running EFTLink.
From a terminal change to the directory for EFTLink.
For example, type cd /opt/eftlink.
If not already done, run installcore.sh to install the desired core which also creates and copies the necessary wrapper to ./bin.
For example, type sudo./installcore.sh/adyen.
To run EFTLink as a service from a terminal type the following command sudo./eftlink.sh start.
To stop, check the status or to restart EFTLink from a terminal, type one of the following commands:
sudo./eftlink.sh stop
sudo./eftlink.sh status
sudo./eftlink.sh restart
sudo./eftlink.sh condrestart
Examine the log file ”Wrapper.log”.
The log file can be found in the designated EFTLink folder\log\eftlink_wrapper.log
Starting the service and stopping the service are all briefly logged in wrapper.log, and this can be used to diagnose any problems.
SelfSigned Certificates
The EFTLink application does not include default TLS encryption keys for secure communication between POS client and EFTLink server, so these need to be generated as part of the installation procedure. A batch file, CreateKeys.bat, and a Linux script, CreateKeys.sh is included in the EFTLink project to facilitate creation of encryption keys.
Locate the CreateKeys.bat / CreateKeys.sh file in the EFTLink folder
From a terminal, run the CreateKeys script file with an appropriate set of parameters to create encryption keys.
CreateKeys.bat -e <algorithm> <bitlength> <signAlgorithm> <daysValidity> CreateKeys.sh -e <algorithm> <bitlength> <signAlgorithm> <daysValidity>
For example, CreateKeys.bat-e RSA 4096 SHA256withRSA 750
Table 2-4 SelfSigned Certificate Parameters
| Switch | Parameter | Description | Supported Value |
|---|---|---|---|
|
-e |
<algorithm> |
Algorithm used for TLS keys encryption. |
EC,DSA,RSA |
|
<bitlength> |
Number of bits - higher values equate to a higher level of encryption. |
256 (when using EC), 1024,2048 (when using DSA), 1024,2048,3072,4096,7680,8192,15360 (when using RSA) |
|
|
<signAlgorithm> |
Signature Algorithm used. |
SHA256withECDSA, SHA384withECDSA, SHA512withECDSA (when using EC), SHA256withDSA (when using DSA), SHA256withRSA, SHA384withRSA, SHA512withRSA (when using RSA) |
|
|
<daysValidity> |
Number of days after creation that the certificate will remain valid. |
100 to 750 days |
Once encryption keys are created, four files will be present on the system in the keys subfolder of EFTLink:
pos.private.jks to be MOVED to the POS client
pos.public.jks - to remain on the EFTLink Server
eftlink.private.jks - to remain on the EFTLink Server
eftlink.public.jks - to be MOVED to the POS client
The following files should be REMOVED from the EFTLink system and placed on the POS in the folder [xstore root]\keys, where xstore root is the main POS client folder, for example: c:\xstore\keys:
pos.private.jks
eftlink.public.jks
This will leave only the following two files on the EFTLink server in the folder [eftlink root]\keys:
eftlink.private.jks
pos.public.jks
The removal of the appropriate files from the EFTLink server is to limit the availability of TLS keys only to where they are required, and in order to reduce the possibility of the keys being obtained and used to monitor traffic between POS and EFTLink server.
These instructions are repeated by the CreateKeys script file when keys are generated.
|
Note: From V20 onwards, expiry of TLS certificates is enforced by default. Self-signed certificates will be valid for a maximum of 750 days. |
Clear warnings will be placed in log files when certificates are due to expire. Expired certificates will not result in loss of communication between POS and EFTLink.
CA Certificates
Optionally, the EFTLink application TLS encryption keys for secure communication between POS client and EFTLink server may be signed by a CA. A batch file, CreateKeys.bat, and a Linux script, CreateKeys.sh is included in the EFTLink project to facilitate creation of encryption keys, generation of signing request and import of the signed certificates.
Locate the CreateKeys.bat / CreateKeys.sh file in the EFTLink folder.
From a terminal, run the CreateKeys script file with an appropriate set of parameters to create encryption keys. The parameters are similar to those when used to generate self-signed certificates but specify the first parameter as -s.
CreateKeys.bat -s <algorithm> <bitlength> <signAlgorithm> <daysValidity> CreateKeys.sh -s <algorithm> <bitlength> <signAlgorithm> <daysValidity>
For example, CreateKeys.bat-s RSA 4096 SHA256withRSA 750
Table 2-5 CA Certificate Parameters
| Switch | Parameter | Description | Supported Value |
|---|---|---|---|
|
-e |
<algorithm> |
Algorithm used for TLS keys encryption. |
EC,DSA,RSA |
|
<bitlength> |
Number of bits - higher values equate to a higher level of encryption. |
256 (when using EC), 1024,2048 (when using DSA), 1024,2048,3072,4096,7680,8192,15360 (when using RSA) |
|
|
<signAlgorithm> |
Signature Algorithm used. |
SHA256withECDSA, SHA384withECDSA, SHA512withECDSA (when using EC), SHA256withDSA (when using DSA), SHA256withRSA, SHA384withRSA, SHA512withRSA (when using RSA) |
|
|
<daysValidity> |
Number of days after creation that the certificate will remain valid. |
100 to 750 days |
Once encryption keys are created, a sub-folder based on the current date/time is created containing the encryption keys along with signing requests:
For example,
Folder name: keys20200710115046
Eftlink.private.jks - selfsigned file
Pos.private.jks - selfsigned file
Eftlink.private.csr - certificate signing request
Pos.private.csr - certificate signing request
Eftlink.private.jks - backup of selfsigned file
Pos.private.jks - backup of selfsigned file
The backup files are required for the situation where a subsequent import is attempted but does not give the required results - further attempts may be made at importing the signed certificates received from the CA.
For this reason, do not remove the backup files.
File are held in this temporary folder rather than the keys folder as the signing process may take some time, and several sets of signed keys can be handled.
Deliver to your CA the following files:
Eftlink.private.csr
Pos.private.csr
In reply you should receive the following files (filenames may vary):
Eftlink.private.cer.der - signing of EFTLink.private.csr
Pos.private.cer.der - signing of POS.private.csr
Root.cer - root certificate used to sign
Optional Intermediate.cer - one or more intermediate certificates
Import the signed certificates into the keystores, by placing the signed files and root certificate (plus optional intermediate certificates) in the temporary signing keys folder keys[date] then running the following command.
Createkeys -I <foldername> <root cert> <eftlink signed file> <pos signed file> <(optional) intermediate certificate 1><(optional) intermediate certificate 2>
Table 2-6 Signed Files, Root Certificates and Intermediate Certificates
| Switch | Parameter | Description | Supported |
|---|---|---|---|
|
-e |
<foldername> |
Temporary keys Subfolder name. Do not provide the full path, just the foldername. |
18 character folder name |
|
<root cert> |
The root certificate provided by the CA |
Security certificate |
|
|
<eftlink signed file> |
Signed file returned by CA |
Security certificate |
|
|
<pos signed file> |
Signed file returned by CA |
Security certificate |
|
|
<intermediate certificate 1> |
CA Intermediate certificate |
Optional Security certificate |
|
|
<intermediate certificate 2> |
CA Intermediate certificate |
Optional Security certificate |
For example, createkeys -i keys20200101010101 ca_root.cer eftlink.private.der.cer pos.private.der.cer ca_intermediate1.cer ca_intermediate2.cer
Archive the temporary keys[date] folder to a safe location as this contains sensitive information.
The following files should be REMOVED from the Eftlink system and placed on the POS in the folder [xstore root]\keys, where xstore root is the main POS client folder, for example: c:\xstore\keys:
pos.private.jks
eftlink.public.jks
This will leave only the following two files on the EFTLink server in the folder [eftlink root]\keys:
eftlink.private.jks
pos.public.jks
The removal of the appropriate files from the EFTLink server is to limit the availability of TLS keys only to where they are required, and in order to reduce the possibility of the keys being obtained and used to monitor traffic between POS and EFTLink server. These instructions are repeated by the CreateKeys script file when keys are generated.
|
Note: From V20 onwards, expiry of TLS certificates is enforced by default. Self-signed certificates will be valid for a maximum of 750 days. |
Clear warnings will be placed in log files when certificates are due to expire. Expired certificates will not result in loss of communication between POS and EFTLink.
See the Oracle Retail EFTLink Core Configuration Guide located on OHC and refer to the chapter for the specific core selected.
By default in Windows, the 'OPI Server' service is using the Local system account user. In order to ensure for EFTLink service to create dynamic key store files, a user with an administrative privilege is needed. This is only applicable for cores like PointUS and Cayan. In the services panel, right click on the OPI Server service. Select the Properties option. Select the Log on tab. Select This account:. Input the user's credentials and select OK.
Adyen: The POS_JNI jar which is provided by Adyen is also required. This needs to be copied to C:\eftlink\cores\Adyen or /opt/eftlink/cores/Adyen for Linux. Refer to the Third Party section of the Adyen core in the Oracle Retail EFTLink Core Configuration Guide located on OHC for more details.
AJB FiPay: The AJBComm.jar component needs to be copied to C:\eftlink\cores\FIPay or /opt/eftlink/cores/FIPay for Linux. Refer to the FileSet section of the AJB core in the Oracle Retail EFTLink Core Configuration Guide located on OHC for more details.
Cayan: The merchant credentials which are supplied by Cayan team are needed to be setup. This can be done in Xstore's back office through the EFTLink Admin functions. Refer to the Account Information Entry section of the Cayan core in the Oracle Retail EFTLink Core Configuration Guide located on OHC for more details.
VerifoneUS: The PED needs to be paired with EFTLink prior to use. This can be done through Xstore's back office in the EFTLink Admin functions. Refer to the Administration Functions section of PointUS core in the Oracle Retail EFTLink Core Configuration Guide located on OHC for more details.
EFTLink can be configured to use multiple cores for the purpose of redirecting requests based on:
Line display
Request Type
Cardrange.xml
Referrals
Line Display
Sale State Notification requests can either be disabled altogether or be forwarded to either one particular core or a delegated list of cores.
Preselected Cores
Preselected cores are configurable within the eftlinkconfig.properties file. You can configure EFTLink to forward requests to a particular core based upon EWallet, GiftCard (Card Service Request) or a Custom Form (Device Request).
CardRange.xml
EFTLink always checks the cardrange.xml before determining which core is selected for handling the card Service Request.
The cardrange.xml offers EFTLink the ability to redirect card service requests to preselected cores base on the *card pan or card type.
*As the POS is not subject to sending an EMV PAN due to PCI regulations. Card PAN is only applicable with non PCI transactions (Gift card or Ewallet).
Referrals
EFTLink supports a referral feature whereby a core can request that another core handles the request on its behalf.
By default EFTLink sets the main core (core 0) for referrals however this is configurable via EFTLinkConfig.Properties.
The cardrange.xml can also be used to redirect the referral to any active core.
A referral could be based upon a feature not supported or, it could be based upon a particular failed response / error code.
The core requesting the referral is in control and is responsible for the transaction response back to the POS.
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 really 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.
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.
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.
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.
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/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.
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:
Replace: java manito.eft.opi.server.OPIServer
With: java manito.eft.opi.server.MultiServerLauncher
Replace: java -cp $CLASSPATH manito.eft.opi.server.OPIServer
With: java -cp $CLASSPATH manito.eft.opi.server.MultiServerLauncher
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.
Replace: PEDPoolEnabled = false
With: PEDPoolEnabled = true
Replace: PEDPoolOneCatchAllChannel0 = false
With: PEDPoolOneCatchAllChannel0 = true
See PED Pooling Set Up for more information.
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):
In the main eftlink folder, run installcore.bat as if configuring standalone EFTLink. This will setup the EftlinkConfig.properties file.
Create a subfolder under the main eftlink folder named serverN, where N is the sequence number.
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.
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.
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.
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. |
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 also 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 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.
Each POS client is identified by a unique sequence number starting from 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
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
EachPOS has to 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.
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. |
As noted above, each POS has to 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.
(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>
(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.
