Messenger Installation and Configuration Guide 3.1 InstallConfigGuide.pdf4.4 CHECK IF ADAPTERS ARE RUNNING ... Other JDBC 2.0 enabled databases on request . Installing Ponton X/P 3.1

Messenger

Installation and Configuration Guide

Manual Version 3.1

September 19, 2008

Ponton X/P 3.1 – Installation and Configuration Guide 2

Content

FURTHER INFORMATION AND SUPPORT ....................................................... 4

1 INTRODUCTION .......................................................................................... 5

1.1 ABOUT PONTON X/P ......................................................................................... 5

1.2 ARCHITECTURE OVERVIEW .................................................................................. 6

1.3 SUPPORTED FEATURES ....................................................................................... 7

2 DOWNLOADING PONTON X/P 3.1 ............................................................... 8

2.1 COMPONENTS .................................................................................................. 8

3 INSTALLING PONTON X/P 3.1 .................................................................... 9

3.1 MINIMUM SYSTEM REQUIREMENTS ........................................................................ 9

3.2 INSTALLATION PROCEDURE ............................................................................... 10

3.3 IMPORTING THE CONFIGURATION FROM A PREVIOUS VERSION .................................... 10

3.4 INSTALLING PATCHES ....................................................................................... 11

4 QUICK-STARTING THE SOFTWARE ........................................................... 12

4.1 LOGGING IN .................................................................................................. 12

4.2 STOPPING THE MESSENGER ............................................................................... 14

4.3 BASIC CONFIGURATION .................................................................................... 14

4.4 CHECK IF ADAPTERS ARE RUNNING ...................................................................... 21

4.5 CHECK THE STATUS OF YOUR MESSAGES ............................................................... 23

5 CONFIGURATION OPTIONS ...................................................................... 26

5.1 MESSENGER CONFIGURATION ............................................................................ 26

5.2 LISTENER SETTINGS ........................................................................................ 42

5.3 PARTNER CONFIGURATION ................................................................................ 42

5.4 PARTNER AGREEMENTS .................................................................................... 55

5.5 CA CERTIFICATES ........................................................................................... 64

5.6 HOT FOLDER ADAPTER ..................................................................................... 65

5.7 DISPLAY SCHEMA CONFIGURATION...................................................................... 70

5.8 USER ADMINISTRATION .................................................................................... 71

6 ADVANCED CONFIGURATION ................................................................... 72

6.1 TIME SERVER CONFIGURATION .......................................................................... 72

6.2 XML SCHEMA CONFIGURATION .......................................................................... 73

6.3 PROCESSING X12 DOCUMENTS .......................................................................... 75

6.4 PROCESSING EDIFACT DOCUMENTS ................................................................... 75

6.5 ADVANCED DATABASE CONFIGURATION ................................................................ 76

6.6 ADVANCED MESSAGE MONITOR CONFIGURATION .................................................... 76


6.7 AGREEMENT CONFIGURATION FOR PLAIN PACKAGER ................................................ 78

6.8 LISTENER CONFIGURATION ............................................................................... 80

6.9 ACCESS TO THE ADMINISTRATION TOOL ............................................................... 92

6.10 CONTENT RULES ........................................................................................... 92

6.11 PORT CONFIGURATION ................................................................................... 94

6.12 MESSENGER CLUSTER .................................................................................... 96

6.13 SSO CONFIGURATION .................................................................................... 97


Further Information and Support

Technical Support/Helpdesk

E-mail [email protected]

Phone +49.40.69213-344

Ponton Consulting

www.ponton-consulting.de

[email protected]

XML Information Pages

www.w3.org (World Wide Web Consortium)

www.oasis-open.org (OASIS standards organization)

www.ebxml.org (all about ebXML)

www.xml.org (XML industry portal)

xml.coverpages.org (XML Cover Pages)

www.xmlsoftware.com (software products for XML processing)

mailto:[email protected]

http://www.ponton-consulting.de/


http://www.w3.org/

http://www.oasis-open.org/

http://www.ebxml.org/

http://www.xml.org/

http://xml.coverpages.org/

http://www.xmlsoftware.com/


1 Introduction

1.1 About Ponton X/P

Ponton X/P is the ebXML, AS1, AS2 and AS3 compliant Message Service developed by Ponton Consulting. It ensures encrypted, signed, compressed, validated, archived, and guaranteed transfer of XML documents between business partners.

Ponton X/P is packaged with an embedded HSQL database and web server, so that the installation process only requires a few configuration steps.

The Message Service also includes use of the Ponton Certificate Authority, which is integrated into the Messenger network. Business partners may thus kick-start their integration within minutes. If users of Ponton X/P prefer migration to third-party certificate authorities such as VeriSign®, Thawte®, or GlobalSign® this can easily be done just by requesting and installing the corresponding certificate.

Moreover, Ponton X/P allows for flexible back-end integration based on a large range of adapters from Ponton Consulting or third parties.

The Ponton X Series

Apart from Ponton X/P, the X Series comprises two other tools:

Ponton X/E is the form-based XML Editor to easily create papiNet documents or any other document that is based on XML Schema. Find more information on Ponton X/E at http://www.ponton-consulting.de/english/xe.html.

Ponton X/D is a database adapter that is used for direct export/import of documents to and from application data. It is being used both with standard ERP systems like SAP R/3 or J.D. Edwards and with home-grown application software. Find more information at http://www.ponton-consulting.de/english/xd.html.

http://www.ponton-consulting.de/english/xe.html

http://www.ponton-consulting.de/english/xe.html

http://www.ponton-consulting.de/english/xd.html

http://www.ponton-consulting.de/english/xd.html

Introduction


1.2 Architecture Overview

Ponton X/P consists of the following main modules:

1. Messenger – This is the core of Ponton X/P. It transforms messages received from the back-end (for example an ERP system) into a standard-compliant ebXML messages. Several processing steps are performed before the ebXML message is sent to the receiver.

2. Listener – This (optional) module is usually located in the DMZ to receive message from remote systems and forward them to the Messenger within the secure zone of an organization. No further processing is carried out by the Listener. A distributed installation, with the Listener installed separately from the Messenger, is not necessary if the Messenger is in the DMZ or if it is used for internal integration.

3. Adapters – There are many ways to integrate the Messenger with the application software in the back-end. An adapter helps bridge this gap. There are different adapters available for use with Ponton X/P: Ponton X/D is a Database Adapter that maps XML payload content directly to and from a database. The Hot Folder Adapter scans outbox folders and transfers documents to the Messenger. Vice-versa, messages received from a business partner are dropped into an inbox folder.

DB

ERPSystem

Ponton

Ponton

Ponton

X/P

User

ApplicationBusine

ss

Partne

r

Ponton X Series

X/E

X/DXML

Document

Messenger

Listener

Listener

ebXML Message

ebXML Acknowledgement

Gen

eri

cA

dap

ter

Gen

eri

cA

dap

ter

Te

st

Ada

pte

rH

ot

Fo

lde

rA

da

pte

r

ERP

Gen

eric

Ad

ap

ter

Gen

eric

Ad

ap

ter

Te

st

Ada

pte

rH

ot F

old

er

Ada

pte

r ERP

Messenger

Introduction


1.3 Supported Features

Features Features (Cont.)

Base Features

EbXML 2.0 Support

Security Features

End-to-End encryption

AS1, AS2 and AS3 Support End-to-End persistent signatures

Reliable document delivery Channel encryption

Database & file log Channel authentication

Audit trail information SMIME support

Max. payload document size unlimited Document transfer by E-Mail,

HTTP(S) and FTP(S)

>92% Document Compression Embedded request & installation

of X.509 certificates

Support of Win2000, Win2003

Server, Win XP, Vista, Solaris,

HP/UX, AIX, Linux

Access to Ponton certification

authority

Archiving of doc., signature, etc. 1-click signature verification

Other Features

Fine-grained definition of allowed

XML Schemas per Agreement

Turnaround time with encryption

& signing in both directions for

50 KB payload within LAN

Same across Internet:

Turnaround of 90% of transfers

Performance (Messages per min.)

Perform. (4 Clustered Messengers)

Scheduling of maintenance times

0,5 Sec

< 4 Sec.

>=150

>=600

Admin/user notification by email

Web-based configuration

& monitoring

SOAP and Web-Service Interface

Localizability

Included Localizations en,de,fr,ru,pt

1:1 definition of communication

settings and XML Schema sets

Programming interface

for software integration

Online Registry for Profile

Exchange


2 Downloading Ponton X/P 3.1

The software can be downloaded from the product page of Ponton Consulting:

http://www.ponton-consulting.de/en/products/downloads.html

Please fill in the download request form. You will receive an e-mail containing a hotlink for access to the installation file.

2.1 Components

You will find the following components in the installation package:

Ponton X/P Messenger – the core component for guaranteed, secure delivery of XML messages

Ponton X/P Hot Folder Adapter – allows easy connection of the Messenger to your application software

HTTP Adapter – allows HTTP-based back-end integration with your ERP system(s).

Listener – a lightweight process to receive XML documents via HTTP or FTP and forward them to your Messenger over the firewall.

E-mail Listener – another lightweight process that polls your mail server for new messages.

http://www.ponton-consulting.de/english/xp/downloads.php


3 Installing Ponton X/P 3.1

3.1 Minimum system requirements

Hardware

Disk space 100 MB

Memory space 256 MB

Processor Pentium III, 500 MHz

Depending on the number of XML schema files and the corresponding XSL stylesheets that are pre-loaded by your Messenger, you should increase your main memory as follows:

5-8 schemas: 512 MB

8-20 schemas: 1024 MB

This avoids unnecessary swapping overhead.

Operating systems

Windows 2000, Service Pack 2 (Workstation or Server)

Windows X/P Professional, Service Pack 2

Windows Server 2003

Windows Vista Business or Ultimate (32/64 Bit)

Linux, Solaris, AIX, HP-UX

In general, any platform supporting Java Runtime Environment 1.5.

Databases

Oracle (version 8.1.5 or compatible)

MS SQL Server 2000 or 2005

DB2 (version 5.0 or compatible)

MySQL (version 4.0 or higher)

Sybase (version 12 or higher)

Other JDBC 2.0 enabled databases on request

Installing Ponton X/P 3.1


3.2 Installation procedure

The software is installed using a self-extracting executable, which guides the user through the installation process. If only standard options are chosen, the whole installation should not take more than 10 minutes.

Note: Under certain circumstances the installer may run into conflicts with other software running on the same computer. In this case, you should exit all other applications and then restart the installation.

Start the installation by double-clicking the Ponton X/P 3.1 setup file, and go through the installation screens as follows:

Welcome: A short introduction to the installation process. Click on Next to continue.

License Agreement: This screen contains the license terms for use of Ponton X/P. To continue the installation, you have to agree to the license terms by clicking on I Agree.

Choose Components: Select the components you want to install. If you are sure you won’t need certain components, such as the Stress Adapter or the XML Editor, you can exclude them from the installation to save disk space. Simply deactivate the relevant check boxes. Click on Next to continue.

Choose Install Location: Select the installation root folder either by typing it in, or by clicking on Browse and navigating to the folder you want to use. Click on Next to continue.

