Setup PEPPOL AP

This page explains how to setup an OpenPEPPOL AS2 AccessPoint from scratch. AP is the abbreviation for Access Point which is the technical endpoint for sending and receiving business documents.

There are a few known possibilities (I'm aware of) on how to build/run a PEPPOL AS2 AccessPoint.

  • You can use Oxalis as a prebuild solution. It supports AS2 and AS4 but comes without professional support.
  • You can use Holodeck B2B as a prebuild solution. It supports AS2 and AS4 and comes with commercial support.
  • The solution described in this document is the usage of my as2-lib as the AS2 communication channel and as2-peppol-servlet for receiving AS2 messages within a standard Java servlet. By default no external AS2 software is required for this solution, so I'm presenting a fully self-contained Open Source solution. This solution is also used by the Austrian government to receive e-Invoices via PEPPOL.

Prerequisites

Before you can start you need to have the following information in place:

  1. As the very first step you need to sign the TIAs (Transport Infrastructure Agreements) with OpenPEPPOL AISBL
  2. Afterwards you need to apply for an AP certificate at OpenPEPPOL. This certificate is required to run the AP.
  3. At least one of the default PEPPOL BIS v2 (processes) must be implemented (according to the TIAs). A list of all available BISs is available on the PEPPOL website.
  4. You should have a look at the official PEPPOL AS2 specification.
  5. You should have a look at the official PEPPOL Envelope specification (SBDH).
  6. You should be familiar with Java
  7. Basic knowledge about Apache Tomcat (and optionally a web server) should be present

AS2 Message structure

An AccessPoint is a technical adapter for sending and receiving PEPPOL UBL documents. The following images shows the overall structure of a transmitted AS2 message in a very simplified way:

PEPPOL AS2 message structure

The outermost container is an S/MIME (Secure / Multipurpose Internet Mail Extensions) message. It is a basic MIME message including signature data. One MIME part of the message is the so called Standard Business Document Header (SBDH). It is a UN/CEFACT standard for merging XML documents with relevant metadata into a single XML document. PEPPOL maintains its own Envelope specification that is based on SBDH. Finally inside the SBDH the main UBL business document is contained. The complete UBL 2.1 specifications can be downloaded from the OASIS UBL web site.

Implementation

This section points to projects that help in implementing the different layers of an AS2 message. If you are already familiar with these concepts you may simply skip this section.

  • S/MIME: to read and write S/MIME messages The Legion of the Bouncy Castle provides tools for it. It is licensed under an MIT-like license. The latest version 1.62 is used within as2-lib for S/MIME handling. The relevant Maven artefacts are:
        <dependency>
          <groupId>org.bouncycastle</groupId>
          <artifactId>bcmail-jdk15on</artifactId>
          <version>1.62</version>
        </dependency>
        <dependency>
          <groupId>com.sun.mail</groupId>
          <artifactId>javax.mail</artifactId>
          <version>1.6.2</version>
        </dependency>
  • SBDH: to read an write SBDH messages I created a Java library called ph-sbdh which uses JAXB generated objects. Additionally the Java library peppol-sbdh can be used on top of ph-sbdh as it adds the PEPPOL specific requirements. Both libraries are licensed under the Apache 2.0 license. The relevant Maven artefacts are:
        <dependency>
          <groupId>com.helger</groupId>
          <artifactId>ph-sbdh</artifactId>
          <version>4.1.0</version>
        </dependency>
        <dependency>
          <groupId>com.helger</groupId>
          <artifactId>peppol-sbdh</artifactId>
          <version>7.0.0</version>
        </dependency>
  • UBL 2.1: to read an write UBL messages I created a Java library called ph-ubl which uses JAXB generated objects. This library is licensed under the Apache 2.0 license. The relevant Maven artefacts are:
        <dependency>
          <groupId>com.helger</groupId>
          <artifactId>ph-ubl21</artifactId>
          <version>6.1.2</version>
        </dependency>

AS2 AccessPoint receiver

An example project that shows how to receive PEPPOL documents via AS2 can be found in the as2-peppol-server project. It uses as2-lib, ph-ubl and peppol-sbdh to receive messages from arbitrary PEPPOL AS2 receivers. It requires no external AS2 handler (like Mendelson) and no mandatory database setup. as2-peppol-server is a Java 1.8+ project and licensed under Apache 2.0 license.

Detailed setup description can be found directly on the as2-peppol-server project page.

AS2 AccessPoint sender

An example project that shows how to send PEPPOL documents via AS2 can be found in the as2-peppol-client project. It uses as2-lib, ph-ubl and peppol-sbdh to send messages to arbitrary PEPPOL AS2 receivers. as2-peppol-client is a Java 1.8+ project and licensed under Apache 2.0 license.

The steps to send a document are outlined as follows:

  1. As a prerequisite, you need to know the following things:
    1. The UBL document to be send. How you create your UBL file is out of scope!
    2. The PEPPOL participant ID of the receiver (e.g. 0088:test). The determination of the recipient ID is not in scope for PEPPOL!
    3. Your PEPPOL sender participant ID. There is no fixed way how to determine this. If you are registered as a PEPPOL recipient, than please use your recipient ID as your sender ID. If you are not registered as a sender have a look at the latest PEPPOL policy for use of identifiers as well as the Participant Identifier Scheme code lists and search the VAT scheme suitable for your country (at the end of the list). Assuming you are from San Marino and your VAT number is 123456 than use the following sender ID: 9951:123456.
    4. You need to know the PEPPOL document type identifier and PEPPOL process identifier in which you want to send the document. If you are unsure what document type and process the receiver supports you can use the Participant information tool contained in this page to determine the details.
    5. You need to have a valid PEPPOL AP certificate for sending documents to the PEPPOL network.
  2. Perform an SMP lookup on the recipient ID and the document type ID to retrieve a list of all endpoints and extract the one using the transportProfile busdox-transport-as2-ver1p0 (for AS2; for AS4 it is peppol-transport-as4-v2_0). From this endpoint use EndpointReference as the destination URL and also remember the certificate of the recipient. It is later needed to extract the as2-to ID.
  3. Next thing to do is to create an SBDH document. Using the peppol-sbdh library this can be performed in very few steps:
    1. Create an instance of com.helger.peppol.sbdh.PeppolSBDHDocument which is filled with the UBL document, the sender participant ID, the receiver participant ID, the document type ID and the process ID (all stated in the prerequisites above).
    2. Convert the PeppolSBDHDocument to a StandardBusinessDocument using the PeppolSBDHDocumentWriter utility class.
  4. For setting up the AS2 client request some additional input is needed:
    1. A PKCS12 keystore containing your PEPPOL AP certificate. If you only have a JKS keystore, you can easily convert it to a PKCS12 keystore using the great Portecle tool by exporting the certificate and the public key. You need to enter a password for the newly created keystore upon export.
    2. The password to access the PKCS12 keystore.
    3. Your AS2 ID (as2-from), which must be the common name of your PEPPOL AP certificate subject (e.g. APP_1000000001).
    4. The alias of the certificate in the PKCS12 keystore to be used. Ideally it is equal to your AS2 ID for easy matching but this is just an idea.
    5. The AS2 ID of the receiver (as2-to), which must be the common name of the recipients PEPPOL AP certificate subject (e.g. APP_1000000002) received via the previous SMP lookup.
    6. The public key of the receiver as an X.509 certificate. This is exactly the certificate received from the previous SMP lookup.
  5. Finally the AS2 message can be send synchronously and the MDN can be received synchronously.
You must be logged in to post a comment!