Messenger. Installation and Configuration Guide

Transcription

1 Messenger Installation and Configuration Guide Manual Version 3.1 September 19, 2008

2 Content FURTHER INFORMATION AND SUPPORT INTRODUCTION ABOUT PONTON X/P ARCHITECTURE OVERVIEW SUPPORTED FEATURES DOWNLOADING PONTON X/P COMPONENTS INSTALLING PONTON X/P MINIMUM SYSTEM REQUIREMENTS INSTALLATION PROCEDURE IMPORTING THE CONFIGURATION FROM A PREVIOUS VERSION INSTALLING PATCHES QUICK-STARTING THE SOFTWARE LOGGING IN STOPPING THE MESSENGER BASIC CONFIGURATION CHECK IF ADAPTERS ARE RUNNING CHECK THE STATUS OF YOUR MESSAGES CONFIGURATION OPTIONS MESSENGER CONFIGURATION LISTENER SETTINGS PARTNER CONFIGURATION PARTNER AGREEMENTS CA CERTIFICATES HOT FOLDER ADAPTER DISPLAY SCHEMA CONFIGURATION USER ADMINISTRATION ADVANCED CONFIGURATION TIME SERVER CONFIGURATION XML SCHEMA CONFIGURATION PROCESSING X12 DOCUMENTS PROCESSING EDIFACT DOCUMENTS ADVANCED DATABASE CONFIGURATION ADVANCED MESSAGE MONITOR CONFIGURATION Ponton X/P 3.1 Installation and Configuration Guide 2

3 6.7 AGREEMENT CONFIGURATION FOR PLAIN PACKAGER LISTENER CONFIGURATION ACCESS TO THE ADMINISTRATION TOOL CONTENT RULES PORT CONFIGURATION MESSENGER CLUSTER SSO CONFIGURATION Ponton X/P 3.1 Installation and Configuration Guide 3

4 Further Information and Support Technical Support/Helpdesk Phone Ponton Consulting XML Information Pages (World Wide Web Consortium) (OASIS standards organization) (all about ebxml) (XML industry portal) xml.coverpages.org (XML Cover Pages) (software products for XML processing) Ponton X/P 3.1 Installation and Configuration Guide 4

5 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 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 Ponton X/P 3.1 Installation and Configuration Guide 5

6 Hot Folder Adapter Generic Adapter Test Adapter Generic Adapter Test Adapter Generic Adapter Hot Folder Adapter Generic Adapter Introduction User Business Partner Ponton X/E Application Ponton X/P XML Document Ponton X/D ERP System DB Ponton X Series 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. ebxml Message Listener Messenger Messenger Listener ERP ERP ebxml Acknowledgement Ponton X/P 3.1 Installation and Configuration Guide 6

7 Introduction 1.3 Supported Features Features Features (Cont.) Base Features Security Features EbXML 2.0 Support 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 , HTTP(S) and FTP(S) >92% Document Compression Embedded request & installation of X.509 certificates Support of Win2000, Win2003 Server, Win XP, Vista, Solaris, Access to Ponton certification HP/UX, AIX, Linux authority Archiving of doc., signature, etc. 1-click signature verification Admin/user notification by Other Features Web-based configuration & monitoring Fine-grained definition of allowed XML Schemas per Agreement SOAP and Web-Service Interface Localizability Turnaround time with encryption & signing in both directions for 50 KB payload within LAN 0,5 Sec Included Localizations en,de,fr,ru,pt Same across Internet: Turnaround of 90% of transfers < 4 Sec. 1:1 definition of communication settings and XML Schema sets Performance (Messages per min.) Perform. (4 Clustered Messengers) >=150 >=600 Programming interface for software integration Scheduling of maintenance times Online Registry for Profile Exchange Ponton X/P 3.1 Installation and Configuration Guide 7

8 2 Downloading Ponton X/P 3.1 The software can be downloaded from the product page of Ponton Consulting: Please fill in the download request form. You will receive an 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. Listener another lightweight process that polls your mail server for new messages. Ponton X/P 3.1 Installation and Configuration Guide 8

9 3 Installing Ponton X/P 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 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 Ponton X/P 3.1 Installation and Configuration Guide 9

10 Installing Ponton X/P 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: Ponton X/P 3.1 Installation and Configuration Guide 10

11 Installing Ponton X/P 3.1 Messenger Configuration. This includes the settings for: - Communication - - 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. Ponton X/P 3.1 Installation and Configuration Guide 11

12 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: or 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. Ponton X/P 3.1 Installation and Configuration Guide 12

13 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. Ponton X/P 3.1 Installation and Configuration Guide 13

14 Quick-Starting the Software 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. Ponton X/P 3.1 Installation and Configuration Guide 14

15 Quick-Starting the Software 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. Ponton X/P 3.1 Installation and Configuration Guide 15

16 Quick-Starting the Software 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. Ponton X/P 3.1 Installation and Configuration Guide 16

17 Quick-Starting the Software 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 connection). Otherwise, you will see a page with a text box containing the certificate request. This page includes an 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 Ponton X/P 3.1 Installation and Configuration Guide 17