For the purposes of this documentation let’s assume that you have installed Ponton X/P in C:\Ponton XP 3.1 (or in a UNIX environment in /pontonxp3). This folder will be referred to as the installation root.

Choose Start Menu Folder: Specify a folder in the Start Menu in which you want to install the program shortcuts. Click on Next to continue.

Installing: Shows a progress bar to indicate how far the actual installation has proceeded

Installation Complete: The installation is now complete. After clicking on Next and Finish you can proceed with the configuration of the software.

3.3 Importing the configuration from a previous version

It is possible to import the main configuration items from old Messengers of the version 2.1, 2.3 and 2.4 after installing the new 3.1 version.

You need a copy of the complete old installation (i.e. the X/P folder) on the same machine on which you run the new 3.1 messenger.

Execute the installation procedure as described above and open the import configuration page. Enter the path to the old Ponton X/P installation folder including the folder itself. Following configuration items can be imported:

Installing Ponton X/P 3.1


Messenger Configuration. This includes the settings for: - Communication

- eMail

- Time Servers

- Archive

SSL Certificate

Partners

Agreements In case you import a 2.1 Messenger configuration, a new agreement is created for each combination of a local and a remote partner, if you check this option.

Database This option will transfer all entries from the database of your old messenger into the database that is defined in the configuration of the 3.1 messenger. Therefore, you should configure your new database before doing the import.

3.4 Installing patches

The Messenger is automatically checking for availability of patches on the Ponton server. This is done on startup and after that every 24 hours. If a patch is available, you will notice a download button on the status page. By clicking this download button, the latest available patch will be downloaded to the system. This patch is automatically installed during next restart of the Messenger.


4 Quick-Starting the Software

You can start the Messenger either via the Windows Start menu, or by executing startup.bat in the installation root directory. If you have not started the Messenger from a command shell, but via the Windows interface, this will open an output window.

Please wait until the web server has fully initialized all the software components. When the initialization is finished, the following text should be shown near the bottom of the output window:

***********************************************

Messenger 3.1 is initialized

(c) Ponton Consulting GmbH

Please log in to the Admin tool at <Messenger URL>

***********************************************

If any errors occur during startup, this will be indicated in the output window and logged in the file

[installation root]\xmlpipe\log\messenger-DATE.log

4.1 Logging in

Now the Messenger is ready for use: open your web browser and enter the URL:

http://<hostname>:8080/pontonxp

or

http://localhost:8080/pontonxp, if the Messenger is running on the local machine.

This will bring up the login screen, allowing you to log in to the Ponton X/P Administration Tool.

http://localhost:8080/pontonxp

Quick-Starting the Software


The initial user name and password are:

User: xpadmin

Password: xppass

Important: Since these initial user login settings are the same on every installation, you are advised to change the password as soon as possible to prevent unauthorized access to the Administration Tool.

On startup, the Messenger status screen is displayed, showing information on the current server configuration and the status of different Messenger processes (Threads). You can switch to this screen at any time by choosing Messenger Status from the menu.



Using the Menu/Navigation Panel

Click on the folder icons in the menu panel to open and close the folders. Click on the page labels to display the corresponding screens.

4.2 Stopping the Messenger

If you started the software from the start menu (or if it was installed as a Windows service), you can stop the Messenger by selecting Stop Ponton XP from the start menu. Alternatively, you can execute the batch file shutdown.bat (located in the installation root directory).

If you started the Messenger from a command shell, you may also press CTRL-C to stop the process.

4.3 Basic configuration

The basic functionality of Ponton X/P is to enable the secure exchange of messages between business partners. This entails setting up at least two partner configurations:

a local partner (representing your own organization)

a remote partner (representing your business partner’s organization)

Of course, for your actual daily business you will generally exchange messages with a number of different business partners, so you will need to define different remote partner configurations.

If you want to set up an initial test installation, it is often easier to install two Messengers on separate PCs within your local environment to avoid firewall restrictions. On the other hand, if you want to immediately test with a remote partner, please ensure with your technical administration staff that your firewall is configured to allow the necessary connections.

The following steps describe a basic configuration for test purposes.

Define a local partner

Create a local partner

Open the Configuration menu in the left frame, and then click on Partners Create/Delete Partners.

On the Create/Delete Partners screen, enter a Local ID for yourself, and activate the local radio button in order to create a local partner. Then click Create New Partner.



The next step is to specify the configuration details for this new partner. When you create a new partner, the Local Partner Configuration screen is displayed with the new partner name selected. You can call up a partner configuration afterwards by going to Configuration Partners Local Partners and selecting a partner name from the

drop down menu at the top of the page. There are different tabs for the various configuration settings: Identification, Communication, Schema Sets, etc.

Identification settings

On the Identification tab, you can edit the different IDs used to refer to the given partner (in this case your new local partner):

Partner Display Name – the Display Name is used within Ponton X/P in menus, selection lists, etc.

Internal Partner ID – the Internal Partner ID is used for communication with the backend (ERP) system.

PartyID – the PartyID is used for the identification of business partners in the messaging process. Please note that the different partners have to use correct PartyIDs in their partner configurations to identify the relevant partners. For further details see the Define remote partners section below.

Note: By default, the Partner Display Name, the Internal Partner ID and the PartyID are all preset to the same value as the Local ID used when a new partner is created. On the Identification tab you can modify these settings as required.

The default PartyID Type is PontonCertificate (issued by the Ponton Certificate Authority). Other Party ID types can also be used, for example EIC, Duns Number, GLN (Global Location Number) or URI. For a single partner you can create multiple Party IDs by using different Party ID types.



Click Save to confirm your settings for this new partner.

Note: After making any changes in your configuration settings, remember to click the Save button before you move on. If you switch to a different page or tab without saving the new settings, your modifications will be lost.

Communication settings

On the Communication tab, enter the communication settings for your new partner configuration. Please specify the access details for the communication protocols you want to support: HTTP(S), SMTP, SMIME and FTP(S).

URI of Messenger Service – when entering the URI for HTTP(S) or FTP(S), please be sure to include the port. A complete setting looks like this:

your.server.com:8080/pontonxp/SoapListener

Other settings

On the Schema Sets tab, indicate which schema sets you want to support.

Certificates

Ponton X/P enables you to send signed and/or encrypted messages based on the use of certificates. The installation of a certificate is not required, however, and you may want to skip this step for your initial tests. In this case, please take note of the restrictions described below under Basic testing without certificates.



In any case, your configuration for actual business purposes should include the installation of certificates for your local and remote partners.

Requesting and installing a certificate

Ponton offers a lightweight certificate authority (CA) that allows you to easily request and install certificates for the Messenger. The Certificate tab has subordinate tabs for requesting, installing and subsequently exporting a certificate (for a local partner). To request a certificate from the Ponton CA, click on the Request tab and fill in the certificate request form.

If you activate the Send request to CA check box your request will be sent directly to the CA (using the configured E-Mail connection). Otherwise, you will see a page with a text box containing the certificate request. This page includes an e-mail link that can be used to submit the certificate request to the Ponton CA.

For further details on working with certificates see the Partner Certificates section (beginning on page 49).

Basic testing without certificates

If you decide to run your initial tests without installing certificates for your partner configurations, please note that the following settings have to be modified to compensate for the absence of a certificate.

For your local partner configuration:

Configuration Partners <local partner> Processing



Deactivate the Signing and Encryption options

Configuration Partners <local partner> Packaging

Deactivate the Use XML Signature option

For each of your remote partner configurations (see below):

Configuration Partners <remote partner> Processing

Deactivate the Signing and Encryption options

Configuration Partners <remote partner> Packaging

Deactivate the Use XML Signature option

Activate the software (trial version)

You can run Ponton X/P as a trial version for 60 days. To activate the trial version go to Configuration Messenger Activation/License and click on the Activation

Request tab - or simply click the Create Activation Request link shown on the startup screen (Messenger Status). This will call up the Activation Request tab with a box containing your activation request.

For the trial version, please click on the e-mail link at the top of the page. This will copy the activation request to your e-mail client. Using your e-mail client, please send the activation request to [email protected].

Note: The Send Activation Request by HTTP option is only available when activating a license and is therefore disabled in the trial version.

You will receive a reply e-mail containing the activation code for your system. Please copy the complete activation code and paste it into the text box on the Install tab:




Notes

When sending your activation request by e-mail, it is important to copy the complete activation request code, including the lines “----- Begin Activation Request -----” and “----- End Activation Request -----”. This is also the case when copying the activation code from the reply e-mail into the Install tab. Again, please be sure to include the “Begin” and “End” lines.

After installing a license key you may have to repeat the activation process to activate your license (depending on certain license conditions).

Define remote partners

To test your Messenger configuration, Ponton Consulting offers a test server called xptest.ponton-consulting.de. This server is pre-configured in your Messenger set-up.

Before integrating with your business partners, you can start out using this test server as your messaging partner to experiment with different functions and configuration options, etc.

Please note, however, that your new Messenger configuration is not known to the Ponton test server. For this reason, you only have limited options available for exchanging messages with the Ponton test server – in particular, you can send messages to the test server, but the replies will generally indicate that the sender was “unknown”.

If your tests with the xptest server are successful, you can go ahead and create external partner settings for your business partners. The procedure is the same as with a local partner with a few minor exceptions. The main difference is that you have to have your partners inform you about the

http://xptest.ponton-consulting.de:8080/



settings used in their respective Messenger installations and also have them send you their certificates for installation in your respective partner configurations.

Hint! To check if your partner’s Messenger is up and running, open your browser and go to the URL:

http://<your.partners.domainname>:<port-number>/papinet/SoapListener

The URL for the test server at Ponton Consulting is:

http://xptest.ponton-consulting.de/pontonxp/SoapListener

Note: When exchanging partner configurations with your business partners please keep in mind that identical party IDs have to be used in the local and remote configurations. The partner display names and internal IDs, on the other hand, may be different.

ABC’s local partner config.

ABC’s external

partner config.

XYZ’s local

partner config.

XYZ’s external

partner config.

Partner display name ABC Local XYZ Global XYZ Local ABC Corp

Internal partner ID ABC015 (ERP ID) XYZ381 (ERP ID) 401690 (DB ID) 494230 (DB ID)

Party ID ABC12201 XYZ2950A XYZ2950A ABC12201

Set up a partner agreement

The partner configuration settings specify the options supported by each partner. Agreements, on the other hand, determine the actual settings to be used for communication and processing between two specific partners.

For test purposes it may be helpful to switch off encryption and signing in your partner agreement (on the Processing tab). In any case, please ensure that the settings are compatible for both partners – otherwise you may experience errors in the transfer or processing of messages between the two partners.

http://xptest.ponton-consulting.de/pontonxp/SoapListener



For further details on partner agreements see the Partner Agreements section.

4.4 Check if adapters are running

To check whether your adapters are running, go to Adapter Monitor in the main menu. If no built-in adapter was used before (Test Adapter or Hot Folder Adapter) and no external adapter has connected to the Messenger, the Adapter Monitor will indicate: “No adapter info available…”

Now start the Test Adapter, and go back to the Adapter Monitor. It should indicate: “Test Adapter ready to receive messages…”



Call up the Test Adapter from the main menu of Ponton X/P:



