< Back to User Guide Top

EBICS host

Connector Access & Licensing

Connectors require separate licenses and are governed by commercial terms. Although all connectors are accessible in-product by default, usage beyond the Customer’s contract is subject to audit and adjustment.

For compliance or subscription inquiries, please contact Cleo Sales.

Overview

The Electronic Banking Internet Communication Standard (EBICS) uses the HTTPS protocol to securely transmit files over the Internet. EBICS follows a client-server architecture, where the bank acts as the server and the customer (individual or company) is the client. All transactions are initiated by the client, either as uploads (e.g., order type IZV for domestic payments) or downloads (e.g., order type STA for SWIFT daily accounts).

VersaLex uses PUT and GET action commands—both executed via HTTP POST—to transport secure data to remote banking servers. EBICS messages are encapsulated in XML and encrypted at both the transport (SSL/TLS) and content levels. EBICS also supports strong signature mechanisms, including both handwritten and electronic signatures.

EBICS classifies orders as either bank-technical (e.g., payments, statements) or system-related (e.g., key management, contractual information). VersaLex handles:

  • Bank-technical orders via GET and PUT commands.
  • System-related orders via the EBICS Mailbox tab.

Among the many EBICS order types, FUL and FDL are general-purpose:

  • FUL supports general uploads.
  • FDL supports general downloads.

For more details, refer to the official EBICS specification at https://www.ebics.org.

Customers and Users

In the context of EBICS, a customer is defined as the organizational unit that concludes a contract with the bank, and a user is defined as a human or technical system that is assigned to a customer. Customers are often also referred to as partner, and users are often also referred to as subscriber. The customer/partner has a Partner ID to uniquely identify it, and the user/subscriber has a User ID. The customer-user combination is tied to a mailbox, and their associated IDs are specified on the EBICS mailbox: EBICS tab. See EBICS Mailbox. These IDs are sent with almost every initial request to the bank server.

Technical Subscribers

The EBICS specification explains the concept of technical subscribers. When requests are sent from a technical subscriber, the optional  <SystemID> element is defined. Technical subscribers do not exist in the context of the VersaLex EBICS client, therefore, the <SystemID> element will never be specified.

Bank-Customers Contracts

Initially, a contract is established between a bank and a customer. The contract includes details such as the orders the customer can issue, which accounts are accessible, and signing permission level.. All contractual details are outside of the EBICS specification and are therefore outside the scope of the VersaLex EBICS client. The management of these contractual details are maintained somewhere within the environment of the financial institution, and not within the VersaLex environment. Therefore, it is the responsibility of the financial institution to guard against unauthorized transactions. For example, if a certain VersaLex user is not authorized to issue a particular order, this transaction will ultimately be prevented when the bank server issues the appropriate return code (that is, EBICS_INVALID_USER_STATE) during the initialization phase of an order.

File-Based Transfers

All order data tranmissions are file-based. The VersaLex EBICS client, by default, ensures that all upload requests specify an HTTP header Content-Type name parameter corresponding to the original file name within the VersaLex file system. Conversely, it is anticipated that the bank server will provide a Content-Type "name" parameter or a Content-Disposition "filename" parameter within the returned HTTP headers for all download requests. While this is anticipated, it is not required for download orders. See Inbound File Names.

Data Segmentation and Checkpoint Restart

According to the EBICS specification, there is a one (1) MB limit on the size of the payload (i.e., the data encapsulated within the <OrderData> element). After the payload has been compressed, encrypted, and base64-encoded, if larger than 1 MB, it must be segmented into multiple transaction steps. The EBICS specification defines optional checkpoint restart rules at the segment breaks. The VersaLex EBICS client supports the checkpoint restart capability for both uploads and downloads.

Signatures

EBICS calls for multiple levels of signatures. Almost every message request and response carries a signature; this signature is wrapped within the <AuthSignature> element and it uses the XML Signature methodology. This is referred to as the identification and authentication signature, and it is required for almost every EBICS request and response. In addition to the identification and authentication signature, a so-called electronic signature (abbreviated as ES) can also be present on an EBICS upload request. This signature is embodied within the <UserSignatureData> element. The ES signs the payload and the identification and authentication signature signs overall EBICS packages.

Order Attributes

The EBICS specification requires the <OrderAttribute> element on most EBICS requests. See the table below. To learn more, see the EBICS specification at www.ebics.org .

The <OrderAttribute> element is 5-character field. The setting for each character is as follows:

Position Meaning Permitted Values
1 Type of data transmitted

O = order data and ES

U = ES only

D = order data and transport ES

(or no ES in the case of certain key management orders like HIA and INI)
2 Compression type Z = ZIP compression
3 Encryption type for order data and/or ES

N = no encryption

H = hybrid encryption AES/RSA
4 Reserved N = reserved setting
5 Reserved N = reserved setting

Security Media For Private Keys

The EBICS specification defines the following codes for identification of the medium for storage of private keys.

Security Medium Setting
No specification 0000
Diskette 01dd
Chipcard 02dd
Other removable storage medium 03dd
Non-removable storage medium 04dd

Note that "dd" represents any number combination that is configurable by the customer. This value is specified through the EBICS Host: EBICS tab. See EBICS Host.

Inbound File Names

Inbound files can be received via a GET command or via one of the ancillary orders executed through the EBICS mailbox: EBICS tab (using Execute Ancillary Order or Download Bank Keys). See EBICS Mailbox.

The general order of precedence is as follows:

  1. If a "destination" name is specified on the GET command, it is used.
  2. Otherwise, the Default File Name setting from the EBICS Host: EBICS tab is used. See EBICS Host: EBICS Tab.

Within the destination string of a GET command or within the Default File Name, source file macros (e.g., %sourcefile%) can be used to build the final destination name. When a macro is used, if the Content-Disposition "filename" or the Content-Type "name" is specified on the inbound response from the bank server, then it is used to resolve the macro. If both parameters are specified, then Content-Disposition takes precedence. Conversely, if neither parameter is specified, then the generic string, "receive.file", is used for the macro substitution.

After the inbound file name is determined, the following will determine its final name. These steps are different for files associated with a GET command and for files associated with an ancillary or key download.

If a file is associated with a GET command:

  • if -UNI is specified on the command, and the file already exists, the name will be made unique (e.g., changing FDL.xml to FDL1.xml) to avoid overwriting the file.
  • if -APE is specified on the command, the file will be appended to if it already exists.
  • if neither -UNI nor -APE are specified, and the file already exists, it will be overwritten.

If a file is associated with an ancillary or key download:

  • if the file already exists, the name will be made unique (e.g., changing HTD.xml to HTD1.xml) to avoid overwriting the file.

Key Management

The EBICS specification defines several provisions and order types associated with the exchange of public keys.  Three sets of public-private keys are defined for EBICS application-level encryption and signing. They are:

  1. key pair for encryption
  2. key pair for identification and authentication signature
  3. key pair for electronic signature (ES)

According to the specification, key pairs 1 and 2 can be the same pair, but key pair 3 must be unique. The bank server will respond with appropriate error codes if this requirement is not met.

SSL/TLS Keys

In addition to the keys used at the application-level, there is a public-private key pair for TLS-level encryption.  The EBICS specification makes no restrictions as to whether or not this key pair may coincide with one of the application-level keys.

Key Exchange

When a user is first created, the bank will classify the user as New. Prior to conducting transactions, the user must be classified asReady. The Ready state means that the bank has all the information necessary for the user to start submission of orders, including bank's download keys. To achieve the Ready state, the bank requires the receipt of certain keys. Know the requirements of your banking partner in order to provide the necessary keys according to the prescribed methods.