18 Quick-Starting the Software 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 link at the top of the page. This will copy the activation request to your client. Using your client, please send the activation request to activation@ponton-consulting.de. 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 containing the activation code for your system. Please copy the complete activation code and paste it into the text box on the Install tab: Ponton X/P 3.1 Installation and Configuration Guide 18

19 Quick-Starting the Software Notes When sending your activation request by , 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 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 Ponton X/P 3.1 Installation and Configuration Guide 19

20 Quick-Starting the Software 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: The URL for the test server at Ponton Consulting is: 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) (DB ID) (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. Ponton X/P 3.1 Installation and Configuration Guide 20

21 Quick-Starting the Software 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 Ponton X/P 3.1 Installation and Configuration Guide 21

22 Quick-Starting the Software Call up the Test Adapter from the main menu of Ponton X/P: Ponton X/P 3.1 Installation and Configuration Guide 22

23 Quick-Starting the Software 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). Ponton X/P 3.1 Installation and Configuration Guide 23

24 Quick-Starting the Software 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 nonbusiness 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 Ponton X/P 3.1 Installation and Configuration Guide 24

25 Quick-Starting the Software Net Network/Transmission L Receiver s Listener M Receiver s Messenger A Receiver s Adapter Ponton X/P 3.1 Installation and Configuration Guide 25

26 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 preconfigured 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 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. Ponton X/P 3.1 Installation and Configuration Guide 26

27 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 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. Ponton X/P 3.1 Installation and Configuration Guide 27

28 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 28

29 Configuration Options 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 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. Ponton X/P 3.1 Installation and Configuration Guide 29

30 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 30

31 Configuration Options Configuration By setting up inbound and outbound connections in your Messenger configuration you can enable a number of useful options, in particular: notification this requires an outbound connection. SMTP and SMIME protocols the use of SMTP and/or SMIME as a transport protocols requires an outbound connection for sending messages and an inbound connection for receiving messages. Inbound connection You can enable your Messenger to receive 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 s are stored Ponton X/P 3.1 Installation and Configuration Guide 31

32 Configuration Options Outbound connection This connection is used for 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 s SMTP the outgoing mail server to be contacted by your Messenger in order to submit the Username / password must be entered if your mail server requires authentication for outgoing s, in this case enter the settings to be used by the Messenger to log in on the mail server To test the connection, enter a receiver 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 . 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 Ponton X/P 3.1 Installation and Configuration Guide 32

33 Configuration Options 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 based communication for all local partners, since they all share the same mailbox. Ponton X/P 3.1 Installation and Configuration Guide 33

34 Configuration Options Notification You can use the notification service to send s 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 Notification and click New Receiver. Enter the 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 notification will be as follows: Notification for message + Message ID By defining one or more subject elements you can customize the subject of the notification. If you define several subject elements, they will be separated by blanks in the subject line. Ponton X/P 3.1 Installation and Configuration Guide 34

35 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 35

36 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 36

37 Configuration Options 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 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 to the address indicated (from a computer that has an connection). Ponton X/P 3.1 Installation and Configuration Guide 37

38 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 38

39 Configuration Options 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 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. Ponton X/P 3.1 Installation and Configuration Guide 39

40 Configuration Options 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 . Ponton X/P 3.1 Installation and Configuration Guide 40

41 Configuration Options To submit your activation request by , as with the trial version (see page 18), click on the link at the top of the Activation Request tab or copy the complete activation request and send it to using your preferred client. You will receive a reply 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 , 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 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. Ponton X/P 3.1 Installation and Configuration Guide 41

42 Configuration Options 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 Ponton X/P 3.1 Installation and Configuration Guide 42

43 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 43

44 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 44

45 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 45

46 Configuration Options Ponton X/P 3.1 Installation and Configuration Guide 46

47 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 47

48 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 48

49 Configuration Options 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 , 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 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. Ponton X/P 3.1 Installation and Configuration Guide 49

50 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 50

51 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 51

52 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 52

53 Configuration Options 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 Downloadbutton (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. Ponton X/P 3.1 Installation and Configuration Guide 53

54 Configuration Options 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 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. Ponton X/P 3.1 Installation and Configuration Guide 54

55 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 55

56 Configuration Options Internal Partners Internal Partner LondonTrading - Use http/https/smtp/ smime - Use 3.0/3.1 Schemas - Encrypt, Sign, Compress - IP = Internal Partner LondonTest - Use http/https/smtp/ smime - Use 3.0/3.1 Schemas - Encrypt, Sign, Compress - IP = Internal Partner ParisTrading - Use http/https/smtp/ smime - Use 3.0/3.1 Schemas - Encrypt, Sign, Compress - IP = Messenger Partner Configuration Agreement LTr/XYZ -https, Signing, Encr. Agreement LTst/XYZ -https, Signing, Encr. Agreement LTr/Centr. -https, Signing, Encr. Agreement Ptr/Timbuktu -http - Signing, Encr. External Partners External Partner Stadtwerke XYZ - Use https - Use 3.0 Schemas - Encrypt, Sign, Compress - IP = External Partner Centrica - Use http/https/smtp/ smime - Use 3.0/3.1 Schemas - Encrypt, Sign, Compress - IP = Internal Partner TimbuktuTrading - Use http - Use 3.1 Schemas - Encryption, Signing - IP = 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. Ponton X/P 3.1 Installation and Configuration Guide 56

57 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 57

58 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 58

59 Configuration Options 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: 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). Ponton X/P 3.1 Installation and Configuration Guide 59