Send a Ping-Message to your partner

To check whether the Messenger configurations (on both your own system and your remote partner’s system) are set up correctly, you can begin by sending a Ping message:

1. Select a sending partner (your local partner)

2. Select a receiving partner (one of the defined remote partners)

3. Click the Ping button to test whether communication with the selected partner is possible.

If your connection to the remote partner is successful, you should see Remote reply: Pong Message in the Status column of the ping message. If not, you will see an error message in the Status column.

For further details on the status of your messages, check the Message Monitor as described in the Message Monitor section below.

As an alternative you can also click the PingAll button, which will open a new browser window where the Status of all configured Partners is displayed. Since there are very different response times depending on the partners, you will not immediately see the final Status for all partners. Therefore the window will automatically refresh every couple of seconds to display the current Status updates.

If you accidentally close the window, you can click the PingAll button again to redisplay the currently running Status request. It is not possible to start a new PingAll process unless all final Status responses were received.

Send your partner a test message

As your next step, please send a test message to your remote partner:

1. Select a document (from the File on server list or by choosing a Local file)

2. For test purposes, activate the Test Message checkbox

3. Send the document by clicking Send Message

Your Test Adapter then forwards the document to your Messenger. The document is processed by the Messenger according to the settings and filters defined in the relevant partner agreement. Finally the document is sent to the specified receiver party’s Messenger (or Listener) address.

4.5 Check the status of your messages

The status of messages can be monitored in the Message Monitor window, which you can select from the main menu of Ponton X/P. This is where you can check whether your messages have been properly transferred to the receiver. The status of your messages is shown in the Result column (located in the message overview in the upper right panel).



Note: In the Message Monitor, please be sure to click the Search button (located below the filter settings on the left), otherwise the list of messages on the right will be empty. If you want to include Ping messages, Acknowledgements and other non-business documents in the list, please set the Type to All documents (instead of All business documents).

The following color codes are used to indicate the transfer/processing status:

Green checkmark – the transfer was successful.

Red cross – something went wrong (in this case, the complete entry is highlighted red).

Question mark – the message is still unconfirmed (in this case, the entry is highlighted yellow).

To check for details, click on the MessageID and look at the log information (in the lower right panel). Each processing step carried out by your Messenger is displayed here. As long as no errors occurred, the log entries are highlighted green.

The left-hand columns show

How the message was transferred from your test adapter to the Messenger

Which Messenger filters were applied to the message

How the document was transferred to the receiver

You may experiment with the Test Adapter and the Message Monitor and send other documents. Please also ask your test partner to send documents to your Messenger.

The results shown in the Message Monitor indicate the processing sequence:

A Sender’s Adapter

M Sender’s Messenger

L Sender’s Listener



Net Network/Transmission

L Receiver’s Listener

M Receiver’s Messenger

A Receiver’s Adapter


5 Configuration Options

The overall configuration of Ponton X/P breaks down into the following sections:

Messenger configuration. This section focuses on your local setting for the Messenger. This includes database connections, default filter settings, communication protocol selection etc.

Partner configuration. Per partner, several settings are required: partner identification, filter activation (which overrides the default setting), communication settings, etc.

Agreement configuration. To communicate, two partners need to agree on a set of settings, they want to use for the interchange.

Certificate management. For own partners, key pairs may be created and certificates requested. For certificate authorities as well as for each individual partner, certificates can be installed. Certificates may be requested for signing and encryption, for SSL, and for S/MIME.

Hot folder configuration. The Hot Folder Adapter is tightly integrated with the Messenger and can therefore be configured through the same interface. It supports the definition of multiple hot folders for sending and receiving documents as well as dedicated folders for business partners.

5.1 Messenger Configuration

Messenger Database

The Messenger stores log entries in a database. Ponton X/P is installed with a pre-configured HSQL database. Please note, however, that the HSQL database is intended only for test purposes. For productive operations, an enterprise database system should be used, as for example:

Oracle (version 8.1.5 or compatible)

MS SQL Server 2000

DB2 (version 5.0 or compatible)

MySQL (version 4.0 or higher)

Sybase (version 12 or higher)

Other JDBC 2.0 enabled databases on request

The log database is accessed via JDBC connection. The Ponton X/P distribution includes configuration scripts to set up the tables for the database systems mentioned above. You can refer to these scripts as examples to create scripts for your own database system.

Configuration Options


If you do not yet have a database system with JDBC support in use, you can download the setup files for MySQL from http://dev.mysql.com/downloads.

To configure the Messenger database, the following set-up needs to be performed:

1. Go to Configuration Messenger Database.

2. Choose a matching database dialect from the dropdown list.

3. Enter the driver class name and the URL for the JDBC connection to your database.

4. Enter the user name and password for the connection, if required.

5. Click Test to test the connection.

6. Click Reconnect database to connect to the new database.

Note: The connection to the standard HSQL database supplied with the Messenger requires a “truncated” URL that does not contain the database name (as shown above). When using a different database system, please consult the relevant driver documentation for details on how to specify the database URL.

http://dev.mysql.com/downloads/



Logging Level

To specify the logging level, go to Configuration Messenger Logging and select the desired settings for Messenger and JDBC logging.

There is a range of settings available:

OFF turns logging off completely.

…

TRACE logs all the messages output by the system.

Note: Please keep in mind that the chosen logging level can have an effect on the performance of your system. In particular, it is advisable to use DEBUG or TRACE logging only in connection with error tracking and analysis.



Message Queue Settings

Under Configuration Messenger Message Queues you can specify the interval to scan the (inbound and outbound) message queues.

The default setting is 500 ms (0.5 seconds).

The Inbound Queue Delivery Timeout specifies the maximum timeframe allowed for a successful message delivery to an adapter. The timeframe starts when a message is scheduled for delivery and ends when the adapter acknowledges the correct reception. Whenever this allowed timeframe is exceeded a warning message will be logged. In combination with the email notification this can be used to alert an administrator about the communication issue between Messenger and Adapter.

With the Inbound Queue Notification Retry you can configure, how many times the failing of the delivery of a message to the adapter should be reported. So if the delivery timeout is specified as 5 minutes, a warning will be created every 5 minutes.

Inbound Queue Retry Delay specifies the delay after an unsuccessful message delivery attempt. This is used to disburden the receiving adapter in case of load peaks.



Partner Registry Configuration

The partner registry allows you to exchange profiles with other partners by uploading and downloading partner configurations to/from the registry. The connection and authentication to access the registry are configured on this page.

Registry URL – enter the address where the registry is to be accessed.

Username/Password – enter the user name and password for access to the registry. These will be provided by the registry administrator.

Automatic updates – this option allows you to automatically update your imported profiles at a specified interval. Please note that the download interval is only enabled when automatic updating is active.

Download partners now – click on the Download button to update your imported profiles immediately.



E-mail Configuration

By setting up inbound and outbound e-mail connections in your Messenger configuration you can enable a number of useful options, in particular:

E-mail notification – this requires an outbound e-mail connection.

SMTP and SMIME protocols – the use of SMTP and/or SMIME as a transport protocols requires an outbound e-mail connection for sending messages and an inbound e-mail connection for receiving messages.

Inbound connection

You can enable your Messenger to receive e-mail messages by setting up a POP/IMAP connection with the following entries:

Protocol – set to pop3 / IMAP (depending on the type of mail server)

Server – the hostname or IP address of your mail server

Interval – the frequency for accessing the server for mail download

Username / password – must be properly set to authenticate the Messenger on the mail server

Inbox Folder – the folder on the server where new emails are stored



Outbound connection

This connection is used for e-mail messages sent by your Messenger to your business partners. The following data needs to be configured:

From – the sender’s address to be used for your e-mails

SMTP – the outgoing mail server to be contacted by your Messenger in order to submit the e-mail

Username / password – must be entered if your mail server requires authentication for outgoing e-mails, in this case enter the settings to be used by the Messenger to log in on the mail server

To test the e-mail connection, enter a receiver e-mail address (in the Send test mail to field) and click on Test.

Certificate

This tab is used to request and install an S/MIME certificate for your Messenger, allowing you to exchange signed and encrypted messages via e-mail. Fill in the request form and submit your request to the Ponton CA. When you receive the S/MIME certificate go to the Show/Install tab and paste it in the entry box.

Note: This is the S/MIME certificate for your local Messenger configuration. For information on requesting and installing S/MIME certificates for your remote partner



configurations please refer to the Transport Certificates section. Further details on requesting and installing certificates can be found in the Partner Certificates section.

Also note that this S/MIME certificate is used in email based communication for all local partners, since they all share the same mailbox.



E-mail Notification

You can use the notification service to send e-mails to specified addresses whenever certain events occur. For example, you might want to notify your system administrator whenever certain errors are encountered.

To specify an address, go to Messenger eMail Notification and click New Receiver. Enter the e-mail address for this receiver in the text field, and select the events for which this receiver is to be notified. You can use CTRL-click to activate multiple entries in the list.

Subject Elements

If no subject elements are defined, the subject of the e-mail notification will be as follows:

“Notification for message” + Message ID

By defining one or more subject elements you can customize the subject of the e-mail notification. If you define several subject elements, they will be separated by blanks in the subject line.



For defining subject elements you can use the following element types:

Text – a static text that you enter in the text box.

Variable - a predefined variable such as the Message ID, the Message Type or the Receiver ID/Display Name.

Xpath - the xpath to an element/value contained in the payload message.

Please note that the use of xpath values as notification subject elements may lead to decreased performance, because the entire payload message has to be parsed in order to resolve the xpath expression.

Please note as well that only a subset of the complete xpath syntax is supported for the definition of subject elements. In particular, the following restrictions apply:

The xpath must be an absolute path starting with the root node of the payload document.

The xpath must refer to an actual node within the document. In the case of multiple nodes that satisfy the xpath, the first occurrence will be used.

Reference to node attributes is not possible.

Use of conditional expressions is not possible.



Communication Settings

On this screen you can specify

Proxy settings – if your Messenger will be connecting to the Internet via a proxy server. Please note: The NT Domain is only required if your proxy server uses NTLM authentication.

If you are going to be using a distributed Listener (as described in the Listener Configuration section) you have the option of also using the Listener as a proxy server for outgoing messages. In this case, click on the Use Listener Proxy button to enable use of the Listener as the Messenger’s proxy server.

Retransmission Handling – you can use this setting to specify the number of retransmission attempts and the interval (in seconds) between attempts. If a message cannot be transmitted successfully in the specified number of retries, the Messenger will give up and mark the message as “failed”.

SSL Server certificate check – if you enabled this option only communication with Messengers, that use SSL certificates that have been issued by a trusted CA known to your Messenger are allowed.

Allow loopback – makes it possible to send messages from a local partner to another local partner.



Server configuration

There are different types of connections to the Messenger called Services:

- Listener connections for inbound messages

- Adapter connections for outbound messages

- Administration connection for accessing the web interface

You can define multiple connectors for the communication with the Messenger. A connector specifies the protocol and the port for one or multiple services.

You also can change the protocol and the port for the GUI, but please note that only one connector can be defined for the GUI services.

SSL-Certificate