The transfer of keys from the client to the server and from the server to the client is referred to as key exchange and is supported through the EBICS mailbox: EBICS tab. See EBICS Mailbox. Under EBICS, provisions have been made for key exchange through certain order types defined within the specification. The key exchange order types implemented through the VersaLex EBICS client are:

Upload:

  • INI - Upload ES key
  • HIA - Upload signing and encryption keys
  • H3K - Upload signing, encryption, and ES keys
  • PUB - Update ES key
  • HCA - Update signing and encryption keys
  • HCS - Update signing, encryption, and ES keys

Download:

  • HPB - Download signing and encryption keys

The EBICS specification also calls for hardcopy "initialisation letters" through which a secondary submission of key information is passed. The VersaLex EBICS client also provides functions to produce these letters.

EBICS Client Order Types

Below is a table summarizing the order types referenced in the EBICS specification at www.ebics.org . The source of the table originated from Appendix 13 of Specification EBICS Version 2.5. The last column of the table displays where the order type is supported within the framework of an EBICS host, mailbox, or action.

View Client Order Types table

Order Type Direction of Transfer Text Specification Status Where Supported in VersaLex
FDL D Download file with any format Optional

Supported through the GET command.

See EBICS Command Reference
FUL U Upload file with any format Optional

Supported through the PUT command.

See EBICS Command Reference
HAA D Download retrievable order types Optional

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
HAC D Download status information (XML Format) Mandatory

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
HCA U Update signing and encryption keys Mandatory

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
HCS U Update signing, encryption, and ES keys Mandatory

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
HEV D Download supported versions Mandatory

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
HIA U Upload signing and encryption keys Mandatory

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
HKD D Download customer data for all users Optional

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
HPB D Download signing and encryption keys Mandatory

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
HPD D Download bank parameters Mandatory

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
HSA U Upload subscriber keys for FTAM users Optional Not Planned [4]
HTD D Download customer data for this specific user Optional

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
HVD D Retrieve VEU state Conditional  
HVE U Add VEU state Conditional  
HVS U VEU cancellation Conditional  
HVT D Retrieve VEU cancellation details Conditional  
HVU D Download VEU overview Conditional  
HVZ D Download VEU overview with additional information Conditional  
H3K U Upload signing, encryption, and ES keys Optional

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
INI U Upload ES key Optional

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
PTK D Download status information (German version only) Optional

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
PUB U Update ES Key Optional

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
SPR U Suspend user Optional

Supported through the EBICS mailbox: EBICStab.

See EBICS Mailbox
AEA, AIA, etc. [5] U/D Variable Variable

Upload commands supported through the PUTcommand .

Download command supported through the GETcommand .

See EBICS Command Reference

EBICS Configuration

The following sections explain how to configure an EBICS host from scratch using the generic EBICS preconfigured host. See Cloning and activating a pre-configured host.

  1. Obtain the following parameters from your bank server:

    • URL, of the form https://remote-host:port/resource-path?optional-parameters .  
    • The server's Host ID.
    • EBICS version supported (2.4 or 2.5).
    • ES (electronic signature) version supported (A005 or A006).

  2. Provide the following parameters to your bank server:

    • Your Partner ID
    • Your User ID
  3. Click the Templates tab in the tree pane.
  4. If necessary, expand the Hosts tree in the Templates tab to find the host you want to use.

  5. Right-click the host and select Clone and Activate. 

    The entire pre-configured host branch (including a mailbox and actions) is copied and activated, the Active tab is selected in the tree pane, and the new active host is selected in the tree.  If necessary, you can append the new active host alias with a number to make it unique. 

    Note: The original pre-configured host remains in the pre-configured tree.

  6. Enter host-level configuration information.
    1. Click the new host in the tree pane.
    2. Enter host-level configuration information on the tabs in the content pane. See EBICS Host.
    3. Click Apply to save your work.
  7. Enter mailbox-level configuration information.
    1. Click the mailbox under your host in the tree pane.
    2. Enter mailbox-level configuration information on the tabs in the content pane. See EBICS Mailbox.
    3. Click Apply to save your work.
  8. Enter action-level configuration information.
    1. Click an existing mailbox action to display its configuration tabs. Alternatively, right-click the mailbox and select New Action.
    2. Edit action information on the tabs in the content pane. See EBICS Action .
    3. Click Apply to save your work.
  9. Click Apply to save your work.
Important: If you leave any of these panels without clicking Apply, your work will not be saved. You can configure the native UI to prompt to you click Apply when changes are made. See Other system options. However, in the web UI, this is not valid. In the web UI, if you make updates to a host and then click a part of the product not related to a host, for example any of the buttons in the banner, the product will not prompt you to click Apply and your updates will not be saved.

EBICS Host

The following describes configuration of the Generic EBICS preconfigured host.

To rename the host alias, right-click on the host and choose Rename. Alternatively, you can change the host alias by modifying the Hostalias field in the content pane and clicking Apply.

EBICS Host: General Tab

Server Address

The address where your trading partner's server receives requests. Either a fully qualified name (recommended) or an IP address.

Port

The port where your trading partner's server receives requests. You can specify either a specific port number or -1 to indicate the default port for HTTP (80) or HTTP/s (443).

Connection Type

The kind of connection you want to use for this host.

Possible values:

  • System Default - See for information about setting the system default.
  • Direct Internet Access or VPN - Use either a direct connection to the internet or a VPN.

Default value: System Default

Forward Proxy

The address of the forward proxy you want to use for this host.

Select the System Default check box to use the default proxy. See Configuring for a proxy for information about specifying a default proxy.

Default Directories

Modify the default directories, if necessary.  You can use macro variables from the drop-down lists.  See Using Macro Variables for a list of the applicable macros (Default Host Directory context) and example usage.  For VLTrader and Harmony, see URI File System interface overview for information about you can use a Cleo-provided or custom URI for the Inbox and/or Outbox.  See Specifying default host directories for information about setting up system-level directories and custom directory macro variables.

Inbox

Default directory for incoming files. Enter a value directly or click … to navigate to and select a directory.

Possible values: Any local or shared directory.

Default value: inbox\

Outbox

Default directory for outgoing files. Enter a value directly or click … to navigate to and select a directory.

Possible values: Any local or shared directory.

Default value: outbox\

Sentbox

If specified, default directory for retaining sent files.  Files are a copy of the original source file; any file manipulations performed as part of the send are not reflected in the sentbox copies. Enter a value directly or click … to navigate to and select a directory.

Possible values: Any local or shared directory.

Default value: No default value.

Receivedbox

If specified, default directory for retaining received files.  Files are a copy of the final destination file; any file manipulations performed as part of the receive are reflected in the receivedbox copies. Enter a value directly or click … to navigate to and select a directory.

Possible values: Any local or shared directory.

Default value: No default value.

EBICS Host: EBICS Tab

To
Host ID

The bank server's identifier, up to 35 characters with pattern [a-zA-Z0-9,=]. The value you enter here is placed in the<HostID> element of requests.

Received Files
Default File Name

The filename to be used when an inbound file name is not otherwise specified. To understand the rules for naming inbound files, see EBICS Overview. This field can include any supported macros; see Using Macro Variables for information about applicable macros (Destination File context) and example usage. Also, note the EBICS-specific reserved macro variable, %ebics.ordertype%, which substitutes the three-character order type.

Ancillary Order Inbox

Specify the destination location for the ancillary download orders through the Ancillary Order Inbox.  All ancillary order data downloaded through Execute Ancillary Order will be placed in this location, as well as the <HPBResponseOrderData> associated with Download Bank Keys. See EBICS Mailbox. Click [...] to change the ancillary order inbox location, or select "%inbox%" or a custom macro variable from the drop-down list. If this field is left blank, the default inbox location (as set on the host General tab) will be inserted automatically and used.  

