Configuration file

AS2 Configuration file

A special XML configuration file must be used to configure the AS2 handling. It contains:

• a reference to the keystore to be used (in element certificates)
• a reference to a partnership factory (storing the exchange combinations) (in element partnerships)
• a list of modules that are executed when a message is received (in elements module)

Note: Alternatively you can also use a code based configuration. See e.g. https://github.com/phax/phase2/blob/master/phase2-servlet/src/test/java/com/helger/phase2/servlet/example/AS2ReceiveXServletHandlerCodeConfig.java for an example.

See page Architecture for the description of the different modules.

Within a configuration file, the macro %home% is replaced with the parent directory of the configuration file. This replacement happens only when a value starts with %home%.

Complete example configuration file:

<?xml version="1.0" encoding="utf-8"?>
<phase2>
  <!-- [required] The keystore to be used (since v4) -->
  <certificates classname="com.helger.phase2.cert.CertificateFactory"
                type="pkcs12" 
                filename="%home%/server-certs.p12"
                password="mypassword" />

  <!-- [required] The keystore to be used (prior to v4) -->
  <!--
  <certificates classname="com.helger.phase2.cert.PKCS12CertificateFactory" 
                filename="%home%/server-certs.p12"
                password="mypassword" />
  -->                
                
  <!-- [required] The pro-forma partnership factory -->                  
  <partnerships classname="com.helger.phase2.servlet.util.AS2ServletPartnershipFactory"
                filename="%home%/server-partnerships.xml"
                disablebackup="true" />
 
  <!-- [required] the processing queue -->
  <processor classname="com.helger.phase2.processor.DefaultMessageProcessor"
             pendingMDN="%home%/pendingMDN"
             pendingMDNinfo="%home%/pendinginfoMDN">

    <!-- [optional] Store sent MDNs to a file
      Note: "charset" attribute was added in v4.1.0 
    -->
    <module classname="com.helger.phase2.processor.storage.MDNFileModule"
            filename="%home%/mdn/$date.uuuu$/$date.MM$/$mdn.msg.sender.as2_id$-$mdn.msg.receiver.as2_id$-$mdn.msg.headers.message-id$"      
            protocol="as2"
            tempdir="%home%/temp"
            charset="utf-8" />

    <!-- [optional] Store received messages and headers to a file 
      Note: "charset" attribute was added in v4.1.0 
    -->
    <module classname="com.helger.phase2.processor.storage.MessageFileModule"
            filename="%home%/inbox/$date.uuuu$/$date.MM$/$msg.sender.as2_id$-$msg.receiver.as2_id$-$msg.headers.message-id$"
            header="%home%/inbox/msgheaders/$date.uuuu$/$date.MM$/$msg.sender.as2_id$-$msg.receiver.as2_id$-$msg.headers.message-id$"    
            protocol="as2"
            tempdir="%home%/temp"
            charset="utf-8" />

    <!-- [required] The main receiver module that performs the message parsing.
         This module also sends synchronous MDNs back.
         Note: the port attribute is required but can be ignored in our case!
         Note: the 'errordir' attribute allows parameters since v3.0.4 only!
         Note: the 'errorstorebody' attribute was added with v3.0.4! 
    -->
    <module classname="com.helger.phase2.servlet.util.AS2ServletReceiverModule"      
            port="10080"
            errordir="%home%/inbox/error/$date.uuuu$/$date.MM$"
            errorformat="$msg.sender.as2_id$, $msg.receiver.as2_id$, $msg.headers.message-id$"
            errorstorebody="false"/>

    <!-- To process the documents further than just storing them to disk, implement
         class AbstractProcessorModule and register the module here.
         See the phax/as2-peppol-servlet project on how to handle e.g. SBDH documents 
    -->                      
  </processor>
</phase2>

All the elements between $...$ is replaced with actual message content. Each element is split by dots, and is explained below:

• date - date related parameters
  • xxx - contains the Java date time formatter string - see https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html for a detailed explanation
• msg - message related parameters
  • sender - contains sender parameters
    • Example: msg.sender.as2_id - access the parameter as2_id of the message sender
  • receiver - contains receiver parameters
    • Example: msg.receiver.as2_id - access the parameter as2_id of the message receiver
  • attributes - contains internal attributes. Key names are case sensitive.
    • Example: msg.attributes.as2_url - access the attribute as2_url containing the target URL of a message
  • headers - contains HTTP headers. If a header occurs more than once, each value is printed delimited by , . Header names are case-insensitive.
    • Example: msg.headers.host - access the HTTP header host
  • content-disposition.filename - special case that contains the filename attribute from the Content-Disposition header.
• mdn - message MDN related parameters
  • sender - contains sender parameters
    • Example: mdn.sender.as2_id - access the parameter as2_id of the MDN sender
  • receiver - contains receiver parameters
    • Example: mdn.receiver.as2_id - access the parameter as2_id of the MDN receiver
  • attributes - contains internal attributes. Key names are case sensitive.
    • Example: mdn.attributes.DISPOSITION - access the attribute DISPOSITION containing the disposition of an async MDN.
  • headers - contains HTTP headers. If a header occurs more than once, each value is printed delimited by , . Header names are case-insensitive.
    • Example: mdn.headers.host - access the HTTP header host
  • text - contains the MDN payload as a string
    • Example: mdn.text.anything - access the MDN payload. Note the anything value can really be anything but MUST be provided.
  • msg - contains the message related parameter (see above)
    • Example: mdn.msg.sender.as2_id - access the parameter as2_id of the message sender
• rand - random values
  • xxx - create a random number with n digits (where n is the number of x in the value). For a example to create a random number between 00 and 99 use xx whereas for a random number between 00000 and 99999 use xxxxx. Leading zeroes are always kept.