This page allows you to request and install a certificate for your server. You need this certificate to be able to receive messages via https. To request a certificate, go to the Request tab and fill in the form – then click OK.

Note: If your messenger is configured to send outgoing e-mail messages, you can activate the Send request to CA checkbox. Your certificate request will then be forwarded to the Ponton CA automatically. If you leave this checkbox deactivated, the certificate request will be generated and displayed on the next page. In this case, please copy the request to a text file and send it via e-mail to the address indicated (from a computer that has an e-mail connection).



When you receive the SSL certificate, copy and paste it into the text box on the Show/Install tab.

You need to restart Ponton X/P to let it use the new SSL certificate.

Archive Settings

The archiving filter stores the following information in a dedicated directory:

Backend Envelope

Packaging Envelope

Payload – this is the actual business document

Certificate

Signature

Attachment

Each part is stored in a separate file.

The Archive Folder setting can be used to indicate the location of the archiving folders. These can be expressed as

An absolute path to the required folder.

A relative path beginning with '$PONTONXP_HOME' – this placeholder refers to the folder [installation root]\xmlpipe.

In addition to the main Archive Folder, you can define a separate Archive Failed Folder, which will be used to store failed messages. If you prefer to store all your data in a single archive, you can use the same path setting as the Archive Folder.



The Maximum Age setting specifies how long the files will be archived – expressed in days.

Activation / License Configuration

This section describes how to install and activate licenses for Ponton X/P. If you want to activate the software as a trial version, please see the description starting on page 18.

Installing a license

You will generally receive your Ponton X/P license as a text or e-mail from Ponton or from your licensing organization.

To install your license go to Configuration Messenger Activation / License and click on the License tab. Copy the complete license text (including the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----) and paste the license text into the text box on the Install tab.

Click on Save to complete the installation of the license. You should see a message indicating that the license was successfully installed.



Activating an installed license

Depending on your license conditions it may be necessary to activate your license after it is installed. If so, you will see a Create Activation link in the upper right corner and on the Messenger Status screen.

To activate your license go to Configuration Messenger Activation / License and

click on the Activation Request tab - or simply click the Create Activation link. This will call up the Activation Request tab with a box containing your activation request.

The easiest and fastest way to complete your license activation is to click on the Send button (below the text box on the Activation Request tab). This will activate the license almost immediately. You should see a message indicating that your license was successfully activated.

Please note, that direct activation via HTTP is not available for trial licenses (included with the software distribution). To activate a trial version you will have to send the activation request by e-mail.



To submit your activation request by e-mail, as with the trial version (see page 18), click on the e-mail link at the top of the Activation Request tab or copy the complete activation request and send it to [email protected] using your preferred e-mail client.

You will receive a reply e-mail containing your activation code, which you can then copy and paste into the text box on the Install tab. Then click the Save button to complete your license activation.

Following the activation the message in the upper right corner and on the Messenger Status screen will indicate the name and the remaining lifetime of the license, for example:

Licensed for: ABC Corp, Days left: 1096

Notes

When sending your activation request by e-mail, it is important to copy the complete activation request code, including the lines “----- Begin Activation Request -----” and “----- End Activation Request -----”. This is also the case when copying the activation code from the reply e-mail into the Install tab. Again, please be sure to include the “Begin” and “End” lines.

Depending on your license conditions, you may need to repeat the license activation process after making certain changes to your local partner configuration.



Maintenance

Maintenance is used for disable the follow services:

Stop delivery to adapters - incoming messages remain in inbound queue and will not be sent to adapters.

Stop delivery to partners - outgoing messages remain in outbound queue and will not be sent to partners

Rejection of incoming messages - No messages from partners are accepted by the messenger's listeners (internal components, not to be confused with separate listener software)

Rejection of outgoing messages - No messages from the backend adapters are accepted by the messenger

To enable maintenance, at least one maintenance period must be created. During this time the Messenger the selected services will not be active.

5.2 Listener Settings

The settings in this section are used to specify the Listener configuration in a distributed installation. For details please refer to the Listener Configuration section (beginning on page 80).

5.3 Partner Configuration

The partner configuration distinguishes between Local and Remote partners – this distinction indicates whether the partner refers to a local partner configuration within your own Ponton X/P system or to a remote partner configuration on an external



system. In certain cases, the configuration steps may differ slightly. For example, you can submit a certificate request for a local partner, but not for a remote partner. In the case of remote partners you would receive the certificate from the partner directly or by downloading the partner’s profile from the registry.

A partner profile can be seen as representing the communication capability of the respective partner. A partner may, for example, support HTTP(S), SMTP, SMIME and FTP(S) as transport protocols. An agreement (as explained further down) then restricts the capabilities of two partners to a choice of options that are supported by both sides. In the case of the transport protocol, the partners might define HTTP as the protocol they want to use.

If you use the Adapter notification mechanism, any changes in your Partner Configuration will be reported to your adapters.

Create a Partner Entry

To create a new partner entry, go to Configuration Partners Create Partner, enter

a Local ID for the new partner (this is the local identifier for your configuration) and indicate whether this partner entry is for

A local partner – this might be a department within your organization.

A remote partner – these entries refer to your business partners, for example: customers, suppliers, carriers, warehouse operators, etc.

Finally, click on Create New Partner to generate the new partner entry – you will then see the partner configuration screen.



Delete a Partner Entry

To delete a partner entry, go to Configuration Partners Delete Partner, select the relevant Partner Name (the display name in your configuration), and then click Delete Partner.

Partner Identification

Partner display name – this is the name shown in the lists and screens within Ponton X/P.

Internal Partner ID – this identifier is used internally by Ponton X/P for communication with the backend and the file system.

Disable – this option allows you to disable a specific partner within your Messenger configuration, without deleting the partner configuration. In this case the Messenger will reject any message received from this partner.

PartyID / PartyID Type – PartyIDs are used to identify partners externally. To avoid name clashes and duplication, well-known naming schemas exist to identify partners, e.g., DUNS codes, VAT numbers, IANA codes etc. For this reason, trading partners should agree on a minimal set of identification types (like DUNS numbers and IANA codes) that is to be used by all partners.

Note: Please ensure that identical PartyIDs are used in the different Messenger configurations – otherwise there will be errors when you attempt to exchange messages with your partners.

More than one PartyID can be defined per partner. The limit is given by the number of PartyID types. These are configured separately – please check the Advanced Configuration section.

Hint! Please also check the Ponton X/P Technical Overview document for a detailed explanation of ebXML codes and partner identification.



Note: There are two additional checkboxes on this screen for the configuration of remote partners. If the Automatic updates option is activated, the profile for the remote partner will be downloaded from the registry automatically whenever it changes, while you can not change this partner manually. This is only the case, however, if the global setting to Enable automatic updates has been activated in the Profile Registry configuration.

Enabling automatic Certificate updates will allow having partner certificates automatically updated if an ebXML signed message is received. Several restrictions apply to this automatic update:

the new certificate must have a later issue date

the issuing CA must be the same

the distinguished name of the subject must be unchanged

Certificate updates via the profile registry are not affected by this flag.

Communication Settings

The communication settings specify the URIs of Partner’s Messenger Service for the supported communication protocols. Choose a protocol and enter the address to be used to access the partner’s Messenger via the given protocol, for example: partner.server:8080/pontonxp/SoapListener.

It is possible to use several URIs per protocol. This allows you for example to set up different Listeners for one partner by varying the address like

partner.server:8080/pontonxp/AS2Listener.





Schema Sets

The Schema Sets tab allows you to specify which schema sets are “allowed” for message exchange with this partner. The actual set of schemas to be used can be specified individually in each partner agreement.

On the Schema Sets tab you will see a list of the schema sets installed on your Messenger system. Each entry in the list comprises the following elements:

A checkbox for activating/deactivating the given schema set.

The name of the schema set.

A numerical entry indicating the number of selected/defined document types in the schema set – for example, 8/10 means that there are 10 document types included in the schema set and 8 of them are currently activated.

A Details link that can be used to call up the document type configuration for the given schema set.

To specify which of the document types contained in a schema set are to be used, click on the Details link. This calls up a window showing a list of the defined document types in the schema set. You can use the checkboxes to activate/deactivate the individual document types. The checkbox above the list (in the upper left corner) can be used as a select all/select none shortcut.



Note: Please click the OK button after making any changes to the document type configuration, and then be sure to click the Save button on the Schema Set tab. Otherwise your changes will not be saved.



Payload Processing Configuration

The Validation, Signing, Compression, Encryption options specify whether the relevant message processing methods are supported by the given partner.

Partner Certificates

For local partners you can go to the Request tab and fill in the certificate request form to obtain a certificate from the Ponton CA. When you receive the certificate via e-mail, copy and paste it into the text box on the Show/Install tab. You will need to enter the private key password (i.e. the password you entered when you filled in the certificate request) to confirm that this certificate is actually yours.

To install a remote partner’s certificate, have the partner send you the certificate via e-mail and then cut and paste the certificate code into the relevant partner configuration. Likewise, you can share your certificate with your business partners by sending the certificate to them via e-mail and having them paste it into their partner configurations.

Note: It is important to cut and paste the complete certificate code, including the lines “----- Begin Certificate -----” and “----- End Certificate -----”.

Important: A partner certificate will only be accepted after the certificate of the issuing CA (certificate authority) has been installed. Otherwise the trust relationship between the partner and the CA cannot be traced. The certificate for the Ponton CA is automatically included in the default installation. For other certificate authorities you will need to obtain and install the relevant CA certificate.



LDAP Certificate Import

If the certificates that should be installed are located on a public LDAP server, it is also possible to directly import the certificates from that server. On the Show/Install page, the LDAP radio button has to be clicked to display the LDAP related configuration.

Please consult your LDAP administrator about the needed DN and Attribute settings.

Also note that certificates for remote partners with a LDAP references will also be checked for updates during the regular automatic certificate-update.



Multiple certificates - Default certificate definition

You can install several certificates for one local partner. This enables you to use different certificates for functions like signing and encryption or for different partners. More important, you can use the default certificate function to ensure that whenever a certificate expires a new valid certificate is available.

The advantage of the default certificate is that your Messenger replaces an expired certificate automatically by a valid one, as long as there are still valid certificates left in your partner configuration. In case your counterparty uses a 3.1 Messenger, its Messenger will update the default certificate of your partner profile parallel to your Messenger. In any other case you may have to provide the new default certificate to your counterparty.



All certificates that you install for one partner will become default certificate in the order of their valid-from date. Alternatively, you can select manually the default certificate and the certificate that should be default when this certificate expires.

For the use of the default function in the agreements, please refer to the Partner Agreements section.



Message Packaging

The options on this page specify how the messages sent by this partner will be packaged for transmission and backend processing.

You can choose between different packaging standards, that offer divers options to specify whether the relevant packaging elements will be used by this partner. ebXML and AS1/AS2/AS3 are most widely used. For details on the specific settings please refer to the descriptions of packaging elements in the Partner Agreements section.

Synchronize Partner Profile with the Registry

To synchronize the current partner configuration with the profile registry, go to the Registry tab. If the current partner configuration has not changed since it was last synchronized with the registry, a corresponding message will be displayed.

Otherwise you will see an Upload-button (in case of a local partner) or a Download-button (in case of a remote partner).