Initial Requests
Specify product information

Select Specify product information to specify the optional <Product> element on each initial EBICS request (that is, "initialisation" phase). When selected, the following element will be included in the XML: <Product Language="en" InstituteID="Cleo Communications">VersaLex 4.5</Product>. Language (i.e., "en" for English) is in accordance with ISO 639-1. "VersaLex" will be replaced by "LexiCom", "VLTrader", or "Harmony" as necessary, followed by the current version level of the software product.

Security Medium ID

Specify the Security Medium ID. This is the two-digit identifier that the EBICS specification requires as part of the <SecurityMedium> element. Since all VersaLex private keys are stored on a non-removable medium, the following element will be included in the XML (given the example value of "00" as shown in the panel above): <SecurityMedium>0400</ SecurityMedium>.

EBICS Host: HTTP Tab

HTTP/HTTPs

Only HTTP/s is allowed for EBICS; therefore, it is pre-selected and cannot be changed. However, to verify that the server name in the received SSL server certificate matches the connected server name, select Check certificate server name.

Check certificate server name

Verifies that the server name in the received SSL server certificate matches the server name actually connected to.

Method

Use POST for both the PUT and GET commands since POST is used exclusively within the context of EBICS.

Path

The bank server's resource path. Given the URL provided by your banking partner in the form https://remote-host:port/resource-path?optional-parameters, the bolded portion in this field should be entered. Note that the beginning slash ("/") is required.

Parameters

Specify any optional URL parameters. By default, no parameters are specified for EBICS messages. If parameters are required, you must obtain them from your banking partner when the relationship is established. Given the URL provided by the banking partner in the form https://remote-host:port/resource-path?optional-parameters the bolded portion in this field should be entered. 

For syntax and rules on specifying HTTP parameters, see HTTP Configuration section. Note that you cannot specify a parameter that matches an EBICS PUT/GET reserved parameter (for example, OrderType).

Headers

Specify values to override any default headers or add new, custom headers. When overriding default headers, make sure they meet the requirements of the EBICS specification. The VersaLex EBICS client will, by default, generate the following headers on all generated HTTP requests: 

  • Host header (for example, Host: bank01.bank.com:443)
  • Content-type header, with the name parameter if applicable (for example, Content-Type: text/xml; name=cust01.pain.001.001.02)
  • Content-Length header (for example, Content-length:1000)

The VersaLex EBICS client will in turn honor the following headers on all generated HTTP responses:

  • Content-type header, with the name parameter if applicable (for example, Content-type: text/xml; name=cust01.camt.053.001.02)
  • Content-Length header (for example, Content-length:1000)
  • Content-Disposition header, with the filename parameter if applicable (for example, Content-disposition: inline; filename= cust01.camt.053.001.02)

EBICS Host: Advanced Tab

The host's Advanced tab contains several property settings fields.  These settings typically do not affect your ability to connect to a host.  However, you may want to change some of these settings when configuring a runtime environment.

See Setting advanced host properties for information about how to use and set the properties supported in all protocols. Properties available for EBICS include:

Add Mailbox Alias Directory to Inbox

Appends a subdirectory at the end of the host's configured inbox directory.  This allows files received through different  mailboxes to be kept separate.

Possible values: On or Off

Default value: Off

Add Mailbox Alias Directory to Outbox

Appends a subdirectory at the end of the host's configured outbox directory.  This allows files to be sent through different mailboxes to be kept separate.

Possible values: On or Off

Default value: Off

Add Mailbox Alias Directory to Receivedbox

Appends a subdirectory at the end of the host's configured receivedbox directory.  This allows files that have been sent through different mailboxes to be kept separate.

Possible values: On or Off

Default value: Off

Add Mailbox Alias Directory to Sentbox

Appends a subdirectory at the end of the host's configured sentbox directory.  This allows files that have been sent through different mailboxes to be kept separate.

Possible values: On or Off

Default value: Off

Allow Actions To Run Concurrently

Normally, actions and host actions within the same host are allowed to run concurrently. You can use this property to not allow actions and host actions to run concurrently.

Possible values: On or Off

Default value: On

Command Retries

If an error or exception occurs during a command, the number of times the command should be retried.

Possible values: 0 - n

Default value: 0

Connection Timeout

The amount of time allowed for each read operation.

Possible values: 0 - n seconds

0 indicates no timeout

Default value: 150 seconds

Do Not Send Zero Length Files

Indicates whether zero length files to be sent to the server should be ignored rather than processed. If the -DEL option is being used, any zero length file ignored will also be deleted.

Possible values: On or Off

Default value: Off

EBICS Version

Specifies the version of EBICS that should be used.

Possible values: EBICS 2.4 or EBICS 2.5

Default value: EBICS 2.4

Email On Check Conditions Met

Send an email notification after running a CHECK command where the overall conditions of the check are met.  See Configuring email or execute based on results.

Possible values: Email addresses separated by commas (,), semicolons (;), or colons ( : ).  The first address should be an internal email address.

Default value:The value specified for this property on the Options > Advanced panel (if set).

Email On Check Conditions Not Met

Send an email notification after running a CHECK command where the overall conditions of the check are not met. See Configuring email or execute based on results.

Possible values: Email addresses separated by commas (,), semicolons (;), or colons ( : ).  The first address should be an internal email address.

Default value:The value specified for this property on the Options > Advanced panel (if set).

Email On Fail

If an error occurs during a command, email the error condition.  See  Configuring email or execute based on results.

Possible values: Email addresses separated by commas (,), semicolons (;), or colons ( : ).  The first address should be an internal email address.

Default value:The value specified for this property on the Options > Advanced panel (if set).

Email On Flag

If a flagged event occurs, email the event. See Configuring email or execute based on results.

Email addresses separated by commas (,), semicolons (;) or colons (:). The first address should be an internal email address.

Possible values: Email addresses separated by commas (,), semicolons (;), or colons ( : ).  The first address should be an internal email address.

Default value:The value specified for this property on the Options > Advanced panel (if set).

Email On Repetitive Action Failures

When "Email On Fail" is enabled and the same failure occurs each time an action is run for a specific host, leaving this option unchecked suppresses emailing of the same alert multiple times.  If the same email alert continues to be suppressed after 24 hours, the suppressed email alert will be sent every 24 hours and after every system restart if the failure occurs again. When the failure is resolved an email alert will be sent.

Possible values: On or Off

Default value: On

Encryption Algorithm

The method used to encrypt/decrypt payload.

Possible values:

  • AES/128
  • AES/192
  • AES/256
  • SEED
  • TripleDES

Default value: TripleDES

ES Version

Specifies the version of ES that should be used.

Possible values:

  • A005
  • A006

Default value: A005

Execute On Check Conditions Met

After executing a CHECK command where the overall conditions are met, run a system command.  See Configuring email or execute based on results.

Possible values: System command to be executed.

Default value: The value specified for this property on the Options > Advanced panel (if set).

Execute On Check Conditions Not Met

After executing a CHECK command where the overall conditions are not met, run a system command.  See Configuring email or execute based on results.

Possible values: System command to be executed.

Default value: The value specified for this property on the Options > Advanced panel (if set).

Execute On Fail

If an error occurs during a command, run a system command.  See Configuring email or execute based on results.

Possible values: System command to be executed.

Default value: The value specified for this property on the Options > Advanced panel (if set).

Execute On Repetitive Action Failures

