OpenAS2 Server Application

Server Documentation

Version: 4.15.0

Copyright: Uhuru Technology

1. Introduction

The OpenAS2 application enables you to transmit and receive AS2 messages with EDI-X12, EDIFACT, XML, or binary payloads between trading partners. The AS2 implementation conforms with RFC4130 supporting the 1.1 specification.

This document describes how to install, configure and use OpenAS2. An appendix provides information on upgrade procedures as new versions of the application are released.

In this document a partner can be either your own company or a company you will be exchanging data with using AS2. A partner can receive and/or send documents to the other partner and each direction is controlled by a separate partnership configuration setup.

The sample configurations in this document are based on Unix type OS but in general the only significant difference is that it may be necessary to use “\” instead of “/” for folder name separators on Microsoft Windows based machines but because the application is Java it should work fine leaving the “/” for the most part as Java will do the conversion if necessary.

This document is valid for version 2.11.0 and up.

2. License

As of version 4.0.0 the default license is a GPL V3 license. If you wish to resell OpenAS2 either as a standalone service or embedded within your own product then you must apply for a commercial license from Uhuru Technology. You are of course permitted to continue using versions prior to 4.0.0 which were distributed under the BSD license.

3. Glossary

EDI – Electronic Data Interchange

MDN - Message Disposition Notification

JCE - Java Cryptography Extension

UI – User Interface

Partner – a definition of an entity that can receive or send AS2 messages to any other partner. A partner is a logical entity meaning you can have multiple partner entries defined for your own organisation as well as for other organisations you wish to exhange AS2 messages with

Partnership – a definition of how a sending partner connects to a receiving partner. For given partners A and B requiring both way transfers, there must be a separate partnership defined for each transfer direction.

4. Java Compatibility

The package downloaded from Sourceforge will only run on Java 11 and up. If you require Java 8 then it will require some additional work but you will not be able to use the web based configuration UI.

Currently the core OpenAS2 package is compiled on Java 8 but other supporting libraries used by the UI configuration API are compiled with Java 11 so to use Java 8 you will need to remove the API packages.

To do this remove all jar files in the “lib” folder that match the following patterns:

• *ws*

• grizzly*

• jersey*

Make sure you have not enabled the REST API command processor in the config.xml if you remove these files.

NOTE: The configuration UI and associated API is deprecated and will be removed in the next major release.

5. Basic Functional Overview

The OpenAS2 application provides the following mechanisms for sending and receiving files with a vanilla deployment:

• Files to be sent are placed in folders that are detected by directory polling modules and sent to the relevant destination AS2 partner using the AS2 protocoal. These polling modules are configured in XML and provide the ability to determine the target partner either based on the file being in a specific folder that is specifically designated for a target partner or a generic folder where the file name contains the relevant information to determine the target partner.
  If configured for an MDN response, the MDN response from the partner is stored in a folder defined by the MDN storage module

• Received files from partners are placed in a location defined the message storage module. The default configuration for OpenAS2 creates dedicated inbox folders per partnership.
  If configured for an MDN response, the application will automatically send an MDN that is by default signed.

All sent and received files are tracked in a database tracking system that updates the progress of the message state in the database at key points in the life cycle of message.

6. Installing OpenAS2

6.1. System Requirements

To be able to run the OpenAS2, you will need:

1. Java™ installed on the machine you intend to run the OpenAS2 server on – this document uses Java 1.7.refer to the compatibility notes for the minimum version of Java supported. Currently it is Java 11 or higher.

2. The OpenAS2 package version you wish to use. The downloadable packages can be found here: https://sourceforge.net/projects/openas2/files

3. Java Cryptography Extension (JCE) policy files you can download the correct version from the Java website. Search “Java Cryptography Extension Unlimited Strength“ to find the right cryptography extension for your version of Java. The current link for Java8 is here.

6.2. Installing Application

The following steps will provide an installed app on a target machine:

1. Unzip the downloaded OpenAS2 package into a suitable location, which we will refer to as <install_dir>.

   NOTE: Typical values for <install_dir> locations are /opt/OpenAS2 under Linux®/Unix or C:\OpenAS2 under Microsoft® Windows®. You can include the version number of the installed package in the folder name for ease of identifying the deployed version.