Please note that the Messenger has to establish a connection with the registry in order to compare the current partner configuration with the profile stored in the registry. For this reason you may experience a short delay when you open the Registry tab.



Transport Certificates

Transport certificates are used for S/MIME connections.

To install a transport certificate for a remote partner go to Configuration Partners Transport Certificate and select the intended S/MIME connection from the URL list. Then paste the certificate into the displayed text box.

To install a transport certificate for a local partner go to Configuration Messenger

eMail Certificate and select the intended S/MIME connection from the URL list. Then paste the certificate into the displayed text box.

Remote Maintenance

Remote Maintenance is used for disable message exchange with the remote partner.

To enable remote maintenance, at least one maintenance period must be created. During this time the Messenger will not send any documents on partner URLs.



5.4 Partner Agreements

About Partner Agreements

Partner agreements serve to specify the communication, processing and other settings to be used when messages are exchanged between specific partners. Each agreement applies to a given combination of a local and a remote partner or, if you use loopback, a combination of two local partners. The agreements define specific settings relating to the sending and the receipt of messages, as well as global settings for both sending and receiving.

When setting up a partner agreement it should be noted that the range of options available for selection is dependent on the options supported by the two partner configurations. Only options that are activated in both partner configurations can be chosen as part of the partner agreement.



The settings in each partner agreement are based on how the two partners want to handle the communication, packaging and processing of messages. Each partner agreement implements a specific combination of settings according to the requirements of the given partners. For details on what the individual settings mean and how they work, please see the descriptions in the Partner Configuration section.

Creating a Partner Agreement

To create a new partner agreement, go to Configuration Agreements Create/Delete Agreement. From the list of Local and Remote Partners, select your local partner and the intended remote partner for this new agreement. Then click on Create New Agreement.

This leads you to the agreement configuration page. You can call up this page

afterwards by going to Configuration Agreements Agreements and selecting the relevant partners at the top of the page or by clicking on an entry in the Agreements

List (Configuration Agreements Agreements List).

Creating an Agreement between two local partners

To be able to create an agreement between to local partners you first have to enable loopback in the Messenger Configuration (see page 36). After this, you can proceed in the same way as described above.

Note: Only one agreement is created between two local partners. This means that most settings are fixed for inbound direction of the receiving partner after adjusting the sender’s outbound settings. Nevertheless, you have to change the roles of partner1 and partner2 when editing the agreement once to define the inbound adapter the receiving partner should use.

Messenger Partner Configuration

Internal Partner„LondonTrading“- Use http/https/smtp/smime

- Use 3.0/3.1 Schemas- Encrypt, Sign, Compress- IP = 203.112.4.133

Internal Partner„LondonTest“- Use http/https/smtp/smime


Internal Partner„ParisTrading“- Use http/https/smtp/smime


. . .

External Partner„Stadtwerke XYZ“- Use https- Use 3.0 Schemas- Encrypt, Sign, Compress- IP = 144.211.59.172

External Partner„Centrica“- Use http/https/smtp/smime


Internal Partner„TimbuktuTrading“- Use http- Use 3.1 Schemas- Encryption, Signing- IP = 182.144.21.1

. . .

AgreementLTr/XYZ-https, 3.0- Signing, Encr.

AgreementLTr/Centr.-https, 3.1- Signing, Encr.

AgreementLTst/XYZ-https, 3.0- Signing, Encr.

AgreementPtr/Timbuktu-http- Signing, Encr.

Internal Partners External Partners



Editing a Partner Agreement

To display or edit the settings in an existing partner agreement, go to Configuration

Agreements Agreements. From the list of Local and Remote Partners at the top of

the screen, select the partners the agreement applies to. Then click the Outbound, Inbound or Global radio button (in the upper left corner) to call up the respective settings for this agreement:

Outbound – these settings apply to messages that partner1 sends to the partner2.

Inbound – these settings apply to messages that partner1 receives from partner2.

Global – these settings apply to both outbound and inbound messages.

The agreement settings for communication, packaging, processing etc. are located on different tabs. Most of the settings in an agreement configuration are based on options specified in the partner configurations. For details on the different topics please refer to the Partner Configuration section.

Once again, please note that you will only be able to select options that have been activated for both of the partners in question. So if you and your communication partner have not specified a common set of options, there will be no options to agree upon and the page will have no content. In this case the settings in the partner configurations will need to be modified so that an agreement configuration is possible. Please note, however, that the agreement has to be compatible on both sides, so you will want to contact the partner in question to specify the options to be supported.

Note: If you subsequently change your partner configurations so that certain settings in the partner agreement are no longer applicable, you will see a red X at the top of the agreement configuration screens and the relevant settings will be highlighted red.



Please deactivate any settings in the agreement that are not supported by both partners. You can quickly check which settings are affected by going to the Messenger Status screen. The Events list at the bottom of the screen will contain an entry for each of the “conflicting settings”. To call up the relevant configuration screen you can simply click on the error description.

Note: If you imported a partner configuration from the profile registry, you will not be able to change your partner’s configuration settings locally. You will have to contact the relevant partner, agree on a common set of configuration options, and then upload/update each other’s modified configurations via the profile registry.



Communication

URI – specifies the transport protocol to be used for sending messages based on this agreement.

Retries / Retry Interval – indicates how often and how long the Messenger will try to send a message until it receives an acknowledgement. If more than (retries + 1) intervals are entered than the last retry interval will be used by rest retries.

Packaging

ebXML Standard:

available for all protocols

Use XML Signature – signs the message with XML Signature In the outbound direction you have to select the certificate for signing in case you have multiple certificates.

Request Acknowledgements – if you enable this setting all outbound messages must be receipted by an acknowledgement from your partner. These acknowledgements can be signed, if your partner supports this option.

The ebXML Service / ebXML ServiceType settings can be used to specify the ebXML service that handles the message. For papiNet messaging “%TESTFLAG%” can be used as the service identifier (to automatically set the service to Test or Production) and “papiNet” can be used as the service type.

ebXML Action – This setting identifies a process within the specified ebXML Service. For papiNet messaging “%MESSAGETYPE%” can be used to automatically set the action to the message type.

Request synchronous reply – If you use a synchronous protocol, a reply can be requested through the same connection.

CPA Id – The CPA Id specifies the parameters governing the exchange of messages between the parties. For papiNet messaging the following agreement can be used: www.papiNet.org/data/CPABasicHTTP.xml.

Role – EbXml allows you to define a role for sender and receiver (ex. 'buyer' and 'seller'). This has no effect on Ponton X/P, but other messaging software might require specific values.

Attachment role – EbXml allows you to define roles for the different attachment types. Ponton X/P uses these roles to identify attachments in case of multiple attachments.

AS1, AS2 and AS3 Standard:

The possible settings for these standards are mostly the same, but while AS1 is available for SMTP, AS2 covers the communication by HTTP(S) and AS3 covers the communication by FTP(S).



Request MDN – similar to an acknowledgment you can request an MDN for all outbound messages from your partner. If you want the MDN to be signed, you can select the algorithm.

For AS2, the MDN can be send to an address different to the sender address, if you enable Request asynchronous reply and fill in the URI.

S/MIME signature – you can select the algorithm to sign the message with your eMail certificate.

If you enable S/MIME compression a lower amount of data has to be transmitted.

S/MIME encryption – It is recommended to encrypt messages to achieve secure messaging. Your message will be encrypted with your partner’s eMail certificate.

Plain:

available for HTTP(S) and FTP(S)

sending and receiving pure XML messages without the need of a transport envelope

intended for the communication with a partner that does not have a Messaging software and does not want to maintain one. For the detailed configuration of the Plain Packager, please refer to the section Advanced Configuration (page 74).

Processing

All options selected under processing are applied to the payload.

Validation – enables XML validation for incoming/outgoing messages.

Signing – specifies whether signing is to be used. If activated you can select the signature algorithm: “SHA1withRSA”, “SHA512withRSA”, “MD5withRSA” or “SMIME-SHA1”. In the outbound direction, you also have to define which certificate should be used for signing, if you have installed multiple certificates for your local partner.

Compression Type – specifies whether compression is to be used. If activated, you can select the compression type: “Zlib”, “Deflated” , “GZIP” and “ZIP”. The default value is “Zlib”.

Encryption – It is recommended to encrypt messages to achieve secure messaging. Selectable values are DES-EDE3-CBC, SMIME-DES-EDE3-CBC, AES256_CBC or SMIME-AES256_CBC. Encryption is performed with your remote partner’s certificate. If your partner has multiple certificates you have to select the certificate by which the encryption should be carried out.

You can select divergent processing options for special Message Types by defining Processing Exceptions.



Rules

The settings on this tab can be used to specify Content Rules for inbound and outbound messages based on the current partner agreement. The Inbound / Outbound radio buttons are used to display the settings for the respective message processing direction.

For details on defining Content Rules please refer to the section Content Rules (see page 92).

XML Modification

The XML modification is – when enabled – the first step of the inbound or outbound message processing. By XML Modification it is possible to change encoding and the line ending of a document before sending or after receiving, so that it is adapted to the requirements of the receiver or of an interior adapter.

Additionally, there are options to change some XML elements in the payload that are especially helpful to guarantee the compatibility with older papiNet standards.

XML Encoding – the document can be transferred to UTF-8 and UTF-16, several ISO encodings and some encodings for Japanese text.

Line Ending – the line endings in the document will be changed to the LF, CR or CR LF.

Update Envelope – PapiNet 1.x documents have envelope information in the payload. If this option is enabled the protocol, the message ID, the time stamp, the sender and the receiver will be set to right values.

Doctype – the DTD in a payload document can be updated according to the schema or can be removed.

Pretty Print – xml documents are reformatted to increase human readability. It has no effect on the xml structure itself, however it can help badly implemented xml parsers to process the document.

Schema Sets

The Schema Sets tab allows you to specify which schema sets are to be used for message exchange based on the current partner agreement. To access the Schema Sets tab open the relevant partner agreement and click the Global settings button.



Please note that the schema sets available for selection in a given partner agreement are dependent on the basic settings in your partner profiles for the two relevant partners. In the above example, the schema set for X12_503 cannot be activated, because one of the partner profiles does not support this schema set. Please keep in mind, however, that this consistency check is local, i.e. it applies to the partner profiles and agreements in your own Messenger configuration. To ensure successful message exchange with your remote partners you will need to cross check the selected options (as well as your other configuration settings) with your partners.

For further details, please refer to Partner Configuration Schema Sets.

Locating Inconsistencies in a Partner Agreement

Ponton X/P offers a convenient feature for locating inconsistencies between the settings in a partner agreement and the settings in the relevant partner configurations. If a setting is found to be inconsistent the Admin Tool will display the following messages and markers:

On the Messenger Status page, the inconsistent settings are shown in the Events list. The corresponding entries indicate which partner agreement is affected, for example:

Hint: To call up the relevant configuration page for the given agreement you can simply click on the description.



Within the agreement configuration, the presence of an incorrect or inconsistent setting is marked by a small red x in the upper left corner (next to the Outbound – Inbound – Global selection). If you point your mouse at the small x marker you will see a tool tip indicating that an inconsistency has been found, for example:

On the specific page in the agreement configuration where the incorrect or inconsistent setting is located, the label for the relevant setting is colored red, for example:

By pointing your mouse at the label you can call up a tool tip with further information. If you disable the relevant setting and then save the agreement, you will see that the option is removed from the agreement page, since it is no longer supported by at least one of the partners.



5.5 CA Certificates

Ponton X/P uses trusted certificates to ensure the identity and authorization of partner configurations. Ponton offers its own lightweight certification authority, which can be used in connection with Ponton X/P messaging. This is the default CA in a standard Ponton X/P installation and the Ponton CA certificate is automatically installed with the software.

If you want to use certificates issued by a 3rd party CA you will need to request and install the root certificate of the CA. You will not be able to install partner certificates issued by a given CA until the CA’s root certificate has been installed.

When you receive the CA’s root certificate go to Configuration Certificates

Install CA Cert and then copy and paste the certificate into the text field. If you received the CA certificate as a file (e.g. *.cer) you can use the Browse function to select the file for import. Click Save to add this CA certificate to your Messenger configuration.



5.6 Hot Folder Adapter

General Configuration

Address / Port – the Hot Folder Adapter (HFA) is addressed as a separate process that communicates with the Messenger via HTTP. Therefore, the hostname and port number need to be set up for the Messenger. If the HFA is co-located with the Messenger on the same machine, use “localhost” for the IP address. In this case, the HFA does not run as a separate Java process but will be hosted on the same server.

Path – the HFA needs to know the Adapter communication path of the Messenger. By default it is /pontonxp/AdapterService.

Console / File Log Level – the HFA provides log output to the console and to log files. Both can be configured regarding the level of detail. The console log is only useful if the HFA is running as a standalone application, so you can safely leave it disabled in the default configuration.

Create / Delete Hot Folder

Several HFAs may be created. The HFAs are created and deleted on the respective configuration pages under Configuration Hot Folder Adapters Create Hot Folder

(or Delete Hot Folder).

Each HFA registers under a different ID with the Messenger. HFAs may be created for individual partners – in this case, messages exchanged with other partners will be stored and processed by means of the default HFA.



Configure a HFA

Each HFA requires several directories to be defined:

Inbox – a document will be stored in the Inbox whenever it was received from a partner.

Outbox – documents to be sent to the business partner are dropped here. The HFA grabs them in a defined frequency.

Failed – if a document could not be sent to a partner and all retries failed, it will be stored in this folder.

Work – if a document transfer is in progress or all attempts to send the document have not yet been tried, the document will remain here. After a final failure, it will be transferred to the Failed folder.



The following settings are also supported:

Port – the port to be used by the HFA (optional)

Receiver format – standard format is XML

Save Backend envelope – the Backend envelope is retained for incoming messages

Support attachments – the HFA will save any files attached to an incoming message to the selected inbox folder

Scan Interval – the interval to wait (in seconds) between checking the outbox

Max. number of parallel messages – specifies the maximum number of receiving threads the adapter can process simultaneously.

Use partner subfolders – if this is set, this HFA will create inbox and outbox folders for the defined local and remote partners. Inbound messages are automatically sorted into the according folder, depending on the specified (local) receiver. Outbound messages, on the other hand, have to be stored to the (remote) receiving partner’s outbox folder.

Note: Please note that no backend message is used in this mode and it is ignored if it exists.

Without partner subfolders, the HFA folder structure looks like this:



If you activate the partner subfolders option, subfolders for each defined partner will be added to the inbox (local partners) and the outbox (remote partners):



Use ERP acknowledgement – with this option activated, the ERP application receives an acknowledgement from the receiving Messenger on the partner’s side. This acknowledgement will be provided via the specified Inbox.

File extensions – defines which files should be accepted by the hotfolder for processing. Additionally to .xml this could be for example .x12-files. For detailed information about the processing of x12 documents please refer to the Advanced Configuration (page 71).



5.7 Display Schema Configuration

The schema sets to be supported for each partner are defined in the partner configuration. The standard sets available with the installation are shown under

Configuration Schemata:



5.8 User Administration

Two types of user roles are distinguished:

Administrators – these users have full access to the Messenger’s configuration interface.

Operators – these users only have access to the Adapter Monitor, the Message Monitor, and the Test Adapter. The options in the configuration menu are not available.

Additionally, there is a distinction between expert and non-expert users. For the application of the Messenger in some environments certain configuration settings may be pre-defined. In the correspondent Messenger versions these settings are not visible for non-expert users. Nevertheless, expert users can access all items that they are allowed to by their role.

Please note the following points in connection with the Messenger’s standard user administration:

This is a very simple user administration. For integrating the Messenger with another user administration such as LDAP, please use the SSO version.

User accounts can only be created or deleted by administrators.


6 Advanced Configuration

6.1 Time Server Configuration

To ensure trouble-free exchange of messages and business transactions, messaging applications like Ponton X/P need to use a correct time setting. The standard solution for this issue is to synchronize the local system time with a time server. There are many high-precision time servers – so-called NTP servers – that can be accessed on the Internet. In general, communication between applications and NTP servers is carried out via UDP packets on port 123.

Time synchronization can be carried out at operating system level, or at application level. If the computer that hosts the Messenger application already has automatic time synchronization at the system level, there is no need to use additional application level synchronization.

To view or modify the NTP server configuration, go to

Configuration Messenger Time Servers

Depending on your requirements, you can activate/deactivate the Messenger’s Time Server synchronization by means of the enabled/disabled option.

Advanced Configuration


The Synchronize interval setting determines how often the application will be synchronized with the NTP server(s) – when enabled. The default setting is to synchronize every 24 hours.

For further information about NTP – the Network Time Protocol – please visit www.ntp.org.

6.2 XML Schema Configuration

Important! The Messenger distinguishes between available schema sets and activated schema sets. Just inserting entries in the schema configuration, as described in this section, does not activate the schema sets or the corresponding schemas for use by the Messenger. In order to make use of the schemas in a schema set, you have to activate the schema set in the partner configurations and partner agreements.

To view or modify the activated schema sets in a partner configuration, go to

Configuration Partners <partner name> Schema Sets

and activate/deactivate the relevant checkboxes.

In this manner you can activate and deactivate schema sets for specific partner configurations and also specify which of the schemas within a schema set are to be used in the given partner configuration or agreement.

The schema sets available in your Messenger configuration are contained in the following path below the Messenger installation folder:

[installation root]\xmlpipe\config\Schemata\

For each schema set there is a configuration file and a subfolder based on the name of the given schema set, for example:

[installation root]\xmlpipe\config\Schemata\EFET3.0\

[installation root]\xmlpipe\config\Schemata\EFET3.0.xml

In addition, there can be style sheets associated with the schemas in the new schema set. These are stored in a subfolder (based on the name of the given schema set) of the XSL folder, as in:

[installation root]\xmlpipe\config\XSL\EFET3.0\

The process of adding a new schema set to your Messenger configuration involves the following steps:

Create a new subfolder within the Schemata folder, using the name of the schema set as the folder name.

Copy the schemas for the new schema set into this folder.

Create a new subfolder within the XSL folder, using the name of the schema set as the folder name.

Copy the style sheets for the new schema set into this folder.

Create a configuration file according to schemaset.xsd with entries for the schemas contained in the new schema set. If you are not working in a controlled XML editing environment, you may want to create the new

http://www.ntp.org/



configuration file by copying one of the existing XML files and making the necessary changes. The following example shows the structure of configuration entries in this file.

<SchemaSet Name="yourSchemaSet">

<Schema Name="yourSchema" MessageType="yourMsgType" MessageVersion="yourMsgVers">

<Namespace>yourNamespace</Namespace>

<DisplayName>Your Display Name</DisplayName>

<SchemaFile>yourSchemaFile</SchemaFile>

<XSLFile>yourStylesheet</XSLFile>

</Schema>

…

<SchemaFolder>yourSchemaFolder</SchemaFolder>

<XSLFolder>yourStylesheetFolder</XSLFolder>

</SchemaSet>

You can add a schema to an existing schema set in this file by inserting a <Schema> block (just copy and paste one of the existing blocks and modify the configuration as required). Please ensure that your new schema specification includes correct settings for the attributes of the Schema element:

Name= This attribute corresponds with the ebXML Schema Location of incoming messages. When an ebXML message is received, the Messenger looks for a schema configuration where the Schema Name attribute matches the Schema Location specified in the ebXML envelope.

MessageType= This attribute corresponds with the attribute MessageMetaData/DocumentInfo@MessageName in the backend envelope of outgoing messages.

MessageVersion= This attribute corresponds with the element MessageMetaData/DocumentInfo/DTDVersionNumber in the backend envelope of outgoing messages.

Note: The specification of MessageType and MessageVersion must be used together for outgoing messages, as they are combined to form an identifier for the message schema.

You also have the option of adding a new schema set with your own schema definitions to the schema configuration. In this case you would insert a <SchemaSet> block with subordinate <Schema> blocks. Your added schema set will automatically be inserted in the list of available schema sets on the Messenger configuration pages.


6.3 Processing X12 Documents

The Messenger can send and receive documents that follow the X12 Standard. The processing, however, is different from its handling of XML documents. Please note, that the Messenger does not validate the X12 documents, but only reads out some elements that are needed to conduct the sending.

These elements are:

ISA06 – interpreted as the SenderID

ISA08 – interpreted as the ReceiverID

ISA13 – used as main part of the MessageID. As The ISA13 Interchange Control number is unique only for the sender, it is extended by the SenderID to build the MessageID.

ISA12 – interpreted as Schemaset (without the zeros)

ST01 – interpreted as the schema (=MessageType). The Transaction Set Header (ST) is a repetition element, but the messenger only considers the ST01 element in the first Transaction Set.

Decisive for the identifying of the elements is their position in the respective header, defined by the number of separators.

6.4 Processing EDIFACT Documents

Similar to X12 documents, the Messenger can also send and receive EDIFACT documents. The EDIFACT documents are not validated, but only needed elements are extracted from the mandatory UNB and UNH sections.

These elements are:

S002.0004 – interpreted as SenderID

S003.0010 – interpreted as ReceiverID

S004.0020 – used as MessageID

S009.0065 – interpreted as MessageType

S009.0052 and S009.0054 – these values are concatenated to form the MessageVersion. The Schemaset name is constructed with a static “EDIFACT_” prefix and the MessageVersion appended.



6.5 Advanced Database Configuration

Important! Since the Messenger database is used for essential message processing and tracking purposes, you should not experiment with the database configuration on a “live” system. For test and debugging purposes, you are advised to set up a trial system.

Installation with other Databases

This section describes the main steps required to install a different database system on the Messenger, for example an Oracle database.

1. Install database driver. Copy the database driver to

[installation root]\xmlpipe\lib

Note: Please note that only drivers with the extension *.jar are loaded by Ponton X/P. If the JDBC driver you want to use is a *.zip file, you will have to rename the file to *.jar. The JDBC driver for Oracle 9i is the file ojdbc14.jar.

2. Create database and tables. Ponton X/P is supplied with SQL scripts for DB2, MS SQL Server 2000, MySQL, Oracle and Sybase. These can be used to create the tables for the Messenger database. If you are using another database, you may need to modify these scripts to work correctly with your database system.

