Starting and stopping the supplier service
Installing (or removing) the supplier Windows service
Starting and stopping the Supplier Server in Windows service mode
This version of FEX provides a supplier service. The supplier service is a standalone background process that enables you to supply account statements to the EBICS Server.
The supplier service monitors an input directory named inbox. All files that are deposited in this directory will be supplied automatically to the EBICS Server. A file qualifies for the supply if its name matches a defined pattern. By default, this pattern is set to: IBAN_EBICSBANKHOSTID_ORDERTYPE_FILEFORMAT_DATE.
If the supply succeeds, the supplied file is moved from the inbox directory to the success directory. If it fails, it is placed in the failed directory.
Note: If you just want to supply a single file, for example for maintenance or testing, you can use the supplier command line tool.
On UNIX platforms, start the supplier service by running the script <SUPPLIER_INSTALL_DIR>/bin/supplyservice.sh.
On Windows platforms, run the script <SUPPLIER_INSTALL_DIR>\bin\supplyservice.bat.
Depending on the way you stop the Supplier, there might be a risk of corruption of the data
| OS | Stop command | Risk of Data Corruption | Description |
|---|---|---|---|
| Windows | Taskkill* | No | Supplier processes any running Supply till completion before stopping. |
| Windows "Process Manager" Stop | Yes | Stop is not managed by the Supplier; resources are de-allocated by the Operating System. | |
| Windows Service | No | Supplier Controller is Mandatory for Windows Services. Supplier processes any running Supply till completion before stopping. | |
| Control-C in an open command window | No | ||
| UNIX | kill signal 9 | Yes | Stop is not managed by the Supplier; resources are de-allocated by the Operating System. |
| Default kill signal (15) | No | Supplier processes any running Supply till completion before stopping. | |
| Control-C in an open command window | No |
*Taskkill is not available on all Windows Platforms.
The safest way to stop the Supplier is to enable the "Advanced process status"/Supplier Controller and the related scripts as described below.
The Supplier Controller is a small client that instructs the Supplier Service to shutdown. When you call the script <SUPPLIER_INSTALL_DIR>\bin\controllerStop.bat (or <SUPPLIER_INSTALL_DIR>/bin/controllerStop.sh on UNIX), the Supplier Service will safely stop. To enable this functionality, you have to modify <SUPPLIER_INSTALL_DIR>/conf/supply.properties by setting supplier.controller.activated to true and setting an available port number to supplier.controller.port (default value is 64000). The Controller will automatically start with the Supplier Service.
From version 2.8.1, the Controller is set by default when the Windows service is used on the supplier. This functionality is required for the Windows service so you must not deactivate it in this case.
Consult supplier service logs in <SUPPLIER_INSTALL_DIR>/logs/supplier.log.
Two different supply modes are provided: File and Database. The supply mode determines how the supply is stored in EBICS Server: as a file in the data store or directly serialized into the database. You set the mode when installing EBICS Server using the Axway Installer. In the EBICS Server: Supplier settings screen, select DataStore directory (file) or Ebics Server Database (database). If you want to modify the selection later on, run the installer in Update mode.
Important: The configuration of the supplier service depends on the configuration of the EBICS Server. Each order type / file format couple is configured with a specific handler (in Processing/Fetch Transactions). The handler determines how data is stored in the EBICS Server ("Axway Generic Fetch" Transaction for File Mode and "Axway Database Fetch Handler" for Database Mode). For details of handlers, see EBICS: Processing .
For example, if the (order type, file format) FDL.camt.xxx.cfonb120.stm is configured with Axway Generic Fetch (File mode), to enable the supplier service to supply on it, you need to set its supply mode to File.
For more information about supply modes and how they affect the behavior of the supplier service, see Limitations
You can edit advanced settings in the properties file: <SUPPLIER_INSTALL_DIR>/conf/supply.properties.
supplier.controller.port=64000
supplier.controller.activated=false
If necessary, you can change the file pattern by editing this property:
|
file.regex=^([0-9A-Za-z]+)_([0-9A-Za-z]+)_([0-9A-Za-z]+)_([0-9A-Za-z\.]+)_([0-9]+)$ |
file.regex is a POSIX regular expression which is structured like this: FIELD1_FIELD2_FIELD3_..._FIELDN. You can also replace the field separator with file.separator.
There are some mandatory fields for the supply: iban, order type, file format and EBICS bank host id. You can also add optional fields such as date or file number.
Date format: The default date format configured in the properties files is YYYYMMDD.
You can change the position of a field in the pattern file.regex by editing these properties:
|
file.group.mdt.iban=1 file.group.mdt.orderType=3 file.group.mdt.fileFormat=4 file.group.mdt.bankhostid=2 file.group.opt.date=5 |
| Note | For supplying order types without a file format (only 3 letters) the configuration properties must be updated as below: |
|
file.regex=^([0-9A-Za-z]+)_([0-9A-Za-z]+)_([0-9A-Za-z]+)_([0-9]+)$ file.separator=_ file.group.mdt.iban=1 file.group.mdt.bankhostid=2 file.group.mdt.orderType=3 file.group.opt.date=4 |
The supplier service is multi-threaded. You can tune the number of threads used to supply by editing the property:
|
supplier.threads=5 |
Increasing this value does not necessarily mean that the supplier service will be faster. It must be set according to your production environment and your use case to get the best performance.
The supplier service has a connection retry mechanism with the EBICS Server. You can set the number of retries:
|
server.connection.retry.number=5 |
You can also set the time between two retries (in milliseconds):
|
server.connection.retry.delay=1000 |
When using the File mode, the supplier service has two possible file transfer strategies: copy and move. Copy is the default behavior. It makes a copy of the file to supply from the supplier service to the data store of the EBICS Server and then moves the file from the inbox directory to the success directory. The move strategy moves the file from the inbox directory directly to the data store without making a copy in the success directory. This strategy is more efficient because move is faster than copy but has a limitation. It only works when the inbox directory and the EBICS Server data store directory are on the same file system partition. Otherwise you must use the copy strategy. Depending on your use case, the copy strategy can be useful if you need to keep a copy of the successful supplied files. The following property sets the file transfer strategy. Possible values are "copy" and "move".
|
file.transfer.strategy=copy |
If you want to use the database mode, you must set the following parameters in the configuration file:
| Property | Description |
|---|---|
| databaseUseDBsupply | If set to true, it switches to the database mode (for supplier service only) |
| databaseUrl | The url to the database in standardized form |
| databaseLogin | The login to the database |
| databasePassword | The password to the database |
| databaseType | The type of database (ORACLE or MYSQL) |
Important: The use of the database requires the handler of the used order types to be set to "Axway Database Fetch Handler" in the server. The supplier service will not run any check at runtime to ensure consistency between the supplier service set-up and the server set-up.
During the installation process on Windows platforms, the Installer asks whether or not to install in Windows Service mode. All scripts described here are only available if this option was selected.
To install the supplier Windows service, run the script: <InstallationDir>/Supplier/service/installSupplierEbicsServer.bat
To remove the supplier Windows service, run the script: <InstallationDir>/Supplier/service/removeSupplierEbicsServer.bat
If, during installation, the Supplier Server was installed as a Windows service, you can start and stop the Supplier Server as follows:
Alternatively, run the script: <InstallationDir>/Supplier/service/startSupplierEbicsServer.bat
Alternatively, run the script: <InstallationDir>/Supplier/service/stopSupplierEbicsServer.bat
Technically, there are different ways to add files to the inbox directory of the supplier service. If you choose a copy-based method, the supply might be wrong for huge files. When you copy a huge file to the inbox directory, the supplier service can supply it even though the copy is not finished which can lead to inconsistent data. To avoid this problem, copy your file with the .lck extension. For example, rename the file FILE_TO_SUPPLY to FILE_TO_SUPPLY.lck. The supplier service will ignore it until you rename or move it in the same directory without the .lck extension after the copy ends. Move is an atomic file system operation so it ensures the consistency of the file.
The Tracked Object for the supplier is specified in the supplier configuration file <SUPPLIER_INSTALL_DIR>/conf/supply.properties and must contain a "FileName" attribute. The default XFBTRANSFER Tracked Object already contains this attribute. The FileName attribute will be filled in with the full path name of the supplied file.
The Current table in Sentinel holds the latest supplied file name. The full list of file names for the current day is stored in the History table. The full path name is sent to Sentinel.
| Note | If the FileName attribute defined in the Tracked Object is not large enough to contain the full path, Sentinel will store the first characters in the database. The end of the file name will be lost. |
If you use File-based fetch handlers, the supplier service must be installed on the same machine as the EBICS Server. The supplier service cannot remotely send a file to a "file system" data storage. It can be installed remotely if you use Database-based handlers.
Although the supplier command line tool dynamically determines how a file must be supplied (File or Database mode), the supplier service does not. The supplier service works exclusively in the configured mode. In other words, you can not mix several order types which have different storing modes. If the supplier service is configured for File mode, and you try to supply a file on an order type which is configured in Database mode in the EBICS Server, the supply will fail. To bypass this limitation you can use two different installations of the supplier service, one configured for File mode and the other for Database mode. Just be careful about the order types you submit to each one.
Installing EBICS Server: Start here
Specific application server configuration