When Execute On Fail is enabled and the same failure occurs each time an action is run for a specific host, leaving this option unchecked suppresses multiple executions of the Execute On Fail command.  If suppression of execution of the command for this failure continues after 24 hours, the suppressed Execute On Fail command will be executed every 24 hours and after a system restart if the failure occurs again.  When the failure is resolved, the Execute On Fail command will be executed again.  Users must account for this by including the %status% macro variable for the Execute On Fail command (see Using macro variables) and then checking for a success or failure.    

Possible values: On or Off

Default value: On

Execute On Successful Copy

After successfully copying  a file using LCOPY, run a system command.  This command may be used for post-processing the file.  See Configuring email or execute based on results.

Possible values: System command to be executed.

Default value: The value specified for this property on the Options > Advanced panel (if set).

Execute On Successful Receive

After successfully receiving a file, run a system command.  This command may be used for post-processing the file.  See Configuring email or execute based on results.

Possible values: System command to be executed.

Default value: The value specified for this property on the Options > Advanced panel (if set).

Execute On Successful Send

After successfully sending a file, run a system command.  This command may be used for post-processing the file.  See Configuring email or execute based on results.

Possible values: System command to be executed.

Default value: The value specified for this property on the Options > Advanced panel (if set).

Fixed Record EOL Characters

End-of-line characters to be inserted and/or deleted.

Possible values: 0 to n characters. 

  • \r - carriage return
  • \n - new line (linefeed)
  • \f - form feed
  • \t - horizontal tab
  • \0 - null
  • \\ - backslash
Fixed Record Incoming Delete EOL

If Fixed Record EOL Characters has been specified and Fixed Record Length is greater than 0, indicates to look for and delete EOL characters while receiving a file.

Possible values: On or Off

Default value: Off

Fixed Record Incoming Insert EOL

If Fixed Record EOL Characters has been specified and Fixed Record Length is greater than 0, indicates to insert EOL characters while receiving a file.

Fixed Record Incoming Delete EOL and Fixed Record Incoming Insert EOL are mutually exclusive properties.

Possible values: On or Off

Default value: Off

Fixed Record Length

The fixed record length after which end-of-line characters need to be inserted and/or deleted.

Possible values: 0 - n

Default value: 0

Fixed Record Outgoing Insert EOL

If Fixed Record EOL Characters has been specified and Fixed Record Length is greater than 0, indicates to insert EOL characters while sending a file.

Possible values: On or Off

Default value: Off

High Priority

Indicates whether incoming and/or outgoing transfers through the host should be treated as high priority. When both high priority and regular priority transfers are active, the high priority transfers get a larger portion of the available bandwidth. Go to Configure > Options > Other to set the High Priority Transfers Percentage Available Bandwidth (defaults to 75). See Other system options for more information.

Possible values:

  • Incoming
  • Outgoing
  • Both
Ignore EOL Characters In ES Hash Calculation

If selected, all CR and LF characters that are in the payload will be ignored in the ES hash calculation.

Possible values: On or Off

Default value: Off

Include Failure In Subject Of Email

When specified, the exception message will be included in the email that is generated on failure.

Possible values: On or Off

Default value: The value specified for this property on the Options > Advanced panel

Include Line Separators In Base64 Content

If selected, indicates that CRLF should be used to break Base64 <OrderData> content into fixed-length blocks (generally 64 bytes).  If false, Base64 <OrderData> will be output with no line breaks.

Possible values: On or Off

Default value: Off

Include X509 Data In Key Uploads

When this property is selected, the optional X509 certificate data is included in the XML document body for all key uploads that contain an element that extends <PubKeyInfoType>. This includes INI, HIA, PUB, HCA, and HCS. For the H3K transaction (version 2.5 only), X509 certificate data is always included, as it is not optional for H3K.

Possible values: On or Off

Default value: Off

LCOPY Archive

If specified, contains the directory for archiving LCOPY source files.

Possible values: Any local or shared directory. Macros can be used.  See Using macro variables (LCOPY Archive context).

Default value: The value specified for this property on the Options > Advanced panel, if any.

Log Individual LCOPY Results To Transfer Logging

When this option is enabled, a <send> and <receive> result is logged to the transfer log for each file copied.

Possible values: On or Off

Default value: Off

Macro Date Format

Specifies the date format to be used when the %date% macro is used.

Possible values: See Using macro variables for information about usage and possible date/time formats.

Default value: The value specified for this property on the Options > Advanced panel, if any.

Macro Time Format

Specifies the time format to be used when the %time% macro is used.

Possible values: See Using macro variables for information about usage and possible date/time formats.

Default value: The value specified for this property on the Options > Advanced panel, if any.

Maximum Incoming Transfer Rate (kbytes/s)

Sets the maximum incoming transfer rate in Kbytes (1024 bytes) per second for each mailbox or host. The default value of 0 does not limit the transfer rate. The Maximum Incoming Transfer Rate system setting might also limit the transfer rates. The system Maximum Incoming Transfer Rate value is used unless this setting is more restrictive. For simultaneous transfers, the number of active transfers also affects individual transfer rates. See Advanced system options.

Possible values: 0 - n

Default value: 0

Maximum Outgoing Transfer Rate (kbytes/s)

Sets the maximum outgoing transfer rate in Kbytes (1024 bytes) per second for each mailbox or host. The default value of 0 does not limit the transfer rate. The system setting might also limit the transfer rates. The system Maximum Outgoing Transfer Rate value is used unless this setting is more restrictive. For simultaneous transfers, the number of active transfers will also affect individual transfer rates. See Advanced system options for more information about Maximum Outgoing Transfer Rate.

Possible values: 0 - n

Default value: 0

Omit Name Parameter From Content Type

When selected, the applicable file name is not included in the Content-Type header.

Possible values: On or Off

Default value: Off

Outbox Sort

Controls the order in which multiple files are transferred for a PUT command.  If System Default is specified, the value set on the Configure > Options > Advanced tab takes precedence.  For Alphabetical ordering, the file extensions are not used to determine the sorted order unless they are needed to make the filenames unique.

Possible values:

  • System Default
  • Alphabetical
  • Date/Time Modified

Default value: System Default

Outgoing Insert EOL Between Interchanges

If Fixed Record Outgoing Insert EOL is active, indicates to also insert EOL characters between EDI interchanges while sending the file.

Possible values: On or Off

Default value: Off

Partner Email Address

The email address of the trading partner for this trading relationship.  When set, this address is automatically used to send your local profile information and/or certificates to your trading partner. See Emailing a profile to your trading partner.

Possible values: Email address(es) separated by commas (,), semicolons (;) or colons ( : ). 

PGP Compression Algorithm

Compression method used when OpenPGP packaging (with compression) is requested through the Mailbox Packaging tab. See Configuring mailbox packaging. If System Default is specified, the value set on the Configure > Options > Advanced tab is in effect.

Possible values:

  • System Default
  • ZIP
  • ZLIB

Default value: System Default

PGP Encryption Algorithm

Encryption method used when OpenPGP packaging (with encryption) is requested through the Mailbox Packaging tab. See Configuring mailbox packaging. If System Default is specified, the value set on the Configure > Options > Advanced tab takes precedence.

Possible values:

  • System Default
  • TripleDES
  • Blowfish
  • CAST5
  • DES
  • AES-128
  • AES-192
  • AES-256
  • Twofish

Default value: System Default

PGP Hash Algorithm

Signing method used when OpenPGP packaging (with signing) is requested through the Configuring mailbox packaging.  If System Default is specified, the value set on the Configure > Options > Advanced tab takes precedence.