The SQL scripts are located in the subfolders under [installation root]\sql (once the database tables are in place, Ponton X/P will automatically insert master data as needed on start up, using [installation root]\xmlpipe\config\sql\insert_log_messages.sql).

3. Set up database connection. The configuration of database connections is described in the Messenger Database section beginning on page 26. To connect with a different database, choose a matching database dialect from the dropdown list and enter the Driver Classname and URL in the textboxes.

The entries for the Oracle 9i JDBC driver are:

Driver: oracle.jdbc.driver.OracleDriver

URL: jdbc:oracle:thin:@<host>:<port>:<database>

6.6 Advanced Message Monitor Configuration

In the configuration directory “...\xmlpipe\config” there is a file messagemonitor.xml which can be used to change the selection and ordering of the Message overview window in the Message Monitor. The default setting is displayed in the following picture:



The number of entries displayed per page in the Message Monitor can be set by means of the LinesPerPage setting. Particularly if you are using a high resolution screen (with more than 1024 x 768 pixel), you may want to increase the number of lines per page.

Further, a mapping table defines which database column is to be displayed in which monitor column. The number of columns again depends on the screen resolution.

Finally, if main memory size allows, caching of XSL stylesheet definitions helps accelerating processing speed for XSL transformations.



6.7 Agreement Configuration for Plain Packager

Outbound Configuration

This paragraph describes how to configure an Agreement when sending messages from your Messenger to a receiver without a messaging application by using the Plain Packager.

Please note: It is not recommended to use the Plain Packager for communication with messaging software, as all features which are covered by a transport envelope do not exist or are limited, like reliability, security, duplicate control.

Communication: If the receiver requires HTTP or FTP authentication, the user and password need to be configured in the outbound communication page

Packaging: Select the “Plain” tab.

Processing: Please clarify if your counterparty has any possibilities of processing. Usually you will have to turn off Signing, Encryption and Compression.

The resulting transmission is a HTTP POST or FTP STOR with a pure XML content which is containing the unaltered XML message as it was received by the Messenger from the Adapter.

The communication is successful if the receiver returns a HTTP 200 result-code or FTP 226 result-code. Any other code will be regarded as a failure



Inbound Configuration

To enable your Messenger to receive pure XML messages without transport envelope, you have to select the Plain Packager on the inbound direction of the Agreement. You can fill in a password that the sender has to transmit to be allowed to send messages. For security reasons it is recommended to specify a password for each Partner Agreement.

Inbound Messages need to be transmitted as HTTP POST to the URL http://YOUR_IP:PORT/pontonxp/PlainListener or FTP STOR to the URL ftp://YOUR_IP:PORT/inbound/plain/PARTNER_ID that you have to setup in the Communication page of the Partner Configuration.

It is recommended to select HTTPS or FTPS as protocol to avoid that username and password are transmitted in plain text.

Additionally, the Messenger needs to know who the sender and receiver are. There are two options to provide the Messenger with this information using HTTP:

The sender transmits HTTP BASIC authentication information with the POST. Username needs to be constructed of receiver id, sender id and a dollar sign as separator. For example: receiver$sender the password has to match what is configured in the inbound packaging options, if the password is disabled any password is accepted.

The sender transmits additional HTTP parameters as part of the URL. For example: http://YOUR_IP:PORT/pontonxp/PlainListener?cpa=receiver$sender&pass=pass



word the password has to match what is configured in the inbound packaging options, if the password is disabled any password is accepted.

If FTP is selected as transmission protocol, the information of sender and receiver must be transmitted similar to communication via HTTP. The sender will be identified using FTP authentication information, which can be explicitly set for each agreement or for all agreements, if the authentication information is a part of FTP URL like this: ftp://USERNAME:PASSWORD@YOUR_IP:PORT/inbound/plain/PARTNER_ID. Association between the FTP user and sender must be configured in your Listener. For details please refer to the FTP Settings section (beginning on page 91). The receiver will be identified using the last part of the URL. In this case is PARTNER_ID is the identifier of the receiver.

Identification of Message-Type

When an inbound message is processed it is important that the message can be recognized as a specific message type.

The Messenger is able to use meta information from the message content for identification purposes. Any of the following data is used in this process:

- DocType definition

- Schema location definition

- Schema-Namespace

- Root-Element name

If none of this was found, then it is not possible to validate the message against an XML Schema.

6.8 Listener Configuration

Depending on your security requirements and your system and firewall configuration, you may want to set up a Listener for incoming messages. The Listener can run on a computer in the DMZ, separate from the Messenger. The purpose of the Listener is to pick up incoming connections and forward them to the Messenger (across the firewall). The firewall rules must be set up to allow this connection between the Listener and the Messenger. When a message is received, the Listener notifies the Messenger and the Messenger then picks up the message.

You also have the option of subsequently installing the Listener as a service under Windows – this service can then be configured to start automatically when the system starts up.

To install the Listener, run the setup program (PontonXP-3.1-Listener-setup.exe) on the computer you will be using as the Listener.

The configuration is carried out in the Messenger Admin tool. Please note that a connection from the Messenger to the Listener is required for administrative access. This is specified on the Admin tab in the configuration. See below for further details.



Listener Connection Modes

The Listener can be used in different modes, depending on your security requirements and other system configuration issues. There are two basic features that can be used separately or in combination: callback mode and secure listener mode.

Note: The use of the secure modes – both forwarding and callback – is of particular interest when

No secure (HTTPS) connection is to be used between the Listener and the Messenger – in this case, the Listener can use a secured/encrypted channel (HTTPS) for external connections with partners and an unsecured/unencrypted channel for internal connections with the Messenger.

Client authentication is to be used for incoming requests – the Listener will accept an incoming HTTPS request/connection only if a corresponding client certificate has been installed in the Listener configuration.

Callback Mode

Note: When the Listener is used in callback mode (or secure callback mode) it takes up to 2 minutes before the connection between Messenger and Listener is established.

The communication flow between Messenger and Listener is as follows:

When the Messenger starts up, it opens a connection to the Listener. The configuration settings for the connection between Messenger and Listener are

located at Configuration Listeners Configuration, in particular on the Configuration tab.

When the Listener receives an incoming message (or rather an HTTP/HTTPS request), it informs the Messenger – by way of the permanent connection – about the arrival of the new request.

The Messenger then picks up the connection on the Listener’s callback port and redirects it to its own local port (e.g. your.messenger:8080) for further processing. There is no protocol conversion done, therefore an incoming HTTPS or HTTP connection is tunneled without modification to the Messenger.



Secure Listener / Forwarding Mode

In this mode, the communication flow between Messenger and Listener is handled as follows:

In forwarding mode, no permanent connection is established between the Messenger and the Listener.

When the Listener receives an incoming HTTP/HTTPS request, it simply forwards the data contained in the request to the Messenger using the address specified in the configuration. The forwarding always uses a new HTTP connection for communication with the Messenger.

The Listener can optionally verify SSL client certificates in case of HTTPS. Unauthorized connections will be rejected with an error response.

Note: To allow the forwarding connection, the firewall has to be configured so that the Listener is permitted to access the Messenger on the specified HTTP port.

Secure Listener / Callback Mode

This mode offers a combination of the features supported in Secure Listener mode and Callback mode, as described above. In particular, the use of client authentication can be combined with the advantages of the permanent callback connection.

Listener Settings in the Messenger Admin Tool

To set up or modify the Listener configuration, please go to Configuration

Listeners in the Admin tool.



Admin Connection

Enter the IP address and port for the admin connection (Messenger to Listener). The standard port number for this connection is 50081.

Note: If you want to use the Messenger without a distributed Listener you can deactivate the Listener by choosing “disabled”. Please keep in mind, however, that the connection settings for your Messenger service (both locally and in your partners’ configurations) will have to be adjusted accordingly if you change the Listener activation status.



Listener Mode

This setting allows you to determine the connection mode between Messenger and Listener. For further details please see Listener Connection Modes below.

Note: Please note that additional tabs and configuration settings are available depending on the selected connection mode.



Configuration Settings

The settings on this tab specify the Listener configuration for incoming connections and communication with the Messenger.

The following screen shows the settings for callback mode.

HTTP / HTTPS – enables the Listener to handle the relevant connection types.

Listener (1) – specifies the IP address and port for incoming connections of the relevant type (HTTP or HTTPS).

Service (2) – specifies the IP address and port for the permanent service connection of the relevant type (HTTP or HTTPS) between the Messenger and the Listener.

Callback (3) – specifies the IP address and port for the callback connection of the relevant type (HTTP or HTTPS) between the Messenger and the Listener.

For further details please refer to the Listener Connection Modes section.



When secure listener mode is selected, the configuration tab looks like this:



Client certificate check – specifies that the Listener will only accept connections from “known” clients. For connections with other Ponton X/P users you can simply use the partner certificates installed in your Messenger’s partner configurations. On the other hand, if you are going to be exchanging messages with 3rd party messaging services, you can install client certificates for these partners on the Client Certificate tab.

Use partner certificates – specifies that the partner certificates installed in your Messenger’s partner configurations will be imported to the Listener configuration and used for authentication of incoming HTTPS connections. This also enables automatic synchronization of partner certificates between Messenger and Listener.

Messenger (2) – specifies the IP address, port and context of your Messenger connection.

Max. data size – specifies the maximum size of incoming messages, including the transport envelope.




When secure callback mode is selected, the configuration tab looks like this:



Client certificate check – specifies that the Listener will only accept connections from “known” clients. For connections with other Ponton X/P users you can simply use the partner certificates installed in your Messenger’s partner configurations. On the other hand, if you are going to be exchanging messages with 3rd party messaging services, you can install client certificates for these partners on the Client Certificate tab.

Use partner certificates – specifies that the partner certificates installed in your Messenger’s partner configurations will be imported to the Listener configuration and used for authentication of incoming HTTP connections.

Service (2) – specifies the IP address and port for the permanent service connection between the Messenger and the Listener.

Callback (3) – specifies the IP address and port for the callback connection between the Messenger and the Listener.

Note: there is only one Service and one Callback setting, because all incoming HTTP/HTTPS requests are internally converted to new HTTP requests.




Connection Settings for Your Messenger Service

Please note that if you are going to receive incoming connections via the Listener, your partners will have to enter the public URI of your Listener in their configurations (under

Configuration Partners <partner name> Communication Tab URI of

Partner’s Messenger Service).

Proxy Settings

With this setting you can enable the use of the Listener as a proxy server for outbound connections. Please note that you will need to enable proxy communication in your Messenger configuration under “Communication Settings”.



Server Certificate

This tab is for the configuration of your Listener server certificate for HTTPS or FTPS connections.

Note: This tab is only available for secure listener and secure callback mode or if FTP is enabled.

The subordinate tabs are used to request and install the server certificate, as well as the CA certificate, if necessary. If you use Ponton certificates for the server and client certificate configurations, you will not need to install a CA certificate, since the Ponton CA certificate is already contained in the Listener distribution.



Client Certificate

This tab is for the configuration of client certificates for the authentication of HTTPS connections.

Note: This tab is only available for secure listener and secure callback mode.