60 Configuration Options 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 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 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. Ponton X/P 3.1 Installation and Configuration Guide 60

61 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 61

62 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 62

63 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 63

64 Configuration Options 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 3 rd 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. Ponton X/P 3.1 Installation and Configuration Guide 64

65 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 65

66 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 66

67 Configuration Options 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: Ponton X/P 3.1 Installation and Configuration Guide 67

68 Configuration Options 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): Ponton X/P 3.1 Installation and Configuration Guide 68

69 Configuration Options 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). Ponton X/P 3.1 Installation and Configuration Guide 69

70 Configuration Options 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: Ponton X/P 3.1 Installation and Configuration Guide 70

71 Configuration Options 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. Ponton X/P 3.1 Installation and Configuration Guide 71

72 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. Ponton X/P 3.1 Installation and Configuration Guide 72

73 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 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 Ponton X/P 3.1 Installation and Configuration Guide 73

74 Advanced Configuration 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= MessageType= MessageVersion= 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. This attribute corresponds with the attribute MessageMetaData/DocumentInfo@MessageName in the backend envelope of outgoing messages. 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. Ponton X/P 3.1 Installation and Configuration Guide 74

75 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: S interpreted as SenderID S interpreted as ReceiverID S used as MessageID S interpreted as MessageType S and S these values are concatenated to form the MessageVersion. The Schemaset name is constructed with a static EDIFACT_ prefix and the MessageVersion appended. Ponton X/P 3.1 Installation and Configuration Guide 75

76 Advanced Configuration 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: Ponton X/P 3.1 Installation and Configuration Guide 76

77 Advanced Configuration 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. Ponton X/P 3.1 Installation and Configuration Guide 77

78 Advanced Configuration 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 Ponton X/P 3.1 Installation and Configuration Guide 78

79 Advanced Configuration 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 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: Ponton X/P 3.1 Installation and Configuration Guide 79

80 Advanced Configuration 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. Ponton X/P 3.1 Installation and Configuration Guide 80

81 Advanced Configuration 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. Ponton X/P 3.1 Installation and Configuration Guide 81

82 Advanced Configuration 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. Ponton X/P 3.1 Installation and Configuration Guide 82

83 Advanced Configuration Admin Connection Enter the IP address and port for the admin connection (Messenger to Listener). The standard port number for this connection is 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. Ponton X/P 3.1 Installation and Configuration Guide 83

84 Advanced Configuration 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. Ponton X/P 3.1 Installation and Configuration Guide 84

85 Advanced Configuration 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. Ponton X/P 3.1 Installation and Configuration Guide 85

86 Advanced Configuration When secure listener mode is selected, the configuration tab looks like this: 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). 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 3 rd 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. For further details please refer to the Listener Connection Modes section. Ponton X/P 3.1 Installation and Configuration Guide 86

87 Advanced Configuration When secure callback mode is selected, the configuration tab looks like this: 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). 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 3 rd 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. For further details please refer to the Listener Connection Modes section. Ponton X/P 3.1 Installation and Configuration Guide 87

88 Advanced Configuration 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. Ponton X/P 3.1 Installation and Configuration Guide 88

89 Advanced Configuration 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. Ponton X/P 3.1 Installation and Configuration Guide 89

90 Advanced Configuration 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. Ponton X/P 3.1 Installation and Configuration Guide 90

91 Advanced Configuration 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). Ponton X/P 3.1 Installation and Configuration Guide 91

92 Advanced Configuration 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 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. Ponton X/P 3.1 Installation and Configuration Guide 92

93 Advanced Configuration 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 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. Ponton X/P 3.1 Installation and Configuration Guide 93

94 Advanced Configuration 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, Notification, ChangeDestinationAdapter (for incoming messages only) and ChangeDestinationURL (for outgoing messages only). Depending on the selected action, different settings are required: For Notification specify the receiver s address as well as any subject elements to be used. For details on defining subject elements see the 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 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 Ponton X/P 3.1 Installation and Configuration Guide 94

95 Advanced Configuration 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> </PublicServerName> <InternalPort>4002</InternalPort> <PrivatePort>8080</PrivatePort> </Http> <Https> <PublicServerName> </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. Ponton X/P 3.1 Installation and Configuration Guide 95

96 Advanced Configuration 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 xp-helpdesk@ponton-consulting.de Ponton X/P 3.1 Installation and Configuration Guide 96

97 Advanced Configuration 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: Ponton X/P 3.1 Installation and Configuration Guide 97

98 Advanced Configuration 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: Ponton X/P 3.1 Installation and Configuration Guide 98

99 Advanced Configuration - 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. Ponton X/P 3.1 Installation and Configuration Guide 99