Possible values:

  • System Default
  • MD2
  • MD5
  • RIPE-MD-160
  • SHA-1
  • SHA-256
  • SHA-384
  • SHA-512

Default value: System Default

PGP Integrity Check

When OpenPGP encrypting (see Configuring mailbox packaging), include an integrity check on encrypted data. Can be disabled for compatibility with certain OpenPGP implementation.

Possible values: On or Off

Default value: On

PGP Signature Verification

Indicates whether or not signed inbound PGP messages should verified when inbound OpenPGP packaging is requested through the Mailbox Packaging tab. See Configuring mailbox packaging. In general, this property should be enabled.

Possible values: On or Off

Default value: On

PGP V3 Signature
 
Reset Connection After Timeout On Response

When enabled will cause an immediate reset on the socket (instead of a graceful close) when a SocketTimeoutException occurs.

Possible values: On or Off

Default value: Off

Retry Delay

The amount of time (in seconds) before a retry should be attempted.

Possible values: Any value greater than zero.

Default value: 60 seconds

Reuse SSL Sessions Across Actions

If selected, SSL sessions from previous connections to the same destination (address and port number) may be resumed to avoid costly negotiation. If unselected, only SSL sessions used in the current action to the same destination may be resumed.  When unselected, a new SSL session is created for the initial command port connection.

Possible values: On or Off

Default value: On

SSL Allow Legacy Renegotiation

When selected, legacy renegotiation is allowed. If this property is not selected, the extension described in RFC5746 is used for renegotiation and the server must also support this extension. See RFC5746 for a description of the extension and the vulnerability it addresses.

Possible values: On or Off

Default value: On

SSL Cipher

Indicates a specific cipher to be used with the server for SSL key exchange, encryption, and hashing. If not set, the list of supported ciphers is presented to the server and the server picks one.

Possible values: Any cipher from the supported list. If the server does not also support the cipher, an SSL handshake error will occur.

SSL Maximum Protocol Version

Specifies the maximum protocol version allowed. By default, this field is blank, designating that Cleo Harmony, Cleo VLTrader, or Cleo LexiCom will select the most recent version (currently TLS 1.2).

Possible values:

  • SSL 3.0
  • TLS 1.0 (SSL 3.1)
  • TLS 1.1 (SSL 3.2)
  • TLS 1.2 (SSL 3.3)
SSL Minimum Encryption Key Size

Specifies the minimum encryption key size allowed when selecting an SSL cipher. To prevent use of low- or medium-strength ciphers, change from the default value of 0 to 112, 128, or 256 (depending on the requirement). Note that if this value is set too high, all ciphers are filtered out causing the No suitable cipher suites are enabled exception to occur.

Possible values: 0 - n bits

Default value: 0

SSL Minimum Protocol Version

Specifies the minimum protocol version allowed. SSL 3.0 is the default value for compatibility with servers that do not support the more recent TLS versions 1.0, 1.1, and 1.2.

Possible values:

  • SSL 3.0
  • TLS 1.0 (SSL 3.1)
  • TLS 1.1 (SSL 3.2)
  • TLS 1.2 (SSL 3.3)

Default value: SSL 3.0

SSL Use Record Splitting

Indicates whether to use 1/n-1 record splitting in CBC mode as a countermeasure against the Rizzo/Duong BEAST (Browser Exploit Against SSL/TLS) attack against the SSL 3.0 / TLS 1.0 protocol. Must be turned off if the SSL library on the other side of the connection does not support the feature.

Possible values: On or Off

Default value: On

Store Raw Sent And Received

Indicates whether copies of the "raw" outgoing requests and corresponding incoming responses are stored in the EBICS\sent+received folder.  These files may be useful in diagnosing problems, however, generally this property should be 'off' to conserve disk space.

Possible values: On or Off

Default value: Off

Terminate On Fail

If an error occurs during a command, stop the action. 

Regarding CHECK commands:  Terminate On Fail is only honored if the ConditionsMet parameter is set and the result of the CHECK is classified as Error. The CHECK command is only available in the Cleo Harmony and Cleo VLTrader applications.

Possible values: On or Off

Default value: On

Unzip Use Path

Indicates whether or not zip entry paths should be used for LCOPY -UNZIP operations.  When enabled, the entry's path is added to the destination path, unless the entry contains an absolute path. In this case, the absolute path is used in place of the destination path. 

Possible values: On or Off

Default value: On

Wait For Execute On

Indicates whether execution should wait for processing to complete within an Execute On Fail, Execute On Successful Copy,Execute On Successful Receive, or Execute On Successful Send command.  Note that this option does not apply to native AS400 execution.

Possible values: On or Off

Default value: On

XML Encryption Algorithm

The method used to encrypt/decrypt files when XML Encryption packaging is requested through the Mailbox Packaging tab. See Configuring mailbox packaging .  If System Default is specified, the value set on the Configure > Options > Advanced tab takes precedence. 

Possible values:

  • System Default
  • TripleDES
  • AES-128
  • AES-192
  • AES-256

Default value: System Default

Zip Comment

Specifies the comment to be added to the zip archive file in LCOPY -ZIP operations.

Default value: The value specified for this property on the Options > Advanced panel, if set.

Zip Compression Level

Controls the level of compression for LCOPY -ZIP operations. If System Default is specified, the value set on the Configure > Options > Advanced takes precedence 

Possible values:

  • System Default
  • 9 - (Best Compression)
  • 8
  • 7
  • 6
  • 5
  • 4
  • 3
  • 2
  • 1
  • 0 - (No Compression)

Default value: System Default

Zip Subdirectories Into Individual Zip Files

Indicates whether or not subdirectories should be bundled for LCOPY –ZIP –REC operations.  When enabled, each first-level subdirectory (and all of its descendents) will be bundled together into an individual zip file.  The name of this zip file may optionally reflect the subdirectory name if an asterisk (*) is placed in the destination path.  Any files that are directly off the source root directory will not be copied. 

Possible values: On or Off

Default value: On

EBICS Mailbox

A mailbox's parameters allow access to the remote bank server and define the desired security level of the file being sent.

EBICS Mailbox: EBICS Tab

Set up your identification to the bank server, manage key exchange, and perform several ancillary functions.

From

While these fields are not required for all EBICS requests, they are required for most and therefore values must be specified.

My Partner ID
My User ID

Your identification. Up to 35 characters with pattern [a-zA-Z0-9,=] for each field..

Ancillary Orders
Execute Ancillary Order

Click Execute Ancillary Order to display the Executing Ancillary Order dialog box. See Executing an ancillary order.

Key Management

Perform key management tasks. See Managing keys within EBICS.

Executing an ancillary order

  1. Optional. Override the value in the Ancillary Order Inbox field.

  2. Select an order from the Order Type menu.

    Choose from the following:

    • Download Retrievable Orders (HAA)
    • Download Customer Acknowledgment (HAC)
    • Download Supported Versions (HEV)
    • Download Customer Data (HKD)
    • Download Bank Parameters (HPD)
    • Download Subscriber Data (HTD)
    • Download Customer Protocol (PTK)
  • Depending upon the order type selected, the Start Date and End Date will be enabled. In this case, specify values. The date values must be in the form YYYY-MM-DD. 

  • Click Execute to run the order. 

    Messages are displayed as the transaction steps take place for execution of the order.

  • Optional. Click Cancel at any point to interrupt the execution.

Some of the ancillary orders might not be supported by the server, either because they are optional or because they are not supported under the particular EBICS version. When this occurs, it is possible to see the return code EBICS_UNSUPPORTED_ORDER_TYPE or EBICS_INVALID_ORDER_TYPE.