The subordinate tabs are used to install (and delete) client certificates, as required. For partners using Ponton X/P you can simply import the certificates installed in your Messenger’s partner configurations by activating the “Use partner certificates” option on the Configuration tab.

FTP Settings

This tab is for the configuration of FTP settings.

The common FTP server settings can be configured on the Config subordinate tab.

On the Logins subordinate tab you can edit FTP users and associations between FTP user and receiver (remote partner).



6.9 Access to the Administration Tool

This section describes how to improve the security of the Ponton X/P system so that access to the Administration Tool is encrypted using HTTPS.

Enabling HTTPS access

By default only HTTP is used for accessing the administration interface. It is possible to switch to HTTPS by changing the server configuration. See page 37 for details.

6.10 Content Rules

You can define special rules that determine how messages will be processed based on specified content (within the message or the envelope). The content rules are defined specifically for each partner agreement.

To create a new content rule go to Configuration Agreements and choose the agreement you want to modify (i.e. the relevant local and remote partner). Then open the Rules tab and click on Create New Rule.



The basic definition of a content rule includes

XPath – this setting specifies the element or attributes to be checked for a given value or value range.

Operator – the operator used for comparing values.

Value – the value to be checked.

In addition to the specification of an element or attribute within the document, it is also possible to use the following reference keys in the XPath field to specify the associated message information:

!MessageType – The Message Type as specified in the document schema. Note: The available message types are displayed in the Message Monitor in the Message Type list.

!MessageVersion – This field identifies the schema version. The relevant version IDs can be found in the schema set definition files located under [installation root]\xmlpipe\config\Schemata

!SchemaSet – This field identifies the schema set name. The relevant names can be found in the schema set definition files located under [installation root]\xmlpipe\config\Schemata

!TestFlag – This flag is set to TRUE for test messages, otherwise it is FALSE.

!LogInfo – This field may contain remarks or any other text. The contents are displayed in the Message Monitor.

For outgoing messages – based on the given agreement – the content rule can be used to trigger a log entry and/or an e-mail notification and as a new feature, also the destination URL can be changed. So it is possible to route certain messages to different servers or URLs.



For incoming messages the content rule can also be used to determine which Adapter is used for message processing.

The action to be taken is based on the Action setting:

Action – you can select one of the following actions: Flag, EMailNotification, ChangeDestinationAdapter (for incoming messages only) and ChangeDestinationURL (for outgoing messages only).

Depending on the selected action, different settings are required:

For EMailNotification – specify the receiver’s e-mail address as well as any subject elements to be used. For details on defining subject elements see the E-mail Notification section (beginning on page 34).

For ChangeDestinationAdapter – choose the adapter to be used for message processing. The value field contains a list of the available adapters.

For ChangeDestinationURL – choose the URL to be used for the message. The value field contains all configured URLs for the receiving partner.

Note: The use of !SenderId or !ReceiverId as filter criteria is no longer supported since these are already specified as the local and remote partners of the relevant agreement. In other words, content rules are always sender and receiver specific.

6.11 Port Configuration

The Messenger’s standard configuration uses port 8080 for HTTP connections and port 8443 for secure (HTTPS) connections. If those ports are already in use or they are not allowed due to firewall policies, then it is necessary to adjust the default ports.

This section describes how to set up the messenger to use a non-default port configuration.

HTTP Settings

The port setting for the Messenger’s HTTP and HTTPS connections are stored in the configuration file server.xml:

[installation root]\xmlpipe\config\server.xml

This file defines the connections (Connectors) for the Messenger like this:

<Connector id="1">

<Address>*</Address>

<Port>8443</Port>

…

</Connector>

The standard settings for the Messenger ports are

HTTP port: 8080 for Adapters, GUI, Listeners

HTTPS port: 8443 for Listeners



Shutdown port : 7626

To modify your connections, you will need to enter the relevant port numbers indicated above as Port.

Callback Listener Port Settings

If the used Listener mode is either Callback or Secure-Callback, then it is needed to update the port configuration for the Messenger callback as well. The settings are defined in messenger.xml. There are two PrivatePort elements that have to contain the same values as defined for the Listener connector in the server.xml.

<CallBackListener>

<Http>

<PublicServerName>127.0.0.1</PublicServerName>

<InternalPort>4002</InternalPort>

<PrivatePort>8080</PrivatePort>

</Http>

<Https>

<PublicServerName>127.0.0.1</PublicServerName>

<InternalPort>4003</InternalPort>

<PrivatePort>8443</PrivatePort>

</Https>

</CallBackListener>

Adapter Settings

The settings for the Messenger adapters are contained in the relevant XML files under

[installation root]\xmlpipe\config.

In particular, a standard installation includes the files testadapter.xml and hotfolder.xml. Each of these configuration files contains a block specifying the connection to the messenger:

<Messenger>

<Address>yourMessengerHost</Address>

<PortNumber>yourMessengerPort</PortNumber>

<Path>…</Path>

</Messenger>

If you have configured the Messenger to run on a different port (see above), you will need to enter the relevant port number here.



6.12 Messenger Cluster

Since version 2.4 of Ponton X/P, there is a standard way of combining multiple instances of Messengers so that they appear as a single instance to external partners or administration users. For more information on this cluster mode, please contact the helpdesk at [email protected]




6.13 SSO Configuration

If you have installed the SSO based version of Messenger then you can manage the users that can access the Messenger and their roles more easily.

Most important benefits:

Central management of user accounts

Central management of application roles

Only one login for domain and application

In order to configure the Messenger for use of SSO you must perform following steps BEFORE you start the Messenger for the first time.

Remark: at this time only MS Active Directory based domains for both “MS Windows 2000 Server” and “MS Windows 2003 Server” are supported.

The Messenger must be able to access your Active Directory Server directly in order to process the authentication and authorisation mechanism.

Important! Please contact your system administrator (responsible for managing Active Directory Server) for the following steps about configuring your Active Directory Server.

Active Directory configuration

Create a user in your Active Directory which (user) will be used as “application service user” for the Messenger. (E.g. pontonxp)

Delegate the control of “Read Group Membership” for the object type “Users objects” under the “Users” folder to the “application service user” created above.

The picture below shows the Wizard-Summary of the described “control delegation” on a Windows 2000 Server Active Directory:



Create a group in your Active Directory that represents the administrator role in Messenger. E.g.: xp-admins. Add some users to this administrator group. (all users added to this group will be administrators of the Messenger)

Create a group in your Active Directory that represents the operator role in Messenger. E.g.: xp-operators Add some users to this operator group. (all users added to this group will have operator role in Messenger)

Messenger Configuration SSO file

The file <InstallationRoot>\xmlpipe\webroot\WEB-INF\SSOConfig.properties contains the information that the X/P Messenger needs to use the Active Directory.

It informs the X/P Messenger e.g. which users of which domain are allowed to use it (regardless of where the Messenger itself is running) and where to find the domain controller.

Please complete the following properties:

de.ponton.commons.sso.group_base

LDAP DN (Distinguished Name), in which the groups are defined. Consists of:



- CN\=... Name of the directory, in which the groups are defined.

- DC\=.... DC is for Domain Component. Domain Components are parts of the complete denomination of the domain. Each component comprises the segment between two dots.

Note: The name of the directory (1) and the complete denomination of the domain (2) can be found in the console tree of the Active Directory.

Example: de.ponton.commons.sso.group_base=CN\=Groups,DC\=test,DC\=ponton,

DC\=local

de.ponton.commons.sso.user_member_attribute

Name of the attribute that defines to which group a user belongs

Note: The default value (see example below) normally needs not to be changed.

Example: de.ponton.commons.sso.user_member_attribute=memberOf

de.ponton.commons.sso.wins

IP of the nameserver of the domain.



Note:

- If no name server is used, the variable %WINS_SERVER% can remain in this place.

- If you are not sure what to fill in, you can try the IP of the domain controller.

Example: de.ponton.commons.sso.wins=192.168.200.176

de.ponton.commons.sso.domain_name

Name of the domain.

Note: Can be found in the properties of the domain.

Example: de.ponton.commons.sso.domain_name=test

de.ponton.commons.sso.domain_controller

IP of the domain controller

Example: de.ponton.commons.sso.domain_controller=192.168.200.176

de.ponton.commons.sso.service_principal

Service User (to whom the control of the domain was delegated)

Consists of: <name of the domain>\\<name of the Service User>

Example: de.ponton.commons.sso.service_principal=test\\servicemess

de.ponton.commons.sso.user_base

Consists of:

- CN\=... Name of the directory, in which the users are defined.

- DC\=.... DC is for Domain Component. Domain Components are parts of the complete denomination of the domain. Each component comprises the segment between two dots. Note: can be found the same way as de.ponton.commons.sso.group_base.

Example: de.ponton.commons.sso.user_base=CN\=Users,DC\=test,DC\=ponton,

DC\=local

de.ponton.commons.sso.mapping.group.operator

Name of the group with the Messenger operators, as assigned when configurating the Active Directory.

Example: de.ponton.commons.sso.mapping.group.operator=pontonxp-operators



de.ponton.commons.sso.service_password

Service-User’s password, as assigned when configurating the Active Directory. The password is typed in clear text. It will be encrypted by the X/P Messenger on first start.

Example: de.ponton.commons.sso.service_password=start

de.ponton.commons.sso.user_login_suffix

Suffix of the sso users names.

Note: To be found in the properties of the user (tab account). Usually identical with the complete denomination of the domain.

Example: [email protected]

de.ponton.commons.sso.user_search_attribute

The attribute that is used to identify the user.


Example: de.ponton.commons.sso.user_search_attribute=userPrincipalName

de.ponton.commons.sso.strict_domain_logon

Must be true.

Example: de.ponton.commons.sso.strict_domain_logon=true

de.ponton.commons.sso.domain_controller_port

Number of the port, where the Active Directory is listening on.


Example: de.ponton.commons.sso.domain_controller_port=389

de.ponton.commons.sso.mapping.group.administrator

Name of the group with the Messenger administrators, as assigned when configurating the Active Directory.

Example: de.ponton.commons.sso.mapping.group.administrator= pontonxp-admins

Browser Configuration

Please note that for Internet Explorer and Firefox browser different steps are required in order to activate the Browser-based SSO authentication.

Internet Explorer



The authentication process is done automatically by Internet Explorer 6, only if the Messenger start URL is identified as “Local Intranet”.

In some cases where the URL of the Messenger installation does not resides in the “Local Intranet” zone of your IE6 you need also to add such URL manually.

To do so:

- go in main menu to “Tools/Internet Options”

- select the “security” tab

- select “Local intranet”

- click on “Sites..” button

- click on “Advanced…” button

- type the URL of the Messenger server into the field labelled “Add this Web site to the zone:”

- click on “Add” button.

Recommendation: the network administrator should add globally the URL of the Messenger to the “Local Intranet” zone of you Internet Explorer.

Firefox

To activate the SSO integration in Firefox you need to perform following steps:

- Type about:config in the address field of Firefox

- Type network.automatic-ntlm-auth.trusted-uris in the filter filed

- Double click on the result line

- Type the URL of the Messenger in the appearing dialog and click on OK.

- You may need to restart Firefox in order the changes have effect.