2. If on a Unix based system you may need to run this command to make shell scripts executable but most systems these days respect the file permissions embedded in the ZIP file:
   chmod 755 <install_dir>/bin/*.sh

3. For the encryption and certificate management to work correctly, you must have the proper JCE policy files installed in your version of Java (see system requirements above). The downloaded zip archive contains the two files local_policy.jar and US_export_policy.jar. Install them into your Java location under <JAVA_HOME>/lib/security. Back up the existing files before installing these new ones. There are numerous detailed articles on the web for installing these files if you need more information.

The file structure will look something like the figure below without the data and logs folders which are created automatically by the server when it starts based on configuration if they do not exist.

6.3. Tuning Java

The default settings for the Java virtual machine in the startup script (start_openas2.sh or start_openas2.bat) will work for installations on most machines for low volume/small file size transfers. However, if your system will be transferring large files or you want to use parallel processing mode for sending files to achieve very high throughput (see Directory Polling Configuration Attributes), you will need to increase memory allocation. If you expect to support very high inbound AS2 traffic you will need to increase memory allocation and possibly tune the garbage collector to get reasonable performance.

NOTE: See the section on splitting large files – it will be much more performant for very large files.

How much you can increase memory allocation to Java will depend on how much RAM is installed on the system running OpenAS2 and how many other processes will be running concurrently that will also require memory. Most systems deploy with at least 8GB RAM these days so increasing memory allocation from the default amount in the startup script should not cause adverse affects to the system.

To increase memory allocation you need to increase the heap space. This is set using the -Xmx option. You could increase this from the 384m (m = MB) default setting to 1g or 2g to get good performance for larger files or busy systems and for very large files given enough RAM you can set it to 6g or 8g. Search for “-Xmx” in the startup script and adjust accordingly.

For garbage collection you may want to allocate a more appropriate garbage collector than the default parallel collector that is the default in Java. In Java 7 and up, the G1 collector is ideal if you use large heap space allocation. To enable it add this to the command line parameter:

–XX:+UseG1GC

Based on basic internal testing and user feedback, the following are guidelines for setting your heap space (Xmx):

• files up to 50MB – 384m

• files up to 150MB – 756m

• files up to 300MB - 2g

• files up to 500MB – 3g

• files up to 750MB - 4g

7. Configuration Overview

NOTE: The recommended way to configure OpenAS2 is to use the properties file method as described in the section OpenAS2 Configuration Properties below. However, a fuller description of how OpenAS2 configuration works is provided in the next few sub sections allowing more advanced setup and customisation if desired.

7.1. Key Configuration Concepts

This section explains the details of the configuration files and how they link together.

The OpenAS2 server uses four files to configure and execute:

1. config.xml – configures the application such as the types of modules that are started, the logging systems, command processors and global properties. This is the key file for starting OpenAS2 and must be passed in either as a command line option or as an environment variable. If the application cannot find the file it will fail to start.
NOTE: This is the default name for the file and is referred to in this document by that name but you can use any name you like since it is passed in from the command line by the invoking batch script or can be set as an environment variable. The file path can be passed in as an environment variable named “OPENAS2_CONFIG_FILE” or you can directly modify the shell script. For example in the *nix shell script it is this line that determines the configuration file name and location and assumes the default folder structure is not changed when installing OpenAS2:
EXTRA_PARMS="$EXTRA_PARMS -Dopenas2.config.file=${binDir}/../config/config.xml"
The Microsoft batch file has a similar line.

Most values that may need to be modified for customized deployments or setting sensitive values such as passwords are extracted to properties at the top of the config.xml file which in turn can be overridden by an external properties file as described later in this document and is the preferred method of configuring the OpenAS2 server.

2. partnerships.xml – configures the partners and partnerships. Provides the ability to specify different signing and encryption algorithms, message compression, MDN handling etc
NOTE: This is the default name for the file and is referred to in this document by that name but you can use any name you like – see the Partner Configuration section below for how to set a different name.

3. as2_certs.p12 – a PKCS12 keystore that stores the SSL certificates used to secure the messages for all partners. It contains the primary key for your own company as well as the public keys for all your trading partners
NOTE: This is the default name for the file and is referred to in this document by that name but you can use any name you like – see the AS2 Certificate Configuration section below for how to set a different name.

4. commands.xml – the application provides a way to enter commands to control and configure the system whilst it is running either via the console or a remote tool (configured in the config.xml file above). This file stores the commands that the application will support. This file should not be modified.

7.2. Dynamic Configuration Changes

At startup, the application caches the configuration from the config.xml, partnerships.xml and the as2_certs.p12 files. The system will monitor the partnership configuration file and the asAS2 certificates file for any changes to the files after the application has started. If a change is detected in either of the files, the system will automatically refresh the partnership definitions or the certificates from the changed files as appropriate.

IMPORTANT: Currently the config.xml file and associated properties file are is notNOT monitored for changes and will require a restart of the application for any changes in thoseat files to be picked up.

7.3. “home” Configuration Parameter

The folder containing the config.xml file defines the home configuration parameter that can be used to reference other files on the file system relative to a known base folder in the app. This is done by encapsulating home in percentage signs (%home%). All files can be referenced relative to this parameter and it is how the default config.xml file defines the location of other configuration and data file locations used by the OpenAS2 application.

Therefore the default home location for %home% with the current default OpenAS2 folder structure will be:

[InstallDir]/config

7.4. Passing In Setting Configuration Values

The application supports 32 ways of passing in configuration parameters that can be used in the modify the config.xml file default settings without having to change the config.xml file. Using one or more of these methods instead of modifying the config.xml file makes it easier to upgrade to new releases.:

7.4.1. OpenAS2 Configuration Properties

This is the recommended approach to configuring OpenAS2.

All properties in the config.xml can be overridden using a properties file placed anywhere on the file system and made available to the OpenAS2 configuration engine by passing in the path to the file in an environment variable named “OPENAS2_PROPERTIES_FILE” and you would define it something like this in a Nix system:

export OPENAS2_PROPERTIES_FILE=/opt/OpenAS2/config/openas2.properties

Running the OpenAS2 startup script will then add the value from that environment variable to the Java invocation so that the configuration engines uses the properties from that file to override the default values in the config.xml file. A sample file with the current properties is provided in the config directory:

<install dir>/config/openas2.properties.sample

It is best to only put the values you are changing in the properties file defined in the OPENAS2_PROPERTIES_FILE environment variable so it is easy to know what you have changed from the default provided by the OpenAS2 package and will make upgrades simpler and for the most part seamless since generally OpenAS2 tries to remain fully backwards compatible.

Any properties added into this file will become available in the OpenAS2 configuration engine and will override any other values with matching property names within the engines context which includes all properties in the <properties> section of the config.xml file. If you want to configure your partnerships using properties then you can add any additional properties you want to use into the properties file and you can reference them using this format in the partnerships.xml file attribute values.

For instance, adding this to the properties file:

some_prop_name.enc_alg=MyPreferredEncryptionAlgorithm

… can then be referenced in the XML file like this:

<attribute name="encrypt" value="$properties.some_prop_name.enc_alg$"/>

7.4.2. Environment Variables

ThisUsing environment variables avoids exposing sensitive information in the execution environment. Any property defined in the parameterfile in the discussed in the previous section or any attribute value in the config.xml configuration file can be changed to source its value from an environment variable by setting the value of the property or parameter to include a string in this format as part of the value:


$ENV{env var name}


For instance, the password for the certificates file could be set like this in the external properties file:

as2_keystore_password=$ENV{AS2_CERTIFICATE_PWD}

… or like this in the <properties> element of the config.xml:
<certificates classname="org.openas2.cert.PKCS12CertificateFactory"
filename="%home%/as2_certs.p12”

passwordas2_keystore_password="$ENV{AS2_CERTIFICATE_PWD}"
interval="300"/>


Then set the password in the as an environment variable as below before running the startup script:


export AS2_CERTIFICATE_PWD=my_secret_password

7.4.3. System Properties

Properties can be passed into the application using the Java command line format:
-D<property name>=<property value>
The properties passed in this way will NOT overwrite any existing configuration properties in either the openas2.properties file of the properties section of the config.,xml so this mechanism is only useful for new properties you want top use for custom configuration.See All network modules that listen for inbound HTTP requests can be configured to bind to a specific IP address (or host name) on the server using the “address” attribute. These modules by default will bind to localhost (127.0.0.1). section of this document for an extended discussion on using system properties.

Environment variable replacement occurs BEFORE system properties so you can use environment variables to set properties in the config.xml which in turn are used for other config values. For instance, you can change this in the <properties> section of the config.xml:

<properties storageBaseDir="%home%/../data"

To:

<properties storageBaseDir="$ENV{storageBaseDir}"

Then setting the “storageBaseDir” environment variable will set the property which in turn sets that values where that property is used.

8. Dynamic Variables

Dynamic variables can be used in configuration files for run time replacement of strings. It allows using values that are determined either at startup or in real time at the time an action is taken in one of the modules supporting things like:

• referencing a common value across partnerships or modules using properties

• creating folder structures with names based on message identifiers, dates etc

• identifying the partners in an AS2 transaction

• changing the name of the file sent to the partner

• adding custom headers to the HTTP message

Some variables are specific to certain processor modules and not supported for all situations where dynamic variables can be used. The variables used in the configuration files are as follows:

• $properties.xxx$ - uses the value of a property xxx defined in the “properties” section of the config.xml
  where xxx is any valid attribute name and can contain periods
  for example: $properties.jakarta.mail.properties.file$ - gets the file for email configuration
• $date.xxx$ - create date strings in a defined format
  where xxx is any valid character formatting string defined in java.text.SimpleDateFormat
  for example: $date.yyyy$ gets the 4 digit year
  $date.MM$ gets the 2 digit month
  $date.dd$ gets the 2 digit day of month
  $msg.xxx.yyy$ - accesses various information contained in the AS2 message.
  • Typically used by file modules to configure the name of files used to persist the message payload.
    The “xxx” part can be any one of the following:
  • sender – accesses the “sender” element of the partnership in use for the current message. “yyy” can be any attribute name within the “sender” element
    eg. $msg.sender.as2_id$ - retrieves the AS2 ID of the sender of the message
  • receiver - accesses the “receiver” element of the partnership in use for the current message. “yyy” can be any attribute name within the “receiver” element
    eg. $msg.receiver.as2_id$ - retrieves the AS2 ID of the receiver of the message
  • attributes – accesses any attributes on the message. The attribute name is used in place of “yyy”
    The 2 generally available attributes are:
    • filename – this is the name of the file that will be sent as part of the AS2 message payload. This is how to access it as a dynamic variable:
      $msg.attributes.filename$
    • original_filename – the name of the file as it was when received by the OpenAS2 server for sending. This name can be changed by various mechanisms supported by AS2 so that the name of the payload sent to the partner is different to what it was when received by OpenAS2. Use it like this:
      $msg.attributes.original_filename$
    There are various ways to set additional attributes into the message context ($msg) so that you can then use those in dynamic string replacement.
  • headers - accesses any headers on the message. The header name is used in place of “yyy”. The following accesses the content type header for the AS2 message:
    $msg.headers.content-type$
    $msg.headers.message-id$ accesses the Message-ID header for the AS2 message
  • content-disposition - used to access any content-disposition attribute in the received message content disposition where the attribute identifier is used in place of “yyy”. The following accesses the name of the file received from the partner:
    $msg.content-disposition.filename$
  • hash - produces a hex digest of the content of the message payload. It is typically used to include a value in a file name that is unique to the content of the file so that repeated deliveries of the same file name do not overwrite an existing file unless the content is also identical. The digest algorithm is used in place of “yyy” and can be any of md5, sha1, sha256 or sha512, optionally followed by an underscore and the number of characters to truncate the digest to. Note that the digest is calculated over the payload so it is only available where the message content has been loaded. The following produces the first 16 characters of the SHA-256 digest of the payload:
    $msg.hash.sha256_16$
  $mdn.zzz$ for message mdn parameters, used by EmailLogger and MDNFileModule
  where zzz can be any of the following values:
  • msg – requires “zzz” to be in the form “xxx.yyy” and can access data points as defined for $msg.xxx.yyy$ format dynamic variables above
  • sender – gets the as2_id of the sender
  • receiver – gets the as2_id of the receiver
  • text - gets the text portion of the MDN
  • attributes – requires “zzz” to be in the form “xxx.yyy” and can access data points as defined for $msg.xxx.yyy$ format dynamic variables above
  • headers – requires “zzz” to be in the form “xxx.yyy” and can access data points as defined for $msg.xxx.yyy$ format dynamic variables above
  
  eg.: $mdn.text$ gets the text portion of the MDN
  $rand.zzz$ can be used on most strings to produce random strings.
  • Produces a random UUID or a 0 padded random number of a defined number of digits where zzz can be any string of any number of characters
  • if “zzz” is “UUID” or “uuid” (e.g $rand.UUID$) then it produces a random UUID
  • for any other string of characters other than UUID, the number of characters in the string determines the number of digits in the random number that is generated and will be zero padded
    e.g $rand.1234$ - creates a 4 digit random number between 0000 and 9999
    $rand.ax1fg4c5$ - creates an 8 digit random number between 00000000 and 99999999
  $exception.xxx$ -used by EmailLogger
  where xxx can be any of the following
  • name - retrieves name of the exception
  • message – retrieves the exception message
  • trace – retrieves the trace log for the exception
  
  eg.: $exception.trace$ gets the trace log of the exception
  $component.xxx$ -used in module configuration
  where xxx can be any of the attribute names specified above the attribute in the same module element. Can be used to simplify setting hard coded strings into a concatenated string used by the server module. See the DB tracking module definition for an example.

9. Application Configuration

The file named “config.xml” configures the modules that will be activated by the AS2 server when it starts up. This file can be located anywhere within the disk subsystem on which the OpenAS2 application runs as it is passed into the application as a startup parameter.

Some of the key configuration settings in the config.xml file are:

• define the modules to be activated in the OpenAS2 application

• override module default classes in the AS2 code base

• enhance or change behaviour of modules and the inputs and outputs of the modules.

• define the location of the certificates keystore and password

• define the location of the partnerships configuration file

• specify the listening ports

• enable support for high availability/load balanced environments

• change system behaviour via properties

See appendices for a detailed definition of the config.xml file structure.

There are 3 2 component groups configured in the config.xml that control plugin components for those groups. All the plugin components can be enabled/disabled by settingan the appropriate “enabled” attribute on the componentproperty in a properties file explained in the previous section and generally the enabled value is available to be set in the properties at the head of the config.xml file if you want to change the config.xml file.

The component groups are :

1. Loggers

• The <loggers> element is the parent element for all logger plugins and each logger is defined in a <logger> element.

• The loggers provide different output destinations for logging and some of the loggers are disabled by default

• The “enabled” attribute in the <logger> element is required and can be either “true” or “false”

2. Command processors

• The <commandProcessors> element is the parent element for all command processor plugins and each command processor is defined in a <commandProcessor> element.

• Command processors support configuration and system setting query commands and some of these command processors are disabled by default.

• The “enabled” attribute in the <commandProcessor> element is required and can be either “true” or “false”

1. Certificates

• The <certificates> element is the parent element for all certificate handlers

• There is one required handler for AS2 certificates and a 2^nd that is disabled by default for the self signed certificate trust keystore

2. Modules

• The <processor> element is the parent element for all module plugins and each module is defined in a <module> element.

• Modules support ca variety of functions in OpenAS2 such as directory polling, receivers for AS2 and MDN messages, file system persistence and health checks. Some modules are disabled by default.

• The “enabled” attribute in the <commandProcessor> element is NOT required and can be either “true” or “false”. If the attribute is not present on the <module> element then it will default to “true”

There are 2 listening ports for inbound connections (see partnerships.xml config for outbound connections) used for:

1. receiving messages and synchronous MDN's – default port number 10080

2. receiving asynchronous MDN's - default port number 10081

The port numbers are arbitrary and defaulted to a number above 1024 that does not require root access to listen on (normally on Unix type systems any port below 1024 requires root access). The port values are important to the partner you will be communicating with if they will be sending AS2 messages to your system. For outbound only systems, it is only necessary to have a listener for asynchronous MDN's if using that mechanism for MDN's.

Each module has a number of attributes that can be configured on the module elemenusing propertiest to control and change how the module behaves.

All network modules that listen for inbound HTTP requests can be configured to bind to a specific IP address (or host name) on the server using the “address” attribute. These modules by default will bind to localhost (127.0.0.1)..

System Level Properties

9.1. Properties can be passed into the application in a 2 ways:

Command line- this uses the Java command line format of:
-D<property name>=<property value>
The default bash script can be used pass these in by invoking the script with the additional properties. For instance, to change the default “storageBaseDir” property you would do this:
./start_openas2.sh -dstorageBaseDir=/opt/OpenAS2Data

Separate properties file that will override the defaults – see below for details on usage.

There are a number of properties that can be defined in the config.xml <properties> element that apply globally to functionality in the system. These are discussed in the relevant functional area they apply to.

These properties can be overridden using a separate properties file or using command line properties. To use an overriding properties file, pass the properties file name including path in a Java system property on the command line using the property named “openas2.properties.file”. If this is found in the Java system properties then the properties from this file will override any properties in the config.xml <properties> element. So for example you could create a file “my.properties” with the following in it:

storageBaseDir="%home%/../data"

log_date_format="yyyy-MM-dd HH:mm:ss.SSS"

sql_timestamp_format="yyyy-MM-dd HH:mm:ss.SSS"

email.logger.enabled="false"

Start the OpenAS2 app by adding this to the startup command:

-Dopenas2.properties.file=my.properties

Properties can also be used in the XML configuration for config.xml processors or in the partnerships configuration to facilitate changing in one place instead of having to change in multiple places. An example of this is the “storageBaseDir” property used in the config.xml.

Properties are also used to enable and disable configuration components as discussed in the previous section.

A <properties> element attribute can be used to define the "as2_url” in one place and then the partnerships files just use that property reference.

For example having this in the config.xml:

<properties storageBaseDir="%home%/../data"

as2_async_mdn_url="http://localhost:10081"

/>

Then setting the “as2_receipt_option” as shown below will mean you only have to change the async MDN URL in one place and use the following in all partnerships using async MDN mode:

<attribute name="as2_receipt_option" value="$properties.as2_asyn_mdn_url$"/>

You can also embed properties references within other properties to limit the number of places things must be changed for a single change. As an example, the Asyn MDN recevier module port might need to be changed and will need to be reflected in the partnership config:

<properties storageBaseDir="%home%/../data"

async_mdn_receiver_port="10081"

as2_async_mdn_url="http://localhost:$properties.async_mdn_receiver_port$"

/>

Then you can use the as2_async_mdn_url property in the partnership for async MDN as shown above and the async_mdn_receiver_port property in the config for the async MDN module:

<module enabled="$properties.module.AS2MDNReceiverModule.http.enabled$"

classname="org.openas2.processor.receiver.AS2MDNReceiverModule"

port="$properties.async_mdn_receiver_port$"/>

9.2. Sending Files

OpenAS2 has a directory polling module that scans configured directories for files and will send the file to a partner. The directory scanner will check each file it finds for 2 consecutive poll cycles and if the size has not changed then it will push the file into the send queue.

The destination partner for the files is determined in 2 possible ways:

1. Configuring a specific folder to be mapped to a specific partnership configuration.
   This is the preferred mechanism for sending files. All files dropped in a specified folder will be sent to the same partner. Each partnership entry must explicitly be enabled to have a poller.

2. A single generic directory for files destined to any partner configured in the config.xml file.
   This mechanism will process files for all partnerships in series unless you enable parallel processing and can make it much harder to debug when things go wrong. There is a sample configuration provided in the installation package config.xml. This requires the name of the file to be in a very specific format. See the next sub section for details on how this works.

9.2.1. Directory Polling Configuration Attributes

The partner to send to is determined either by a dedicated folder for a partner or using a generic folder where the target partner is identified by parsing the file name of the file found by the directory polling module. Some of the kCommoney attributes for the polling modukle defined in the config.xml are:

• outboxdir – a text string that can contain dynamic variables the will be evaluated at startup to produce a file path that specifies the directory to scan for files to send.

• errordir - specifies the directory to put files in when something goes wrong trying to send the file

• interval - specifies how many seconds between each scan of the directory

• sendfilename - specifies that the sent message must include the file name for the remote partner

• mimetype – sets the mime type in the header for the file in the message sent to the partner

• process_files_in_parallel – by default each detected file is processed in series which has a significantly lower throughput. The default value for this is “false”. Typically it will process a 10K file in just under a second meaning if files arrive at a slightly faster rate there will be a growing backlog. Set this to “true” to process files in parallel.
  IMPORTANT NOTE: Parallel processing is likely to consume more memory (RAM) so make sure your server has sufficient RAM to cope. If you are consistently transferring very large files (>100MB) in high volume then parallel processing may not be a good idea.

• max_parallel_files – if parallel processing is enabled for the poller then this attribute will limit how many files are processed in parallel simultaneously. The default value for this is “20”. The bigger the average size of the files, the smaller you should make this value to avoid memory issues that could significantly slow down the processing speed.

For all poller attributes, the following dynamic variables can be used within value string for all forms of poller configuration:

• $properties.*$

• $date.*$

• $random.*$

For the pollers configured in the partnership, an additional property cane be use top access partnership and associated partner attributes using the following format:

• $partnership.name$ - gets the partnership “name” attribute value

• $partnership.sender.XXX$ - gets the an attribute value from the partner node associated as the sender in the partnership

• $partnership.receiver.XXX$ - gets the an attribute value from the partner node associated as the receiver in the partnership

In the above, the XXX can be any of:

• name

• as2_id

• x509_alias

See the section on partnerships defined pollers below for an example.

9.2.2. Partnerships XML Defined Directory Poller

This poller is configured as a child element of the partnership element that requires a poller in the partnerships.xml file. Only partnerships that must SEND files should have this configuration.

The advantage of this poller configuration is that the directory poller is automatically removed if the partnership is disabled or removed and retains a cleaner configuration over time.

When the OpenAS2 server detects a change to the partnerships.xml file it will automatically clear all existing partnerships defined pollers and reload all partnerships, starting any pollers for the partnerships configured to load a poller module.

The base configuration for these pollers is stored in the config.xml file in the “pollerConfigBase” element. Each attribute in this base element can be overridden in the partnership. The base configuration defines the outboxdir to include the name of the partnerships receiver AS2 ID allowing it to be used in any partnership element without requiring an override. If the base configuration outboxdir is changed, be aware that this can adversely affect existing deployed partnerships using the partnership enabled poller.

The minimum required setting in a partnership to enable a poller is shown below. Insert the shown element as a child of the <partnership> element to enable a poller for that partnership:

<pollerConfig enabled="true"/>

If the “enabled” attribute is set to any value other than “true” or the attribute is not present then a poller will not be added for that partnership.

The below properties define the default values for partnership configured pollers:

pollerConfigBase.outboxdir="$properties.storageBaseDir$/outbox/$partnership.receiver.as2_id$"

pollerConfigBase.errordir="$properties.storageBaseDir$/outbox/error/$date.yyyy$-$date.MM$-$date.dd$/$partnership.receiver.as2_id$"

pollerConfigBase.interval="5"

pollerConfigBase.defaults="sender.as2_id=$partnership.sender.as2_id$, receiver.as2_id=$partnership.receiver.as2_id$"

pollerConfigBase.sendfilename="true"

pollerConfigBase.mimetype="application/EDI-X12"

pollerConfigBase.process_files_in_parallel="false"

pollerConfigBase.max_parallel_files="20"

pollerConfigBase.max_file_processing_time_minutes="30"

Do not change the “defaults” attribute unless you know what you are doing – it is specified to retrieve the sender and receiver AS2 ID’s from the partnership that the poller is configured in and changing it will cause the poller to fail to know where to send files to or send them to the incorrect destination. The file name sent to the partner will be exactly the name of the file as it is when detected by the directory polling module unless there is some other configuration to override the file name as defined in the “File Name Parsing” section further down in this document.

If you want to override any of the pollerConfigBase properties values on a per partnership basis, put the relevant attribute you want to override into the pollerConfig element in the partnership.

For example, to override the outdboxdir attribute, you would have this in the pollerConfig element:

<pollerConfig enabled="true" outboxdir="/my/specific/base_dir/$partnership.receiver.as2_id$"/>

The rest of the values will use the pollerConfigBase .* values for that partnership.

9.2.3. Generic Send Directory Poller

This uses a generic directory for receiving files to send to a paaprtner defined by the “outboxdir” attribute and relies on the file name to be in a specific format to extract the sender and receiver ID’s. In the example config.xml file, there is a directory polling module configured with the below XML:

<module classname="org.openas2.processor.receiver.AS2DirectoryPollingModule"

outboxdir="$properties.storageBaseDir$/toAny"

errordir="$properties.storageBaseDir$/toAny/error"

interval="5"

delimiters="-."

mergeextratokens="false"

sendfilename="true"

format="sender.as2_id, receiver.as2_id, attributes.filename"

process_files_in_parallel="false"

max_parallel_files="20"

mimetype="application/EDI-X12" />

• delimiters a - attribute specifies how to split the file name into multiple parts.

• format d - defines the variables that will be set based on the parsed file name. Using the value set in the example above, the first three parts of the split file name set the sender, receiver and filename.

• mmergeextratokens - forces any extra tokens from splitting the file name using the delimiters to be merged into the final token from the “format” attribute

So for this example, a file name of the form:

MyCompany-YourCompany-TheEdiFileNameToBeSent.edi

would send a message from the AS2 ID “MyCompany” to AS2 ID “YourCompany” and send the file name as “ TheEdiFileNameToBeSent”. If you wanted to include the “.edi” extension in the file name to be sent then the “delimiter” attribute must NOT contain the “.” character OR set the “mergeextratokens” attribute to “true”. See the File Name Parsing“File Name Parsing” section further down in this document for more details.nn

$partnership.receiver.as2_id$$partnership.receiver.as2_id$ $ sentdir="$properties.storageBaseDir$/outbox/sent/$partnership.receiver.as2_id$/$date.YYYY$-$date.MM$-$date.dd$"

is f and changing it will cause the poller to fail to know where to send files to

If you want to override any of the attributes from the pollerConfigBase element, you simply put the relevant attribute you want to override into the pollerConfig element in the partnership.

For example, to override the outdboxdir attribute, you would have this in the pollerConfig element:

<pollerConfig enabled="true" outboxdir="/my/specific/base_dir/$partnership.receiver.as2_id$"/>

The rest of the attributes will be sourced from the pollerConfigBase element.

Dedicated Sending

9.2.4. Directory

The below XML defines a dedicated directory for files to be sent to a specific partner:

<module

classname="org.openas2.processor.receiver.AS2DirectoryPollingModule"

outboxdir="$properties.storageBaseDir$/toPartnerA/"

errordir="$properties.storageBaseDir$/toPartnerA/error"

interval="5"

defaults="sender.as2_id=MyCompany_OID, receiver.as2_id=PartnerA_OID"

sendfilename="true"

mimetype="application/EDI-X12"/>

The “defaults” attribute specifies the sender and receiver AS2 ID’s for any file that lands in the folder. The file name sent to the partner will be exactly the name of the file as it is when detected by the directory polling module unless there is some other configuration to override the file name as defined in the “File Name Parsing” section further down in this document.

9.2.5. Restricting Directory Files By Extension Or Name

The directory polling module can be configured to only use files with a specific extension and/or exclude files with a specific extension and/or exclude files based on a regular expresssion match on the entire file name.

The attributes allow multiple extensions to be defined using a comma as separator that can contain spaces before or after the comma. This is configured adding either or both of the following attributes for either of the above examples for a directory polling module although it does not make sense to use both at the same time:

fileextensionfilter="doc, docx, txt, edi"

fileextensionexcludefilter="tmp"

filenameexcluderegexfilter=".+Tmp[.]{1}.+"

The attributes above are evaluated as an AND function so if any of the filters excludes a file it ignores the other filters and excludes the file from processing.

Using the above attributes, files with “.tmp” on the end of the file name or with “Tmp.” in the file name will be ignored and only files with “.doc” “.docx”, “.txt”, “.edi” will be processed.

NOTE: Using both “fileextensionfilter” and “fileextensionexcludefilter” at the same time is generally redundant since the “fileextensionfilter” does NOT include “tmp” extensions so the “.tmp” will be ignored with just the “fileextensionfilter” option in this example.

9.2.6. Auto Splitting Large Files

Configuration can be added per partnership definition to automatically split files into smaller files for sending to a partner. This only works for line based files where the file contains information that is split up into multiple lines and the splitter reads the input file line by line calculating the size of each line and adding to a running tital until it the total exceeds the specified maximum size. Typically this is used for very large CSV files.

The following attributes can be added to the partnership definition that defines sending a file from your location to your partner:

<attribute name="split_file_threshold_size_in_bytes" value="1073741824"/>

<attribute name="split_file_contains_header_row" value="true" note="If true, the header row will be repeated in each file"/>

<attribute name="split_file_name_prefix" value="SF" note="Each split file name will be prefixed with the string specified here if set"/>

The attributes have the following effect:

• split_file_threshold_size_in_bytes – specify in bytes the threshold size of the file to be sent. The actual size will at most be the specified threshold size plus the length of line that crosses the threshold so if your lines could be very long and the file size is critical, specify a smaller size to accommodate.

• split_file_contains_header_row - If set to “true”, the header row will be repeated in each file. If omitted or set to any other value, this attribute has no effect.

• split_file_name_prefix" - Each split file name will be prefixed with the string specified here. if set. If omitted or set to the empty string, this attribute has no effect.

Each new file will be prefixed with a zero padded incrementing counting reflecting the files being created from the source file.

Using the example attributes above, files will be split at 1GB into multiple files where if the source file name is a 3GB file named my_test_data.csv, the resulting files sent to the partner would be SF01-my_test_data.csv, SF02-my_test_data.csv, SF03-my_test_data.csv and each file would have the first row from the original source file repeated in each file sent.

NOTE: The partner will receive multiple files where the file name will be prefixed with a unique zero padded identifier to give the split files a unique reference as explained above.

9.2.7. Queue Based Sending

As an alternative to polling a directory, files to be sent can be sourced from a message queue using the JmsPollingModule. An external system publishes a message to the queue identifying the sender and receiver AS2 IDs and the location of the file to be sent, and OpenAS2 consumes that queue message and sends the file through the normal sending pipeline. Any broker supporting AMQP 1.0 can be used, for example Azure Service Bus, via the Apache Qpid JMS client.

This decouples the production of files from OpenAS2 and allows the broker to own the retry and dead-lettering behaviour. Because the queue is shared, multiple OpenAS2 instances can consume from the same queue to provide high availability and failover. Note that the total outbound concurrency is the number of instances multiplied by the consumer_count value so keep it within the connection limits your partners allow.

The file itself is not carried in the queue message. The queue message identifies a file that must be readable by the OpenAS2 instance that consumes it, so the file must be on shared storage if more than one instance is consuming from the queue.

The module is enabled by adding it to the processor section of the config.xml as shown below:

<module classname="org.openas2.processor.receiver.JmsPollingModule"

broker_url="amqps://your-namespace.servicebus.windows.net"

broker_user="$properties.servicebus.sas_key_name$"

broker_password="$properties.servicebus.sas_key$"

queue_name="outbound-as2"

consumer_count="1"

sender_id_property="sender_as2_id"

receiver_id_property="receiver_as2_id"

filepath_property="filepath"

filename_property="filename"

errordir="$properties.storageBaseDir$/outbox/error/$date.yyyy$-$date.MM$-$date.dd$"

sentdir="$properties.storageBaseDir$/sent"

mimetype="application/EDI-X12"/>

The attributes are as follows:

broker_url - the AMQP URL of the broker to connect to.

broker_user and broker_password - the credentials used to connect to the broker. For Azure Service Bus these are the shared access key name and the shared access key.

queue_name - the name of the queue to consume the messages from.

consumer_count - the number of concurrent consumers this instance will run against the queue. Defaults to 1.

sender_id_property and receiver_id_property - the names of the properties on the queue message that hold the AS2 ID of the sender and of the receiver. These are used to identify the partnership to send the file with.

filepath_property and filename_property - the names of the properties on the queue message that identify the file to be sent.

errordir and sentdir - the directories the file is moved to after a failed or a successful send, as for the directory polling module. Both support dynamic variables.

mimetype - the content type set on the message sent to the partner.

9.3. Receiving Files

In order otto receive and persist files over AS2 from a partner you must have the following configured:

1. A network receiver module – receives files over the network from a partner. There can be multiple receiver modules listening on different ports and these can be configured to use HTTPS as defined in the “Inbound Transfers” section for using HTTPS. This module extracts the file from an AS2 message and then searches for a module that can process the extracted file

2. A file handler module – this module is responsible for persisting the file extracted from the received AS2 message or handing it off for further processing.

The default configuration provided with the OpenAS2 installer There is not much to configure for receiving files. As long as there is an AS2 receiver handler active, messages will be received and the files stored in the configured directory for the MessageStorageHandler module. The default modules for receiving and storing files in the config.xml file properties section is shown below.

<module classname="org.openas2.processor.storage.MessageFileModule"

filename="$properties.storageBaseDir$/$msg.sender.as2_id$-$msg.receiver.as2_id$/inbox/$msg.content-disposition.filename$-$msg.headers.message-id$"

header="$properties.storageBaseDir$/$msg.sender.as2_id$-$msg.receiver.as2_id$/msgheaders/$date.yyyy-MM-dd$/$msg.content-disposition.filename$-$msg.headers.message-id$"

protocol="as2"

tempdir="$properties.storageBaseDir$/temp"/>module.MessageFileModule.enabled="true"

module.MessageFileModule.filename="$properties.storageBaseDir$/$msg.sender.as2_id$-$msg.receiver.as2_id$/inbox/$msg.headers.message-id$"

module.MessageFileModule.header="$properties.storageBaseDir$/$msg.sender.as2_id$-$msg.receiver.as2_id$/msgheaders/$date.yyyy-MM-dd$/$msg.headers.message-id$"

module.MessageFileModule.tempdir="$properties.storageBaseDir$/temp"

module.AS2ReceiverModule.http.enabled="true"

module.AS2ReceiverModule.http.port="10080"

<module classname="org.openas2.processor.receiver.AS2ReceiverModule"

port="10080"

errordir="$properties.storageBaseDir$/inbox/error"

errorformat="sender.as2_id, receiver.as2_id, headers.message-id"/>

9.3.1. Overriding Storage Location Per Partnership

The “filename” attribute for the message storage module determines where the received file will be stored and in which directory. This can be overridden per partnership so that file storage locations can be completely different to the default location. To do this, add a store_received_file_to attribute to the partnership

<attribute name="store_received_file_to" value="$properties.storageBaseDir$/inbox/$msg.receiver.as2_id$/inbox/$msg.sender.as2_id$-$rand.12345$-$msg.content-disposition.filename$"/>

The above adds the sender AS2 ID into the file name and stores it in a folder specific to the receiver AS2 ID.

9.3.2. Providing Default File Name

Normally the sender will send the name of the file in the payload headers but is not required in AS2 so you can set a default filename for this case.

It is set in the config.xml file properties section using attribute as2_receive_message_filename_fallback as shown below. It supports $msg, $date and $rand style dynamic parameters.

<properties

storageBaseDir="%home%/../data"

log_date_format="yyyy-MM-dd HH:mm:ss.SSS"

sql_timestamp_format="yyyy-MM-dd HH:mm:ss.SSS"

as2_message_id_format="OPENAS2-$date.ddMMyyyyHHmmssZ$-$rand.UUID$@$msg.sender.as2_id$_$msg.receiver.as2_id$"

as2_async_mdn_url="http://localhost:10081"

as2_receive_message_filename_fallback="$rand.shortUUID$"

/>

To override this set the property in the openas2.properties file.

9.4. AS2 Message State Tracking To Database

9.4.1. Default Database Message State Logging

As of version 2.1.0 the system will track key events in the message transmission and reception process and invokes any configured action handlers that can then process the information in some way. The default deployment of OpenAS2 supports a database tracking module that will write the message state to an embedded H2 database. As an AS2 message is processed, key points are logged to the database for a given message as a single record. As the message reaches the next state, the system overwrites the previous state.

The database tracking uses the module "org.openas2.processor.msgtracking.DbTrackingModule".

Configuration parameters for the database tracking functionality are shown in the table below.

** IMPORTANT: Using a different table name requires ensuring that the database schema has the same table name. See the appendices for information on creating the schema.

9.4.2. Managing the Default Embedded H2 Database

The user name and password for the H2 database can be changed using either a JDBC connection or the command line tool as described below. It is recommended that a readonly user is added for reading data from the database.

To connect to the H2 database whilst OpenAS2 is running use this JDBC connect string:

jdbc:h2:tcp://localhost:9092/openas2

To query the database from the command line, you must have OpenAS2 running then use this command:

java -cp [path to OpenAS2 install]/lib/h2-1.4.197.jar org.h2.tools.Shell -user sa -password OpenAS2 -url jdbc:h2:tcp://localhost:9092/openas2

There is a script in the bin folder named db_connect.sh that will do the above for you.

There is a file named db_ddl.sql file located in the config folder that can be used to create the necessary table structure if your DB becomes corrupted.

Run the command found in the “bin” directory of your install in the order defined to recreate the DB if you are on a unix based system or use the “No script option” if you are on Microsoft Windows. Run the command with “-h” option to get the command line options:

• h2_create_new_db.sh -P <your DB password>
No script option: java -cp <path to install dir>\lib\h2-<version of H2 lib>.jar org.h2.tools.RunScript -user sa -password <password> -url jdbc:h2:<path to install dir>/config/DB/openas2 -script <path to install dir>/config/db_ddl.sql

The other way to recreate the database table is using this command whilst OpenAS2 is running:

java -cp [path to OpenAS2 install]/lib/h2* org.h2.tools.RunScript -user sa -password OpenAS2 -url jdbc:h2:tcp://localhost:9092/openas2 -script [path to OpenAS2 install]/config/db_ddl.sql

NOTE: The version of H2 deployed with the application only works in Java 7 or higher. Download the older version of H2 that was compiled with support for Java 1.6 if you wish to use Java 6: https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/h2database/h2-2014-01-18.zip (Replace the jar in the OpenAS2 lib folder with that version and change the startup script to include the replaced version of H2, delete the files in <installDir>/config/DB, restart OpenAS2 server and recreate the database using the command referenced above).

See appendixes for information on creating external database DDL statements and updating the existing database if the schema is changed in a new release.

9.4.3. Using An External Database For Message State Tracking

Use of an external database can be configured for any database that has a JDBC driver such as Oracle, MySql, MariaDB, SQLServer or Postgresql.

To use an external database:

• put the appropriate JDBC driver jar for the SQL system you want to use into the “lib” folder of the OpenAS2 install

• the “use_embedded_db” attribute must be set to “false” and the appropriate settings changed in the database tracking module XMLproperties.

Below is a sample properties configuration for using a Postgresql database in the openas2.properties file:

<module classname="org.openas2.processor.msgtracking.DbTrackingModule"

use_embedded_db="false"

force_load_jdbc_driver="false"

db_user="sa"

db_pwd="OpenAS2"

db_name="openas2"

db_directory="%home%/DB"

jdbc_driver="org.postgresql.Driver"

jdbc_connect_string="jdbc:postgresql://localhost:5432/$component.db_name$"

sql_escape_character="'"

/>msg_tracking.use_embedded_db="false"

msg_tracking.force_load_jdbc_driver="false"

msg_tracking.db_user="sa"

msg_tracking.db_pwd="OpenAS2"

msg_tracking.db_name="openas2"

msg_tracking.table_name="msg_metadata"

msg_tracking.jdbc_connect_string="jdbc:postgresql://db.url.com:5432/$component.db_name$"

msg_tracking.sql_escape_character="'"

The user name and password can be changed using either a JDBC connection or the command line tool as described below. It is recommended that a readonly user is added for reading data from the database.

To connect to the H2 database whilst OpenAS2 is running use this JDBC connect string:

jdbc:h2:tcp://localhost:9092/openas2

To query the database from the command line, you must have OpenAS2 running then use this command:

java -cp [path to OpenAS2 install]/lib/h2-1.4.197.jar org.h2.tools.Shell -user sa -password OpenAS2 -url jdbc:h2:tcp://localhost:9092/openas2

There is a script in the bin folder named db_connect.sh that will do the above for you.

There is a file named db_ddl.sql file located in the config folder that can be used to create the necessary table structure if your DB becomes corrupted.

Run the command found in the “bin” directory of your install in the order defined to recreate the DB if you are on a unix based system or use the “No script option” if you are on Microsoft Windows. Run the command with “-h” option to get the command line options:

• h2_create_new_db.sh -P <your DB password>
No script option: java -cp <path to install dir>\lib\h2-<version of H2 lib>.jar org.h2.tools.RunScript -user sa -password <password> -url jdbc:h2:<path to install dir>/config/DB/openas2 -script <path to install dir>/config/db_ddl.sql

The other way to recreate the database table is using this command whilst OpenAS2 is running:

java -cp [path to OpenAS2 install]/lib/h2* org.h2.tools.RunScript -user sa -password OpenAS2 -url jdbc:h2:tcp://localhost:9092/openas2 -script [path to OpenAS2 install]/config/db_ddl.sql

NOTE: The version of H2 deployed with the application only works in Java 7 or higher. Download the older version of H2 that was compiled with support for Java 1.6 if you wish to use Java 6: https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/h2database/h2-2014-01-18.zip (Replace the jar in the OpenAS2 lib folder with that version and change the startup script to include the replaced version of H2, delete the files in <installDir>/config/DB, restart OpenAS2 server and recreate the database using the command referenced above).

See appendixes for information on creating external database DDL statements and updating the existing database if the schema is changed in a new release.

9.4.4. Optimising External Database Performance

When using an external database, the Hikari connection pool is used to improve performance. The pool can be optimised using the Hikari configuration properties as defined here:

https://github.com/brettwooldridge/HikariCP/blob/dev/README.md#gear-configuration-knobs-baby

Add a file named hikari.properties in the config folder with settings for the properties you want to optimise.

9.5. Overriding Certificate Store Password

The certificate store password is stored as thean XML attribute “password” property with key name “ssl_keystore_password” on the <certificates> element.

The following mechanisms to avoid storing a password in a file on the file system are supported for improved password security:

1. This can be overridden uUsing the system property “org.openas2.cert.Password”. For improved security, it may not be desired to store the password in the XML file.

2. 
   This can be passsed into the application by adding the following to the java command:

3. 
   -Dorg.openas2.cert.Password=myCertificateStorePassword

4. Setting an environment variable with the password then overriding the password property in the opensas2.properties file referencing the environment variable something like this:
   ssl_keystore_password=$ENV{MY_AS2_PWD_ENV_NAME}

This can be set by using an additional parameter to the batch script file so that it can be set as part of invoking the script. The UNIX shell script will support the password as a parameter. The Windows bat file will need to be enhanced.

9.6. Resend Retry Configuration

When failures occur transferring a message to a trading partner, the system will automatically try to resend the message. By default the system will retry indefinitely.

The following properties control the resending of messages:

• module.DirectoryResenderModule.enabled=true --- Handles resending AS2 messages if there are any failures in sending the AS2 message include failure to receive an MDN.

• module.DirectoryResenderModule.resenddelay=60 --- How long in seconds before the resender module attempts to resend a failed tranmission of an AS2 message.

• resend_on_ssl_exception=true --- if set to “true” then when an SSL exception occurs trying to connect to a partner, the message will go into a retry loop. The default is “false”.

When using asynchronous MDN responses, the system will try to resend the asynchronous MDN using the same logic in terms of how many times it will retry sending it.

IMPORTANT: An AS2 message (or asynchronous MDN) that is put into the retry queue will use exactly the same parameters as when it was first sent. Therefore any changes to partnership such as destination URL, Async MDN response URL, signing algorithm etc. for that message after the first attempt to send the message will NOT be picked up by the message. The message must be deleted from the resend queue if changes were needed in the partnership definition and the message resent by passing in the file it was supposed to send again.

Restricting the retry attempts can be done at the processor level (applies to all partnerships configured on the server) and at the partnership level. Partnership configuration will override processor settings.

To define the processor level retry count, set the “resend_max_retriesprocessor.resend_max_retries” attributeproperty on the processor element to a valid integer in the OpenAS2 properties to a valid integer value.

Example snippet:

<processor classname="org.openas2.processor.DefaultProcessor"

pendingMDN="%home%/../data/pendingMDN3"

pendingMDNinfo="%home%/../data/pendinginfoMDN3"

processor.resend_max_retries="10" – in the config.xml

processor.resend_max_retries=10 – in the OpenAS2 properties file if used >

To define the partnership level retry count, set an attribute element on the partnership with name attribute value as “resend_max_retries” and a value attribute element to a valid integer.

Example snippet:

<partnership name="MyCompany-to-PartnerA">

<attribute name="resend_max_retries" value="3"/>

<sender name="MyCompany"/>

9.7. Asynchronous MDN Response Wait Time

In the case of asynchronous MDN responses, the application will wait for a fixed amount of time (default is 4560 seconds) for the partner to respond with an asynchronous MDN and then produce a fail message and move the sent file to the error directory as specified in the configuration.

To change the wait time before the application decides the partner will not respond can be done using a property in the openas2config.xml.properties file using the attributeproperty key name name "as2_mdn_response_max_wait_seconds".

For example:

<properties as2_mdn_response_max_wait_seconds=”600” />

9.8. File Name Parsing

The name of the file passed into the OpenAS2 application for sending to a remote partner can be used to provide information to the AS2 handler that can be used to affect various aspects of how the file is handled.

When the file is picked up for processing by the directory poller, it will look for an attribute named “format” on the AS2DirectoryPollingModule component for that directory in the config.xml file. This attribute is used to break the actual file name into multiple parts and the values assigned to the relevant objects defined in the “format” attribute.

This poller attribute is required in the signle poller that extracts the target AS2 ID from the file name. It uses An examplethis format in the config.xml is:

format=”sender.as2_id, receiver.as2_id, attributes.filename"

The above format will set the AS2 sender and receiver ID as well as the name of the file sent in the AS2 message if configured to send a filec name in the payload. It does this by name by tokenizing the name of the file found in the polling directyoryname using delimiters defined in the “delimiter” attribute. The delimiters for tokenizing defaults to “-.” so the actual name of the file as picked up from the file system will be parsed and split into tokens using either a dash (-) or a period (.) and therefore using the above format, the name of the actual file would have to be in the format XXX-YYY-ZZZ or XXX.YYY.ZZZ or any combination of dash or period and then the AS2 sender would be set to XXX, AS2 receiver to YYY and the name of the file as ZZZ. Any extra string tokens will be discarded so for instance a file name of “X-Y-Z.edi” parsed against the format string above would simply discard the “.edi” part of the file name. If you want the file name sent to the remote partner to be Z.edi then the delimiter attribute value would just be “-” OR use the “mergeextratokens“ parameter which would merge all trailing tokens from the file name into the last token specified in the “format” attribute.

The file name can also be configured to be parsed on a per partnership basis if a partner requires a different file name format to be sent or custom headers added to the AS2 message using partnership attributes as defined in section 10.9.2. Dynamic Header Values From File Name.

9.9. Using A Proxy Server

The application uses the java.net.HttpURLConnection class for HTTP communication and as such should automatically use a proxy server if the appropriate system properties are set.

As of version 2.3.0, OpenAS2 also supports proxy server authentication and the setting of the proxy server host, port, username and password via the properties either in the config.xml or in the external openas2.properties file.in the config.xml file. The settings in the config.xml will override any system properties passed in to the Java virtual machine from the command line.

TheThe following properties are supported in the config.xml filecontrol proxy functionality in OpenAS2:

• http.proxyHost

• https.proxyHost

• http.proxyPort

• https.proxyPort

• http.proxyUser

• http.proxyPassword

To bypass the proxy for certain destination hosts you will need to use the relevant system propertiesy.

This is an example of a proxy server configuration using the openas2.properties file for HTTP connections nd is the recommended way to do it:

http.proxyHost=192.168.1.1

http.proxyPort=1099

http.proxyUser=acme

http.proxyPassword=secret

This is an example of a proxy server configuration using OpenAS2 properties for HTTP connectionsdirectly in the config.xml:

<openas2>

<properties

http.proxyHost="192.168.1.1"

http.proxyPort="1099"

http.proxyUser="acme"

http.proxyPassword="secret"

/>

<certificates classname="…

….

….

</openas2>

This article provides the basics on proxy functionality in Java:

https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html https://blogs.oracle.com/wssfc/entry/proxy_server_authentication_in_java

9.10. Health Check For High Availability Deployment

There are 2 ways to implement a health check.

1. Use a specific URI on the existing AS2 receiver HTTP listener – provides a simple HTTP 200 response but does not do any checking of application status

2. Use a dedicated healthcheck module that runs on a separate HTTP port and provides extended checking of the status of the application and its modules.

9.10.1. Healthcheck URI On Exisiting AS2 Listener

This mechanism simply provides validation that the application is listening on the specified socket and does not provide any verification of the health of other components of the application.

The AS2 receiver module can be configured to recognize a specific URI as a health check request instead of a normal AS2 message. By default, the healthcheck URI is set to “/healthcheck”. The full URL would be the combination of host name/ip address and port number with the URI as suffix.

e.g http://localhost:10080/healthcheck

9.10.2. Dedicated Healthcheck Module

As of version 2.4.0, a health check module is included in the OpenAS2 deployment.

This module adds a listener on a specified HTTP or HTTPS port that can be invoked by a load balancer or other application to check if the application is running.

It is invoked by any GET request on the specified host and port irrespective of URI

e.g http://localhost:10080/ or http://localhost:10080/some/random/uri

Currently the module will invoke a health check method for all active modules and returns HTTP 200 OK if there are no errors. It checks all configured listeners that the socket is active and responding as well as relevant health checks for other modules such as the database tracking module, resender modules and directory polling modules.

If errors are detected, it will return HTTP 500 Internal Error with a list of errors detected in the body of the response.

This allows you to configure the load balancer to send an HTTP request to the configured port and will return a 200 OK response.

To enable the module you need to uncomment the definition at the bottom of the config.xml file setting the port as appropriate for your environment. Below is the sample entry in thedefault properties in the config.xml file:

<module classname="org.openas2.processor.receiver.HealthCheckModule" port="10099"/>module.HealthCheckModule.enabled="false"

module.HealthCheckModule.address="localhost"

module.HealthCheckModule.port="10099"

If desired you can bind the healthcheck module to a specific IP address using the “address” attributeproperty:

<module classname="org.openas2.processor.receiver.HealthCheckModule" address="10.0.2.1"/ port="10099"/>module.HealthCheckModule.address="10.0.0.1"

HTTPS transport can be configured as per section SSL Certificates - Configuring HTTPS Transport in this document.

See the appendix for notes on deploying OpenAS2 in a clustered/load balanced environment.

9.10.3. HTTP User Agent Header

By default, the “User-Agent” header sent in the HTTP requests will contain the application title and version along with the module name sending the request. This can be overridden using the property name "http.user.agent” in the openas2.properties file. For example:

<properties

http.user.agent="AS2 1.1 Compliant Server"

log_date_format="yyyy-MM-dd HH:mm:ss.SSS"

sql_timestamp_format="yyyy-MM-dd HH:mm:ss.SSS"

/>

10. Partner Configuration

The file named partnerships.xml configures all the information relating to the partners you will be exchanging data with. See the appendix for information on the structure of this file.

The “partnerships” element in the application configuration file (described in section Application Configuration above) causes the partnerships to be loaded by the application. The default entry in the application configuration file for this element is as below:

<partnerships classname="org.openas2.partner.XMLPartnershipFactory"

filename="%home%/partnerships.xml"

interval="120"/>

The “interval” attribute specifies the number of seconds between each check for a changed partnership file. If a change of the partnership file is detected, the partnership file will be automatically reloaded.

It is important to keep in mind that the word partner refers to any entity specified as a recipient or sender of AS2 messages and includes your own company that you might be configuring the application for.

Each partner will require the following entries in the file:

• a <partner> element – key information defining the partner

• a <partnership> element - key information for defining a partnership between 2 partners
  Separate <partnership> elements are required for inbound and outbound data for a specific partner pairing.

10.1. Partner Definition

The <partner> element requires 3 attributes to enable AS2 partner identification:

1. name – the partner “name” as an identifier string – this is the key to connect partnerships to a partner definition

2. as2_id – the AS2 identifier that uniquely identifies the partner in the AS2 protocol – this is the key for identifying the target/source partner and is included in AS2 message headers to allow the receiving partner to identify the source of the message and verify the target partner for the AS2 message. It is also used by the general directory polling module to look up the partner names and hence the partnership definition where the as2_id of the sender and receiver are part of the transferred file name.

3. x509_alias – the X.509 certificate alias. It identifies the alias of the certificates for this partner in the keystore. The encryption and decryption of messages requires the partners public or private key as appropriate.
   Note: You can verify these codes with the server using the 'cert list' command. The certificate names listed MUST match the X.509 certificate alias in partnerships.xml

10.2. Partnership Definition

The <partnership> element identifies a specific direction of AS2 message transfer from one partner to another. The “name” attribute on the <partnership> element is not important but should be used to clearly identify the intended use of the partnership definition. It is suggested the name value uses the names of the source and destination partners something like xxx-to-yyy.

The <partnership> element encapsulates a number of child elements that are necessary to properly configure a partnership:

• <sender name=”xxx”> - identifies the sending partner definition such that xxx must match the “name” attribute of a <partner> element

• <receiver name=”yyy”> - identifies the receiving partner definition such that yyy must match the “name” attribute of a <partner> element

• <as2_url> - a fully qualified URI that provides the connection string to the remote partner for sending AS2 messages. If sending to another OpenAS2 server then the port number must match the value configured in the config.xml file of the remote OpenAS2 server.
  NOTE: This attribute supports } and can be used to target modify the URL dynamically. See the section Dynamic AS2 Url Configuration for more information.

• <as2_mdn_to> - neccesary if an MDN response is required and can be any random string but is most commonly configured with an email address

The partnership element attribute values supports using a key value string that can be used to reference other attributes within the same partnership element to ensure consistent configuration. The value field in an attribute can use the format $attribute.XXX$ to reference the value of the attribute name “XXX”. The value in the attribute value containing the reference to another attribute will be replaced at load time with the referenced attributes value.

For instance you can have :

<attribute name="some_attrib_name" value="My value: $attribute.other_attrib"/>

<attribute name="other_attrib" value="bingo"/>

The value for "some_attrib_name" will be "My value: bingo" after the application starts up.

For an implemented example see the MDN MIC Algorithm section below.

NOTE: This feature does cascade the replacement. ie it will NOT replace values in attribute values that themselves contain references to other attributes. It may appear to cascade depending on the order in which attributes are processed but the processing order is not guaranteed so will not produce a reliable result

10.2.1. Signing

Signing is controlled by the “sign” attribute in the “partnership” element. Remove this element from the partnership to send a message without signing.

Supported signing algorithms are: md2, md5, sha-1, sha-224, sha-256, sha-384, sha-512

The above algorithm identifier strings are RFC5751 standard. If your partner uses a signing algorithm that is in the form “sha256”, “sha2_256”, “sha2-256”, “sha1”, “sha2-384” etc. and they cannot use the standard algorithm identifier, you must set your partnership “sign” attribute to match theirs. OpenAS2 will automatically attempt to convert the algorithm identifier to the RFC5751 standard.

10.2.2. Encryption

Encryption is controlled by the “encrypt” attribute in the “partnership” element. Remove this element from the partnership to send a message without encryption.

Supported algorithms are: 3des, cast5, rc2_cbc, aes128, aes192, aes256

10.2.3. MDN MIC Algorithm

The MDN must be signed using the same algorithm that the sent message was signed with. The recipient partner is told the signature algorithm via a field in the “as2_mdn_options” attribute and the value uses the $attribute.sign$ dynamic variable to ensure it matches the “sign” attribute as shown in the example below:

<attribute name="as2_mdn_options"

value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, $attribute.sign$"/>

If you receive errors something like “mismatched Message Digest” or similar messages then ensure you have this attribute set correctly.

If you need to send an unsigned MDN then set the attribute on the partnership as below:

<attribute name="as2_mdn_options" value="none"/>

10.2.4. Reject Unsigned Messages

The AS2 protocol allows messages to be sent unsigned but this can be a security risk. OpenAS2 supports being able to reject any messages that are sent unsigned by setting an attribute on the partnership or for global applicability, as a parameter.

The default setting is to enforce signing of messages. To remove enforcement for a specific partner, add the following to the partnership that is defined for receiving files from your partner:

<attribute name="reject_unsigned_messages" value="false"/>

To allow unsigned messages globally set the property in the openas2.properties files to false:

reject_unsigned_messages="false"

You can then override the global setting in the partnership with a value of “true” if needs be on a per partnership basis.

10.2.5. Dynamic AS2 Url Configuration

The target URL for sending messages to your partner (the “as2_url” attribute in the partnership element) can be dynamically set using message attributes set from dynamic variables. Typically this can be used to change the URI part of the URL (ie the part after the host name) but can be used to set the entire URL if desired. The names of the dynamic variables can be any alphanumeric that makes sense to you.

There are 3 ways to set message attributes that can be used in the for dynamic URL’s:

1. Parsed from the file name that is passed into OpenAS2 for sending (see the section File Name Parsing for more details on how this is done). This is typically used for a generic directory polling module.

2. Explicitly set in the directory polling modules “defaults” attribute. Using this mechanism you would need different directories (ie multiple DirectoryPollingModule instances) per URL you want to use.

3. A combination of the 2 methods above.

For example assume there is a partnership with the “as2_url” parameter as follows:

<partnership name="MyCompany-to-PartnerA">

<sender name="MyCompany"/>

<receiver name="PartnerA"/>

<attribute name="protocol" value="as2"/>

...

...

<attribute name="as2_url" value="http://as2.company.com/AS2Routing/$msg.attributes.as2_url_suffix$"/>

...

...

<attribute name="as2_mdn_to" value="edi@myCompany.com"/>

</partnership>

If you are using a generic polling module and want to use the file name as the source for replacing $msg.attributes.as2_url_suffix$ then use a DirectoryPollingModule as below:

<module classname="org.openas2.processor.receiver.AS2DirectoryPollingModule"

outboxdir="$properties.storageBaseDir$/toAny"

errordir="$properties.storageBaseDir$/toAny/error"

interval="5"

delimiters="-"

mergeextratokens="true"

sendfilename="true"

format="sender.as2_id, receiver.as2_id, attributes.as2_url_suffix, attributes.filename"

mimetype="application/EDI-X12" />

Any file in the format <YourCompanyAS2_ID>-<YourPartnerAS2_ID>-<SomeUrlSuffix>-<SomeFilenameToSend> would replace the $msg.attributes.as2_url_suffix$ with the text extracted matching <SomeUrlSuffix>. For instance, a file name of “MyCompany_OID-PartnerA_OID-Shipping-222222-invoice.msg” would send a message from “MyCompany_OID” partner to “ PartnerA_OID” partner using URL http://as2.company.com/AS2Routing/Shipping with file name “ 222222-invoice.msg”.

If you use a dedicated DirectoryPollingModule as the source for replacing $msg.attributes.as2_url_suffix$ then use a DirectoryPollingModule configured as shown below:

<module classname="org.openas2.processor.receiver.AS2DirectoryPollingModule"

outboxdir="$properties.storageBaseDir$/toPartnerA"

errordir="$properties.storageBaseDir$/toPartnerA/error"

interval="5"

defaults="sender.as2_id=MyCompany_OID, receiver.as2_id=PartnerB_OID, attributes.as2_url_suffix=Invoicing"

sendfilename="true"

mimetype="application/EDI-X12" />

Any file picked up by this polling module would replace the $msg.attributes.as2_url_suffix$ in the “as2_url” attribute with “Invoicing”. For instance, a file name of “AST-222222.msg” would send a message from “MyCompany_OID” partner to “ PartnerA_OID” partner using URL http://as2.company.com/AS2Routing/Invoicing with file name “ AST-222222-invoice.msg”.

It is also possible to use 2 sources for building the URL. Given a “as2_url” attribute set as shown below:

<attribute name="as2_url" value="http://as2.company.com/$msg.attributes.as2_url_base$/$msg.attributes.as2_url_suffix$"/>

Set up a dedicated DirectoryPollingModule as shown below:

<module classname="org.openas2.processor.receiver.AS2DirectoryPollingModule"

outboxdir="$properties.storageBaseDir$/toPartnerA"

errordir="$properties.storageBaseDir$/toPartnerA/error"

interval="5"

defaults="sender.as2_id=MyCompany_OID, receiver.as2_id=PartnerB_OID, attributes.as2_url_base=Shipping/"

sendfilename="true"

delimiters="-"

mergeextratokens="true"

sendfilename="true"

format="attributes.as2_url_suffix, attributes.filename"

mimetype="application/EDI-X12" />

A file name of “AST-222222.msg” would send a message from “MyCompany_OID” partner to “ PartnerA_OID” partner using URL http://as2.company.com/Shipping/AST with file name “ 222222-invoice.msg”.

10.2.6. Allow Expired Partner Certificates For Signature Verification

By default, the system will not allow signature verification with an expired partner certificate.

To allow the use of expired parner certificates for signature verification, set the property in the openas2.properties file (or the properties section of the config.xml file) to false:

as2_sign_allow_expired_certificate="true"

10.3. Example Multi-Partner Configuration

The default partnerships.xml shows a configuration for your own entry and one partner.

The below shows a configuration for your own company configuration and 2 partners. The MyCompany-to-PartnerA partnership uses Synchronous MDN whilst the MyCompany-to-PartnerB partnership uses Asynchronous MDN.

<partnerships>

<partner name="MyCompany"

as2_id="MyCompany_OID"

x509_alias="mycompany"

email="as2msgs@openas2.com"/>

<partner name="PartnerA"

as2_id="PartnerA_OID"

x509_alias="partnera"

email="as2msgs@partnera.com"/>

<partner name="PartnerB"

as2_id="PartnerB_OID"

x509_alias="partnerb"

email="as2msgs@partnerb.com"/>

<partnership name="MyCompany-to-PartnerA">

<sender name="MyCompany"/>

<receiver name="PartnerA"/>

<attribute name="protocol" value="as2"/>

<attribute name="content_transfer_encoding" value="binary"/>

<attribute name="compression_type" value="ZLIB"/>

<attribute name="subject" value="File $attributes.filename$ sent from $sender.name$ to $receiver.name$"/>

<attribute name="as2_url" value="http://as2.partnera.com:4080"/>

<attribute name="as2_mdn_to" value="edi@myCompany.com"/>

<attribute name="as2_mdn_options"

value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, $attribute.sign$"/>

<attribute name="encrypt" value="3DES"/>

<attribute name="sign" value="SHA-256"/>

<attribute name="resend_max_retries" value="3"/>

<attribute name="prevent_canonicalization_for_mic" value="false"/>

<attribute name="rename_digest_to_old_name" value="false"/>

<attribute name="remove_cms_algorithm_protection_attrib" value="false"/>

</partnership>

<partnership name="PartnerA-to-MyCompany">

<sender name="PartnerA"/>

<receiver name="MyCompany"/>

<attribute name="protocol" value="as2"/>

<attribute name="content_transfer_encoding" value="binary"/>

<attribute name="compression_type" value="ZLIB"/>

<attribute name="subject" value="File $attributes.filename$ sent from $sender.name$ to $receiver.name$"/>

<attribute name="as2_url" value="http://localhost:10080"/>

<attribute name="as2_mdn_to" value="edi@parnera.com"/>

<attribute name="as2_mdn_options"

value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, $attribute.sign$"/>

<attribute name="encrypt" value="3DES"/>

<attribute name="sign" value="SHA256"/>

<attribute name="resend_max_retries" value="3"/>

<attribute name="prevent_canonicalization_for_mic" value="false"/>

<attribute name="rename_digest_to_old_name" value="false"/>

<attribute name="remove_cms_algorithm_protection_attrib" value="false"/>

</partnership>

<partnership name="MyCompany-to-PartnerB">

<sender name="MyCompany"/>

<receiver name="PartnerB"/>

<attribute name="protocol" value="as2"/>

<attribute name="content_transfer_encoding" value="8bit"/>

<attribute name="compression_type" value="ZLIB"/>

<attribute name="subject" value="File $attributes.filename$ sent from $sender.name$ to $receiver.name$"/>

<attribute name="as2_url" value="https://as2.partnerb.com:8443"/>

<attribute name="as2_mdn_to" value="edi@myCompany.org"/>

<attribute name="as2_mdn_options"

value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, $attribute.sign$"/>

<attribute name="as2_receipt_option" value="$properties.as2_async_mdn_url$"/>

<attribute name="encrypt" value="3DES"/>

<attribute name="sign" value="SHA-1"/>

<attribute name="resend_max_retries" value="3"/>

<attribute name="prevent_canonicalization_for_mic" value="false"/>

<attribute name="rename_digest_to_old_name" value="false"/>

<attribute name="remove_cms_algorithm_protection_attrib" value="false"/>

</partnership>

<partnership name="PartnerB-to-MyCompany">

<sender name="PartnerB"/>

<receiver name="MyCompany"/>

<attribute name="protocol" value="as2"/>

<attribute name="content_transfer_encoding" value="8bit"/>

<attribute name="compression_type" value="ZLIB"/>

<attribute name="subject" value="File $attributes.filename$ sent from $sender.name$ to $receiver.name$"/>

<attribute name="as2_url" value="http://localhost:10080"/>

<attribute name="as2_mdn_to" value="edi@partnerb.com"/>

<attribute name="as2_receipt_option" value="https://as2.partnerb.com:8444"/>

<attribute name="as2_mdn_options"

value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, $attribute.sign$"/>

<attribute name="encrypt" value="3DES"/>

<attribute name="sign" value="SHA256"/>

<attribute name="resend_max_retries" value="3"/>

<attribute name="prevent_canonicalization_for_mic" value="false"/>

<attribute name="rename_digest_to_old_name" value="false"/>

<attribute name="remove_cms_algorithm_protection_attrib" value="false"/>

<attribute name="resend_max_retries" value="3"/>

</partnership>

</partnerships>

10.4. Configuring the AS2 Message ID

The message ID used for uniquely identifying the message sent to a partner defaults to the following format:

OPENAS2-$date.ddMMyyyyHHmmssZ$-$rand.UUID$@$msg.sender.as2_id$_$msg.receiver.as2_id$

To change this globally for all partnership definitions, change the property in the config.xml file to the desired format string using the attribute name “as2_message_id_format” in the “properties” element.

<properties

log_date_format="yyyy-MM-dd HH:mm:ss.SSS"

sql_timestamp_format="yyyy-MM-dd HH:mm:ss.SSS"

as2_message_id_format="&lt;OPENAS2-$date.ddMMyyyyHHmmssZ$-$rand.UUID$@$msg.sender.as2_id$_$msg.receiver.as2_id$>"

/>

The message ID that is generated can be overridden on a partnership by partnership basis. To set it for a particular partnership, add an attribute named "as2_message_id_format" to the partnership definition and use any dynamic parameters as specified in the dynamic parameters section of this document.

Something like this:

 <partnership name="MyCompany-to-PartnerA">
        <sender name="MyCompany"/>
        <receiver name="PartnerA"/>
        <attribute name="protocol" value="as2"/>
        <attribute name="content_transfer_encoding" value="binary"/>
        <attribute name="as2_message_id_format" value="ACME-$date.yyyyMMddHHmmssZ$-$rand.UUID$"/>

In some cases, the choice of the Message ID will not be suitable for generating an MDN message Id because the parameter strings will not have a value value such as when the message ID references some parts of the parsed file name and would return a “null” value in the MDN context. In this case you can specify a different format for the MDN message ID that is generated and this can be set at partnership or system level as above.

<properties

log_date_format="yyyy-MM-dd HH:mm:ss.SSS"

sql_timestamp_format="yyyy-MM-dd HH:mm:ss.SSS"

as2_mdn_message_id_format="&lt;OPENAS2-MDN-$rand.UUID$@$msg.sender.as2_id$_$msg.receiver.as2_id$>"

/>

To set it for a particular partnership, add an attribute named "as2_mdn_message_id_format" to the partnership definition and use any dynamic parameters as specified in the dynamic parameters section of this document.

Something like this:

 <partnership name="MyCompany-to-PartnerA">
        <sender name="MyCompany"/>
        <receiver name="PartnerA"/>
        <attribute name="protocol" value="as2"/>
        <attribute name="content_transfer_encoding" value="binary"/>
        <attribute name="as2_mdn_message_id_format" value="ACME-MDN-$date.yyyyMMddHHmmssZ$-$rand.UUID$"/>

10.5. Setting Content Type

10.5.1. Configuration Sources

OpenAS2 provides 6 ways to set the Content-Type header for each sent AS2 message:

1. Set the same default for all partnerships as a system property – set the property named “content_type” to the value you want as the default in your property overrides file
   content_type=application/octet-stream

2. Set the partnership default - set the attribute with name “content_type”.
   An example of specifying an EDIFACT AS2 payload is shown below:
   <attribute name="content_type" value="application/EDIFACT"/>

3. Set the poller default – set the property named “pollerConfigBase.mimetype” in your property overrides file for all pollers:
   pollerConfigBase.mimetype=application/octet-stream

4. Set it in a specific partnership poller by adding “mimetype” as an attribute on the “pollerConfig” element in the partnership. This will override the pollerConfigBase.mimetype setting above for that specific partnership:
   <pollerConfig enabled="true" mimetype="application/edi-x12"/>

5. Retrieve dynamically determined value based on the filename extension of each file being sent for all configured partnerships. The software will extract the filename extension from the file being sent and use that to lookup the Content-Type to use for that payload using a predefined set of mappings. The mapping from filename extension (eg. “xml” in “somefilename.xml”) to Content-Type is set in a properties file. The content_type_mappings.properties file in the config directory that comes with the OpenAS2 install package can be used as an example. To get the system to load the mappings, set the property named “content_type_mapping_file” to the name of the file on the file system you want to use at system level. For example:
   content_type_mapping_file=$properties.config_dir$/content_type_mappings.properties

6. Apply the same functionality as the system level dynamically determined value based on the filename extension described in the previous point but only for a specific partnership instead of system wide. To get the partnership to load the mappings, set the attribute named “content_type_mapping_file” to a value containing the name of the file on the file system you want to use at partnership level. For example:
   <attribute name="content_type_mapping_file" value="$properties.config_dir$/content_type_mappings.properties"/>

Any combination of the above 6 mechanisms is valid but it is important to understand how each property overrides others.

10.5.2. Configuring Dynamic Content-Type Lookup

Enabling the dynamic lookup requires a flag to be set either at system level or at partnership level.

For system level set the property named “use_dynamic_content_type_mapping” to to “true” in your property overrides file. Any other value other than “true” or the lack of this property will disable system level dynamic mapping. For example:
use_dynamic_content_type_mapping=true

For partnership level dynamic lookup set the attribute named “use_dynamic_content_type_mapping” to “true” in your partnership definition. Any other value other than “true” or the lack of this property will disable partnership level dynamic mapping. For example:
<attribute name="use_dynamic_content_type_mapping" value="true"/>