For all ancillary orders except HEV, the downloaded order data will be placed in ancillary order inbox (as seen in the FILE record shown in the dialog box above). Since the response data is very simple for HEV, it will be reported immediately through detail messages. 

Managing keys within EBICS

The exchange of all keys takes place from the Key Management panel. To understand key-pair requirements and key exchange within the context of EBICS, see EBICS Overview. 

Uploading your keys

  1. On the EBICS mailbox EBICS tab, click Upload My Keys. 

    The Uploading My Keys dialog box appears.

  2. In the Order Type menu, select the upload order to execute.

    Choose from the following:

    • Upload ES Key (INI)
    • Upload Signing and Encryption Keys (HIA)
    • Upload Signing, Encryption, and ES Keys (H3K)
    • Update ES Key (PUB)
    • Update Signing and Encryption Keys (HCA)
    • Upload Signing, Encryption, and ES Keys (HCS)
  3. Click Execute to begin the transaction for uploading. As the transaction takes place, the progress is shown through messages displayed within the dialog box.
  4. Optional. Click Cancel at any point to interrupt the execution.

Downloading the bank keys

  1. On the EBICS mailbox EBICS tab, click Download Bank Keys. 

    The Downloading Bank Keys dialog box appears and the download begins.

    As the transaction takes place, the progress is shown through messages displayed within the dialog box.

    The <OrderData> of the HPB response (embodied in <ebicsKeyManagementResponse>) is decoded, decrypted, and decompressed, yielding an <HPBResponseOrderData> instance document. This document is stored in the ancillary order inbox location in a file name according to the Inbound File Names. See EBICS Overview. In addition, the pertinent key information contained within the <HPBResponseOrderData> is also stored in the host file associated with this mailbox. 

  2. Optional. Click Cancel at any point to interrupt the download.

Printing initialization letters

If you have uploaded your keys to the bank through the INI and HIA transactions, the EBICS specification calls for separate hard copy letters.

  1. On the EBICS mailbox EBICS tab, click Print Initialisation Letters.

    Separate confirmation dialog boxes appears for each type of transaction - INI and HIA.

  2. Click OK for each confirmation.

    The system prints two letters containing the data according the EBICS specification. For more information, visit www.ebics.org.

Suspending your account

If your account or its associated keys have been compromised in some way, you can easily suspend your account.

On the EBICS mailbox EBICS tab, click Suspend My User Account.

The system executes the SPR order and displays a dialog box containing information about the order.

The SPR order is a special upload transaction, transmitting only the ES of a dummy one-space payload. Since only the ES is sent, the <OrderAttributes> will be set to UZHNN. See EBICS Overview. 

EBICS Mailbox: ES Tab

ES Certificate Alias
Password

Enter your ES Certificate Alias. This is the name of the ES certificate that is registered with the VersaLex application through the Certificate Manager. Click Browse to view and select this certificate.

Enter the for your certificate's private key.

Signature Class

If you are transacting business with a bank that is EBICS T compliant, then Signature Class should be set to Transport signature (type 'T'). If you are transacting business with a bank that is EBICS TS compliant, then Signature Class should be set to Single signature (type 'E'). Note that the A and B signature classes, as defined in the EBICS specification, will not be supported until VEU is fully supported. See EBICS Overview.

Note:

Referring to the EBICS specification and the ebics_signature.xsd schema (found at www.ebics.org), it appears that the element <OrderSignatureData> is unbounded within the <UserSignatureData> element. At this time, the VersaLex EBICS client supports only one instance of  <OrderSignatureData>. 

The bank server will maintain a record of your partner and user ID, along with your associated signature permission level. The mechanism the bank uses to obtain and initialize these records is outside the scope of the Cleo VerasLex EBICS client.

The EBICS specification requires that the certificate used for ES is different from the certificate used for identification and authentication and encryption. See EBICS Overview. See EBICS Mailbox: Certificates Tab for information about defining identification and authentication certificate and the encryption certificate.

EBICS Mailbox: Certificates Tab

My Certificates
Override Local Listener Certificates

Enables fields where you specify signing and encryption certificates to use with this particular partner instead of the certificates you configured for the Local Listener. See Configuring certificates for Local Listener.

If you override the default certificates, you must also exchange the certificates you specify here with your partner.

Signing Certificate Alias

The name of the signing certificate registered with the VersaLex application through the Certificate Manager. The certificate must be the same as the one exchanged with your remote trading partners, unless you want to override it at the Mailbox level. See Configuring certificates for Local Listener.

Click Browse to navigate to and select a certificate. Enter the Password for your signing certificate's private key.

Encryption Certificate Alias

The certificate for decrypting your trading partner’s messages, if you have created or obtained a separate certificate.

Click Browse to navigate to and select a certificate. Enter the Password for your encryption certificate.

Use signing certificate

Select this check box to use the same certificate for signing and decrypting your trading partner's messages. The Encryption Certificate Alias and Password are populated to match the Signing Certificate Alias and disabled.

EBICS Mailbox: HTTP Tab

Use the mailbox HTTP tab to assign Default Values for headers for GET and PUT. For EBICS, the default value of the Content-Typeheader must always be text/xml or application/xml.

EBICS Mailbox: Authenticate Tab

If the target server requires WWW authentication, select the appropriate type and provide a Username and Password and, optionally, theRealm.

EBICS Mailbox: Security Tab

Since it is mandated for EBICS, HTTP/s is pre-selected on the Security tab. With HTTP/s, the target bank server can issue client certificates. If so, import the client certificate using Certificate management and then specify (or browse to) the imported Certificate Aliasand specify a Password.  

EBICS Mailbox: Packaging Tab

See Configuring mailbox packaging for information about payload files packaging.

EBICS Trading Partner

A trading partner's parameters define a unique identifier on the host system. By default, the Trading Partner branch is not created since it is unnecessary for EBICS transactions.  

EBICS Action

An action's parameters capture a repeatable transaction for your mailbox on the host system. Create a new action under the mailbox.

EBICS Action: Action Tab

Use the Action tab to configure commands within an action.

The commands specified in the  host HTTP tab (as well as the local commands) are available for use. See EBICS Host, Composing an action, and  EBICS Command Reference.

Note: If a parameter or header value has an embedded space, you must use a \s to represent the space within the command. For example, %OPQ\scompany represents %OPQ company. This is done automatically in the dialog editor. If a space is left in the value, the command is not parsed correctly.

EBICS Command Reference

This section provides guidance for using Harmony EBICS host commands.

PUT

Send one or more files to the bank server.

PUT -DEL "source" OrderType=, 
[StartDate]=, [EndDate]=,[FileFormat]=, [CountryCode]=, 
[CustomParameters]=, name=value,...
-DEL

If PUT is successful, delete the local file.

"source"

Local source path

  • Path can be to a filename or to a directory.
  • * and ?, or a regular expression, are supported in filename. See Using wildcards and regular expressions for additional information.
  • If you specify a relative path, the command uses the default outbox.
  • Use of macro variables is supported. See Using macro variables (Source File context) for a list of the applicable macros.
  • If the path contains a space, dash (-), comma (,), or equal sign (=), it must be enclosed with double quotes ("...").
OrderType=,

This required parameter specifies the three-character code defined by the EBICS specification. The acceptable order types include the generic FUL or any supported upload request listed in Section 1 of Annex 2 to the Specification EBICS.

[StartDate]=, [EndDate]=

These optional parameters specify the start and end date, both of the form YYYY-MM-DD according to ISO 8601.  If a date range is specified, then both the StartDate and EndDate must be specified.   If the order type is not FDL or FUL, you can only specifyStartDate-EndDate if CustomParameters is not specified.

[FileFormat]=,

The file format must be of the form <area>.<syntax_and_format>.<description>.  See Section 2 of the Annex 2 to the Specification EBICS.  Note that, while this parameter is only applicable to certain order types, it is required for the FUL and FDL order types.  Also, macros are allowed when FileFormat is used on the PUT command (Destination File context).

[CountryCode]=,

If you specify the FileFormat parameter, you can also specify an optional two-character country code.  All country codes should comply with the ISO 3166-1 standard, including the "exceptional reservations" category (for example, "EU" indicates European Union).

[CustomParameters],

This optional parameter can contain one-to-many generic key-value pairs, each separated by a semi-colon.  If the order type is not FDL or FUL, you can only specify CustomParameters if StartDate-EndDate are not specified.

name

HTTP parameter=value and header=value pairs

GET

Receive one file from the bank server.

GET –UNI|-APE "destination" OrderType=, 
[StartDate]=,[EndDate]=, [FileFormat]=, [CountryCode]=,
[CustomParameters]=, name=value,...
-UNI

Ensure the local filename is unique.

–APE

If local filename exists, append the file.

"destination"

Local destination path

  • Path can be to a filename or to a directory.
  • * and ?, or a regular expression, are supported in filename. See Using wildcards and regular expressions for additional information.
  • If you specify a relative path, the command uses the default inbox.
  • Use of macro variables is supported. See Using macro variables (Source File context) for a list of the applicable macros.
  • If the path contains a space, dash (-), comma (,), or equal sign (=), it must be enclosed with double quotes ("...").
OrderType=,

This required parameter specifies the three-character code defined by the EBICS specification.   The acceptable order types include the generic FDL or any supported download request listed in Section 1 of Annex 2 to the Specification EBICS.

[StartDate]=, [EndDate]=

These optional parameters specify the start and end date, both of the form YYYY-MM-DD according to ISO 8601.  If a date range is specified, then both the StartDate and EndDate must be specified.   If the order type is not FDL or FUL, you can only specifyStartDate-EndDate if CustomParameters is not specified.

[FileFormat]=,

The file format must be of the form <area>.<syntax_and_format>.<description>.  See Section 2 of the Annex 2 to the Specification EBICS.  Note that, while this parameter is only applicable to certain order types, it is required for the FUL and FDL order types.  Also, macros are allowed when FileFormat is used on the PUT command (Destination File context).

[CountryCode]=,

If you specify the FileFormat parameter, you can also specify an optional two-character country code.  All country codes should comply with the ISO 3166-1 standard, including the "exceptional reservations" category (for example, "EU" indicates European Union).

[CustomParameters],

This optional parameter can contain one-to-many generic key-value pairs, each separated by a semi-colon.  If the order type is not FDL or FUL, you can only specify CustomParameters if StartDate-EndDate are not specified.

name

HTTP parameter=value and header=value pairs

SET

Change an action property value. The new value only affects the commands that follow the SET.

SET property=value
property = value

Action property and new value

  • The property name must have no embedded spaces.
  • The value specified remains in effect until it is set again or until the end of action.  

  • To reset property back to default value (host-level or system-level), specify

    SET property

    or

    SET property=
  • To clear a string property, use the CLEAR command

CLEAR

Clear an action property string value. The cleared value only affects the commands that follow the CLEAR.

CLEAR property
property

Action property name with no embedded spaces.

SYSTEM

Execute a local system command.

SYSTEM "path"
"path"

Local command path with arguments.

WAIT

Pause execution.

WAIT seconds
Seconds

Number of seconds to pause.

LCOPY

Copy one or more files locally.

LCOPY –DEL -REC {–UNI|–APE} {-ZIP|-UNZ} "source" "destination"
-DEL

If the command is successful, delete the local file.

-REC

Recursively search all subdirectories.

You cannot use this option with the -UNZ option.

-UNI

Ensure the copied filename is unique.

-APE

Append copied file to existing destination file.

-ZIP

Zip all the files into one or more ZIP archive files, depending on the destination specified.

  • Specify ZIP comment and compression level through Zip Comment and Zip Compression Level properties. See Setting advanced host properties.
  • The ZIP archive files created through the LCOPY command conform to the standard ZIP file format. Visit http://docs.oracle.com/javase/6/docs/api/java/util/zip/package-summary.html. The ZIP file format should not be confused with other popular file compression/archive formats such as GZIP, TAR, RAR, etc. The LCOPY command works only with ZIP-formatted files. In addition to the VersaLex application, there are many other software packages that can read/write ZIP-formatted files, for example, WinZip (Windows), File Roller (Linux), PKZIP and Info-ZIP (Windows/Linux/other Unix).
  • In addition to standard ZIP-formatted archives, the VersaLex application also supports password-based AES- encrypted ZIP files (128-bit, 192-bit, and 256-bit). See Cryptographic Services.
-UNZ

Unzip the source file(s).

  • All source files must be ZIP archive files.
  • You cannot use this option with the -REC option.
  • Use ZIP entry paths if Unzip Use Path is set. See Setting advanced host properties.
  • The ZIP archive files created through the LCOPY command conform to the standard ZIP file format (reference http://docs.oracle.com/javase/6/docs/api/java/util/zip/package-summary.html). The ZIP file format should not be confused with other popular file compression/archive formats such as GZIP, TAR, RAR, etc. The LCOPY command works only with ZIP-formatted files. In addition to the application, there are many other software packages that can read/write ZIP-formatted files, for example, WinZip (Windows), File Roller (Linux), PKZIP and Info-ZIP (Windows/Linux/other Unix).
  • In addition to standard ZIP-formatted archives, the VersaLex application also supports password-based AES- encrypted ZIP files (128-bit, 192-bit, and 256-bit). See Encryption of Zip Files for more information on this capability.
"source"

Source path

  • Path can be to a filename or to a directory
  • You can use * and ?, or a regular expression when you specify a filename. See Using wildcards and regular expressions for additional information.
  • If you specify a relative path, the command uses the default inbox.
  • You can use macro variables. See Using macro variables (Source File context) for a list of the applicable macros.
  • If the path contains a space, dash (-), comma (,), or equal sign (=), it must be enclosed with double quotes ("...").
"destination"

Destination path.

  • Path can be to a filename or to a directory.
  • If you specify a relative path, the command uses the default inbox.
  • You can use macro variables. See Using macro variables (Source File context) for a list of the applicable macros.
  • You can use a single * within the destination path. In this context, it is not a wildcard. Rather, it is used to substitute a source file name or a source subdirectory name. When * is used in conjunction with both the -REC and -ZIP options, and Zip Subdirectories Into Individual Zip Files is enabled, then * is substituted with each first-level subdirectory name. When* is not used for bundling zipped subdirectories, then it is used as a shortcut for the %sourcefilename% or %srcfilename%macro. Only one * is allowed in the destination path. See Setting advanced host properties.
  • When copying a file without the -APE option, or when copying a file with the -APE option where the destination file does not already exist, a temporary file name is used while the copy operation is taking place. This temporary file is placed in the destination directory. Its name begins with the product name and ends with .tmp. Once the copy completes successfully, the temporary file is renamed to the destination name.
  • If the path contains a space, dash (-), comma (,), or equal sign (=), it must be enclosed with double quotes ("...").

LDELETE

Delete one or more files locally.

LDELETE "source"
"source"

Source path.

  • Path can be a filename or a directory.
  • You can use * and ?, or a regular expression when you specify a filename. See Using wildcards and regular expressions for additional information.
  • If you specify a relative path, the command uses the default inbox.
  • Use of macro variables is supported. See Using macro variables (Source File context) for a list of the applicable macros.
  • If the path contains a space, dash (-), comma (,), or equal sign (=), it must be enclosed with double quotes ("...").

LREPLACE

Replace bytes in one or more files locally.

LREPLACE "source" Replace="input bytes" With="output bytes"
"source"

Source path.

  • Path can be to a filename or to a directory.
  • You can use * and ?, or a regular expression when you specify a filename. See Using wildcards and regular expressions for additional information.
  • If you specify a relative path, the command uses the default inbox.
  • You can use macro variables. See Using macro variables (Source File context) for a list of the applicable macros.
  • If the path contains a space, dash (-), comma (,), or equal sign (=), it must be enclosed with double quotes ("...").
"input bytes"

List of bytes to be replaced.

  • Comma separated list of byte values (0-255).
  • All bytes in comma-separated list must be found in the file in listed sequence in order to be replaced.
"output bytes"

List of bytes to be substituted for original input bytes.

  • Comma separated list of byte values (0-255).
  • If With parameter is omitted, then the input bytes are deleted from the file.

CHECK

See CHECK command for information about this advanced command.

SCRIPT

See to SCRIPT command for information about this advanced command.

EBICS Comment

# text...

Lines in the action starting with a # character are considered comments and will be ignored when the action executes. Lines starting with # are generally used for documentation purposes.

EBICS-Specific Directories

The following additional directories will be created either during the EBICS installation or as needed by the application.

Directory Purpose
EBICS\ack\sent\

The EBICS\ack\sent\ directory contains the sent application-level acknowledgments (those sent during the 'Receipt' step of an EBICS download transaction).  Acknowledgments are only stored if 'Save Sent Receipt' is set on the Local Listener Advanced tab.  Saved receipts are archived automatically according to the 'Archive ...' settings, also located on the Local Listener Advanced tab.  See Specifying Local Listener advanced properties.

Archive files are stored under EBICS\ack\sent\.
EBICS\schemas_2_4\

The EBICS\schemas_2_4\ directory contains XML schema (.xsd) files that describe the format of EBICS 2.4 documents.
EBICS\schemas_2_5\

The EBICS\schemas_2_5\ directory contains XML schema (.xsd) files that describe the format of EBICS 2.5 documents.
EBICS\sent+received\

The EBICS\sent+received\ directory contains copies of the raw outgoing requests and corresponding incoming responses.  These files can be helpful in diagnosing problems.   Old files should be deleted or archived by the user if necessary.

Within EBICS\sent+received\ , subdirectories further divide the data based on host ID, upload\nonce, download\nonce, or order type.
EBICS\unsent\

The EBICS\unsent directory contains transient copies of the raw XML associated with EBICS requests.  Files in the folder are removed once a transaction is complete.

EBICS Quick-Start Steps

Below are the steps to get started with an EBICS host.

Before Starting

Before starting, you must obtain the following parameters from your bank server:

  • URL, of the form https://remote-host:port/resource-path?optional-parameters  
  • Host ID
  • EBICS version supported (2.4 or 2.5)
  • ES (electronic signature) version supported (A005 or A006)

Before starting, you must provide the following parameters to your bank server:

  • Your Partner ID
  • Your User ID

Once you exchange the above information with your bank server, you can proceed to activate a generic EBICS host within VersaLex:

  1. Click the Templates tab in the tree pane.
  2. Right-click the Generic EBICS host under the Generic folder.
  3. Select Clone and Activate. 
  4. If desired, type a new host alias in the content pane panel and click Apply.
  5. From here, all changes will be made to the newly activated host.

Host Configuration

  1. On the EBICS Host General tab (see EBICS Host: General Tab) do the follwing:
    1. In the Server Address field, provide the remote-host section of the server's URL.
    2. In the Port # field, provide the port section of the server's URL.
  2. On the EBICS Host EBICS tab (see EBICS Host: EBICS Tab) do the following:
    1. In the Host ID field, provide the Host ID provided by your bank server. This identifier is case sensitive.

  3. For the HTTP GET and PUT commands on the EBICS Host HTTP tab (see EBICS Host: HTTP Tab):

    1. Since EBICS allows only the POST method, the Method fields will be pre-configured.
    2. In the Path fields, provide the resource-path section of your bank server's URL. 
    3. In the Parameters fields, provide the optional-parameters section of your bank server's URL

     . 

    1. Since EBICS allows 'text/xml' and 'application/xml', the Headers fields will be preconfigured for you.
  4. On the EBICS Host Advanced tab (see EBICS Host: Advanced Tab):
    1. Select the EBICS Filter Group to view the baseline configurable EBICS properties. The default properties related to SSL should be sufficient to begin. Note that the EBICS Version defaults to EBICS 2.4 and the ES Version defaults to A005. If the server requires a different setting, change these properties appropriately. For detailed information regarding EBICS-specific advanced properties, refer to the EBICS Host: Advanced Tab.
    2. While performing initial tests, it can be useful to set the Store Raw Sent And Received property. When set, the outgoing requests and corresponding incoming responses will be stored in the EBICS\sent+received folder. These files can be useful in diagnosing problems. However, after initial tests are complete and everything is running smoothly, you can disable this property to conserve disk space.

Mailbox Configuration

  1. On the mailbox EBICS tab:
    1. Fill in the My Partner ID field with the Partner ID provided to your bank server. This value is case-sensitive.
    2. Fill in the My User ID field with the User ID provided to your bank server. This value is case-sensitive.
  2. On the mailbox ES tab, fill in the ES Certificate Alias and Password fields associated with your ES certificate. EBICS requires that your ES certificate be different from the certificate you use for basic signing and encryption (those configured under the mailboxCertificates tab).
  3. On the mailbox Certificates tab:
    1. To override the baseline Local Listener certificates, select Override Local Listener Certificates and fill in the Signing Certificate Alias and Password, as well as the Encryption Certificate Alias and Password fields. Note that EBICS allows these certificates to be the same; however, they must be different from your ES certificate configured under the EStab.

At this point, no other configuration should be necessary. Proceed to Key Exchange.

Key Exchange

  1. Upload your ES key to the bank server.

    1. On the mailbox EBICS tab, click Upload My Keys.

      The Uploading My Keys dialog box appears.

    2. In the Order Type field, select Upload ES Key (INI), and then click Execute. 

      The message pane displays information regarding the INI transaction.

  2. Upload your signing (X002) and encryption (E002) keys to the bank server. 
    1. On the mailbox EBICS tab, click Upload My Keys.

    2. In the Order Type field, select Upload Signing and Encryption Keys (HIA), and then click Execute. 

      The message pane displays information regarding the HIA transaction.

      Note: Once the INI and HIA transactions have been successfully completed, the bank server should reject repeated attempts to transmit keys via INI and HIA. If you attempt this, you should receive EBICS_INVALID_USER_OR_USER_STATE from the server. To update your keys, use the PUB, HCA, and HCS orders through Upload My Keys.

  3. Download the bank's keys for signing (X002) and encryption (E002). 

    1. In the mailbox EBICS tab, click Download Bank Keys. 

      The message pane displays information about the HPB transaction.

Now you are ready to issue upload orders through the PUT command and download orders through the GET command. See EBICS Command Reference. You can also issue any of the ancillary orders through the mailbox EBICS tab Execute Ancillary Order function. For information about how to send and receive a test file, see Send and Receive a Test File.

Send and Receive a Test File

In the Action tab, run the <test> action. Executing the <test> action will send a sample file through an FUL order and then receive the same file through an FDL order type. See EBICS Action: Action Tab for more information. 

Related articles

Comments

0 comments

Please sign in to leave a comment.