Interchange 5.12.0 AdministratorsGuide AllOS en
Interchange 5.12.0 AdministratorsGuide AllOS en
Interchange 5.12.0 AdministratorsGuide AllOS en
ADMINISTRATOR GUIDE
Interchange
Version 5.12
10 August 2015
Copyright © 2015 Axway
All rights reserved.
This documentation describes the following Axway software:
Axway Interchange 5.12
No part of this publication may be reproduced, transmitted, stored in a retrieval system, or translated into any human or
computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise,
without the prior written permission of the copyright owner, Axway.
This document, provided for informational purposes only, may be subject to significant modification. The descriptions and
information in this document may not necessarily accurately represent or reflect the current or planned functions of this
product. Axway may change this publication, the product described herein, or both. These changes will be incorporated in
new versions of this document. Axway does not warrant that this document is error free.
Axway recognizes the rights of the holders of all trademarks used in its publications.
The documentation may provide hyperlinks to third-party web sites or access to third-party content. Links and access to these
sites are provided for your convenience only. Axway does not control, endorse or guarantee content found in such sites.
Axway is not responsible for any content, associated links, resources or services associated with a third-party site.
Axway shall not be liable for any loss or damage of any sort associated with your use of third-party content.
Contents
Preface 23
Who should read this guide 23
Related documentation 23
Support services 23
About this guide 24
Accessibility 26
Accessibility features of Interchange 26
Keyboard shortcuts 26
Screen reader support 27
Accessibility features of the documentation 27
Screen reader support 27
Graphic readabilty 27
1 About Interchange 34
Features and services 34
Support for transport protocols 34
Support for trading exchanges 34
Support for security protocols 35
Message services 35
Trading partner management 36
Security services and operations 37
Visibility 37
Standards certification 37
2 Planning considerations 38
Security considerations 38
Firewalls and proxy servers 39
Interchange in a firewall environment 40
Editing URLs to allow for firewalls 41
Getting a partner’s external connection details 42
Proxy servers 42
User interface with proxy servers 42
Deployment in proxy environment 42
Forward proxy 43
4 Peer network 65
Can you use peer network? 65
Peer network overview 66
Protocols for peer communication 66
Trading protocols supported for peer cloning 66
Cloneable objects and their dependent objects 67
Example architectures 68
Peer network business use cases 71
Disaster recovery 72
Staging environment 72
20 WebTrader 980
Can you use WebTrader? 980
Terminology 980
WebTrader overview 981
Manage WebTrader partners and users 981
After you create a WebTrader partner 982
Add a WebTrader partner 982
Manage sponsor and trading relationships 984
Manage trading restrictions 985
Add a WebTrader user to a partner 990
Delete a WebTrader user from a partner 991
Add WebTrader user roles 992
Set WebTrader password policy 993
Additional WebTrader user management options 994
Group WebTrader partners by category 994
Enable trading with non-WebTrader partners 995
Use the WebTrader partner search tool 996
Activate self-registration for WebTrader partners 996
Manage WebTrader p artner and community attributes templates 997
Create a partner or community attributes template 998
Modify a partner or community attributes template 999
Fill in required WebTrader partner attributes 999
Change the attributes template display order 1000
Delete partner or community attributes template 1000
Manage WebTrader d ocument attributes templates 1000
Create a document attributes template 1001
Modify a document attributes template 1001
Change document attribute display order 1002
Delete a document template 1002
22 eSubmissions 1032
Can you use eSubmissions? 1032
25 Troubleshooting 1139
Troubleshoot online help 1139
Use the log4j file for troubleshooting 1139
Troubleshoot test trading 1139
Troubleshoot protocols and standards 1139
ebXML 1139
HTTP 1139
SFTP 1140
Web service 1140
X.25 1140
Troubleshoot unexpected Interchange restarts 1140
Unexpected Interchange restarts 1140
Analyze restart problems 1140
Glossary 1144
l Networks
l Servers
l Databases
l Security
l User accounts and permissions
l Document exchanges with applications and business partners
This guide presumes you have knowledge of:
l Your company's business processes and practices
l Your company's hardware, software, and IT policies
l The Internet, including use of a browser
Others who may find parts of this guide useful include other technical or business users.
Related documentation
Go to Axway Sphere at support.axway.com to view and download Interchange documentation.
Support services
Go to Axway Sphere at support.axway.com to contact a representative, learn about training
programs, or download software, documentation, and knowledge-based articles. The website is for
customers with active Axway support contracts. You need a user name and password to log on.
About Interchange — Describes use cases, EDI standards, information about how Interchange
processes messages, and standards certification. See About Interchange on page 34.
Planning considerations — Describes how to plan for your Interchange installation, including
security considerations; firewalls and proxy servers; trading large messages; and documenting
custom configurations. See Planning considerations on page 38.
Peer network — If your software license enables peer networking, this chapter describes business
use cases, peer network settings, configuration, cloning, managing duplicate messages, and how to
track peer messages. See Peer network on page 65.
Trading configuration — Learn about the trading configuration used by Interchange. See
Trading configuration on page 132.
Message Tracker — Message Tracker is a tool in the user interface for monitoring database records
of traded messages. See Message Tracker on page 826 for more information.
Staged HTTP — Describes how The staged HTTP transport provides a secure way for communities
to receive messages from partners without having to change firewall configurations. See Staged
HTTP on page 958.
WebTrader — You can use WebTrader if your software license.xml file enables the webtrader
key. See WebTrader on page 980.
CSOS — For licensed users, Interchange supports digital signing and verification of controlled
substance orders in compliance with the U.S. Drug Enforcement Administration. See Axway CSOS
on page 1008.
eSubmissions — Describes the functionality within Interchange to send large messages to the
U.S. Food and Drug Administration. See eSubmissions on page 1032.
Troubleshooting — Describes the steps you can take if you are having trouble installing or using
Interchange. See Troubleshooting on page 1139.
This section describes the accessibility features of the Interchange product and its documentation.
l Keyboard shortcuts on page 26
l Screen reader support on page 27
Keyboard shortcuts
Interchange provides a set of shortcuts for navigating the interface screens and for executing
various actions.
Note To use shortcuts with JAWS, turn off the virtual PC cursor. For more information, see
Screen reader support on page 27.
The following table contains a list of keyboard shortcuts that you can use:
To do this Press
Move forward through selectable objects Tab
Move backwards through selectable objects Shift + tab
Multi-select in list boxes (where multi-select is enabled) Ctrl + click
Multi-select (where multi-select is enabled) Shift + click
Select/clear check boxes and radio buttons Space
Display drop-down box content Alt + down arrow
Move cursor within drop-down box Up arrow / down arrow
As with other screen readers, you interact with JAWS using keyboard shortcuts. Most of the time,
you must press the JAWS key in combination with other keys. By default, the JAWS key is the Insert
key.
To use the arrow keys and keyboard shortcuts with Interchange, turn off the virtual PC cursor by
pressing the JAWS key+Z.
Graphic readabilty
l The documentation is very readable on high-contrast displays.
l There is sufficient contrast between the text and the background color.
l The colors used in graphics are designed to be easily distinguishable by people who have color
blindness.
l Product enhancements on page 28
l Documentation enhancements on page 33
Product enhancements
The following product changes have been made:
New Functionality
Platform updates Operating systems (all 64-bit):
l Windows 2012
l RHEL 7
l AIX 7
Databases:
l DB2 10.5
l Oracle 12c
l MySQL 5.6
l Axway Database 4.6.0
Java: JRE 7
Security: TLS 1.2
See the Interchange Installation Guide for a full overview of supported platforms.
Admin user To enhance product security, when logging into the Interchange user interface for
password change the first time as the admin user, the interface requires you to change the default
requirement admin password.
Acceptance of Email pickups now include an option for accepting inbound email from a POP3 server
email sender by based on server domain. Wild card characters are supported for defining groups of
domain accepted email sending addresses.
See:
l Modify an SMTP (embedded) transport on page 383
l Modify an SMTP/POP (external) transport on page 388
Swagger Swagger is automatically deployed by the installer to provide a user-friendly interface
automatic for REST API operations.
deployment
Web Services You can now configure Interchange to generate metadata attributes from the SOAP
SOAP header headers of inbound Web Services messages. The metadata can be used in ways
metadata similar to other Interchange-handled metadata.
Sequential Guarantees the delivery order of distributed messages. The new capability ensures the
delivery messages are delivered in a first-in first-out (FIFO) order. For example, this makes
certain that a Purchase Order message and an Order Update message are delivered
sequentially. This p romotes productive and efficient supply chain relationships.
Security Enhanced fine-grained roles and access controls ensure a comprehensive approach to
governance user level permissions and restrictions. Complete support for encryption and TLS/SSL
is supported throughout the product, as well as password credential encryption.
FTP message FTP external pickup configuration now enables you to use the consumption order
processing can (consumption timestamp) to determine the message processing order.
now be set to the See "Modify an FTP (external) pickup or delivery" in the Interchange Administrator
order of oldest to Guide.
newest
New database / Interchange now supports:
version support l DB2 10.5
l The use of DB2 HADR in cluster environments.
l Oracle 12c
See "Set up DB2 database" or "Set up Oracle database" in the Interchange Installation
Guide.
Audit logging of You can now generate CVS and XML formatted logs of the changes that users perform
changes made in in the user interface.
the user interface See Create audit files of UI object changes on page 1089.
Enhanced system The system throttle can now be manually engaged to enable the system to complete
throttling of the processing of all currently active messages.
message See Manage the system throttle on page 62.
processing on
Interchange
nodes
Enhanced Communication adapter enhancements have been made to multiple communication
communication protocols including:
adapters l APOP (Email)
l MQ (V8/SSL, Multi-Instance)
l FTP (SAPPEND/SUNIQUE)
l PeSIT
l SMTP (New sender validation allows broader range of sender email addresses)
l Staged HTTP (Updated OS and JRE support)
l FTP/SFTP (Embedded servers upgraded to create events when files are
downloaded)
Visibility - l More detailed reporting to Sentinel
Sentinel
l Heartbeat information from Interchange
performance and
exchange l Improved installation and configuration, including configuration of the backup
monitoring Sentinel server for notifications
l Sentinel server connection configuration from the Interchange user interface
l Sentinel tracking of WebTrader events - Sentinel now collects information about
WebTrader user and administrator actions
l Sentinel Tracked Object evolutions - The number of events reported by the
Sentinel Tracked Object for Interchange has been reduced to limit processing
load.
See Sentinel on page 1061.
Sentinel tracking When a remote partner accesses the embedded FTP/SFTP server to download a file,
of FTP/SFTP Interchange now generates and sends an event to Sentinel that indicates one of the
customer following new STATES:
download events l Downloading
l Downloaded
l Interrupted
l Removed
For additional information about Sentinel tracking of embedded FTP/SFTP server
event states, see the Interchange Administrator Guide.
Additional New standards support for retail value chain, healthcare, and financial have been
message added for:
standards and l MLLP
protocols
l AS4
AS4 support Interchange provides support for AS4 message trading with remote partners. This
includes support for:
l One-way message push exchanges
l One-way message pull exchanges
l Server-mode AS4 message queuing
l Client-mode polling of remote AS4 server queues
l Large message splitting and joining
l Duplicate message detection
l Message retry and resending
l UserNameToken and X509 user authentication
See AS4 on page 499.
User interface l Enhanced search tools including more granularity for searches of unpackaged
enhancements protocols
l Improved display controls - Pagination / scalability for displays of thousands of
configuration objects
l Updated navigation and help links
l Permission-driven control of users' rights to change/delete all objects
l Flexible trading partner management, with user-defined attributes
Security l Access control enhancements - More permissions, controls, and restrictions
improvements l Broader support for encryption and TLS/SSL everywhere
l Broader configuration of encryption on partner and transaction type levels
l PGP enhancements
WebSphere MQ Interchange now provides JARs in support of WebSphere MQ 8.x.
8.x support
REST APIs APIs now support a Representational State Transfer (REST) model for accessing
processing resources. See the Interchange Developer Guide for more information.
CRL retrieval You can now configure automated CRL checking and downloading using HTTPS
using HTTPS URLs, in addition to the HTTP and LDAP URLs that were already supported.
URLs
Axway DB 4.6.0 Interchange now supports the use of Axway Database 4.6.0. To use this database, it
support must be installed using the dedicated Axway Database Installer.
See "Set up Axway Database" in the Interchange Installation Guide.
Discontinued Functionality
Platforms Interchange 5.12 is only supported on Windows, Linux, and AIX. See the Interchange
Installation Guide for more details.
32-bit support From this release, Interchange is installed only in 64-bit mode.
EBICS Interchange 5.12 does not support EBICS.
ePedigree ePedigree is not embedded in Interchange 5.12.
Transaction As of this release, Transaction Director is no longer delivered. End-to-end visibility is
Director now provided by Sentinel.
Synchrony Synchrony Database 4.4.0 is not supported with Interchange 5.12. Users must
Database 4.4 upgrade to Axway Database 4.6.0.
Persistable event The persistable event queue for Sentinel is no longer supported.
queue
Anonymous user The anonymous user feature is no longer supported. Instead, a default remote user is
included with the deployment. See the Interchange Administrator Guide for more
information.
Documentation enhancements
This release of Interchange includes the following documentation changes:
l The documentation set for Interchange has been reorganized and a new standalone installation
guide was created.
l Accessibility features, such as alternative tags for images, have been added to each document,
as well as a new Accessibility chapter.
Interchange can be implemented as a single end-point solution or as a clustered, fault tolerant
gateway with unlimited trading partners. The application's user interface integrates gateway
management, monitoring and metrics into one view.
l AS4
l EDIINT AS1, AS2, AS3
l OFTP (V1 and V2) over TCP/IP, X.25, and ISDN
l RosettaNet RNIF (V1.1 and V2)
l ebXML ebMS (V2)
l HL7 MLLP (V1 and V2)
l cXML (V4)1
l Web Services (SOAP/REST)
l X.400 over X.25 and TCP/IP (X.420 and X.435 profiles)
l HTTP, HTTP/S, Staged HTTP Web Servlet
l Axway Transfer CFT, and PeSIT
l FTP, S/FTP, FTP/S
l JMS, IBM WebSphere MQ
l WebDAV
l Secure email (via SMTP)
l File System
l WebTrader - WebTrader is a browser-based interface for mailbox-based exchange of files over
secure HTTP. Non technically trained end users can send and receive documents, and manage
copies of these exchanges from a user-friendly interface.
l Software Development Kit for custom protocols
Note CXML V4.0 protocol is currently in beta status. (Limited tests have been done. Available
upon request only.)
l SSL 2.0, 3.0
l TLS 1.0 - TLS 1.2
l SSH 2.0 (client authentication)
l S/MIME
l PGP
l Certificates (X509, PGP) with CRL, CSR, CEM, and OCSP support
l FIPS
l NIST 800-52
l Encryption: RC2, RC4, DES, 3DES, AES
l Signature: MD5, SHA-1, SHA-256
l Algorithms for key exchange: diffie-hellman-group1-sha1, diffie-hellman-group14-sha1, diffie-
hellman-group-exchange-sha1.
Message services
Interchange provides the following message-handling services:
l Integration with back-end applications
l Message identification based on one or more exchange attributes, standards, identifiers, or
individual content.
l Multiplication (duplication)
l Message routing
l Message handling can be extended with optional processing of inbound or outbound messages
based on metadata attributes and actions. Interchange enables you to set up conditions to:
o Copy messages to parties other than the sending or receiving party
o Re-route messages from one partner to another
o Prohibit re-routing of messages
o Reject messages
o Perform custom processing using your own Java class
o Generate notifications
Message handling involves performing message actions. Message actions are triggered by single
or multiple conditions, which are a combination of attributes and operators. For example, you
can specify that whenever a community sends a message to partner A, a copy is sent to partner
B.
Message actions can be applied to inbound and outbound messages. For inbound messages,
message actions are applied after a message has been validated, unpackaged and parsed, but
before the payload is sent to a back-end system via an application transport. For outbound
messages, message actions are applied after a document has been picked up from the backend,
but before it has been packaged.
l Community definitions – A community represents your local way of grouping trading partners. It
defines your organization’s internal processes for handling messages. It also defines how your
community expects to receive messages from partners. The local information is used by your
system to set document back-up options, tune system performance, and integrate with back-end
systems. While these settings are significant to you, they are not relevant for your partners.
l Ramping, in-Life, and decommissioning management.
l A registration wizard helps members of a community generate partner information for trading.
This functionality is for partners who want to trade via AS1, AS2, ebXML, or WebTrader. The
wizard prompts a user to supply the information Interchange needs to build a valid partner.
l Security certificate management – Interchange offers true security by providing authentication,
confidentiality, integrity, and non-repudiation of documents. Interchange uses state-of-the-art
cryptography to ensure the security of the documents that are exchanged over the Internet.
l Role-based access – Users and roles enable administrators to add and manage ranges of user
permissions. Roles define the permissions users have for performing tasks. Roles can be defined
with few or many permissions. Each user should be assigned at least one role, although it is
possible to assign multiple roles to a single user.
l Signing – Interchange supports digital signatures. Signing is a mechanism by which a message
is authenticated, proving that the message is effectively coming from a given sender.
l Encryption – Interchange uses a combination of public-private key encryption (asymmetric
encryption), and symmetric key encryption. This hybrid system uses the best characteristics of
each method and minimizes the shortcomings of each. It follows the widely adopted S/MIME
standard for securing messages.
l SSL authentication – Interchange optionally allows certificates to be used for authenticating the
identity of trading partners. Secure Sockets Layer (SSL) protocol authentication provides an
added layer of security to trading relationships.
Visibility
Interchange provides the following visibility-related features:
l End-to-end visibility – There are a number of ways to monitor system activity. Methods are
available through the user interface and log files. The user interface methods are easier to use
and understand than the log files, which are designed for software developers or advanced
users. The user interface has tools for monitoring various types of system activity.
l Alerts/Events – Each product generates events and alerts that aid in tracking abnormal or
unexpected behavior across the system. Alerts and events are written to log files.
Standards certification
The Interchange trading engine has been certified for
interoperability for AS1, AS2, AS3, AS4, and ebXML. See
http://www.drummondgroup.com for a list of software the
trading engine has been tested with successfully for
interoperability.
l Security considerations on page 38
l Firewalls and proxy servers on page 39
l User interface with proxy servers on page 42
l Run the UI over HTTPS on page 44
l Data backup recommendations on page 47
l Document custom configurations on page 48
l Trade large messages on page 49
l See also: Peer network on page 65
Security considerations
To ensure the integrity of data, the following security measures are recommended in addition to
your company's own security policies. Although risks are possibly remote, failure to institute
minimum security measures may result in compromised data.
l Do not install or run Interchange under a privileged account. This includes root in UNIX and
administrator or system accounts in Windows.
l Do not view a binary document that has been received by Interchange without first scanning the
document for viruses.
l Institute a policy for periodically changing the password for logging on to the user interface.
l Control access to the computer running Interchange to authorized users.
l If you use an external database on a different computer than the one running Interchange,
control access to the database computer to authorized users.
l If you manually distribute your digital certificates to trading partners, do so via a secure means.
Encourage your partners to do likewise. If you send certificate files as email attachments,
compressing the files with WinZip or another such tool is recommended.
It is likely you or your partners have firewalls to guard against unauthorized connections. You must
take firewalls into account when configuring Interchange.
Moreover, your network may require outbound HTTP messages to the Internet to go through a
proxy server on your network. On rare occasions, the messages you send may have to go through a
proxy server on your partner’s network.
Caution Message trading can fail if firewalls or proxy servers are not considered when configuring
Interchange. This is a common issue for new users. Consult with your network
administrator if you need help with firewalls or proxy servers.
The following figure shows where a firewall or proxy server could be located in proximity to your or
your partner’s network.
The following are guidelines for outbound and inbound traffic.
l Outbound – As a general rule, your firewall must be configured to allow outbound HTTP traffic
on the port you specify in the URL for your partner (for example, 4080). Your partner's firewall
must be configured to allow inbound HTTP traffic on the port you specify.
In highly secure environments you may want to set up firewall rules that only allow outbound
HTTP traffic on this port to the IP address of your partner. However, this imposes a firewall
maintenance burden on you if your partner's IP address changes or if you add partners. The
same applies to your partners if they choose to configure their firewalls to allow inbound traffic
only from specific IP addresses.
l Inbound – The firewall considerations for inbound traffic are similar to those for outbound
traffic. You can allow blanket inbound traffic on a particular port such as 4080 or you can
specify per-partner firewall rules based on the IP address of each partner who connects to you.
Specifying partner-specific firewall inbound firewall rules provides a high level of protection
against denial-of-service attacks. As with partner-specific outbound firewall rules, however, it
imposes a firewall maintenance burden if the partner’s IP address changes or if you add partners.
Note If your software license supports DMZ nodes, your configuration can be different. See
Secure Relay DMZ nodes on page 474.
As part of normal operation, the operating system's socket layer dynamically allocates a local port
for each outbound connection you make. This requirement is a fundamental part of socket-based
protocols such as Telnet, FTP and HTTP. It is not specific to Interchange. For example, if an
outbound connection is made to an HTTP host on port 4080, the operating system allocates a
dynamic port for the client's end of the connection. This can be seen by running the netstat -an
command on the client after the outbound connection is established. If your firewall is so strict that
it checks the ports in each packet that passes through it, you must configure the firewall to allow
packets containing dynamic ports associated with local addresses. These are typically in the range of
49152 to 65535 with most operating systems, but on some systems the range is 1024 to 65535.
These dynamic ports are associated only with outbound connections. It is not necessary to allow
new inbound connections on these ports.
If you place Interchange in the DMZ, take precautions to move the decrypted documents out of the
DMZ to a secure location. You can accomplish this any number of ways. The method usually
depends on your back-end needs and choice of integration options.
When you configure the embedded HTTP or HTTPS inbound transport, the default local URL is in
the following format:
The local URL contains the internal name (cluster machines) for the computer running Interchange.
You cannot change the local URL. If you installed Interchange behind a firewall or load balancer,
you must make sure your partners have the correct public URL to send you documents. Values such
as the host, port and path in the public URL may be different than the internal values because of
remapping performed by the firewall or load balancer.
Depending on your transport, your partner needs a URL in the following format:
You may have to contact your company’s firewall administrator to obtain the correct public URL.
You can change the URL for partners on the transport maintenance page of the user interface. After
confirming the URL is correct, you can export your community profile for your partner to import as a
partner profile. The external URL is contained in the partner profile.
A similar consideration applies to embedded FTP servers. You must specify the external public host
and port in the server settings.
Ask the partner for the external name or IP address and port number for each transport protocol you
intend to use.
From the Partners page, select the partner and open the maintenance page for the transport for
sending messages to the partner. Make sure the URL for sending is correct on the Settings tab. Enter
a user name and password to connect if required.
Proxy servers
If your network requires all outbound HTTP traffic to navigate a proxy server to access the Internet,
you can enable this for the community. For more information see HTTP outbound proxy on page
584.
l Deployment in proxy environment on page 42
l Forward proxy on page 43
l Reverse proxy on page 44
Interchange can be deployed in a network environment where proxy servers are used to enhance
security, caching or logging. Two typical proxy server implementations are described: forward proxy
and reverse proxy.
Forward proxy
In a forward proxy configuration, the web proxy server is used within a company’s local area
network behind a firewall or in the DMZ. Path A in the following figure illustrates that browser users
connect to internal and external servers via a proxy server behind a firewall. Usually as a matter of
policy, all browsers in the company are configured to go through the proxy server to connect to
internal and external web servers. A browser can be configured to bypass the proxy server (path B in
the figure), but this probably would go against policy.
The web proxy server might be set up inside the firewall, as in the figure, or in the DMZ. If inside the
firewall, the proxy server is configured to route internal HTTP traffic directly to the servers. It does
this based on the domain name or IP subnet. If in the DMZ, the browser is configured to route HTTP
to the proxy when an Internet server is detected.
Interchange can be deployed in a forward proxy environment. While this does not require modifying
browsers, adjustments are required for the proxy server.
The proxy server needs to be configured to restrict hosts to Interchange domains. It also must be
configured to provide direct access to internal web servers.
Reverse proxy
In a reverse proxy configuration, the web proxy server is in the DMZ as shown in the following
figure. It provides a secure path for external client browsers through the firewall to the internal web
server. The external users address their browsers to the proxy host name and port number and might
use the secure HTTP protocol, HTTPS. The proxy server translates external browser requests to the
host name and port number on the inside of the firewall.
To deploy Interchange in a reverse proxy environment, configure the proxy with reverse mapping.
Consult with the proxy server administrator or see the proxy documentation for how to configure
the mapping. For example, consider a situation where the server runs on HostA port 6080 and the
proxy server runs on HostB port 8080. In this case external browsers would use the following URL to
connect to the server on the inside: http://HostB.collaborationsoftware.com:8080.
Configure HTTPS
Use this procedure to configure the server so that browsers can log on to the user interface via
HTTPS.
information about the cipher suites they have in common. Then they communicate using the
common cipher suite that offers the highest level of security. If they do not have a cipher suite
in common, secure communication is not possible.
In versions of Interchange earlier than 5.9, cipher suites configuration was handled by a file
named sslciphersuites.xml. As data in that file is saved in the database, the custom cipher
suites configuration is retained upon upgrading and is displayed in the Selected list under the
checkbox in the user interface. The sslciphersuites.xml file is no longer used.
6. Click Save.
7. Select the Personal certificates tab and click Add a certificate to open the certificate wizard.
You can add a self-signed or a CA certificate. The certificate has a public-private key pair. The
certificate is used to secure connections between browsers and the server.
If you choose to add a self-signed certificate, you can accept all default values in the certificate
wizard.
The steps for adding a server certificate are the same as adding a certificate for a community
profile. See Add a certificate on page 792 for more information.
After adding the certificate, the General tab displays again.
8. Select the Personal certificates tab again. The certificate you added in step 7 is listed. You can
click the certificate's name to display details.
9. If there is more than one certificate, select the certificate you want as the default and click
Save.
10. On the General tab, check again that the UI connections made via HTTPS is selected.
l Restart the server. If you operate multiple computers in a cluster, restart all servers.
or
l Restart all nodes and the user interface. Go to the System management page and click Stop
all nodes. On the Stop all nodes page, click Restart all nodes and Yes, include the
user interface. Click Stop/restart. Note that restarting the user interface ends your
browser session.
13. Inform users of the URL needed to connect from a browser to the user interface. If you use the
suggested port, 6443, the URL is https://<host>:6443/ui where <host> is the fully
qualified domain name or IP address of the computer running the server.
If you change the configuration, click Save. You also must do one of the following:
l Restart the server. If you operate multiple computers in a cluster, restart all servers.
or
l Restart all nodes and the user interface. Go to the System management page and click Stop all
nodes. On the Stop all nodes page, click Restart all nodes and Yes, include the user
interface. Click Stop/restart. Note that restarting the user interface ends your browser
session.
Although broad in scope, these practices are intended to avoid worst-case issues that may arise in a
production environment or when upgrading.
1. Back up the installation directory on a regularly scheduled basis. Follow your company's policy
for data backups or make up your own backup schedule. If you store data in one or more
directories other than common\data, back up those, too.
If you use Windows, turn off the server before backing up files. This is recommended because
Windows locks files in use by an application, which prevents files from being copied while
locked. UNIX and Linux systems do not lock files.
2. Back up the external database on a regularly scheduled basis. Schedule database backups to
occur at about the same time as file system backups. For the trading engine, it's important to
synchronize these backups because the database references certificate data in the
common\conf\keys directory.
3. Export the private keys for the encryption, signing, and SSL certificates for each community
profile. Keep the key backups in a secure location.
4. Before upgrading to a new version or service pack, do the following:
a. Turn off the server. All processing must be halted before upgrading.
b. Back up files as described in step 1.
c. Back up the external database as described in step 2.
d. Back up private keys as described in step 3.
Unless data are backed up before upgrading, you cannot revert to the previous version if the
need arises. Even with proper backups, retreating to the state before the upgrade may be
difficult or impossible due to hardware or software issues unique to your network. In the worst
case, you may have to re-install the application and begin anew with a fresh database.
The extent of custom changes depends on the complexity of your configuration. Regardless of the
complexity, the best practice is to document your changes and keep copies of custom scripts or
code files.
Interchange provides a file system directory to help in documenting custom changes. The directory
is <install directory>\site. A readme text file there provides an overview. An advantage of
using the site directory is that upon upgrading to a new version, the contents of the site directory
from the old installation directory tree are copied to the new version as part of the installation
process.
The site directory has subdirectories with the following recommended uses.
l bin – Store copies of your post-processing scripts, other scripts or executable files. Where
possible in the user interface, use a relative path to point to this directory (for example, for a
post-processing script). After upgrading to a new version, you do not have to alter the path in
the UI.
l conf – Store copies of custom configuration files. Your source code should refer to this
directory as ../site/conf.
l doc – Store text documents containing notes about custom changes. These can be notes about
any changes that would be a useful reference for someone performing an upgrade or disaster
recovery.
For example, if you edit the alerts.xml or events.xml file in <install
directory>\conf, document the changes in a text file and save it here. When upgrading, use
the notes to make the same changes to the alerts.xml or events.xml in the new version.
Note that it is not recommended to make backup copies of changed system files for the purpose
of substituting the backed up files for ones in a newly installed application. This is because
system files may have been changed by the software developers between an old and new version
of the application. This is especially true of the filereg.xml file. The filereg.xml file
installed with a new version should always be used.
Custom changes for some values in system files do not require documenting because they are
forwarded during an upgrade by the application installer. This includes the commonPath entry
from filereg.xml.
l JARs – Store Java archive (JAR) files and class files for in-line processors, pluggable transports,
JMS, and custom parsers. Any classes in this directory are included automatically in the classpath
before <install directory>\jars. This includes JAR files; there is no need to explicitly add
them to the classpath.
l webapps – Custom web applications developed by users that are to be deployed upon server
startup.
Interchange can handle very large messages of 2 gigabytes or more. But external factors can limit
the size of messages you can exchange with partners. Such factors can include available disk space
and RAM and network hardware, including computers, routers, load balancers and firewalls. These
factors not only can affect your system, but your partners’.
The following topics are points to consider if you want to trade very large documents.
Disk space
Disk space requirements can become very large because Interchange creates multiple copies of each
message.
The temporary directory, generally located on the local file system, must be large enough to contain
multiple copies of each message. See the Interchange Installation Guide, Temp directory
requirement.
The backup directory, generally located on a network file system when running in a cluster, must be
large enough to hold multiple copies of each message. For example, by default a backup is kept of
both the raw “consumed” file and the “packaged” or “unpackaged” file, depending on whether you
are sending or receiving. These copies may remain in the backup directory for many days,
depending on the purge interval.
The storage associated with the integration pickup and delivery exchanges must be sufficient to
hold one copy of each message that is sent or received.
If you have a firewall between Interchange and the database and you trade large messages that
request synchronous AS2 receipts, you must do one of the following to avoid database errors while
waiting for synchronous receipts:
l Change your firewall idle time-out to allow connections between Interchange and the database
to remain open and idle for at least as long as it takes for the synchronous receipt to be returned.
This applies to inbound and outbound messages. The amount of time to allocate depends on
the size of the largest message and the load on your trading engine, as well as your partners’
trading engines. This easily could be hours for multi-gigabyte messages that are signed and
encrypted.
or
l Change your collaboration settings to request asynchronous AS2 receipts. You must ask your
partners to do this as well.
Considerations by transport
Certain transports have special considerations for large messages. Check with your vendor regarding
considerations for third-party transports such as JMS providers.
The following considerations apply for transport clients and servers embedded in Interchange.
HTTP chunking
Sending a message larger than 2 gigabytes can result in problems if chunking is not enabled. For
this reason, when Interchange sends a message larger than 2 gigabytes, it automatically enables
chunking for that message, even if chunking is disabled for the partner’s HTTP delivery exchange.
Virtually all modern HTTP/1.1-compliant servers support chunking, including the embedded server
used by Interchange. But if a partner’s server does not support chunking, and you need to trade
messages larger than 2 gigabytes, your partner must upgrade his server.
AS2 receipts
You should request asynchronous receipts from partners if you are trading messages larger than a
few megabytes. Failure to do so could result in response time-outs on the client or server or idle
time-outs in firewalls or gateways in the connection chain. This is due to the potentially long period
in which the connection may appear idle while the server is unpacking the message until it can
return the synchronous receipt. Problems related to timed-out connections can be difficult and
time-consuming to diagnose. If you know beforehand about trading even one large message,
change your AS2 collaboration settings to request asynchronous receipts before you have problems.
See Manage default collaboration settings on page 910.
In previous versions the response time-out was fixed at 30 minutes on the server side. On the client
side it could be adjusted manually on the Advanced tab for the delivery exchange, but only to a
fixed value that was not suitable for both large and small messages.
This change allows trading large messages that request synchronous receipts to be more reliable.
Nevertheless, you are strongly encouraged to request asynchronous receipts to avoid potential time
outs in external network components that are beyond your control.
Your partner also must make similar adjustments to receive large messages from you.
With multi-gigabyte messages, the time required to return a synchronous receipt could be hours or
days, depending on factors such as the speed of the hardware and system load. Even when
requesting asynchronous receipts, the message must be copied to the backup directory before the
HTTP response can be returned. If the backup directory is on the network, this could take several
minutes. Contact your firewall administrator to ensure the time-out is set appropriately based on the
types of receipts being requested and the size of the messages.
l Add a trading engine node on page 54
l View and manage nodes on page 54
l Configure UI connection on page 56
l Configure server IP binding on page 59
l Configure global transport settings on page 60
l Configure the global external SMTP server on page 60
l Generate cluster thread dumps on page 61
l Manage the system throttle on page 62
l See also Data storage, backups, and purging on page 849
You can also perform a variety of system management tasks to develop the health, security, and
connectivity of your production environment.
The System Management page is arranged in a set of tabs and a list of Related Tasks.
Tabs
l Cluster nodes tab
l DMZ nodes tab
l DMZ zones tab
l X.25/B-ISBN routers tab
The following topics provide information and procedures for working in the Cluster nodes tab:
l View and manage nodes on page 54
l Configuration outline for X.25 on page 634
l Add or edit an X.25/B-ISDN router on page 635
l Certificates search results page on page 783
l Manage certificate revocation lists (CRLs) on page 802
l Configure TSL retrieval on page 616
l Configure the global external SMTP server on page 60
l Manage default search settings on page 843
l Configure global transport settings on page 60
l Embedded transport servers on page 431
l Manage password policies of transport users on page 129
l Message metadata and attributes on page 412
l Message attributes templates on page 424
l Monitor file system health on page 1085
l Manage IP address whitelists on page 490
l Configure server IP binding on page 59
l Configure UI connection on page 56
l Generate cluster thread dumps on page 61
l Manage the system throttle on page 62
Node status
The System management page, Node tab displays a status for each node. Trading engine nodes can
have one of the following statuses:
l Not running
l Starting
l Running
l The trading engine stops.
l The new status of the engine is displayed in the node status column.
Users can also use the restart command to manually resume message consumption if the system was
intentionally started in the throttled state.
Pause consumption
Interchange consumes messages through application and trading pickups. To pause message
consumption, on the System management page click Pause pickups for all trading engine
nodes.
When you select this option:
l Trading pickups and application pickups on all cluster nodes stop polling and consuming
messages.
l The Mode column for the trading engine node displays Pickups paused.
l The pause command changes to Restart pickups for all trading engine nodes.
l Interchange continues to process all messages that have already been consumed.
l Retries of failed messages continue.
Resume consumption
To resume message consumption, click Restart pickups for all trading engine nodes.
Configure UI connection
Use the Configure UI connection page to specify how browsers can connect to the Interchange user
interface. Browser connections can be via HTTP, HTTPS or both.
To open the Configure UI connection page, go to the System management page and click the
Configure UI connection link in the Related tasks list.
Axway Interchange HTTP UI connections are typically made through port 6080. HTTPS connections
are typically made using port 6443. You can modify the ports required for both HTTP and HTTP/S
access.
If you select to use HTTPS, you must add a server certificate as described in the procedure below.
You have options to:
l Use a self-signed or CA certificate
l Import a certificate and private key from a file
l Retrieve a certificate from a certificate authority
This certificate secures the connection between browsers and the server. If you select HTTPS and
require client authentication, you must add the client's trusted root certificate.
Configure HTTPS
Use this procedure to configure the server so browsers can log on to the user interface via HTTPS.
1. Click System management on the toolbar to open the System management page.
2. Click the task Configure UI connection near the bottom of the page to open the Configure
UI connection page.
When you are open this page for the first time, connections via HTTP is configured by default.
You can accept the default or add configuration for connecting via HTTPS. You cannot disable
connections via HTTP until you have configured HTTPS. Once HTTPS has been configured, you
can return to this page and select to have browsers connect via HTTP or HTTPS, or both.
3. On the General tab, select UI connections made via HTTPS. Port 6443 is displayed by
default, however you can change the number as your situation requires.
4. Optionally, select the Override SSL and TLS cipher suites option for overriding a cipher
suite.
Select this option, and use the Add and Remove buttons to specific the cipher suites that are
supported for the embedded server. If none are selected, all cipher suites are supported by
default. The default is less secure than specifying only certain cipher suites.
The default order in the Available column is the preferred order of use. Once ciphers are
moved to the Selected column, you can arrange the order. Interchange uses the ciphers in the
order they are listed.
Of the many algorithms for encrypting data and computing the message authentication code,
there are varying levels of security. Some provide the highest levels of security, but require a
large amount of computation for encryption and decryption. Others are less secure, but provide
rapid encryption and decryption. The length of the key used for encryption affects the level of
security. The longer the key, the more secure the data.
The option for overriding cipher suites enables you to select the level of security that suits your
needs and enables communicating with others who might have different security requirements.
For example, when an SSL connection is established, the client and server exchange
information about the cipher suites they have in common. Then they communicate using the
common cipher suite that offers the highest level of security. If they do not have a cipher suite
in common, secure communication is not possible.
In versions of Interchange earlier than 5.9, cipher suite configuration was handled by a file
named sslciphersuites.xml. As data in that file is saved in the database, the custom cipher
suite configuration is retained upon upgrading and is displayed in the Selected list under the
check box in the user interface. The sslciphersuites.xml file is no longer used.
5. If you want port forwarding for the user interface, select the DMZ ports tab. Select to enable
port forwarding for HTTP or HTTPS or both. See Secure Relay DMZ nodes on page 474 for
information about port forwarding.
This option is available only if your software license supports the DMZ nodes functionality.
6. Click Save.
7. Select the Personal certificates tab and click Add a certificate to open the certificate
wizard.
You can add a self-signed or a CA certificate. The certificate has a public-private key pair. The
certificate is used to secure connections between browsers and the server.
If you choose to add a self-signed certificate, you can accept all default values in the certificate
wizard.
The steps for adding a server certificate are the same as adding a certificate for a community.
See Add a certificate on page 792 for more information.
After you add a certificate, the General tab displays again.
8. Select the Personal certificates tab again. The certificate you added in an earlier step is
listed. You can click the certificate’s name to display details.
9. If there is more than one certificate, select the certificate you want as the default and click
Save.
10. On the General tab, check again that UI connections made via HTTPS is selected.
11. If you are configuring HTTPS and selected Require client authentication, select the
Trusted roots certificates tab and add a trusted root certificate.
With this option, the server requires the user's browser to send a certificate back to the HTTPS
server. The HTTPS server must trust the certificate returned by the browser client. If a browser
user has a CA-issued certificate for authentication, you must at least trust the root CA
certificates. If a browser user has a self-signed certificate, the user must export the certificate
and public key to a file and give you the file. You then must import the certificate file.
12. To complete the configuration you must do one of the following:
l Restart the server. If you operate multiple computers in a cluster, restart all servers.
or
l Restart all nodes and the user interface. Go to the System management page and click Stop
all nodes. On the Stop all nodes page, click Restart all nodes and Yes, include the
user interface. Click Stop/restart. Note that restarting the user interface ends your
browser session.
13. Inform users of the URL needed to connect from a browser to the user interface. If you use the
suggested port of 6443, the URL is:
https://<host>:6443/ui
where <host> is the fully qualified domain name or IP address of the computer running the
server.
If you change the configuration, click Save. You also must do one of the following:
l Restart the server. If you operate multiple computers in a cluster, restart all servers.
or
l Restart all nodes and the user interface. Go to the System management page and click Stop all
nodes. On the Stop all nodes page, click Restart all nodes and Yes, include the user
interface. Click Stop/restart. Note that restarting the user interface ends your browser
session.
By default, all of the trading engine internal socket servers (for example, HTTP, SMTP) are bound to
all network interfaces of the computer used as the application server, or computers used as servers if
a clustered environment. This allows clients to connect to the servers on any of the IP addresses
associated with the network interfaces in a given machine. For example, if a machine has two
network interfaces having IP addresses 10.10.1.1 and 10.10.1.2, the HTTP server for the user
interface would be available on both IP addresses at the default port of 6080. The same would apply
to the HTTP server for trading (if configured), but at the default port of 4080. Note that all servers
also would be available on the loop-back interface, 127.0.0.1, as well (if available). For the majority
of users, the default behavior of binding to all available IP addresses is satisfactory.
The other option is to bind only to the IP address of the application server identified by the CYC_
NETWORK_NAME property. This property is in the <machine_name>_environment file, or files if a
clustered environment. The file is in <interchange_install directory>\bin.
To bind only to CYC_NETWORK_NAME, go to the System management page in the user interface and
click Configure server IP binding. Select the CYC_NETWORK_NAME option and click Save
changes. Restart the server for the change to take effect.
There is a command-line tool in the application’s tools directory named netInfo that you can use to
identify the network interfaces on the application server. Note that it may report more than one IP
address per network interface, depending on how your network is configured. The tool also reports
the value of CYC_NETWORK_NAME. Run the script without parameters from the tools directory.
l FTP
l SFTP
l cXML over HTTP
l Web Services
For information about the settings you can control for each of these transports, see:
l Lockout settings for FTP (embedded) server users on page 452
l Lockout settings for SFTP (embedded) users on page 458
l Lockout settings for cXML (embedded HTTP) users on page 439
l Lockout settings for Web Services (HTTP embedded) users on page 731
When you click the link, a dialog box offers you three options:
l Open – Open a window displaying thread dump information
l Save – Save the thread dump information to a file
l Cancel – Abandon the action
The system throttle can be engaged for different reasons:
l Intentionally engaged at startup (via tuning.properties file setting).
l Intentionally engaged during runtime (via a UI control button).
l The trading engine Task Scheduler load exceeds the default limit of 150.
l The JVM (trading engine or control node) experiences an OutOfMemory exception.
l The file system takes too long to write a test file to the backup directory. In rare instances, Java
Garbage Collection by the control node or trading engine node can require so much time to
complete that the timer for the file system health check (when invoked just prior to the onset of
a Garbage Collection event) exceeds the 15 second default limit, due to activity suspension until
the Garbage Collection completes).
When a system throttle is engaged, consumption of new inbound work is halted. The trading engine
stops polling and returns a 503 error to your trading partners when they try to connect.
Interchange then re-prioritizes all traffic based upon these rules:
l New outbound files are consumed, packaged, and sent before any other work
l Inbound connections are then opened and inbound messages are processed.
l Failed outbound/inbound messages are then processed.
When the system throttle is invoked you may receive a log entry similar to the following
(TaskScheduler load example):
You manage general system throttle settings from the tuning.properties file. These settings are
described in the following paragraphs. Additionally, you can manually engage/disengage system
throttling at runtime in the UI. .
The properties in this file are applied only to the node where the tuning.properties file is
located. You must set the property for each node of a cluster by modifying the file for each node.
By default, tuning.properties is empty. This indicates that all of its possible entries are
operating at their default values.
This chapter describes how to use the two properties related to system throttling that you can set in
this file:
l systemThrottle.pausePickups – Default=false
l systemThrottle.maximumTaskQueueSize – Default=150
To to force startup in throttled mode:
1. Go to <install_directory>/conf and open the tuning.properties file in a text editor.
2. Add the property:
systemThrottle.pausePickups
3. Set the value of the property to "true":
systemThrottle.pausePickups=true
4. Save the file.
5. Restart Interchange.
When the system restarts, it will operate in throttled mode. This status will be displayed for trading
engine notes on the System Management page of the UI. You can temporarily override throttling by
clicking Restart pickups for all trading engine nodes. When you restart Interchange, it will
restart in throttled mode until you modify this property.
We recommend that you change this property value in increments of 25.
To change the Task Scheduler load limit:
1. Go to <install_directory>/conf and open the tuning.properties file in a text editor.
2. Add the property:
systemThrottle.maximumTaskQueueSize
3. Set the value of the property to the desired value, for example:
systemThrottle.maximumTaskQueueSize=175
4. Save the file.
5. Restart Interchange.
When the system restarts, it will engage throttling at the new load limit threshold.
This icon on the user interface toolbar indicates that your user license supports the features:
Related topics
l Peer network overview on page 66
l Peer network business use cases on page 71
l Compare peer network and trading network objects on page 76
l Configure a peer network on page 77
l Peer network settings on page 78
l Peer rules on page 80
l Peer network cloning restrictions on page 85
l Manually clone an application delivery on page 86
l Manually clone an application pickup on page 87
l Manually clone a partner on page 87
l Manually clone a trading pickup on page 88
l Manually clone CPAs on page 89
l Manage duplicate messages in peer network on page 89
l Log peer network debug events on page 90
l Track peer messages on page 91
Peers are communities and partners that are linked in a network for the purpose of sharing
synchronized trading partner configurations. The messages that peers exchange with each other are
related only to the peer network. Trading communities and trading partners separately carry on the
usual e-commerce traffic. Peer communities and partners are distinct from trading communities and
partners, although peer and trading objects have many similarities. (See Compare peer network and
trading network objects on page 76.)
The MIME envelope for peer messages has the following special content MIME type:
application/x-cyclone-peer-to-peer. If you use a non-default protocol, you must add this
peer message content MIME type as a message attribute. Non-default protocols may require
additional configuration. Contact Axway for additional information and help with special setup
requirements.
l AS1 (email)
l AS2 (HTTP)
l AS3 (FTP, SFTP)
l AS4 (HTTP)
l ebXML (HTTP, SMTP)
l Generic email (SMTP, POP)
l No packaging (FTP, SFTP, File system, JMS, MQ, WebDav, MLLP)
l Odette FTP V1 (HTTP)
l Odette FTP V2 (HTTP)
l PeSIT
l PGP (FTP, SFTP)
l RosettaNet 1.1 ( HTTP)
l RosettaNet 2.0 ( HTTP)
l Secure file (HTTP, FTP, SFTP, File system, JMS, MQ, WebDav)
l Partner
o Routing ID
o Messaging ID
o Contacts
o Certificate
o Properties
o Trading deliveries
l Application pickup
o Transport protocol settings
l Application delivery
o Delivery settings
o Transport settings
l Trading pickup
o Transport protocol settings
l CPA
o (no dependent objects)
l cXML
l X400
l WebTrader
l Web Services
l AS4
l MQ trading and application pickups in server mode are not supported (only client mode is
supported)
l Pluggable transports and servers
The polling features of transport protocols are not supported for peer cloning.
Example architectures
The following figure shows an example of three trading engine clusters joined in a peer network.
The clusters are all under the control of a single company or enterprise. The peer network could be
connected through the Internet, a LAN or a WAN.
The preceding figure illustrates the inherent flexibility of the peer network and Interchange. Each
cluster is a different size and runs on a different operating system. Each cluster has its own database,
and each database can be a different type. Geographically, peer clusters can be located in the same
building or on different continents.
The messages exchanged in the peer network are called peer messages. There are two types of peer
messages:
l Trading partner configuration messages
l Ping messages
Peer messages are written in XML. A peer message consists of two parts:
l Content –The actual ping message or trading partner description.
l History – Used by the peer network to make sure peer messages are not replicated redundantly
across the network.
The MIME envelope for peer messages has the following special content MIME type:
application/x-cyclone-peer-to-peer. If you use the "No packaging" or "File system" transports,
you must add the peer message content MIME type of application/x-cyclone-peer-to-peer as a
message attribute.
Each cluster or Interchange instance is represented by a single peer community. Just as a trading
community shares its profile with trading partners, the peer community shares its peer profile with
the other peers in the network. The view from within each peer is a single peer community, with
peer network partners represented by imported peer partner profiles. The following figure illustrates
the peer community and peer partner relationship in a peer network.
Note that the Internet traffic illustrated in the previous two figures represents only the peer messages
exchanged between peer clusters and not e-commerce traffic. Peer messages can consist largely of
ping messages exchanged at regular intervals among peers to determine whether peer partners are
active. Depending on the configuration, trading partners also are exchanged across the peer
network. Each time a trading partner is updated on one instance of the trading engine, the changes
can be broadcast to all peers or only to selected peers.
When trading partners are synchronized across the peer network, this enables multiple clusters of
trading engines to act together as a single large cluster for trading purposes. The following figure
illustrates this type of scaled-up trading network enabled by the peer network. In this example all
message traffic is e-commerce traffic.
While in the previous figure it is possible for both peer clusters to exchange e-commerce messages
with all trading partners, note that only one cluster communicates with one trading partner at a
time. While trading partners can be replicated across the peer cluster, trading messages are not. The
database for each cluster contains trading message records only for its own cluster, not also for
another peer cluster. In the previous figure, if peer cluster B went down, and if both clusters had a
common back-end system, peer cluster A would process all messages for all trading partners until
cluster B came back up. The peer network has intelligence to make sure that when cluster A sends a
business message to a trading partner, the partner’s response acknowledging receipt of the message
is returned to cluster A and not another cluster.
Disaster recovery
By setting up multiple peer instances of Interchange — ideally located at different physical sites —
trading partners can be continuously replicated to a hot-backup instance of the trading engine.
Swapping between the production and backup instances is handled outside of Interchange by way
of network routing configured by the peer network user. For example, given an external URL such as
http://edi.myco.com/exchange/myco, the network could be set up to route requests for
edi.myco.com internally to IP address 10.10.1.1 if the production instance is active or to
10.10.1.2 if the backup instance is active.
Production and backup peers:
Staging environment
The peer network enables you to provide a staging environment for trading communities to perform
test trading with new partners before the partner profiles are promoted to the production trading
environment.
In this use case, a staging instance of Interchange is set up as a peer of the production instance. The
staging peer may have different application and trading exchanges than the production peer.
The following are possible steps for promoting a trading partner from the staging peer to the
production peer:
1. Set up or import the new partner profile on the staging peer.
2. Export the staging peer's trading community profile and send it to the new partner, who
imports the profile as a partner profile on the partner's system.
3. Perform test trading as needed between the staging peer and the new trading partner's system.
4. At promotion time, use the Clone trading partners wizard in the staging peer to send the trading
partner's profile to the production peer.
5. Export the production peer's trading community profile and send it to the new partner, who
imports the profile as a partner profile on the partner's system. If the production partner uses
the same name or routing ID as the staging profile, tell the partner to select the "replace" option
during import.
The following figure shows the relationship between a single staging peer and a single production
peer. Note that only the staging peer sends trading partner definitions, and only does so manually
using the cloning wizard.
A staging environment could be compromised of multiple tiers (development, staging, production).
The following figure shows a case with several staging peers and one production peer. In this
example, new trading partners are promoted manually in phases until finally promoted to the
production peer:
The following figure shows the relationship in a peer network with multiple staging peers and
multiple production peers:
Peers could be physically located at the same site or different sites. Moreover, each peer could have
a different back-end integration system. Alternatively, the same could be achieved by configuring
the network with symbolic host and file system path names that map to different physical resources
for each peer.
In a global enterprise case, peers can be widely dispersed geographically. For a global enterprise, as
well as for the large-scale case, a peer network offers:
l Redundancy.
l Support for heterogeneous environments in which peers run on different operating systems
(UNIX, Linux, Windows) and have different databases (Oracle, SQL Server, DB2, MySQL).
l Ability for each peer to have different integration exchanges for efficiently interfacing with local
back-end systems.
The peer network is resistant to catastrophic failures at individual sites because physical hardware,
processing capacity, and configuration information are duplicated across multiple sites. However, if
all nodes for one peer fail, some messages in-flight at that moment could be delayed until that peer
is restarted. This is due to the loosely coupled nature of the peer network. In comparison, no in-
flight messages are affected when a cluster node fails within a given Interchange instance.
The following figure shows an example of a large-scale or global peer network. Staging, backup and
production peers are part of the network example. Notice how a peer’s role dictates whether trading
partners flow automatically or manually.
The following figure shows an upgrading case between two production peer clusters. Normally,
both peers would auto-clone trading partners to each other. During an upgrade, however, auto-
cloning is turned off. Peer 1 suspends production trading and installs the upgraded software. Peer 2
continues operating as a production system. This presumes that a load balancer, if used, is re-
directing all trading traffic to peer 2. After a period of testing on peer 1, peer 2 manually clones any
changed or new trading partners to peer 1. Peer 2 suspends production, and peer 1 goes back into
production. Peer 2 installs the upgrade. Following testing on peer 2, peer 1 manually clones any
changed or new trading partners to peer 2. Finally, both upgraded peers turn auto-cloning back on
and resume production.
However, there are important differences between peer networks and regular trading networks. For
instance, there can be only one peer community per Interchange instance or cluster. Apart from that
difference, you set up and maintain the peer community in much the same way as a normal trading
community. Peer partners and normal trading partners are similar to each other as well.
It is important to understand the differences between peer objects and normal trading objects. Peer
communities and partners are used only by the peer network to communicate messages among
peers. Such messages are system-generated; the peer network does not pick up messages from
back-end applications. Peer communities and partners are never used for exchanging e-commerce
messages among parties. That role is handled exclusively by trading partners and trading
communities.
Peer partners and communities must have unique names and routing IDs, just like trading partners
and communities. Because these peer and trading objects are similar, the peer network forces a
prefix of “Peer-” for each peer partner and community name to distinguish them from trading
partner and community objects. Moreover, the Interchange user interface keeps peer
partner/community and trading partner/community objects separate. Peer partners and
communities can be accessed only through the Peer network menu on the top toolbar. Trading
objects can be accessed through the Trading configuration and Partners menus on the toolbar.
You can export a peer community to a profile with its certificate and public key, just as you can a
trading partner or community. After exporting to a profile, you give the profile to a peer network
manager to import in a similar way, however Interchange recognizes it as a peer partner profile, not
a trading partner profile.
When you manually add a peer community, you do not have to set up an application pickup
exchange for it. A peer community does not pick up messages from back-end applications.
However, when you add a peer community, the trading engine automatically sets up an application
delivery exchange. This is a file system delivery with a default path of <install
directory>\common\data\peerNetwork\in. You can optionally configure Interchange to
write inbound peer messages to this directory.
1. All instances of Interchange must use Interchange 5.8 or later.
If the ebXML message protocol is used for exchanging messages with trading partners, all
instances must be Interchange 5.8 or later. Note that ebXML can be used for peer-to-peer
communications, but a protocol with less overhead, such as AS2, is recommended.
2. Follow the usual procedure for installing, configuring and, if applicable, setting up multiple-
node clusters. See the appropriate sections of the documentation for details. Make sure each
instance of Interchange is operating properly before proceeding with the peer network
configuration.
3. If you plan on using the peer network to link instances of the trading engine that are actively
trading, see Manage duplicate messages in peer network on page 89.
4. Log on to the user interface and click Peer network > Manage peer network on the
toolbar to open the Peer network page.
5. Click Create the peer community to launch the Add Community Wizard. Follow the prompts
to add a peer community profile.
When you add a peer community, the system includes the following in the profile:
l An AS2 pickup for receiving messages from peer partners. This exchange is added as a
convenience, because most peer partners choose AS2 for exchanging peer messages. If you
want to use a different message protocol, edit the peer community.
l A file system application delivery. This is added in case you want to route messages received
from peer partners to the file system for debugging. It is not used unless you explicitly
configure this behavior under peer network settings.
Repeat this step for each Interchange instance.
6. Export the peer community profile. Repeat this step for each Interchange instance.
7. Distribute the peer profiles among the Interchange instances or clusters. For example, if there
are three instances, distribute as follows:
l Peer community A gives exported profile file to peers B and C.
l Peer community B gives exported profile file to peers A and C.
l Peer community C gives exported profile file to peers A and B.
8. For each Interchange instance, import the peer partner profiles. For example, if there are three
instances, import as follows:
l Peer community A imports peer partner profiles B and C.
l Peer community B imports peer partner profiles A and C.
l Peer community C imports peer partner profiles A and B.
On the peer network page, click Add a peer partner.
General setting
Enable the peer network
Select this option to activate the peer community online and make it available to peer
partners. When enabled, trading partner profiles can be sent or received, either through
auto-cloning or manually, depending on the trading partner profile sharing settings.
There may be times when you want to disable the peer network temporarily. For example,
to make changes to trading partner profiles that you do not want cloned to peer partners.
As long as the peer network is disabled, no changes are cloned, even to peers for whom the
auto-clone rule is enabled.
Pings tab
Send pings
If you select this option, the peer community sends ping messages to peer partners at the
specified interval. Sending pings at regular intervals helps all peers to be aware
continuously of the operational status of other peers in the network.
The pings settings apply globally for all peers. If you enable pings for one peer, all peers
are directed to send and receive pings. If pings are enabled, the other settings also apply to
all peers. Any change to the ping configuration for one peer affects all peers.
The Peer network page has columns for the peer community and peer partners to display
the status of the last pings sent or received.
A ping message is an application/x-cyclone-peer-to-peer message with content that
identifies it as a ping message. A ping message is not encrypted or signed.
Ping interval
The time in minutes between ping broadcasts.
Time in hours to retain ping history. Ping history events are displayed on the Peer network
page.
Ping tolerance
Number of minutes within which a peer partner must respond to a ping. If a partner fails to
respond within the tolerance limit, a late warning is displayed for the partner in the "Peer
partners" section on the Peer network page.
Advanced tab
Use these options to choose whether to write inbound ping messages or other inbound peer
messages to a back-end application. Interchange provides a default file system application delivery
for sending inbound peer messages to a back-end folder. Writing peer messages to the back-end
may be helpful in troubleshooting or for auditing purposes.
Write only inbound ping messages to a back-end file system folder.
Write other inbound peer messages to a back-end file system folder.
Peer message folder maintenance: Peer messages are small, so do not rapidly create disk
space issues. If you select this option, it is a good practice to apply the same global purge
and backup configuration settings as for trading engine messages.
Peer rules
Use the Peer partner rules page to control how an individual peer partner exchanges information
with other peers. Each peer partner that you create has a dedicated Peer partner rules page.
To open the Peer partner rules page, click Rules to the right of a partner listed in the "Peer partners"
section on the Peer network page.
Partner tab
Accept trading partner additions, changes and deletions from the peer
partner
Enables the remote peer community to accept trading partners sent by this peer partner. In
most cases, you should select this option.
If this option is turned off, you cannot automatically or manually send any additions or
changes to this peer partner.
Enables trading partners o n the peer community instance to be sent to this peer partner
each time a trading partner has been added or changed. The peer partner also is notified
when trading community membership for a trading partner is changed.
If a trading partner is deleted from the peer community instance, this peer partner is
notified to also delete the trading partner. In the case of ebXML, the trading partner and
the related CPA are deleted.
l In the add trading partner wizard when you create a trading partner
l Under Properties in the trading partner summary page after you create the trading
partner
For trading partners configured to use the RosettaNet message protocol, clear the Allow
this partner to be cloned to peers option. RosettaNet partners should not be
distributed via auto-cloning.
Relay to the peer partner any trading partner additions, changes, and
deletions received from other peers
When this option and auto-clone are selected, the peer community instance forwards any
trading partners received from this peer partner to other peer partners for whom auto-
cloning is active. Select this rule unless you have a specific reason not to relay. Relaying
does not result in the same trading partner crisscrossing the peer network multiple times.
This is because each peer message that contains a trading partner includes a history of
where the partner has been sent and received. The peer network does not forward a trading
partner when the history indicates other peer partners have received it already.
Caution If you do not enable auto-cloning and instead prefer to use the trading partner cloning
wizard, you need to manually track new and changed trading partners. See Manually clone
a partner on page 87. This is especially the case if you re-name a trading partner and use
the wizard to distribute the updated object. From a peer partner’s perspective, the updated
trading partner seems new, but will have a routing ID that duplicates a current trading
partner. With auto-cloning enabled, the system keeps track of new and changed trading
partners, including trading partner name changes.
Enables the peer community to accept application deliveries sent by this peer partner.
In most cases, you should select this option. Clear this option only if you want to be
absolutely sure that the peer community does not accept application deliveries from this
peer partner.
Enables application deliveries on the peer community instance to be sent to this peer
partner each time an application delivery has been added or changed. If an application
delivery is deleted from the peer community instance, this peer partner is notified to also
delete the application delivery.
Relay to the peer partner any application delivery additions, changes and
deletions received from other peers
When this option and auto-clone are selected, the peer community instance forwards any
trading community application deliveries received from this peer partner to other peer
partners for whom auto-cloning is active.
Select this rule unless you have a specific reason not to relay. Relaying does not result in
the same application delivery crisscrossing the peer network multiple times. This is because
each peer message that contains an application delivery includes a history of where the
delivery has been sent and received. The peer network does not forward a delivery when
the history indicates other peer partners have received it already.
Enables the peer community to accept application pickups sent by this peer partner.
In most cases, you should select this option. Clear this option only if you want to be
absolutely sure that the peer community does not accept application pickups from this
peer partner.
Enables application pickups on the peer community instance to be sent to this peer partner
each time an application pickup has been added or changed. If an application pickup is
deleted from the peer community instance, this peer partner is notified to also delete the
application pickup.
Relay to the peer partner any application pickup additions, changes and
deletions received from other peers
When this option and auto-clone are selected, the peer community instance forwards any
trading community application pickups received from this peer partner to other peer
partners for whom auto-cloning is active.
Select this rule unless you have a specific reason not to relay. Relaying does not result in
the same application pickup crisscrossing the peer network multiple times. This is because
each peer message that contains an application pickup includes a history of where the
pickup has been sent and received. The peer network does not forward a pickup when the
history indicates other peer partners have received it already.
Enables the peer community to accept trading pickups sent by this peer partner.
In most cases, you should select this option. Clear this option only if you want to be
absolutely sure that the peer community does not accept trading pickups from this peer
partner.
Enables trading pickups on the peer community instance to be sent to this peer partner
each time a trading pickup has been added or changed. If a trading pickup is deleted from
the peer community instance, this peer partner is notified to also delete the trading pickup.
Relay to the peer partner any trading pickup additions, changes and
deletions received from other peers
When this option and auto-clone are selected, the peer community instance forwards any
trading community trading pickups received from this peer partner to other peer partners
for whom auto-cloning is active.
Select this rule unless you have a specific reason not to relay. Relaying does not result in
the same trading pickup crisscrossing the peer network multiple times. This is because each
peer message that contains a trading pickup includes a history of where the pickup has
been sent and received. The peer network does not forward a pickup when the history
indicates other peer partners have received it already.
CPAs tab
The rules on this tab apply only for peers that have ebXML trading configurations. The CPAs
exchanged are related to e-commerce message traffic. These are not CPAs used by the peer network
itself to exchange messages between peers.
Accept CPA additions, changes and deletions from the peer partner
Enables the peer community to accept CPAs sent by this peer partner.
In most cases, you should select this option. Clear this option only if you want to be
absolutely sure that the peer community does not accept CPAs from this peer partner.
Enables CPAs on the peer community instance to be sent to this peer partner each time a
CPA has been added or changed. If a CPA is deleted from the peer community instance,
this peer partner is notified to also delete the CPA.
When auto-cloning is turned off, keep track of the CPAs that have been changed or added
in order to manually clone the proper CPAs to other peers. See Manually clone CPAs on
page 89.
Relay to the peer partner any CPA additions, changes and deletions
received from other peers
When this option and auto-clone are selected, the peer community instance forwards any
CPAs received from this peer partner to other peer partners for whom auto-cloning is
active.
Select this rule unless you have a specific reason not to relay. Relaying does not result in
the same CPA crisscrossing the peer network multiple times. This is because each peer
message that contains a CPA includes a history of where the CPA has been sent and
received. The peer network does not forward a CPA when the history indicates other peer
partners have received it already.
Global attributes
The peer networking feature does not clone certain global attributes to remote peer
partners. Instead, the settings must be manually configured on the remote peer partner
server. This ensures each peer partner remains synchronized within the peer network and
allows for successful trading. The following are settings and attributes that are not cloned
and must be manually configured:
l Global embedded servers (for any applicable transport)
l Global external SMTP server (any protocol that has SMTP as a transport)
l Global transport settings (for protocols):
o FTP
o SFTP
l Message attributes templates
l IP address whitelist
If auto-cloning is turned off and objects are deleted on the peer network main server that
was previously cloned to a peer partner, these objects are not deleted when a manual clone
occurs on the main server. These objects include CPAs, trading pickups, and trading
partners.
To delete these objects and remain synchronized with all of the peers in the network, you
must manually log in to each peer partner server and remove or delete the same objects.
Note: Application pickups and deliveries are dropped and rebuilt on peers when cloned.
All generated SSL certificates for any applicable transport are not cloned to the peer partner
server. The administrator must manually import the SSL certificate to ensure successful
trading and synchronization between peer partners.
All asynchronous AS2 MDNs (returned receipts) are correctly recognized in a peer network
environment if the message is returned on a trading engine different from the original
request. This is so that the original transfer of the message is correctly returned.
PeSIT trading pickups can have multiple routing IDs, but the additional routing IDs are not
cloned. PeSIT routing IDs must be manually added to each peer partner.
Peer Network auto-cloning will not occur for the objects you import through the system
import feature.
Workaround : After you execute a system import and restart the trading engine, if you have
Peer Network auto-cloning configured, you can force peer cloning by re-saving the objects
that you want to clone.
To clone application deliveries, you select communities that contain delivery settings that reference
one or more application deliveries. Although you select communities, it is the application deliveries
that the communities reference that are cloned, not the communities.
For example:
l community_A has application delivery settings that reference application_delivery_X and
application_delivery_Y
l community_B has delivery settings that reference application_delivery_Z
If you select only community_A, application_delivery_X and application_delivery_Y
are cloned.
If you select only community_B, application_delivery_Z is cloned.
If you select both community_A and community_B, application_delivery_X, application_
delivery_Y, and application_delivery_Z are cloned.
Note that when you manually clone application deliveries, you can choose the application deliveries
to clone by selecting the community that references them. When you automatically clone (by using
the auto-clone option of the peer rules page), you cannot selectively clone. When auto-cloning is
selected, you clone every application delivery that has been added, changed and deleted.
You cannot use the clone wizard to direct a peer partner to delete an application delivery. That is an
advantage of the auto-clone control that the clone wizard does not have.
You cannot use the clone wizard to direct a peer partner to delete an application pickup. That is an
advantage of the auto-clone control that the clone wizard does not have.
Note that when you manually clone partners, you can choose which partners to clone from this list.
When you automatically clone partners (by selecting the partner auto-clone option of the peer rules
page), you cannot selectively clone. When partner auto-cloning is selected, you clone every partner
that has been added, changed, or deleted.
You cannot use the clone wizard to direct a peer partner to delete a trading partner. That is an
advantage of the auto-clone control that the clone wizard does not have.
Use this manual cloning method when you have disabled auto-cloning or when you want to send an
updated trading pickup to a peer partner who has been off line for a time.
Prerequisites
The trading pickup cloning case is a special case, because unlike other exchanges, each trading
pickup belongs to a unique community. In order to clone a trading pickup, the same community
must be configured on the network that is the target of the cloning.
l You have configured a peer network.
l You have created a community and added a trading pickup.
l The community is duplicated on the target network.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
3. Click Trading pickup in the navigation graphic to open the Trading pickups page.
4. From the list of available exchanges, click the name of a trading pickup you want to clone to
open the Change this pickup page.
5. At the bottom of the page, in the "Related tasks" list, click Clone this trading pickup to
open the cloning wizard.
6. From the display list, select the peer partners that are to receive this cloned trading pickup, and
click Finish.
Use the CPA cloning wizard to send new and updated CPAs from a peer community to peer partners.
The wizard is helpful when you have disabled auto-cloning or when you want to send updated CPAs
to a peer partner who has been off line for a time.
You cannot use the clone wizard to direct a peer partner to delete a CPA. That is an advantage of the
auto-clone control that the clone wizard does not have.
You do not need to manage duplicate messages if the peer network is employed only to promote
configurations from a staging environment to a production environment or only as a backup to a
production environment.
Normally Interchange handles duplicate messages effectively on its own. At the business protocol
level, Interchange always checks for duplicate messaging IDs in the headers of packaged inbound
messages. Optionally, Interchange also can be set to detect and reject duplicates after unpacking
inbound messages and checking document content for such things as duplicate EDI control IDs
(see Inbound message validation rules on page 939). But in a peer network, duplicate message
checking is not reliable because only objects are shared between peer databases, not messages.
There are a number of possible solutions. The following describes some of these. Keep in mind these
are general descriptions. You may require the help of a professional services consultant to plan and
implement a solution that works for your peer network.
The router could:
l Remember messaging IDs and always route duplicate messages to the same peer.
or
l Use an algorithm based on information such as the sender IP address or the message ID to
predictably route duplicate messages to the same peer. For example, a scheme based on a hash
of the message ID could route odd numbers to peer 1 and even numbers to peer 2.
log4j.category.com.cyclonecommerce.collaboration.peernetwork=info
The log4j.properties file is at <install directory>\conf. For more information about this
file, see Troubleshooting with the log4j file on page 1095.
When search results from a peer are displayed, dates and times reflect the time zone of the currently
logged on user.
The following describes the Peer Tracker fields on the Message Tracker page. (Also accessible by
selecting Peer network > Track peer messages and clicking Show/Hide.)
Another difference is Peer Tracker does not provide links to payloads and receipts on message
details pages as Message Tracker does, as those documents reside on the peer partner's system.
However, Peer Tracker reports all the same data as Message Tracker.
When search results from a peer are displayed, dates and times reflect the time zone of the currently
logged on user.
Other differences and similarities are listed in the following table.
Attributes pop-up windows on search results pages yes no
Links to community and partner profiles on the message details page yes no
document summary tab.
Links to payloads and receipts on the message details page document yes no
summary tab and message processing details tab.
Add a note on the message details page document summary tab. yes no
Links to certificates on the message details page message processing yes no
details tab.
l Trading engine governance script on page 93
l Tools in bin directory on page 93
l Database configuration tool on page 95
l Document generator on page 97
l Tools in tools directory on page 101
l Check the collaboration and action trees on page 107
Execute the script without parameters to display the options. The parameters are:
l start – Starts Interchange server.
l stop – Stops Interchange server.
l status – Displays whether Interchange server is running.
l restart – Restarts Interchange server.
l start-and-wait – Starts Interchange server. The server status is displayed in the current console
window; a second console window for displaying status is suppressed.
The start and stop parameters duplicate the functionality of stopServer and startServer scripts in the
trading engine bin directory (see Tools in bin directory on page 93). You can use either method. If
your system is Windows, you optionally can run Interchange as a service or manually start the server
on the Start menu.
If you use Windows, the names of these tools have an extension of .cmd (for example,
dbConfig.cmd). If you use UNIX, whether or not the tools have an extension depends on the
specific brand of UNIX or Linux OS (for example, dbConfig or dbConfig.sh).
Depending on whether you use Windows or UNIX, some of these tools may not have been installed
with the application. If a tool changes a value in the database, restart the server for the change to
take effect.
Tool Description
<host>_ Sets the short and long names of the computer running the server. This tool is
environment not for use by end users.
admin Opens the user interface log-on page in a browser.
dbConfig Displays and allows you to change connection settings for an external
database. See Database configuration tool on page 95.
docGen Opens the Document Generator, which can generate test messages for
Interchange. See Document generator on page 97.
environment Sets environment variables that are specific to all nodes running on a
particular computer. This tool is not for use by end users.
executiveStatus Displays the status of Interchange server nodes.
executiveStop Stops the executive and all Interchange nodes. The executive node is a JVM
that is responsible for bootstrapping all other JVMs.
manageNode Enables you to add, remove, start, stop, and restart cluster nodes. Run
manageNode to display instructions for using the tool and a list of available
parameters. Only a user associated with the admin role can use this tool.
netConfig The system uses this utility to identify the short and long names of computers
running Interchange server. See the Interchange Installation Guide,
Computer names and clustering.
nodeInfo Displays information about cluster nodes, machines in a cluster, and node
status. Run nodeInfo to display instructions for using the tool and a list of
available parameters. Only a user associated with the admin role can use this
tool.
startServer Starts the server.
stopServer Stops the server.
systemuser Changes or adds a system user and password. This user is only used by
Interchange. This tool is not for use by end users.
Tool Description
tail Provides live viewing of log files. See Real-time viewing of log files on page
1094.
unlockUser Unlocks a user who is blocked from logging on to the user interface after
exhausting the number of log-on retries. See Unlock a blocked user on page
128.
Use dbConfig to:
l Change from one database to another
l Change or correct a parameter such as database name or password
l Test the database connection (GUI only)
The database password is encrypted in datastoreconfig.xml, so you must use the tool to
change the password. You cannot edit datastoreconfig.xml to change the password.
Warning: The database must allow a minimum of 600 connections.
Tool guidelines
Here are some guidelines for using the database configuration tool.
1. Before using the tool, stop the server. Make a backup copy of the datastoreconfig.xml file
in the application's conf directory.
2. To use the test connection feature in the GUI, change the fields as needed and click Test
Connection. If the database has been created, the information in the fields is correct and the
tool can connect to the database, the test should succeed. If not, make changes and test again.
When you are satisfied with the results, click Save.
3. When using the GUI, click Save before exiting or your changes are not saved. Changes are
saved to datastoreconfig.xml in the application's conf directory.
4. Restart the server when you are done.
Run dbConfig
Windows
To run dbConfig on Windows machines:
The software opens the Datastore Configurator page.
3. From the Datastore Configurator page, click Test Connection.
If the connection is correct, a confirmation field is displayed.
UNIX / Linux
1. Stop the trading engine server. Make a backup copy of the datastoreconfig.xml file in the
application's conf directory.
2. Using the cd command, go to <install directory>\bin.
3. Run dbConfig in a console window.
The tool can be run in a command line with the following parameters:
4. Test the connection by examining the cn.log to see if Interchange successfully connected to
the database. If necessary, repeat the above steps and change the command line details.
5. Save.
Document generator
Use the Interchange Document Generator utility to create test documents that conform to the
structures of X12 EDI or BizTalk XML formats. To create an end-to-end test, you can generate
documents of any size and send them at any interval you choose to another trading engine.
Procedure
l Create EDI or XML test documents on page 97
l Run from a command line on page 99
You can run multiple sessions of the Document Generator. Each session can generate different
document types, sizes and rates.
1. In Windows:
l Select Start > All Programs > Axway Software > Axway > Interchange >
Document Generator.
or
l In the application’s bin directory, double-click docGen.cmd.
In UNIX log in to the Axway account you created previously, ensure that you have X Windows
connectivity to the server where you installed the application. Run the following command to
open the Document Generator:
<install directory>/bin/docGen
You also can run the Document Generator from a command line. See Run from a command line
on page 99.
3. Complete the fields as described below.
4. Click Generate to generate the number and size of documents you specified. The Document
Generator continues to generate documents at the interval you specified until you click Stop or
close the EDI or XML Document Generator window.
Field descriptions
The following describes the fields on the EDI and XML Document Generator windows.
l Sender’s ID – Type the ID of the sender.
l Receiver’s ID – Type the ID of the receiver.
l Control ID (EDI only) – Type any numeric control ID. This is the starting number for the
document counter.
l Output Directory – Type the directory where the Document Generator writes the outbound
documents. Or, use the Browse button to locate this directory. This is typically the sender’s EDI
or XML out directory.
l Input template (EDI only) – If you want to use your own X12 EDI document as the template
for creating test EDI documents, click Browse to point to the document on your system.
Document Generator copies your document and inserts your specified sender, receiver and
control ID in the generated test documents. If you want Document Generator to create
documents for you, leave this field blank.
l Documents to generate – Type any value between 1 and 999999 to indicate the number of
documents you want to create per unit of time. The Document Generator creates all of these
documents at once.
l Document size (K) – Type any value between 1 and 999999 to indicate the size of each
document you want to create.
l Regeneration time (min) – Type any value between 1 and 999999 to indicate the time in
minutes the Document Generator waits to create the next document or set of documents.
l Maximum unconsumed files – This is a fail-safe optional control to stop generating
documents in the output directory after Interchange has stopped consuming messages. For
example, when the server has stopped running. When the number of unconsumed documents
reaches this limit, the utility stops generating documents. This prevents large numbers of
unconsumed messages from piling up in the output directory.
You cannot pause the Document Generator from the command line as you can when using the GUI.
Only one Document Generator at a time can be started from the command line in a single DOS
window or terminal window.
Note If you run Interchange on UNIX and there are spaces in the sender’s or receiver’s ID, we
recommend using the Document Generator GUI. See Create EDI or XML test documents on
page 97.
UNIX
For UNIX, the following example shows the command line format for Company1 to create 7 EDI
documents that are 3K in size every 5 minutes and place them in the EDI out directory for sending to
Partner1. The control ID is 302.
If you run the docGen command without any parameters, the GUI opens.
To stop the generator:
Windows
For Windows, the following example shows the proper command line format. Events related to
running the tool are written to the docgen.log in the application’s log directory.
docGen -type edi -sender company1 -receiver partner1 -docid 302 -outpath
[installation_directory]/data/company1/ediout -size 3 -ndocs 7 -interval
5
Press Ctrl-C in the DOS window to stop the Document Generator.
If there are spaces in the sender’s or receiver’s routing ID or out directory name, place the IDs or
directory name in quotation marks so Windows properly handles the spaces.
If you use Windows, the names of these tools have an extension of .cmd (for example,
as1Tool.cmd). If you use UNIX, whether or not the tools have an extension depends on the
specific brand of UNIX or Linux OS (for example, as1Tool or as1Tool.sh). This does not apply to
scripts with extension of .sql.
Depending on whether you use Windows or UNIX, some of these tools may not have been installed
with the application. If a tool changes a value in the database, restart the server for the change to
take effect.
Tool Description
as1Tool Packages, unpackages and dumps EDIINT messages. This
tool is not for use by end users.
as2Tool Packages, unpackages and dumps EDIINT messages. This
tool is not for use by end users.
as3Tool Packages, unpackages and dumps EDIINT messages. This
tool is not for use by end users.
asxTool Packages, unpackages and dumps EDIINT messages. This
tool is not for use by end users.
certScan Scans public-key certificates and reports information,
warnings and errors. See Analyze certificates for errors on
page 809.
certStats Collects statistics about the certificates in the database.
See Collect data about certificates on page 810.
crlPurgeHttpsClient Removes outdated CRLs from the CRL table and file
system. See Purge old CRLs on page 808.
dataMover Migrates data from one database to another. This tool is to
be used only by some Activator users under the
supervision of technical support.
Tool Description
deallocateClob De-allocates Character Large Object (CLOB) data types in
Oracle databases. Recommended for use only by database
administrators and experienced users of Oracle.
Before version 5.6, Interchange misallocated CLOB for
some database tables. This could result in a database
eventually running out of space. We recommend using
this tool if you use a version before 5.6 or are upgrading.
The tool performs a limited unit of work at each
invocation. As the amount of misallocated storage can
vary from one installation to another, you can run the tool
repeatedly until the tool generates messages indicating
there is no more unnecessary CLOB storage to remove.
Run the tool without parameters from a command line to
display instructions for use.
This tool is not necessary if you are using a current version
of Interchange.
derby_IJ Enables SQL queries of a Derby database. This tool is not
for use by end users.
diagnose When performing troubleshooting, this tool can be used
to compress and send log files to technical support.
Technical support often requests log files when helping
users. Run the tool from a command line and follow the
menu prompts.
For information about how to submit log files to technical
support through the user interface, see Send log files to
technical support on page 1100.
diff The diff tool is similar to the Unix diff tool and the
Windows comp tool. It improves upon these tools by
reporting the offsets of differences even in binary files.
Also, it is platform independent, and it sets exit codes to
allow shell scripts or batch files to make use of the tool.
Very large files are processed using Java nio buffers for
efficiency. The tool provides help if you invoke it with -?.
dirTester Tests the Java temp or other specified directory by writing
an unbuffered and a buffered temp file. This tool is for use
only upon advice of technical support.
ebxmlCpaSchema Performs tests on the content of the ebXML CPA. The tool
tronValidator makes sure matching elements in each PartyInfo
element of the ebXML CPA are consistent. See Tools for
CPAs on page 570.
Tool Description
ebxmlCpaSecurity Used for digitally signing CPAs. Its various functions all
Guard relate to signing and verifying digital signatures of a CPA.
See Tools for CPAs on page 570.
ebxmlCpaValidator Performs a schema validation on a CPA. See Tools for CPAs
on page 570.
exportProfile Exports community and partner profiles to XML files.
Community profiles are exported as partner profiles.
Partner profiles also can be exported as partner profiles,
either singly or in a batch. Run exportProfile without
parameters to display directions for using the tool. This
tool is only for use with Interchange 5.4 or later.
externalConfigBackupRestore.cmd For the use of this tool, see Back up and restore a custom
configuration on page 860.
extractSpecialTarFiles The tar command has a known limitation for archive
entries bigger than 8 GB in size.
Use this tool to unpack tar files created by Interchange
when they have a size larger than 8GB.
Use this tool from the command line with the following
syntax:
extractSpecialTarFiles <soruce_file.tar.gz>
<destination_directory>
fillInMessage For messages traded before upgrading to version 5.4 or
Direction later of Interchange, this tool adds metadata to the
database regarding the direction of traded messages
(inbound, outbound). Message direction displays in the
search results of Message Tracker.
Use of this tool is optional if you have used versions earlier
than 5.4. The tool is not needed if you did not use a
version earlier than 5.4.
Run this tool only when the server is not running. If the
database contains thousands of records, it may take hours
for the tool to run. If you start the tool and end the
process before it is completed, you can re-start the tool
later and it picks up where it left off.
ftpTester Verifies interoperability of Interchange with FTP servers.
See FTP tester tool on page 868.
Tool Description
httpTester Tests whether an HTTP client can connect to the HTTP
server. This tool is for use only upon advice of technical
support.
jmsTester Checks for proper configuration of JMS queues.
keyInfoWriter Extracts KeyInfo element information from a certificate for
use in a CPA for ebXML trading. See Extract KeyInfo
element for a CPA on page 567.
listTimeZones Lists all available time zones for the JRE in use on a
computer.
logViewer Interleaves multiple log files and sorts log entries
chronologically. It also can filter log categories, log levels
and threads. This tool is not for use by end users.
manageTrading Starts/stops trading engines and pauses trading engine
message consumption. This tool supports the following
options:
l manageTrading help
l manageTrading processing start [transient] – Starts all
trading engines on the local server. When "transient"
option is specified, the nodesmembership table does
not update the flag that indicates if a node is
automatically started or not at server startup.
l manageTrading processing stop [transient] – Stops all
trading engines on the local server. Same comment
on the "transient" option as for start.
l manageTrading consumption pause – Engages the
Pause Consumption system throttler across all trading
engines in the cluster.
l manageTrading consumption resume – Stops the
Pause Consumption system throttler across all trading
engines in the cluster.
messagePurgeTool Immediately deletes all database records of traded
messages and all files in the backup directory. See Purge
Interchange manually on page 863.
mmdGenerator Used to generate all possible MMDs or a specific MMD for
an ebXML CPA. See Tools for CPAs on page 570.
Tool Description
modifyUIPorts Resets the HTTP user interface port in the event of a port
conflict that makes the UI inaccessible. This tool is for use
only upon advice of technical support. Run the tool
without parameters to display instructions for use. In
addition, read the port resetting instructions in the
startup.xml file at <install directory>\conf.
netInfo Finds network interfaces for a computer. See Configure
server IP binding on page 59.
oracle_create_table Script for implementing Oracle custom tablespaces. See
Spaces.sql the Oracle custom tablespaces option of the Interchange
Installation Guide.
partyInfo Lists the names and details about the community, partner
and WebTrader profiles configured in Interchange and the
totals for each profile type. This tool provides a way to
obtain information about profiles outside of the user
interface.
passportIntegrationConfig Enables you to set the Interchange / PassPort connection
parameters from a command line.
rejectInprocess Sets Interchange messages that are stuck in the in-process
Messages state to a status of failed. This tool is for use only upon
advice of technical support, and only when all TE and CN
nodes are stopped. Run the tool without parameters to
display a list of valid parameters.
sftpTester Verifies the operation of the SFTP client in Interchange
and a partner’s SFTP server.
sysInfo Displays system information such as the operating system,
memory statistics, JVM class path and JVM library path.
This information also writes to <install
directory>\logs\sysInfo.log.
treeScan Scans the collaboration and action trees for corruption.
See Check the collaboration and action trees on page 107.
uiSslConfig Backup tool for editing the ...conf\startup.xml file in
case the setup method described in Configure
UI connection on page 56 does not work properly.
Tool Description
upgradeCompare Searches for and lists changes made to an installation tree
after a snapshot was taken with the upgradeList tool.
This tool is used when upgrading.
upgradeDiff Recursively compares the sizes of system files in the old
and new installation directory trees. This tool is used when
upgrading.
upgradeList Generates a snapshot of the entire application installation
directory tree. This tool is used when upgrading.
versionInfo Lists the version and build number of the installed
application. Run the tool without parameters to generate
the list.
Usage
The tool has the following usage. All options can be specified by a full name (for example,
iterations) or an abbreviation (for example, i). Also, the treeScan command must be entered
on a single command line.
treeScan
[-license|-l <license_file>]
[-iterations|-i <iteration_count>]
[-sleep|-s <sleep_time>]
[-emailTo|-et <address>]...
[-emailLevel|-el error|warn|info|all]
[-minCommunities|-mc <integer>]
[-minExchanges|-me <integer>]
Where:
l license_file is the name of the license file corresponding to the database configured in
../conf/datastoreconfig.xml. The default license file is in ../conf/license.xml.
l iteration_count is the number of scan cycles, with each of the two trees being scanned once
per cycle. The default number of iterations is 1. A value of 0 (zero) indicates an infinite number
of iterations; the tool should scan forever until terminated by the user.
l sleep_time is the number of seconds to wait between scan cycles. The default value is 30
seconds.
l address is a valid email address for sending the results of a scan. Multiple -emailTo options
can be given to specify multiple email recipients. A message is sent only when a scan's results are
different from the last successfully emailed scan results. See the next bullet for more criteria on
emailing scan results. The tool sends messages via the global external SMTP server as set in the
instance of Interchange whose trees are being scanned (see Configure the global external SMTP
server on page 60).
l error|warn|info|all indicates the minimum level of notification in the scan that is required to
send an email message.
o error, which is the default, indicates at least one error must be reported in a scan for the
scan's results to be emailed to the specified recipients.
o warn indicates the results of a scan containing any warnings or errors that are potentially
emailed.
o info indicates the results of a scan containing any warnings, errors or infos that are
potentially emailed.
o all indicates all scan results that are potentially emailed.
l integer is a non-negative integer indicating the minimum number of distinct trading
communities or distinct exchanges that must be referenced by the action and collaboration
trees. The only types of exchanges that are referenced by the trees are application pickup and
community pickup exchanges.
Functionality
The tool checks for the following peculiarities in the action and collaboration trees:
l Bad number of root nodes (nodes with NULL parent) in action or collaboration tree. Each tree
must have exactly one root node.
l Bad root node name in the action or collaboration tree.
l Missing required nodes in the action or collaboration tree. Required nodes are determined by the
licensed product and features indicated in the license file.
l Missing or unexpected selection criteria in an action or collaboration tree node.
l Missing or unexpected action in an action tree node.
l No community nodes in the action or collaboration tree.
l A change in the number of community nodes in the action and collaboration trees from the
previous scan.
l No exchange point nodes in the action or collaboration tree.
l A change of the number of exchange point nodes in the action tree from the previous scan.
l Missing community node in the action or collaboration tree. All nodes in the action and
collaboration trees with children corresponding to local parties are scanned for local party
nodes. A set of all found local parties is constructed to verify whether all action and
collaboration tree nodes that are supposed to have children corresponding to local parties do
have children for all the found local parties.
l Missing required building block in a collaboration tree node. All required building blocks are
checked for type (for example, ReliableMessaging, BusinessProtocol,
TransportRetryCount) but not necessarily values. All BusinessProtocol building blocks
are checked for the required business protocol types (for example, AS1, AS2, email and
RosettaNet). Required business protocol types are determined by the licensed message protocol
features indicated in the license file.
Found peculiarities are logged at an info, warn or error level, depending on severity. Log
messages are routed to standard output and to the treeScan.log file in the logs directory.
Also, at the end of each scan a summary of the number of each level of peculiarity is logged.
l Open the user interface on page 110
l The toolbar on page 111
l Navigation aids for the Interchange user interface on page 112
l If your license requires or optionally allows using an external database, the database is properly
configured.
l The server is running.
l You have a compatible browser:
o Mozilla Firefox 35 or newer
o Internet Explorer 10 or newer
o Chrome 41 or newer
Be aware and notify your trading partners of the following requirement, which is required
to run applets in the user interfaces:
The browser must include the Java Runtime Environment (JRE) plugin version 1.7 (update
45 or later). The latest released version of JRE is recommended.
Note that some browsers (such as Chrome 42 – Released April 2015) do not allow Java
plugins in the way plugins have been enabled traditionally in browsers. Special
configuration is now required. For more information refer to the Java website under the
topic of "How do I enable Java in my web browser?"
Logon procedure
To log on to the user interface:
1. Make sure the server is running.
2. To log on, use one of the following methods:
l On Windows, select Start > All Programs > Axway Software > [installation name]
> Admin.
l In Windows Explorer, double-click admin in <install directory>\bin.
l On Windows or UNIX, point the browser to:
http://host:6080/ui/Host
Host is the fully qualified domain name or IP address of the computer running the server. If
the browser and Interchange are on the same computer, you can use localhost.
3. Use admin as the user ID and Secret1 as the password when logging on the first time. The
user name and password are case sensitive.
These are the user ID and password of the default system user. After logging on, it is
recommended that you create a user with all permissions enabled and use it as a system
administrator. You should also immediately change the password of the user admin. See
Interchange user administration on page 114.
The first time you log on, a page titled Getting started displays. It provides tips and links for
configuring the application.
The toolbar
The primary navigation aid of the user interface is the top toolbar. The options available on your
toolbar depend on the functionality enabled by your user license. See the following toolbar
example.
The following table describes the toolbar elements. Hover your cursor over the icons in the UI to
view menu items.
Home Application home page for a dashboard view of system
activity.
CSOS Configure and view orders for compliance with the Controlled
Substance Ordering System. This displays only when users
have a license for CSOS.
Message Search and display trading activity records and documents.
Tracker
Reports Manage and view alert activity reports.
Tasks and Manage alert rules and view alerts.
Alerts
System Manage miscellaneous system configurations.
management
Peer network Configure a network for managing multiple trading engine
clusters. This displays only when users have a peer network
license.
Trading Configure trading communities and other trading settings.
configuration
Partners Configure trading partners.
Users and Configure users and permissions.
roles
Help Product information and user documentation.
The following figure shows the community navigation graphic:
The following figure shows the partner navigation graphic:
The graphics appear on the community or partner summary page and related pages. For more
information, see Modify a community on page 138 and Modify a partner on page 156.
You also use this area to change user passwords and manage global settings, such as session time-
out intervals.
For users with CSOS capability, a personal certificates tab is provided for associating a user with
certificates. See Axway CSOS on page 1008.
The following topics provide information about user administration tasks you can perform in the
Interchange user interface:
l Admin user on page 114
l Manage users on page 115
l Change password on page 116
l Manage roles on page 116
l Date and time preferences on page 126
l Global user settings on page 127
l Unlock a blocked user on page 128
l Manage password policies of transport users on page 129
Admin user
The default system user has a user ID of admin and an initial password of Secret1. The initial
username for the default system user is root administrator. This user is assigned to a role named
admin, which has permissions to perform all functions. You cannot view or change the permissions
of the admin role. You also cannot delete the admin role or the admin user.
After logging on the first time with the admin user login credentials, it is recommended that you
immediately change the password.
You can use the admin user as a system administrator user. However, it is recommended that you
add another user instead and assign it to the admin role to act as the system administrator. This way,
you can reserve the admin user as a backup.
Manage users
The Users and roles area of the user interface has links for adding, changing, and deleting users.
Note If your software license allows users to have certificates, see Axway CSOS on page 1008.
Add a user
1. Select Users and roles > Add a user.
2. Complete the fields.
3. Choose a role for the user. If the role you want is not available, you can create a role and add
the user to it later.
4. Click Add this user.
Modify a user
1. Select Users and roles > Manage users.
2. Select a user and make the changes you want.
3. Click Save changes.
Delete a user
1. Select Users and roles > Manage users.
2. Select a user.
3. Click Delete this user.
Rather than deleting, you can disable a user by clearing the Enable this user checkbox.
l A user has a choice of the time zone to display in the user interface. The default is the server’s
time zone. See the Time zone tab for other options.
l The total number of browser sessions that can run concurrently is controlled by the user license.
You can check the maxUserSessions element in the license.xml file by selecting Help >
License information on the top toolbar in the user interface.
Change password
Any user can change his or her own password. In addition, a user with permissions for managing
users can change the passwords of others as well as his or her own password.
1. To change a password:
a. Select Users and roles > Change my user account.
or
b. If you are an administrator, select Manage users and click a user name.
2. On the user’s page, click Change this user’s password.
3. Type the new password twice in the fields and click Save changes. The new password is
effective the next time the user logs on.
Manage roles
Roles are sets of permissions an administrator can create to define the limits of what users are
allowed to do in the user interface.
The following diagram shows the high-level hierarchy of permissions you can control with roles. For
detailed information about each permission within these categories, see Role permissions on page
118.
In most cases, limiting a role prevents items outside the scope of the role from appearing in the user
interface. For example, if the role does not have Manage trading configuration permission, a
user with that role cannot see the Add a community link. In other cases, the user sees a message
stating that he or she does not have access. For example, if the role does not have View
applications permission, when a user with that role clicks the Application delivery icon in the
community flow diagram, the restricted access message appears.
After you create a role, you can assign it to one or more users. An administrator role typically has
permissions to perform all tasks. The default system role is named "admin" and has all available
permissions. You can create roles that have many or few permissions.
The Roles page is displayed listing all available roles. To view the details of any individual role, click
the name of the role in the list.
Add a role
1. Select Users and roles > Add a role.
2. Type a name for the role and, optionally, a description.
3. Review the list of permissions and select the ones you want for the role. For a description of the
permissions you can select, see Role permissions on page 118.
4. Click Add this role when done.
The new role is added to the list of roles on the Roles page.
Modify a role
1. Select Users and roles > Manage roles.
2. Click the name of the role to change to open the Change role page for the selected role.
3. Check the characteristics of the role, by selecting and viewing the four tabs:
l Permissions tab – Displays the permissions applied to this role. For details, see Role
permissions on page 118.
l Partner restrictions tab – Displays the partner restrictions applied to this role: For details,
see Partner restrictions for roles on page 121.
l Application restrictions – Displays the partner restrictions applied to this role: For
details, see Application restrictions for roles on page 123.
l Community restrictions – Displays the partner restrictions applied to this role: For
details, see Community restrictions for roles on page 125.
4. Make any necessary changes and click Save changes.
Delete a role
1. Select Users and roles > Manage roles.
2. On the line with the name of the role to delete, click Delete.
The role is deleted and removed from the list of roles on the Roles page.
Role permissions
When you add or change a role, you specify what type of tasks users assigned to the role are
allowed to perform. To do this, you select permissions for the role from the available permissions
displayed on the Permissions tab. The more permissions you select for the role, the broader the
authority of that role. For an administrator role, you typically select all p ermissions.
The following list describes all possible permissions for roles. Depending on your user license, not all
of these may be available in the user interface or applicable to your users.
Caution If you use Axway PassPort for access management, see Advice for PassPort users on page
126 for important information about permissions.
l Execute reports – Allows generating reports. This permission has the following child
permission, which applies only if the parent permission is selected.
Manage reports – For Interchange, allows using the alert activity report.
l Manage tasks – Allows display of the task list on the home page.
l Perform operations on list view objects in a single action – Allows users with this
permission to execute "all-type" operations on UI pages that display lists of multiple objects. For
example, a user with this permission has access to buttons and commands of the type “Delete /
All”, “Copy / All”, “Change status / All”, etc.
If the user does not have this permission, the corresponding "all-type" commands and buttons
do not appear. In that case the user can still manually select every element and perform an
action, but does not have the "all-type" commands.
"All-type" commands act only on the objects that have been returned from the current user's
most recent query. If the most recent search query had no filtering criteria, the "all-type"
command will effectively act on all objects of the query type that exist in the database.
l Search for messages processed by the trading engine – Allows the use of Message
Tracker to search for and view traded messages and information about messages. This
permission has the following child permissions, which can be applied when the parent
permission is selected.
o Add notes to messages – Allows users to write notes while reviewing message details in
Message Tracker.
o Delete messages – Allows deleting messages in Message Tracker.
l View applications – Allows viewing application pickup and delivery exchanges.
o Manage applications – Allows the modification of application pickup and delivery
exchanges.
o Restrict management to selected applications – Select this option if you want to
limit the Manage application permission to one or more application exchanges that
you specify. Click the Restrict to applications hyperlink to open the application
selection page. See Application restrictions for roles on page 123.
o Restrict viewing to selected applications – Select this option if you want to limit the
View application permission to one or more application exchanges that you specify. Click
the Restrict to applications hyperlink to open the application selection page. See
Application restrictions for roles on page 123.
l View system status – Allows viewing the system management area of the user interface. This
permission has the following child permissions, which can be applied when the parent
permission is selected.
o Manage system properties and security – Allows using controls in the system
management area of the user interface, including managing embedded servers, certificates,
and message attributes/templates.
Notes:
- If this permission is selected but the role is restricted from viewing communities or partners,
the role still shows all community and partner certificates in the Manage certificates list, but
prevents users from accessing the details links.
- If your license enables Secure Relay, this permission is required to manage IP whitelists
accessed from the system management page.
Partner restrictions take effect when one or more of the following is selected on the Permissions
tab:
l Search for messages processed by Interchange > Restrict searching to selected partners
l Manage partners configuration > Restrict management to selected partners
l View partners configuration > Restrict viewing to selected partners
The conditions set on the Partner restrictions tab apply equally to both of these role permissions. If
you want partner restrictions to be identical for searching in Message Tracker and managing
partners, select both. If you want partner restrictions to be different for both permissions, set up two
roles.
The Partner restrictions tab has two general conditions. These can be further refined with other
filtering conditions on the tab’s three sub-tabs.
The general conditions are:
l Limit this role to the partner selections and permissions indicated below – Users
assigned to the role can access information only for the partners selected on the sub-tabs. Select
this if you want the role to have access only to a limited number of partners. Specify the
exceptions on the Communities, Categories or Partners sub-tabs.
If you select this and do not specify any exceptions on the sub-tabs, the effect is the role does
not have access to any partners.
l Apply this role to all partners except for those selected with the permissions
indicated below – Users assigned to the role can access information for all partners with the
exception of the partners selected on the sub-tabs. Select this if you want the role to have access
to many partners, except for a specified few. Specify the exceptions on the Communities,
Categories or Partners sub-tabs.
If you select this and do not specify any exceptions on the sub-tabs, the effect is the role has
access to all partners.
You can use one or more of the Partner restriction tab’s sub-tabs to select partners. The effects of
the sub-tabs are cumulative. For instance, if you select community A on the Communities sub-tab
and partners C and D on the Partners sub-tab, all partners of community A as well as partners C and
D — regardless whether C and D belong to community A — are affected.
If you do not make any selections on the sub-tabs, this has the effect of denying access to all
partners.
If you need help setting up partner categories to use the Categories sub-tab, see Group partners by
categories on page 158.
See Manage multiple partner-restricted roles on page 122 and Role permissions on page 118.
Application exchange restrictions take effect when you select o ne or more of the following on the
Permissions tab:
l Manage applications > Restrict management to selected applications
l View applications > Restrict viewing to selected applications
The conditions you set on the Application restrictions tab apply equally to both of these role
permissions. If you want the application restrictions on a role to be identical for viewing and
modifying application exchanges, you select all of the options. If you want different groups of users
to have application restrictions that are different for a single application exchange (or group of
application exchanges), you must set up more than one role.
The Application restrictions tab has two general conditions:
l Limit this role to the application selections and permissions indicated below – Users
assigned to the role can access information only for the application exchanges that are selected
on the tab. Select this option if you want the role to have access only to a limited number of
application exchanges that you specify in the tab.
Note: If you select this option, but do not specify any application exchanges, the role does not
have access to any application exchanges.
l Apply this role to all applications except for those selected with the permissions
indicated below – Users assigned to the role can access information for all application
exchanges, with the exception of the application exchanges selected on this tab. Select this
option if you want the role to have access to many application exchanges, except for a few that
you specify.
Note: If you select this option, but do not specify any excepted application exchanges, the role
has access to all application exchanges.
The following table lists common tasks related to applications that users may need to perform and
the role permissions that apply.
Task Permission
View the list of applications View applications; filtered based on any restrictions
you configure.
View the details of an application View applications; limited based on any restrictions
you configure.
Modify an application Manage applications; limited based on view and
manage restrictions.
Change the state of an application Manage applications; limited based on view and
manage restrictions.
Delete an application Manage applications; limited based on view and
manage restrictions.
Add an application Manage applications; not allowed if restrictions on
managing applications are configured.
Create a new embedded server Manage trading configuration. Not affected by
restrictions.
View the details of an embedded server View trading configuration. Not affected by
restrictions.
View the list of trusted root certificates View applications. Not affected by restrictions.
Trust and un-trust root certificates Add, modify, export, and delete community and
server certificates. Not affected by restrictions.
The following table lists tasks related to application users (such as an FTP user) and the role
permissions that apply.
Task Permission
View the list of application users View applications. If application restrictions are
configured, the main lists of application users (such
as the Application FTP users page) are not visible.
Add a new application user Manage applications. Can add new users only on
applications that are within their Manage restrictions.
Task Permission
Delete an application user Manage applications. Not affected by Manage
restrictions, but not possible to do if View
applications restrictions are configured, or if the user
is in use by an application.
Modify an existing application user Manage applications. Not affected by Manage
restrictions, but not possible to do if View
applications restrictions are configured.
Change which user is assigned to an Manage applications. Can change users only on
application (and which directory they applications that are within their Manage restrictions.
use)
View the keys for an application SFTP View applications. Not affected by Manage
user restrictions, but not possible to do if View
applications restrictions are configured.
Add/remove keys for an SFTP user Manage applications. Not affected by Manage
restrictions, but not possible to do if View
applications restrictions are configured.
Access password policy details View trading configuration. Not affected by
restrictions.
Community restrictions take effect when you select one or more of the following permissions on the
Permissions tab:
l Search for messages processed by the trading engine > Restrict searching to selected
communities
l Manage trading configuration > Restrict management to selected communities
l View trading configuration > Restrict viewing to selected communities
The conditions you set on the Community restrictions tab apply equally to any of the role
permissions that are listed in the above list. If you want the community restrictions on a role to be
identical for searching, managing, and viewing communities, you select all of the options. If you
want different groups of users to have community restrictions that are different for a single
community (or group of communities), you must set up more than one role.
If you set up community restrictions so that a role has access to Community A but is restricted from
viewing Community B, the role allows users to see messages between the two communities.
The Community restrictions tab has two general conditions:
l Limit this role to the community selections and permissions indicated below – Users
assigned to the role can access information only for the communities that are selected on the
tab. Select this option if you want the role to have access only to a limited number of
communities that you specify.
Note: If you select this option, but do not specify any communities, the role does not have
access to any communities.
l Apply this role to all communities except for those selected with the permissions
indicated below – Users assigned to the role can access information for all communities, with
the exception of the communities selected on this tab. Select this option if you want the role to
have access to many communities, except for a few that you specify.
Note: If you select this option, but do not specify any excepted communities, the role has
access to all communities.
The Interchange UI displays user permissions in a parent-child structure. To use a child permission,
the parent permission also must be selected. The Interchange UI dynamically enforces this parent-
child relationship. For instance, if you select the child permission Manage reports, the UI selects
the parent permission for you.
In the PassPort UI, however, user privileges for Interchange are listed without regard to parent-child
relationships. In PassPort you must assign privileges to roles according to the same parent-child
structure used by Interchange. In other words, to assign the child Execute reports privilege to a
PassPort user role, you also must assign the parent Manage reports privilege. The Interchange
default privileges in the PassPort UI have the same names as in the Interchange UI. See Role
permissions on page 118 for guidance on mirroring the parent-child relationship in PassPort.
Use the Date/Time tab to select the time zone for displaying dates relative to the user’s browser.
Use either the local or a remote time zone. You can choose the format for displaying dates. You can
also choose where in the user interface to apply the specified format.
Only users assigned to a role with the “manage users and roles” permission can view or change
global user settings.
l Passwords must have at least one special character from the set – Forces users to
have at least one special character in their passwords. Type the permitted characters in the
special characters allowed field. For example, you can allow characters such as: `~!@#$%^&*
()-=[]{}\|;:",.<>?.
Use the utlity unlockUser in <install directory>\bin. Run the utility without parameters in a
UNIX console or in a Windows command window.
The utility prompts you for the password of the admin user and the user ID of the user to unlock.
The length of time users can be locked out and the number of times users can try to log on before
being locked out are set to apply to all users. For more information, see Global user settings on page
127.
Note In rare cases, the utility may not work. If this happens, try enclosing the password in
quotes. For example: “password”.
A default password policy is in effect globally for all transport users. You can override the default
policy by adding one or more user-defined policies and assigning policies to specific users.
Password policies are not transport-specific. FTP, SFTP and Web Services users can be assigned to
the same policies.
The following topics describe setting up and assigning password policies:
l Add, change transport user password policy on page 129
l Transport users password policy settings on page 130
l Assign password policy to transport user on page 131
Get started
1. Select System management on the toolbar to open the System management page.
2. Click the task Manage password policies of transport users. This opens a page of the
same name.
Add a policy
1. Click Add a new password policy to create a policy. See Transport users password policy
settings on page 130 for descriptions of the fields to complete.
2. Click Save changes to add the policy.
Change a policy
1. Click the name of a policy to open it.
2. Change fields and click Save changes. See Transport users password policy settings on page
130 for descriptions of the fields.
3. Select an assigned users tab and click a user’s name to assign a different password policy.
Delete a policy
1. Before deleting a policy, determine whether to reassign its users to another policy. If you do not
reassign users, any users assigned to a deleted policy are reassigned to the default policy.
2. Click Delete and click OK to confirm you want to delete a password policy. You cannot delete
the default policy.
When changing a policy, select a user tab and click a user's name to assign a different policy to a
user.
l Policy name – The policy name. You cannot change the name of the default policy.
l Policy description – An optional description of the password policy.
l Minimum password length – The minimum number of characters allowed for user
passwords.
l Minimum change count before password can be reused – The number of times a user
must change a password before a previous password can be re-used. If a value of 0 is used, the
minimum change count for password re-use is disabled. This means a minimum change count
does not affect password re-use.
l Elapsed days before password can be reused –The number of days that must pass before
a user can re-use a password. If a value of 0 is used, elapsed days before a password can be re-
used is disabled. This means a password can be re-used immediately if the minimum change
count also is 0.
l Days password remains valid before it must be reset – The number of days a password
is valid before it must be changed. If a value of 0 is used, a password remains valid forever.
l Passwords must not contain the user ID – By default, this option is selected. Forces users
to enter passwords that do not contain the user ID string.
l Passwords must have at least one upper-case letter and one lower-case letter –
Forces users to have at least one upper-case letter and one lower-case letter in passwords. With
or without this selected, passwords are case sensitive.
l When adding a pickup or delivery exchange, and you are setting up a new user account, you
can select the password policy for the user.
l When changing a transport user you can assign a different password policy.
Topics related to trading configurations include:
l How configurations work on page 133
l Communities on page 134
o Add a community on page 136
o Modify a community on page 138
o Use the community search tool on page 141
o Checklist for community configuration on page 141
l Partners on page 142
o Add a partner on page 143
o Community trading partners on page 147
o Add a partner to a community on page 148
o Partner data form on page 151
o Modify a partner on page 156
o Delete a partner on page 158
o Group partners by categories on page 158
o Use the partner search tool on page 159
l Application pickups on page 160
o Add an application pickup on page 161
l Application deliveries on page 162
o Add an application delivery on page 162
l Application pickup and application delivery fields on page 163
l Modify an application pickup or delivery on page 202
l Fields for modifying application pickups and application deliveries on page 203
l Community trading pickups and partner deliveries on page 256
o Add a trading pickup on page 261
o Add a partner trading delivery on page 262
o Trading pickup and trading delivery fields on page 263
o Modify a trading pickup on page 326
o Modify a partner trading delivery on page 327
l Routing IDs on page 408
o Add a routing ID on page 409
o Modify a routing ID on page 410
l Message metadata and attributes on page 412
o Metadata uses on page 413
o Metadata definitions on page 414
o Metadata for record file management on page 418
o Add a community attribute on page 421
o Add a partner attribute on page 422
o Message attributes templates on page 424
l Export and import profiles on page 426
If you and your partner use Axway software, you can take advantage of the application's
configuration management features, such as configuration and certificate exporting and importing.
If a partner uses other interoperable software, you must maintain the partner configuration
manually.
To establish a trading relationship, you create and export your community configuration to your
trading partner, who imports it as a partner configuration. Conversely, your partner creates and
exports a community configuration that you import as a partner configuration on your system.
The image below shows how community configurations are exchanged between partners. This
example shows two companies exporting community configurations to be exchanged and imported
as partner configurations.
Communities
A community is an Interchange object that represents your local way of grouping trading partners.
It defines your organization’s internal processes for handling messages. It also defines how your
community expects to receive messages from back-end applications and from remote partner
exchange points.
This information is used by your system to set document back-up options, tune system performance
and communicate with back-end systems.
The trading information in the community configuration (also known as a community profile) is
important to your partners. It consists of what message protocols and transports you want partners
to use when sending documents to you. If you want to securely exchange documents, the exported
community definition also contains a copy of your certificate and public key used by partners to
encrypt messages before sending.
When you add a community in the Interchange user interface, you specify the following elements:
l Community name
l Routing ID to be used by partners to send you documents. A community can have multiple
routing IDs.
l For secure trading, a certificate with a public-private key pair. Your private key remains in your
system. Only the public key and certificate are provided to partners in the exported community
profile.
After you add a community, you can view and manage the community configuration in the user
interface.
The Interchange interface view of the community includes a graphic image of the community's
component elements.
In the user interface, you can click the elements of the community graphic to view and manage each
part of the community configuration.
l Summary – A report of trading activity for the period you specify, defaulting to activity within
the last hour. It also shows the default delivery exchange for receiving messages from partners
and certificate information.
l Properties – Displays the name and country code of the community, as well as any associated
attributes.
l Certificates – Displays certificates associated with a community. On this page you can add and
manage certificates. For more information see Certificates pages on page 786.
l Routing IDs – Displays the routing IDs associated with a community. A community routing ID
is the “from” address used in message trading. A community must have at least one, but can
have multiple routing IDs. For more information see Routing IDs on page 408.
l Contacts – Displays the principal contact person for the community and the corresponding
email address. You can optionally add a phone number and notes.
You can use any email address you want. This can be an address for one person or an alias
address with a distribution to many people. You also can enter multiple e-mail addresses by
separating each address with a semicolon.
l [Transport] users – The [Transport] users page lists user accounts associated with embedded
servers and the usage for the users. [Transport] is a variable for transports such as FTP, SFTP and
others.
The [Transport] users icon appears only when certain types of embedded servers have been
configured for a community.
l Application delivery – Displays the transports set up to route messages to a back-end system.
A community can have multiple application delivery exchanges. For more information, see
Application deliveries on page 162.
l Application pickup – Displays the transports set up to retrieve messages from back-end
systems for packaging and sending to partners or other applications. If a community has
multiple application pickup exchanges, all are polled for outbound messages. For more
information see Application pickups on page 160.
l Delivery settings – Enables you to set the default delivery exchange for the community to use
for routing consumed messages. For more information, see Delivery settings on page 889.
l Message handler – Set up message actions, such as re-routing, triggered by specified
conditions. For more information see Message handler on page 892.
The message handler page enables you to set up message actions, such as re-routing, triggered
by specified conditions.
l Message validation – The message validation page lets you set whether a community accepts
or rejects EDI messages with duplicate control IDs. You also can specify whether a community
accepts or rejects signed or encrypted messages. For more information, see Inbound message
validation rules on page 939.
l Collaboration settings – The collaboration settings page lets you set up encryption, signing
and other rules for messages a community sends. Provided a community uses a certificate, the
default settings are adequate in many cases. For more information see Collaboration settings on
page 909.
l Trading pickup – The trading pickup page shows the message protocols and transports
partners use to send messages to the community and how the community retrieves the sent
messages. A community with multiple trading pickups gives partners multiple avenues for
sending messages. For more information see Community trading pickups and partner deliveries
on page 256.
l HTTP proxy – Use the HTTP proxy page to define a global HTTP proxy through which all
outbound HTTP traffic is routed, if needed. All communities use this proxy. For more
information see HTTP outbound proxy on page 584.
l Trading partners – The trading partners page shows the partners that belong to a community.
For more information see Community trading partners on page 147.
Add a community
For a description of communities, see Communities on page 134.
See Manually create a new community on page 137.
l Import a backed-up Interchange community profile and its partners from a
compressed file – Use this option is to import a backed-up file containing an Interchange
version 5.x community profile and its associated partner profiles.
See Import a backed-up Interchange version 5 community profile and its partners in a
compressed file on page 137.
l Email address – Enter an email address for the community contact.
l Routing ID – Enter an ID to use as a routing reference in the user interface.
l EbXML party ID type or cXML domain – If you plan to trade ebXML or cXML
documents, select this option. For additional information, see ebXML overview on page
545.
6. Select the default, Yes, launch the wizard to add a certificate. Optionally, you can add a
certificate at a later time.
For details about certificate management, see Add a certificate on page 792.
7. Enter one or more values for any attributes that display in the Define community attributes
wizard.
8. Click Finish.
9. Select the default, Create a self-signed certificate and click Next
You can import a backed-up community profile to a new instance of the trading engine with a fresh
database or to an existing instance.
You must import the backed-up profile through the user interface. You import the same compressed
file that was exported. Do not copy the file to the profiles\autoImport directory. The file is not
compatible with auto-importing.
The backed-up community and partners are imported. If a duplicate community is detected,
you can overwrite the existing community or rename the imported community.
Modify a community
For a description of communities, see Communities on page 134.
To add a new community, see Add a community on page 136.
For a description of how to limit the number of displayed communities, see Use the community
search tool on page 141.
After you create a community, you can view and modify the community's characteristics.
To view and modify an existing community:
1. In the user interface, from the Trading configuration menu select Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary screen for
that community.
3. At the top of the Summary page is a community navigation graphic for the community. This
graphic represents the parts of the community and provides active links to pages on which you
manage these parts.
In the user interface, place your cursor over a label and a red box appears around that part of
the graphic. Click inside the red box to go to the page that the label references.
You can use the community graphic links to view and edit the following user interface pages for
the community:
l Summary — Reports trading activity for the period you specify. The default period of
activity is the last hour. This page also shows the default delivery exchange for receiving
messages from partners and certificate information.
l Properties — Displays:
o The name of the community
o A country code that indicates the community location
o Any attributes associated with the community for processing or search purposes. You
can change the value for one or more of the optional attributes on that page. You can
define optional attributes in one of three states:
o Empty text box and empty checkbox — this attribute is ignored at runtime.
o Completed text box and empty checkbox — this attribute is evaluated at runtime.
o Disabled text box (grayed out) and selected checkbox — this attribute may exist for
other agreements, but is negated at runtime for this particular agreement.
l Certificates — Displays certificates associated with this community. You also can add a
certificate. For more information see Certificates pages on page 786.
l Routing IDs — Displays the routing IDs associated with this community. A community
routing ID is the “from” address used in message trading. A community can have one or
more routing IDs. For more information see Routing IDs on page 408.
l Contacts — Identifies the principal contact person for the community. Other information
can be added, including a phone number and notes.
l Application delivery — Displays the available delivery exchanges that the community can
use to send documents and messages to back-end applications.
l Application pickup — Displays the available pickup exchanges that the community can
use to consume documents and messages from back-end applications.
l Delivery settings — Displays routing criteria and specific file-handling behavior that the
community uses to deliver messages to back-end applications. You can set different routing
criteria and handling specifications for each application delivery the community uses.
l Message handler — Enables you to set up message actions, such as re-routing, triggered
by specified conditions. For more information see Message handler on page 892.
l Message validation — Enables you to specify whether a community accepts or rejects
EDI messages with duplicate control IDs. You also can specify whether a community
accepts or rejects signed or encrypted messages. For more information see Inbound
message validation rules on page 939.
l Collaboration settings — Enables you to set up encryption, signing and other rules for
messages a community sends. Provided a community uses a certificate, the default settings
are adequate in many cases. For more information see Collaboration settings on page 909.
l Trading pickup — Displays the message protocols and transports that partners use to
send messages to the community and how the community retrieves the sent messages. A
community with trading pickups gives partners multiple avenues for sending messages. For
more information see Community trading pickups and partner deliveries on page 256.
l HTTP proxy — Enables you to define a global HTTP proxy through which all outbound
HTTP traffic is routed, if needed. All communities use this proxy. For more information see
HTTP outbound proxy on page 584.
l Trading partners — Enables you to view the Trading partners page. This page shows
the partners that belong to a community. It displays the status of messages traded with
each partner. You can use commands on this page to add partners to the community, and
to display collaboration settings between the community and its partners.
Tasks to complete
If an important step in the community configuration is not yet completed, the interface displays this
task and provides a link to the page where you can complete the task.
l Add a partner to this community
l Show community-to-partner collaboration settings
l Change embedded transport server
l Enable all exchanges for receiving partner messages
l Manage CPAs
l Export this community as a partner profile
l Back up this community and its partners
l Delete this community
The search tool is located in the left panel of the Communities page. If the search panel is hidden,
click the SHOW/HIDE tab to display it. By default, this page lists all communities, regardless of
community membership
You can launch searches that use any combination of the following criteria:
l Community name
l Routing ID
l Delivery protocol
l Delivery transport
You can use the wildcard characters "*" and "?" for searches. You can combine wildcards with
partial names. For example *part* would return MyPartner if such a partner existed.
To filter for search results that return every instance of a criteria, use either the asterisk wildcard
character ( *), or use the syntax: [ANY]. Note that you must use the opening and closing brackets
around ANY, or the search will return no results.
Searches are not case sensitive.
1. Does your community have at least one routing ID? This is the unique identifier for a
community in e-commerce trading. See Routing IDs on page 408.
If you plan to trade ebXML documents, enter an ebXML party ID type only if the routing ID is
not a URI. See Routing ID for ebXML on page 561.
2. What kind of certificate do you want to use: self-signed or CA? See Manage certificates on page
782.
3. What integration exchange do you want to use for picking up messages from a back-end
system? See Application pickups on page 160 and Application deliveries on page 162.
4. What trading exchange do you want to use for receiving messages from partners? See
Community trading pickups and partner deliveries on page 256.
5. What integration exchange do you want to use for routing messages received from partners to a
back-end system? See Community trading pickups and partner deliveries on page 256.
6. Have you added a trading partner, either by importing a profile file or manually configuring a
profile? See Add a partner on page 143.
7. Have you determined whether messages sent or received by you or partners must pass through
proxy servers, firewalls, or load balancers? If so, take steps to adjust the trading engine
configuration to accommodate unhindered message traffic. See Firewalls and proxy servers on
page 39 and, if applicable, HTTP outbound proxy on page 584.
8. Do you want the community to use default or custom collaboration settings? These are rules for
how outbound messages are packaged. A packaged message is one that has been signed and
encrypted and also MIME-wrapped with sender and receiver information along with other data.
See Collaboration settings on page 909.
9. Have you viewed the collaboration settings between your community and your partner to make
sure security and packaging are aligned? See Search and display collaboration settings on page
910.
10. What document packaging rules do you want to enforce for the messages your community
receives from partners? If trading EDI documents, do you want the community to accept or
reject duplicate documents? See Inbound message validation rules on page 939.
11. Do you want to set up a post-processing script for special handling of documents before
sending to partners or after receiving them from partners? For example, inbound documents
can be channeled to a specific integration directory with a post-processing script. See Post-
processing configuration on page 905.
12. Do you want to set up conditions for re-routing, copying, or rejecting messages? See Message
handler on page 892.
13. Have you added and started at least one node? See the "Processing nodes and clustering"
section of the Interchange Installation Guide and Add a trading engine node on page 54.
14. Have you configured the global external SMTP server for sending email messages? See
Configure the global external SMTP server on page 60.
15. How long do you want to retain records of processed messages? Delivery exchanges by default
are set to back up all messages passing through them. Messages must be backed up to use
Message Tracker on page 826 properly. You can set a schedule for how long records are
retained. See Data storage, backups, and purging on page 849.
Partners
A partner is an Interchange object that represents a sender or receiver in a message-processing
definition.
Just as you give a partner your community configuration profile to use as a partner profile, your
partner exports a community profile to a file and sends it to you. You import this file as the partner's
profile on your system. The imported partner definition consists of contact information and the
message protocols and transports your partner supports for receiving documents.
For partners who do not use Axway software, you must manually create partner configurations on
your system.
Partners can exist without being associated with a community, however partners must belong to a
community for trading to occur.
Significant elements of a partner configuration are:
l The partner name.
l A routing ID to use as a routing reference in the user interface.
l Optionally, one or more delivery exchanges for sending documents to the partner.
l For secure trading, the partner’s certificate and public key for encrypting the messages you send.
Add a partner
For a description of partners, see Partners on page 142.
Prerequisites
Use the partner data form to collect information about the partner. See Partner data form on page
151.
Procedure
1. In the user interface, from the Partners menu select Manage partners.
2. Click Add a partner.
3. Select an Manually create a new partner and click Next.
4. Complete the fields:
l Partner name – Enter a name to identify this partner in the user interface.
l Country code – Select the country code that corresponds to the country where the partner
is located.
l Contact name – Enter an administrative contact name for this partner.
l Phone number – Enter a phone number for the partner contact.
l Email address – Enter an email address for the partner contact
l Allow this partner to be auto-cloned to peers – If your license supports the peer
network, this option is selected by default. Clear this option if you do not want auto-cloning
or do not use the peer network.
l Routing Id – Enter an ID to use as a routing reference in the user interface.
l ebXML party ID type or cXML domain –
For ebXML traders only, enter an ebXML party ID type only if the routing ID you enter is not
a URI.
For cXML traders only, enter the matching cXML credential domain type.
l Choose communities for this partner – From the displayed list of available
communities, select the communities that you want this partner to be a member of. Partners
do not have to be members of any community, but partners must be a community member
for trading to occur.
5. Click Next to display the Define partner properties screen.
6. Optionally add partner properties.
7. Click Finish.
The new partner is added to the list of available partners on the Partners page.
Prerequisites
If you are expecting the imported partner profile to include the partner's certificate and public key,
check whether a partner's certificate is trusted. Go to the partner summary page and click
Certificates in the navigation graphic at the top of the page. Click the certificate name and then
click the Trusts tab. Check the details of third-party certificates imported with profiles to make sure
trusted roots are present.
Procedure
1. From the Partners menu, select Manage partners.
2. Click Add a partner to open the wizard.
3. Select Import a partner profile from a file and click Next.
You typically use this procedure to migrate profile data from Interchange 4.2.x to Interchange 5.x
or later.
Note A partner can exist in your Interchange configuration without being associated with any
community. A partner can also be associated with multiple communities.
l Community name – Display only. This is the community to which the trading partners are
subscribed. You cannot modify this field
l Trades in the last [time unit] with this community – Select a time unit and click Update
to view number of trades. Available time units are:
o 1 hour (default)
o 4 hours
o 8 hours
o 24 hours
o 7 days
o 30 days
l Trading partner table – This table lists the partners that are subscribed to the community. For
each partner you can view the number of messages in per status:
o Failed
o In process
o Waiting for receipt
o To
o From
l Select an action – Select one or more partners from the list of subscribed partners, then use
the drop-down list Remove command to remove the selected partner(s) from the list of the
community's subscribed partners.
l Choose whether this community will re-route messages received from one partner
to another partner – Select an option for this community:
o Never re-route messages
o Allow messages to be rerouted
l Related tasks – Use the hyperlinks to:
o Add a partner to this community. See Add a partner to a community on page 148.
o Show community-to-partner collaboration settings. See Collaboration settings on page 909.
Note A partner can exist in your Interchange configuration without being associated with any
community. A partner can also be associated with multiple communities.
This chapter describes how to manage partner/community relationships from the community side.
Alternatively, you can create or modify a partner from the Partners page. When you do this, you
have the option of associating (or "subscribing") the partner to one or more communities. For
details of how to add a partner (independently of the community configuration) see Add a partner
on page 143.
Procedures
Prerequisites
Optionally, use the partner data form to collect information about the partner. See Partner data form
on page 151.
Procedure
1. Complete the fields:
l Partner name – Enter a name to identify this community in the user interface.
l Country code – Select the country code that corresponds to the country where the partner
is located.
l Contact name – Enter an administrative contact name for this partner.
l Phone number – Enter a phone number for the partner contact.
l Email address – Enter an email address for the partner contact
l Allow this partner to be auto-cloned to peers – If your license supports the peer
network, this option is selected by default. Clear this option if you do not want auto-cloning
or do not use the peer network.
l Routing Id – Enter an ID to use as a routing reference in the user interface.
l ebXML party ID type or cXML domain –
For ebXML traders only, enter an ebXML party ID type only if the routing ID you enter is not
a URI.
For cXML traders only, enter the matching cXML credential domain type.
l Choose communities for this partner – From the displayed list of available
communities, select the current community and any additional communities that you want
this partner to be a member of. Partners do not have to be members of any community, but
partners must be a community member for trading to occur.
2. Click Next to display the Define partner properties screen.
3. Optionally add partner properties.
4. Click Finish.
The new partner is added to the list of available partners on the Partners page and on the
community Trading partners page.
Prerequisites
If you are expecting the imported profile to include the partner’s certificate and public key, check
whether a partner’s certificate is trusted. Go to the partner summary screen and click Certificates in
the navigation graphic at the top of the page. Click the certificate name and then click the Trusts
tab. Check the details of third-party certificates imported with profiles to make sure trusted roots are
present.
Procedure
1. Next to the File name box, click Browse and locate the XML partner file.
2. Under Choose the import mode, select how the system should handle the partner if a current
partner exists with the same name.
3. Select the appropriate options:
l Allow this partner to be auto-cloned to peers – If your license supports the peer
network, this option is selected by default. Clear this option if you do not want auto-cloning
or do not use the peer network.
l Choose communities for this partner – From the displayed list of available
communities, select the current community and any additional communities that you want
this partner to be a member of. Partners do not have to be members of any community, but
partners must be a community member for trading to occur.
4. Click Finish.
The partner is imported. The new partner is added to the list of available partners on the
Partners page and on the community Trading partners page.
2. Click Finish.
The selected partners are added to the list of available partners on the community Trading
partners page.
When you are ready to add a partner, go to the partners area of the user interface, click Add a
partner and then click Manually create a new partner.
Trading engine
Field Partner’s data
Product name
Version number
Identity
Fields followed by an asterisk represent required information in Interchange.
Company name *
Routing ID *
One ID is required but the partner
can have multiple IDs
Contact name *
Contact phone number *
Contact e-mail address *
Protocol
The partner’s preferred protocol for your community to send documents.
EDIINT AS1 (e-mail)
EDIINT AS2 (HTTP)
Secure file (HTTP, FTP, file system, JMS, MQSeries). Files are
packaged using S/MIME.
Secure e-mail (for partners who use mail clients such as Microsoft
Outlook)
Other (FTP, file system, JMS, MQSeries). No packaging or security
ebXML
Transport details
The partner’s preferred transport for your community to send documents.
HTTP, email
HTTP URL
HTTPS URL
Authenticate SSL Circle one: yes no
connection
SMTP/POP email address
SMTP-to-SMTP email address
SMTP server name
Port (default 25)
Use SSL Circle one: yes no
If use SSL is yes, the
SSL port
FTP
FTP server name
Port
Inbox
Pickup
User name
Password
Clients must use SSL to connect to this
server
JMS
JNDI URL
JNDI factory
JNDI user name
JNDI password
JMS queue
JMS connection factory
JMS user name
JMS password
MQSeries
MQSeries server
Port (default 1414)
Queue name
Queue manager
Channel
Character set (default 819)
User name
Password
Preferences
Preference Partner's data
Preserve original filenames
If preserve original filenames is true, overwrite duplicate filenames
If preserve original filenames is true, sequentially number
duplicate filenames
Generate unique filenames
Security details
The partner must provide a digital certificate to effect secure trading.
Sign documents Circle one: yes no
Request acknowledgments Circle one: yes no
Request signed acknowledgments Circle one: yes no
If HTTP or HTTPS, request synchronous Circle one: yes no
acknowledgments
Message digest Circle one:
SHA1 (default)
MD5
Encrypt documents (yes or no) Circle one: yes no
Partner trades binary documents Circle one: yes no
Partner trades XML documents Circle one: yes no
XML type
Sender XPath if custom XML type
Receiver XPath if custom XML type
Modify a partner
For a description of partners, see Partners on page 142.
To add a new partner, see Add a partner on page 143.
For a description of how to limit the number of displayed partners, see Use the partner search tool
on page 159.
After you create a partner, you can view and modify the partner's characteristics.
To view and modify an existing partner:
l Summary – Displays information about the partner including:
o Community memberships
o Administrator contact name
o Administrator email address (if any)
o Default routing ID
o Default delivery exchange
o Default encryption certificate (if any)
Additionally, the summary page displays any additional tasks you must execute to complete
the partner trading configuration.
l Properties – Displays:
o The name of the partner
o A country code that indicates the partner location
o Cloning option - visible only if you are licensed to use the peer network.
o Any attributes associated with the partner for processing or search purposes. You can
change the value for one or more of the optional attributes on that page. You can
define optional attributes in one of three states:
o Empty text box and empty checkbox — this attribute is ignored at runtime.
o Completed text box and empty checkbox — this attribute is evaluated at runtime.
o Disabled text box (grayed out) and selected checkbox — this attribute may exist for
other agreements, but is negated at runtime for this particular agreement.
l Certificates – Displays certificates associated with this partner. You also can add a
certificate here. For more information see Certificates pages on page 786.
l Routing IDs – Displays the routing IDs associated with this partner. A partner routing ID is
the “from” address used in message trading. A partner can have one or more routing IDs.
For more information see Routing IDs on page 408.
l Contacts – Displays the principal contact person for the partner, and any additional
contacts that you may add. For each contact, you can add or edit additional information,
including a phone number, email and notes about the contact. The primary contact is
indicated above the list of contacts.
To change the primary contact, click in the selection box next to the contact name of a
non-primary contact to select it. Then from the Select an action box, select Make
primary and click Selected.
l [Transport] users – The [Transport] users page lists user accounts associated with
embedded servers and the usage for the users. [Transports] is a variable for transports such
as FTP, SFTP and others.
The [Transport] users icon appears only when a partner account has been associated with
certain types of community delivery deliveries.
Delete a partner
1. In the user interface, select Partners > Manage partners to display the Partners page.
2. In the list of available partners, click the selection box next to the name of the partner or
partners you want to delete.
3. From the Select an action drop-down menu, select Delete.
The interface displays the new options Selected and All.
l Click Selected to delete only the partners that have their selection boxes checked.
l Click All to delete all partners that are currently displayed in the list of the Partners page.
There are two types of partner categories:
l Regular categories – After grouping partners in regular categories, you can search for
partners in one or more categories to view lists of the partners or take actions such as changing
the partners' community. Click Partners on the top toolbar to display the Partners page. Use the
partner search panel to set filter conditions. See Use the partner search tool on page 159.
You also can build user roles based on partner categories to restrict users' access to data for
specified partners. See Partner restrictions for roles on page 121.
l Collaboration categories – You can use collaboration categories the same as regular
categories, but there is one significant additional feature. A community can use a collaboration
category to apply custom collaboration settings for outbound messages to many partners
simultaneously. See Manage community-to-category collaboration settings on page 932.
Collaboration categories are recommended only if your community wants to apply custom
collaboration settings to multiple partners. If not, use regular categories instead.
A single partner can be added to multiple regular categories, but a partner can belong to only one
collaboration category at a time. You can add regular categories in a parent-child hierarchical
relationship. Parent-child relationships are not allowed for collaboration categories, as conflicts
between categories could occur.
Add a category
1. Select Partners > Manage categories to display the Categories page.
2. Click Add a category to open the Add a category page.
3. Enter the new category name.
4. Select the level on the category tree where you want the category to reside.
5. Click Add.
Delete a category
1. Select Partners > Manage categories to display the Categories page.
2. From the list of available categories, click a category to open the Change category page for that
category.
3. Click Delete this category.
The category and any dependent subcategories are deleted.
2. From the list of partners, click the name of a partner to display the Summary page for that
partner.
3. In the navigation graphic at the top of the Summary page, click Categories to open the
Choose categories page.
4. Select a category by clicking a category checkbox, and click Save changes.
The search tool is located in the left panel of the Partners page. If the search panel is hidden, click
the SHOW/HIDE tab to display it. By default, this page lists all partners, regardless of community
membership
You can launch searches that use any combination of the following criteria:
l Partner name
l Routing ID
l Delivery protocol
l Delivery transport
l Transport location (protocol URL)
l Partner community membership or partners who do not belong to a community
l Partner delivery message protocol
l Partner category membership
You can use the wildcard characters "*" and "?" for searches. You can combine wildcards with
partial names. For example, *part* would return MyPartner if such a partner existed.
To filter for search results that return every instance of a criteria, use either the asterisk wildcard
character ( *), or use the syntax: [ANY]. Note that you must use the opening and closing brackets
around ANY, or the search will not return any results.
Searches are not case sensitive.
You also can specify how many columns of information to display for the partners found in a search.
In addition to partner name, you can display default routing ID, contact, default delivery exchange,
categories, and communities.
Application pickups
An application pickup is an Interchange object that specifies the way the product c onsumes
messages and files from applications. You set up application pickups within a community. You can
have multiple application pickups.
l FTP
l SFTP
l File system
l JMS
l IBM MQSeries
l Web services API server
l Web services (HTTP)
l PeSIT
l Axway Integrator
l Pluggable server
l From address and To address wizard fields on page 263
Transport-specific pages:
l FTP (external) transport configuration on page 272
l FTP (embedded) transport configuration on page 275
l SFTP (external) transport configuration on page 281
l SFTP (embedded) transport configuration on page 286
l File system transport configuration on page 189
l JMS transport configuration on page 294
l IBM MQSeries transport configuration on page 300
l Add or modify a PeSIT application pickup (embedded server) on page 667
l Add or modify a PeSIT application pickup (polling client) on page 670
l Integrate with Axway Integrator on page 1048
l Pluggable server on page 320
Application deliveries
An application delivery is an Interchange object that specifies the way Interchange sends files to
applications. You set up application deliveries within a community. You can have multiple
application deliveries.
l FTP
l SFTP
l File system
l JMS
l IBM MQSeries
l Web services API server
l Web services (HTTP)
l PeSIT
l Axway Integrator
l Pluggable server
6. Complete fields of the following pages. The pages and fields vary depending on the transport
protocol you selected in the previous step.
Common pages:
l From address and To address wizard fields on page 263
Transport-specific pages:
l FTP (external) transport configuration on page 272
l FTP (embedded) transport configuration on page 275
l SFTP (external) transport configuration on page 281
l SFTP (embedded) transport configuration on page 286
l File system transport configuration on page 189
l JMS transport configuration on page 294
l IBM MQSeries transport configuration on page 300
l Web Services API pickup and delivery configuration on page 200
l Add or modify a PeSIT application delivery on page 659
l Integrate with Axway Integrator on page 1048
l Pluggable server on page 320
Common screens:
l From address and To address wizard fields on page 263
Transport-specific screens:
l FTP (external) transport configuration on page 272
l FTP (embedded) transport configuration on page 275
l SFTP (external) transport configuration on page 281
l SFTP (embedded) transport configuration on page 286
l File system transport configuration on page 189
l JMS transport configuration on page 294
l IBM MQSeries transport configuration on page 300
l Web Services API pickup and delivery configuration on page 200
l Add an MLLP application pickup on page 199
l Add an MLLP application delivery on page 198
l Add or modify a PeSIT application delivery on page 659
l Add or modify a PeSIT application pickup (embedded server) on page 667
l Add or modify a PeSIT application pickup (polling client) on page 670
l Pluggable server on page 320
The wizard shows the pages when you add:
l An application pickup
l A community pickup to consume messages from trading partners under the No packaging
message protocol.
Fields
l Address must be determined by either message attribute configuration or by
protocol address only .
l Specify the address. Always use a fixed address.
Specifies that Interchange should always use a fixed address for the sender or receiver. You can
click Pick party to launch a wizard that helps you locate the community or partner you want.
The “from” or “to” party must be set up as a community or partner in the user interface.
l Use the protocol address but if protocol address is missing, parse the document for
the address.
If you select this option, you must configure the address parsing rule. See Address parsing
rule options below.
l Always parse for the address. Regardless whether the message protocol provides
the address, always parse the document for the address.
Select this option to specify that Interchange should always parse the message for the sender or
receiver address.
For messages from partners, however, Interchange still checks the protocol header for the
sender and receiver. A message with an unknown sender or receiver in the header is rejected.
The always parse option for inbound messages is for finding the identity of true senders or true
receivers.
For messages picked up from applications, the always parse option tells Interchange to find the
sender or receiver in the message body. Messages from integration do not have protocol
headers.
If you select this option, you must configure the address parsing rule. See Address parsing
rule options below.
When this parsing option is elected, communities and partners must have matching routing
IDs in the same format. For example, if the “from” address in a parsed message is
ID:interchange ID:value3:value4, the partner must have the same routing ID.
When this option is not selected, “to” and “from” addresses in messages are parsed only for
Interchange ID and ID values. For example, 1:partner is parsed as the sender and rendered
as partner1 in the user interface.
Note that TRADACOMS only has two, optional values that can be parsed. They must match
one of the following patterns:
o A:
o :B
o A:B
Note This topic describes configuring an external FTP server. For an embedded FTP server, see
FTP (embedded) transport configuration on page 275.
To enable partners to send messages to your FTP server, first set up the account, user ID and
password for the FTP server where Interchange retrieves files. Any partner who intends to receive
messages from you by FTP also must also perform this step.
In general, you should use the AS3 message protocol rather than the secure file protocol to trade
securely via FTP. An exception would be trading with a partner who uses an earlier version of
Interchange or Activator that does not support AS3. See Secure file message protocol on page 971
for more information.
Caution If you use Microsoft Internet Information Services (IIS) for the FTP server, make sure it is
updated with the latest patches from Microsoft. Large files (approximately 1 gigabyte) may
fail unless IIS is up to date.
Information-level messages about FTP client-server interaction write to Interchange log file. For
more verbose messages to aid in troubleshooting FTP issues, you can change the message level to
debug. Open:
log4j.properties file in <install directory>\conf
Search for the following entry, change the value from info to debug, then save and close the file.
log4j.category.com.cyclonecommerce.tradingengine.
transport.ftp.SimpleDebug=info
The debug setting logs each meta-command (for example, Send), followed by each primitive
command as it is sent to the server (Rest, Stor, Rnfr, Rnto, and so on). Also, a message is logged
each time a data connection is initiated or accepted. Each file name received during List operations
is logged. For more information see System logs on page 1093.
When used for integration delivery or sending to partners, default settings are in place to preserve
original file names and sequentially number duplicate file names. With these settings, Interchange
uses a file naming convention to defeat conflicts arising from multiple nodes feeding identically
named documents to the same FTP directory and server. Files are renamed in the following format:
But you can use the following because a period is the first character of the inbox directory
name:
c:\data\pickup\.inbox
When receiving files from a partner, we recommend that your partner write files to the inbox
directory first and then move them to the pickup directory when they are ready to be
retrieved. This process is automatic if your partner also uses any of the Axway products B2Bi,
Interchange, or Activator. If the partner uses other software to upload files to your server,
the software should be configured to initially upload the files to the inbox directory and
move them to the pickup directory when they are ready to be retrieved.
For outbound integration, the back-end system must write the message to the inbox and
then move it to the pickup directory.
For inbound integration and sending outbound to partners, Interchange writes to the inbox
and then moves the message to the pickup directory.
There may be some specialized servers, typically running on mainframes, that support only part
of the FTP protocol (RFC 959). In such cases you may have to clear this option and take steps of
your own to make sure collisions do not occur.
If you are connecting to a partner’s Interchange-embedded FTP server, do not select this option.
o Use separate directory for temporary files – Type the full path of an inbox directory
(for example, c:\data\inbox). Files are uploaded to this directory. When fully written,
files are moved to the pickup directory for retrieval.
Do not put the inbox under the pickup directory unless you use a period at the beginning of
the inbox name. Interchange and other applications ignore directories and files that begin
with periods.
For example, do not use the following directory structure:
c:\data\pickup\inbox
But you can use the following because a period is the first character of the inbox directory
name:
c:\data\pickup\.inbox When receiving files from a partner, we recommend that your
partner write files to the inbox directory first and then move them to the pickup directory
when they are ready to be retrieved. This process is automatic if your partner also uses Axway
products B2Bi, Interchange or Activator. If the partner uses other software to upload files to
your server, the software should be configured to initially upload the files to the inbox
directory and move them to the pickup directory when they are ready to be retrieved.
For outbound application deliveries, the back-end system must write the message to the
inbox and then move it to the pickup directory.
For inbound application and sending outbound to partners, Interchange writes to the inbox
and then moves the message to the pickup directory.
o Use special extension in pickup directory for temporary files – If you prefer not to
use an inbox, select this option. While a file is being written to the pickup directory, a
temporary extension is added so the system knows not to retrieve it because the file is only
partially written. Once fully written, the temporary extension goes away and the file can be
retrieved.
Click Next to name the exchange.
After you name the exchange, Finish.
Note If prompted, you can select a Secure Relay DMZ zone to route messages to the partner.
This option displays only for transports for sending to partners when your user license
supports Secure Relay and a DMZ zone has been added. For details, see Secure Relay DMZ
nodes on page 474.
When you elect to set up an embedded FTP transport for a community, the exchange wizard asks
whether you want to:
l Use a previously defined embedded FTP server (if available)
l Define a new embedded FTP server
If you choose to use a previously-defined embedded FTP server, the wizard prompts for the user
account name. You can choose an existing account or define a new one. If you choose an existing
account, you must choose a sub-directory within that account’s home directory that is not assigned
to any other exchange point.
If you choose to define a new embedded FTP server, the wizard prompts for a server name and port
number. The wizard then asks for a user name and password for the new server. If the default
selections already are in use, you must use another user name and password.
Note For a description of configuring an external FTP server, see FTP (external) transport
configuration on page 272.
l Trading servers are used for receiving messages from partners. In the simplest case, a partner’s
FTP client connects to your embedded server to PUT a message for your community to pick up.
There also is a more complex configuration — hosted embedded FTP — where your community
lets partners connect to your embedded server to GET messages.
l Application servers are used for retrieving messages from, or delivering messages to, back-
end systems.
The exchange wizard enforces the usage context for embedded FTP servers. For example, the wizard
does not let you define a new embedded FTP trading server when the usage requires an application
server.
To configure hosted partner accounts for embedded FTP servers, you must have a specific license
permission. Your license.xml file must enable the permission: hostedPartnerFtpAccounts.
Without this permission you can configure a partner to send messages via an external FTP server,
but not an embedded server. This permission does not affect back-end application accounts; there
is no restriction on adding hosted accounts from which a back-end system can pick up messages.
Community FTP accounts on page 171 Community exchanges, trading servers only
Partner FTP accounts on page 172 Community and partner exchanges, trading
servers only
FTP accounts for back-end application exchanges Community exchanges, application servers
on page 173 only
User names are shared by all trading servers. This enables a load balancer to send a request to any
trading server. However, user names associated with application servers are not related to user
names shared by trading servers. For example, the user name user1 on the trading side is
completely different from user1 on the application side.
The following topics describe each account type.
Partners can perform PUT operations to community accounts associated with trading pickups, but
not GET operations. This is to prevent partners from accessing each others’ files.
Partners can drop packaged messages directly into the home directory of a community account. As
a result, community FTP accounts can be referred to as shared accounts.
When a community profile is exported as a partner profile file to be imported by partners, the
community FTP account is exported with the FTP pickup exchange.
To avoid file name collisions you can use the Message attributes tab on the embedded FTP
pickup exchange maintenance page to specify sub-directories where partners can place files based
on the sender routing ID. This also allows identifying the sender when binary files are dropped off.
For example, the following sub-directory scheme could be used for two partners (p1 and p2) to
drop off files for community c1:
Sub-directory Purpose
p1/c1 p1 sends to c1
p2/c1 p2 sends to c1
If a partner-specific sub-directory scheme is used, the partner must manually specify the sub-
directory after importing the community's profile. If there is only one community and it has only one
routing ID, the second directory level is unnecessary.
The user interface segregates the two purposes. When adding a partner embedded FTP delivery
exchange, the wizard suggests the /mailbox sub-directory under the home directory. This is where
Interchange delivers messages for the partner to pick up. This can be thought of as a hosted partner
delivery exchange, since the partner is picking up messages from your server. If the same partner
account is added to an existing community pickup exchange, the system suggests the home
directory (/). This ensures outbound and inbound messages are not confused.
For hosted partner delivery exchanges, you must inform the partner performing the GET operation
of the FTP host name or IP address, the port number, the path, and the server user name and
password. If your partner uses Axway products B2Bi, Interchange or Activator, the partner must add
a community pickup exchange for receiving messages via an external FTP server (see FTP (external)
transport configuration on page 272). The default value of the pickup directory must be changed to
mailbox or whatever directory you specified. Also, clear the option for use temporary files.
Partner FTP accounts cannot be used by back-end application exchanges.
In this example, an administrator adds an outbound hosted FTP delivery exchange for partner1.
The administrator associates the user account p1. The user interface suggests /mailbox as the sub-
directory where the partner retrieves (GET) messages.
Optionally, for binary trading the use the Message attributes tab of the embedded FTP pickup
maintenance page to specify sub-directories where Interchange delivers files based on the routing
ID of the sending community. For instance:
Sub-directory Purpose
p1/mailbox/c1 p1 GETS messages from community1
p1/mailbox/c2 p1 GETS messages from community2
Since partner FTP accounts are partner-specific, message attribute mapping only is needed for
identifying the community if there is more than one possible sending community or there is no other
way to identify the community. This would be the case when you intend to trade binary files, which
have no packaging or internal identifying information.
Message attribute mapping also can be used to sort messages into arbitrary sub-directories based on
other metadata besides the sender or receiver. For example, an inline process could assign metadata
items to outbound messages that would cause them to be sorted into sub-directories based on
mappings specified on the Message attributes tab.
This example is for traders who do not want to upload files to a shared community FTP account.
An administrator adds or selects a community embedded FTP pickup exchange. The pickup
exchange can be one already associated with a community FTP account, such as c1. The pickup
exchange provides an anchor for one or more partner FTP accounts where files may be dropped off
for the community.
The administrator selects the Directories tab on the community pickup exchange. There the
administrator can add a new partner account or select an existing one.
The user interface suggests / as the home directory for the FTP account where partners can drop
files for the community. In contrast, /mailbox is the suggested directory when a hosted delivery
exchange is added for a partner to GET messages.
Note Embedded FTP servers treat paths beginning with a slash as starting at the home directory
for the user account currently logged in.
When you create an FTP account you can choose to either use an existing account, a new account
(with all fields empty), or to define one later.
When defining an embedded FTP pickup for the first time, the exchange wizard suggests the generic
name application as the FTP account name. The same user name is offered for the first FTP
application delivery exchange. The difference is \out is suggested as the pickup subdirectory name
and \in is suggested as the delivery subdirectory name. You can change the user names and
subdirectories as long as the same combination of user name and subdirectory is not specified for
two exchanges. This is true for all embedded FTP exchanges.
In the early days of the Internet it was common for an FTP client to use port mode. The data
connection was established from the server back to the client, even though the original control
connection was always established from the client to the server.
The client is generally less prepared than the server to open firewall ports, and passive mode has
become the standard (Windows command line FTP client is an exception). In passive mode, when
the client wants to perform a GET, PUT or LIST operation, the server creates a temporary socket
listening on a port specifically for that client, usually at a high number like 50,000. The client then
makes the data connection to the server, performs the transfer and the connection is dropped. The
control connection remains active.
Most firewalls in use today allow the client through on the temporary data port, even if the port is
not explicitly configured to be open. This is safe because the firewall can eavesdrop on the initial
control connection from the client and notice it is an FTP connection. If the connection is non-SSL,
the firewall also can notice the temporary port the server assigned for the client to establish the data
connection. Subsequently when the client tries to connect again on that port, the firewall allows the
connection on a one-time basis to the temporary port.
Load balancers present a similar problem. If the load balancer is FTP-aware, it can route incoming
data connections to the same server as the associated control connection. But the load balancer
cannot do this in the case of SSL. It must be configured to route all connections from the same
origination IP address to the same server until there are no more connections from that IP to that
server.
Since all trading servers share the same pool of user accounts, the load balancer can be configured
to route incoming control connections to any trading server. For example, if you have two
Interchange nodes on different machines, each running a server on port 4021, the load balancer
can be configured to round-robin between the two hosts.
l Server name – Enter a name for the new embedded FTP server. This can be any name you
want. You can select this server when setting up additional embedded FTP delivery exchanges
later.
If this is the first server, the wizard suggests the name Trading FTP if the server is to be used for
receiving messages from partners or Application FTP if the server is to be used for exchanging
messages with a back-end system.
l Port – The port number that listens for incoming FTP connections. This is known as the control
port. The wizard suggests a port not in use and displays a list of ports in use by Interchange. You
can use the suggested port or another.
If this is the first server, the wizard suggests — if not already in use — 4021 for a trading server or
5021 for an integration server. For security reasons, trading and integration servers must use
different ports.
If you elect to define a new account, complete the following fields. If you are defining the first user
account, the wizard suggests for the user name and password the community default routing ID for
a trading server or application for a back-end application server.
l Password – The password to connect to the server.
l Confirm password – The password to connect to the server. Anonymous connections are not
supported.
l Transport user password policy – Select the password policy to assign to the user. See
Manage password policies of transport users on page 129 for more information.
Click Next to continue the configuration.
But if you add an amended path, the effective directory is the specified sub-directory. For
example:
common\data\ftp\users\trading\<user account>\<amended path>
For the first integration server, the wizard suggests an amended path of in for integration
delivery or out for integration pickup. By default the home directory (/) is not used, but you can
change this.
Interchange keeps track of the embedded FTP directory structure for you. Do not manually
change any directories Interchange creates for managing messages transported via embedded
FTP servers.
Click Next if you want to name the exchange. Otherwise, click Finish.
Note If prompted, you can select a Secure Relay DMZ zone to route messages to the partner.
This option displays only for transports for sending to partners when your user license
supports Secure Relay and a DMZ zone has been added. For details, see Secure Relay DMZ
nodes on page 474.
To enable partners to send messages to your SFTP server, first set up the account, user ID and
password for the SFTP server where Interchange retrieves files. Any partner who intends to receive
messages from you by SFTP also must also perform this step.
SFTP is similar to FTP, but performs all operations over an encrypted Secure Shell (SSH) transport.
SFTP and FTP/SSL (or FTPS) are different transports. An SFTP server can communicate only with
other SFTP servers, not FTP servers.
Interchange supports limited SFTP functionality as the following notes:
l Only supports SSH 2.0.
l Checkpoint-restart functionality is not supported.
l User commands and scripting (as supported for FTP) are not supported for SFTP.
This transport has been tested only with the OpenSSH sftp-server.
For more information about SSH see:
l http://datatracker.ietf.org/wg/secsh/charter/
l http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt
l http://www.openssh.com/faq.html
SFTP fields
The following fields are used in the delivery exchange wizard for configuring this transport.
But you can use the following because a period is the first character of the inbox directory
name:
c:\data\pickup\.inbox
When receiving files from a partner, we recommend that your partner write files to the inbox
directory first and then move them to the pickup directory when they are ready to be
retrieved. This process is automatic if your partner also uses Interchange. If the partner uses
other software to upload files to your server, the software should be configured to initially
upload the files to the inbox directory and move them to the pickup directory when they are
ready to be retrieved.
For outbound integration, the back-end system must write the message to the inbox and
then move it to the pickup directory.
For inbound integration and sending outbound to partners, Interchange writes to the inbox
and then moves the message to the pickup directory.
If this exchange is for a community, add the private key to the community. If this exchange is for
a partner, add the public key to any community that will be trading with the partner.
To add a key, click Certificates in the navigation graphic at the top of the community summary
page. Select the SSH keys tab. Click Add an SSH key, follow the prompts and click Add.
Select the key as the default SSH key after it has been added.
For more information see Public-private key and password authentication on page 292.
l Use host-based authentication – Select this option if this delivery binds outbound messages
to a server that requires host-based authentication. You can use host-based authentication with
a Linux SFTP server. Before you activate this option you must complete the steps listed below. If
you have started creating an external SFTP pickup or delivery, cancel the wizard and complete
the prerequisites first.
Note: If you select this option, in the "Configure outbound connection proxy page", you must
not select the option "Begin secure connection in DMZ". See Configure outbound connection
proxy on page 488.
o On the server:
1. Copy the public key file to the following directory:
/home/user/.ssh/
2. Append the public key file contents to authorized_keys:
/home/users/.ssh/key1.pub >> /home/user/.ssh/authorized_keys
3. Append the public key to the /etc/ssh/ssh_known_hosts file. Edit to add
hostname:
cat /home/user/.ssh/sshkey1_linux36.pub >> /etc/ssh/ssh_known_
hosts
4. Add the client's hostname to the following file:
/etc/ssh/shosts.equiv
o On the client:
1. Copy the corresponding private key file to a directory.
2. In Interchange, create a new pickup/delivery using an external SFTP server. When
prompted to Configure the SFTP settings, after you complete the initial fields,
select Use host-based authentication. Enter the User Name and browse to the
private key file. If a Key password is required, enter it.
Secure Relay
If prompted, you can select a Secure Relay DMZ zone to route messages to the partner. This option
displays only for transports for sending to partners when your user license supports Secure Relay
and a DMZ zone has been added. For details, see Secure Relay DMZ nodes on page 474.
Testing SFTP
You can use the sftpTester tool to exercise the SFTP client outside of Interchange. The script to start
sftpTester can be found in <install directory>\tools.
sftpTester is a console-based application that can verify the operation of the SFTP client in
Interchange and a partner’s SFTP server. Interchange server does not have to be running to use this
tool. You can use it on UNIX or Windows.
sftpTester duplicates the way Interchange accesses an SFTP server. It is a test program to verify
interoperability with SFTP servers. If you can send, list, receive and delete files on a SFTP server
using sftpTester, this is a good indication Interchange can interoperate with the server.
sftpTester prompts for all the information it needs, as the following illustrates:
After prompting for the initial configuration information such as the host, user and password,
sftpTester displays a main prompt that allows you to enter meta-commands to perform simple
operations such as list, send and receive. You can enter a question mark (?) at this point to get more
information. The following information displays upon entering a question mark at the main prompt:
Consumer commands
-> Enter CONSUMER command (e.g. ?, LIST, RECeive, DELete, LLIST, LCD,
QUIT): ?
CONSUMER metacommands (abbreviations shown in upper case):
? help
LIST list files on host
RECeive filename retrieve file from host
DELete filename delete file from host
LCD change local working directory
LLIST list files in local working directory
QUIT/EXIT/BYE exitNormal SftpTester
Producer commands
Troubleshooting SFTP
For troubleshooting, you can write messages specific to the SFTP transport to Interchange log file.
You can add the following properties to the log4j.properties file at <install directory>\conf.
l For messages related to high-level operation of the SFTP client, this property in debug mode is
useful for finding common SFTP problems.
log4j.category.com.cyclonecommerce.tradingengine.transport.sftp.SimpleDebug=d
ebug
l For messages related to low-level operation of the SFTP client, this property in debug mode
produces verbose messages. (Try the simple debug property before using this one.)
log4j.category.com.cyclonecommerce.tradingengine.transport.sftp= debug
When you elect to set up an embedded SFTP transport for a community, the wizard asks whether
you want to:
l Use a previously defined embedded SFTP server (if available)
l Define a new embedded SFTP server
If you choose to use a previously defined embedded SFTP server, the wizard prompts for the user
account name. You can choose an existing account or define a new one. If you choose an existing
account, you must choose a subdirectory within that account’s home directory that is not assigned
to any other exchange point.
If you choose to define a new embedded SFTP server, the wizard prompts for a server name and port
number. The wizard then asks for a user name and password for the new server. If the default
selections already are in use, you must use another user name and password.
When you create an embedded SFTP server, Interchange also generates an RSA public-private key
pair for the server. The key pair has no visibility in your user interface. But when you export your
community profile as a partner profile, the server’s public key is exported with it. When your B2Bi,
Interchange, or Activator p artner imports the partner profile, the public key can be displayed. Your
partners use the public key to authenticate the embedded server upon connecting.
Note For a description of configuring an external SFTP server, see SFTP (external) transport
configuration on page 281.
To configure hosted partner accounts for embedded SFTP servers, you must have a specific license
permission. Your license.xml file must enable the permission: hostedPartnerSftpAccounts.
Without this permission you can configure a partner to send messages via an external SFTP server,
but not via an embedded server. This permission does not affect back-end application accounts;
there is no restriction on adding hosted accounts from which a back-end system can pick up
messages.
Community SFTP accounts on Community trading pickups, trading servers only
page 182
Partner SFTP accounts on page Community trading pickups and partner trading deliveries,
182 trading serves only
Application SFTP accounts on Community application pickups and deliveries, application
page 184 servers only
User names are shared by all trading servers. This enables a load balancer to send a request to any
trading server. However, user names associated with application servers are not related to user
names shared by trading servers. For example, the user name user1 on the trading side is
completely different from user1 on the application side.
The following topics describe each account type.
Partners can perform PUT operations to community accounts associated with trading pickups, but
not GET operations. This is to prevent partners from accessing each others’ files.
Partners can drop packaged messages directly into the home directory of a community account. As
a result, community SFTP accounts can be referred to as shared accounts.
When a community profile is exported as a partner profile file to be imported by partners, the
community SFTP account is exported with the pickup exchange.
To avoid file name collisions you can use the Message attributes tab on the pickup exchange to
specify subdirectories where partners can place files based on the sender routing ID. This also allows
identifying the sender when binary files are dropped off. For example, the following subdirectory
scheme could be used for two partners (p1 and p2) to drop off files for community c1:
Subdirectory Purpose
p1/c1 p1 sends to c1
p2/c1 p2 sends to c1
If a partner-specific subdirectory scheme is used, the partner must manually specify the subdirectory
after importing the community's profile. If there is only one community and it has only one routing
ID, the second directory level is unnecessary.
The user interface segregates the two purposes. When adding a partner embedded SFTP delivery,
the wizard suggests the /mailbox subdirectory under the home directory. This is where
Interchange delivers messages for the partner to pick up. This can be thought of as a hosted partner
delivery exchange, since the partner is picking up messages from your server. If the same partner
account is added to an existing community pickup exchange, the system suggests the home
directory (/). This ensures outbound and inbound messages are not confused.
For hosted partner delivery exchanges, you must inform the partner performing the GET operation
of the SFTP host name or IP address, the port number, the path, and the server user name and
password. If your partner uses Interchange or Activator, the partner must add a community pickup
exchange for receiving messages via an external SFTP server (see SFTP (external) transport
configuration on page 281 for configuration information). The default value of the pickup directory
must be changed to mailbox or whatever directory you specified. Also, clear the option for use
temporary files.
Partner SFTP accounts cannot be used by back-end application exchanges.
In this example, an administrator adds an outbound hosted SFTP delivery exchange for partner1.
The administrator associates the user account p1. The user interface suggests /mailbox as the
subdirectory where the partner retrieves (GET) messages.
Optionally, for binary trading the Message attributes tab can specify subdirectories where
Interchange delivers files based on the routing ID of the sending community. For instance:
Subdirectory Purpose
p1/mailbox/c1 p1 GETS messages from community1
p1/mailbox/c2 p1 GETS messages from community2
Since partner SFTP accounts are partner-specific, message attribute mapping only is needed for
identifying the community if there is more than one possible sending community or there is no other
way to identify the community. This would be the case when you intend to trade binary files, which
have no packaging or internal identifying information.
Message attribute mapping also can be used to sort messages into arbitrary subdirectories based on
other metadata besides the sender or receiver. For example, an inline process could assign metadata
items to outbound messages that would cause them to be sorted into subdirectories based on
mappings specified on the Message attributes tab.
This example is for traders who do not want to upload files to a shared community SFTP account.
An administrator adds or selects a community-embedded SFTP trading pickup. The trading pickup
can be one already associated with a community SFTP account like c1. The exchange provides an
anchor for one or more partner SFTP accounts where files may be dropped off for the community.
The administrator selects the Directories tab on the community trading pickup. There the
administrator can add a new partner account or select an existing one.
The user interface suggests / as the home directory for the SFTP account where partners can drop
files for the community. In contrast, /mailbox is the suggested directory when a hosted delivery
exchange is added for a partner to GET messages.
Note Embedded SFTP servers treat paths beginning with a slash as starting at the home directory
for the user account currently logged in.
When you create an SFTP account you can choose to either use an existing account, a new account
(with all fields empty), or to define one later.
The \out directory is suggested as the pickup subdirectory name and \in is suggested as the
delivery subdirectory name. You can change the user names and subdirectories as long as the same
combination of user name and subdirectory is not specified for two exchanges. This is true for all
embedded SFTP exchanges.
Since all trading servers share the same pool of user accounts, the load balancer can be configured
to route incoming control connections to any trading server. For example, if you have two
Interchange nodes on different machines, each running a server on port 4022, the load balancer
can be configured to round-robin between the two hosts.
Server fields
l Server name – Enter a name for the new embedded SFTP server. This can be any name pickup
you want. You can select this server when setting up additional embedded SFTP delivery
exchanges later.
If this is the first server, the wizard suggests either the name Trading SFTP if the server is to be
used for receiving messages from partners or Application SFTP if the server is to be used for
exchanging messages with a back-end system.
l Port – The port number that listens for incoming SFTP connections. This is known as the
control port. The wizard suggests a port not in use and displays a list of ports in use by
Interchange. You can use the suggested port or another.
If this is the first server, the wizard suggests — if not already in use — 4022 for a trading server or
5022 for an application server. For security reasons, trading and integration servers must use
different ports.
You must select one of the following authentication options:
l This server requires the SFTP client to authenticate using a password – Select to
require your partner to submit a password to connect to your embedded SFTP server.
l This server requires the SFTP client to authenticate using a public/private key pair
– Select to require your partner to use a private key to encrypt an authentication message and
pass it to the server to decrypt with the matching public key. This process enables the server to
verify the identity of the partner. Your partner must generate a private-public key pair and give
you a file containing the public key.
l This server requires the SFTP client to authenticate using both a password and a
public/private key pair –
Select this option to require both a password and public/private key pair.
l This server allows the SFTP client to authenticate using either a password or a
public/private key pair – Select this option to require either a password or a public/private
key pair.
Click Next to continue the configuration.
l Select an existing account from the drop-down list (if an account has been previously defined)
l Define a new account
l Define an account later
If you elect to define a new account, complete the fields for the authentication option you selected
on the previous wizard page.
Password authentication
l Password – The password to connect to the server. Anonymous connections are not
supported.
l Confirm password – Confirm the password.
UserName is a value generated by the key tool (for example, pnuechte@ls0020). UserName is
optional.
Click Next to continue the configuration.
If you add an amended path, the effective directory is the specified subdirectory. For example:
common\data\ssh\users\trading\<user account>\<amended path>
For the first trading server, the wizard suggests an amended path of mailbox for trading pickup.
By default the home directory (/) is not used, but you can change this.
For the first application server, the wizard suggests an amended path of in for application
delivery or out for application pickup. By default the home directory (/) is not used, but you can
change this.
Interchange keeps track of the embedded SFTP directory structure for you. Do not manually
change any directories Interchange creates for managing messages transported via embedded
SFTP servers.
Note If prompted, you can select a Secure Relay DMZ zone to route messages to the partner.
This option displays only for transports for sending to partners when your user license
supports Secure Relay and a DMZ zone has been added. For details, see Secure Relay DMZ
nodes on page 474.
Click Next if you want to name the exchange. Otherwise, click Finish.
This procedure assumes:
l The local community and the remote partner both use Interchange.
l Both parties use AS3 embedded SFTP. However, the steps for external SFTP are similar (see SFTP
(external) transport configuration on page 281).
l The local community’s embedded SFTP server requires the SFTP client (the remote partner) to
authenticate using a password.
l The remote partner’s embedded SFTP server requires the SFTP client (the local community) to
authenticate using a public-private key pair.
The following procedures indicate the tasks performed by the local community and the remote
trading partner.
11. Export the community profile as a partner profile. Give the public key from step 1 and the
profile file to the remote partner.
4. On the SFTP settings tab:
l Verify the Use public/private key pair authentication option is selected.
l Add the user name from the previous procedure in the User name field. This is the user
name the local community uses to connect to the remote partner's embedded SFTP server.
l Click Save changes.
The partners now are configured to exchange messages.
l Use generic MMDs on page 954
l Web Services message protocol on page 726
l ebXML on page 545
l RosettaNet on page 699
Your JMS system may have file size limitations. Check the documentation for your JMS system.
Note If you are using the Axway Integrator JMS transport for integrating Interchange with Axway
Integrator, see Integrate with Axway Integrator on page 1048.
The JMS application transport is an input and output source for messages. This is how it works:
Interchange polls the JMS server for messages in the designated inbound queue. This means that
any JMSMessage placed in the queue by another process is retrieved by Interchange, which verifies
the type of JMSMessage (BytesMessage or TextMessage). If verified, Interchange packages and
sends it to the partner. Likewise, every message Interchange receives from a partner is unpackaged,
converted to a BytesMessage or TextMessage and placed on the designated outbound queue.
For applicaton pickup exchanges, Interchange determines whether the message read from the
queue is a BytesMessage or a TextMessage. For delivery application delivery exchanges, in which
messages from partners are sent to back-end systems, you can select the JMS type (BytesMessage or
TextMessage) on the Advanced tab of the transport’s maintenance page.
When using JMS for application exchanges, configure Interchange to parse EDI and XML messages
retrieved from a back-end system for sender and receiver information.
Binary documents retrieved from the back-end must have the following metadata string parameters
appended to the BytesMessage or TextMessage: SenderRoutingId, ReceiverRoutingId and
ContentMimeType. Interchange performs routing decisions based on the string parameters.
When Interchange sends a BytesMessage or TextMessage to the back end, it includes the string
parameters SenderRoutingId, ReceiverRoutingId and ContentMimeType for all document types.
Other metadata are available for JMS messages. See Metadata definitions on page 414. Virtually all
of this metadata are copied into the JMS message when Interchange produces the message to a JMS
queue. When reading from a JMS queue, all metadata from the JMS message are copied into the
collaboration message, but it may not make sense to set some items in the JMS message. For
example it would not make sense to set the ConsumptionURL in the JMS message. Also see XML for
JMS and AQ event routers on page 1110.
Note that when Interchange encounters a metadata element containing characters that JMS cannot
recognize, it changes the offending characters into the hex representation of the ASCII code of the
characters. For example, the metadata element ediint.DocumentType becomes
ediint$2eDocumentType. The $2e is the hex representation of a period. When submitting JMS
messages to Interchange, use the properly encoded hex names to have them turned into the proper
metadata names.
In addition to using the delivery exchange wizard to configure a JMS transport, other set up is
required. Depending on your provider, follow the recommendations in the JMS transport
configuration on page 190 or JMS transport configuration on page 190 topic.
Note If BEA WebLogic is your JMS provider, there are options for ensuring proper load balancing
and fail-over when delivering messages to clustered JMS servers. One option is to configure
a distributed destination in WLS and reference its JNDI name on the JMS configuration
page in Interchange. At runtime, the JNDI lookup performed by the WebLogic JMS client
resolves the distributed destination name to a physical queue. Another option is to provide
a comma-separated list of host names in the JNDI URL field in Interchange (for example,
t3://node1:7001,node2:7002,node3:7003). At runtime, the JMS client round-robins
between the specified providers. Both options ensure load balancing and support for fail-
over. See the WebLogic documentation for how to configure these options.
Most providers
In addition to completing the JMS transport configuration page in the user interface, to enable
Interchange to use a custom JMS provider:
1. Copy the necessary JAR files for your JMS provider to <install_
directory>/Interchange/site/jars.
This directory is already part of the CLASSPATH.
2. Restart Interchange.
Troubleshooting
Note: You cannot have multiple versions of the provider JAR files in the
...Interchange/site/jars or ...Interchange/corelib/db/ directories. For example, if
you already have v7.5 IBM MQ JARs and add V8.0 JARs, you must remove the older JARS to avoid
conflicts.
In Windows environments, in some cases you may experience JAR conflicts when a provider JAR file
is added to ...Interchange/site/jars. If this the case, you can:
1. Create a new folder to contain the specific JAR files for the JMS provider.
2. Go to .../Interchange/conf and open jvmArguements.xml in a text editor.
3. Add the name of the directory containing the JAR or class files (or both) in the
jvmArguements.xml file so the server can locate the JMS and JNDI provider. Add CLASSPATH
entries under the “TE” node type, as in the following example. Entries can be either a “path”
reference or a reference to a single JAR:
4. Save the file.
WebSphere MQ
For WebSphere MQ configuration details, see WebSphere MQ configuration on page 733.
Oracle AQ
If the provider is Oracle Advanced Queuing facility (Oracle AQ), Oracle must be the external database
for Interchange and Oracle AQ must be installed.
Add a message queue on Oracle AQ. The queue payload type must be one of the following:
l SYS.AQ$_JMS_BYTES_MESSAGE
l SYS.AQ$_JMS_TEXT_MESSAGE
On the Oracle client, copy the Oracle AQ drivers aqapi.jar and jmscommon.jar. You may find
these files in the rdbms/jlib directory. Paste the files to the Interchange directory <install
directory>\Interchange\corelib\db\oracle and restart the server.
For any JMS transport for Oracle AQ that polls for messages, go to the Advanced tab on the
transport’s maintenance page and select Use transacted queue. You need to do this if the JMS
settings tab name includes the word polled. For example, JMS (polled) settings. If the settings
tab is named JMS (listener) settings, the Use transacted queue control is not available on the
Advanced tab.
If Oracle AQ is installed on Oracle 10g or later, JMS performance in listener mode may be poorer than
in polled mode. If this is the case, consult Oracle documentation or technical support about whether
to keep or change values of the following AQ parameters:
System.setProperty("oracle.jms.minSleepTime","200");
System.setProperty("oracle.jms.maxSleepTime","1000");
Once the values are determined, set identical values in the Interchange jvmArguements.xml file
at <install directory>\conf. The properties to add are:
<Property key="oracle.jms.minSleepTime">200</Property>
<Property key="oracle.jms.maxSleepTime">1000</Property>
The steps are:
1. Open the jvmArguments.xml file.
2. Scroll to the TE section (NodeType type="TE").
3. Add the min and max sleep time properties. Values are in milliseconds. The change should look
like the following snippet. The added properties are in bold.
4. Save and close the file.
JMS fields
The following fields are used in the delivery exchange wizard for configuring this transport.
Except for the user name and password, you can obtain the information needed to complete this
page from the JMS provider's documentation. The information varies depending on the provider. If
you have questions, contact your JMS provider.
l JMS type – There are two choices for acquiring messages from a JMS queue for integration
pickup and receiving messages from partners:
o Polled. Interchange polls the JMS server at intervals for messages. This is the default setting.
The polling interval and the maximum number of files to retrieve per interval can be adjusted
on the Advanced tab of the transport’s maintenance page. Although the rate at which
messages enter the system is controlled, this selection introduces latency and overhead in
checking the JMS server when the queue is empty. (If Sybase EAServer is the JMS provider,
you must select Polled.)
o Listener. The JMS server calls Interchange as soon as a message is written to its queue.
Messages are transferred as they arrive and do not wait for Interchange to poll for them.
When selected, the transport’s Advanced tab on the maintenance page has a setting for
reconnecting to the JMS server if the server goes down. However, there are no controls
related to polling, because polling does not apply. Although latency and polling overhead
are eliminated, this selection cannot control the rate at which messages enter the system,
which could overload it. (If you use WebLogic, the Allow Close In On Message check box for
the queue factory must be selected in the WebLogic user interface.)
Once polled or listener has been selected, the JMS type cannot be changed on the transport’s
maintenance page.
l JMS queue – The name of the queue. Example: XMLQueue@router1
l This queue requires a user name and password – Select this if the queue requires a user
name and password. When selected, fields appear for entering the information.
o User name – A user name for the JNDI provider. This value could be blank and is typically
provided for in the JNDI URL. However, this depends on the JNDI provider and how it is
configured.
o Password – A password for the JNDI provider. This value could be blank and is typically
provided in the JNDI URL. However, this depends on the JNDI provider and how it is
configured.
o Confirm password – Type the password again for confirmation.
l Use JNDI – Select this if a Java Naming and Directory Interface (JNDI) provider. When selected
the applicable fields display.
l JNDI URL – The network URL used to obtain access to the JNDI service provider for your JMS
service. Example: smqp://localhost:4001/timeout=10000
l JNDI factory – The name for the JNDI service provider class. Example:
com.swiftmq.jndi.InitialContextFactoryImpl
If you want a Java class for a provider other than Oracle AQ, you need the help of a
professional services consultant. Contact technical support for information.
o Parameters – These are the parameters for implementing the Java class. There are four
parameters required for the Java class for Oracle AQ. These parameters must be in the
following order:
o Host. The name of the computer running Oracle AQ.
o Database name. The name of the database that contains the message queue.
o Port. The port Oracle AQ uses to listen for messages.
o Driver type. The type of JDBC driver for connecting to the provider. For Oracle AQ, the
valid values are thin and oci8.
l Send payload via file system (delivery exchange only) – Select this option to have payloads
sent by a file system. You can specify the size of payloads to send and the path for payload files.
The receiver uses the path to retrieve the files.
Click Next if you want to name the exchange. Otherwise, click Finish.
Testing JMS
You can use the jmsTester tool to exercise the JMS client outside of Interchange. The script to start
jmsTester can be found in <install directory>\tools.
jmsTester is a console-based application that can verify the operation of the JMS client in
Interchange and a partner’s JMS server. Interchange server does not have to be running to use this
tool. You can use it on UNIX or Windows.
jmsTester duplicates the way Interchange accesses a JMS server. It is a test program to verify
interoperability with JMS servers. If you can send, list, receive and delete files on a JMS server using
jmsTester, this is a good indication Interchange can interoperate with the server.
jmsTester prompts for all the information it needs, as the following illustrates:
After prompting for the initial configuration information, you can use one of the following test
commands:
l (c)onnect
l (d)isconnect
l (s)end
l (r)etrieve
l (a)cknowledge
Prerequisites
To use this transport, on the MQSeries server side, the following elements must be properly
configured:
l Queue manager
l Queues
l Channel
l Listener
l Queue manager key database (for SSL connections)
l Certificate (for SSL connections)
Note To trade using MQ SSL, you must have a trusted SSL root certificate. Make sure your
certificates are up to date and trusted.
SSL_RSA_EXPORT1024_WITH_DES_CBC_ DES_SHA_EXPORT1024
SHA
SSL_RSA_EXPORT1024_WITH_RC4_56_SHA RC4_56_SHA_EXPORT1024
SSL_RSA_EXPORT_WITH_RC4_40_MD5 RC4_MD5_EXPORT
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 RC2_MD5_EXPORT
SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA FIPS_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA
SSL_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA
SSL_RSA_WITH_DES_CBC_SHA DES_SHA_EXPORT
SSL_RSA_WITH_NULL_MD5 NULL_MD5
SSL_RSA_WITH_NULL_SHA NULL_SHA
SSL_RSA_WITH_RC4_128_MD5 RC4_MD5_US
SSL_RSA_WITH_RC4_128_SHA RC4_SHA_US
Click Next if you want to name the exchange. Otherwise, click Finish.
Prerequisites
The application delivery resides in a community object. Before you add an application delivery you
must add a community to represent the MLLP client.
Procedure
1. In the user interface, select Trading configuration > Manage trading configuration to
open the Communities page.
2. Select the community you want to use to represent the MLLP client.
Prerequisite
You must have a community defined.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
3. Click Application pickup in the navigation graphic to open the Application pickups page.
4. Click Add an application pickup.
5. Choose the message protocol No packaging and click Next.
6. Complete the From address page and click Next.
7. Complete the To address page and click Next.
8. On the Choose transport protocol page, select MLLP and click Next.
9. Configure the MLLP server:
l Server name – Server name, for example MyServer.
l Port – MLLP Server access port on your hosting machine.
l Clients must use TLS to connect to this server – Select this option if you require TLS
for this connection.
l This server requires client authentication. The partner must present an
authentication certificate trusted by the server when connecting – If you
selected the TLS requirement option above, select this option to require your partners to
submit a certificate to verify their identity before the pickup allows the connection. Clear
this option to use non-authenticated MLLP. If you select this option, you must add an
authentication certificate for the partner.
10. Enter a name for the pickup to identify it in the user interface. Hint: Enter a name that is easily
identifiable in a list of pickups in the user interface.
11. Click Finish.
Application pickup
When a community uses the Web Services API to retrieve messages from a back-end system, the
Web Services API transport uses a global embedded Web Services API server. The application posts
messages to a URL in the following format:
http://host:5080/services/MessageService
Where:
l host is the fully qualified domain name or IP address of the computer running Interchange.
l The default port is 5080. You can modify this value.
To set up this transport for a community, you add a Web Services API server application pickup. No
other configuration is required.
The Web Services API application pickup can accept a maximum file size of about 15 megabytes.
This is because of the way the Apache web server, which is embedded within Interchange, requires
files to be written into memory. This behavior can quickly exhaust the heap memory available to the
Java virtual machine within Interchange.
The work-around to the file-size limitation is for the back-end Web Services client to send a URL of
the file’s location, rather than the file itself, to Interchange. The URL the client sends specifies where
Interchange can pick up the outbound file for packaging and sending.
After Interchange consumes the file, it places the file into a virtual data object. As the payload is not
stored in memory, it does not consume any of the JVM memory.
For a Web Services application pickup to accept a URL instead of the actual file, you do not have to
change the configuration within Interchange. However, you must have a programmer make a
change within the Web Services client that submits outbound files to Interchange.
Application delivery
When a community uses the Web Services API to send messages received from partners to a back-
end system, the Web Services API transport uses an API client to send messages to a back-end web
server. This setup requires the help of a technician or developer who is familiar with Web Services
and the Web Services Description Language (WSDL). The technician or developer needs to provide
a server implementation of the provided MessageService WSDL.
There are two ways to get the WSDL document that describes the requirements for both the server
and client:
l The first way is to set up a Web Services API server application pickup and then point a browser
to the following URL:
http://host:5080/services/MessageService?wsdl
Where host is the fully qualified domain name or IP address of the computer running
Interchange. Use localhost if the browser and Interchange are on the same computer.
l If you have the optional Software Development Kit, the second way is to get the following file in
the SDK directory tree:
sdk\wsdl\TradingEngineNodeServices\MessageService.wsdl
Sample client implementations are also available in the SDK directory tree. For more information
see the SDK Developer’s Guide.
When the back-end web server has been configured according to the WSDL requirements, you can
enter the URL for posting messages to the back-end server in the configuration field for the Web
Services API client in the delivery wizard.
Click Next if you want to name the exchange. Otherwise, click Finish.
After the transport has been set up, you have the option of sending the message payload (the
default) or only the URL that points to the payload. If you choose to send only the URL, the back-
end system uses the URL to retrieve the payload from Interchange backup directory. To enable this
option:
l Backing up files must be enabled for the WebServices API client application delivery.
l If you have set up a schedule on Interchange for deleting messages, the back-end must retrieve
the payload before the next scheduled purge occurs or the payload is lost. For information about
setting up schedules for deleting messages see Data storage, backups, and purging on page
849.
Pluggable server
The pluggable embedded server transport is available only to users who have the optional Software
Development Kit. If you are an SDK user, see the pluggable embedded server chapter in the
Interchange Developer Guide for configuration information.
Interchange supports embedded server extensibility through pluggable servers for customized
message consumption. This enables custom code to control message exchanges with any back-end
application or custom trading protocol without changing the base code.
When a customized transport protocol is desired, developers can use the pluggable server API to
create servers to run inside of Interchange.
Transport-specific tabs
l Modify an FTP (embedded) pickup or delivery on page 333
l Modify an FTP (external) pickup or delivery on page 337
l Modify an SFTP (embedded) pickup or delivery on page 349
l Modify an SFTP (external) pickup on page 352
l Modify a file system pickup or delivery on page 329
l Modify a JMS pickup or delivery on page 368
l Modify an MQSeries pickup or delivery on page 375
l Modify an MLLP application delivery on page 249
l Modify a Web Services API server application pickup or delivery on page 245
General fields
The following items are displayed on the modification screens for all types of application pickups
and application deliveries:
l Test... – Click this button to test the exchange connection.
l Enable this delivery or Enable this pickup – Select this option to enable the exchange, or
alternatively, clear the option to disable the exchange.
l Name – View or modify the display name of this pickup exchange.
l Make this the default delivery – Select this option if you have multiple deliveries and you
want this delivery to be selected for the community or partner by default.
Proxy tab
The delivery exchange wizard and maintenance pages for HTTP and HTTPS transports for partners
have fields for specifying whether connections must be made through a proxy.
Normally you do not need to define a partner proxy. Do not use this page unless your partner
requires you to connect through a proxy on their end.
If the local community is configured with a proxy, the community proxy overrides all partner
proxies. If you need both a community proxy and a partner proxy, your network administrator must
configure your local proxy outside the application, to navigate the partner proxy.
The following describes the fields for the proxy tab on the maintenance page.
For messages from partners, however, the trading engine still checks the protocol header for the
sender and receiver. A message with an unknown sender or receiver in the header is rejected.
The always parse option for inbound messages is for finding the identity of true senders or true
receivers.
For messages picked up from integration, the always parse option tells the trading engine to find
the sender or receiver in the message body. Messages from integration do not have protocol
headers.
The additional parse settings below apply.
When this parsing option is elected, communities and partners must have matching routing
IDs in the same format. For example, if the “from” address in a parsed message is
ID:interchange ID:value3:value4, the partner must have the same routing ID.
When this option is not selected, “to” and “from” addresses in messages are parsed only for
InterchangeID and ID values. For example, 1:partner is parsed as the sender and rendered
as partner1 in the user interface.
Note that TRADACOMS only has two, optional values that can be parsed. They must match
one of the following patterns:
A:
:B
A:B
Metadata message attributes are an optional feature.
You can use the following methods to attach metadata to a message:
l Message attributes template
l Fixed message attributes
o Always. The file name specifies the template. If there is no matching template, the message
fails.
o If known. The same as Always, except if there is no matching template, the default
template is used.
o Never. The default template is used.
l Message attributes template has priority over fixed message attributes – If fixed
message attributes also have been configured on this tab and there is a conflict between fixed
attributes and a message attributes template, select this option to give the template priority over
the fixed attributes. If not selected, fixed attributes have priority.
You can use both directory mapping and fixed attributes in an exchange configuration. If you do
this, make sure that the attributes do not overlap. If overlapping occurs, a fixed attribute takes
precedence over directory mapping.
Using the fields:
l Attribute name – From, the drop-down list, select an attribute name, enter a value for the
selected attribute in the Value field and click Add.
Examples:
l An attribute/value pair can trigger, for instance, a post-processing action. For more information,
see Add post-processing elements on page 906.
l if you want to do ebXML trading without using MMDs, you can add attributes that match the
required MMD elements. For more information, see Using fixed metadata on page 559.
l ediint.EmailToAddress – Overrides the “to” address set on the delivery exchange.
l ediint.EmailFromAddress – Overrides the “from” address set on the delivery exchange.
l email.EmailToAddressList – Enables sending messages to multiple recipients.
l email.EmailCcAddressList – Enables sending copies of messages to multiple recipients.
l email.EmailBccAddressList – Enables sending blind copies of messages to multiple
recipients.
Each List attribute supports multiple email addresses in a comma-separated series. For example:
Name1@domain.com,Name2@domain.com,Name3@domain.com
Do not enter email addresses in URL format. For example, do not use an address in the format:
mailto:user@domain.com
The splitter rejects documents whose control numbers do not match or are missing a trailer
segment.
This integrated utility splits interchanges, including the headers and trailers, into separate
documents containing a single interchange. If the original file contains only one interchange, the
utility produces the original file with no changes.
In Message Tracker the original unsplit document has a status of Split. When viewing the details of
the original, the document summary tab reports “Message split” and provides links to the split
payloads. When viewing the details of a split payload, the document summary tab reports “Message
is the result of a split” and provides a link to the unsplit original.
Schedule tab
Use the Schedule tab to set times for making a pickup or delivery exchange inactive while keeping
the transport in an enabled state. For example, you could set a schedule to turn off the exchange for
a few hours once a week to perform maintenance on a transport server. Note, however, that the
Schedules tab is dependent upon the configuration of the Advanced tab.
By default exchanges are active continuously. Schedules are added by day of the week and time of
day. For instance, if you select Monday 0:00 - 23:59, the exchange is on all day every Monday. If
you select Monday 8:30 - 11:30, the exchange is on from 8:30 to 11:30 a.m. and off all other times
on Mondays.
Times are expressed in 24-hour format: hh:mm or h:mm. Times are the time zone for your server.
Your server’s time zone is displayed in parentheses following the sentence Times are in your
server’s time on the Schedule tab.
When determining the length of time to set for a Schedule's "on" time, allow for a minimum of three
to four polling intervals to fully complete during that "on" time.
If you schedule down times for a pickup used by a community to receive messages from partners,
you may want to inform partners when the transport is inactive.
If you want an exchange to be active most of the time but turned off only some of the time, you
may need many schedules specifying the daily times you want the transport to be on or off. For
example, to schedule a transport to turn off between 1 and 2 p.m. each Saturday, eight schedules
are needed as follows: six daily schedules calling for the transport to run continuously Sunday
through Friday and two Saturday schedules, the first specifying the transport is on from midnight to
1 p.m. and the second specifying the transport is on from 2 p.m. to midnight.
Messages in queue when a transport turns off are suspended until the transport turns back on. For
example, if a message is picked up from an application while the transport for sending to a partner is
turned off, Message Tracker reports the status for the message as “scheduled production.” When the
transport turns on again, processing of the message continues. Similarly, retries and resends for
messages are suspended while the transport is off, but they resume at the point where they were
suspended when the transport turns back on.
To use schedules, make sure message backups are enabled for the affected transports. Unless
backups are enabled, messages in process when a transport turns off cannot be queued to resume
processing when the transport turns on again.
If you trade via the AS2 message protocol and request asynchronous receipts, your community
cannot receive receipts from partners when the sending transport is turned off. To avoid this,
request synchronous receipts or schedule a transport to be off when no messages are in process.
This chapter provides information for completing fields in the maintenance pages.
For related information, see the following chapters:
l Lockout settings for FTP (embedded) server users on page 452
l Directory path – The FTP directory associated with the user. A specific combination of user
and directory can be associated with only one exchange.
l Specify what to do when the back-end system uploads messages to subdirectories
of the directories listed above (pickup only)– Select an option:
o Allow – Enables the user to write files to any subdirectory under the root path.
o Do not allow – Enables the writing of files to a subdirectory under the root path only when
a message attribute is set up for each subdirectory level.
Example without the original file extension:
z47e4120_4ce
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to a
back-end application or resend messages to partners. Backup files are stored in \<install
directory>\common\data\backup, unless you specify otherwise.
l Restrict maximum file size for this transport – Optionally lets you specify the maximum
size of files a transport can handle.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log.
Express the maximum size in bytes. Do not use commas. For example, a kilobyte is 1024 bytes, a
megabyte is 1048576 bytes, a gigabyte is 1073741824 bytes. The smallest maximum allowed is
1000 bytes. On the opposite extreme, you can enter the largest number the field can
accommodate.
In most cases, use binary mode, (default). Always trade packaged files (for example, AS2, AS3,
Secure file) in binary mode.
Use binary mode also for trading text files. This applies to text files with no packaging if the
receiver is not sensitive to the type of line-ender. If the receiver requires a particular line-ender,
select an ASCII option to have Interchange translate the line-ender based on what is required by
the back-end system.
Three ASCII options are available for pickup exchanges, but only one for delivery exchanges.
The FTP specification requires the sender to always use CRLF as the line-ender when transmitting
files in ASCII mode. It is up to the receiver to translate the line-ender to something else if desired.
l Use passive mode (delivery only) – Select this option to transmit files using passive mode. In
this mode, during the connection, the server specifies the port it will listen to for the data
connection.
l Use active mode (delivery only) – Select this option to transmit files using active mode. Then
in the Active ports field, enter the ports where the client will listen to the data port of the
server.
Note: To configure Interchange to connect to a partner's embedded FTPS server in active mode,
you must add the public key of the client server as a trusted SSL root certificate on the FTPS
embedded server used for the pickup/delivery exchange.
But you can use the following because a period is the first character of the inbox directory
name:
c:\data\pickup\.inbox
When receiving files from a partner, we recommend that your partner write files to the inbox
directory first and then move them to the pickup directory when they are ready to be
retrieved. This process is automatic if your partner also uses Axway products B2Bi,
Interchange or Activator. If the partner uses other software to upload files to your server, the
software should be configured to initially upload the files to the inbox directory and move
them to the pickup directory when they are ready to be retrieved.
For outbound integration, the back-end system must write the message to the inbox and
then move it to the pickup directory.
For inbound integration and sending outbound to partners, Interchange writes to the inbox
and then moves the message to the pickup directory.
o Use special extension in pickup directory for temporary files – If you prefer not to
use an inbox, select this option. While a file is being written to the pickup directory, a
temporary extension is added so the system knows not to retrieve it because the file is only
partially written. Once fully written, the temporary extension goes away and the file can be
retrieved.
l Attempt restarts – Indicates whether the system resumes transferring large files at the point
interrupted when a connection is lost before a transfer is completed. If you select this check box,
the system resumes processing of files at least as large as specified in the restartable minimum
bytes field. This checkpoint-restart feature is worthwhile only for large documents. If this option
is not used, the system starts a file transfer over when processing is interrupted.
o Restartable minimum bytes (MB) – If attempt restarts is selected, the minimum size of a
file that triggers the system to continue the file transfer at the point interrupted before the
connection was lost. The minimum size is in megabytes. The system only resumes transfers
of files that meet this minimum. The system starts over the transfer of smaller files whose
processing is interrupted.
o Temporary file lifetime (hours) – If attempt restarts is selected, how long the system
retains a file whose transfer has been interrupted while waiting for the connection to be
restored. This temporary file enables the system to resume the transfer at the point
interrupted.
Example without the original file extension:
z47e4120_4ce
If you want to add a new command set file, create the file and add an entry for it in
filereg.xml. For example, if your new command set is called myftpcommandset.xml, enter
that name in the field and add the following entry to filereg.xml:
<File name="myftpcommandset.xml" path="conf/myftpcommandset.xml"/>
* One or more characters.
? Any single character.
[ ] Matches any single character within the brackets. For example, r[aou]t matches
rat, rot and rut.
, Commas can be used as and/or operators within brackets (for example, r[a,o,u]t).
- Use hyphens within brackets to specify ranges of letters or numbers. For example,
[0-9] is for any number between 0 and 9, and [A-Za-z] is for any upper- or lower-
case letter.
. Use the character dot to separate the file name and extension. For example, *.txt.
| Use the pipe character to separate multiple file name formats. For example,
*.edi|*.txt|[a,b,c]?.xml.
Specify with the radio buttons whether the filter pattern is inclusive or exclusive. If inclusive,
only files matching the pattern are consumed. If exclusive, files matching the pattern are
ignored, but all other files are consumed.
Interchange ignores files that do not meet filtering conditions. Ignored files are not reported in
Message Tracker. Such files also do not generate log messages unless the following property is
set to debug in conf\log4j.properties:
log4j.category.com.cyclonecommerce.tradingengine
Backup files are stored in \<install directory>\common\data\backup, unless you
specify otherwise.
l Restrict maximum file size for this transport – Optionally lets you specify the maximum
size of files a transport can handle. If Interchange receives a file larger than the maximum, the
file is rejected and a message is written to the events log. If received via HTTP, a 413 response
also is sent and the connection is closed. A 413 message is Request Entity Too Large.
The maximum size must be expressed in bytes. Do not use commas. For instance, a kilobyte is
1024 bytes, a megabyte is 1048576 bytes, a gigabyte is 1073741824 bytes.
The smallest maximum allowed is 1000 bytes. On the opposite extreme, you can enter the
largest number the field can accommodate.
This control is available only for transports used for picking up messages from integration or
receiving messages from partners.
l Polling configuration:
o Maximum files per polling interval – The highest number of messages the system can
retrieve each time it polls.
o Polling interval (seconds) – The interval in seconds Interchange waits before polling for
messages to retrieve.
l Consumption order:
o Allow server to determine – This is the default behavior. Interchange processes
messages in a random order.
o Process by timestamp (oldest first)– Select this option if you want Interchange to process
messages in the order oldest-to-newest. The external FTP server must support the MDTM
command.
If you select this option, the value of the field "Maximum concurrent connections" is
automatically set to "1".
Note: In some cases setting concurrent connections to "1" may cause reduced throughput.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for both application and trading deliveries.
This is a way to allocate messages among nodes in a clustered environment. When the maximum
is reached, another node is contacted to take messages and so on. This field is not applicable in
a single node environment.
l Maximum messages per connection – This value specifies the maximum number of
messages to be consumed over a single connection before the connection is closed and
reopened on another processing node. This setting effectively controls load balancing. The
default setting of 1 achieves optimal load balancing at the cost of greater overhead per message.
Depending on your message volume and the load on each node, this value could be increased to
avoid the overhead associated with reconnecting to the transport server, at the cost of a less
well-balanced cluster.
This setting applies to the following types of exchanges: FTP, SFTP, JMS, MQSeries, POP, X420,
X435, and Pluggable Server.
This setting is applicable in clustered environments when more than one Interchange node is
configured.
l Specify preferred nodes – If there are one or more nodes for Interchange, you can select one
or more as the preferred nodes for consuming messages. If the preferred nodes are running,
these are used to process messages. If the preferred nodes are stopped, work is distributed
among the remaining running available nodes. Selecting preferred nodes lets you manage work
distribution among nodes.
This option is available for integration pickup and trading delivery exchanges that poll for
messages.
In general, this setting should not be used. Usually it is best to let Interchange automatically
determine which node should be responsible for initiating the polling of which exchange point.
This setting is useful if you have a cluster that spans geographical locations and each location
has its own local transport servers. In this situation, you would use this setting to ensure the
exchange points associated with the transport servers are assigned to nodes in the vicinity of the
transport servers. If you have a Peer Network license, note that these settings are not cloneable.
l Zone – If you use DMZ nodes and want to send or receive messages via a specific DMZ zone,
select the zone. This field is available only when the user license supports Secure Relay and a
DMZ zone has been added. For details, see Secure Relay DMZ nodes on page 474.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, re-sends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Connect timeout (seconds) – Time in seconds Interchange waits for a connection to the
delivery exchange before the attempt times out. Although the default value is 30 seconds, this
may be longer than the interval allowed by your operating system (OS). For example, Windows
XP by default allows a maximum timeout of 20 seconds. The actual connect timeout interval is
the lesser of the OS timeout and the value set in Interchange.
l Read timeout (seconds) – Time in seconds Interchange waits to read data from the delivery
exchange before terminating the connection.
l User commands – Enter user commands such as SITE to be sent to the server after login.
Commands must be entered in the exact case and format expected by the server. For example,
most FTP clients allow “mkdir test”, but most servers only accept “MKD test”. Consult RFC 959
for a list of standard FTP commands. You can use FTP commands that do not make use of the
FTP data connection. Commands that make use of the FTP data connection are not supported.
In addition, specific servers may support other commands. Refer to the server documentation for
more information.
If any command fails, the remaining commands are not executed, and production to the FTP
server fails. To avoid possible failures, preface any command with an “at” sign (@) to indicate
that errors from that command should be ignored, for example, “@MKD test”. Preface any
command with an asterisk to cause the entire line to be treated as a comment, for example,
“*Create test directory”.
This field is available for the FTP transport only.
If you want to add a new command set file, create the file and add an entry for it in
filereg.xml. For example, if your new command set is called myftpcommandset.xml, enter
that name in the field and add the following entry to filereg.xml:
<File name="myftpcommandset.xml" path="conf/myftpcommandset.xml"/>
* One or more characters.
? Any single character.
[ ] Matches any single character within the brackets. For example, r[aou]t matches
rat, rot and rut.
, Commas can be used as and/or operators within brackets (for example, r[a,o,u]t).
- Use hyphens within brackets to specify ranges of letters or numbers. For example,
[0-9] is for any number between 0 and 9, and [A-Za-z] is for any upper- or lower-
case letter.
. Use the character dot to separate the file name and extension. For example, *.txt.
| Use the pipe character to separate multiple file-name formats. For example,
*.edi|*.txt|[a,b,c]?.xml.
Specify with the radio buttons whether the filter pattern is inclusive or exclusive. If inclusive,
only files matching the pattern are consumed. If exclusive, files matching the pattern are
ignored, but all other files are consumed.
Interchange ignores files that do not meet filtering conditions. Ignored files are not reported in
Message Tracker. Such files also do not generate log messages unless the following property is
set to debug in conf\log4j.properties:
log4j.category.com.cyclonecommerce.tradingengine
If the partner or back-end system uses the same account to upload messages, you must configure a
separate directory for uploads on a delivery exchange.
If no account exists, click Add to add an account and associated directory.
If the partner or back-end system uses the same account to pick up messages, you must configure a
separate directory for pickups on a pickup exchange.
If no account exists, click Add to add an account and associated directory.
An external SFTP pickup resides outside of Interchange.
To add a key, click Certificates in the navigation graphic at the top of the community summary
page. Select the SSH keys tab. Click Add an SSH key, follow the prompts and click Add.
Select the key as the default SSH key after it has been added. For more information see Public-
private key and password authentication on page 292.
l Use host-based authentication – This is not used.
Directories tab
l Pickup directory – Type the path of the directory on your server where messages are picked
up. When Interchange polls the server for files, it only looks in the pickup directory, not an
inbox directory.
l Use temporary files to avoid read/write collisions – We recommend using this option to
prevent Interchange from attempting to retrieve partially written files. When this is selected, you
must select one of the two following options.
o Use separate directory for temporary files – Type the full path of an inbox directory
(for example, c:\data\inbox). Files are uploaded to this directory. When fully written,
files are moved to the pickup directory for retrieval.
Do not put the inbox under the pickup directory unless you use a period at the beginning of
the inbox name. Interchange and other applications ignore directories and files that begin
with periods.
For example, do not use the following directory structure:
c:\data\pickup\inbox
But you can use the following because a period is the first character of the inbox directory
name:
c:\data\pickup\.inbox
When receiving files from a partner, we recommend that your partner write files to the inbox
directory first and then move them to the pickup directory when they are ready to be
retrieved. This process is automatic if your partner also uses Axway products B2Bi,
Interchange or Activator. If the partner uses other software to upload files to your server, the
software should be configured to initially upload the files to the inbox directory and move
them to the pickup directory when they are ready to be retrieved.
For outbound integration, the back-end system must write the message to the inbox and
then move it to the pickup directory.
For inbound integration and sending outbound to partners, Interchange writes to the inbox
and then moves the message to the pickup directory.
o Use special extension in pickup directory for temporary files – If you prefer not to
use an inbox, select this option. While a file is being written to the pickup directory, a
temporary extension is added so the system knows not to retrieve it because the file is only
partially written. Once fully written, the temporary extension goes away and the file can be
retrieved.
Filenames tab
l Preserve original filenames – Select this if you want original file names to be preserved
when Interchange delivers messages. For binary messages, we recommend that you preserve
original file names. Otherwise, Interchange assigns a unique file name that does not readily
identify the contents of the file. Preserving original file names also allows your back-end
application to process binary messages based on their file names. This field applies to both
application and partner deliveries.
l Overwrite duplicate filenames – An option when you choose to preserve original file names.
If duplicate file names are detected, Interchange overwrites the existing file.
l Sequentially number duplicate filenames – An option when you choose to preserve
original file names. If duplicate file names are detected, Interchange appends a number to the
new file. For most transports, the appended number is consecutively numbered. For FTP and
SFTP, however, the appended number is hexadecimal and looks like this: filename_c4.
l Generate unique filenames – Select to have the system provide a unique file name instead of
using the original name. This field applies to both application and partner deliveries. When
selected, files are given arbitrary names. The names always have less than 30 characters and
often have less than 20 characters.
Appended to the file name is a hex representation of a monotonically increasing file name
counter that is maintained in the database and guaranteed to be unique across all nodes in a
cluster. In addition, if the original file name had an extension, the same extension is appended
to the unique name the system generates.
The following are examples of unique file names generated by the system, one with the original
file extension and one without:
o dabeed45_4cb.edi
o z47e4120_4ce
Advanced tab
l Maximum concurrent connections (for trading pickups only) – The number of total open
connections Interchange server can make to a partner. If you are operating in a cluster
environment, this is the total number across the entire cluster, no matter how many JVM nodes
are running. For example, if the value is 100 connections and there are 150 messages to
consume, Interchange opens only 100 connections to that partner. The remaining 50 messages
are queued until connections become available.
l Maximum concurrent connections – The number of total open connections Interchange
server can make to a partner. If you are operating in a cluster environment, this is the total
number across the entire cluster, no matter how many JVM nodes are running. For example, if
the value is 100 connections and there are 150 messages to send, Interchange opens only 100
connections to that partner. The remaining 50 messages are queued until connections become
available.
The default value is suitable in almost all cases. However, if a partner says Interchange is over
running his receiving system, decrease the value. (This advice does not apply to OFTP X.25 or
X.25 over ISDN, as the default maximum value is 1 for those transports.) If sending messages to
Transfer CFT via PeSIT, the value in this field must be less than the CFTTCP setting in Transfer
CFT. This setting applies only to transports that send messages to partners or deliver messages to
integration.
l Retries – This is the number of times Interchange will retry connecting to the partner’s
transport if the initial attempt to connect and send the message failed. The following are
common reasons for triggering retries.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Read timeout (seconds) – How long in seconds that Interchange waits to read data from the
delivery exchange before terminating the connection.
l Override SSH ciphers – Select this check box to specify, using the Add and Remove
buttons, the specific ciphers supported for the server. If not selected, all ciphers are supported
by default. The default is less secure than specifying only certain ciphers. This check box is
available for production delivery exchanges.
The default order in the Available column is the preferred order of use. Once ciphers are moved
to the Selected column, you can arrange the order. Interchange uses the ciphers in the order
listed.
l Maximum block size per downloading packet – Sets the maximum size of the packets that
can be downloaded from an external SFTP server by the SFTP client within Interchange. The
client downloads messages in a series of data packets. By default the maximum size is 32768
data packet units. The default value is compatible with most SFTP servers. But when handling
messages of a certain size (2-3 megabytes or larger), some servers cannot process many packets
of the default size and downloading hangs. If this occurs, reduce the packet size maximum.
Adjusting the value is a trial-and-error process. You may have to test several values depending on
the size of the messages being processed. For example, when messages are approximately 3 MB
in size, the maximum packet size can be set at 4096. This field is available only on the trading
and application pickup exchanges.
l Enable file filtering – Available for some exchanges used for application pickups and for
receiving from partners, file filtering allows Interchange to discriminate which files to consume
based on file names. In the file name filter pattern field, type the formats of the files you want
the transport to consume or ignore. Use conventional wildcard characters for file names or
extensions or both. The following describes the supported characters and symbols:
* One or more characters.
? Any single character.
[ ] Matches any single character within the brackets. For example, r[aou]t matches
rat, rot and rut.
, Commas can be used as and/or operators within brackets (for example, r[a,o,u]t).
- Use hyphens within brackets to specify ranges of letters or numbers. For example,
[0-9] is for any number between 0 and 9, and [A-Za-z] is for any upper- or lower-
case letter.
. Use the character dot to separate the file name and extension. For example, *.txt.
| Use the pipe character to separate multiple file-name formats. For example,
*.edi|*.txt|[a,b,c]?.xml.
Specify with the radio buttons whether the filter pattern is inclusive or exclusive. If inclusive,
only files matching the pattern are consumed. If exclusive, files matching the pattern are
ignored, but all other files are consumed.
Interchange ignores files that do not meet filtering conditions. Ignored files are not reported in
Message Tracker. Such files also do not generate log messages unless the following property is
set to debug in conf\log4j.properties:
log4j.category.com.cyclonecommerce.tradingengine
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners. Backup files are stored in \<install
directory>\common\data\backup, unless you specify otherwise.
l Restrict maximum file size for this transport – Optionally lets you specify the maximum
size of files a transport can handle.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log. If received via HTTP, a 413 response also is sent and the connection is
closed. A 413 message is Request Entity Too Large. The maximum size must be expressed in
bytes. Do not use commas. For instance, a kilobyte is 1024 bytes, a megabyte is 1048576 bytes,
a gigabyte is 1073741824 bytes. The smallest maximum allowed is 1000 bytes. On the opposite
extreme, you can enter the largest number the field can accommodate. This control is available
only for transports used for picking up messages from integration or receiving messages from
partners.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for both application and trading deliveries.
l Maximum files per polling interval – The highest number of messages the system can
retrieve each time it polls.
l Polling interval (seconds) – The interval in seconds Interchange waits before polling for
messages to retrieve.
l Zone – If you use DMZ nodes and want to send or receive messages via a specific DMZ zone,
select the zone. This field is available only when the user license supports Secure Relay and a
DMZ zone has been added. For details, see Secure Relay DMZ nodes on page 474.
Example without the original file extension:
z47e4120_4ce
The default value is suitable in almost all cases. However, if a partner says your trading engine is
overrunning his receiving system, decrease the value. (This advice does not apply to OFTP X.25
or X.25 over ISDN, as the default maximum value is 1 for those transports.)
If sending messages to Transfer CFT via PeSIT, the value in this field must be less than the
CFTTCP setting in Transfer CFT.
This setting applies only to transports that send messages to partners or deliver messages to
integration.
l Retries – The number of times Interchange retries connecting to the partner’s transport if the
initial attempt to connect and send the message failed. The following are common reasons for
triggering retries.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from the back end or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners. Backup files are stored in \<install
directory>\common\data\backup, unless you specify otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands.
This option is available for application and trading pickups that poll for messages.
In general, this setting should not be used. Usually it is best to let Interchange automatically
determine which node should be responsible for initiating the polling of which exchange point.
This setting is useful if you have a cluster that spans geographical locations and each location
has its own local transport servers. In this situation, you would use this setting to ensure the
exchange points associated with the transport servers are assigned to nodes in the vicinity of the
transport servers. If you have a Peer Network license, note that these settings are not cloneable.
Note: There can be only one Interchange per (clustered) host. In this case you can p ick which
trading engine (that is, which host) performs the work.
If the back-end system uses the same account to upload messages, you must con figure a separate
directory for that purpose on a pickup exchange.
If no account exists, click Add to add an account and associated directory.
l JNDI factory – The name for the JNDI service provider class. Example:
com.swiftmq.jndi.InitialContextFactoryImpl
If you want a Java class for a provider other than Oracle AQ, you need the help of a
professional services consultant. Contact Axway technical support for information.
o Parameters – There are four parameters required for the Java class for Oracle AQ. These
parameters must be in the following order:
o Host. The name of the computer running Oracle AQ.
o Database name. The name of the database that contains the message queue.
o Port. The port Oracle AQ uses to listen for messages.
o Driver type. The type of JDBC driver for connecting to the provider. For Oracle AQ, the
valid values are thin and oci8.
l Send payload via file system(delivery only)– Select this check box to have payloads sent by
a file system. You can specify the size of payloads to send and the path for payload files. The
receiver uses the path to retrieve the files.
polling of which exchange point. This setting is useful if you have a cluster that spans
geographical locations and each location has its own local transport servers. In this situation,
you would use this setting to ensure the exchange points associated with the transport servers
are assigned to nodes in the vicinity of the transport servers.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it. Retries occur
according to an algorithm that starts at 5 minutes. The interval between retries increases with
each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60 minutes. The
interval plateaus at 60 minutes. This means if the retry value is greater than 5, the fifth and each
subsequent retry occurs at 60 minute intervals. For example, if retries is 3, the system will try
connecting again in 5 minutes if the initial connection attempt fails. If this retry attempt also
fails, the system attempts a second retry in 10 minutes. The third retry attempt is made 15
minutes later. If the third retry attempt fails, the message is given a failed status. So after four
attempts (the first attempt plus 3 retries), the message fails. You can search for and manually
resubmit failed messages in Message Tracker. Retries do not occur precisely at these intervals
because each connection attempt takes some seconds, which varies by computer. So retries
actually occur after the connection attempt time plus the interval. This control applies only to
retrying to send messages, not receiving. It applies only to retrying to send related to transport
issues. It does not apply to successfully sent messages for which receipts have not been received
as expected. Another control, resends, determines how many times the system will resend a
message when a receipt is not received from the partner. For information about resends, see
reliable messaging in the collaboration settings chapter.
l Message Type – Specifies the JMS message class. This field applies only to JMS when used for
receiving messages from partners or integration delivery.
o BytesMessage. A BytesMessage object is used to send a message containing a stream of
uninterrupted bytes. It inherits from the Message interface and adds a bytes message body.
o TextMessage. A TextMessage object is used to send a message containing a
java.lang.String. It inherits from the Message interface and adds a text message body.
l Use transacted queue – Select this option if the provider is Oracle AQ. Otherwise, do not
select it.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners. Backing up files.
This is required for the system to perform fail-over operations such as attempting to send
messages again (retries) in case of a transport connection failure. Without backups, a message
in process cannot be recovered if the server or a processing node stops or restarts. Backups are
needed to resubmit messages to back-end applications or resend messages to partners. Backup
files are stored in \<install directory>\common\data\backup, unless you specify
otherwise.
l Post Processing script – The full path to an executable file that contains post-processing
commands.
Use application segmentation if:
o Messages are too large to be handled by the application in a single buffer,
o Data conversion must be performed by sender channels and the format is such that the
putting application must specify the segment boundaries to make possible the conversion of
individual segments.
l This server requires a user name and password – If selected, enter a user name and
password to connect to the server.
l Use SSL to connect to the IBM MQSeries server – If this option is not selected, you can
select this option and then select a cipher suite from the list of available suites. If this option is
already selected (because it was selected when the exchange was added), you cannot deselect
it. If you want to deactivate SSL on this exchange you must delete the exchange and then create
a new exchange without the SSL option.
Note: If you select this option you must add a trusted certificate for access to the IBM MQSeries
server after completing the configuration of this delivery exchange.
When you select this option you must also complete the Select the SSL cipher suite field.
From the drop down list, select the SSL cipher suite to use for the connection. The value must
match the cipher suite that is configured for the channel on the MQSeries server. The following
cipher suites are displayed, however not all of these suites are currently supported.
SSL_RSA_EXPORT1024_WITH_DES_CBC_ DES_SHA_EXPORT1024
SHA
SSL_RSA_EXPORT1024_WITH_RC4_56_SHA RC4_56_SHA_EXPORT1024
SSL_RSA_EXPORT_WITH_RC4_40_MD5 RC4_MD5_EXPORT
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 RC2_MD5_EXPORT
SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA FIPS_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA
SSL_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA
SSL_RSA_WITH_DES_CBC_SHA DES_SHA_EXPORT
SSL_RSA_WITH_NULL_MD5 NULL_MD5
SSL_RSA_WITH_NULL_SHA NULL_SHA
SSL_RSA_WITH_RC4_128_MD5 RC4_MD5_US
SSL_RSA_WITH_RC4_128_SHA RC4_SHA_US
l Message persistence – Applicable only for outbound messages. Select a message persistence
mode:
o Non-persisted – No persistence. Messages may be lost.
o Persisted – Messages survive failures or restarts. This overrides the persistence configured
for the queue.
o As defined by the queue – Messages are persisted according to the queue configuration.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field applies to both application and partner deliveries.
l Maximum messages per connection – This value specifies the maximum number of
messages to be consumed over a single connection before the connection is closed and
reopened on another processing node. This setting effectively controls load balancing. The
default setting of 1 achieves optimal load balancing at the cost of greater overhead per message.
Depending on your message volume and the load on each node, this value could be increased to
avoid the overhead associated with reconnecting to the transport server, at the cost of a less
well-balanced cluster.
This setting is applicable in clustered environments when more than one Interchange node is
configured.
l Specify preferred nodes – In a multi-node cluster installation of Interchange, you can select
one or more nodes as the preferred nodes for consuming messages. If the preferred nodes are
running, these are used to process messages. If the preferred nodes are stopped, work is
distributed among the remaining running available nodes. Selecting preferred nodes lets you
manage work distribution among nodes.
This option is available for application and trading pickups that poll for messages.
In general, this setting should not be used. Usually it is best to let Interchange automatically
determine which node should be responsible for initiating the polling of which exchange point.
This setting is useful if you have a cluster that spans geographical locations and each location
has its own local transport servers. In this situation, you would use this setting to ensure the
exchange points associated with the transport servers are assigned to nodes in the vicinity of the
transport servers.
Note: There can be only one Interchange per (clustered) host. In this case you can p ick which
trading engine (that is, which host) performs the work.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And
if an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5,
the fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails,
the message is given a failed status. So after four attempts (the first attempt plus 3 retries),
the message fails. You can search for and manually resubmit failed messages in Message
Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt
time plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to
retrying to send related to transport issues. It does not apply to successfully sent messages
for which receipts have not been received as expected. Another control, resends, determines
how many times the system will resend a message when a receipt is not received from the
partner. For information about resends, see reliable messaging in the collaboration settings
chapter.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners. Backing up files.
This is required for the system to perform fail-over operations such as attempting to send
messages again (retries) in case of a transport connection failure. Without backups, a message
in process cannot be recovered if the server or a processing node stops or restarts. Backups are
needed to resubmit messages to back-end applications or resend messages to partners. Backup
files are stored in \<install directory>\common\data\backup, unless you specify
otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for both application and trading deliveries.
Settings tab
l Host – The fully-qualified domain name of the computer on which the embedded server runs.
Interchange detects this setting; you cannot change it.
l Port – The port on which the server listens for connection requests. Default = 5080.
Advanced tab
l Minimum threads – Lowest number of threads Interchange must dedicate to the server.
l Maximum treads – Largest number of threads Interchange can dedicate to the server.
l Read timeout – The maximum number of seconds the server waits when reading data from a
partner.
Retries occur according to an algorithm that starts at 5 minutes. The interval between
retries increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30
minutes, 60 minutes. The interval plateaus at 60 minutes. This means if the retry value
is greater than 5, the fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second
retry in 10 minutes. The third retry attempt is made 15 minutes later. If the third retry
attempt fails, the message is given a failed status. So after four attempts (the first
attempt plus 3 retries), the message fails. You can search for and manually resubmit
failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes
some seconds, which varies by computer. So retries actually occur after the connection
attempt time plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to
retrying to send related to transport issues. It does not apply to successfully sent
messages for which receipts have not been received as expected. Another control,
resends, determines how many times the system will resend a message when a receipt is
not received from the partner. For information about resends, see reliable messaging in
the collaboration settings chapter.
Also, in rare cases a partner’s HTTP server may be unable to handle chunked messages,
regardless of message size. You should perform tests to determine whether a partner’s server can
handle chunked messages. If not, the partner must use Interchange with the embedded server to
receive large chunked messages successfully.
If you enable chunking because of large messages, you also probably need to request that
receipts be sent over an asynchronous connection. See the chapter on collaboration settings for
details.
l Attempt restarts – Select this option to turn on checkpoint-restart. A checkpoint is
information saved to disk that is a recovery point in the event of a transport failure. The restart
program uses the last saved checkpoint and starts again, ensuring no loss of data.
The checkpoint files are saved on the server under the <install
directory>/common/data/http/restartable, which is normally common to all nodes in
the cluster. Thus, if a transfer is interrupted and the load balancer directs the restart request to a
different node, the restart file will be accessible to the new node even though it did not process
the original request.
To reduce unnecessary overhead when processing small files, checkpoint files are only created
for messages that are at least 100 KB in size. Also, if a restart is attempted for a message whose
checkpoint file on the server is more than four hours old, the checkpoint file will be discarded
and the entire message will be retransmitted.
The restart logic is used only during transport retries, such as might occur when a transfer is
interrupted due to network problems. If you resubmit a message in Message Tracker, no attempt
is made to perform a checkpoint-restart.
This feature only works if your partner uses Interchange and its embedded HTTP server. Do not
select this option if a partner uses an external or staged HTTP server or uses a trading engine
other than Interchange.
l Enable use of 102-processing – This option is available to ensure that the connection
between the client and server does not become idle and fail while message processing is in
progress. For example, this makes sure the connection remains active when the client is sending
a multi-gigabyte message. Or, to prevent a firewall from disconnecting an idle connection before
the server receives the entire message and returns a 200 OK response. Most often this setting is
useful when the client requests a synchronous receipt, but also could be recommended in some
cases for an asynchronous receipt.
Selecting this option directs Interchange to add the following to the header of an outbound
message: Expect: 102-processing. This is an HTTP response code that indicates processing
is in progress. If the receiving server supports 102 responses, the header triggers the server to
send 102 responses to the client repeatedly until the server has completely processed the
inbound message.
Before selecting this option, make sure the server supports 102 responses. If you turn on 102
processing and the server does not support it, the server will return a 417 message (the server
could not meet the expectation given in the Expect header) and the connection may fail. If the
receiving partner uses the embedded HTTP server in Interchange 5.5.1 or later, 102 responses
are supported. This also is supported if your partner uses Jetty 6 or later.
Filenames tab
Example without the original file extension:
z47e4120_4ce
Schedule tab
See Schedule tab on page 208.
Advanced tab
l Maximum concurrent connections – The number of total open connections Interchange
server can make to a partner. If you are operating in a cluster environment, this is the total
number across the entire cluster, no matter how many JVM nodes are running. For example, if
the value is 100 connections and there are 150 messages to send, Interchange opens only 100
connections to that partner. The remaining 50 messages are queued until connections become
available.
The default value is suitable in almost all cases. However, if a partner says your trading engine is
overrunning his receiving system, decrease the value. (This advice does not apply to OFTP X.25
or X.25 over ISDN, as the default maximum value is 1 for those transports.)
l Retries – The number of times Interchange retries connecting to the partner’s transport if the
initial attempt to connect and send the message failed. The following are common reasons for
triggering retries.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners. Backup files are stored in \<install
directory>\common\data\backup, unless you specify otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands.
To address tab
See From address and To address tabs on page 204.
Schedule tab
See Schedule tab on page 208.
Advanced tab
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners. Backup files are stored in \<install
directory>\common\data\backup, unless you specify otherwise.
l Restrict maximum file size for this transport – Optionally specify the maximum size of
files that this transport can handle. If Interchange receives a file larger than the maximum, the
file is rejected and a message is written to the events log.
l Maximum files per polling interval – The highest number of messages the system can
retrieve each time it polls.
l Polling interval (seconds) – The interval, in seconds, Interchange waits before polling for
messages to retrieve.
l FTP external
l FTP embedded
l File system
For each of these delivery types, you can select the option to define a naming construction pattern
for the new generated file names and for automatic duplicate file naming. To configure the resulting
file naming, you must enter a naming pattern in the Pattern field.
The information in this chapter also applies to fields you complete for the:
l Message Handler file renaming action
l PeSIT delivery configuration
The values you can enter in the Pattern field vary depending on the use case.
l Literal strings
l %metadata name% – You can use any metadata attribute associated with the FTP or File System
delivery. You cannot use Custom attributes.
l $filename$
l $extension$
l $timestamp$– Where timestamp is a shortcut for SimpleDateFormat string
‘yyyyMMddHHmmssSSS’.
l $sequence$ – This is a monotonically increasing counter. A different counter is maintained for
each delivery exchange. A Message Handler rule uses a single global counter.
l $any legal Java SimpleDateFormat string$
Examples
The incoming file name (before any renaming takes place) is represented by the tags $filename$
and $extension$. For example, an incoming file named TestFile1.txt would have the name
defined by the tags:
l $filename$ = TestFile1
l $extension$ = .txt ( note that the dot is included)
You could enter the following patterns in the Pattern field to obtain the following results.
New$filename$$extension$ NewTestFile1.txt
My$filename$_$sequence$$extension$ MyTestFile1_53.txt
$filename$_$sequence$$extension$ TestFile1_54.txt
You must include $filename$.
You must enter at least one of the following elements, in order to ensure that a unique name is
generated for the duplicate:
l $sequence$ – This is the sequence number calculated from all delivery file names handled on
all deliveries
l $timestamp$
l $filesequence$ – This variable is only allowed in the duplicate file naming case (not the file
naming case above). It is calculated from only the file names handled on the specific delivery
where you set the pattern. It is recommended that you use $ sequence$ instead of
$filesequence$ because $filesequence$ consumes g reater processing resources.
l $any legal Java SimpleDateFormat string$
Example:
1. A pickup consumes the file My.txt.
2. You have configured the Message Handler with the File Rename Rule Pattern
$filename$File$extension$.
Filename result = MyFile.txt
3. A file system delivery is configured with the File Rename Pattern
$filename$$extension$.backup .
Filename result = MyFile.txt.backup
4. Suppose Interchange detects a filename duplicate - the file MyFile.txt.backup already
exists at the delivery location. You have configured the file system delivery with a
Duplicate Rename Pattern $filename$_$timestamp$$extension$.
Filename result = MyFile.txt20130215113703512.backup
If the $extension$ tag did not have the dot, there would be many situations when you would
have to enter a pattern such as $filename$.$extension$, which produce defective results when
the incoming file name had no extension at all.
Examples:
Incoming file=FileWithoutExension with pattern $filename$. $extension$ is renamed
FileWithoutExension.
Incoming file=FileWithoutExension with pattern $filename$. $extension$.backup is renamed
FileWithoutExenstion..backup. ( Note the duplicate dot in the result).
To prevent this error, the extension tag includes the full extension, if any, including the dot.
Therefore $filename$$extension$ tags work in all cases, without problem.
Partner deliveries are located in partner objects. A partner delivery specifies how a community
sends documents to a remote partner.
The user interface lists trading pickups and partner deliveries by the message protocol they use for
trading. A message protocol supports one or more transports.
Your local community and trading partner can use the same or a different message protocol for
exchanging messages. However, if you use different protocols, you must be prepared to return
receipts via the same protocol as the payloads were received. The partner should configure his
system likewise.
The following figure illustrates a trading relationship where the local community and the remote
trading partner use different message protocols. The community prefers receiving payloads via the
AS1 protocol. The partner prefers receiving payloads via AS2. To accommodate these preferences,
both parties must be prepared to send and receive via AS1 and AS2. In this scenario, the community
receives a payload via AS1 and returns a receipt to the sending partner via AS1. Meanwhile, the
community sends a payload via AS2 and receives a receipt from the receiving partner via AS2. This
figure shows the community and partner send via different message protocols.
In the figure above, on the community side, AS2 is the designated default protocol for sending in
the partner profile. On the partner side, AS1 is the default for sending. This is necessary because
Interchange uses the default protocol in the partner profile for sending payloads. See Search and
display collaboration settings on page 910.
The following table lists the message protocols and related transports communities and partners can
use for exchanging messages. The message protocols you can use depends on your user license.
Select Help > License information on the top toolbar in the user interface to see what protocols
your license supports. Communities also require application pickup and delivery exchanges. For
information about these exchanges, see Application deliveries on page 162 and Application pickups
on page 160.
The following table shows the pickup and delivery types you can use to support various message
protocols in Interchange. The packaging options column indicates whether a message protocol
supports signing and encryption of messages using digital certificates. It also indicates whether
message compression is supported.
Embedded SMTP
SMTP/POP
No packaging notes
The pluggable embedded server transport is available only to users who have the optional Software
Development Kit. If you are an SDK user, see the pluggable embedded server chapter in the SDK
Developer’s Guide for configuration information.
For other conditions about trading via the generic email protocol, see Email client partners on page
579.
Selecting this option enables Interchange to send messages successfully to Axway Gateway via
secure file HTTP.
Upon receiving a secure file HTTP message from Interchange, Axway Gateway expects to find the
payload’s file name in the HTTP POST request URL. Normally, Interchange does not include this. But
when the option is selected, Interchange appends ?filename=name to the URL, where name is
the production file name.
Common pages:
l From address and To address wizard fields on page 263
View the following topics for information on configuring specific trading pickup types:
l File system transport configuration on page 189
l JMS transport configuration on page 294
l IBM MQSeries transport configuration on page 300
l Staged HTTP on page 958
l FTP (external) transport configuration on page 272
l FTP (embedded) transport configuration on page 275
l SFTP (external) transport configuration on page 281
l SFTP (embedded) transport configuration on page 286
l OFTP transport configuration on page 617
l Add or modify a PeSIT trading pickup (polling client) on page 684
l Add or modify a PeSIT trading pickup ( embedded server) on page 689
l X.400 trading configuration on page 740
l Secure file message protocol on page 971
l ebXML on page 545
l Send ebXML via an intermediary on page 562
Prerequisite
You must have a partner. See Add a partner on page 143.
Procedure
1. In the user interface, select Partners > Manage partners.
2. From the list of partners, click the name of a partner to display the Summary page for that
partner.
3. Click the Partner delivery icon in the navigation graphic to open the Partner deliveries page.
4. Click Add a delivery to open the exchange wizard.
5. Choose a message protocol to use to deliver messages to the partner and click Next.
6. Complete the fields of the following pages. The pages and fields vary depending on the
transport protocol you selected in the previous step.
Common pages:
l From address and To address wizard fields on page 263
View the following topics for information on configuring specific exchange types:
l File system transport configuration on page 189
l FTP (external) transport configuration on page 272
l FTP (embedded) transport configuration on page 275
l SFTP (external) transport configuration on page 281
l SFTP (embedded) transport configuration on page 286
l JMS transport configuration on page 294
l IBM MQSeries transport configuration on page 300
l Secure file message protocol on page 971
l ebXML on page 545
l Send ebXML via an intermediary on page 562
Common pages:
l From address and To address wizard fields on page 263
View the following topics for information on configuring specific trading pickup types:
l File system transport configuration on page 189
l JMS transport configuration on page 294
l IBM MQSeries transport configuration on page 300
l Staged HTTP on page 958
l FTP (external) transport configuration on page 272
l FTP (embedded) transport configuration on page 275
l SFTP (external) transport configuration on page 281
l SFTP (embedded) transport configuration on page 286
l OFTP transport configuration on page 617
l Add or modify a PeSIT partner delivery on page 675
l Add or modify a PeSIT trading pickup (polling client) on page 684
l Add or modify a PeSIT trading pickup ( embedded server) on page 689
l X.400 trading configuration on page 740
l Secure file message protocol on page 971
l ebXML on page 545
l Send ebXML via an intermediary on page 562
The wizard shows the pages when you add:
l An application pickup
l A community pickup to consume messages from trading partners under the No packaging
message protocol.
Fields
l Address must be determined by either message attribute configuration or by
protocol address only .
l Specify the address. Always use a fixed address.
Specifies that Interchange should always use a fixed address for the sender or receiver. You can
click Pick party to launch a wizard that helps you locate the community or partner you want.
The “from” or “to” party must be set up as a community or partner in the user interface.
l Use the protocol address but if protocol address is missing, parse the document for
the address.
If you select this option, you must configure the address parsing rule. See Address parsing
rule options below.
l Always parse for the address. Regardless whether the message protocol provides
the address, always parse the document for the address.
Select this option to specify that Interchange should always parse the message for the sender or
receiver address.
For messages from partners, however, Interchange still checks the protocol header for the
sender and receiver. A message with an unknown sender or receiver in the header is rejected.
The always parse option for inbound messages is for finding the identity of true senders or true
receivers.
For messages picked up from applications, the always parse option tells Interchange to find the
sender or receiver in the message body. Messages from integration do not have protocol
headers.
If you select this option, you must configure the address parsing rule. See Address parsing
rule options below.
When this parsing option is elected, communities and partners must have matching routing
IDs in the same format. For example, if the “from” address in a parsed message is
ID:interchange ID:value3:value4, the partner must have the same routing ID.
When this option is not selected, “to” and “from” addresses in messages are parsed only for
Interchange ID and ID values. For example, 1:partner is parsed as the sender and rendered
as partner1 in the user interface.
Note that TRADACOMS only has two, optional values that can be parsed. They must match
one of the following patterns:
o A:
o :B
o A:B
l Use generic MMDs on page 954
l Web Services message protocol on page 726
l ebXML on page 545
l RosettaNet on page 699
l AS4 on page 499
Use the following fields to configure this transport.
l URL – The URL for connecting to the server. If Encode and Decode buttons display, click
Encode if the URL contains spaces or non-alphanumeric characters to encode the characters.
Click Decode to reverse the transformation. For example, if you enter http://foo.com/foo=
bar and click Encode the URL becomes http://foo.com/foo%3D%20%20bar.
l Clients must use SSL to connect to this server – Select this to have Secure Sockets Layer
protocol in use during connections. The server presents a certificate for verification. To do this,
a certificate in a profile must be designated as the SSL certificate. The server must support SSL.
If this is not selected, connections are not encrypted.
o Enable host name verification – If selected, Interchange compares the name of the SSL
server to the name in the server’s certificate to ensure they are the same. If you use DMZ
nodes, we recommend against selecting this. If host name verification is enabled, messages
may fail because the client is connecting to the DMZ node and not to Interchange server.
This is not applicable to application exchanges.
l This server requires a user name and password – If selected, type a user name and
password to connect to the server.
Note If prompted, you can select a Secure Relay DMZ zone to route messages to the partner.
This option displays only for transports for sending to partners when your user license
supports Secure Relay and a DMZ zone has been added. For details, see Secure Relay DMZ
nodes on page 474.
Click Next if you want to name the exchange. Otherwise, click Finish.
When you use the exchange wizard add an HTTP transport for a community using an embedded
server, you begin by selecting one of the following options:
o If you choose to define a community-level embedded HTTPS server, you must add an SSL
certificate for the server. After setting up the server in the exchange wizard, go to the
community summary page and click Change an embedded transport server near the
bottom of the page. Click the name of the server to open the maintenance page. If the server
needs a certificate, you are prompted to click Add an SSL server certificate. This action
opens the wizard for adding a certificate.
Except for the global embedded server, embedded HTTP servers can be designated as HTTPS.
See Embedded transport servers on page 431 for information about changing the configurations of
embedded servers.
See HTTP security solutions on page 586 for security guidelines for the embedded HTTP server.
When you use the exchange wizard to add an AS2 embedded HTTP trading pickup, you use the
following fields:
l Name – Type a name for the new embedded HTTP server. This can be any name you want. You
can select this sever when setting up additional embedded HTTP delivery exchanges later.
l Port – The port number that listens for incoming HTTP connections. The default is 4080.
l Clients must use SSL to connect to this server – Select this to set up an HTTPS delivery
exchange. A clear box indicates HTTP. When you select this check box, the following sub-field
displays.
l URL – The wizard displays the URL for the transport. This is the URL your partner uses to send
messages to the community. The last item in the URL is the community routing ID. This is a
suggested value. You can accept it or type another string.
Click Next if you want to name the exchange. Otherwise, click Finish.
Initial configuration
When you use the exchange wizard add an email transport for a community using an embedded
SMTP server, you begin by selecting one of the following options:
l Server name – A name identifying the embedded SMTP server. You can use any name you
want.
l Port – The port number that listens for incoming SMTP connections. The default is 4025.
After you specify the server to use, you enter a name for the exchange and click Finish.
1. Log into the Interchange user interface as an administrator.
2. Manually enter the following URL in your browser: http://<localhost or
machinename>:6080/ui/core/SystemProperties#
The Systems Properties page is displayed.
3. At the bottom of the page click Show default system properties.
4. Find the default system property entry actionTree.clearContentTypeProtocolsList,
and click Add Property.
5. In the Value field, enter AS1.
6. Click Add.
The term "detached" is used to distinguish this email method (which uses an external POP server),
from the system’s embedded SMTP server.
To add an embedded email server see Email (embedded) trading configuration on page 270.
The following are the fields in the delivery exchange wizard for configuring the detached email
server transport for a community.
l Port – The POP server port. Default = 110
l User name – The user name to connect to the server.
l Password – The password to connect to the server.
l Authentication type:
o USER/PASS – Select this option to use standard POP authentication (user/password
transmitted in plain text).
o APOP – Select this option if the server you are connecting to supports APOP (Authenticated
Post Office Protocol). APOP is an extension of traditional POP that enables user passwords to
be encrypted while being transmitted over networks, including the Internet.
1. Log into the Interchange user interface as an administrator.
2. Manually enter the following URL in your browser: http://<localhost or
machinename>:6080/ui/core/SystemProperties#
The Systems Properties page is displayed.
3. At the bottom of the page click Show default system properties.
4. Find the default system property entry actionTree.clearContentTypeProtocolsList,
and click Add Property.
5. In the Value field, enter AS1.
6. Click Add.
Note This topic describes configuring an external FTP server. For an embedded FTP server, see
FTP (embedded) transport configuration on page 275.
To enable partners to send messages to your FTP server, first set up the account, user ID and
password for the FTP server where Interchange retrieves files. Any partner who intends to receive
messages from you by FTP also must also perform this step.
In general, you should use the AS3 message protocol rather than the secure file protocol to trade
securely via FTP. An exception would be trading with a partner who uses an earlier version of
Interchange or Activator that does not support AS3. See Secure file message protocol on page 971
for more information.
Caution If you use Microsoft Internet Information Services (IIS) for the FTP server, make sure it is
updated with the latest patches from Microsoft. Large files (approximately 1 gigabyte) may
fail unless IIS is up to date.
Information-level messages about FTP client-server interaction write to Interchange log file. For
more verbose messages to aid in troubleshooting FTP issues, you can change the message level to
debug. Open:
log4j.properties file in <install directory>\conf
Search for the following entry, change the value from info to debug, then save and close the file.
log4j.category.com.cyclonecommerce.tradingengine.
transport.ftp.SimpleDebug=info
The debug setting logs each meta-command (for example, Send), followed by each primitive
command as it is sent to the server (Rest, Stor, Rnfr, Rnto, and so on). Also, a message is logged
each time a data connection is initiated or accepted. Each file name received during List operations
is logged. For more information see System logs on page 1093.
When used for integration delivery or sending to partners, default settings are in place to preserve
original file names and sequentially number duplicate file names. With these settings, Interchange
uses a file naming convention to defeat conflicts arising from multiple nodes feeding identically
named documents to the same FTP directory and server. Files are renamed in the following format:
But you can use the following because a period is the first character of the inbox directory
name:
c:\data\pickup\.inbox
When receiving files from a partner, we recommend that your partner write files to the inbox
directory first and then move them to the pickup directory when they are ready to be
retrieved. This process is automatic if your partner also uses any of the Axway products B2Bi,
Interchange, or Activator. If the partner uses other software to upload files to your server,
the software should be configured to initially upload the files to the inbox directory and
move them to the pickup directory when they are ready to be retrieved.
For outbound integration, the back-end system must write the message to the inbox and
then move it to the pickup directory.
For inbound integration and sending outbound to partners, Interchange writes to the inbox
and then moves the message to the pickup directory.
There may be some specialized servers, typically running on mainframes, that support only part
of the FTP protocol (RFC 959). In such cases you may have to clear this option and take steps of
your own to make sure collisions do not occur.
If you are connecting to a partner’s Interchange-embedded FTP server, do not select this option.
o Use separate directory for temporary files – Type the full path of an inbox directory
(for example, c:\data\inbox). Files are uploaded to this directory. When fully written,
files are moved to the pickup directory for retrieval.
Do not put the inbox under the pickup directory unless you use a period at the beginning of
the inbox name. Interchange and other applications ignore directories and files that begin
with periods.
For example, do not use the following directory structure:
c:\data\pickup\inbox
But you can use the following because a period is the first character of the inbox directory
name:
c:\data\pickup\.inbox When receiving files from a partner, we recommend that your
partner write files to the inbox directory first and then move them to the pickup directory
when they are ready to be retrieved. This process is automatic if your partner also uses Axway
products B2Bi, Interchange or Activator. If the partner uses other software to upload files to
your server, the software should be configured to initially upload the files to the inbox
directory and move them to the pickup directory when they are ready to be retrieved.
For outbound application deliveries, the back-end system must write the message to the
inbox and then move it to the pickup directory.
For inbound application and sending outbound to partners, Interchange writes to the inbox
and then moves the message to the pickup directory.
o Use special extension in pickup directory for temporary files – If you prefer not to
use an inbox, select this option. While a file is being written to the pickup directory, a
temporary extension is added so the system knows not to retrieve it because the file is only
partially written. Once fully written, the temporary extension goes away and the file can be
retrieved.
Click Next to name the exchange.
After you name the exchange, Finish.
Note If prompted, you can select a Secure Relay DMZ zone to route messages to the partner.
This option displays only for transports for sending to partners when your user license
supports Secure Relay and a DMZ zone has been added. For details, see Secure Relay DMZ
nodes on page 474.
When you elect to set up an embedded FTP transport for a community, the exchange wizard asks
whether you want to:
l Use a previously defined embedded FTP server (if available)
l Define a new embedded FTP server
If you choose to use a previously-defined embedded FTP server, the wizard prompts for the user
account name. You can choose an existing account or define a new one. If you choose an existing
account, you must choose a sub-directory within that account’s home directory that is not assigned
to any other exchange point.
If you choose to define a new embedded FTP server, the wizard prompts for a server name and port
number. The wizard then asks for a user name and password for the new server. If the default
selections already are in use, you must use another user name and password.
Note For a description of configuring an external FTP server, see FTP (external) transport
configuration on page 272.
l Trading servers are used for receiving messages from partners. In the simplest case, a partner’s
FTP client connects to your embedded server to PUT a message for your community to pick up.
There also is a more complex configuration — hosted embedded FTP — where your community
lets partners connect to your embedded server to GET messages.
l Application servers are used for retrieving messages from, or delivering messages to, back-
end systems.
The exchange wizard enforces the usage context for embedded FTP servers. For example, the wizard
does not let you define a new embedded FTP trading server when the usage requires an application
server.
To configure hosted partner accounts for embedded FTP servers, you must have a specific license
permission. Your license.xml file must enable the permission: hostedPartnerFtpAccounts.
Without this permission you can configure a partner to send messages via an external FTP server,
but not an embedded server. This permission does not affect back-end application accounts; there
is no restriction on adding hosted accounts from which a back-end system can pick up messages.
Community FTP accounts on page 277 Community exchanges, trading servers only
Partner FTP accounts on page 277 Community and partner exchanges, trading
servers only
FTP accounts for back-end application exchanges Community exchanges, application servers
on page 279 only
User names are shared by all trading servers. This enables a load balancer to send a request to any
trading server. However, user names associated with application servers are not related to user
names shared by trading servers. For example, the user name user1 on the trading side is
completely different from user1 on the application side.
The following topics describe each account type.
Partners can perform PUT operations to community accounts associated with trading pickups, but
not GET operations. This is to prevent partners from accessing each others’ files.
Partners can drop packaged messages directly into the home directory of a community account. As
a result, community FTP accounts can be referred to as shared accounts.
When a community profile is exported as a partner profile file to be imported by partners, the
community FTP account is exported with the FTP pickup exchange.
To avoid file name collisions you can use the Message attributes tab on the embedded FTP
pickup exchange maintenance page to specify sub-directories where partners can place files based
on the sender routing ID. This also allows identifying the sender when binary files are dropped off.
For example, the following sub-directory scheme could be used for two partners (p1 and p2) to
drop off files for community c1:
Sub-directory Purpose
p1/c1 p1 sends to c1
p2/c1 p2 sends to c1
If a partner-specific sub-directory scheme is used, the partner must manually specify the sub-
directory after importing the community's profile. If there is only one community and it has only one
routing ID, the second directory level is unnecessary.
The user interface segregates the two purposes. When adding a partner embedded FTP delivery
exchange, the wizard suggests the /mailbox sub-directory under the home directory. This is where
Interchange delivers messages for the partner to pick up. This can be thought of as a hosted partner
delivery exchange, since the partner is picking up messages from your server. If the same partner
account is added to an existing community pickup exchange, the system suggests the home
directory (/). This ensures outbound and inbound messages are not confused.
For hosted partner delivery exchanges, you must inform the partner performing the GET operation
of the FTP host name or IP address, the port number, the path, and the server user name and
password. If your partner uses Axway products B2Bi, Interchange or Activator, the partner must add
a community pickup exchange for receiving messages via an external FTP server (see FTP (external)
transport configuration on page 272). The default value of the pickup directory must be changed to
mailbox or whatever directory you specified. Also, clear the option for use temporary files.
Partner FTP accounts cannot be used by back-end application exchanges.
In this example, an administrator adds an outbound hosted FTP delivery exchange for partner1.
The administrator associates the user account p1. The user interface suggests /mailbox as the sub-
directory where the partner retrieves (GET) messages.
Optionally, for binary trading the use the Message attributes tab of the embedded FTP pickup
maintenance page to specify sub-directories where Interchange delivers files based on the routing
ID of the sending community. For instance:
Sub-directory Purpose
p1/mailbox/c1 p1 GETS messages from community1
p1/mailbox/c2 p1 GETS messages from community2
Since partner FTP accounts are partner-specific, message attribute mapping only is needed for
identifying the community if there is more than one possible sending community or there is no other
way to identify the community. This would be the case when you intend to trade binary files, which
have no packaging or internal identifying information.
Message attribute mapping also can be used to sort messages into arbitrary sub-directories based on
other metadata besides the sender or receiver. For example, an inline process could assign metadata
items to outbound messages that would cause them to be sorted into sub-directories based on
mappings specified on the Message attributes tab.
This example is for traders who do not want to upload files to a shared community FTP account.
An administrator adds or selects a community embedded FTP pickup exchange. The pickup
exchange can be one already associated with a community FTP account, such as c1. The pickup
exchange provides an anchor for one or more partner FTP accounts where files may be dropped off
for the community.
The administrator selects the Directories tab on the community pickup exchange. There the
administrator can add a new partner account or select an existing one.
The user interface suggests / as the home directory for the FTP account where partners can drop
files for the community. In contrast, /mailbox is the suggested directory when a hosted delivery
exchange is added for a partner to GET messages.
Note Embedded FTP servers treat paths beginning with a slash as starting at the home directory
for the user account currently logged in.
When you create an FTP account you can choose to either use an existing account, a new account
(with all fields empty), or to define one later.
When defining an embedded FTP pickup for the first time, the exchange wizard suggests the generic
name application as the FTP account name. The same user name is offered for the first FTP
application delivery exchange. The difference is \out is suggested as the pickup subdirectory name
and \in is suggested as the delivery subdirectory name. You can change the user names and
subdirectories as long as the same combination of user name and subdirectory is not specified for
two exchanges. This is true for all embedded FTP exchanges.
In the early days of the Internet it was common for an FTP client to use port mode. The data
connection was established from the server back to the client, even though the original control
connection was always established from the client to the server.
The client is generally less prepared than the server to open firewall ports, and passive mode has
become the standard (Windows command line FTP client is an exception). In passive mode, when
the client wants to perform a GET, PUT or LIST operation, the server creates a temporary socket
listening on a port specifically for that client, usually at a high number like 50,000. The client then
makes the data connection to the server, performs the transfer and the connection is dropped. The
control connection remains active.
Most firewalls in use today allow the client through on the temporary data port, even if the port is
not explicitly configured to be open. This is safe because the firewall can eavesdrop on the initial
control connection from the client and notice it is an FTP connection. If the connection is non-SSL,
the firewall also can notice the temporary port the server assigned for the client to establish the data
connection. Subsequently when the client tries to connect again on that port, the firewall allows the
connection on a one-time basis to the temporary port.
Load balancers present a similar problem. If the load balancer is FTP-aware, it can route incoming
data connections to the same server as the associated control connection. But the load balancer
cannot do this in the case of SSL. It must be configured to route all connections from the same
origination IP address to the same server until there are no more connections from that IP to that
server.
Since all trading servers share the same pool of user accounts, the load balancer can be configured
to route incoming control connections to any trading server. For example, if you have two
Interchange nodes on different machines, each running a server on port 4021, the load balancer
can be configured to round-robin between the two hosts.
l Server name – Enter a name for the new embedded FTP server. This can be any name you
want. You can select this server when setting up additional embedded FTP delivery exchanges
later.
If this is the first server, the wizard suggests the name Trading FTP if the server is to be used for
receiving messages from partners or Application FTP if the server is to be used for exchanging
messages with a back-end system.
l Port – The port number that listens for incoming FTP connections. This is known as the control
port. The wizard suggests a port not in use and displays a list of ports in use by Interchange. You
can use the suggested port or another.
If this is the first server, the wizard suggests — if not already in use — 4021 for a trading server or
5021 for an integration server. For security reasons, trading and integration servers must use
different ports.
directory>\common\data\ftp\users\trading. But if you are configuring an application
transport, the path is <install directory>\common\data\ftp\users\integration.
Caution Do not configure a back-end system to retrieve files from or write files to
common\data\ftp\users\trading. Doing so could result in operational difficulties.
The back-end system must always interact with trading engine application-type transports,
and allow Interchange to route messages to and from trading-type transports.
l Password – The password to connect to the server.
l Confirm password – The password to connect to the server. Anonymous connections are not
supported.
l Transport user password policy – Select the password policy to assign to the user. See
Manage password policies of transport users on page 129 for more information.
Click Next to continue the configuration.
But if you add an amended path, the effective directory is the specified sub-directory. For
example:
common\data\ftp\users\trading\<user account>\<amended path>
For the first integration server, the wizard suggests an amended path of in for integration
delivery or out for integration pickup. By default the home directory (/) is not used, but you can
change this.
Interchange keeps track of the embedded FTP directory structure for you. Do not manually
change any directories Interchange creates for managing messages transported via embedded
FTP servers.
Click Next if you want to name the exchange. Otherwise, click Finish.
Note If prompted, you can select a Secure Relay DMZ zone to route messages to the partner.
This option displays only for transports for sending to partners when your user license
supports Secure Relay and a DMZ zone has been added. For details, see Secure Relay DMZ
nodes on page 474.
To enable partners to send messages to your SFTP server, first set up the account, user ID and
password for the SFTP server where Interchange retrieves files. Any partner who intends to receive
messages from you by SFTP also must also perform this step.
SFTP is similar to FTP, but performs all operations over an encrypted Secure Shell (SSH) transport.
SFTP and FTP/SSL (or FTPS) are different transports. An SFTP server can communicate only with
other SFTP servers, not FTP servers.
Interchange supports limited SFTP functionality as the following notes:
l Only supports SSH 2.0.
l Checkpoint-restart functionality is not supported.
l User commands and scripting (as supported for FTP) are not supported for SFTP.
This transport has been tested only with the OpenSSH sftp-server.
For more information about SSH see:
l http://datatracker.ietf.org/wg/secsh/charter/
l http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt
l http://www.openssh.com/faq.html
SFTP fields
The following fields are used in the delivery exchange wizard for configuring this transport.
But you can use the following because a period is the first character of the inbox directory
name:
c:\data\pickup\.inbox
When receiving files from a partner, we recommend that your partner write files to the inbox
directory first and then move them to the pickup directory when they are ready to be
retrieved. This process is automatic if your partner also uses Interchange. If the partner uses
other software to upload files to your server, the software should be configured to initially
upload the files to the inbox directory and move them to the pickup directory when they are
ready to be retrieved.
For outbound integration, the back-end system must write the message to the inbox and
then move it to the pickup directory.
For inbound integration and sending outbound to partners, Interchange writes to the inbox
and then moves the message to the pickup directory.
o Use special extension in pickup directory for temporary files – If you prefer not to
use an inbox, select this option. While a file is being written to the pickup directory, a
temporary extension is added so the system knows not to retrieve it because the file is only
partially written. Once fully written, the temporary extension goes away and the file can be
retrieved.
l Server’s public key – You have two options for designating the RSA or DSA public key for the
SFTP server. Interchange uses the key to authenticate the server.
o Retrieve public key from server – Click Get Key to have Interchange retrieve the public
key for the SFTP server. The server name and port number entered on this page must be
correct for this option to work.
o Server public key file – Type the path to the file containing the public key for the SFTP
server or click Browse to locate the file. You may have to ask the server administrator for the
file path.
l Use password authentication – Password authentication requires entering the user name
and password for connecting to the server. The user name and password are sent over an
encrypted connection to authenticate the user to the server. Although this option offers ease of
administration, the password is vulnerable because it is sent every time a connection is made.
The password could be compromised if the server is ever compromised.
For more information see Public-private key and password authentication on page 292.
l Use public/private key pair authentication – Public-private key pair authentication
requires entering the user name of the server here.
If this exchange is for a community, add the private key to the community. If this exchange is for
a partner, add the public key to any community that will be trading with the partner.
To add a key, click Certificates in the navigation graphic at the top of the community summary
page. Select the SSH keys tab. Click Add an SSH key, follow the prompts and click Add.
Select the key as the default SSH key after it has been added.
For more information see Public-private key and password authentication on page 292.
l Use host-based authentication – Select this option if this delivery binds outbound messages
to a server that requires host-based authentication. You can use host-based authentication with
a Linux SFTP server. Before you activate this option you must complete the steps listed below. If
you have started creating an external SFTP pickup or delivery, cancel the wizard and complete
the prerequisites first.
Note: If you select this option, in the "Configure outbound connection proxy page", you must
not select the option "Begin secure connection in DMZ". See Configure outbound connection
proxy on page 488.
o On the server:
1. Copy the public key file to the following directory:
/home/user/.ssh/
2. Append the public key file contents to authorized_keys:
/home/users/.ssh/key1.pub >> /home/user/.ssh/authorized_keys
3. Append the public key to the /etc/ssh/ssh_known_hosts file. Edit to add
hostname:
cat /home/user/.ssh/sshkey1_linux36.pub >> /etc/ssh/ssh_known_
hosts
4. Add the client's hostname to the following file:
/etc/ssh/shosts.equiv
o On the client:
1. Copy the corresponding private key file to a directory.
2. In Interchange, create a new pickup/delivery using an external SFTP server. When
prompted to Configure the SFTP settings, after you complete the initial fields,
select Use host-based authentication. Enter the User Name and browse to the
private key file. If a Key password is required, enter it.
Secure Relay
If prompted, you can select a Secure Relay DMZ zone to route messages to the partner. This option
displays only for transports for sending to partners when your user license supports Secure Relay
and a DMZ zone has been added. For details, see Secure Relay DMZ nodes on page 474.
Testing SFTP
You can use the sftpTester tool to exercise the SFTP client outside of Interchange. The script to start
sftpTester can be found in <install directory>\tools.
sftpTester is a console-based application that can verify the operation of the SFTP client in
Interchange and a partner’s SFTP server. Interchange server does not have to be running to use this
tool. You can use it on UNIX or Windows.
sftpTester duplicates the way Interchange accesses an SFTP server. It is a test program to verify
interoperability with SFTP servers. If you can send, list, receive and delete files on a SFTP server
using sftpTester, this is a good indication Interchange can interoperate with the server.
sftpTester prompts for all the information it needs, as the following illustrates:
After prompting for the initial configuration information such as the host, user and password,
sftpTester displays a main prompt that allows you to enter meta-commands to perform simple
operations such as list, send and receive. You can enter a question mark (?) at this point to get more
information. The following information displays upon entering a question mark at the main prompt:
Consumer commands
-> Enter CONSUMER command (e.g. ?, LIST, RECeive, DELete, LLIST, LCD,
QUIT): ?
CONSUMER metacommands (abbreviations shown in upper case):
? help
LIST list files on host
RECeive filename retrieve file from host
DELete filename delete file from host
LCD change local working directory
LLIST list files in local working directory
QUIT/EXIT/BYE exitNormal SftpTester
Producer commands
Troubleshooting SFTP
For troubleshooting, you can write messages specific to the SFTP transport to Interchange log file.
You can add the following properties to the log4j.properties file at <install directory>\conf.
l For messages related to high-level operation of the SFTP client, this property in debug mode is
useful for finding common SFTP problems.
log4j.category.com.cyclonecommerce.tradingengine.transport.sftp.SimpleDebug=d
ebug
l For messages related to low-level operation of the SFTP client, this property in debug mode
produces verbose messages. (Try the simple debug property before using this one.)
log4j.category.com.cyclonecommerce.tradingengine.transport.sftp= debug
When you elect to set up an embedded SFTP transport for a community, the wizard asks whether
you want to:
l Use a previously defined embedded SFTP server (if available)
l Define a new embedded SFTP server
If you choose to use a previously defined embedded SFTP server, the wizard prompts for the user
account name. You can choose an existing account or define a new one. If you choose an existing
account, you must choose a subdirectory within that account’s home directory that is not assigned
to any other exchange point.
If you choose to define a new embedded SFTP server, the wizard prompts for a server name and port
number. The wizard then asks for a user name and password for the new server. If the default
selections already are in use, you must use another user name and password.
When you create an embedded SFTP server, Interchange also generates an RSA public-private key
pair for the server. The key pair has no visibility in your user interface. But when you export your
community profile as a partner profile, the server’s public key is exported with it. When your B2Bi,
Interchange, or Activator p artner imports the partner profile, the public key can be displayed. Your
partners use the public key to authenticate the embedded server upon connecting.
Note For a description of configuring an external SFTP server, see SFTP (external) transport
configuration on page 281.
The exchange wizard enforces the usage context for embedded SFTP servers. For example, the
wizard does not let you define a new embedded SFTP trading server when the usage requires an
application server.
To configure hosted partner accounts for embedded SFTP servers, you must have a specific license
permission. Your license.xml file must enable the permission: hostedPartnerSftpAccounts.
Without this permission you can configure a partner to send messages via an external SFTP server,
but not via an embedded server. This permission does not affect back-end application accounts;
there is no restriction on adding hosted accounts from which a back-end system can pick up
messages.
Community SFTP accounts on Community trading pickups, trading servers only
page 287
Partner SFTP accounts on page Community trading pickups and partner trading deliveries,
288 trading serves only
Application SFTP accounts on Community application pickups and deliveries, application
page 289 servers only
User names are shared by all trading servers. This enables a load balancer to send a request to any
trading server. However, user names associated with application servers are not related to user
names shared by trading servers. For example, the user name user1 on the trading side is
completely different from user1 on the application side.
The following topics describe each account type.
Partners can perform PUT operations to community accounts associated with trading pickups, but
not GET operations. This is to prevent partners from accessing each others’ files.
Partners can drop packaged messages directly into the home directory of a community account. As
a result, community SFTP accounts can be referred to as shared accounts.
When a community profile is exported as a partner profile file to be imported by partners, the
community SFTP account is exported with the pickup exchange.
To avoid file name collisions you can use the Message attributes tab on the pickup exchange to
specify subdirectories where partners can place files based on the sender routing ID. This also allows
identifying the sender when binary files are dropped off. For example, the following subdirectory
scheme could be used for two partners (p1 and p2) to drop off files for community c1:
Subdirectory Purpose
p1/c1 p1 sends to c1
p2/c1 p2 sends to c1
If a partner-specific subdirectory scheme is used, the partner must manually specify the subdirectory
after importing the community's profile. If there is only one community and it has only one routing
ID, the second directory level is unnecessary.
The user interface segregates the two purposes. When adding a partner embedded SFTP delivery,
the wizard suggests the /mailbox subdirectory under the home directory. This is where
Interchange delivers messages for the partner to pick up. This can be thought of as a hosted partner
delivery exchange, since the partner is picking up messages from your server. If the same partner
account is added to an existing community pickup exchange, the system suggests the home
directory (/). This ensures outbound and inbound messages are not confused.
For hosted partner delivery exchanges, you must inform the partner performing the GET operation
of the SFTP host name or IP address, the port number, the path, and the server user name and
password. If your partner uses Interchange or Activator, the partner must add a community pickup
exchange for receiving messages via an external SFTP server (see SFTP (external) transport
configuration on page 281 for configuration information). The default value of the pickup directory
must be changed to mailbox or whatever directory you specified. Also, clear the option for use
temporary files.
Partner SFTP accounts cannot be used by back-end application exchanges.
In this example, an administrator adds an outbound hosted SFTP delivery exchange for partner1.
The administrator associates the user account p1. The user interface suggests /mailbox as the
subdirectory where the partner retrieves (GET) messages.
Optionally, for binary trading the Message attributes tab can specify subdirectories where
Interchange delivers files based on the routing ID of the sending community. For instance:
Subdirectory Purpose
p1/mailbox/c1 p1 GETS messages from community1
p1/mailbox/c2 p1 GETS messages from community2
Since partner SFTP accounts are partner-specific, message attribute mapping only is needed for
identifying the community if there is more than one possible sending community or there is no other
way to identify the community. This would be the case when you intend to trade binary files, which
have no packaging or internal identifying information.
Message attribute mapping also can be used to sort messages into arbitrary subdirectories based on
other metadata besides the sender or receiver. For example, an inline process could assign metadata
items to outbound messages that would cause them to be sorted into subdirectories based on
mappings specified on the Message attributes tab.
This example is for traders who do not want to upload files to a shared community SFTP account.
An administrator adds or selects a community-embedded SFTP trading pickup. The trading pickup
can be one already associated with a community SFTP account like c1. The exchange provides an
anchor for one or more partner SFTP accounts where files may be dropped off for the community.
The administrator selects the Directories tab on the community trading pickup. There the
administrator can add a new partner account or select an existing one.
The user interface suggests / as the home directory for the SFTP account where partners can drop
files for the community. In contrast, /mailbox is the suggested directory when a hosted delivery
exchange is added for a partner to GET messages.
Note Embedded SFTP servers treat paths beginning with a slash as starting at the home directory
for the user account currently logged in.
When you create an SFTP account you can choose to either use an existing account, a new account
(with all fields empty), or to define one later.
The \out directory is suggested as the pickup subdirectory name and \in is suggested as the
delivery subdirectory name. You can change the user names and subdirectories as long as the same
combination of user name and subdirectory is not specified for two exchanges. This is true for all
embedded SFTP exchanges.
Since all trading servers share the same pool of user accounts, the load balancer can be configured
to route incoming control connections to any trading server. For example, if you have two
Interchange nodes on different machines, each running a server on port 4022, the load balancer
can be configured to round-robin between the two hosts.
Server fields
l Server name – Enter a name for the new embedded SFTP server. This can be any name pickup
you want. You can select this server when setting up additional embedded SFTP delivery
exchanges later.
If this is the first server, the wizard suggests either the name Trading SFTP if the server is to be
used for receiving messages from partners or Application SFTP if the server is to be used for
exchanging messages with a back-end system.
l Port – The port number that listens for incoming SFTP connections. This is known as the
control port. The wizard suggests a port not in use and displays a list of ports in use by
Interchange. You can use the suggested port or another.
If this is the first server, the wizard suggests — if not already in use — 4022 for a trading server or
5022 for an application server. For security reasons, trading and integration servers must use
different ports.
You must select one of the following authentication options:
l This server requires the SFTP client to authenticate using a password – Select to
require your partner to submit a password to connect to your embedded SFTP server.
l This server requires the SFTP client to authenticate using a public/private key pair
– Select to require your partner to use a private key to encrypt an authentication message and
pass it to the server to decrypt with the matching public key. This process enables the server to
verify the identity of the partner. Your partner must generate a private-public key pair and give
you a file containing the public key.
l This server requires the SFTP client to authenticate using both a password and a
public/private key pair –
Select this option to require both a password and public/private key pair.
l This server allows the SFTP client to authenticate using either a password or a
public/private key pair – Select this option to require either a password or a public/private
key pair.
Click Next to continue the configuration.
l Select an existing account from the drop-down list (if an account has been previously defined)
l Define a new account
l Define an account later
If you elect to define a new account, complete the fields for the authentication option you selected
on the previous wizard page.
Password authentication
l Password – The password to connect to the server. Anonymous connections are not
supported.
l Confirm password – Confirm the password.
l Transport user password policy – Select the password policy to assign to the user. See
Manage password policies of transport users on page 129 for more information.
Public key authentication
l Public key file – The path to the public key file. You must get this file from your partner, who
generates a private-public key with some type of key-generation tool. The file can have an
extension readable by simple text editors, such as .txt, .xml or .pub.
Interchange accepts a file containing a public key in the following format:
Keytype EncodedKeyValue UserName
where:
Keytype must be one of the following values: ssh-rsa or ssh-dss
EncodedKeyValue is a Base64 encoded string like this:
AAAAB3NzaC1yc2EAAAABIwAAAIEAypVxTV0MRxv4LS3tVld0LX+YhQmbyBSjwGrKqpqyWYH
Vrpv27Lri4oJ8KzeY2HSgiLGBqitVsQjnf65JYZxW0WSoXrCoh6Y1f7zJZszN8P+15wt3QH
0OcHerpdUp5LEfBgCaKRdaPTkgzhpDdMO87ZVFB8vam7fXEYuwUifUyfE=
UserName is a value generated by the key tool (for example, pnuechte@ls0020). UserName is
optional.
Click Next to continue the configuration.
If you add an amended path, the effective directory is the specified subdirectory. For example:
common\data\ssh\users\trading\<user account>\<amended path>
For the first trading server, the wizard suggests an amended path of mailbox for trading pickup.
By default the home directory (/) is not used, but you can change this.
For the first application server, the wizard suggests an amended path of in for application
delivery or out for application pickup. By default the home directory (/) is not used, but you can
change this.
Interchange keeps track of the embedded SFTP directory structure for you. Do not manually
change any directories Interchange creates for managing messages transported via embedded
SFTP servers.
Note If prompted, you can select a Secure Relay DMZ zone to route messages to the partner.
This option displays only for transports for sending to partners when your user license
supports Secure Relay and a DMZ zone has been added. For details, see Secure Relay DMZ
nodes on page 474.
Click Next if you want to name the exchange. Otherwise, click Finish.
This procedure assumes:
l The local community and the remote partner both use Interchange.
l Both parties use AS3 embedded SFTP. However, the steps for external SFTP are similar (see SFTP
(external) transport configuration on page 281).
l The local community’s embedded SFTP server requires the SFTP client (the remote partner) to
authenticate using a password.
l The remote partner’s embedded SFTP server requires the SFTP client (the local community) to
authenticate using a public-private key pair.
The following procedures indicate the tasks performed by the local community and the remote
trading partner.
3. Click the link to open the maintenance page for the SFTP pickup.
4. On the SFTP settings tab:
l Verify the Use public/private key pair authentication option is selected.
l Add the user name from the previous procedure in the User name field. This is the user
name the local community uses to connect to the remote partner's embedded SFTP server.
l Click Save changes.
The partners now are configured to exchange messages.
Your JMS system may have file size limitations. Check the documentation for your JMS system.
Note If you are using the Axway Integrator JMS transport for integrating Interchange with Axway
Integrator, see Integrate with Axway Integrator on page 1048.
The JMS application transport is an input and output source for messages. This is how it works:
Interchange polls the JMS server for messages in the designated inbound queue. This means that
any JMSMessage placed in the queue by another process is retrieved by Interchange, which verifies
the type of JMSMessage (BytesMessage or TextMessage). If verified, Interchange packages and
sends it to the partner. Likewise, every message Interchange receives from a partner is unpackaged,
converted to a BytesMessage or TextMessage and placed on the designated outbound queue.
For applicaton pickup exchanges, Interchange determines whether the message read from the
queue is a BytesMessage or a TextMessage. For delivery application delivery exchanges, in which
messages from partners are sent to back-end systems, you can select the JMS type (BytesMessage or
TextMessage) on the Advanced tab of the transport’s maintenance page.
When using JMS for application exchanges, configure Interchange to parse EDI and XML messages
retrieved from a back-end system for sender and receiver information.
Binary documents retrieved from the back-end must have the following metadata string parameters
appended to the BytesMessage or TextMessage: SenderRoutingId, ReceiverRoutingId and
ContentMimeType. Interchange performs routing decisions based on the string parameters.
When Interchange sends a BytesMessage or TextMessage to the back end, it includes the string
parameters SenderRoutingId, ReceiverRoutingId and ContentMimeType for all document types.
Other metadata are available for JMS messages. See Metadata definitions on page 414. Virtually all
of this metadata are copied into the JMS message when Interchange produces the message to a JMS
queue. When reading from a JMS queue, all metadata from the JMS message are copied into the
collaboration message, but it may not make sense to set some items in the JMS message. For
example it would not make sense to set the ConsumptionURL in the JMS message. Also see XML for
JMS and AQ event routers on page 1110.
Note that when Interchange encounters a metadata element containing characters that JMS cannot
recognize, it changes the offending characters into the hex representation of the ASCII code of the
characters. For example, the metadata element ediint.DocumentType becomes
ediint$2eDocumentType. The $2e is the hex representation of a period. When submitting JMS
messages to Interchange, use the properly encoded hex names to have them turned into the proper
metadata names.
In addition to using the delivery exchange wizard to configure a JMS transport, other set up is
required. Depending on your provider, follow the recommendations in the JMS transport
configuration on page 294 or JMS transport configuration on page 294 topic.
Note If BEA WebLogic is your JMS provider, there are options for ensuring proper load balancing
and fail-over when delivering messages to clustered JMS servers. One option is to configure
a distributed destination in WLS and reference its JNDI name on the JMS configuration
page in Interchange. At runtime, the JNDI lookup performed by the WebLogic JMS client
resolves the distributed destination name to a physical queue. Another option is to provide
a comma-separated list of host names in the JNDI URL field in Interchange (for example,
t3://node1:7001,node2:7002,node3:7003). At runtime, the JMS client round-robins
between the specified providers. Both options ensure load balancing and support for fail-
over. See the WebLogic documentation for how to configure these options.
Most providers
In addition to completing the JMS transport configuration page in the user interface, to enable
Interchange to use a custom JMS provider:
1. Copy the necessary JAR files for your JMS provider to <install_
directory>/Interchange/site/jars.
This directory is already part of the CLASSPATH.
2. Restart Interchange.
Troubleshooting
Note: You cannot have multiple versions of the provider JAR files in the
...Interchange/site/jars or ...Interchange/corelib/db/ directories. For example, if
you already have v7.5 IBM MQ JARs and add V8.0 JARs, you must remove the older JARS to avoid
conflicts.
In Windows environments, in some cases you may experience JAR conflicts when a provider JAR file
is added to ...Interchange/site/jars. If this the case, you can:
1. Create a new folder to contain the specific JAR files for the JMS provider.
2. Go to .../Interchange/conf and open jvmArguements.xml in a text editor.
3. Add the name of the directory containing the JAR or class files (or both) in the
jvmArguements.xml file so the server can locate the JMS and JNDI provider. Add CLASSPATH
entries under the “TE” node type, as in the following example. Entries can be either a “path”
reference or a reference to a single JAR:
4. Save the file.
WebSphere MQ
For WebSphere MQ configuration details, see WebSphere MQ configuration on page 733.
Oracle AQ
If the provider is Oracle Advanced Queuing facility (Oracle AQ), Oracle must be the external database
for Interchange and Oracle AQ must be installed.
Add a message queue on Oracle AQ. The queue payload type must be one of the following:
l SYS.AQ$_JMS_BYTES_MESSAGE
l SYS.AQ$_JMS_TEXT_MESSAGE
On the Oracle client, copy the Oracle AQ drivers aqapi.jar and jmscommon.jar. You may find
these files in the rdbms/jlib directory. Paste the files to the Interchange directory <install
directory>\Interchange\corelib\db\oracle and restart the server.
For any JMS transport for Oracle AQ that polls for messages, go to the Advanced tab on the
transport’s maintenance page and select Use transacted queue. You need to do this if the JMS
settings tab name includes the word polled. For example, JMS (polled) settings. If the settings
tab is named JMS (listener) settings, the Use transacted queue control is not available on the
Advanced tab.
If Oracle AQ is installed on Oracle 10g or later, JMS performance in listener mode may be poorer than
in polled mode. If this is the case, consult Oracle documentation or technical support about whether
to keep or change values of the following AQ parameters:
System.setProperty("oracle.jms.minSleepTime","200");
System.setProperty("oracle.jms.maxSleepTime","1000");
Once the values are determined, set identical values in the Interchange jvmArguements.xml file
at <install directory>\conf. The properties to add are:
<Property key="oracle.jms.minSleepTime">200</Property>
<Property key="oracle.jms.maxSleepTime">1000</Property>
The steps are:
1. Open the jvmArguments.xml file.
2. Scroll to the TE section (NodeType type="TE").
3. Add the min and max sleep time properties. Values are in milliseconds. The change should look
like the following snippet. The added properties are in bold.
4. Save and close the file.
JMS fields
The following fields are used in the delivery exchange wizard for configuring this transport.
Except for the user name and password, you can obtain the information needed to complete this
page from the JMS provider's documentation. The information varies depending on the provider. If
you have questions, contact your JMS provider.
l JMS type – There are two choices for acquiring messages from a JMS queue for integration
pickup and receiving messages from partners:
o Polled. Interchange polls the JMS server at intervals for messages. This is the default setting.
The polling interval and the maximum number of files to retrieve per interval can be adjusted
on the Advanced tab of the transport’s maintenance page. Although the rate at which
messages enter the system is controlled, this selection introduces latency and overhead in
checking the JMS server when the queue is empty. (If Sybase EAServer is the JMS provider,
you must select Polled.)
o Listener. The JMS server calls Interchange as soon as a message is written to its queue.
Messages are transferred as they arrive and do not wait for Interchange to poll for them.
When selected, the transport’s Advanced tab on the maintenance page has a setting for
reconnecting to the JMS server if the server goes down. However, there are no controls
related to polling, because polling does not apply. Although latency and polling overhead
are eliminated, this selection cannot control the rate at which messages enter the system,
which could overload it. (If you use WebLogic, the Allow Close In On Message check box for
the queue factory must be selected in the WebLogic user interface.)
Once polled or listener has been selected, the JMS type cannot be changed on the transport’s
maintenance page.
l JMS queue – The name of the queue. Example: XMLQueue@router1
l This queue requires a user name and password – Select this if the queue requires a user
name and password. When selected, fields appear for entering the information.
o User name – A user name for the JNDI provider. This value could be blank and is typically
provided for in the JNDI URL. However, this depends on the JNDI provider and how it is
configured.
o Password – A password for the JNDI provider. This value could be blank and is typically
provided in the JNDI URL. However, this depends on the JNDI provider and how it is
configured.
o Confirm password – Type the password again for confirmation.
l Use JNDI – Select this if a Java Naming and Directory Interface (JNDI) provider. When selected
the applicable fields display.
l JNDI URL – The network URL used to obtain access to the JNDI service provider for your JMS
service. Example: smqp://localhost:4001/timeout=10000
l JNDI factory – The name for the JNDI service provider class. Example:
com.swiftmq.jndi.InitialContextFactoryImpl
If you want a Java class for a provider other than Oracle AQ, you need the help of a
professional services consultant. Contact technical support for information.
o Parameters – These are the parameters for implementing the Java class. There are four
parameters required for the Java class for Oracle AQ. These parameters must be in the
following order:
o Host. The name of the computer running Oracle AQ.
o Database name. The name of the database that contains the message queue.
o Port. The port Oracle AQ uses to listen for messages.
o Driver type. The type of JDBC driver for connecting to the provider. For Oracle AQ, the
valid values are thin and oci8.
l Send payload via file system (delivery exchange only) – Select this option to have payloads
sent by a file system. You can specify the size of payloads to send and the path for payload files.
The receiver uses the path to retrieve the files.
Click Next if you want to name the exchange. Otherwise, click Finish.
Testing JMS
You can use the jmsTester tool to exercise the JMS client outside of Interchange. The script to start
jmsTester can be found in <install directory>\tools.
jmsTester is a console-based application that can verify the operation of the JMS client in
Interchange and a partner’s JMS server. Interchange server does not have to be running to use this
tool. You can use it on UNIX or Windows.
jmsTester duplicates the way Interchange accesses a JMS server. It is a test program to verify
interoperability with JMS servers. If you can send, list, receive and delete files on a JMS server using
jmsTester, this is a good indication Interchange can interoperate with the server.
jmsTester prompts for all the information it needs, as the following illustrates:
After prompting for the initial configuration information, you can use one of the following test
commands:
l (c)onnect
l (d)isconnect
l (s)end
l (r)etrieve
l (a)cknowledge
Prerequisites
To use this transport, on the MQSeries server side, the following elements must be properly
configured:
l Queue manager
l Queues
l Channel
l Listener
l Queue manager key database (for SSL connections)
l Certificate (for SSL connections)
Note To trade using MQ SSL, you must have a trusted SSL root certificate. Make sure your
certificates are up to date and trusted.
SSL_RSA_EXPORT1024_WITH_DES_CBC_ DES_SHA_EXPORT1024
SHA
SSL_RSA_EXPORT1024_WITH_RC4_56_SHA RC4_56_SHA_EXPORT1024
SSL_RSA_EXPORT_WITH_RC4_40_MD5 RC4_MD5_EXPORT
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 RC2_MD5_EXPORT
SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA FIPS_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA
SSL_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA
SSL_RSA_WITH_DES_CBC_SHA DES_SHA_EXPORT
SSL_RSA_WITH_NULL_MD5 NULL_MD5
SSL_RSA_WITH_NULL_SHA NULL_SHA
SSL_RSA_WITH_RC4_128_MD5 RC4_MD5_US
SSL_RSA_WITH_RC4_128_SHA RC4_SHA_US
Click Next if you want to name the exchange. Otherwise, click Finish.
l Community certificate – For connecting to the MQSeries server.
l Community application pickup certificate – For consuming messages from the MQSeries server.
Community certificate
Interchange uses this certificate to connect to the MQSeries server.
View certificates
To view community SSL certificates:
1. From the Trading configuration menu, select a community.
2. On the community graphic at the top of the page, click the Certificates icon.
The interface displays the Certificates page.
Add certificate
1. From the Trading configuration menu, select a community.
2. On the community graphic at the top of the page, click the Certificates icon.
The interface displays the Certificates page.
3. Select the Trusted SSL root certificates tab.
4. Click Add a trusted root certificate for SSL servers.
5. In the Add a certificate screen, accept the Import a certificate from a file option and click
Next.
6. In the Locate the certificate file screen, use the Browse tool to locate and select the
certificate file provided by MQSeries.
7. In the View certificate details screen, enter a name for the certificate and view the certificate
details to confirm that the certificate is valid.
8. Click Finish.
The certificate is added to the list of certificates on the Trusted SSL root certificates tab.
Remove certificate
1. From the Trading configuration menu, select a community.
2. On the community graphic at the top of the page, click the Certificates icon.
The interface displays the Certificates page.
3. Select the Trusted SSL root certificates tab.
The interface displays the list of SSL trusted certificates available for the community.
4. On the row of the certificate that you want to remove, click Untrust.
The certificate is removed from the list of SSL trusted certificates available for the community.
View certificates
To view community application pickup SSL certificates:
1. From the Trading configuration menu, select a community.
2. On the community graphic at the top of the page, click the Application pickup icon.
The interface displays the Application pickups screen.
3. Select the Trusted root certificates tab.
The interface displays the list of trusted root certificates available for application pickup
exchanges.
Add certificate
1. From the Trading configuration menu, select a community.
2. On the community graphic at the top of the page, click the Application pickup icon.
The interface displays the Application pickups screen.
3. Select the Trusted root certificates tab.
4. Click Add a trusted root certificate.
5. In the Add a certificate screen, accept the default option Import a certificate from a file
and click Next.
6. In the Locate the certificate file screen, use the Browse tool to locate and select a trusted root
certificate.
7. In the View certificate details screen, enter a name for the certificate and view the certificate
details to confirm that the certificate is valid.
8. The certificate is added to the list of certificates on the Trusted root certificates tab.
Remove certificate
1. From the Trading configuration menu, select a community.
2. On the community graphic at the top of the page, click the Application pickup icon.
The interface displays the Application pickups screen.
3. Select the Trusted root certificates tab.
The interface displays the list of trusted root certificates available for application pickup
exchanges.
4. On the row of the certificate that you want to remove, click Untrust.
The certificate is removed from the list of trusted certificates available for application pickups.
For general information on certificate management, see Certificates and keys on page 767.
Transport type
Select the option for receiving messages from remote partners:
Network type
Select the network protocol. The options are:
l TCP. Transmission Control Protocol is the basic communications protocol of the Internet.
l X.25. An ITU-T standard protocol suite for packet-switched wide area network communications.
l X.25 over ISDN (B-channel). Integrated Services Digital Network broadband channel
supports data transfers over telephone networks.
If you select an X.25 option, you are prompted to select a router. You can select an existing router
or add one to use.
l Friendly name – The name of this router. A meaningful name is suggested. If not specified,
Interchange uses a name in the following format: Router on [host name or IP].
l Host – The fully qualified domain name or IP address of the internal interface of the router. It
must be accessible from all Interchange nodes.
o Maximum concurrent outbound connections – The maximum number of outbound
X.25 logical connections that can be made by this router. This is tied to the X.25 network’s
number of allowed virtual channels and bandwidth.
As the virtual channels are used for inbound and outbound connections, and OFTP requires
receipts to be delivered, be careful when specifying this value. For example, if the maximum
number of channels is 10, set this value to 4. This makes sure at least 6 channels stay
available for receipts and inbound connections, if any.
o SNMP community password – The SNMP password with at least read-only rights over the
SNMP tables in the router.
l Friendly name – The name of this router. A meaningful name is suggested. If not specified,
Interchange uses a name in the following format: Router on <host name or IP>.
l Host – The fully qualified domain name or IP address of the internal interface of the router. It
must be accessible from all Interchange nodes.
l Remote CAPI port – The TCP port for the remote CAPI service on the router. This is used to
remotely control the ISDN features of the router. The factory default value for the R4300 is
2662.
l Controller index – The physical number of the ISDN controller within the router, which is
roughly equivalent to a physical ISDN modem connected to one ISDN line. Numbering starts at
1, but there can empty slots (for instance, only one controller with index 2 can be installed).
l Controller description – The name for this controller. A meaningful name is suggested. If not
specified, Interchange uses a name in the following format: Controller <index> on <host
name or IP>.
l Maximum concurrent outbound connections – The maximum number of outbound ISDN
physical calls that can be made on the B-channels by this controller. This is tied to the ISDN
network’s number of B-channels (2 for BRI, 24 or 30 for PRI). As the B-channels are used for
inbound and outbound calls, and OFTP requires receipts to be delivered, be careful specifying
this value. For example, if the maximum number of B-channels is 2, set the value to 1 to make
sure at least 1 channel is available for receipts and inbound connections, if any.
See the following figure: OFTP V1 embedded server in delivery exchange wizard.
l Server name – The name for the embedded OFTP server. This can be any name you want.
l SSID identification code – The start session identification (SSID) of the local or remote
party. Trading partners exchange SSIDs to identify each other in the protocol handshake and
session setup.
l Port – If TCP, the port on which the server listens for connections.
l OFTP protocol version – The protocol version being used (1.3 or 1.4).
l Partner uses RFC 2204, not RFC 5024 – For OFTP V1 only when protocol version is 1.3,
this check box tells Interchange the protocol release level (SSIDLEV) to use for the trading
partner. Select the check box if the partner uses the RFC 2204 implementation. This means the
SSIDLEV field in the start session (SSID) command has a value of 1. Do not select this option if
the partner uses the RFC 5024 implementation. This means the SSIDLEV field in the SSID
command has a value of 2. (Note that in either case the exchange point is being defined for
OFTP protocol revision level 1.3.)
l Clients must use TLS to connect to this server – Select this to set up Transport Layer
Security for the OFTP delivery exchange. When selected, the following sub-field displays.
o This server requires client authentication – If you selected TLS, select this check box
to require your partners to submit a certificate to verify their identity before the delivery
exchange allows the connection.
l Set OFTP session password – Enter a password only when required. The password can be no
longer than eight alphanumeric characters and is case sensitive.
If this is an exchange for receiving messages from a partner, your community presents this
password to the partner. The password is compared to the one the partner has stored for your
community.
If this is an exchange for sending messages to a partner, the partner must present this password
to your community. The password is compared to the one your community has stored for the
partner.
In either case, the passwords must match to establish the connection.
Click Next if you want to name the exchange. Otherwise, click Finish.
l Subscriber number – The subscriber number this embedded server answers to. This is the
number as seen by the ISDN router. Typically, prefix digits (international, external line) have
been removed by the telecom equipment. Check with your telecom operator for the correct
number.
l OFTP protocol version – The protocol version being used (1.3 or 1.4).
l Partner uses RFC 2204, not RFC 5024 – For OFTP V1 only when protocol version is 1.3,
this check box tells Interchange the protocol release level (SSIDLEV) to use for the trading
partner. Select the check box if the partner uses the RFC 2204 implementation. This means the
SSIDLEV field in the start session (SSID) command has a value of 1. Do not select the check box
if the partner uses the RFC 5024 implementation. This means the SSIDLEV field in the SSID
command has a value of 2. (Note that in either case the exchange point is being defined for
OFTP protocol revision level 1.3.)
l Set OFTP session password – Enter a password only when required. The password can be no
longer than eight alphanumeric characters and is case sensitive.
If this is an exchange for receiving messages from a partner, your community presents this
password to the partner. The password is compared to the one the partner has stored for your
community.
If this is an exchange for sending messages to a partner, the partner must present this password
to your community. The password is compared to the one your community has stored for the
partner.
In either case, the passwords must match to establish the connection.
Click Next if you want to name the exchange. Otherwise, click Finish.
Transport type
Select the option for receiving messages from remote partners:
l Port – The TCP port on which the server listens for connection requests. This field does not
apply to OFTP V1 X.25.
l OFTP protocol version – The protocol version.
l Require secure OFTP authentication – For OFTP V2 only, this is an extra layer of security to
enable senders and receivers to validate each other as genuine. There are two requirements to
enable secure OFTP authentication:
o Both the sender and receiver must enable secure OFTP authentication. If one party turns it
on and the other party does not, a protocol error is generated and the session between the
parties is disconnected.
o Both the sender and receiver must be using certificates. These are the normal certificates
used by a community and its partners to securely exchange messages. These are not TLS
certificates, which are additional certificates needed if TLS is configured for a delivery
exchange.
This is how the authentication works: The initiator of the connection uses the partner’s public
key to encrypt and send a short, random message to the partner. The partner decrypts the
message with its private key and sends the message back. The initiator compares the response to
the original message. If the messages match, the initiator has authenticated the partner. The
partner repeats the process to validate the initiator.
l Clients must use TLS to connect to this server – Select this option to set up Transport
Layer Security for the OFTP delivery exchange.
When selected, the following sub-field displays.
o This server requires client authentication – If you selected TLS, select this option to
require your partners to submit a certificate to verify their identity before the delivery
exchange allows the connection.
l Set OFTP session password – Enter a password only when required. The password can be no
longer than eight alphanumeric characters and is case sensitive.
If this is an exchange for receiving messages from a partner, your community presents this
password to the partner. The password is compared to the one the partner has stored for your
community.
If this is an exchange for sending messages to a partner, the partner must present this password
to your community. The password is compared to the one your community has stored for the
partner.
In either case, the passwords must match to establish the connection.
Click Next if you want to name the exchange. Otherwise, click Finish.
Network type
Select the network protocol. The options are:
l TCP. Transmission Control Protocol is the basic communications protocol of the Internet.
l X.25. An ITU-T standard protocol suite for packet-switched wide area network communications.
l X.25 over ISDN (B-channel). Integrated Services Digital Network broadband channel
supports data transfers over telephone networks.
If you select an X.25 option, you are prompted to select a router. You can select an existing router
or add one to use.
l Friendly name – The name of this router. A meaningful name is suggested. If not specified,
Interchange uses a name in the following format: Router on <host name or IP>.
l Host – The fully qualified domain name or IP address of the internal interface of the router. It
must be accessible from all Interchange nodes.
o Maximum concurrent outbound connections – The maximum number of outbound
X.25 logical connections that can be made by this router. This is tied to the X.25 network’s
number of allowed virtual channels and bandwidth.
As the virtual channels are used for inbound and outbound connections, and OFTP requires
receipts to be delivered, be careful when specifying this value. For example, if the maximum
number of channels is 10, set this value to 4. This makes sure at least 6 channels stay
available for receipts and inbound connections, if any.
l Friendly name – The name of this router. A meaningful name is suggested. If not specified,
Interchange uses a name in the following format: Router on <host name or IP>.
l Host – The fully qualified domain name or IP address of the internal interface of the router. It
must be accessible from all Interchange nodes.
l Remote CAPI port – The TCP port for the remote CAPI service on the router. This is used to
remotely control the ISDN features of the router. The factory default value for the R4300 is
2662.
l Controller index – The physical number of the ISDN controller within the router, which is
roughly equivalent to a physical ISDN modem connected to one ISDN line. Numbering starts at
1, but there can empty slots (for instance, only one controller with index 2 can be installed).
l Controller description – The name for this controller. A meaningful name is suggested. If not
specified, Interchange uses a name in the following format: Controller <index> on <host
name or IP>.
OFTP settings
l Hostname – If TCP, the fully qualified domain name or IP address of the OFTP server.
l Partner ISDN number – For ISDN, the partner’s ISDN number. If prefixes are required to
access an external line or an international number, include those in the number.
l Port – The TCP port on which the server listens for connection requests. This field does not
apply to OFTP V1 X.25.
l SSID identification code – The start session identification (SSID) of the local or remote
party. Trading partners exchange SSIDs to identify each other in the protocol handshake and
session setup.
l OFTP protocol version – The protocol version being used (1.3 or 1.4).
l Remote network user address – The NUA of the remote partner’s server to connect to (OFTP V1
X.25 only).
l Charge called party instead of caller – When this check box is select, and when supported
by the carrier and accepted by the partner upon call establishment, the called party is charged
for the call instead of the caller (OFTP V1 X.25 only).
Click Next if you want to name the exchange. Otherwise, click Finish.
See the following figure: add OFTP V2 client in delivery exchange wizard.
OFTP settings
l Hostname – If TCP, the fully qualified domain name or IP address of the OFTP server.
l Port – The TCP port on which the server listens for connection requests. This field does not
apply to OFTP V1 X.25.
l SSID identification code – The start session identification (SSID) of the local or remote
party. Trading partners exchange SSIDs to identify each other in the protocol handshake and
session setup.
l OFTP protocol version – The protocol version.
Click Next if you want to name the exchange. Otherwise, click Finish.
Web-based Distributed Authoring and Versioning (WebDAV) is a set of extensions of HTTP. WebDAV
enables users to edit and manage files collaboratively on remote web servers. RFC 4918 defines the
extensions (see http://tools.ietf.org/html/rfc4918).
When you elect to set up a WebDAV transport for a community using an embedded server, the
delivery exchange wizard asks whether you want to:
l Use a detached HTTP server (partner only)
l Use the system’s global embedded HTTP server
l Use a previously defined embedded HTTP server (if available)
l Use a previously defined embedded HTTPS server (if available)
l Define a new embedded HTTP or HTTPS server
If you choose to use the system’s global embedded HTTP server, the wizard uses the default routing
ID for the community as the last string in the URL. You can accept or change the string.
If you choose to use a previously defined server, the wizard prompts for the community routing ID
to append to the URL.
If you choose to define a new embedded HTTP server, the wizard prompts for a server name, port
number and whether clients must use SSL to connect to the server.
If you choose to define a new embedded HTTPS server, you must add an SSL certificate for the
server. After setting up the server in the delivery exchange wizard, go to the community summary
page and click Change an embedded transport server near the bottom of the page. Click the
name of the server to open the maintenance page. If the server needs a certificate, you are
prompted to click Add an SSL server certificate. This action opens the wizard for adding a
certificate.
Except for the global embedded server, embedded HTTP servers can be designated as HTTPS.
See Staged HTTP on page 958 for security guidelines for the embedded HTTP server.
See the following figure: add embedded HTTP server for WebDAV (1 of 4)
The following fields are used in the delivery exchange wizard for adding a WebDAV transport for a
community by defining a new embedded HTTP server.
l Server name – Type a name for the new embedded HTTP server. This can be any name you
want. You can select this sever when setting up additional embedded HTTP delivery exchanges
later.
l Port – The port number that listens for incoming HTTP connections. Click the field to display a
list of ports already in use.
l Clients must use SSL to connect to this server – Select this to set up an HTTPS delivery
exchange. A non-selected option indicates HTTP. When you select this option, the following
sub-field displays.
l This server requires client authentication – If you selected SSL, select this option to
require your partners to submit a certificate to verify their identity before the delivery exchange
allows the connection. Clear this option to use non-authenticated HTTPS. If you select this
option, you must add an authentication certificate for the partner.
Click Next to continue the configuration.
See the following figure: add embedded HTTP server for WebDAV (2 of 4).
l URL – The wizard displays the URL for the transport. This is the URL your partner uses to send
messages to the community. The last item in the URL is the community routing ID. This is a
suggested value. You can accept it or type another string.
Click Next to continue the configuration.
See the following figure: add embedded HTTP server for WebDAV (3 of 4).
You have these options for selecting a user account:
l Select an existing account from the drop-down list (if available)
l Define a new account
l Define an account later (see Manage users of embedded FTP servers on page 347)
If you elect to define a new account, user name and password fields display. If you are defining the
first user account, the wizard suggests for the user name and password the community default
routing ID for a trading server or integration for an integration server.
l User name – The user name to connect to the server. Not only does your partner use this name
to connect, but Interchange creates a directory of the same name. This is the home directory for
the WebDAV account. It is where a partner sends messages to your community via WebDAV. If
you use the default location for the common directory, the directory is at <install
directory>\common\data\webDAV\users\trading. But if you are configuring an
integration transport, the path is <install
directory>\common\data\webDAV\users\integration.
Caution Do not configure a back-end system to retrieve files from or write files to
common\data\webDAV\users\trading. Doing so could result in operational
difficulties. The back-end system always should interact with transports defined for
integration and allow Interchange to route messages to and from trading transports.
l Password – The password to connect to the server.
l Confirm password – The password to connect to the server. Anonymous connections are not
supported.
Click Next to continue the configuration.
See the following figure: add embedded HTTP server for WebDAV (4 of 4).
But if you add an amended path, the effective directory is the specified subdirectory. For
example:
common\data\webDAV\users\trading\<user account>\<amended path>
For the first integration server, the wizard suggests an amended path of in for integration
delivery or out for integration pickup. By default the home directory (/) is not used, but you can
change this.
Interchange keeps track of the WebDAV directory structure for you. Do not manually change any
directories Interchange creates for managing messages transported via embedded HTTP servers
for WebDAV.
Click Next if you want to name the exchange. Otherwise, click Finish.
Secure file message protocol supports light-weight packaging for payload POST methods into the
Interchange (for example, using curl).
Secure file message protocol supports transfers and failover restart for recovery from service
interruptions.
If you are administrating WebTraders and want to enable large-file handling for your WebTrader
end-users, you must enable a Secure file trading pickup on your WebTrader sponsor community.
When secure file is enabled on the sponsor community, the sponsor's WebTrader partners use a
dedicated applet to upload documents to the sponsor's server through the Secure file trading
pickup.
The following transports support Secure file protocol:
l HTTP
l HTTPS
l FTP
l FTPS
l SFTP
l File system
l MQSeries
l JMS
l Staged HTTP web servlet
Secure file message protocol pre-dates AS3, and is not the same as AS3. If you are using FTP and
AS3 is available, we recommend using AS3. Moreover, if you and your partner both use Axway file-
trading software, use AS2 rather than Secure file over HTTP.
Pluggable server
The pluggable embedded server transport is available only to users who have the optional Software
Development Kit. If you are an SDK user, see the pluggable embedded server chapter in the
Interchange Developer Guide for configuration information.
Interchange supports embedded server extensibility through pluggable servers for customized
message consumption. This enables custom code to control message exchanges with any back-end
application or custom trading protocol without changing the base code.
When a customized transport protocol is desired, developers can use the pluggable server API to
create servers to run inside of Interchange.
Prerequisite
You must have a community defined.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
Prerequisites
The partner delivery resides in a partner object. Before you add a partner delivery you must add a
partner object to represent the MLLP client partner.
Procedure
1. In the user interface, select Partners > Manage partners to open the Partners page.
2. Select the partner you want to use to represent your MLLP client partner.
3. On the partner map of the partner summary page, click the Partner delivery icon.
4. On the Delivery exchanges page, click Add a delivery.
5. On the Choose message protocol page, select No packaging and click Next.
6. On the Choose transport protocol page, select MLLP and click Next.
7. On the Configure the MLLP settings page, complete the fields:
l MLLP server – Enter the address of the MLLP server to which you are connecting.
l Port – Enter the server port for MLLP connections.
l Client must use TLS to connect to this server – Select this option if TLS is required
for the client connection to the MLLP server.
l Enable host name verification – If you require TLS use for connection to the server,
you can optionally select this additional security feature.
8. On the Exchange name page, enter a name for the partner delivery.
9. Click Finish.
Prerequisites
The partner delivery resides in a partner object. Before you add a partner delivery you must add a
partner object to represent the Web Services exchange partner.
If you are configuring Interchange a to provide Web Services, your partner is a Web Services client
(consumer).
If you are configuring Interchange to consume Web Services, you partner is a Web Services provider
server.
The WSDL parsing wizard creates collaboration settings at the level of the community/partner
delivery point. These settings:
l Override any other level of settings in the collaboration settings hierarchy (default, community-
specific, category-specific, community to partner specific, community to partner delivery
specific.). For information about the collaboration settings hierarchy, see Collaboration settings
on page 909.
l Apply only to the messages sent from the selected community to the partner you are
configuring.
To use the wizard and automatically generate community collaboration settings for Web Services
sent to a specific partner, see Option 1: Configure with WSDL parsing wizard on page 323. You can
create the processing connection now or later. The processing connection links the mapping part to
the transport.
Procedure
When you execute this procedure, you have a choice of two methods of configuring the properties
of the connection to the Web Services partner (provider):
l If you have stored a copy of the provider's WSDL on your file system or if you can connect to the
provider URL and retrieve the WSDL, you can configure the delivery using the WSDL parser
wizard (method 1 below).
l Manually configure the delivery (method 2 below)
7. On the same page, do one of the following:
l Browse to find the WSDL file. This is the default option.
l Select Retrieve WSDL from URL and enter the URL of the WSDL. If the WSDL is located
behind a proxy, and enter the proxy connection information:
o Proxy user
o Proxy password
o Proxy port
o Proxy host
8. Click Next.
9. On the Choose endpoint page, select the operation you want to call from the WSDL and click
Next.
10. The wizard checks for a username token in the WSDL policies. If one is detected, the interface
displays the Define username token page, otherwise, skip to the next step. Complete the fields
in this page to define a user account to use when calling the service:
l Define a new user? – Select this option to define a new user and password to use when
calling the service.
l User name – Enter the new user name.
l Password / Confirm password – Enter and confirm a password for the new user.
Click Next.
11. On the Choose community page, select the community for who will send the request to this
partner, and then click Next. The communities you see in the drop-down list are communities
that are currently linked to the partner. The wizard completes the processing connection
automatically when the delivery exchange is created.
12. On the Choose transport protocol page accept the default HTTP protocol and click Next.
13. On the Configure the HTTP settings page, complete the fields and then click Next:
l URL — Enter the partner's WebService URL.
l Select Encode or Decode to use either https:// or http:// , respectively.
l Clients must use SSL to connect to this server — Select this option if you must
connect to this server using SSL. If you select this option, you can also select the Enable
host name verification option.
l This server requires a user name and password — select this option if the partner's
server requires this information, then complete the following fields:
o User name — Enter the client's user name.
o Password — Enter the client's password.
o Confirm password — Enter the client's password again for verification.
14. On the Exchange Name page, enter a name for this delivery. This is the friendly name that is
used to identify this delivery in the user interface.
15. Click Finish.
o Password — Enter the client's password.
o Confirm password — Enter the client's password again for verification.
9. On the Name page, enter a name for this delivery. This is the friendly name that is used to
identify this delivery in the user interface.
10. Click Finish.
The interface adds the Web Services delivery to the list of available delivery exchanges for this
partner.
If you enter a name that was previously created, the Duplicate Exchange Point Name message
displays. Enter an unused name.
l You can tune or modify the Web Services delivery.
l The wizard generates values in the community / partner collaboration settings. These settings
specify how to package messages sent from the linked community to the partner.
Prerequisites
The trading pickup resides in a community object. Before you add a trading pickup you must add a
community to represent your enterprise as a Web Services exchange participant.
Procedure
1. In the user interface, from the Trading configuration menu select Manage trading
configuration.
2. From the list of communities, click the name the community you created in step 1. This displays
the Summary page for that community.
3. Click the Trading pickup icon in the navigation graphic to open the Trading pickups page
for the community.
4. Click Add a pickup to open the Exchange Wizard.
5. For the transport protocol select Web Services (HTTP).
l You can tune or modify the Web Services pickup.
To view and modify a trading pickup:
l ebXML on page 545
l Send ebXML via an intermediary on page 562
For details about the fields you can view and modify, see Fields for modifying community pickups
and partner deliveries on page 328.
Transport-specific tabs
l Modify an application pickup or delivery on page 202
l Modify an AS4 embedded server pickup on page 539
l Modify a file system pickup or delivery on page 329
l Modify an FTP (embedded) pickup or delivery on page 333
l Modify an FTP (external) pickup or delivery on page 337
l Modify an SFTP (embedded) pickup or delivery on page 349
l Modify an SFTP (external) pickup on page 352
l Modify an HTTP transport on page 359
l Modify a staged HTTP transport on page 365
l Modify a JMS pickup or delivery on page 368
l Modify an MLLP trading delivery on page 373
l Modify an MLLP trading pickup on page 372
l Modify an MQSeries pickup or delivery on page 375
l Modify a pluggable server pickup or delivery on page 380
l Modify an SMTP (embedded) transport on page 383
l Modify an SMTP/POP (external) transport on page 388
l Modify a Web Services API server application pickup or delivery on page 245
l Modify a Web Services trading pickup on page 397
l Modify a Web Services trading delivery on page 401
l Modify a WebDAV pickup or delivery on page 405
Example without the original file extension:
z47e4120_4ce
The default value is suitable in almost all cases. However, if a partner says your trading engine is
overrunning his receiving system, decrease the value. (This advice does not apply to OFTP X.25
or X.25 over ISDN, as the default maximum value is 1 for those transports.)
If sending messages to Transfer CFT via PeSIT, the value in this field must be less than the
CFTTCP setting in Transfer CFT.
This setting applies only to transports that send messages to partners or deliver messages to
integration.
l Retries – The number of times Interchange retries connecting to the partner’s transport if the
initial attempt to connect and send the message failed. The following are common reasons for
triggering retries.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from the back end or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners. Backup files are stored in \<install
directory>\common\data\backup, unless you specify otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands.
In general, this setting should not be used. Usually it is best to let Interchange automatically
determine which node should be responsible for initiating the polling of which exchange point.
This setting is useful if you have a cluster that spans geographical locations and each location
has its own local transport servers. In this situation, you would use this setting to ensure the
exchange points associated with the transport servers are assigned to nodes in the vicinity of the
transport servers. If you have a Peer Network license, note that these settings are not cloneable.
Note: There can be only one Interchange per (clustered) host. In this case you can p ick which
trading engine (that is, which host) performs the work.
If the back-end system uses the same account to upload messages, you must con figure a separate
directory for that purpose on a pickup exchange.
If no account exists, click Add to add an account and associated directory.
This chapter provides information for completing fields in the maintenance pages.
For related information, see the following chapters:
l Lockout settings for FTP (embedded) server users on page 452
l Directory path – The FTP directory associated with the user. A specific combination of user
and directory can be associated with only one exchange.
l Specify what to do when the back-end system uploads messages to subdirectories
of the directories listed above (pickup only)– Select an option:
o Allow – Enables the user to write files to any subdirectory under the root path.
o Do not allow – Enables the writing of files to a subdirectory under the root path only when
a message attribute is set up for each subdirectory level.
Example without the original file extension:
z47e4120_4ce
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to a
back-end application or resend messages to partners. Backup files are stored in \<install
directory>\common\data\backup, unless you specify otherwise.
l Restrict maximum file size for this transport – Optionally lets you specify the maximum
size of files a transport can handle.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log.
Express the maximum size in bytes. Do not use commas. For example, a kilobyte is 1024 bytes, a
megabyte is 1048576 bytes, a gigabyte is 1073741824 bytes. The smallest maximum allowed is
1000 bytes. On the opposite extreme, you can enter the largest number the field can
accommodate.
In most cases, use binary mode, (default). Always trade packaged files (for example, AS2, AS3,
Secure file) in binary mode.
Use binary mode also for trading text files. This applies to text files with no packaging if the
receiver is not sensitive to the type of line-ender. If the receiver requires a particular line-ender,
select an ASCII option to have Interchange translate the line-ender based on what is required by
the back-end system.
Three ASCII options are available for pickup exchanges, but only one for delivery exchanges.
The FTP specification requires the sender to always use CRLF as the line-ender when transmitting
files in ASCII mode. It is up to the receiver to translate the line-ender to something else if desired.
l Use passive mode (delivery only) – Select this option to transmit files using passive mode. In
this mode, during the connection, the server specifies the port it will listen to for the data
connection.
l Use active mode (delivery only) – Select this option to transmit files using active mode. Then
in the Active ports field, enter the ports where the client will listen to the data port of the
server.
Note: To configure Interchange to connect to a partner's embedded FTPS server in active mode,
you must add the public key of the client server as a trusted SSL root certificate on the FTPS
embedded server used for the pickup/delivery exchange.
But you can use the following because a period is the first character of the inbox directory
name:
c:\data\pickup\.inbox
When receiving files from a partner, we recommend that your partner write files to the inbox
directory first and then move them to the pickup directory when they are ready to be
retrieved. This process is automatic if your partner also uses Axway products B2Bi,
Interchange or Activator. If the partner uses other software to upload files to your server, the
software should be configured to initially upload the files to the inbox directory and move
them to the pickup directory when they are ready to be retrieved.
For outbound integration, the back-end system must write the message to the inbox and
then move it to the pickup directory.
For inbound integration and sending outbound to partners, Interchange writes to the inbox
and then moves the message to the pickup directory.
o Use special extension in pickup directory for temporary files – If you prefer not to
use an inbox, select this option. While a file is being written to the pickup directory, a
temporary extension is added so the system knows not to retrieve it because the file is only
partially written. Once fully written, the temporary extension goes away and the file can be
retrieved.
l Attempt restarts – Indicates whether the system resumes transferring large files at the point
interrupted when a connection is lost before a transfer is completed. If you select this check box,
the system resumes processing of files at least as large as specified in the restartable minimum
bytes field. This checkpoint-restart feature is worthwhile only for large documents. If this option
is not used, the system starts a file transfer over when processing is interrupted.
o Restartable minimum bytes (MB) – If attempt restarts is selected, the minimum size of a
file that triggers the system to continue the file transfer at the point interrupted before the
connection was lost. The minimum size is in megabytes. The system only resumes transfers
of files that meet this minimum. The system starts over the transfer of smaller files whose
processing is interrupted.
o Temporary file lifetime (hours) – If attempt restarts is selected, how long the system
retains a file whose transfer has been interrupted while waiting for the connection to be
restored. This temporary file enables the system to resume the transfer at the point
interrupted.
original file name had an extension, the same extension is appended to the unique name the
system generates.
Example with the original file extension:
dabeed45_4cb.edi
Example without the original file extension:
z47e4120_4ce
If you select the consumption order option "Process by timestamp" on this tab, the software
automatically sets the value of this field to "1".
l Connect timeout (seconds) – Time in seconds Interchange waits for a connection to the
delivery exchange before the attempt times out. Although the default value is 30 seconds, this
may be longer than the interval allowed by your operating system (OS). For example, Windows
XP by default allows a maximum timeout of 20 seconds. The actual connect timeout interval is
the lesser of the OS timeout and the value set in Interchange.
l Read timeout (seconds) – Time in seconds Interchange waits to read data from the delivery
exchange before terminating the connection.
l User commands – Enter user commands such as SITE to be sent to the server after login.
Commands must be entered in the exact case and format expected by the server. For example,
most FTP clients allow “mkdir test”, but most servers only accept “MKD test”. Consult RFC 959
for a list of standard FTP commands. You can use FTP commands that do not make use of the
FTP data connection. Commands that make use of the FTP data connection are not supported.
In addition, specific servers may support other commands. Refer to the server documentation for
more information.
If any command fails, the remaining commands are not executed, and production to the FTP
server fails. To avoid possible failures, preface any command with an “at” sign (@) to indicate
that errors from that command should be ignored, for example, “@MKD test”. Preface any
command with an asterisk to cause the entire line to be treated as a comment, for example,
“*Create test directory”.
This field is available for the FTP transport only.
If you want to add a new command set file, create the file and add an entry for it in
filereg.xml. For example, if your new command set is called myftpcommandset.xml, enter
that name in the field and add the following entry to filereg.xml:
<File name="myftpcommandset.xml" path="conf/myftpcommandset.xml"/>
In the file name filter pattern field, type the formats of the files you want the transport to
consume or ignore. Use conventional wildcard characters for file names or extensions or both.
The following describes the supported characters and symbols:
* One or more characters.
? Any single character.
[ ] Matches any single character within the brackets. For example, r[aou]t matches
rat, rot and rut.
, Commas can be used as and/or operators within brackets (for example, r[a,o,u]t).
- Use hyphens within brackets to specify ranges of letters or numbers. For example,
[0-9] is for any number between 0 and 9, and [A-Za-z] is for any upper- or lower-
case letter.
. Use the character dot to separate the file name and extension. For example, *.txt.
| Use the pipe character to separate multiple file name formats. For example,
*.edi|*.txt|[a,b,c]?.xml.
Specify with the radio buttons whether the filter pattern is inclusive or exclusive. If inclusive,
only files matching the pattern are consumed. If exclusive, files matching the pattern are
ignored, but all other files are consumed.
Interchange ignores files that do not meet filtering conditions. Ignored files are not reported in
Message Tracker. Such files also do not generate log messages unless the following property is
set to debug in conf\log4j.properties:
log4j.category.com.cyclonecommerce.tradingengine
This control is available only for transports used for picking up messages from integration or
receiving messages from partners.
l Polling configuration:
o Maximum files per polling interval – The highest number of messages the system can
retrieve each time it polls.
o Polling interval (seconds) – The interval in seconds Interchange waits before polling for
messages to retrieve.
l Consumption order:
o Allow server to determine – This is the default behavior. Interchange processes
messages in a random order.
o Process by timestamp (oldest first)– Select this option if you want Interchange to process
messages in the order oldest-to-newest. The external FTP server must support the MDTM
command.
If you select this option, the value of the field "Maximum concurrent connections" is
automatically set to "1".
Note: In some cases setting concurrent connections to "1" may cause reduced throughput.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for both application and trading deliveries.
This is a way to allocate messages among nodes in a clustered environment. When the maximum
is reached, another node is contacted to take messages and so on. This field is not applicable in
a single node environment.
has its own local transport servers. In this situation, you would use this setting to ensure the
exchange points associated with the transport servers are assigned to nodes in the vicinity of the
transport servers. If you have a Peer Network license, note that these settings are not cloneable.
l Zone – If you use DMZ nodes and want to send or receive messages via a specific DMZ zone,
select the zone. This field is available only when the user license supports Secure Relay and a
DMZ zone has been added. For details, see Secure Relay DMZ nodes on page 474.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, re-sends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Connect timeout (seconds) – Time in seconds Interchange waits for a connection to the
delivery exchange before the attempt times out. Although the default value is 30 seconds, this
may be longer than the interval allowed by your operating system (OS). For example, Windows
XP by default allows a maximum timeout of 20 seconds. The actual connect timeout interval is
the lesser of the OS timeout and the value set in Interchange.
l Read timeout (seconds) – Time in seconds Interchange waits to read data from the delivery
exchange before terminating the connection.
l User commands – Enter user commands such as SITE to be sent to the server after login.
Commands must be entered in the exact case and format expected by the server. For example,
most FTP clients allow “mkdir test”, but most servers only accept “MKD test”. Consult RFC 959
for a list of standard FTP commands. You can use FTP commands that do not make use of the
FTP data connection. Commands that make use of the FTP data connection are not supported.
In addition, specific servers may support other commands. Refer to the server documentation for
more information.
If any command fails, the remaining commands are not executed, and production to the FTP
server fails. To avoid possible failures, preface any command with an “at” sign (@) to indicate
that errors from that command should be ignored, for example, “@MKD test”. Preface any
command with an asterisk to cause the entire line to be treated as a comment, for example,
“*Create test directory”.
This field is available for the FTP transport only.
l Command set file key – The FTP command set file controls the commands sent to the FTP
server for operations such as send, receive, delete. The default command set file is
ftpcommandset.xml. This field lets you specify a different command set file. In most cases you
can use the default value. Changing this is only for advanced FTP users with specialized needs.
The field value is the name of an entry in filereg.xml in <install directory>\conf that
points to another file in the conf directory. The following is the entry in filereg.xml for the
default ftpcommandset.xml file:
<File name="ftpcommandset.xml" path="conf/ftpcommandset.xml"/>
If you want to add a new command set file, create the file and add an entry for it in
filereg.xml. For example, if your new command set is called myftpcommandset.xml, enter
that name in the field and add the following entry to filereg.xml:
<File name="myftpcommandset.xml" path="conf/myftpcommandset.xml"/>
server automatically deletes files that have been downloaded, deselect this option. This option
applies only to delivery exchanges using external FTP servers for picking up messages from
integration or receiving messages from partners.
l Enable file filtering – Available for some exchanges used for application pickups and for
receiving from partners, file filtering allows Interchange to discriminate which files to consume
based on file names.
In the file name filter pattern field, type the formats of the files you want the transport to
consume or ignore. Use conventional wild card characters for file names or extensions or both.
The following describes the supported characters and symbols:
* One or more characters.
? Any single character.
[ ] Matches any single character within the brackets. For example, r[aou]t matches
rat, rot and rut.
, Commas can be used as and/or operators within brackets (for example, r[a,o,u]t).
- Use hyphens within brackets to specify ranges of letters or numbers. For example,
[0-9] is for any number between 0 and 9, and [A-Za-z] is for any upper- or lower-
case letter.
. Use the character dot to separate the file name and extension. For example, *.txt.
| Use the pipe character to separate multiple file-name formats. For example,
*.edi|*.txt|[a,b,c]?.xml.
Specify with the radio buttons whether the filter pattern is inclusive or exclusive. If inclusive,
only files matching the pattern are consumed. If exclusive, files matching the pattern are
ignored, but all other files are consumed.
Interchange ignores files that do not meet filtering conditions. Ignored files are not reported in
Message Tracker. Such files also do not generate log messages unless the following property is
set to debug in conf\log4j.properties:
log4j.category.com.cyclonecommerce.tradingengine
l Community FTP accounts
l Application FTP accounts
l Partner FTP accounts
There are different types of accounts because a single embedded FTP server can be used for
integration or trading but not both. Separate embedded FTP servers are required. For more
information, see FTP (embedded) transport configuration on page 275 and Embedded FTP user
accounts on page 276.
On the FTP user pages you can change the password for a user and enable or disable a user. You
also can click a link to the exchange point associated with a user. An FTP user account can be
deleted only if it is not associated with a delivery exchange.
Attempting to log on to a disabled account results in a 421 account disabled message.
The user is locked out for a specified number of minutes. The user must wait until the lockout
interval expires, unless an administrator unlocks the user before the interval ends.
1. In the navigation graphic at the top of a community summary page, click Application
delivery.
2. In the list of available application deliveries, click an FTP (embedded) transport to open its
maintenance page.
3. Select the Directories tab and check whether any users have been locked out.
4. Click Unlock to enable the user to try again to connect.
/**
* Java method to submit a message to an embedded FTP server.
Typically a back-end system might do
* this to submit a message to an integration pickup exchange, but a
partner could also use this to submit a
* message to a community exchange on the trading side. In this
example the message is dropped off to a
If the partner or back-end system uses the same account to upload messages, you must configure a
separate directory for uploads on a delivery exchange.
If no account exists, click Add to add an account and associated directory.
If the partner or back-end system uses the same account to pick up messages, you must configure a
separate directory for pickups on a pickup exchange.
If no account exists, click Add to add an account and associated directory.
An external SFTP pickup resides outside of Interchange.
To add a key, click Certificates in the navigation graphic at the top of the community summary
page. Select the SSH keys tab. Click Add an SSH key, follow the prompts and click Add.
Select the key as the default SSH key after it has been added. For more information see Public-
private key and password authentication on page 292.
l Use host-based authentication – This is not used.
Directories tab
l Pickup directory – Type the path of the directory on your server where messages are picked
up. When Interchange polls the server for files, it only looks in the pickup directory, not an
inbox directory.
l Use temporary files to avoid read/write collisions – We recommend using this option to
prevent Interchange from attempting to retrieve partially written files. When this is selected, you
must select one of the two following options.
o Use separate directory for temporary files – Type the full path of an inbox directory
(for example, c:\data\inbox). Files are uploaded to this directory. When fully written,
files are moved to the pickup directory for retrieval.
Do not put the inbox under the pickup directory unless you use a period at the beginning of
the inbox name. Interchange and other applications ignore directories and files that begin
with periods.
For example, do not use the following directory structure:
c:\data\pickup\inbox
But you can use the following because a period is the first character of the inbox directory
name:
c:\data\pickup\.inbox
When receiving files from a partner, we recommend that your partner write files to the inbox
directory first and then move them to the pickup directory when they are ready to be
retrieved. This process is automatic if your partner also uses Axway products B2Bi,
Interchange or Activator. If the partner uses other software to upload files to your server, the
software should be configured to initially upload the files to the inbox directory and move
them to the pickup directory when they are ready to be retrieved.
For outbound integration, the back-end system must write the message to the inbox and
then move it to the pickup directory.
For inbound integration and sending outbound to partners, Interchange writes to the inbox
and then moves the message to the pickup directory.
o Use special extension in pickup directory for temporary files – If you prefer not to
use an inbox, select this option. While a file is being written to the pickup directory, a
temporary extension is added so the system knows not to retrieve it because the file is only
partially written. Once fully written, the temporary extension goes away and the file can be
retrieved.
Filenames tab
l Preserve original filenames – Select this if you want original file names to be preserved
when Interchange delivers messages. For binary messages, we recommend that you preserve
original file names. Otherwise, Interchange assigns a unique file name that does not readily
identify the contents of the file. Preserving original file names also allows your back-end
application to process binary messages based on their file names. This field applies to both
application and partner deliveries.
l Overwrite duplicate filenames – An option when you choose to preserve original file names.
If duplicate file names are detected, Interchange overwrites the existing file.
l Sequentially number duplicate filenames – An option when you choose to preserve
original file names. If duplicate file names are detected, Interchange appends a number to the
new file. For most transports, the appended number is consecutively numbered. For FTP and
SFTP, however, the appended number is hexadecimal and looks like this: filename_c4.
l Generate unique filenames – Select to have the system provide a unique file name instead of
using the original name. This field applies to both application and partner deliveries. When
selected, files are given arbitrary names. The names always have less than 30 characters and
often have less than 20 characters.
Appended to the file name is a hex representation of a monotonically increasing file name
counter that is maintained in the database and guaranteed to be unique across all nodes in a
cluster. In addition, if the original file name had an extension, the same extension is appended
to the unique name the system generates.
The following are examples of unique file names generated by the system, one with the original
file extension and one without:
o dabeed45_4cb.edi
o z47e4120_4ce
Advanced tab
l Maximum concurrent connections (for trading pickups only) – The number of total open
connections Interchange server can make to a partner. If you are operating in a cluster
environment, this is the total number across the entire cluster, no matter how many JVM nodes
are running. For example, if the value is 100 connections and there are 150 messages to
consume, Interchange opens only 100 connections to that partner. The remaining 50 messages
are queued until connections become available.
l Maximum concurrent connections – The number of total open connections Interchange
server can make to a partner. If you are operating in a cluster environment, this is the total
number across the entire cluster, no matter how many JVM nodes are running. For example, if
the value is 100 connections and there are 150 messages to send, Interchange opens only 100
connections to that partner. The remaining 50 messages are queued until connections become
available.
The default value is suitable in almost all cases. However, if a partner says Interchange is over
running his receiving system, decrease the value. (This advice does not apply to OFTP X.25 or
X.25 over ISDN, as the default maximum value is 1 for those transports.) If sending messages to
Transfer CFT via PeSIT, the value in this field must be less than the CFTTCP setting in Transfer
CFT. This setting applies only to transports that send messages to partners or deliver messages to
integration.
l Retries – This is the number of times Interchange will retry connecting to the partner’s
transport if the initial attempt to connect and send the message failed. The following are
common reasons for triggering retries.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Read timeout (seconds) – How long in seconds that Interchange waits to read data from the
delivery exchange before terminating the connection.
l Override SSH ciphers – Select this check box to specify, using the Add and Remove
buttons, the specific ciphers supported for the server. If not selected, all ciphers are supported
by default. The default is less secure than specifying only certain ciphers. This check box is
available for production delivery exchanges.
The default order in the Available column is the preferred order of use. Once ciphers are moved
to the Selected column, you can arrange the order. Interchange uses the ciphers in the order
listed.
l Maximum block size per downloading packet – Sets the maximum size of the packets that
can be downloaded from an external SFTP server by the SFTP client within Interchange. The
client downloads messages in a series of data packets. By default the maximum size is 32768
data packet units. The default value is compatible with most SFTP servers. But when handling
messages of a certain size (2-3 megabytes or larger), some servers cannot process many packets
of the default size and downloading hangs. If this occurs, reduce the packet size maximum.
Adjusting the value is a trial-and-error process. You may have to test several values depending on
the size of the messages being processed. For example, when messages are approximately 3 MB
in size, the maximum packet size can be set at 4096. This field is available only on the trading
and application pickup exchanges.
l Enable file filtering – Available for some exchanges used for application pickups and for
receiving from partners, file filtering allows Interchange to discriminate which files to consume
based on file names. In the file name filter pattern field, type the formats of the files you want
the transport to consume or ignore. Use conventional wildcard characters for file names or
extensions or both. The following describes the supported characters and symbols:
* One or more characters.
? Any single character.
[ ] Matches any single character within the brackets. For example, r[aou]t matches
rat, rot and rut.
, Commas can be used as and/or operators within brackets (for example, r[a,o,u]t).
- Use hyphens within brackets to specify ranges of letters or numbers. For example,
[0-9] is for any number between 0 and 9, and [A-Za-z] is for any upper- or lower-
case letter.
. Use the character dot to separate the file name and extension. For example, *.txt.
| Use the pipe character to separate multiple file-name formats. For example,
*.edi|*.txt|[a,b,c]?.xml.
Specify with the radio buttons whether the filter pattern is inclusive or exclusive. If inclusive,
only files matching the pattern are consumed. If exclusive, files matching the pattern are
ignored, but all other files are consumed.
Interchange ignores files that do not meet filtering conditions. Ignored files are not reported in
Message Tracker. Such files also do not generate log messages unless the following property is
set to debug in conf\log4j.properties:
log4j.category.com.cyclonecommerce.tradingengine
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners. Backup files are stored in \<install
directory>\common\data\backup, unless you specify otherwise.
l Restrict maximum file size for this transport – Optionally lets you specify the maximum
size of files a transport can handle.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log. If received via HTTP, a 413 response also is sent and the connection is
closed. A 413 message is Request Entity Too Large. The maximum size must be expressed in
bytes. Do not use commas. For instance, a kilobyte is 1024 bytes, a megabyte is 1048576 bytes,
a gigabyte is 1073741824 bytes. The smallest maximum allowed is 1000 bytes. On the opposite
extreme, you can enter the largest number the field can accommodate. This control is available
only for transports used for picking up messages from integration or receiving messages from
partners.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for both application and trading deliveries.
l Maximum files per polling interval – The highest number of messages the system can
retrieve each time it polls.
l Polling interval (seconds) – The interval in seconds Interchange waits before polling for
messages to retrieve.
l Zone – If you use DMZ nodes and want to send or receive messages via a specific DMZ zone,
select the zone. This field is available only when the user license supports Secure Relay and a
DMZ zone has been added. For details, see Secure Relay DMZ nodes on page 474.
The user is locked out for a specified number of minutes. The user must wait until the lockout
interval expires, unless an administrator unlocks the user before the interval ends.
l Community SFTP accounts
l Integration SFTP accounts
l Partner SFTP accounts
There are different types of accounts because a single embedded SFTP server can be used for
integration or trading but not both. Separate embedded SFTP servers are required. For more
information, see SFTP (embedded) transport configuration on page 286 and SFTP user accounts on
page 287.
On the SFTP user pages you can change the password or the public key file for a user and enable or
disable a user. You also can click a link to the exchange point associated with a user. An SFTP user
account can be deleted only if it is not associated with a delivery exchange.
Attempting to log on to a disabled account results in a 421 account disabled message.
The maintenance pages display all of the transport fields that can be changed, while the exchange
wizard has only the most commonly used. The following are the fields on the Settings and
Advanced tabs.
If you require information about SSL authentication, see SSL authentication on page 775.
For information about managing cXML user lockouts, see Lockout settings for cXML (embedded
HTTP) users on page 439.
When Interchange sends a message via HTTP, it acts in the role of the HTTP client. The endpoint
Interchange is connecting to is the HTTP server.
HTTP error codes are reported in Interchange log files. When you see an HTTP code in a log file,
Interchange merely is echoing the code returned by an HTTP server, firewall, proxy server or load
balancer.
The response code for a successfully sent message is 200 (meaning “OK”). When a 503 code is
returned, this may be due to action by Interchange system throttle. A 503 code indicates service
temporarily is unavailable. The throttle attempts to monitor the message load by looking at available
memory and the depth of internal queues. When a loaded condition is detected, consumption of
new work is halted. This means two things: exchange points stop polling and embedded servers
return a 503 code.
For a complete list of HTTP codes, go to http://www.ietf.org/rfc/rfc2616.txt and see section 10 of
the document.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log. If received via HTTP, a 413 response also is sent and the connection is
closed. A 413 message is Request Entity Too Large.
The maximum size must be expressed in bytes. Do not use commas. For instance, a kilobyte is
1024 bytes, a megabyte is 1048576 bytes, a gigabyte is 1073741824 bytes.
The smallest maximum allowed is 1000 bytes. On the opposite extreme, you can enter the
largest number the field can accommodate.
This control is available only for transports used for picking up messages from integration or
receiving messages from partners.
If you use DMZ nodes, we recommend against selecting this. If host name verification is
enabled, messages may fail because the client is connecting to the DMZ node and not to
Interchange server. This is not applicable to integration exchanges.
l This server requires a user name and password – If selected, type a user name and
password to connect to the server.
l Retries – This is the number of times Interchange will retry connecting to the partner’s
transport if the initial attempt to connect and send the message failed. The following are
common reasons for triggering retries.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
In the last case, the 200 OK response also includes the receipt if synchronous receipts are
requested. Otherwise, it is a simple 200 OK response with no payload. And if an asynchronous
receipt is requested, the partner connects later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Connect timeout (seconds) – Time in seconds Interchange waits for a connection to the
delivery exchange before the attempt times out. Although the default value is 30 seconds, this
may be longer than the interval allowed by your operating system (OS). For example, Windows
XP by default allows a maximum timeout of 20 seconds. The actual connect timeout interval is
the lesser of the OS timeout and the value set in Interchange.
l Read timeout (seconds) – Time in seconds Interchange waits to read data from the delivery
exchange before terminating the connection.
l Response timeout (seconds) – The limit in seconds that Interchange waits for the delivery
exchange to respond to a request before terminating the connection.
If the business protocol is AS2, the response timeout value is dynamically computed by
Interchange before the file is sent from the HTTP client partner to the receiving HTTP server. This
value is directly related to the file size; a larger file size results in a larger response timeout value.
This dynamic computation allows the receiving HTTP server more time to process a larger file.
Before selecting this option, make sure the server supports 102 responses. If you turn on 102
processing and the server does not support it, the server will return a 417 message (the server
could not meet the expectation given in the Expect header) and the connection may fail. If the
receiving partner uses the embedded HTTP server in Interchange 5.5.1 or later, 102 responses
are supported. This also is supported if your partner uses Jetty 6 or later.
l Receiver is Axway Gateway – This field appears only when an HTTP or HTTPS transport under
the secure file message protocol has been added to a partner profile.
Selecting this option enables Interchange to send messages successfully to Axway Gateway via
secure file HTTP.
Upon receiving a secure file HTTP message from Interchange, Axway Gateway expects to find
the payload’s file name in the HTTP POST request URL. Normally, Interchange does not include
this. But when the option is selected, Interchange appends ?filename=name to the URL,
where name is the production file name.
l Override SSL and TLS cipher suites – Select this option and then use the Add and
Remove buttons to specify the cipher suites supported for the embedded server. If not selected,
all cipher suites are supported by default.
Keeping the default cipher list is less secure than specifying a restricted set of cipher suites.
The cipher suites that are displayed in the "Available" column depend on your runtime
environment (JRE version, IACK or FIPS enablement, Secure Relay configuration, ....).
The default order in the "Available" column is the preferred order of use. Once ciphers are moved
to the Selected column, you can arrange the order. Interchange uses the ciphers in the order
listed.
A cipher suite is a collection of security algorithms used in making connections via Secure
Sockets Layer or Transport Layer Security. For example, an SSL or TLS protocol requires signing
messages using a message digest algorithm. But the choice of algorithm is determined by the
particular cipher suite being used for the connection. Typically, you can select an MD5 or SHA
digest algorithm.
Of the many algorithms for encrypting data and computing the message authentication code,
there are varying levels of security. Some provide the highest levels of security, but require a
large amount of computation for encryption and decryption. Others are less secure, but provide
rapid encryption and decryption. The length of the key used for encryption affects the level of
security. The longer the key, the more secure the data.
The option for overriding cipher suites lets you select the level of security that suits your needs
and enables communicating with others who might have different security requirements. For
example, when an SSL connection is established, the client and server exchange information
about the cipher suites they have in common. Then they communicate using the common
cipher suite that offers the highest level of security. If they do not have a cipher suite in
common, secure communication is not possible.
In versions of Interchange earlier than Interchange 5.9, cipher suites configuration was handled
by a file named sslciphersuites.xml. As data in that file is saved in the database, the
custom cipher suites configuration is retained upon upgrading and is displayed in the Selected
list under the option in the user interface. The sslciphersuites.xml file is no longer used.
The maintenance pages display the transport fields that can be changed, while the delivery
exchange wizard has only the most commonly used. The following are the fields on the settings and
advanced tabs.
Advanced tab
l Maximum concurrent connections – The number of total open connections Interchange can
make to a partner. If you are operating in a cluster environment, this is the total number across
the entire cluster, no matter how many JVM nodes are running. For example, if the value is 100
connections and there are 150 messages to send, Interchange opens only 100 connections to
that partner. The remaining 50 messages are queued until connections become available. The
default value is suitable in almost all cases. However, if a partner says your Interchange is
overrunning his receiving system, decrease the value. (This advice does not apply to OFTP X.25
or X.25 over ISDN, as the default maximum value is 1 for those transports.) If sending messages
to Transfer CFT via PeSIT (PeSIT), the value in this field must be less than the CFTTCP setting in
Transfer CFT. This setting applies only to transports that send messages to partners or deliver
messages to integration.
l Retries – This is the number of times Interchange will retry connecting to the partner’s
transport if the initial attempt to connect and send the message failed. The following are
common reasons for triggering retries.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if
synchronous receipts were requested. Otherwise, it will be a simple 200 OK response
with no payload. And if an asynchronous receipt was requested, the partner will
connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between
retries increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30
minutes, 60 minutes. The interval plateaus at 60 minutes. This means if the retry value
is greater than 5, the fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second
retry in 10 minutes. The third retry attempt is made 15 minutes later. If the third retry
attempt fails, the message is given a failed status. So after four attempts (the first
attempt plus 3 retries), the message fails. You can search for and manually resubmit
failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes
some seconds, which varies by computer. So retries actually occur after the connection
attempt time plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to
retrying to send related to transport issues. It does not apply to successfully sent
messages for which receipts have not been received as expected. Another control,
resends, determines how many times the system will resend a message when a receipt is
not received from the partner. For information about resends, see reliable messaging in
the collaboration settings chapter.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log. If received via HTTP, a 413 response also is sent and the connection is
closed. A 413 message is Request Entity Too Large.
The maximum size must be expressed in bytes. Do not use commas. For instance, a kilobyte is
1024 bytes, a megabyte is 1048576 bytes, a gigabyte is 1073741824 bytes.
The smallest maximum allowed is 1000 bytes. On the opposite extreme, you can enter the
largest number the field can accommodate.
This control is available only for transports used for picking up messages from the back end or
receiving messages from partners.
l Maximum files per polling interval – The highest number of messages the system can
retrieve each time it polls.
l Polling interval (seconds) – The interval in seconds Interchange waits before polling for
messages to retrieve.
l Specify preferred nodes – If there are one or more nodes for Interchange, you can select one
or more as the preferred nodes for consuming messages. If the preferred nodes are running,
these are used to process messages. If the preferred nodes are stopped, work is distributed
among the remaining running available nodes. Selecting preferred nodes lets you manage work
distribution among nodes.
This option is available for application and trading pickup exchanges that poll for messages.
In general, this setting should not be used. Usually it is best to let Interchange automatically
determine which node should be responsible for initiating the polling of which exchange point.
This setting is useful if you have a cluster that spans geographical locations and each location
has its own local transport servers. In this situation, you would use this setting to ensure the
exchange points associated with the transport servers are assigned to nodes in the vicinity of the
transport servers.
If you want a Java class for a provider other than Oracle AQ, you need the help of a
professional services consultant. Contact Axway technical support for information.
o Parameters – There are four parameters required for the Java class for Oracle AQ. These
parameters must be in the following order:
o Host. The name of the computer running Oracle AQ.
o Database name. The name of the database that contains the message queue.
o Port. The port Oracle AQ uses to listen for messages.
o Driver type. The type of JDBC driver for connecting to the provider. For Oracle AQ, the
valid values are thin and oci8.
l Send payload via file system(delivery only)– Select this check box to have payloads sent by
a file system. You can specify the size of payloads to send and the path for payload files. The
receiver uses the path to retrieve the files.
engine is overrunning his receiving system, decrease the value. (This advice does not apply to
OFTP X.25 or X.25 over ISDN, as the default maximum value is 1 for those transports.) If
sending messages to Transfer CFT via PeSIT, the value in this field must be less than the CFTTCP
setting in Transfer CFT. This setting applies only to transports that send messages to partners or
deliver messages to integration.
l Retries – This is the number of times Interchange will retry connecting to the partner’s
transport if the initial attempt to connect and send the message failed. The following are
common reasons for triggering retries.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it. Retries occur
according to an algorithm that starts at 5 minutes. The interval between retries increases with
each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60 minutes. The
interval plateaus at 60 minutes. This means if the retry value is greater than 5, the fifth and each
subsequent retry occurs at 60 minute intervals. For example, if retries is 3, the system will try
connecting again in 5 minutes if the initial connection attempt fails. If this retry attempt also
fails, the system attempts a second retry in 10 minutes. The third retry attempt is made 15
minutes later. If the third retry attempt fails, the message is given a failed status. So after four
attempts (the first attempt plus 3 retries), the message fails. You can search for and manually
resubmit failed messages in Message Tracker. Retries do not occur precisely at these intervals
because each connection attempt takes some seconds, which varies by computer. So retries
actually occur after the connection attempt time plus the interval. This control applies only to
retrying to send messages, not receiving. It applies only to retrying to send related to transport
issues. It does not apply to successfully sent messages for which receipts have not been received
as expected. Another control, resends, determines how many times the system will resend a
message when a receipt is not received from the partner. For information about resends, see
reliable messaging in the collaboration settings chapter.
l Message Type – Specifies the JMS message class. This field applies only to JMS when used for
receiving messages from partners or integration delivery.
o BytesMessage. A BytesMessage object is used to send a message containing a stream of
uninterrupted bytes. It inherits from the Message interface and adds a bytes message body.
o TextMessage. A TextMessage object is used to send a message containing a
java.lang.String. It inherits from the Message interface and adds a text message body.
l Use transacted queue – Select this option if the provider is Oracle AQ. Otherwise, do not
select it.
To address tab
See From address and To address tabs on page 204.
Schedule tab
See Schedule tab on page 208.
Advanced tab
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners. Backup files are stored in \<install
directory>\common\data\backup, unless you specify otherwise.
l Restrict maximum file size for this transport – Optionally specify the maximum size of
files that this transport can handle. If Interchange receives a file larger than the maximum, the
file is rejected and a message is written to the events log.
Schedule tab
See Schedule tab on page 208.
Advanced tab
l Maximum concurrent connections – The number of total open connections Interchange
server can make to a partner. If you are operating in a cluster environment, this is the total
number across the entire cluster, no matter how many JVM nodes are running. For example, if
the value is 100 connections and there are 150 messages to send, Interchange opens only 100
connections to that partner. The remaining 50 messages are queued until connections become
available.
The default value is suitable in almost all cases. However, if a partner says your Interchange is
overrunning his receiving system, decrease the value. (This advice does not apply to OFTP X.25
or X.25 over ISDN, as the default maximum value is 1 for those transports.)
l Retries – The number of times Interchange retries connecting to the partner’s transport if the
initial attempt to connect and send the message failed. The following are common reasons for
triggering retries.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Connect timeout (seconds) – Interval, in seconds, Interchange waits for a connection to the
delivery exchange before the attempt times out. Although the default value is 30 seconds, this
may be longer than the interval allowed by your operating system (OS). For example, Windows
XP by default allows a maximum timeout of 20 seconds. The actual connect timeout interval is
the lesser of the OS timeout and the value set in Interchange.
l Read timeout (seconds) – Time in seconds Interchange waits to read data from the delivery
exchange before terminating the connection.
l Start block character – The decimal byte value to use for the start block character. Start and
stop block characters enclose the message data that is sent or received in through MLLP
messages. At runtime Interchange converts this decimal value to hexadecimal. Default = 11
(hexadecimal B). The default value is the customary MLLP value. You must use the same values
for the client and server sides of the MLLP exchange.
l End block character – The decimal byte value to use for the end block character. Start and
stop block characters enclose the message data that is sent or received in through MLLP
messages. At runtime Interchange converts this decimal value to hexadecimal. Default = 28
(hexadecimal 1C). The default value is the customary MLLP value. You must use the same values
for the client and server sides of the MLLP exchange.
l Acknowledgement expected from the target MLLP server – Select this option to keep
the connection with the MLLP server open while waiting for acknowledgement.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners. Backup files are stored in \<install
directory>\common\data\backup, unless you specify otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands.
l Characters set (delivery only) – The character set used by the queue manager. This number
should match the number used by the queue manager. The default is 819.
l Message segmentation – Select this option to enable message segmentation on this
transport. Then complete the related sub-fields:
Use application segmentation when queue manager segmentation does not suffice because
messages are too large to be handled by the application in a single buffer. Or, when data
conversion must be performed by sender channels and the format is such that the putting
application must specify the segment boundaries to make possible the conversion of individual
segments.
o MQSeries segmentation – Select this option to segment messages into chunks that
together equal the maximum message length value of the queue as set by the queue
administrator.
o Application segmentation – Select this option to segment messages into chunks equal to
the value you specify in the Segmentation size field. Each segment must be equal to or
less than the maximum message length value of the queue
Use application segmentation if:
o Messages are too large to be handled by the application in a single buffer,
o Data conversion must be performed by sender channels and the format is such that the
putting application must specify the segment boundaries to make possible the conversion of
individual segments.
SSL_RSA_EXPORT1024_WITH_DES_CBC_ DES_SHA_EXPORT1024
SHA
SSL_RSA_EXPORT1024_WITH_RC4_56_SHA RC4_56_SHA_EXPORT1024
SSL_RSA_EXPORT_WITH_RC4_40_MD5 RC4_MD5_EXPORT
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 RC2_MD5_EXPORT
SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA FIPS_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA
SSL_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA
SSL_RSA_WITH_DES_CBC_SHA DES_SHA_EXPORT
SSL_RSA_WITH_NULL_MD5 NULL_MD5
SSL_RSA_WITH_NULL_SHA NULL_SHA
SSL_RSA_WITH_RC4_128_MD5 RC4_MD5_US
SSL_RSA_WITH_RC4_128_SHA RC4_SHA_US
l Message persistence – Applicable only for outbound messages. Select a message persistence
mode:
o Non-persisted – No persistence. Messages may be lost.
o Persisted – Messages survive failures or restarts. This overrides the persistence configured
for the queue.
o As defined by the queue – Messages are persisted according to the queue configuration.
This setting is applicable in clustered environments when more than one Interchange node is
configured.
l Specify preferred nodes – In a multi-node cluster installation of Interchange, you can select
one or more nodes as the preferred nodes for consuming messages. If the preferred nodes are
running, these are used to process messages. If the preferred nodes are stopped, work is
distributed among the remaining running available nodes. Selecting preferred nodes lets you
manage work distribution among nodes.
This option is available for application and trading pickups that poll for messages.
In general, this setting should not be used. Usually it is best to let Interchange automatically
determine which node should be responsible for initiating the polling of which exchange point.
This setting is useful if you have a cluster that spans geographical locations and each location
has its own local transport servers. In this situation, you would use this setting to ensure the
exchange points associated with the transport servers are assigned to nodes in the vicinity of the
transport servers.
Note: There can be only one Interchange per (clustered) host. In this case you can p ick which
trading engine (that is, which host) performs the work.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5,
the fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails,
the message is given a failed status. So after four attempts (the first attempt plus 3 retries),
the message fails. You can search for and manually resubmit failed messages in Message
Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt
time plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to
retrying to send related to transport issues. It does not apply to successfully sent messages
for which receipts have not been received as expected. Another control, resends, determines
how many times the system will resend a message when a receipt is not received from the
partner. For information about resends, see reliable messaging in the collaboration settings
chapter.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners. Backing up files.
This is required for the system to perform fail-over operations such as attempting to send
messages again (retries) in case of a transport connection failure. Without backups, a message
in process cannot be recovered if the server or a processing node stops or restarts. Backups are
needed to resubmit messages to back-end applications or resend messages to partners. Backup
files are stored in \<install directory>\common\data\backup, unless you specify
otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for both application and trading deliveries.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners.
Backup files are stored in \<install directory>\common\data\backup, unless you
specify otherwise.
l Restrict maximum file size for this transport – Select this option to specify the maximum
size of files a the exchange can handle.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log.
o Maximum file size – Enter the maximum file size in bytes. Do not use commas.
This chapter provides information for completing fields in the maintenance pages.
For related information, see the followingchapters:
l Manage users of embedded SFTP on page 358
l Lockout settings for SFTP (embedded) users on page 458
l "*" may be substituted for zero or more characters
l "?" may be substituted for any one of the 36 characters, "A" through "Z" and "0" through "9
Examples of accounts using wildcards:
l *@domain.com
l *@*.*
When Interchange parses the user account name, it ranks specific characters over wildcard
characters. For example, "partner1@domain1" is selected over "partner?@domain1".
Example – We define the following addresses on an email trading pickup:
l Partner1 = partner1@myPartner.com
l Partner2 = @myPartner.com
l Partner3 = *@*
When receiving a message from partner1@myPartner.com, Interchange identifies the sending
partner as Partner1.
the same email address resolves to PartnerB.
In this case, the trading pickup that consumes the message determines the partner with whom the
user account is associated, based on the accounts specified in its Accounts tab.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Connect timeout (seconds) – Time in seconds Interchange waits for a connection to the
delivery exchange before the attempt times out. Although the default value is 30 seconds, this
may be longer than the interval allowed by your operating system (OS). For example, Windows
XP by default allows a maximum timeout of 20 seconds. The actual connect timeout interval is
the lesser of the OS timeout and the value set in Interchange.
l Read timeout (seconds) – Time in seconds Interchange waits to read data from the delivery
exchange before terminating the connection.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from back-end applications or from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners.
Backup files are stored in \<install directory>\common\data\backup, unless you
specify otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for community integration delivery exchanges and partner
trading delivery exchanges.
l Zone – If you use DMZ nodes and want to send or receive messages via a specific DMZ zone,
select the zone. This field is available only when the user license supports Secure Relay and a
DMZ zone has been added. For details, see Secure Relay DMZ nodes on page 474.
This chapter provides information for completing fields in the maintenance pages.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Connect timeout (seconds) – Interval in seconds Interchange waits for a connection to the
delivery exchange before the attempt times out. Although the default value is 30 seconds, this
may be longer than the interval allowed by your operating system (OS). For example, Windows
XP by default allows a maximum timeout of 20 seconds. The actual connect timeout interval is
the lesser of the OS timeout and the value set in Interchange.
l Read timeout (seconds) – Time in seconds Interchange waits to read data from the delivery
exchange before terminating the connection.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners.
Backup files are stored in \<install directory>\common\data\backup, unless you
specify otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for community integration delivery exchanges and partner
trading delivery exchanges.
l Zone – If you use DMZ nodes and want to send or receive messages via a specific DMZ zone,
select the zone. This field is available only when the user license supports Secure Relay and a
DMZ zone has been added. For details, see Secure Relay DMZ nodes on page 474.
l "*" may be substituted for zero or more characters
l "?" may be substituted for any one of the 36 characters, "A" through "Z" and "0" through "9
Examples of accounts using wildcards:
l *@domain.com
l *@*.*
When Interchange parses the user account name, it ranks specific characters over wildcard
characters. For example, "partner1@domain1" is selected over "partner?@domain1".
Example – We define the following addresses on an email trading pickup:
l Partner1 = partner1@myPartner.com
l Partner2 = @myPartner.com
l Partner3 = *@*
When receiving a message from partner1@myPartner.com, Interchange identifies the sending
partner as Partner1.
In this case, the trading pickup that consumes the message determines the partner with whom the
user account is associated, based on the accounts specified in its Accounts tab.
When a partner uses a mail client application to send a trading document as an attachment to an
email message, Interchange actually receives two or more documents. These can include the
MIME header, the text of the email message and the document attachment. Interchange tracks
and processes the incidental MIME body parts just as it does any document. Although such
processing does no harm, it can cause confusion.
Selecting this check box causes the incidental MIME body parts to be ignored while preserving
the important document attachments.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners.
Backup files are stored in \<install directory>\common\data\backup, unless you
specify otherwise.
l Restrict maximum file size for this transport – Optionally lets you specify the maximum
size of files a transport can handle.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log. If received via HTTP, a 413 response also is sent and the connection is
closed. A 413 message is Request Entity Too Large.
The maximum size must be expressed in bytes. Do not use commas. For instance, a kilobyte is
1024 bytes, a megabyte is 1048576 bytes, a gigabyte is 1073741824 bytes.
The smallest maximum allowed is 1000 bytes. On the opposite extreme, you can enter the
largest number the field can accommodate.
This control is available only for transports used for picking up messages from integration or
receiving messages from partners.
l Maximum files per polling interval – The highest number of messages the system can
retrieve each time it polls.
l Polling interval (seconds) – The interval in seconds Interchange waits before polling for
messages to retrieve.
This setting is applicable in clustered environments when more than one Interchange node is
configured.
l Specify preferred nodes – If there are one or more nodes for Interchange, you can select one
or more as the preferred nodes for consuming messages. If the preferred nodes are running,
these are used to process messages. If the preferred nodes are stopped, work is distributed
among the remaining running available nodes. Selecting preferred nodes lets you manage work
distribution among nodes.
This option is available for integration pickup and trading delivery exchanges that poll for
messages.
In general, this setting should not be used. Usually it is best to let Interchange automatically
determine which node should be responsible for initiating the polling of which exchange point.
This setting is useful if you have a cluster that spans geographical locations and each location
has its own local transport servers. In this situation, you would use this setting to ensure the
exchange points associated with the transport servers are assigned to nodes in the vicinity of the
transport servers.
The maintenance pages display the transport fields that can be changed, while the delivery wizard
has only the most commonly used. The following are the fields on the settings and advanced tabs.
The URL Interchange uses to post messages to a back-end system.
The number of total open connections Interchange can make to a partner. If you are
operating in a cluster environment, this is the total number across the entire cluster, no
matter how many JVM nodes are running. For example, if the value is 100 connections and
there are 150 messages to send, Interchange opens only 100 connections to that partner.
The remaining 50 messages are queued until connections become available. The default
value is suitable in almost all cases. However, if a partner says your Interchange is
overrunning his receiving system, decrease the value. (This advice does not apply to OFTP
X.25 or X.25 over ISDN, as the default maximum value is 1 for those transports.) If sending
messages to Transfer CFT via PeSIT (PeSIT), the value in this field must be less than the
CFTTCP setting in Transfer CFT. This setting applies only to transports that send messages
to partners or deliver messages to integration.
Retries
The number of times Interchange will retry connecting to the partner’s transport if the
initial attempt to connect and send the message failed.
The following are common reasons for triggering retries.
l The connection attempt failed immediately for a reason such as host not
found.
l The host was found, but the connection process took longer than the
connect timeout interval specified on the Advanced tab.
l The connection was successful, but the partner’s HTTP server took longer
than the response timeout interval to return a 200 OK response indicating the
message was successfully received. A 200 OK response is a transport
response, separate from a message protocol response such as an AS2 receipt.
Note that in the last case, the 200 OK response also includes the receipt if synchronous
receipts were requested. Otherwise, it is a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between
retries increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30
minutes, 60 minutes. The interval plateaus at 60 minutes. This means if the retry value is
greater than 5, the fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3 , the system tries connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry
in 10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt
fails, the message is given a failed status. So after 4 attempts (the first attempt plus 3
retries), the message fails. You can search for and manually resubmit failed messages in
Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes
some seconds, which varies by computer. So retries actually occur after the connection
attempt time plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to
retrying to send related to transport issues. It does not apply to successfully sent messages
for which receipts have not been received as expected. Another control, resends,
determines how many times the system resends a message when a receipt is not received
from the partner. For information about resends, see Default collaboration fields on page
911 in the collaboration settings chapter.
Send the payload through this transport. This option is only for integration delivery.
After the transport has been set up, you have the option of sending the message payload
(the default) or only the URL that points to the payload. If you choose to send only the
URL, the back-end system uses the URL to retrieve the payload from the Interchange
backup directory. Because the payload is retrieved from the backup directory, there are two
conditions that must be met if you choose to send the payload URL only:
l Backing up files must be enabled for the Web Services API client integration
delivery exchange.
l If you have set up a schedule on Interchange for deleting messages, the back-
end must retrieve the payload before the next scheduled purge occurs or the
payload is lost. For information about setting up schedules for deleting
messages see Data storage, backups, and purging on page 849.
Time long in seconds Interchange waits for the delivery exchange to respond to a request
before terminating the connection.
If you are sending files larger than 2 gigabytes, select this to turn on chunking. A chunked
message is a large message broken into smaller pieces for sending to a partner over the
Internet or to back-end integration.
Although primarily for handling large messages, chunking can be enabled for small
messages, too. However, if your partners use a trading engine other than Interchange or
use an external or staged HTTP server, they may be unable to accept messages larger than
2 gigabytes, even if the messages are chunked.
Also, in rare cases a partner’s HTTP server may be unable to handle chunked messages,
regardless of message size. You should perform tests to determine whether a partner’s
server can handle chunked messages. If not, the partner must use Interchange with the
embedded server to receive large chunked messages successfully.
If you enable chunking because of large messages, you also probably need to request that
receipts be sent over an asynchronous connection. See the chapter on collaboration
settings for details.
Attempt restarts
Select this option to turn on checkpoint-restarts. A checkpoint is information saved to disk
that is used as a recovery point in the event of a transport failure. The restart program uses
the last saved checkpoint and starts again, ensuring no loss of data.
Checkpoint files are saved on the server under the <install
directory>/common/data/http/restartable, which is normally common to all
nodes in the cluster. If a transfer is interrupted and the load balancer directs the restart
request to a different node, the restart file is accessible to the new node even though it did
not process the original request.
To reduce unnecessary overhead when processing small files, checkpoint files are only
created for messages that are at least 100 KB in size.
If a restart is attempted for a message whose checkpoint file on the server is more than four
hours old, the checkpoint file is discarded and the entire message is retransmitted.
The restart logic is used only during transport retries, such as might occur when a transfer
is interrupted due to network problems. If you resubmit a message in Message Tracker, no
attempt is made to perform a checkpoint-restart.
This feature only works if your partner uses B2Bi, Interchange or Activator and its
embedded HTTP server. Do not select this option if a partner uses an external or staged
HTTP server or uses a trading engine other than B2Bi, Interchange or Activator.
Select this option to ensure that the connection between the client and server does not
become idle and fail while message processing is in progress. For example, this makes sure
the connection remains active when the client is sending a multi-gigabyte message. Or, to
prevent a firewall from disconnecting an idle connection before the server receives the
entire message and returns a 200 OK response. Most often this setting is useful when the
client requests a synchronous receipt, but also could be recommended in some cases for
an asynchronous receipt.
Selecting this option directs Interchange to add the following to the header of an
outbound message: Expect: 102- processing. This is an HTTP response code that indicates
processing is in progress. If the receiving server supports 102 responses, the header
triggers the server to send 102 responses to the client repeatedly until the server has
completely processed the inbound message. Before selecting this option, make sure the
server supports 102 responses. If you turn on 102 processing and the server does not
support it, the server will return a 417 message (the server could not meet the expectation
given in the Expect header) and the connection may fail. If the receiving partner uses the
embedded HTTP server in Interchange or Activator 5.5.1 or later, 102 responses are
supported. This also is supported if your partner uses Jetty 6 or later.
Select this option if you want the system to back up copies of the messages it consumes.
Backing up files is strongly recommended. This is required for the system to perform fail-
over operations such as attempting to send messages again (retries) in case of a transport
connection failure. Without backups, a message in process cannot be recovered if the
server or a processing node stops or restarts. Backups also are needed if you want the
ability to resubmit messages to back-end applications or resend messages to partners.
Backup files are stored in \<install directory>\common\data\backup, unless you
specify otherwise.
Post-processing script
The full path to an executable file that contains post-processing commands.
Click the link to display the settings for the global Web Services API server.
Indicates whether the system backs up copies of the messages it consumes. Backing up
files. This is required for the system to perform fail-over operations such as attempting to
send messages again (retries) in case of a transport connection failure. Without backups, a
message in process cannot be recovered if the server or a processing node stops or restarts.
Backups are needed to resubmit messages to back-end applications or resend messages to
partners. Backup files are stored in \<install directory>\common\data\backup,
unless you specify otherwise.
Optionally lets you specify the maximum size of files a transport can handle.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log. If received via HTTP, a 413 response also is sent and the
connection is closed. A 413 message is Request Entity Too Large. The maximum size must
be expressed in bytes. Do not use commas. For instance, a kilobyte is 1024 bytes, a
megabyte is 1048576 bytes, a gigabyte is 1073741824 bytes. The smallest maximum
allowed is 1000 bytes. On the opposite extreme, you can enter the largest number the field
can accommodate. This control is available only for transports used for picking up
messages from the back end or receiving messages from partners
Prerequisite
Add a Web Services trading pickup on page 326
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration to open the Communities page.
2. Select the community that represents your organization as a Web Service participant.
3. On the community map of the summary page, click the Trading pickup icon to open the
Trading pickups page.
4. From the list of exchanges, click the Web Services p ickup to open the Change this pickup page.
Use the tab and field descriptions on this page to view and change your pickup settings.
5. When you are done with your modifications, click Save changes.
Fields
General fields
Enable this pickup
Select or de-select this option to enable or disable the pickup.
Name
Name of the pickup.
Select this option if you have multiple exchanges and you want this pickup to be selected
for the community d efault pickup.
The local port and path the embedded HTTP server uses. A server starts on each computer
in the cluster using this information. If you have only one computer, only one server is
started.
The fully qualified host name or IP address, port number and path where partners must
connect to send messages.
When you export your community profile as a partner profile, the URL becomes part of
your exported partner profile. The host, port and path may be different than the values in
the local URL. If your network uses a load balancer or firewall, contact your network
administrator for the correct value.
If your local URL is HTTP and you use an SSL terminator in the DMZ for inbound
connections, the partner must send messages to the terminator and not to Interchange.
You must specify the HTTPS URL of the terminator as the URL used by partners. Make sure
the terminator can forward messages to Interchange. Your partner also must import and
trust the public-key certificate from your SSL terminator. Interchange cannot include this
certificate when the community profile is exported as a partner profile.
Accounts tab
When partners are required to connect to the server with user names and passwords, you can view
and create user accounts on the Accounts tab.
To create a user account click Add and then complete the fields: User name, Password,
and Transport user password policy – From the drop-down list, select a password
policy to apply to this account.
Partner
Users accounts owned by specific partners can also be added to the exchange. To enable
server access for the account of a specific partner, click Add, then select a partner from the
list of available partners, and select an account from the list of accounts that belong to that
partner.
Description
Description of the custom class function.
Class name
Name of the custom class.
Parameter
Parameter required for the custom class.
Schedule tab
By default, exchange points are active continuously. You can add active schedules by day of the
week and time of day. For example, if you select Monday 0:00 - 23:59, the exchange is on all day
every Monday. If you select Monday 8:30 - 11:30, the exchange is on from 8:30 to 11:30 a.m. and
off all other times on Mondays.
Advanced tab
WSDL
WSDL 1.1 file
Use this field and the following field to implement a custom Web Service for use by
Interchange. To support ?wsdl and/or ?wsdl2 queries, the custom Web Service must
create the appropriate wsdl or wsdl2 file or both. Use one or both of these fields to point to
the custom file or files.
See WSDL file field description above.
Header
Generate new WSDL
Use this command to open the WSDL configuration wizard and define a new service.
Select this option if you want to SOAP headers to be carried as metadata attributes with the
message.
If you selected the previous option (Parse SOAP headers into message metadata),
enter an XPath expression to resolve the header.
Click Add to display the Local XPath field and then enter an XPath expression.
Enter any legal XPath expression. Xpath wildcard syntax is permitted. If the
expression resolves to more than one node, only the value of the first matching
node is included in the metadata value.
To define multiple headers, click Add multiple times and enter an expression in
each field.
Body / Attachments
Process SOAP body
Select this option to process the contents of the SOAP body.
Process attachments
Select this option to process the attachments of the SOAP message.
Processing
Receive handler config file
The file to use when unpacking a message. The default file is axis2.xml. The file is in
located in <install directory>\conf.
Select this option to have the back-end application generate synchronous responses.
If this option is not selected, the synchronous response is generated within Interchange.
By default, this option is not selected.
If this option is selected, Interchange keeps open the inbound HTTP connection so a
synchronous response payload can be built by the back-end system. Once Interchange
receives it, the response is packaged and sent over the open HTTP connection. If selected,
you must create an MMD for Interchange to pick up from the back end. Make sure to
remove any custom service from the repository that builds responses within Interchange.
This is the mostly likely option if you do not have the optional Software Development Kit.
By default, this option is not selected.
You also must create an Axis service that builds the response. The service must use the
message receiver, defined within Interchange, that receives the original message and helps
in handling and sending the response built by your service. If Interchange cannot find a
service, the connection is closed with an HTTP 204 response. The optional Software
Development Kit contains information about how to build such a service.
Default = 60 seconds. Enter a time limit for Interchange to wait for missing messages of a
sequence before taking the appropriate action. This feature avoids the blocking of
processing when a sequenced message is not available.
Select this option to have the system back up copies of the messages it receives from
partners. Backing up files is strongly recommended. This is required for the system to
perform fail-over operations such as attempting to send messages again (retries) in case of
a transport connection failure. Without backups, a message in process cannot be
recovered if the server or a processing node stops or restarts. Backups also are needed if
you want the ability to resend messages to partners. Backup files are stored in <install
directory>\common\data\backup, unless you specify otherwise.
Select this option to specify the maximum size of files the transport can handle. If
Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log. If received via HTTP, a 413 response also is sent and the
connection is closed. A 413 message is Request Entity Too Large. The maximum size must
be expressed in bytes. Do not use commas. For instance, a kilobyte is 1024 bytes, a
megabyte is 1048576 bytes, a gigabyte is 1073741824 bytes. The smallest maximum
allowed is 1000 bytes. On the opposite extreme, you can enter the largest number the field
can accommodate.
Prerequisites
Add a Web Services trading partner delivery. For details, see Add a Web Services trading delivery on
page 322.
Procedure
1. In the user interface, from the Partners menu select Manage partners to open the Partners
page.
2. Select the partner that represents your Web Service partner.
3. On the partner map of the partner summary page, click the Partner delivery icon.
4. On the Partner deliveries page, from the list of deliveries, click a Web Services type delivery
to open the Change this delivery page.
Use the tab and field descriptions on this page to view and change your delivery settings.
5. When you are done with your modifications click Save changes.
Fields
General fields
Enable this delivery
Select or deselect this option to enable or disable the transport.
Name
Name of the delivery.
When you have multiple deliveries, one of the deliveries must be designated as the default
delivery.
The partner's web service URL.
Select this option if the partner's server requires a user name and password. Then complete
the fields: User name, Password, Confirm password.
Proxy tab
Use a proxy to access this server
Select this option if you must pass through a proxy to reach the delivery server. For partner
exchanges, the proxy is located between Interchange and the partner HTTP server.
Host
The URL of the proxy host.
Port
The port where the proxy host listens for connections.
Select this option if the proxy server requires a user name and password. Then complete
the fields: User name, Password, Confirm password.
Description
Description of the custom class function.
Class name
Name of the custom class.
Parameter
Parameter required for the custom class.
Schedule tab
By default, exchange points are active continuously. You can add active schedules by day of the
week and time of day. For example, if you select Monday 0:00 - 23:59, the exchange is on all day
every Monday. If you select Monday 8:30 - 11:30, the exchange is on from 8:30 to 11:30 a.m. and
off all other times on Mondays.
Advanced tab
Maximum concurrent connections
The number of total open connections Interchange can make to a partner. If you are
operating in a cluster environment, this is the total number across the entire cluster, no
matter how many JVM nodes are running. For example, if the value is 100 connections and
there are 150 messages to send, Interchange opens only 100 connections to that partner.
The remaining 50 messages are queued until connections become available. The default
value (100) is suitable in most cases. However, if a partner says your Interchange is
overrunning his receiving system, decrease the value.
Retries
The number of times Interchange will retry connecting to the partner’s transport if the
initial attempt to connect and send the message failed.
Connect timeout
Time in seconds Interchange waits for a connection to the delivery before the attempt
times out. Although the default value is 30 seconds, this may be longer than the interval
allowed by your operating system (OS). For example, Windows XP by default allows a
maximum timeout of 20 seconds. The actual connect timeout interval is the lesser of the
OS timeout and the value set in Interchange.
Read timeout
The maximum number of seconds the server waits when reading data from a partner.
Response timeout
The interval in seconds partners are allotted to return search results requested by your local
server.
Select this option if you are sending files larger than 2 gigabytes. You may also enable
chunking for small messages. However, if your partners use a trading engine other than
B2Bi, Interchange or Activator or use an external or staged HTTP server, they may be
unable to accept messages larger than 2 gigabytes, even if the messages are chunked. In
rare cases a partner’s HTTP server may be unable to handle chunked messages, regardless
of message size. Perform tests to determine whether a partner’s server can handle chunked
messages.
Attempt restarts
Select this option to turn on checkpoint-restarts. A checkpoint is information saved to disk
that is used as a recovery point in the event of a transport failure. The restart program uses
the last saved checkpoint and starts again, ensuring no loss of data.
Checkpoint files are saved on the server under the <install
directory>/common/data/http/restartable, which is normally common to all
nodes in the cluster. If a transfer is interrupted and the load balancer directs the restart
request to a different node, the restart file is accessible to the new node even though it did
not process the original request.
To reduce unnecessary overhead when processing small files, checkpoint files are only
created for messages that are at least 100 KB in size.
If a restart is attempted for a message whose checkpoint file on the server is more than four
hours old, the checkpoint file is discarded and the entire message is retransmitted.
The restart logic is used only during transport retries, such as might occur when a transfer
is interrupted due to network problems. If you resubmit a message in Message Tracker, no
attempt is made to perform a checkpoint-restart.
This feature only works if your partner uses Interchange or Activator and its embedded
HTTP server. Do not select this option if a partner uses an external or staged HTTP server or
uses a trading engine other than Interchange or Activator.
Select this option to ensure that the connection between the client and server does not
become idle and fail while message processing is in progress. For example, this makes sure
the connection remains active when the client is sending a multi-gigabyte message. Or, to
prevent a firewall from disconnecting an idle connection before the server receives the
entire message and returns a 200 OK response. Most often this setting is useful when the
client requests a synchronous receipt, but also could be recommended in some cases for
an asynchronous receipt.
Selecting this option directs Interchange to add the following to the header of an
outbound message: Expect: 102- processing. This is an HTTP response code that indicates
processing is in progress. If the receiving server supports 102 responses, the header
triggers the server to send 102 responses to the client repeatedly until the server has
completely processed the inbound message. Before selecting this option, make sure the
server supports 102 responses. If you turn on 102 processing and the server does not
support it, the server will return a 417 message (the server could not meet the expectation
given in the Expect header) and the connection may fail. If the receiving partner uses the
embedded HTTP server in Interchange or Activator 5.5.1 or later, 102 responses are
supported. This also is supported if your partner uses Jetty 6 or later.
Select this option if you want the system to back up copies of the messages it receives from
partners. Backing up files is strongly recommended. This is required for the system to
perform fail-over operations such as attempting to send messages again (retries) in case of
a transport connection failure. Without backups, a message in process cannot be
recovered if the server or a processing node stops or restarts. Backups also are needed if
you want the ability to resubmit messages to back-end applications or resend messages to
partners. Backup files are stored in \<install directory>\common\data\backup,
unless you specify otherwise.
Post-processing script
The full path to an executable file that contains post-processing commands.
The maintenance pages display the transport fields that can be changed, while the pickup or
delivery exchange wizard has only the most commonly used. The following are the fields on the
settings and advanced tabs.
o The Allow option allows the user to write files to any subdirectory under the root path.
o The Do not allow option allows writing files to a subdirectory under the root path only
when a message attribute is set up for each subdirectory level.
See Message attributes tab on page 206.
Click Modify to change the user or directory path.
l WebDAV user – The name of the user.
l Directory path – The directory associated with the user. A specific combination of user and
directory can be associated with only one exchange.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log. If received via HTTP, a 413 response also is sent and the connection is
closed. A 413 message is Request Entity Too Large. The maximum size must be
expressed in bytes. Do not use commas. For instance, a kilobyte is 1024 bytes, a megabyte is
1048576 bytes, a gigabyte is 1073741824 bytes. The smallest maximum allowed is 1000 bytes.
On the opposite extreme, you can enter the largest number the field can accommodate. This
control is available only for transports used for picking up messages from integration or
receiving messages from partners.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt
time plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to
retrying to send related to transport issues. It does not apply to successfully sent messages
for which receipts have not been received as expected. Another control, resends, determines
how many times the system will resend a message when a receipt is not received from the
partner. For information about resends, see reliable messaging in the collaboration settings
chapter.
l Delete file after it is downloaded – Select this if you want the embedded server to delete
files after they have been downloaded from it.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners. Backing up files.
This is required for the system to perform fail-over operations such as attempting to send
messages again (retries) in case of a transport connection failure. Without backups, a message
in process cannot be recovered if the server or a processing node stops or restarts. Backups are
needed to resubmit messages to back-end applications or resend messages to partners. Backup
files are stored in \<install directory>\common\data\backup, unless you specify
otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for community application and partner delivery exchanges.
l Zone – If you use DMZ nodes and want to send or receive messages via a specific DMZ zone,
select the zone. This field is available only when the user license supports Secure Relay and a
DMZ zone has been added. For details, see Secure Relay DMZ nodes on page 474.
Routing IDs
A routing ID is a unique identifier that Interchange uses as the "to" and "from" address for
e-commerce messages exchanged over the Internet.
There is a relationship between routing IDs (used for partner identification at the transport level)
and messaging IDs (used for partner identification at the message level). Typically, routing IDs are
automatically generated based on the messaging IDs created for the partner. Users can add routing
IDs manually as well.
When you add a community or partner, the user interface prompts you to enter one routing ID. After
the initial community or partner setup, you can add as many additional routing IDs as you want. To
add or delete a routing ID, click Routing IDs on the navigation graphic at the top of the
community or partner summary page and follow the prompts.
Although a community or partner can have many routing IDs, the user interface designates one per
community or partner as the default. Default routing IDs are used by default for message protocol
headers when packaging messages. For example, when packaging an AS2 message, the default
routing IDs are used for as2-to and as2-from attributes in headers, regardless of the routing IDs
parsed from the payload. In the user interface you can change the default routing IDs for a
community or partner. To override default routing IDs, you work with user-defined collaboration
settings.
A routing ID can be in any format or length (up to 255 characters), including standard EDI or
custom formats that include special characters or spaces.
Add a routing ID
Modify a routing ID
After you create a Community or Partner, you can:
l Add additional routing IDs
l Delete routing IDs
l Party ID type – For ebXML, AS4 or WebServices traders only, enter an ebXML party ID
type only if the routing ID you enter is not a URI. For cXML traders only, enter the matching
cXML credential domain type. For more information, see Routing ID for ebXML on page
411.
5. Click Add.
Delete a routing ID
1. On the Routing IDs page of a partner or community, in the list of routing IDs, click Delete for
any routing ID that you want to remove.
2. Click OK to confirm and complete the delete action.
l The routing ID (party ID) must be a Universal Resource Identifier (RFC 1630). For example,
urn:myroutingid. When the routing ID is a URI, an ebXML party ID type is not necessary.
l When the routing ID (party ID) is not a URI, enter an ebXML party ID type in addition to a unique
routing ID. The ebXML party ID type can be any string (a URI, a DUNS number or something
else) and the routing ID can be any unique string. For example: urn:mystring 123456789.
The type value must match the PartyId /@type attribute value for the PartyInfo entry in the
CPA for the community.
If you trade with the same partner using both ebXML and any other message protocol, the
community needs separate routing IDs for each protocol. The ebXML routing ID must not be the
default. The default must be the routing ID used for the other message protocol.
Attributes
Attributes are metadata used by Interchange for processing and as search criteria for UI displays.
An attribute comprises an attribute name and one or more values that are associated with the name.
You can use attributes in two situations:
Optional – You add a specific value in the object wizard when creating the object or you can
update the object at a later time. If you don't want to use that attribute, it is ignored if you don't add
a value.
Mandatory – You must enter a value for processing. If a Partner or Community Summary does not
contain a particular mandatory value, a message or icon is displayed advising that the required
attribute values are not yet complete for the P artner or Community.
Objects with available attribute templates are:
l Communities, Partners
l WebTrader documents
Within the various attribute wizards, you may add, modify, delete, or export, depending on the
status of the attributes.
Metadata uses
The following are uses for metadata in Interchange:
Pickups
You can configure pickups to attach metadata to messages Interchange consumes from back-end
applications or trading partners.
You can set rules that direct inbound messages to specified deliveries, based on rules.
When using JMS as an application transport, metadata parameters are appended to the
BytesMessage or TextMessage. See JMS transport configuration on page 294.
ebXML trading
To comply with ebXML standards, Interchange supports message metadata elements with message
payloads. The metadata elements are information about message payloads, such as the identity of
the CPA to use for message processing.
Metadata also can be exchanged between Interchange and a back-end system via application
transports.
See ebXML message metadata on page 548.
AS4 trading
To comply with AS4 standards, Interchange supports message metadata elements with message
payloads.
See AS4 metadata on page 503.
RosettaNet trading
To comply with RosettaNet standards, Interchange supports message metadata elements with
message payloads.
See RNIF metadata elements on page 707.
Message handling
Message handling refers to optional processing of inbound or outbound messages based on
metadata attributes and actions. Interchange lets you set up conditions to:
l Copy messages to parties other than the sender or receiver
l Re-route messages from one partner to another
l Prohibit re-routing of messages
l Reject messages
l Perform custom processing using your own Java class
See Message handler on page 892.
Post processing
You can perform post-processing commands on each inbound message immediately after
Interchange has received, processed and written it to an application delivery. You also can execute
post-processing commands after sending messages to partners. Interchange by default passes seven
items of message metadata to the post process. See Post-processing configuration on page 905.
APIs
Metadata are used by all APIs, including Java inline processing and pluggable transports. Using APIs
requires obtaining an optional developer’s license.
Metadata definitions
The following are metadata elements and definitions.
This list does not include metadata elements for:
l AS4 (see AS4 metadata on page 503)
l ebXML (see ebXML message metadata on page 548)
l RosettaNet (see RNIF metadata elements on page 707)
l Record file management (see Metadata for record file management on page 418)
The following elements are listed in the correct format. When using metadata elements, make sure
to use the proper case.
l BusinessProtocol – Business protocol for the current packaging state. The value depends on a
message’s state. For example, "raw" represents an unpackaged state and "EDIINT AS1"
represents a packaged state for the AS1 protocol.
l BusinessProtocolVersion – The business protocol version for the current packaging state of
the message. The value depends on a message’s current state. The value indicates the version of
the ProtocolSender or ProtocolReceiver handling a message. The value does not necessarily
coincide to a specific packaging specification or RFC.
l ConnectionId – An internal unique identifier of the embedded HTTP server connection
through which to send a synchronous response after receiving a message from a partner.
l ConsumptionExchangePointId – Unique ID of the integration or delivery exchange point
where the message originated.
l ConsumptionFilename – The file name of a message picked up from an integration or delivery
transport. The value is null if the message is retrieved from an exchange point that does not
support naming.
l ConsumptionUrl – The URL of the consuming exchange point. If null, the URL cannot be
consumed from the exchange point or the message was not consumed.
l ContentMimeType – The MIME type of the message payload. The following are commonly
used types.
MIME type Description
application/EDI-consent Tradacoms messages
application/EDIFACT EDIFACT messages
application/EDI-X12 X12 messages
application/octet-stream Binary messages
application/xml XML messages
For information about other MIME types see:
http://www.mhonarc.org/~ehood/MIME/MIME.html
l CoreId – Used internally by Interchange.
l Direction – The direction of a message relative to the sending party.
l DocumentClass – The document class of the message payload (for example, X12, XML).
l DocumentType – For EDI documents this is the business document type, such as 894 (invoice)
or 850 (purchase order). For XML documents, the document type has to be parsed from the
document. For ebXML, this is the message type (for example, StatusRequest, StatusResponse,
Pong, Ping).
l DocumentTypeId – The document type definition ID that describes a payload's document
type.
l DoNotReroute – Mark a message so that it is not rerouted.
l DoNotSubmit2Tx – Mark a message to be ignored by the Submit2Tx action.
l EdiControlId – For an EDI message payload, the control ID.
l ediint.DocumentType – For an EDI document, the document type (for example, 850). This is
similar to the DocumentType element, but this one is only for EDI documents.
l ediint.DocumentVersion – The version or release information from the EDI message payload.
This applies to X12 and EDIFACT documents.
l ediint.IsMDN – If a message is a receipt, the value is true. Otherwise, it is false.
l ExpirationTime – Message expiration date. This is the date the message can be purged. Also
see MinimumExpirationTime.
l ExternalCycleIdTOName – Provides an additional link back to the alternate Axway Sentinel
tracked object that may be associated with this parent cycle ID.
l ExternalCycleIdValue – Links CoreId and RefToMessageCoreId for integration with Axway
Sentinel.
l FormPostAppName – Name of the web application that received a form post containing a
document. This is not meant to be the actual J2EE web application name, but a name the user
recognizes.
l FormPostUrl – URL that received a form post containing a document.
l IntegrationId – Integration ID of a message. This can be used, via inline processing or JMS
metadata, to attach a customer-specific ID to a message.
l IsChildPayload – This element has been deprecated.
l IsDuplicate – True if the message is detected to be a duplicate through the business protocol
message ID. False otherwise.
l IsParentPayload – This element has been deprecated.
l JmsFileReference – A JMS property that provides the path to the payload.
l MaxRetries – Used internally by Interchange.
l MinimumExpirationTime – Minimum message expiration date. The earliest date the message
can be purged. The expiration date can be set to a date after this.
l MQCorrelationID – CorrelationId field of a MQSeries message read from or written to the
MQSeries Queue. Value is base 64 encoded.
l MQExpiry – The Expiry field of an MQSeries message read from or written to an MQSeries
queue.
l MQMessageID – The MessageId field of MQSeries message read from or written to the
MQSeries queue. Value is base 64 encoded.
l MQPriority – The Priority field of an MQSeries message read from or written to an MQSeries
queue.
l MQReplyToQueueName – The ReplyToQueueName field of an MQSeries message read from
or written to an MQSeries queue.
l NextRetryNum – Used internally by Interchange.
l NextRetryTime – Used internally by Interchange.
l PackagedBusinessProtocol – Message protocol for the packaged (request or receipt) state.
l PackagedBusinessProtocolVersion – Message protocol version of the unpackaged (request
or receipt) state. The value indicates the version of the ProtocolReceiver handling a message.
The value does not necessarily coincide with a specific packaging specification or RFC.
l packagingLocation – For outbound email messages to an SMTP server, this metadata element
enables you to specify where to place a payload in a packaged email message. This metadata
element can be specified on an individual payload, or included in an MMD for multi-payload
messages.
To use set this attribute for single payloads in the user interface, in the Message Handler click
Add an attribute, enter the attribute name packagingLocation, and set the required value:
o packagingLocation=Body – specifies that the payload is included as a email message
body.
o packagingLocation=Attachment (default) – specifies the payload is included as an
email attachment.
l PeerAnnotation – A comment about a message processed by the peer network. For example,
"Receipt forwarded to peers."
l PeerMessageIsPing – A value of true indicates an inbound or outbound ping associated with
the peer network.
l pesit.callerId – The caller or sender ID (nspart).
l pesit.serverId – The server or receiver ID (nrpart).
l pesit.originalSenderId – The original sender ID.
l pesit.finalDestinationId – The final destination ID.
l pesit.filename – The PeSIT file name or logical name (IDF).
l pesit.filelabel – The PeSIT file label or physical file name (nfname).
l pesit.serviceParam – The PeSIT free-text field sent during the file creation process (param).
l pesit.fileEncoding – Designates how the file is transferred, text or binary (ftype).
l pesit.recordLength – The PeSIT file record length (frecl).
l pesit.priority – The PeSIT transfer priority (pri). This has no effect on Interchange’s behavior.
l PreferredBusinessProtocol – Preferred message protocol for message processing.
l ProductionFilename – The file name of a message sent to integration or a partner. Typically,
this is the same as ConsumptionFilename.
l ProductionUrl – The URL where a message was sent to integration or a partner via any
transport. The value is not set (null) if the message has not been produced.
l ReceiverPartyId – Used internally by Interchange.
l ReceiverPartyIds – Comma-separated list of internal unique IDs of the receiving parties.
l ReceiverPartyName – The name of the receiver.
l ReceiverRejectedReason – Used internally by Interchange.
l ReceiverRoutingId – The routing ID of the message receiver.
l RefToMessageCoreId – A value for this element is provided when one message refers to
another. Typically this would be in web services and ebXML when a business response is sent
that refers to a previous message. The value is the core ID of the related message.
l Rejected – If a message is in the rejected state, the value is true. Otherwise, it is false.
l RejectedReason – For a message in the rejected state, the reason for the rejection.
l SenderPartyId – Used internally by Interchange.
l SenderPartyIds – Comma-separated list of internal unique IDs of the sending parties.
l SenderPartyName – The name of the sender.
l SenderRoutingId – The routing ID of the message sender.
l SentinelCycleIdTOName – Provides an additional link back to the alternate Axway Sentinel
tracked object that may be associated with this parent cycle ID.
l SentinelCycleIdHashedValue – The hashed value of SentinelCycleIdValue.
l SentinelCycleIdValue – Links CoreId and RefToMessageCoreId for integration with Axway
Sentinel.
l SkipMessageValidation – True indicates message validation is not performed for a peer
message (for example, pings).
l StagedHttpClientId – The staged HTTP servlet client ID.
l StagedHttpServletId – The staged HTTP servlet ID.
l SubjectHeader – Enables setting the subject line of outbound messages sent via generic e-mail
(SMTP), AS1, AS2, AS3 and Secure File message protocols. For outbound messages, the subject
line value can be set by adding SubjectHeader as a message attribute on integration pickup
exchanges or adding it to outbound message metadata documents. Interchange sets the
attribute and value on inbound e-mail and EDIINT messages.
l SynchronousResponseRestId – Used internally by Interchange.
l TransportResponseCode – Used internally by Interchange.
l UnpackagedBusinessProtocol – Message protocol for the unpackaged (request or receipt)
state.
l UnpackagedBusinessProtocolVersion – Message protocol version of the unpackaged
(request or receipt) state. The value indicates the version of the ProtocolReceiver handling a
message. The value does not necessarily coincide with a specific packaging specification or RFC.
l UserAnnotation – A comment attached by a user.
l WSIntegrationConnectionId – Unique identifier of the web services integration HTTP server
connection. For internal use only.
You can set these attributes:
l In the Message Handler. See Configure record transformation in message handler on page 902.
l In a Message Attributes Template. See Message attributes templates on page 424.
character set the record is encoded. This enables Interchange to process documents correctly.
l Virtual attributes (for example, VirtualFileRecordFormat) are used by file-transfer
protocols, such as OFTP and PeSIT, to describe the files being transferred. Virtual attributes are
conveyed by a protocol during the exchange to the partner. This tells the partner what is being
transferred and how to process the file once received.
Sent messages
For sending messages, file attributes are defined in a message attributes template or in the message
handler:
l If LocalFileRecordFormat is not given, OCTET_STREAM is assumed (the default value).
l If LocalFileRecordFormat is FIXED_TEXT or FIXED_BINARY, LocalRecordLength is
required.
l If LocalFileRecordFormat is VARIABLE_TEXT or VARIABLE_BINARY, LocalRecordLength
is optional.
l However, if not given, an internal default is assumed. In the case of OFTP, 2048 for VARIABLE_
TEXT, 32000 for VARIABLE_BINARY.
l If LocalFileCharSet is not given, ASCII is assumed.
l LocalFilePaddingCode is required only in case of record transcoding.
l Virtual file attributes are optional. If virtual file attributes are not given, the corresponding local
file attributes are assumed.
l If VirtualFileRecordFormat is different than LocalFileRecordFormat or the
LocalFileChatSet is different than VirtualFileChatset, the file undergoes transcoding
before being sent.
Consumed messages
For consumed messages, virtual file attributes are provided by the protocol elements (metadata), as
conveyed during the protocol exchange. Local file attributes are assumed to be the same as virtual
file attributes received. However, you can use the record transformation options of the message
handler to override these attributes and set file transcoding as needed. Additionally, for PeSIT and
OFTP message consumption, virtual and local file attribute values can be overridden by applying a
message attributes template on the PeSIT or OFTP pickup.
Transcoding
Transcoding applies only to files that have a record structure and not to OCTET_STREAM
(unstructured) files. Transcoding occurs when LocalFileRecordFormat is different from
VirtualFileRecordFormat or LcoalFileCharSet is different from VirtualFileCharset.
File records can be transformed from FIX_ to VARIABLE_ format or vice-versa.
For outbound messages, transformation takes local file attributes as source attributes and virtual file
attributes as target attributes. For inbound message, it is the other way round.
When transformed from FIX_ to VARIABLE_, trailing padding characters (as defined in
LocalFilePaddingChar or VirtualFilePaddingChar) are stripped off to make the record in variable
format.
When transformed from VARIABLE_ to FIX_ , padding characters (as defined in
LocalFilePaddingChar or VirtualFilePaddingChar) are added to make the record in fixed
format. The process assumes fixed format record length is at least as long as the maximum variable
format record.
Attributes
Attribute Value Description
l Free
mandatory value, a message displays on the Partner's Summary page: Fill in the required
attributes. It is located under the heading: You must complete the following tasks
before this partner can trade.
l Make available for searching — Select this check box so the search pages include an
attribute name and value filter that you can use to search for a particular object with a
particular Attribute or a particular Attribute value.
l Make available for message processing – Select this option if the attribute is available
as a criteria for conditional message processing. For example, if a map lacks a partner’s fax
number, you can add an attribute named FaxNumber and add the fax number as the
value. Then the number can be added to the document created by the map.
l This attribute is a list of values — Select this option if you want to attach a selectable
value or list of values to this attribute. If you select this option, you must also complete the
following two fields:
o Selection style — Select whether to display a single selectable value or a list of
selectable values.
o Possible values — Enter the value or values that are available to select. Put each
separate value on a new line. A counter displays the number of characters you have
used out of the possible 4000 available characters for this field.
7. Click Add.
Add attributes
Adding attributes makes them available for use in message attributes templates and in the message
handler area of the user interface.
The message attributes page is for managing attributes (metadata). The page displays all declared
attributes and allows adding others, either user-defined or from internal dictionaries.
l To add an attribute from the pool, click the triangle icon next to the Name field near the
bottom of the page to display a partial list of attributes. To display more attributes, click the
ellipsis at the bottom of the drop-down and scroll down. You also can type a letter to
display attributes that begin with that letter.
l To add a custom attribute, select the Name field and type the name of the attribute.
To add a custom attribute, follow these guidelines: Make attribute names a single text
string. For names that use multiple words, do not use spaces between the words. Use camel
case for names that include two or more words (for example, AttributeName). Avoid
using non-alphanumeric characters in attribute names (for example, commas, periods,
asterisks, ampersands and so on).
It is a good practice to include a prefix for the custom attribute name to make it easy to
identify as a user-defined attribute. For example, you could use a company name as the
prefix (CompanyAttributeName).
4. Click Add.
Delete attributes
To delete an attribute, click the Delete button located in the row of the attribute you want to
delete.
Message attributes templates can be used for:
l Message handler actions
l Consumption delivery exchanges (integration pickup and receiving from partners)
Templates are global objects. They do not belong to a community, a partner or a WebTrader. After a
template is changed, the changes affect all objects associated with it. For example, a template
named foo is associated with a pickup exchange and a message handler action. The template
contains four attribute-value pairs, but has been changed to contain five pairs. The updated
template affects the delivery exchange and the message handler action.
Note If you are licensed for Peer Networking, note that message attributes templates are not
cloned.
You also could assign a value based on a sequence (a counter) or a date by using the key word
sequence and a date format. For example:
A1 = $sequence$$sequence$$sequence$
A2 = $dd-mm-yyyy$
This leads to A1 = 123 and A2 = today’s date in ddmmyyyy format.
6. Click Add message attribute to template.
7. Repeat the steps to add as many attribute-value pairs as you want for the template.
8. To delete an attribute-value pair, click Delete next to that pair.
9. Click Save to save the template and its attribute-value pairs.
Use the following procedure to import an exported message attributes template xml file. If multiple
templates were exported to a single xml file, all message attributes templates exported to the file are
imported.
Caution Deleting a template breaks all existing references to it and may require you to update
consumption exchanges, messaging processing actions, and external metadata sources.
Likewise, a partner who uses Interchange 4.2.x or later can export a community or company
configuration and public key certificate to a file and give it to you to import as a partner profile. For
partners who use other interoperable software, collect the trading data you need and then create a
partner profile in the user interface. Partner data form on page 151 provides a way for documenting
the data needed to create a partner configuration.
If you are upgrading from Interchange 4.2.x, you can export company profiles as such and import
them as community profiles in this version of Interchange.
The following topics explain how to export and import community and partner configurations.
These topics address how to export or import configurations one at a time, which is the typical way
of handling profiles. The topics are:
l Export a community as a partner profile on page 427
l Export a partner profile on page 428
l Import a partner profile on page 428
l Automatic profile imports on page 429
There is also a way to have Interchange import configurations on its own without user intervention.
That method is explained in Automatic profile imports on page 429. Lastly, Create profiles outside
the application on page 430 includes links to schemas for creating configurations externally.
Interchange exports a community configuration as a partner configuration XML file. A community
configuration cannot be exported as a community profile, except when backing up a community
(see Back up a community and its partners on page 853).
If the community has more than one delivery exchange for receiving messages from partners, the
default exchange is the preferred transport. The default exchange is the one that displays at the top
of the list on the community profile's delivery exchange page. Before exporting the profile, you can
change the default or disable a transport to refine the options available to your partner.
Distribute the profile to partners by a secure means. If you send the profile file to partners as an
email attachment, you should compress it with WinZip or similar software to ensure file integrity.
You can only export a community profile in a form usable as a partner profile. You cannot export the
profile by itself as a usable community profile. You can, however, export an entire community (the
community profile and all associated partner profiles). For more information, see Back up a
community on page 854.
One reason to export a partner profile is to create a back-up copy for later importing, if needed.
Partner profiles can be exported with a tool as well as through the user interface. The tool allows
exporting partner profiles singly or in a batch.
An exported partner profile contains information such as the partner's name and routing ID, plus the
configured transports for sending messages to the partner. If there is more than one exchange, the
order of the transports is preserved, as the exchange at the top of the list is the default.
Other preferences included in exported partner profile files include:
l All advanced settings that display on transport maintenance pages in the user interface, such as
maximum concurrent connections, retries, connection, response, and read time-outs.
l HTTP chunking and attempted restarts for HTTP.
l Transport-friendly names.
l The transport's setting for backing up files.
l The paths and file names of post-processing scripts, but not the scripts themselves.
l Information for inline processing Java classes is included in exported profiles, but not the Java
classes themselves.
l If the profile has an FTP transport with an alternate command set file, that preference is included
in the exported file, but not the command set file itself.
If you are expecting the imported profile to include the partner's certificate and public key, check
whether the partner's certificate is trusted. Go to the partner summary page and click Certificates in
the navigation graphic at the top of the page. Click the certificate name and then click the Trusts
tab. Check the details of third-party certificates imported with profiles to make sure trusted roots are
present.
After importing a profile, go to the partner summary page for the imported partner and check
whether any tasks are required to complete the profile configuration. See Post-import tasks.
If a partner uses a trading engine other than Interchange 4.2.x or later, you cannot import a usable
partner profile, but must manually create the profile. Partner data form on page 151 provides a way
for documenting the data needed to manually create a profile.
There are two business cases for automatic profile imports. The first is to migrate community and
partner profiles from an earlier to later version of Interchange.
The second case is to help manage profiles by providing a hands-free method to grow the number
of partners in a community.
Profiles written to <install directory>\profiles\autoImport are imported by Interchange
when the server is running. Once imported, the system moves the profile files from
profiles\autoImport to the appropriate profiles\backup subdirectory, either community or
partner. The system makes all imported partner profiles members of all communities. The system
creates pickup and delivery integration exchanges for an imported community.
If Interchange is unable to import a profile file in the autoImport directory, the system moves the file
to \profiles\autoImport\rejected.
The system also has some profile staging directories, as shown here:
The system does not write to these directories, except during installation when a user is upgrading
from version 4.2.x. The directories are a place to hold profile files before a user moves them to the
autoImport directory. The software installer, for instance, writes profile files to the staged directories
if the user during installation choose to have profiles exported from an earlier version of
Interchange.
Events for profile imports and rejections are written to the control node events log (<hostname>_
cn_events.log) in the logs directory. The events are:
l Administration.Configuration.Party.CommunityImported
l Administration.Configuration.Party.PartnerImported
l Administration.Configuration.Party.ImportFailed
Note Avoid using any special characters in server paths.
Concepts
l Types of embedded servers on page 432
l Usage summary of embedded servers on page 434
l Manage embedded servers on page 435
l HTTP (embedded) business cases on page 468
l HTTP (embedded) fields on page 444
l FTP (embedded) fields on page 446
l SFTP (embedded) server fields on page 453
l SMTP (embedded) configuration on page 459
l OFTP (embedded) fields on page 461
l OFTP X.25 over ISDN (embedded) fields on page 463
l MLLP (embedded) fields on page 608
l PeSIT (embedded) fields on page 465
l HTTP (embedded) business cases on page 468
l Subsystem settings for X.400 server on page 752
l Manage embedded servers on page 435
l Secure Relay DMZ nodes on page 474
l Enable port forwarding for an exchange on page 484
l Configure outbound connection proxy on page 488
l Global and community-specific servers on page 432
l FTP and SFTP servers on page 432
l MLLP servers on page 433
l ODETTE FTP servers on page 433
l PeSIT servers on page 433
l Servers for the user interface on page 434
l X.400servers on page 434
Interchange matches inbound messages to delivery exchanges for specific communities by the
HTTP path or the email address, so there is no need to create a servers for each community. The
exception is HTTPS. Since the server certificate and list of trusted client authentication certificates
are associated with particular communities, you must create a community-specific HTTP server to
handle incoming HTTPS messages for each community.
You also can use an embedded HTTP server for integration pickup by creating a pickup exchange
based on the Web Services API server. For security reasons, this server uses a different port than any
of the HTTP servers used for trading.
SSL is supported only for inbound trading with HTTP. It is not supported by the Web Services API
server (application side), and it is not supported by the SMTP server (partner trading side).
In general, you should not allow outside connections to the Web Services API embedded server.
secure context (FTPS), but not both.
The FTP and SFTP servers also handle secure connections differently than the embedded HTTP
server. Since the embedded HTTP server determines whether a connection must be secure based on
the port, you must define separate servers on different ports if you want to allow both clear and
secure connections. Embedded FTP servers are not tied to a particular community; its trust of client
authentication certificates is tied to the server itself and not to a particular community. When you
view the settings for an embedded FTP server, there is a Trusted root certificates tab on the server
settings page. This is in contrast with embedded HTTP servers, whose trusted SSL certificates are
specified on the Certificates dialog for the associated communities.
SFTP has a slightly different model still. SFTP uses public keys instead of certificates to trust clients,
and the public keys are tied to each SFTP user. Thus, you do not see a tab related to trusts when you
view the settings for an embedded SFTP server. Nor do you find trusted public keys mixed in with a
community’s trusted SSL certificates. Instead, you must go to the community or partner that owns
the SFTP user and view the settings for that SFTP user. This is a security feature of the SFTP protocol
that ties log-in accounts to specific trusted keys. A key is not be accepted if it is used by the wrong
user account for authentication.
With FTP and SFTP servers, all servers on the trading side share the same pool of user accounts. User
accounts for trading are kept separate from user accounts for back-end application exchanges. This
is further enforced when you create an FTP or SFTP exchange for an application delivery or pickup;
you must define a new server instance on a separate port.
As with the Web Services API server, you should generally not allow outside connections to the
SFTP embedded server.
MLLP servers
MLLP embedded servers have a one-to-one relationship with delivery exchanges. For this reason,
there is no global embedded MLLP server. Each time you add an MLLP exchange, you also define a
new server instance on a new port. This means that MLLP servers cannot be shared by multiple
communities.
PeSIT servers
PeSIT embedded servers move messages via PeSIT. See PeSIT on page 651 for more information.
These embedded servers, created by Interchange, are named CnHttpServer and CnHttpsServer.
For more information see Configure UI connection on page 56.
X.400servers
X.400servers support trading messages via the X.420 and X.435 electronic mail standards. For more
information see X.400 on page 737.
* Messages can be exchanged in both directions on the same connection once Interchange
connects.
X.400 servers are not included in the preceding table. See X.400 on page 737 for information about
those servers.
There are various places in the user interface where you can open the maintenance page for an
embedded server. But the embedded servers page is the primary page for managing these servers.
On this page you can view a list of all embedded servers and open the maintenance page of any
server by clicking its name.
Not only can you use this page to manage embedded servers, but your DMZ or network
administrator may find it a useful guide for configuring ports for load balancers and firewalls. Text
on the page describes how an administrator should use the displayed information.
The following illustration is the standard view of the embedded servers page.
The following illustration is the view of the embedded servers page when DMZ nodes functionality is
enabled in the software license. The DMZ nodes version of the page has additional columns (DMZ
hosts, DMZ ports, Zone). See Secure Relay DMZ nodes on page 474 for details about this optional
functionality.
To open an embedded server maintenance page, open the maintenance page of a pickup exchange
that references the embedded server. On a community summary page, click Application pickup or
Trading pickup in the navigation graphic at the top of the page. Click an embedded transport to
open the maintenance page for the pickup. On the settings tab click the link for opening the
maintenance page of the embedded server.
Note If you have a Peer Network license, note that these settings are not clonable.
To change settings:
1. Select System management > Manage embedded servers. Or, click Trading
configuration on the toolbar.
2. On the Communities page, click the link near the bottom of the page named Manage all
embedded servers.
This server only is for HTTP. For HTTPS have a community add an embedded server (see HTTP
(embedded) fields on page 444).
The following are the configuration fields for the server.
Settings tab
Host – The fully qualified domain name of the computer on which the embedded server runs.
Interchange detects this setting; you cannot change it.
Port – The port on which the server listens for connection requests.
Advanced tab
l Minimum threads – The least number of threads Interchange must dedicate to the server.
l Maximum threads – The most threads Interchange can dedicate to the server.
l Read timeout (seconds) – The maximum number of seconds the server waits when reading
data from a partner.
The user is locked out for a specified number of minutes. The user must wait until the lockout
interval expires, unless an administrator unlocks the user before the interval ends.
To change settings:
Settings tab
l Host – The fully qualified domain name of the computer on which the embedded server runs.
Interchange detects this setting; you cannot change it.
l Port – The port on which the server listens for connection requests.
l Host used by partners – The fully qualified domain name or IP address that a community’s
partners must use to connect to this embedded server. Interchange supplies a value based on
the name of the host computer. It’s possible you may have to change it. Contact your firewall
administrator if you need help with this field.
l Port used by partners – The port number that a community’s partners must use to connect to
this embedded server. Contact your firewall administrator if you need help with this field.
In the simplest case there is one DMZ port with the same value as the corresponding embedded
server port in the protected network. If you add a machine to your cluster and return to the DMZ
ports tab, another DMZ port automatically is added in sequence. This happens because every
machine in the cluster that can host the embedded server must be assigned a unique
corresponding port in the DMZ.
Click the port field to display a list of ports already in use.
l Enable IP address checking in DMZ – Select this check box to have Interchange check
partners’ IP addresses against a whitelist of authorized IP addresses. Connections from unknown
IP addresses are not allowed.
l Match IP address against partner definition – When IP address checking is enabled,
select this check box to have the router agent check whether the partner is registered to the IP
address. If not selected, the agent only checks the user’s credentials. (This control is not
available to all types of servers.)
l Zone – If you want to receive messages through a Secure Relay DMZ zone, select a zone. This
drop-down field is available only if zones have been set up.
See Port forwarding details on page 486 for more information.
Advanced tab
l Backlog – The number of connections that the server puts “on hold” while it is busy. Once this
number is reached, connections are refused.
l Read timeout (seconds) –The maximum number of seconds the server waits when reading
data from a partner.
1. Log into the Interchange user interface as an administrator.
2. Manually enter the following URL in your browser: http://<localhost or
machinename>:6080/ui/core/SystemProperties#
The Systems Properties page is displayed.
3. At the bottom of the page click Show default system properties.
4. Find the default system property entry actionTree.clearContentTypeProtocolsList,
and click Add Property.
5. In the Value field, enter AS1.
6. Click Add.
To change settings:
The following are the configuration fields for the server.
Settings tab
l Host – The name of the computer on which the embedded server runs. Interchange detects this
setting; you cannot change it.
l Port – The port on which the server listens for connection requests.
Advanced tab
l Minimum threads – The least number of threads Interchange must dedicate to the server.
l Maximum threads – The most threads Interchange can dedicate to the server.
The UI embedded servers are displayed on the page for managing all embedded servers.
To change settings:
To change settings:
The following are the maintenance fields for an embedded HTTP or HTTPS server that has been
added by a community.
Settings tab
Server name – A name you give the transport server to distinguish it from other embedded servers.
This field gets its initial value when you type it in the delivery exchange wizard.
l Host – The fully qualified domain name of the computer on which the embedded server runs.
Interchange detects this setting; you cannot change it.
l Port – The port on which the server listens for connection requests.
The following display only for an HTTPS server.
Advanced tab
l Minimum threads – The least number of threads Interchange must dedicate to the server.
l Maximum threads – The most threads Interchange can dedicate to the server.
l Read timeout (seconds) – The maximum number of seconds the server waits when reading
data from a partner.
To change settings:
The following are the maintenance fields for an embedded FTP transport server that has been added
by a community.
Settings tab
l Server name – A name you give the transport server to distinguish it from other embedded
servers. This field gets its initial value when you type it in the delivery exchange wizard.
l Port – The port on which Interchange listens for connection requests.
l Add an SSL server certificate or SSL server certificate – For optional SSL, the server
requires an SSL certificate. If the server has a certificate, the name of the certificate is displayed.
If the server does not have an SSL certificate, you are prompted to provide one.
For FTP, once a certificate is added the server becomes FTPS using explicit SSL. Non-SSL
connections are not allowed. If the certificate is removed, the server becomes FTP once more.
Advanced tab
l Maximum concurrent connections – The number of total open connections Interchange
server can make to a partner. If you are operating in a cluster environment, this is the total
number across the entire cluster, no matter how many JVM nodes are running. For example, if
the value is 100 connections and there are 150 messages to send, Interchange opens only 100
connections to that partner. The remaining 50 messages are queued until connections become
available.
The default value is suitable in almost all cases. However, if a partner says your Interchange is
overrunning his receiving system, decrease the value. (This advice does not apply to OFTP X.25
or X.25 over ISDN, as the default maximum value is 1 for those transports.)
If sending messages to Transfer CFT via PeSIT, the value in this field must be less than the
CFTTCP setting in Transfer CFT.
This setting applies only to transports that send messages to partners or deliver messages to
integration.
l Read/idle timeout (seconds) – The maximum number of seconds the server waits when
reading data from a partner.
If you do not select this option, all cipher suites are supported by default. Keeping the default
cipher list is less secure than specifying a restricted set of cipher suites.
The cipher suites that are displayed in the "Available" column depend on your runtime
environment (JRE version, IACK or FIPS enablement, Secure Relay configuration, ....).
The default order in the "Available" column is the preferred order of use. Once ciphers are moved
to the Selected column, you can arrange the order. Interchange uses the ciphers in the order
listed.
A cipher suite is a collection of security algorithms used in making connections via Secure
Sockets Layer or Transport Layer Security. For example, an SSL or TLS protocol requires signing
messages using a message digest algorithm. But the choice of algorithm is determined by the
particular cipher suite being used for the connection. Typically, you can select an MD5 or SHA
digest algorithm.
Of the many algorithms for encrypting data and computing the message authentication code,
there are varying levels of security. Some provide the highest levels of security, but require a
large amount of computation for encryption and decryption. Others are less secure, but provide
rapid encryption and decryption. The length of the key used for encryption affects the level of
security. The longer the key, the more secure the data.
The option for overriding cipher suites lets you select the level of security that suits your needs
and enables communicating with others who might have different security requirements. For
example, when an SSL connection is established, the client and server exchange information
about the cipher suites they have in common. Then they communicate using the common
cipher suite that offers the highest level of security. If they do not have a cipher suite in
common, secure communication is not possible.
In versions of Interchange earlier than Interchange 5.9, cipher suites configuration was handled
by a file named sslciphersuites.xml. As data in that file is saved in the database, the
custom cipher suites configuration is retained upon upgrading and is displayed in the Selected
list under the option in the user interface. The sslciphersuites.xml file is no longer used.
Home directories are used by FTP and SFTP embedded servers to direct messages to a single
subdirectory for a transport user. For example, a community has three delivery exchanges for
receiving messages from partners. All exchanges use the same embedded server and the same user
to connect to the server. The user subdirectories for each exchange are different. The subdirectories
are:
Normally, when a remote partner connects to the server as user foo and sends messages via AS3, the
messages are written to the foo\AS3 subdirectory. Messages sent via secure file and no packaging
are similarly routed to the designated subdirectories for those exchanges.
However, if a home directory for the foo user is set as foo\home, all messages are re-routed to the
home directory. This occurs regardless whether a partner uses the AS3, secure file or no packaging
exchange to send messages to the community
If the advanced control is enabled on a delivery exchange to allow clients to add and remove
subdirectories, the home directory for the embedded server is honored. This means the embedded
server's settings take precedence over the settings for the exchange point, which is hosted on that
embedded server. In this case, messages are re-routed to the home directory even when the
transport user sends to the subdirectory the user created earlier.
If a user has an FTP or SFTP client and logs on to the embedded server directly – outside of a
messaging protocol – the client connects to the home directory rather than to the user subdirectory.
The user is locked out for a specified number of minutes. The user must wait until the lockout
interval expires, unless an administrator unlocks the user before the interval ends.
4. Edit the following fields.
l Maximum retries before a user is locked out – The number of times a user can try
unsuccessfully to log on before the user is locked out.
l Lock out length (in minutes) – The interval in minutes that a lockout is in effect.
l Active ports restriction – List the active ports to which users cannot have access. Specify
0 if there is no specific port restriction. Use comma-separated list to specify multiple port
restrictions. You can use closed or open ranges (examples: 9055, 9056, 9060-9070,
50000-)
5. Click Save changes when done.
1. In the navigation graphic at the top of a community summary page, click Application
delivery.
2. In the list of available application deliveries, click an FTP (embedded) transport to open its
maintenance page.
3. Select the Directories tab and check whether any users have been locked out.
4. Click Unlock to enable the user to try again to connect.
To change settings:
Settings tab
l Server name – A name you give the transport server to distinguish it from other embedded
servers. This field gets its initial value when you type it in the delivery exchange wizard.
l Port –The port on which Interchange listens for connection requests.
Select the authentication method:
l This server requires the SFTP client to authenticate using a password – Requires the
partner to use a password to connect to the embedded server. The password is the one assigned
to the SFTP user associated with the delivery that uses this server. If not selected, the partner
optionally can submit a password, but is not required to do so.
l This server requires the SFTP client to authenticate using a public/private key pair
– Requires the partner to use a private key to encrypt an authentication message and pass it to
the server to decrypt with the matching public key. This process enables the server to verify the
identity of the partner. If not selected, the partner optionally can submit an encrypted
authentication message, but is not required to do so.
l This server requires the SFTP client to authenticate using both a password and a
public/private key pair – Requires the partner to provide both of the above authentication
methods.
l This server allows the SFTP client to authenticate using either a password or a
public/private key pair – Requires the partner to provide either of the authentication
methods.
l External host or IP address – The fully qualified domain name or IP address that a
community’s partners must use to connect to this embedded server. Interchange supplies a
value based on the name of the host computer. In many cases you must change this to the
external name used by your network firewall or load balancer. Contact your network
administrator if you need help with this field.
l External port – The port number that a community’s partners must use to connect to this
embedded server. Contact your network administrator if you need help with this field.
Advanced tab
l Maximum concurrent connections – The number of total open connections Interchange
server can make to a partner. If you are operating in a cluster environment, this is the total
number across the entire cluster, no matter how many JVM nodes are running. For example, if
the value is 100 connections and there are 150 messages to send, Interchange opens only 100
connections to that partner. The remaining 50 messages are queued until connections become
available.
The default value is suitable in almost all cases. However, if a partner says your Interchange is
overrunning his receiving system, decrease the value. (This advice does not apply to OFTP X.25
or X.25 over ISDN, as the default maximum value is 1 for those transports.)
If sending messages to Transfer CFT via PeSIT, the value in this field must be less than the
CFTTCP setting in Transfer CFT.
This setting applies only to transports that send messages to partners or deliver messages to
integration.
l Maximum authentications – The number of failed authentication attempts the server allows
before disconnecting the user.
l Session timeout (seconds) – The number of seconds the server waits before disconnecting
an inactive logged-on user.
l Server’s current DSA public key – This is the designated DSA public key the embedded
server passes to the remote partner’s SFTP client. If the client trusts the key, the message
exchange can proceed.
Interchange keeps the corresponding private key in a file in <install
directory>\common\conf\keys. The private key is not displayed in the user interface.
The public key is passed to the partner’s external client when the client connects. The public key
assures the client that it is connecting to a trusted server. However, if a DSA key is not specified,
the server instead sends the current RSA public key to the client.
The current public key, whether RSA or DSA, is included in the community profile when it is
exported as a partner profile for the partner to import on its instance of Interchange. The current
key displays in the user interface for the delivery settings within the partner. However, if the
partner uses a client other than Interchange, the key is passed to the client when the client
connects to the server.
When the community is exported to a backup file, both the RSA and DSA keys are exported to
the file.
l Change the DSA SSH keys – Select this to change the current DSA public key for this
embedded server. Select one of the following options and click Save changes. If you change
the key after you have exported your community profile as a partner profile, export the profile
again and give the file to your partner to import to its instance of Interchange.
o Use default key – Select to use the default DSA public key. The length of this key is 1024.
The default public key is generated when the first SFTP delivery for receiving messages from
partners via an embedded server is added to a community. Unless otherwise specified, all SFTP
exchange points for all embedded SFTP servers use the same default key.
If you select another key option and later elect to go back to the default key, the same default
key that was first generated becomes the current key again.
o Do not use a key – Select this if you do not want to specify a DSA public key for this
embedded server. If you do, the current RSA public key is used instead. Either a DSA or an
RSA public key must be specified as a current key. Both the DSA and RSA public keys cannot
be disabled at the same time.
o Generate a key – Select this to have Interchange generate a new public-private key pair
and designate the public key as the current DSA public key for this embedded server. Select a
key length before clicking Save changes to generate the key.
The server is off line while the key is being generated, but restarts once the key has been
added.
It may take several minutes or more to generate a key longer than 1024.
o Import a private key – Select this and click Browse to import a private key you have
generated. You must use a tool such as PuTTY-Gen to generate the public-private key pair.
You cannot use Interchange to generate the key. Import only the private key. Interchange
generates the corresponding public key and makes it the current key for this embedded
server.
l Server’s current RSA public key – This is the designated RSA public key the embedded
server passes to the remote partner’s SFTP client. If the client trusts the key, the message
exchange can proceed. See Server’s current DSA public key – This is the designated DSA public
key the embedded server passes to the remote partner’s SFTP client. If the client trusts the key,
the message exchange can proceed. on page 455 for more information about how these keys
are used for SFTP.
l Change the RSA SSH keys – Select this to change the current RSA public key for this
embedded server. Select one of the following options and click Save changes. If you change
the key after you have exported your community profile as a partner profile, export the profile
again and give the file to your partner to import to its instance of Interchange.
o Use default key – Select to use the default RSA public key. The length of this key is 2048.
The default public key is generated when the first SFTP delivery for receiving messages from
partners via an embedded server is added to a community. Unless otherwise specified, all
SFTP exchange points for all embedded SFTP servers use the same default key.
If you select another key option and later elect to go back to the default key, the same
default key that was first generated becomes the current key again.
o Do not use a key – Select this if you do not want to specify an RSA public key. If you do,
the current DSA public key is used, which is the default behavior anyway. Either a DSA or an
RSA public key must be specified as a current key. Both the DSA and RSA public keys cannot
be disabled at the same time.
o Generate a key – Select this to have Interchange generate a new public-private key pair
and designate the public key as the current RSA public key. Select a key length before
clicking Save changes to generate the key. The server is off line while the key is being
generated, but restarts once the key has been added. It may take several minutes or more to
generate a key longer than 2048.
o Import a private key – Select this and click Browse to import a private key you have
generated. You must use a tool such as PuTTY-Gen to generate the public-private key pair.
You cannot use Interchange to generate the key. Import only the private key. Interchange
generates the corresponding public key and makes it the current key for this embedded
server.
Home directories are used by FTP and SFTP embedded servers to direct messages to a single
subdirectory for a transport user. For example, a community has three deliveries for receiving
messages from partners. All exchanges use the same embedded server and the same user to connect
to the server. The user subdirectories for each exchange are different. The subdirectories are:
Normally, when a remote partner connects to the server as user foo and sends messages via AS3, the
messages are written to the foo\AS3 subdirectory. Messages sent via secure file and no packaging
are similarly routed to the designated subdirectories for those exchanges.
However, if a home directory for the foo user is set as foo\home, all messages are re-routed to the
home directory. This occurs regardless whether a partner uses the AS3, secure file or no packaging
exchange to send messages to the community
If the advanced control is enabled on a delivery to allow clients to add and remove subdirectories,
the home directory for the embedded server is honored. This means the embedded server's settings
take precedence over the settings for the exchange point, which is hosted on that embedded server.
In such case, messages are re-routed to the home directory even when the transport user sends to
the subdirectory the user created earlier.
One other item of note: If a user has an FTP or SFTP client and logs on to the embedded server
directly — outside of a messaging protocol — the client connects to the home directory rather than
to the user subdirectory.
The user is locked out for a specified number of minutes. The user must wait until the lockout
interval expires, unless an administrator unlocks the user before the interval ends.
The following are the maintenance fields for an embedded SMTP server that has been added by a
community.
Settings tab
l Server name – A name you give the transport server to distinguish it from other embedded
servers. This field gets its initial value when you type it in the delivery exchange wizard.
l Host – The fully qualified domain name of the computer on which the embedded server runs.
Interchange detects this setting; you cannot change it.
l Port – The port on which the server listens for connection requests.
l Host used by partners – The fully qualified domain name or IP address that a community’s
partners must use to connect to this embedded server. Interchange supplies a value based on
the name of the host computer. It’s possible you may have to change it. Contact your firewall
administrator if you need help with this field.
l Port used by partners – The port number that a community’s partners must use to connect to
this embedded server. Contact your firewall administrator if you need help with this field.
Advanced tab
l Backlog – The number of connections that the server puts “on hold” while it is busy. Once this
number is reached, connections are refused.
l Read timeout (seconds) – How many seconds of inactivity to allow before Interchange
terminates the connection.
1. Log into the Interchange user interface as an administrator.
2. Manually enter the following URL in your browser: http://<localhost or
machinename>:6080/ui/core/SystemProperties#
The Systems Properties page is displayed.
3. At the bottom of the page click Show default system properties.
4. Find the default system property entry actionTree.clearContentTypeProtocolsList,
and click Add Property.
5. In the Value field, enter AS1.
6. Click Add.
To change settings:
Advanced tab
l Minimum threads – The least number of threads Interchange must dedicate to the server.
l Maximum threads – The most threads Interchange can dedicate to the server.
l Read timeout (seconds) – How many seconds of inactivity to allow before Interchange
terminates the connection.
To change settings:
The following are the maintenance fields for an embedded OFTP X.25 over ISDN transport server
that has been added by a community.
Settings tab
l Server name – The name for the embedded OFTP server. This can be any name you want.
l ISDN controller – The ISDN controller, selected from a drop-down list, to use for the outgoing
call.
l Subscriber number – The subscriber number this embedded server answers to. This is the
number as seen by the ISDN router. Typically, prefix digits (international, external line) have
been removed by the telecom equipment. Check with your telecom operator for the correct
number.
Advanced tab
l Minimum threads – The least number of threads Interchange must dedicate to the server.
l Maximum threads – The most threads Interchange can dedicate to the server.
l Read timeout (seconds) – How many seconds of inactivity to allow before Interchange
terminates the connection.
l Limit bandwidth to 56 kbps – Select this when a provider uses 56 kbps-bit transparent
operation with byte-framing from the network as its physical layer protocol instead of the default
64-kbps with HDLC framing. For such cases, this check box must be selected for the ISDN
connection to be properly established.
l Layer 2 window size – Specifies how many layer 2 (ISO 7776) packets can be sent before an
acknowledgment is required from the partner. If blank, use the network’s default value.
l Layer 3 window size – Specifies how many layer 3 (ISO 8208) packets can be sent before an
acknowledgment is required from the partner. If blank, use the network’s default value.
l Layer 3 packet size – Specifies the size of the layer 3 packets. If blank, use the network’s
default value.
l Lowest incoming channel – The starting value for the incoming channels identifier’s
counter. If blank, use the network’s default value.
PeSIT (embedded) fields
An embedded PeSIT server is available after a community adds a PeSIT transport for picking up
messages from integration or a PeSIT transport for receiving messages from partners. You can
change the server’s settings and advanced options.
To change settings:
The following are the maintenance fields for an embedded PeSIT (PeSIT) transport server that has
been added by a community.
Settings tab
l Server name – A name you give the transport server to distinguish it from other embedded
servers. This field gets its initial value when you type it in the delivery exchange wizard.
l Host – The fully qualified domain name of the computer on which the embedded server runs.
Interchange detects this setting; you cannot change it.
l Port – The port on which the server listens for connection requests.
Advanced tab
l Minimum threads –The least number of threads must dedicate to the server.
l Maximum threads –The most threads can dedicate to the server.
l Read timeout (seconds) – How many seconds of inactivity to allow before Interchange
terminates the connection.
If you do not select this option, all cipher suites are supported by default. Keeping the default
cipher list is less secure than specifying a restricted set of cipher suites.
The cipher suites that are displayed in the "Available" column depend on your runtime
environment (JRE version, IACK or FIPS enablement, Secure Relay configuration, ....).
The default order in the "Available" column is the preferred order of use. Once ciphers are moved
to the Selected column, you can arrange the order. Interchange uses the ciphers in the order
listed.
A cipher suite is a collection of security algorithms used in making connections via Secure
Sockets Layer or Transport Layer Security. For example, an SSL or TLS protocol requires signing
messages using a message digest algorithm. But the choice of algorithm is determined by the
particular cipher suite being used for the connection. Typically, you can select an MD5 or SHA
digest algorithm.
Of the many algorithms for encrypting data and computing the message authentication code,
there are varying levels of security. Some provide the highest levels of security, but require a
large amount of computation for encryption and decryption. Others are less secure, but provide
rapid encryption and decryption. The length of the key used for encryption affects the level of
security. The longer the key, the more secure the data.
The option for overriding cipher suites lets you select the level of security that suits your needs
and enables communicating with others who might have different security requirements. For
example, when an SSL connection is established, the client and server exchange information
about the cipher suites they have in common. Then they communicate using the common
cipher suite that offers the highest level of security. If they do not have a cipher suite in
common, secure communication is not possible.
In versions of Interchange earlier than Interchange 5.9, cipher suites configuration was handled
by a file named sslciphersuites.xml. As data in that file is saved in the database, the
custom cipher suites configuration is retained upon upgrading and is displayed in the Selected
list under the option in the user interface. The sslciphersuites.xml file is no longer used.
Interchange user interface provides flexibility for several setup variations. The use cases include the
most common combinations.
Case A
Embedded HTTP
A partner connects to host:port from a remote URL and sends a POST request containing the path
part of the URL.
UI settings
Local URL http://server1.domain.com:4080/exchange/routingID
Remote URL (same)
Proxy (none)
Results
Action Value
Server binds to <cluster_machines>:4080
Partner connects to server1.domain.com:4080
Partner request POST /exchange/routingID HTTP/1.1
HOST server1.domain.com:4080
<other headers and payload>
Case B
UI settings
Local URL http://server1.domain.com:4080/exchange/routingID
Remote URL http://edi.domain.com:5080/exchange/routingID
Proxy (none)
Results
Action Value
Server binds to <cluster_machines>:4080
Partner connects to edi.domain.com:5080
Partner request POST /exchange/routingID HTTP/1.1
HOST edi.domain.com:5080
<other headers and payload>
Case C
UI settings
Local URL http://server1.domain.com:4080/exchange/routingID
Remote URL http://edi.domain.com:5080/inbound/stuff
Proxy (none)
Results
Action Value
Server binds to <cluster_machines>:4080
Partner connects to edi.domain.com:5080
Partner request POST /exchange/routingID HTTP/1.1
HOST edi.domain.com:5080
<other headers and payload>
Case D
UI settings
Local URL http://server1.domain.com:4080/exchange/routingID
Remote URL http://edi.domain.com:5080/inbound/stuff
Proxy proxy.domain.com:8080
Results
Action Value
Server binds to <cluster_machines>:4080
Partner connects to proxy.domain.com:8080
Action Value
Partner request POST http://edi.domain.com:5080/inbound/stuff HTTP/1.1
HOST edi.domain.com:5080
<other headers and payload>
Case E
UI settings
Local URL https://server1.domain.com:1443/exchange/routingID
Remote URL https://edi.domain.com:1453/exchange/routingID
Proxy (none)
Results
Action Value
Server binds to <cluster_machines>:1443
Partner connects to edi.domain.com:1453
Partner request POST /exchange/routingID HTTP/1.1
HOST edi.domain.com:1453
<other headers and payload>
Case F
Embedded HTTPS (SSL) with proxy and remote URL including path
remapping
This is similar to the non-HTTPS proxy case, except that the partner starts off by sending a CONNECT
request to tell the proxy to establish a tunnel to the endpoint server. This allows it to perform SSL
handshaking with the endpoint server before sending the POST request. Note in the following
example that the POST request contains only the path, unlike the non-SSL proxy case, which
includes the full URL in order to tell the proxy how to find the endpoint server.
HTTPS-capable clients that can handle non-transparent proxies are set up to perform these two
steps (CONNECT followed by POST), which keeps the setup simpler for the user.
UI settings
Local URL https://server1.domain.com:1443/exchange/routingID
Remote URL https://edi.domain.com:1453/exchange/routingID
Proxy proxy.domain.com:8083
Results
Action Value
Server binds to <cluster_machines>:1443
Partner connects to proxy.domain.com:8083
Partner request 1 CONNECT edi.domain.com:1453
Partner request 2 POST /exchange/routingID HTTP/1.1
HOST edi.domain.com:1453
<other headers and payload>
Note that if you also require DMZ zones, the DMZ zones must be created first, before the DMZ node
or nodes can be created.
Related topics
l Overview of Secure Relay nodes on page 474
l Add DMZ zones on page 478
l Add a DMZ node on page 481
l Run node as Windows service on page 484
l Enable port forwarding for an exchange on page 484
l Configure load balancer or firewall on page 487
l Configure outbound connection proxy on page 488
l Manage IP address whitelists on page 490
l HTTP trading and Secure Relay on page 493
l The Secure Relay master agent, hosted by Interchange control node, makes the connections
between it and the Secure Relay router agent in the DMZ. The router agent does not initiate
connections to your protected network.
l Connections between the master agent and router agent are encrypted and mutually
authenticated over TLS.
l The multiplexed, persistent connection between the master and router support bi-directional
message traffic. You can send or receive messages over the same connection.
Additional security can be engaged by using IP address whitelists in conjunction with Secure Relay.
See Manage IP address whitelists on page 490.
The following figures illustrate configurations for trading messages via Secure Relay. Both figures
depict a fail-over configuration with redundant Interchange nodes and Secure Relay router agents.
If you elect to use DMZ zones, these configurations can be applied to each zone.
The following figure illustrates the reception of inbound messages via Secure Relay:
The following figure illustrates the sending of outbound messages via Secure Relay:
In this example, it is not necessary for port 4080 to be open on the inner firewall because any
connection to port 4080 on the DMZ node is forwarded through the multiplex connection to
Interchange.
If additional Interchange nodes are started, these also connect to the DMZ node and set up the
necessary forwarding rules for the exchange points they host. If running in cluster of multiple
computers, make sure all instances of Interchange on all machines share the same common
directory. The common directory is specified by the commonPath property in the filereg.xml file
in the conf directory.
The earlier figures show the two types of encrypted connections the master agent makes to the
router agent:
l Administrative – The administrative connection is what the master agent uses to send port-
forwarding rules to the router agent. Rules are sent dynamically to account for changes within
Interchange (for example, a node starting or stopping). Once the connection has been
established, the master agent sends requests and the router agent responds with the result of
each operation.
l Multiplex – The multiplex connection is the bi-directional channel through which e-commerce
messages and receipts flow.
Both the administrative and multiplex connections are persistent, so long as Interchange server and
router agent are running.
The certificate files are stored in common\conf\certs. As long as these files remain and the keys
have not expired, Interchange does not generate other certificates. However, if any of these files are
deleted or the certificates expire, the connections to the router agent are compromised when
Interchange or router agent is restarted. The remedy is:
1. Stop the router agent and remove it from the DMZ computer.
2. Delete all files in common\conf\certs.
3. Add another Secure Relay node in the user interface. Interchange generates a new set of
certificates for Secure Relay.
4. Deploy the new router agent on the DMZ computer.
Load balancing
A load balancer is required to distribute inbound connections among DMZ node ports. The
difference, as compared to the load balancer sending connections directly to Interchange, results
from the redundant connections between Interchange nodes and DMZ nodes. This requires each
embedded server on each Interchange node to be represented by a unique port on each DMZ node.
So instead of sending connections to only two locations (for example, te1:4080 and
te2:4080) the load balancer sends connections to four locations (for example, dmz1:4080/4081
and dmz2:4080/4081). Connections to 4080 on either DMZ node are automatically forwarded to
te1. Connections to 4081 on either DMZ node are automatically forwarded to te2.
FTP passive ports are accommodated using a variation on this scheme. When partners use passive
FTP mode (the default for most modern FTP clients), connections come and go dynamically as GET,
PUT and LIST requests are made. Only Interchange node that accepted the control connection from
the partner is listening for passive connections associated with that partner FTP session. Each time a
GET, PUT or LIST request is made, a temporary forwarding rule is dynamically sent to all DMZ nodes
to ensure the partner's data connection is routed to the correct Interchange node, even if the load
balancer sends it to a different DMZ node than the one that is proxying the control connection.
Specific information for configuring load balancers is provided in Configure load balancer or firewall
on page 487.
Security features
Secure Relay nodes have the following security features:
l Connections to the router agent are established by the master agent within Interchange.
l Connections are encrypted. Authentication is mutual.
l Forwarding is initiated and canceled in concert with the starting and stopping of the embedded
server in the protected network. Forwarding is not permitted for an embedded server that is not
running.
l FTP passive ports are forwarded dynamically as the embedded FTP server assigns passive ports to
clients. Forwarding is not permitted for a passive port that is not currently assigned to an FTP
client.
l The history of connections is written to the router agent’s log file.
DMZ nodes are managed:
l On the DMZ zones tab of the system management page. This is where zones are added. To use
DMZ zones, zones must be added before adding DMZ nodes.
l On the DMZ nodes tab of the system management page. This is where zones are assigned to DMZ
nodes upon adding the nodes.
l On the advanced tab of a transport for a partner. This is where you specify the DMZ zone for
messages sent to the partner.
l On the DMZ ports tab of an embedded server. This is where you specify the DMZ zone for all
inbound messages received by the server.
If you delete a zone on the DMZ zones tab, any nodes associated with the zone no longer are
assigned to any zone. The zone status of the nodes changes to no zone.
If you have no interest in ordering message traffic through specific DMZ nodes, ignore the DMZ
zones tab.
Users of version 5.8 and later of Interchange can use DMZ zones with DMZ nodes. If you used DMZ
nodes in an earlier version and upgraded to 5.8 or later, the pre-existing nodes do not have zones
and cannot be assigned to zones. To use zones, stop and delete the DMZ nodes, remove the nodes
from the DMZ computers, add one or more DMZ zones, add DMZ nodes and assign them to zones,
and deploy the nodes in the DMZ.
5. Go to Add a DMZ node on page 481 and add a node. On the page for adding a node, select a
zone for the node. Do not use the default no zone setting. After adding and starting the node,
return to this procedure and go to the next step.
6. Review the DMZ zones tab. Now the name or IP address of the DMZ computer running the node
assigned to the zone is listed in the Hosts column.
7. Perform other usual tasks for Secure Relay configuration.
a. Turn on port forwarding. See Enable port forwarding for an exchange on page 484.
b. Configure the load balancer or firewall. See Configure load balancer or firewall on page
487.
c. Turn on outbound proxying for Secure Relay. See Configure outbound connection proxy
on page 488.
8. Assign zones to partners. Messages are sent via the assigned zone.
On a partner summary page, click Delivery exchange on the navigation graphic at the top of
the page. Click the name of a transport to open its maintenance page. Select the Advanced
tab. Select a zone from the drop-down list and click Save changes.
Before adding the first or subsequent DMZ nodes, determine whether you want nodes to be
organized by zones. Zones are a way to have messages sent to partners via specific DMZ nodes.
Review Add DMZ zones on page 478 and then return to this procedure.
In addition to adding a node, you must complete other tasks to properly configure Interchange to
use DMZ nodes. These are:
l Enable port forwarding for an exchange on page 484
l Configure load balancer or firewall on page 487
l Configure outbound connection proxy on page 488
Prerequisites
JRE version
The Secure Relay router node requires JRE 7 (or later) on the machine where the node is installed.
Interchange supports the following JVM implementation for DMZ nodes:
l Windows/Solaris/Linux – Sun
l AIX – IBM
l HP-UX – HP
You can obtain unlimited strength JCE policy files from the following web sites:
l Sun/HP –
http://www.oracle.com/technetwork/java/javase/downloads/index.html
l IBM – http://www.ibm.com/developerworks/java/jdk/security/60/
Add a node
1. Click System management on the top toolbar in the user interface to open the System
management page.
2. On the DMZ nodes tab, click Add a node to open the Configure Secure Relay router page.
3. If this is the first node being added, go to the next step and add a password. Otherwise, go to
step 5.
4. Enter a password for securing the private key in a certificate used by DMZ nodes. Interchange
generates the root certificate, the password file and P12 files for the master and router agents.
The root certificate, router P12 file and password file are exported from Interchange and
imported by computers in the DMZ for use by DMZ nodes for authenticating connections from
Interchange.
You only have to set a password once, and there is no need to remember it. No matter how
many DMZ nodes you add later, you are not prompted again for a password.
The generated certificates are stored in common\conf\certs.
5. Complete the fields on the Configure Secure Relay router page:
l Host – Type the IP address or fully qualified domain name of the computer in the DMZ
where the node is to be deployed.
DMZ computers often have two network interfaces with separate IP addresses, one for
internal connections and one for external connections. Since this value is used by
Interchange in the protected network to connect to the DMZ node, you must specify the
internal host interface. You cannot use 0.0.0.0.
l Port – Enter the port number on the internal host interface where the DMZ node listens for
administrative connections from Interchange. The firewall should not allow external
connections to this port.
l External host interface – For proxied outbound active FTP, enter the external IP address
to be returned by the client in response to server requests for active data connections.
l Control port – Enter the port number used by scripts in the Secure Relay xsr/bin directory
on the DMZ computer to query or stop the router. (Listens only on localhost in the DMZ.)
l Zone – If you intend to associate the node with a DMZ zone, select the zone. If the zone
you want does not display, cancel adding the node and add the zone on the DMZ zones tab.
This field displays only if one or more zones have been added on the DMZ zones tab.
Selecting a zone is optional. For information about zones see Add DMZ zones on page 478.
l Data port (min) and Data port (max) – Enter the port range for data connections in
the respective minimum and maximum fields. Only as many ports as there are trading
engine nodes are actually used. A range of at least 9 is suggested. The range of ports must
be dedicated for use only by the Secure Relay router agent. The firewall should not allow
external connections to these ports. For these fields, count the control node as well as all
processing nodes.
You can specify a smaller port range than 9, but the higher range may avoid future issues.
For example, if a user runs two processing nodes and later decides to add two more, Secure
Relay can handle the increase automatically. However, if a narrower range had been
specified, adding more nodes may require redeploying DMZ nodes to account for the ports
used by the added processing nodes. The already deployed DMZ nodes would not have the
configuration for other ports to open when more processing nodes are added.
l Number of data connections – Specify the number of connections each trading engine
node is to make to its assigned data port on the DMZ node. Normally, this should be 1 since
information from multiple conversations is multiplexed over a single connection. In some
cases performance may improve if you increase this to match the number of CPUs in the
DMZ computer.
6. Click Add. The DMZ nodes tab on the system management page displays again and lists the
node you just added. The node has a status of Connecting. There are several tasks yet to
perform to get the node running. To view more about the new node, click the host name to
open a details page.
1. On the DMZ nodes tab, click Export to save the node file to a directory. The file is named
dmzNode.xsr.<internal host interface>_<internal port>.zip.
2. Give the file to your DMZ or network administrator. In most cases, only the administrator is
authorized to work with computers in the DMZ.
The DMZ node agent's P12 file is included in the exported zip file, along with instructions for
your administrator. On Windows, the DMZ node can be run as a service. See Run node as
Windows service on page 484.
3. Once the administrator has completed the configuration and started the node, go back to the
system management page. If the node is working, the node’s status should have changed to
running.
Later, if the Secure Relay node in the DMZ is stopped, the DMZ nodes tab on the system
management page displays a status of Connecting -- Start DMZ node. You need to restart
the node to return to a status of running.
1. From the node’s bin directory, double-click or run setupService.bat to open the Service
mode configuration window. The node must not be running to open the window.
2. Complete the fields as needed:
l Java executable – The path to the Java installation and java.exe file on the computer
running the node. For example: C:\Program Files\Java\JRE7\bin\java.exe.
l Home directory – The location of the node on the computer. Do not change this path.
l Name – The name of the service. This is the name a user would use to stop and start the
service from a command line using XP tools.
l Start automatically – Select this option if you want the service to start the node when the
computer restarts. Clear this option if you want to start the service manually.
l Start service under – Select Current account to have the service start under the name
of the current user’s account.
Select Another account to specify the user name and password of another user. We
suggest using a user account dedicated only to the service and not used by any other user.
When used with Windows 2003, the user account used to run the node must have the
“Open a session as a service” right as set by the local security policy editor. Otherwise it is
not allowed to start services in non-interactive mode.
You can set up the Windows service under a local system account or a domain\user
account. Use a domain account if the service needs to access your network or other
resources requiring user permissions beyond a local account. If unsure, ask your network
administrator. Type a domain\user and password only for a domain account; you do not
have to do so for a local account.
3. Click Register to save your changes.
a. Open the maintenance page for the exchange just added. To do this, click the transport
name on the Trading pickups page for the community.
b. On the embedded settings tab, click the link to view settings for the embedded server.
c. Select the DMZ ports tab.
d. Select Enable DMZ port forwarding and click Save changes. See the Port forwarding
details section below for more information. Click the Port field to display a list of ports
already in use.
Optionally, select one or both of the following options:
f. If an FTP or SFTP server, make sure you have specified a range for passive ports on the
Advanced tab. The default value of 0 does not work with DMZ nodes.
In addition, make sure the external host or IP address on the Settings tab is for the
computer in the DMZ that hosts the DMZ node. The internal host that runs Interchange
cannot be given as the external host. Moreover, make sure the external port on the Settings
tab matches the port field on the DMZ ports tab. For more information about these fields,
see Embedded transport servers on page 431.
5. Go to Configure load balancer or firewall on page 487.
In the simplest case there is one DMZ port with the same value as the corresponding embedded
server port in the protected network. If you add a machine to your cluster and return to the DMZ
ports tab, another DMZ port automatically is added in sequence. This happens because every
machine in the cluster that can host the embedded server must be assigned a unique corresponding
port in the DMZ.
Click the port field to display a list of ports already in use.
Example
Suppose you have two trading engine nodes on separate machines hosting FTP servers on port
4021. On the DMZ ports tab you would see one port representing each machine in the cluster (for
example, 4021 and 4022). This allows a dedicated port forwarding rule to be established from each
unique DMZ port to each unique cluster machine.
Another way to think of this is that a cluster host and port represent a unique to address for a
forwarding rule (for example, te1:4021 and te2:4021). The corresponding from address in the
DMZ also must be unique. This is achieved by assigning multiple ports. Consequently, if the DMZ
node machine is named dmz1, the forwarding rules would look like this:
If you add another DMZ node, it forwards the same set of DMZ port numbers. But the forwarding
rules would still be unique because the new DMZ node must be on a different host machine. For
example:
Notice for a given DMZ node the from host is the same for all the rules, but the port changes.
Similarly, the to host changes for each rule, but the port stays the same. You do not necessarily
need to be aware of this, apart from making sure your load balancer is configured properly.
You can access the DMZ ports tab for any embedded server by clicking on the value in the DMZ
port column on the embedded servers page. You can open the page by selecting System
management > Manage embedded servers.
Most likely, only the simplest setup would send connections directly from the outer firewall to the
DMZ node. That would be the case if there was just one Interchange node and only one DMZ node.
There would be no need for a load balancer. But if there are multiple cluster machines or multiple
DMZ nodes or both, a load balancer is needed.
In the example cited in Enable port forwarding for an exchange on page 484, the load balancer
would send connections to the following four locations:
It is important to update your load balancer configuration whenever either of the following occurs:
l You add a new host machine to the cluster (since this would add a new DMZ port on each DMZ
node for every embedded server).
l You add a new DMZ node (since this would add a new host machine that is listening on the same
DMZ ports as the existing DMZ nodes).
As a general rule, when you add transport servers or host machines in the cluster, refer your DMZ or
network administrator to the information on the embedded servers page to determine whether
corresponding changes are necessary in the load balancer or firewall. This rule also applies when
enabling DMZ port forwarding for an embedded server that previously did not use it.
l Open the outbound proxy page on page 488
l Enable outbound proxy and exceptions on page 489
Exceptions
Exceptions work if given in the same form as the addresses in the delivery exchange points. For
example, if the exchange point gives a host as server.mycompany.com, the exception should be
server.mycompany.com or *.mycompany.com. In this case an IP address would not match
since a host name was specified in the exchange point.
However, you can use IP addresses if some exchange points contain IP addresses. If some
exchanges have IP addresses and some have host names, you can have exceptions for both.
FTP is a special case. Exceptions for FTP must have IP addresses, because responses to passive
commands contain IP addresses and not symbolic host names. As delivery exchange points and
exceptions must be in the same form, the FTP exchange points must use IP addresses, too.
To add an exception:
1. Type a fully qualified domain name or IP address in the Host name or IP address field.
2. Click Add.
You can delete exceptions, too.
In the case of outbound active FTP, review the guidelines on the outbound connection proxy page
for entering the IP address or fully qualified domain name of the Secure Relay host.
Use this page only after you have completed Add a DMZ node on page 481. Inbound configuration
tasks apply only to inbound connections and are not required to set up outbound connections.
These are:
l Enable port forwarding for an exchange on page 484
l Configure load balancer or firewall on page 487
The IP address whitelist is stored in Interchange database. It is edited and managed in the user
interface. Information is synchronized between the master agent within Interchange and the router
agent in the DMZ. Checking is done in the DMZ. But neither the list nor any related parameter is
persisted in the DMZ. IP checking can be enabled or disabled per listening point.
Note If you are licensed for Peer Networking and are cloning the whitelist, note that it should be
manually set on the peer set when needed.
l How IP addresses are checked on page 491
l Add, change IP address whitelist on page 492
l Enable IP address checking on page 493
1. Check whether the sender’s IP address is trusted. This is done at connection time,
independently of the transport protocol.
2. Check whether the IP address corresponds to the correct partner. This check is performed only
when the first check succeeds. If a user name and password is needed for the connection, the
correlation is done through the user that is logging on.
Objects used for checking are:
l Secure Relay DMZ nodes deployed in the DMZ
l One or more embedded servers within Interchange
l A whitelist of IP addresses used by partners
l Users known to Interchange who log in to embedded servers (in applicable cases)
Processing varies depending on whether trading is via a delivery exchange that requires user name
and password authentication.
1. The router agent in the DMZ receives a connection request. The request includes the sender’s IP
address.
2. The IP address of the partner is checked against the whitelist.
a. If the IP address is unknown, the connection is rejected.
b. If the address is known, the connection is allowed.
1. The router agent in the DMZ receives a connection request. The request includes a user name
and password and the sender’s IP address.
2. The router agent submits the request to the master agent.
3. The master agent looks for a partner that matches the user name, password and IP address.
a. If the IP address is unknown, the connection is rejected.
b. If the IP address is known but the log-in credentials are unknown, the connection is
rejected.
c. If both the IP address and the log-in credentials are known, the connection is allowed.
See: Add, change IP address whitelist on page 492 and Enable IP address checking on page 493.
Although this procedure is for the global whitelist, whitelisted IP addresses can be managed per
partner. On a partner summary page, click IP whitelist in the navigation graphic at the top of the
page. Many of steps for adding or changing IP addresses are the same as for the global whitelist,
except the addresses only affect the specific partner and are registered to the partner.
Note IP whitelists are only used with Secure Relay.
Change an IP address
1. Click the name of an IP address to open its details page. You can change the IP address or
range of addresses and change the registered parties.
2. Click Save when done.
Delete an IP address
Click Delete to delete an IP address or range of addresses.
See How IP addresses are checked on page 491 and Add, change IP address whitelist on page 492.
l On the transport maintenance page for your community, in the field named URL used by
partners, the URL must specify the host and port of the computer running the DMZ node and not
the computer running Interchange.
l If you trade via HTTPS, the common name of the SSL certificate must be the fully qualified
domain name of the computer running the DMZ node and not the computer running
Interchange. For more information about adding SSL certificates see Embedded transport
servers on page 431.
Interchange message exchanges can be classified in two general categories:
l Exchanges with applications
l Exchanges with trading partners
l FTP
l SFTP
l File system
l File system with message data (deliveries only)
l JMS
l IBM MQSeries
l MLLP
l Web Services API client
l Web Services (HTTP)
l PeSIT
l Axway Integrator
l Pluggable server
l Application pickups on page 160
l Add an application pickup on page 161
l Application deliveries on page 162
l Add an application delivery on page 162
l Modify an application pickup or delivery on page 202
l cXML (HTTP)
l ebXML (HTTP, SMTP)
l ebXML intermediary (HTTP, SMTP)
l EDIINT AS1 (email)
l EDIINT AS2 (HTTP)
l EDIINT AS3 (FTP, SFTP)
l EDIINT AS4 (HTTP)
l Generic email (SMTP/POP)
l MLLP
l No packaging (FTP, SFTP, file system, JMS IBM MQSeries, WebDAV)
l Odette FTP V1
l Odette FTP V2
l PeSIT
l PGP (FTP, SFTP)
l RosettaNet 1.1 (HTTP)
l RosettaNet 2.0 (HTTP)
l Secure file (HTTP, FTP, SFTP, file system, JMS, IBM MQSeries, WebDAV)
l Web Services (HTTP)
l x420
l X435
l Community trading pickups and partner deliveries on page 256
l Add a trading pickup on page 261
l Modify a trading pickup on page 326
l Add a partner trading delivery on page 262
l Modify a partner trading delivery on page 327
If you need more time to collect information, cancel the registration process and return to the
wizard later.
The following use the registration wizard:
l AS1 / AS2 partner self-registration on page 497
l ebXML partner self-registration on page 576
l AS1 / AS2 partner self-registration on page 497
l AS4 on page 499
l Axway CSOS on page 1008
l ebXML on page 545
l eSubmissions on page 1032
l FTP client scripting interface on page 866
l HTTP outbound proxy on page 584
l Staged HTTP on page 958
l MLLP on page 592
l OFTP on page 611
l PeSIT on page 651
l PGP secure trading on page 693
l RosettaNet on page 699
l Secure file message protocol on page 971
l Email client partners on page 579
l Web services on page 715
l WebTrader on page 980
l X.400 on page 737
A likely use of the registration wizard is for partners who have a trading engine other than
Interchange. The wizard prompts a user to supply the information Interchange needs to build a valid
partner. A community, however, could have partners who use Interchange enroll through the
wizard, as well as partners who use some other interoperable trading engine.
The registration wizard is a web site hosted on Interchange server. A community with license
permissions to use the wizard gives the partner a URL to access the web site in a browser and a user
name and password to log on.
An Interchange community prepares the partner registration wizard for use and the partner’s steps
for using the wizard.
Wizard preparation
Aside from configuring a community in the usual way, complete the following tasks so partners can
join your community using the partner wizard. These steps are applicable only if your user license
allows you to use the partner registration wizard.
1. Set a password for the partner user if this has not already been done.
When you log on to the user interface for the first time after installing, there is a link on the
getting started page for Set a password for partner self-registration. Click the link and
type a password for the partner user. This link only appears if your user license allows you to
run the partner registration wizard.
The system creates the partner user for you. Later, your partners will log on to your server’s
registration wizard with the user ID partner and the password you specify.
If the partner user already has been set up, check the users and roles area. Select Users and
roles > Manage users or Users and roles > partner registrant.
Give your partners the following information:
l URL – The URL for connecting to the page for logging on to the registration wizard. The
URL is in the following format:
http://<host>:6080/ui/
Where the variable host is the fully qualified domain name or IP address of the computer
running Interchange.
l User name and password – The user name and password the partner must use for
logging on to the registration wizard. Have the partner use partner and the password you
specified for the partner user.
l Community name – The name of the community the partner should select to join in the
registration wizard.
2. Discuss with your partner whether to trade messages via the AS1 or AS2 message protocol.
3. After a partner registers via the wizard, a message displays on the user interface home page,
prompting you to approve the registration and associate the partner with your community.
Click Trading Partners in the navigation graphic at the top of the community summary page,
click Add a partner to this community, select Choose an existing partner and click
Next. Select the partner and click Add.
l The URL to connect to the wizard in a browser.
l A user name and password to log on to the wizard.
l The name of the community to join.
l The name of your company.
l A company contact name and e-mail address.
l The routing ID to use as your company’s unique identifier for e-commerce trading.
l An encryption certificate and public key exported to a file with an extension of .cer, .p7b or
.p7c. Do not use a certificate file that contains your private key.
l If trading via AS1, the e-mail address you want the community to use for sending messages to
your company.
l If trading via AS2, the HTTP or HTTPS URL the community needs for sending messages to your
company. If HTTPS, you have the option of specifying in the wizard whether to compare the
name of the SSL server to the name in the server’s certificate to ensure they are the same. Also, if
the community needs a user name or password to connect to the server, you must provide that
information in the wizard.
Once you have collected this information:
1. Log on to the partner registration wizard.
2. Follow the wizard prompts for registering.
3. Wait for the community to contact you with the next steps.
AS4
l MessageProtocolAS4
l MessageProtocolWebServices
AS4 overview
AS4 is a Business to Business (B2B) protocol that extends the functionality of AS2 with ebMS-based
Web Services technology. AS4 is easier to implement and lower in cost to set up and operate than
traditional B2B protocols.
The main benefits of AS4 compared to AS2 are:
l Compatibility with Web Services standards
l Message pulling capability
l Built-in receipt mechanisms
AS4, like AS2, only supports HTTP for Internet transport.
AS4 provides two conformance profiles for ebMS 3.0:
l The ebHandler conformance profile – supports both sending and receiving roles, and both
message pushing and message pulling for each role.
l The Light Client conformance profile – supports both sending and receiving roles, but only
message pushing for sending and message pulling for receiving. In other words, it does not
support incoming HTTP requests, and may have no IP address.
AS4 supports non-repudiation of receipts, similar to the MDN used in AS2, and specified as an XML
schema. Non-repudiation receipts are returned using a dedicated signal message and defaults to
requiring message recipients to return a signed receipt containing the digests necessary for non-
repudiation. The receipt may also contain error handling information if there was some problem
with the document exchange.
AS4 supports duplicate message detection and message retry/resending scenarios for when receipts
for messages are not received by the sender.
Related topics
Concepts:
l AS4 messages on page 501
l AS4 metadata on page 503
l Message Partition Channels (MPC) on page 515
l AS4 user authentication on page 518
l Large message splitting and joining on page 521
l Enable handling of empty SOAP Body messages on page 523
Examples:
l Configure a one-way client pull on page 524
l AS4 use case: One-way push (MMD initiated) on page 527
l AS4 use case: One-way pull (MMD initiated) on page 529
Tasks:
l Add an AS4 trading delivery on page 533
l Modify an AS4 trading delivery on page 534
l Add an AS4 embedded server pickup on page 538
l Modify an AS4 embedded server pickup on page 539
l Add an AS4 polling client pickup on page 541
l Modify an AS4 polling client pickup on page 543
l Manage AS4 polling queues on page 545
AS4 messages
An ebMS message is a SOAP message that contains SOAP header(s) qualified with the ebMS
namespace, and that conforms to the AS4 specification.
Message structure
There are two logical sections within the ebMS message package:
l The first section is the ebMS Header (the eb:Messaging SOAP header block), itself contained in
the SOAP Header.
l The second section is the ebMS Payload, which itself comprises two sections:
o The SOAP Body element within the SOAP Envelope and in case of MIME packaging,
o Zero or more additional MIME parts containing additional application-level payloads. The
SOAP Body and MIME parts are also referred to as ebMS Payload Containers. The SOAP Body
is the only payload container that requires XML-structured content
When you trade messages with AS4 you exchange two categories of messages:
l User messages - Usually containing a payload
l Signal messages – Containing requests, receipts and error messages
The following figure describes the general structure and composition of ebMS User Message:
The following figure describes the general structure and composition of ebMS Signal Message:
AS4 metadata
Interchange supports a standard set of metadata that can be attached to AS4 messages.
Some of the metadata attributes can be used in Message Metadata Documents (MMDs). Example
MMDs are described in this chapter.
Metadata are exchanged between Interchange and a back-end system through the following
application transports:
l JMS (consume from and produce to the back end)
l File system (consume from the back end)
l File system with message metadata (produce to the back end)
l Web services API server (consume from the back end)
l Web services API client (produce to the back end)
This chapter contains the following sections:
l Metadata descriptions on page 504
l Required metadata on page 511
l Message Metadata Documents (MMD) on page 512
l MMD examples on page 512
o Example 1: Initiate a push on page 512
o Example 2: Generate a queued message for pulling on page 513
o Example 3: Initiate a pull request on page 514
o Example 4: Initiate a receipt send on page 514
o Example 5: Initiate an error message send on page 515
Metadata descriptions
The following table lists and describes the metadata attributes that can be used with AS4 messages.
When the attribute can be managed from a Message Metadata Document (MMD), the MMD element
name is given.
Standard Metadata
ReceiverRoutingId To Routing ID of the receiver
participant.
ebXML Metadata
Signal-processing Metadata
Pull-related Metadata
AS4.ProcessedUsingExchangeP –– For information only. Do
oint not override.
Set on the UM received as
response to a pull request
when it has been
processed using specific
exchange point settings.
PollingCycleExecutedRequests –– For information only. Do
not override.
Displays current executed
pull request for the
current sequence.
Incremented whenever a
new pull request is
generated in the current
polling cycle.
PollingCycleRequestsId –– For information only. Do
not override.
Displays the cycle ID of
the polling cycle for a pull
request generated from an
AS4 polling client
exchange.
PollingCycleRequestsExchange –– For information only. Do
not override.
Displays the AS4
exchange point used for
polling .
Splitting-related Metadata
SplitCompressedMessageSize -- For information only. Do
not override.
Specifies the size (in
bytes) of the compressed
MIME envelope .
Shown in the UI, for
internal use, not to be
overwritten by customers
.
FragmentJoiningInterval –– Default=Value of
Interchange system
property
"as4.joinExpirationCheck.
interval
Specifies the maximum
time to expect and
process additional
fragments after the first
fragment is received. Used
to override the global
system property
"as4.joinExpirationCheck.
interval"
ebXML.FragmentCount –– For information only. Do
not override.
Specifies the number of
fragments the MIME
envelope was fragmented
into.
ebXML.FragmentNum –– For information only. Do
not override.
Specifies the current
fragment's sequence .
ebXML.MessageSize –– For information only. Do
not override.
Indicates the size (in
bytes) of the message
after reassembly .
AS4.SplitterAction –– For information only. Do
not override.
Used to display split status
in tracker for the
fragmented user message.
UserMessage –– For information only. Do
not override.
Displays the copy of
UserMessage element.
NonRepudiationInformation –– For information only. Do
not override.
Displays the copy of
NonrepudiationInformatio
n element .
CheckAllCommunitiesForDuplic –– Default=true
ate Enables duplicate checks
across communities or
within a community
SkipSchemaValidation –– Default=true
Enables ebXML schema
validation on the received
message. Since ebXML
schemas generally have
few issues, schema
validation is skipped
default.
Required metadata
According to AS4 specifications, an AS4 user message must have, as a minimum, the following four
metadata attributes:
l FromRole – identifies the authorized role of the party who is sending the message.
l Service – is a string that identifies the service that acts on the message and it is specified by the
designer of the service.
l Action – is a string that identifies an operation or an activity within a Service.
l ToRole – identifies the authorized role of the party who is receiving the message.
If any of the attributes are missing, the AS4 message will fail to package. You can assign the values
of your choice to these metadata attributes. The AS4 standards provide the following default values:
l FromRole = http://docs.oasis-open.org/ebxml-
msg/ebms/v3.0/ns/core/200704/initiator
l ToRole = http://docs.oasis-open.org/ebxml-
msg/ebms/v3.0/ns/core/200704/responder
l Service = http://docs.oasis-open.org/ebxml-msg/as4/200902/service
l Action = http://docs.oasis-open.org/ebxml-msg/as4/200902/action
For a detailed description of AS4 metadata attributes, see AS4 metadata on page 503.
When you develop Agreements, there are two common methods that you can use to attach
metadata attributes to the messages you handle:
l Use a map to set metadata attributes
You can use MMDs to initiate AS4 message push and pulls, as well as to build and deposit AS4
messages into message queues for client pull consumption.
MMDs are used only with file system integration, although the same type of metadata are
transported when integration transports such as JMS or web services API are used.
MMD examples
</Payload>
</MessagePayloads>
</MessageMetadataDocument>
In this MMD:
l Push sender is: AS4BUYER
l Push receiver is: AS4SUPPLIER
l Pushed payload file is: PurchaseOrder.xml
l Location of the payload file on the sender network is:
C:\Axway\Interchange\common\data\
When Interchange consumes this file from a back-end file directory, it recognizes that it is an AS4
MMD (from the ebXML v3 protocol attribute) and uses the file content information to build an
outbound AS4 user message to the receiving participant.
In this MMD:
l Pull sender is: AS4BUYER
l Pull consumer is: AS4SUPPLIER
Note: A message in the pull queue does not have to contain sender/receiver information. A
message can be queued for consumption by any client that is authorized for the MPC. By
entering consumer (receiver) information, you restrict pulling to a specific client partner.
l Payload files are: BusinessDocument_1.xml located in the SOAP Body and
BusinessDocument2.xml attached to the SOAP message.
l Location of the payload files on the pull sender network is:
C:\Axway\Interchange\common\data\
l The AS4 MPC attribute is commented out. Since it is not explicitly specified, the default channel
will be used.
When Interchange consumes this file from a back-end file directory, it recognizes that it is a message
intended for a client pulling partner (from the "message.WaitForPull " metadata attribute).
Interchange then builds a message which it puts in a "wait for pull" message holding queue, to be
polled by a partner.
In this MMD:
l Pull server/sender is: AS4SUPPLIER
l Pull requester/consumer is: AS4BUYER
l Message is signal type: PullRequest
l MPC is the default, specified by the default value: http://docs.oasis-
open.org/ebxmlmsg/ebms/v3.0/ns/core/200704/defaultMPC.
Note: Alternatively, you could remove this line, and Interchange would automatically select the
default implicit (empty) MPC.
In this MMD:
l Receipt sender is: AS4SUPPLIER
l Receipt requester is: AS4BUYER
l Message is signal type: Receipt
In this MMD:
l Error message sender is: AS4SUPPLIER
l Error message receiver: AS4BUYER
l Message is signal type: Error
Multiple sending and receiving participants can use the same MPC for trading.
MPC requirements
For an AS4 message to be successfully transferred, the sending and receiving participants must
agree on the MPC that is to be used for the exchange, and then each participant must configure the
exchange to use that MPC.
Interchange always assumes an MPC for any AS4 message exchange:
If no MPC is explicitly assigned in the exchange configuration, Interchange implicitly
assumes the blank MPC.
You can explicitly specify the default MPC b y using the default value:
http://docs.oasis-
open.org/ebxmlmsg/ebms/v3.0/ns/core/200704/defaultMPC.
You can explicitly specify a value other than the MPC default value.
Assigning MPCs
As explained above, in Interchange, an MPC can be assigned explicitly or implicitly.
When you configure Interchange as a participant in an AS4 message exchange, you must always
include an object that determines the MPC to use (implicitly or explicitly). The object that you use to
do this varies depending on the Message Exchange Pattern and the role Interchange plays in the
pattern.
To summarize how you assign an MPC in an exchange configuration, you can:
l Use the default MPC implicitly by not specifying any
l Use the default MPC explicitly by specifying it: [http://docs.oasis-
open.org/ebxmlmsg/ebms/v3.0/ns/core/200704/defaultMPC]
l Use a non-default MPC by specifying it
l (For client polling pickups only) specify an override MPC
For example, if an Interchange instance has an AS4 Trading Partner Delivery with "MPC123"
specified, it can push an AS4 message to another Interchange instance using that MPC.
In pull mode only, if you specify an MPC in a configuration, but the intended trading partner does
not also specify the same MPC, the trade will fail with an error indicating that the MPC is not found.
Based on the MPC setting in the community trading pickup Polling Settings tab, the polling client
request will contain one of the following values:
Push behavior
When Interchange is configured for AS4 push, it uses the settings of the Partner Trading
Delivery/HTTP Settings tab to select the MPC to use (if not already defined in metadata provided
by an MMD or metadata processing).
Based on these settings:
l If the Message partition channel field is blank, Interchange uses the already-defined or
default implicit (empty) MPC.
l If the Message partition channel field contains a value, that value is the MPC to use for the
transfer (unless it is already defined by an MMD or metadata).
A push with no MPC specified, uses the default implicit (empty) MPC.
For a push, you can explicitly define any MPC, including the default MPC (http://docs.oasis-
open.org/ebxmlmsg/ebms/v3.0/ns/core/200704/defaultMPC).
l UserName tokens
l X.509 security tokens
It is recommended to use at least one of these authentication methods. The two methods may be
combined to authenticate a remote partner's pull request.
Whatever user authentication scheme you agree upon with your AS4 trading partner, it must be
implemented identically for both the sender and receiver partner, or the message exchange will fail.
UserName tokens
UserName tokens are supported for user authentication in AS4 message exchanges, as described in
the WSS: SOAP Message Security specification. The following paragraphs describe their use.
Push authentication
On a sender-initiated AS4 User message push, the UserName token can be optionally included in the
header of the AS4 User message, and checked by the receiver to confirm that it is sent from a known
partner. The token comprises a specific user name and password.
If the user name and password are confirmed, the message is accepted. Otherwise the message is
rejected.
Pull authentication
On a client initiated AS4 pull request, the user name token can be optionally included in the header
of the AS4 Signal message (pullRequest) sent by the client, and used by the server to validate the
requester.
Because a pull request/response is synchronous, the response is returned in the same synchronous
connection and the authentication setting on the server (user message sender) side is ignored.
Activate UserName tokens in the AS4 Collaboration Settings:
1. Open the community that represents you for your AS4 exchanges.
Step 1: Create a user account on the AS4 pickup:
1. Open the community that represents you for your AS4 exchanges.
2. On the community graphic, click on the Trading pickup icon to open the Trading pickups
page.
3. From the list of pickups, click on the name of an AS4 pickup to open the maintenance page for
that pickup.
4. Click the Accounts tab.
5. Under the Partner table, click Add.
6. Click choose a party and from the popup page, select the partner from whom you want to
receive pushed AS4 files. Click OK.
7. Create a user for the selected partner by entering a username and password. Click Save.
Step 2: Set the Validation Rule for inbound AS4 messages:
1. Open the community that represents you for your AS4 exchanges.
2. On the community graphic, click on the Message validation icon to open the Configure
message validation rules page.
3. Select the Web services tab.
4. Select the option: Reject messages without user name and password within
UsernameToken in SOAP header
5. Optionally select the related option: Reject messages when password is plain text (not
digest)
An X.509 certificate specifies a binding between a public key and a set of attributes that includes (at
least) a subject name, issuer name, serial number and validity interval.
Note that an X.509 certificate may be used to validate a public key that may be used to authenticate
a SOAP message or to identify the public key with a SOAP message that has been encrypted. In the
case of user authentication, it is only the authentication function that must be activated.
Activate X.509 tokens in the AS4 Collaboration Settings:
1. Open the community that represents you for your AS4 exchanges.
2. On the community graphic, click on the Collaboration settings icon to open the Configure
community-specific collaboration settings page.
3. In the "Choose the settings to specialize:" section, select Set sending rules for the AS4
message protocol to display the AS4 enveloping options at the bottom of the page.
4. Select the option, Sign messages. Partners use your certificate to verify you as the
sender. Select a message signing algorithm (SHA1 or SHA256) from the drop-down box.
5. Click Save changes.
For additional AS4 Collaboration settings information, see AS4 default settings on page 918.
Set the Validation Rule for inbound AS4 messages:
1. Open the community that represents you for your AS4 exchanges.
2. On the community graphic, click on the Message validation icon to open the Configure
message validation rules page.
3. Select the Web services tab.
4. Select the option: Reject messages that are not authorized using X509 digital
signature defined within SOAP header
5. Click Save changes.
Splitting and joining operates only if the AS4 message has attachments or MTOM optimized content.
How it works
l Interchange sender:
In message sender role, Interchange splits large AS4 messages into multiple fragments,
wrapping each fragment in a separate message with a MessageFragment header element.
Interchange sends multiple AS4 messages to the trading partner for a single submitted source
AS4 message.
l Interchange receiver:
In message consumer role, Interchange detects the presence of a MessageFragment header
element in the inbound AS4 message. This indicates that the content of the fragment is part of a
larger message. On receiving fragment message, Interchange halts the processing until all
related fragments are received. When all the fragmented messages are received, Interchange re-
assembles them by parsing the MessageFragment header and reconstructing the MIME envelope.
Interchange then continues to process the re-assembled MIME message.
In the case of pulled AS4 split messages, each fragment is pulled individually. The pull request is
authorized for fragments using the same parameters as for regular AS4 messages.
Configure splitting
To set up AS4 message splitting and joining, complete the following tasks:
l Set the default fragment size in the Interchange System Properties
l Set Collaboration Settings
l Enable spitting in an AS4 MMD
The Systems properties page is displayed.
3. At the bottom of the page click Show default system properties.
4. Locate the following system properties in the list:
l as4.fragmentSize – Maximum size of a AS4/ebXML fragment (in kilobytes)
l as4.joinExpirationCheck.interval – Maximum time to wait for receiving/pulling
AS4 fragments for re-joining ( in minutes).
5. If you want to modify either of these values, click Add, enter a modified value and click Add
again. Then click Save changes on the System properties page.
For AS4 pushes, include the following attributes (using preferred values for size and compression):
...
<Metadata name="SplitMessage">true</Metadata>
<Metadata name="FragmentSize">5</Metadata>
<Metadata name="SplitCompressionAlgorithm">gzip</Metadata>
...
For outbound AS4 pull-queued messages, include the following attributes (using preferred values
for size and MPC):
...
<Metadata name="SplitMessage">true</Metadata>
<Metadata name="message.WaitForPull">true</Metadata>
<Metadata name="FragmentSize">5</Metadata>
<Metadata name="MessagePartitionChannel">http://testMPC</Metadata>
...
For additional details about metadata and MMD management, see AS4 metadata on page 503.
l An inbound SOAP Body contains no payload
l The inbound payloads are packaged as attachments
An equivalent case exists for Interchange WebServices exchanges. For both AS4 and for
WebServices the Interchange handling of messages with no payload in the SOAP Body is controlled
by the same system property, ws.allowEmptySOAPBody.
However it is important to note that the default behavior for WebServices and for AS4 messages is
not the same:
l For WebServices message consumption, the default setting of ws.allowEmptySOAPBody is
true.
l For AS4 message consumption, the default setting of ws.allowEmptySOAPBody is false.
So unlike configuration for WebServices, you must expressly activate the handling of empty
SOAP Body messages for AS4. To do this, you modify in the Interchange tuning.properties file.
The properties in this file are applied only to the node where the tuning.properties file is
located. You must set properties specified in this file for each node of a cluster by modifying the file
for each node.
By default, tuning.properties is empty. This indicates that all of its possible entries are
operating at their default values.
For an example of an AS4 pull server configuration, see AS4 use case: One-way pull (MMD initiated)
on page 529.
Prerequisites
In order to correctly configure an AS4 client pull transaction, you must have a formal agreement of
how you will exchange AS4 messages with the pull server. This agreement includes:
l Message Partition Channel to use
l Security requirements
l Receipt requirements
l Reliable messaging
l Whether to support message splitting
l Scheduled pull – Scheduled pulls enable you to automatically poll remote server queues for
messages to consume, at periodic intervals and for fixed numbers of pulls per specified interval
of time.
l MMD-initiated pull – Message Metadata Document (MMD) initiated pulls enable you to initiate
a single remote server queue polling event by consuming a file from the back end system. This
back-end MMD initiation can be done manually, for example by depositing a file to a directory,
or may be the result of a programmed back-end system event that generates the MMD file.
On the Advanced tab you can set the following poll scheduling parameters:
l Create an AS4 MMD with pull request metadata. The following file is an example of an AS4 pull
request MMD:
In this example:
o SignalType = PullRequest
o The Message Partition Channel is explicitly specified. Each MPC is linked to a server queue, so
this attribute identifies both the partition channel to use, and the queue to poll.
l Configure Interchange to consume AS4 MMDs from the back end network. One way to do this is
with a file system type application pickup. See Add an application pickup on page 161.
l Configure Interchange to generate the AS4 pull request signal message from the MMD. To do
this you configure Collaboration Settings (see AS4 default settings on page 918) and create an
AS4 server Delivery (see Add an AS4 trading delivery on page 533).
l Configure Interchange to correctly handle the packaging and receipt requirements you have
established with your trading partner (AS4 pull server).
The following figure illustrates an example of a pull-request processing sequence initiated by a back-
end MMD.
In this figure the following events occur:
1. Interchange consumes an AS4 MMD from the back-end file system.
2. Interchange message handler analyzes the MMD and detects that it is an AS4 pull request.
3. Interchange applies AS4 collaboration settings and builds and packages the outbound AS4
signal message.
4. Interchange sends the AS4 pull request signal message to the server using the partner AS4
delivery exchange.
5. The remote server receives the pull request. It checks the sender, receiver and MPC that are
specified in the pull request, and if it finds a match, and if there are any queued messages in the
corresponding queue, the server returns the first queued AS4 user message.
6. If receipts are expected by the sender of the user message, and if "Generate receipts" is enabled
on the AS4 trading pickup referenced by AS4.ResponseProcessingExchangePoint metadata in
PullRequest MMD, then synchronous receipts are generated.
Security options
In the Community Collaboration Settings, you can select several security options for packaging and
sending AS4 messages:
l Encrypt messages — Interchange supports Triple DES and AES (128, 192, 256 bit)
encryption algorithms for AS4 trading. On the receiving partner side, the encryption
requirements are controlled in the Message Validation Rules (see Validation rules: Encryption tab
on page 942).
l Sign messages — Interchange supports SHA1 and SHA256 signing algorithms for AS4 trading.
On the receiving partner side, the signing requirements are controlled in the Message Validation
Rules (see Validation rules: Signing tab on page 941).
l Use username token when sending — Select this option to enable the use of username
tokens to authenticate the sender of the PullRequest on the receiver side. After the sender of the
Pullrequest is authenticated on the server side, the sender may be authorized (based on MPC in
the PullRequest) to consume user messages queued for him.
If you select this option you must provide the required user name and password.
You can optionally select to use a password digest in place of plain text during authentication.
For additional information, see the Collaboration Settings section: AS4 default settings on page
918.
For additional information on user authentication and username tokens, see AS4 user authentication
on page 518.
This is a feature that is configured on the AS4 Server side, enabling the server to make multiple
attempts to respond to client pull request, in the event of a user message delivery failure in response
to a pull request.
This topic describes the configuration of both the sending and receiving participants on
Interchange platforms.
Assumptions
l The sending and receiving partners have agreed on a common configuration for partition
channel, security and acknowledgements.
Processing events
The following figure illustrates the sequence of transfer events.
In this figure the following events occur:
1. Interchange consumes an ebMS V3 MMD from the back-end file system.
2. Interchange message handler analyzes the MMD and detects that it is an AS4 type.
3. Interchange applies AS4 collaboration settings and builds and packages the outbound AS4 user
message. This includes any message payloads that are specified in the MMD.
4. Interchange sends the AS4 user message using the partner AS4 delivery exchange.
5. The remote partner receives the AS4 message and returns a receipt in the form of an AS4 signal
message.
6. Interchange consumes the inbound receipt over the synchronous connection.
1. Create an MMD to use to initiate the AS4 push.
See AS4 metadata on page 503.
2. Add a Community to specify characteristics of Interchange as the sending AS4 exchange
participant.
See Add a community on page 136.
3. Add a Partner to specify the characteristics of the remote partner as the receiving participant.
See Add a partner on page 143.
4. Add a file system type Application Pickup to enable the Community to consume the AS4
MMD from the back end.
See Add an application pickup on page 161.
5. Configure Community AS4 collaboration settings to control the packaging of the AS4 outbound
user message. In this case we select the option "Expect receipts from partners". When we do
this, the push receiving partner must also activate receipts.
See AS4 default settings on page 918.
6. Add a Partner AS4 delivery to enable the connection to the receiving partner.
See Add an AS4 trading delivery on page 533.
1. Add a Community to specify characteristics of Interchange as the receiving AS4 exchange
participant.
See Add a community on page 136.
2. Add a community AS4 pickup to enable the reception of the pushed AS4 user message.
See Add an AS4 embedded server pickup on page 538.
3. Modify the AS4 pickup to enable receipts. On the maintenance page Advanced tab you must
select the option: Generate receipt.
See Modify an AS4 embedded server pickup on page 539.
4. Configure Validation Rules to control how Interchange consumes the AS4 pushed user
message.
5. Add a Partner to specify the characteristics of the original sending participant in this exchange.
See Add a partner on page 143.
Assumptions
l The receiving (pulling) and sending p artners have agreed on a common configuration for
message partition channel, security and receipts.
This feature assures that the AS4 polling queues get cleaned up, however you should be aware of
your backup purge threshold setting to avoid unwanted message loss.
To view or modify automated Interchange purge settings, see Configure automated Interchange
purge on page 862.
Processing events
The following paragraphs describe the sequence of events for a simple AS4 pull, with an AS4
message generated on the server from a consumed MMD, and the pull initiated from a client through
a scheduled polling.
In this figure the following events occur:
1. Interchange consumes an ebMS V3 MMD from the back-end file system.
2. The Interchange message handler analyzes the MMD and detects that it specifies a client-
requested AS4 message pull.
3. Interchange builds an AS4 user message with the specified payload and queues the message in
"Waiting for poll" status, for consumption by a remote AS4 trading partner. The message is now
available for pulling by a partner in client mode.
1. The remote trading partner generates an AS4 pull request to poll the AS4 server message queue
that is associated with the agreed upon AS4 MPC.
2. The client pulls queued messages.
3. The pulling partner generates a receipt for the reception of the AS4 user message and payload,
and sends the receipt to the server.
4. The server checks the AS4 receipt message against the AS4 validation rules.
1. Create an MMD to use to generate an AS4 user message on the server in the client's pull queue.
See AS4 metadata on page 503.
2. Add a Community to specify characteristics of Interchange as the AS4 pull server.
See Add a community on page 136.
3. Add a file system type Application Pickup to enable the Community to consume the AS4
MMD from the back end.
See Add an application pickup on page 161.
4. Add a Community AS4 embedded-server trading pickup to enable Interchange to act in server
mode for the AS4 pull.
See Add an AS4 embedded server pickup on page 538.
5. Configure Community AS4 collaboration settings to control the packaging of the AS4 outbound
user message. For this use case, be sure to set the option "Expect receipts from partners".
See AS4 default settings on page 918.
6. Add a Partner to specify the characteristics of the remote AS4 pull client partner.
See Add a partner on page 143.
7. Add a Partner AS4 delivery to authorize the sender of the PullRequest on specified MPC. When
you create the partner you must specify:
l The URL the partner must use to connect to the server.
l The MPC that is agreed between the server and client for AS4 message exchanges.
l Any security packaging that must be used.
See Add an AS4 trading delivery on page 533.
8. Configure Validation Rules to control how Interchange consumes the AS4 polling request.
1. Add a Partner to specify the characteristics of the remote AS4 server that you are polling. This is
also the partner to whom you will send the receipt.
See Add a partner on page 143.
2. Add a Partner AS4 delivery to specify the connection URL and MPC for the client's polling
connection.
You can have multiple AS4 deliveries for the connection to the polling server. This is useful, for
example, if the server uses multiple MPC values and you want to be able to create a connection
for more than one of those values.
When you create the partner you must specify:
l The URL the partner must use to connect to the server.
l An MPC that is agreed between the server and client for AS4 message exchanges.
l Any security packaging that must be used.
See Add an AS4 trading delivery on page 533.
3. Optionally, modify the AS4 Partner delivery you created in the previous step to change or
further specify the connection parameter.
See Modify an AS4 trading delivery on page 534.
4. Add a Community to specify characteristics of Interchange as the AS4 pulling exchange
participant.
See Add a community on page 136.
5. Add a Community AS4 polling pickup to enable participant to poll the remote server for queued
AS4 messages. When you configure this pickup, you must specify:
l The URL to use for the connection to the server.
l The MPC to use for the AS4 message transfers.
l The polling frequency and number of requests permitted per frequency cycle.
See Add an AS4 polling client pickup on page 541.
6. Modify the AS4 pickup to enable receipts. On the maintenance page Advanced tab you must
select the option: Generate receipt.
See Modify an AS4 polling client pickup on page 543.
7. Configure Validation Rules to control how Interchange consumes the AS4 pulled user message.
AS4 tasks
This section contains the following AS4 specific task descriptions:
l Add an AS4 trading delivery on page 533
l Modify an AS4 trading delivery on page 534
l Add an AS4 embedded server pickup on page 538
l Modify an AS4 embedded server pickup on page 539
l Add an AS4 polling client pickup on page 541
l Modify an AS4 polling client pickup on page 543
l Manage AS4 polling queues on page 545
click Encode the URL becomes http://foo.com/foo%3D%20%20bar.
l Message Partition Channel (MPC) – The Message Partition Channel(MPC) is a required
attribute of any AS4 message exchange. MPCs enable the partitioning the flow of messages
from a sending participant a receiving participant, into several flows that can be controlled
separately and consumed differently. They also allow for merging flows from several
sending participants, into a unique flow that will be treated as such by a receiver.
In this field, you can specify the MPC to use for AS4 message deliveries to this partner.
This value is used both for a final push configuration option and for secondary pull
authorization checks.
If the MPC value has already been set in the metadata (for example by a Message Attributes
Template), the pre-set metadata value will override any value you set in this field.
If you do not specify an MPC in this field, and there is no preset metadata value, the default-
implicit (empty) MPC is selected.
For details about MPCs, see Message Partition Channels (MPC) on page 515.
l Clients must use SSL to connect to this server – Select this option to have Secure
Sockets Layer protocol in use during connections. The server presents a certificate for
verification. To do this, a certificate assigned to a partner must be designated as the SSL
certificate. The server must support SSL. If this option is not selected, connections are not
encrypted.
o Enable host name verification – Select this additional SSL option if you want
Interchange to compare the name of the SSL server to the name in the server’s
certificate, to ensure that they are the same.
See Modify an AS4 trading delivery on page 534.
the object, and can only be modified after you add the object.
Procedure
1. In the Interchange user interface, from the Partners menu select Manage partners.
2. From the list of partners, click the name of a partner to display the Summary page for that
partner.
3. Click Partner delivery in the navigation graphic to open the Partner deliveries page.
4. From the list of available deliveries, click the name of an AS4 d elivery to open the maintenance
page for the delivery.
5. View and modify fields as required. The fields are described in the following section.
6. If you make any changes, click Save Changes.
Advanced tab
l Maximum concurrent connections – The number of total open connections Interchange can
make to a partner. If you are operating in a cluster environment, this is the total number across
the entire cluster, no matter how many JVM nodes are running. For example, if the value is 100
connections and there are 150 messages to send, Interchange opens only 100 connections to
that partner. The remaining 50 messages are queued until connections become available. The
default value is suitable in almost all cases. However, if a partner says your Interchange is
overrunning his receiving system, decrease the value. (This advice does not apply to OFTP X.25
or X.25 over ISDN, as the default maximum value is 1 for those transports.) If sending messages
to Transfer CFT via PeSIT, the value in this field must be less than the CFTTCP setting in Transfer
CFT. This setting applies only to transports that send messages to partners or deliver messages to
integration.
l Retries – This is the number of times Interchange tries to connect to the partner’s transport if
the initial attempt to connect and send the message failed. The following are common reasons
for triggering retries:
o The connection attempt failed immediately for a specific reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note: In the last case above, the 200 OK response also includes the receipt if
synchronous receipts were requested. Otherwise, it will be a simple 200 OK response
with no payload. And if an asynchronous receipt was requested, the partner will
connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between
retries increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30
minutes, 60 minutes. The interval plateaus at 60 minutes. This means if the retry value
is greater than 5, the fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second
retry in 10 minutes. The third retry attempt is made 15 minutes later. If the third retry
attempt fails, the message is given a failed status. So after four attempts (the first
attempt plus 3 retries), the message fails. You can search for and manually resubmit
failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes
some seconds, which varies by computer. So retries actually occur after the connection
attempt time plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to
retrying to send related to transport issues. It does not apply to successfully sent
messages for which receipts have not been received as expected. Another control,
resends, determines how many times the system will resend a message when a receipt is
not received from the partner. For information about resends, see reliable messaging in
the collaboration settings chapter.
The checkpoint files are saved on the server under the <install
directory>/common/data/http/restartable, which is normally common to all nodes in
the cluster. Thus, if a transfer is interrupted and the load balancer directs the restart request to a
different node, the restart file will be accessible to the new node even though it did not process
the original request.
To reduce unnecessary overhead when processing small files, checkpoint files are only created
for messages that are at least 100 KB in size. Also, if a restart is attempted for a message whose
checkpoint file on the server is more than four hours old, the checkpoint file will be discarded
and the entire message will be retransmitted.
The restart logic is used only during transport retries, such as might occur when a transfer is
interrupted due to network problems. If you resubmit a message in Message Tracker, no attempt
is made to perform a checkpoint-restart.
This feature only works if your partner uses Interchange and its embedded HTTP server. Do not
select this option if a partner uses an external or staged HTTP server or uses a trading engine
other than Interchange.
l Enable use of 102-processing – This option is available to ensure that the connection
between the client and server does not become idle and fail while message processing is in
progress. For example, this makes sure the connection remains active when the client is sending
a multi-gigabyte message. Or, to prevent a firewall from disconnecting an idle connection before
the server receives the entire message and returns a 200 OK response. Most often this setting is
useful when the client requests a synchronous receipt, but also could be recommended in some
cases for an asynchronous receipt.
Selecting this option directs Interchange to add the following to the header of an outbound
message: Expect: 102-processing. This is an HTTP response code that indicates processing
is in progress. If the receiving server supports 102 responses, the header triggers the server to
send 102 responses to the client repeatedly until the server has completely processed the
inbound message.
Before selecting this option, make sure the server supports 102 responses. If you turn on 102
processing and the server does not support it, the server will return a 417 message (the server
could not meet the expectation given in the Expect header) and the connection may fail. If the
receiving partner uses the embedded HTTP server in Interchange 5.5.1 or later, 102 responses
are supported. This also is supported if your partner uses Jetty 6 or later.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners. Backing up files is
required for the system to perform fail-over operations such as attempting to send messages
again (retries) in case of a transport connection failure. Without backups, a message in process
cannot be recovered if the server or a processing node stops or restarts. Backups are needed to
resubmit messages to back-end applications or resend messages to partners. Backup files are
stored in \<install directory>\common\data\backup, unless you specify otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for community integration delivery exchanges and partner
trading delivery exchanges.
Prerequisite
You must have at least one community. To add a community, see Add a community on page 136.
Procedure
1. From the menu bar select Trading configuration to open the Communities page.
2. Click the name of the community to which you want to add the AS4 pickup.
3. In map graphic, click the Trading pickup icon to open the Trading pickups page.
4. Click Add a pickup to open the exchange wizard.
5. On the Choose message protocol page, select AS4 (HTTP) and click Next.
6. On the Choose HTTP transport type page, select Use the system's global embedded
HTTP server and click Next.
7. On the Configure URL page, complete the URL that you want to expose to partners. Partners use
this URL to connect and send AS4 messages to your community. The default routing ID of the
community is supplied as a suggested value.
8. Click Next.
9. On the Exchange name p age, enter a meaningful name for the pickup. This is the name that is
displayed to identify the pickup in the UI.
10. Click Finish.
See Modify an AS4 embedded server pickup on page 539.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
3. Click Trading pickup in the navigation graphic to open the community's Trading pickups
page.
4. From the list of available pickups, click the name of an AS4 (embedded) pickup to open the
maintenance page for that pickup.
5. View and modify fields as required. The fields are described in the following section.
6. After making any modifications, click Save changes.
The Local URL field displays the local port and path the embedded HTTP server uses. A server starts
on each computer in the cluster using this information. If you have only one computer, only one
server is started.
Accounts tab
Use the settings on this tab to create accounts to provide name and password information for the
use of user-name tokens in the SOAP headers of AS4 messages that you consume.
You can create two different types of users on this tab:
l AS4 user – This is an account that globally represents an AS4 remote trading partner. This is not
limited to a specifically-defined remote partner. For security reasons it is generally preferable to
use the Partner user account, below.
l Partner user – This is an account that specifies the authentication information of a specific user
account of a remote trading partner.
You can use either account type to provide a user-name token in an AS4 message you send.
To create a new Partner account:
1. Under the Partner table, click Add.
2. In the text box. click the text "click choose a party" and from the popup page, select the partner
from whom you want to receive pushed AS4 files. Click OK.
3. Create a user for the selected partner by entering a username and password. Click Save.
To create a AS4 (global community) account:
1. Under the AS4 table, click Add.
2. Click Create a new user.
3. Enter a username and password. Click Save.
Advanced tab
Use the settings on this tab to specify how to process the inbound messages that you consume
through this pickup.
Header section:
l Parse SOAP headers into message metadata – Select this option if you want SOAP
headers to be carried as metadata attributes with the message.
l XPath reference to SOAP header to parse – If you selected the previous option (Parse
SOAP headers into message metadata), enter an XPath expression to resolve the header.
Click Add to display the Local XPath field and then enter an XPath expression. Enter any legal
XPath expression. Xpath wildcard syntax is permitted. If the expression resolves to more than
one node, only the value of the first matching node is included in the metadata value.
l Generate receipt – You must select this option if the sending participant is expecting AS4
receipts. If the sending participant expects receipts but you do not select this option, the
message exchange will fail and a receipt failure message will be written to the TE.LOG or to
Message Tracker of the AS4 user message sender.
o Synchronous response generated in back end – Select this option to have the back-
end application generate synchronous responses.
If this option is not selected, the synchronous response is generated within Interchange. By
default, this option is not selected.
If this option is selected, Interchange keeps the inbound HTTP connection open so a
synchronous response can be built by the back-end system. The response built by the
backend uses the message ID that was generated by the inbound AS4 user message, to send
back the response in the form of a receipt. Once Interchange receives it, the response is
packaged and sent over the open HTTP connection.
If selected, you must create a receipt or error MMD for Interchange to pick up from the
backend.
Prerequisite
You must have at least one of each of the following objects:
l Community - To add a community, see Add a community on page 136.
l Partner – To add a partner, see Add a partner to a community on page 148.
l Partner AS4 trading delivery, see Add an AS4 trading delivery on page 533.
Procedure
1. From the menu bar select Trading configuration to open the Communities page.
2. Click the name of the community to which you want to add the AS4 pickup.
3. In map graphic, click the Trading pickup icon to open the Trading pickups page.
o If you leave this field blank, the MPC on the selected partner delivery exchange is
applied for the exchange. If the partner delivery exchange MPC field is also empty, then
the default-implicit (empty) MPC is applied for the exchange.
o If you enter the default-explicit MPC, this default MPC is applied for the exchange.
(Default is http://docs.oasis-open.org/ebxml-
msg/ebms/v3.0/ns/core/200704/defaultMPC).
o If you enter an alternative MPC identification, the alternative is applied for the
exchange.
9. Click Next.
10. On the "Exchange name" page, enter a meaningful name for the pickup.
11. Click Finish.
See Modify an AS4 polling client pickup on page 543.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
3. Click Trading pickup in the navigation graphic to open the community's Trading Pickups
page.
4. From the list of available pickups, click the name of an AS4 (polling) pickup to open the
maintenance page for that pickup.
5. View and modify fields as required. The fields are described in the following section.
6. After making any modifications, click Save changes.
o If you enter the default-explicit MPC, this default MPC is applied for the exchange. (Default is
http://docs.oasis-open.org/ebxml-
msg/ebms/v3.0/ns/core/200704/defaultMPC).
o If you enter an alternative MPC identification, the alternative is applied for the exchange.
Advanced tab
User message processing
Header section:
o Group attachments – Select this option take the attachments of the original message
(after they were split into separate messages) and enter them as attributes (metadata) of the
SOAPBody.
Processing section:
l Generate receipt – Select this option if you want to generate receipts for messages that are
pulled from the remote partners polling queue.
l Restrict maximum file size for this transport – Optionally specify the maximum size of
files that this transport can handle, per message pull. If Interchange receives a file larger than the
maximum, the file is rejected and a message is written to the events log.
Pull request processing section:
l Maximum pull requests per polling interval – The highest number of pull requests per
polling interval, that the community can send to retrieve messages that are queued in the AS4
polling queue on the partner server. The polling interval is set in the field below.
l Polling interval (seconds) – (Default = 60) The interval, in seconds, Interchange waits
between polling actions for messages to retrieve.
This feature assures that the AS4 polling queues get cleaned up, however you should be aware of
your backup purge threshold setting to avoid unwanted message loss.
To view or modify automated Interchange purge settings, see Configure automated Interchange
purge on page 862.
ebXML
The following topics provide information about trading messages via the ebXML message protocol.
ebXML overview
ebXML, sponsored by UN/CEFACT and OASIS, is a modular suite of specifications that enables a
company located anywhere to conduct business over the Internet. ebXML embodies the definition
and registration of processes for exchanging business messages, conducting trading relationships
and communicating data in common terms.
Interchange supports the Collaboration-Protocol Profile and Agreement Specification 2.0, available
at http://www.oasis-open.org/committees/ebxml-cppa/documents/ebcpp-2.0.pdf. The supported
CPA schema is: http://www.oasis-open.org/committees/ebxml-cppa/schema/cpp-cpa-2_0.xsd.
Your organization must have a thorough understanding and working knowledge of ebXML to
successfully trade documents using this message protocol. For information about ebXML see
www.ebxml.org or www.oasis-open.org. Books about ebXML also are available commercially.
The CPA represents a contract between two parties defining how they trade ebXML messages.
Interchange takes directions from the CPA, such as the transport to use for sending messages and
whether outbound messages are signed and encrypted. Interchange also enforces the signing and
encryption requirements in the CPA for inbound messages.
1. The back-end system produces metadata and a payload. The metadata identify the CPA to use
for packaging the outbound message.
2. Interchange receives or acquires the message. The way this is accomplished depends on the
integration method. For instance, if file system integration is used, Interchange polls the back-
end file system. If a message metadata document (MMD) is present, it retrieves the MMD. The
MMD tells Interchange where to poll on the file system to retrieve the payload. MMDs, which are
metadata carriers, are explained in ebXML message metadata documents (MMDs) on page 552.
Multiple payloads might accompany the same metadata. If so, Interchange keeps track of all
payloads and relates them to the same metadata. (Multiple payloads are not supported when
JMS is the integration method for outbound messages.)
3. Interchange validates the metadata against the CPA the metadata identifies.
4. Interchange collaboration manager uses the CPA the metadata identifies to build the binary
collaboration rules for packaging and sending the ebXML message to a partner. Packaging
usually involves encrypting and signing the message. The collaboration settings in Interchange
user interface are not used.
5. Interchange sends the message. This is a SOAP message, consisting of a SOAP header
containing collaboration metadata and a payload attachment. If multiple payloads were
received from integration, a single SOAP message is produced, with each payload as an
attachment in the message.
6. When reliable messaging is engaged in the CPA, Interchange receives a receipt acknowledging
that the partner received the message. Interchange checks the receipt against the CPA to see
whether an acknowledgment was requested and whether the receipt conforms to the CPA (for
example, the CPA might require signed receipts). Interchange matches the receipt with the
outbound message and marks the message as delivered.
If the outbound message had multiple payloads, Interchange associates the same receipt to all
payloads, which appear as separate records in Message Tracker.
The receipt is a message handler signal and is not produced to the back-end system.
1. Interchange receives a SOAP message from a partner. The message has collaboration metadata
and one or more payload attachments. The metadata identify the CPA to use for this payload.
2. Interchange validates the message against the CPA identified in the inbound message. For
example, if the CPA requires, Interchange determines whether the message is a duplicate to one
received earlier. If the message is a duplicate, Interchange re-sends the earlier transmitted
receipt to the partner, but does not produce the message again to the back-end system.
Interchange also determines how many payloads are in the message. If there are multiple
payloads, Interchange keeps track of all payloads and relates them to the same metadata.
3. If the CPA requires reliable messaging, Interchange sends the partner a receipt that
acknowledges the message has been received. If the inbound message had multiple payloads,
Interchange associates the same receipt to all payloads, which appear as separate records in
Message Tracker.
4. Interchange sends the payload to a back-end system via an integration transport. Depending on
the transport, Interchange might produce metadata for the payloads. See Supported ebXML
application transports on page 558.
Metadata are exchanged between Interchange and a back-end system via the following application
transports:
l JMS (inbound and outbound)
l File system (outbound)
l File system with message metadata (inbound)
l Web services API server (outbound)
l Web services API client (inbound)
Supported ebXML application transports on page 558 explains the role of these transports in more
detail.
These elements are listed in the correct format. When using metadata elements, make sure to use
the proper case.
For a broader list of elements and more information about metadata, see Message metadata and
attributes on page 412.
l AckRequested – Indicates whether a partner is asked to send a receipt upon receiving the
message. Valid values are true and false. This element can be set per message.
l AckSignatureRequested – If AckRequested is true, this indicates whether the partner is asked
to sign the receipt. Valid values are true and false. This element can be set per message.
l Action – Identifies an action within a Service that processes the message. The Action must be
unique within the Service in which it is defined. The Service designer defines the value of the
Action element.
l ConversationId – A string identifying all consecutive messages belonging to the same
collaborative business process instance. This is useful for monitoring and auditing purposes.
l CPAId – Identifies the CPA that governs the collaboration between the trading parties. This
matches the CPA ID in the CPA, not the name of the CPA XML file.
l DuplicateElimination – Indicates whether the receiving message service handler should
accept or reject duplicate messages. Valid values are true and false. This element can be set per
message.
l ebXML.Ack – A message service level acknowledgment message.
l ebXML.AsyncMshSignal – Indicates that the ebXML message service level signal is used
asynchronously.
l ebXML.DigestAlgorithm – Defines the algorithm for computing the digest of the message.
l ebXML.EncryptionRequested – Indicates whether the message must be encrypted.
l ebXML.Error – Used for an ebXML message service level error message.
l ebXML.Fault – Used for an ebXML message service level fault message.
l ebXML.IsSyncResponse – Indicates a synchronous response.
l ebXML.MshSignalType – Indicates the type of the message service level message.
l ebXML.Payload.Description – The description for a payload. This attribute is optional.
Multiple descriptions are supported. Each description key name should end with an index
number. For example: ebXML.Payload.Description1, ebXML.Payload.Description2,
ebXML.Payload.Description3, and so on.
l ebXML.Payload.DescriptionLang – The language of the description for a payload. This
attribute is required if a Description is included, but do not use if there is no Description. Multiple
description languages are supported. Each description language key name should end with an
index number. For example: ebXML.Payload.DescriptionLang1,
ebXML.Payload.DescriptionLang2, ebXML.Payload.DescriptionLang3, and so on.
l ebXML.Payload.SchemaLocation – The location of the schema for a payload. This attribute
is optional.
l ebXML.Payload.SchemaVersion – The version of the schema for a payload. This attribute is
optional if schema location is used. If schema location is not used, do not use.
l ebXML.Ping – Used for a message service level ping message. On success, a pong message
service level message must follow.
l ebXML.Pong – Used for a message service level pong message. A pong message must be sent
after having received a ping message service level message.
l ebXML.ReceiveAction – Indicates the action taken.
l ebXML.SignalType – Sets the message service level action of the message. The action can be
an acknowledgment, error, message status request.
l ebXML.SigningRequested – Indicates whether the ebXML message must be digitally signed.
l ebXML.StatusRequest – Used to make a request about a previous ebXML message.
l ebXML.StatusResponse – The response to a request about a previously sent ebXML message.
l ebXML.StatusResponse.RefToMsgId – References the message the requesting message
service level message was inquiring for status.
l ebXML.SyncMshSignal – Indicates the message service level signal is used synchronously.
l FromRole – The role of the sending party.
l Hl7Version – Indicate the version of the HL7 message.
l IsHl7 – Indicates the payload is an HL7 message.
l IsStarBOD – Set to true for business object documents (BODs) that conform to Standards for
Technology in Automotive Retail (STAR). Otherwise, set to false. See STAR BODs with ebXML on
page 574.
l MessageId – A unique identifier for a message that conforms to RFC 2822.
l ProcessSpecName – Defines the underlying business process specification.
l ProcessSpecUUID – Unique identifier of the BPSS ProcessSpecification.
l ReceiverRoutingIdType – The ebXML party ID type of the message receiver.
l RefToMessageId – When present, this must have a MessageId value of an earlier message to
which this message relates. If there is no related earlier message, this element must not be used.
l SenderRoutingIdType – The ebXML party ID type of the message sender.
l Service – Identifies the collaborative business process. This can be bound to a service in back-
end integration.
l ServiceType – An option of the Service element, it is required only when the trading partners
require a type to properly identify the service. If the Service is not a URI, a type must be
specified.
l SyncReply – Indicates whether a response is used (such as a message level acknowledgment of
a message for reliable messaging purposes). For example, instead of returning an HTTP code of
200 indicating success of a received ebXML message and then opening a new connection to
send the message level acknowledgment back, the message level acknowledgment is sent over
the same HTTP connection. The value of SyncReply can be true or false.
l TimeToLive – If used, this indicates the time, expressed as universal time, that a message must
be delivered. This attribute is optional.
l ToRole – The role of the receiving party. Indicates the role the party is playing in the business
transaction, such as the seller role.
MMD only
The following ebXML metadata elements are used only in message metadata documents.
l RemovePayloadAfterProcessing – Indicates (true or false) whether Interchange deletes the
payload from the file system after processing the message. (MMDs always are deleted after
processing.) Use of this element is optional. If not used, the payload is not deleted, which is the
same behavior as using the element with a value of false. If RemovePayloadAfterProcessing is
true, payloads are deleted after being picked up. This also works for the resubmit case in which
payloads are retrieved from the backup directory. This element only is for use in MMDs for
outbound messages.
l PayloadLocation – The directory path to the document.
l PayloadLocationType – The path and file name of the payload. Payloads can be on a file
system or an HTTP or FTP server, as the following examples illustrate:
File system
<Location type="filePath">C:\smallxmlPO.xml</Location>
HTTP
<Location type="xs:anyURI">http://www.oasis-
open.org/committees/ebxml-cppa/schema/cpp-cpa-2_
0.xsd</Location>
FTP
<Location type="xs:anyURI">ftp://acme:acme@cfoster-
dell.cyclonecommerce.com:4021/mailbox/foo.dat</Location>
In the FTP example, acme:acme in the URL represents the user name and password for
connecting to the FTP server. Note: using an e-mail address as the password is not supported.
l PayloadMimeContentId – An identifier of the payload content.
l PayloadMimeContentType – The MIME type of the payload. For example, application/xml.
AckRequested Optional
AckSignatureRequested Optional
Action Optional
ConversationId Optional
CPAId Optional
DuplicateElimination Optional
FromRole Required
MessageId Optional
PayloadLocation MMD only
PayloadLocationType MMD only
PayloadMimeContentId MMD only
PayloadMimeContentType MMD only
ProcessSpecName Optional
ProcessSpecUUID Optional
RefToMessageId Optional
Service Optional but recommended for reliable performance
ServiceType Required only if Service is specified and it is not a URI.
TimeToLive Optional
ToRole Required
MMDs are used only with back-end file system exchanges, although the same type of metadata are
transported when application transports such as JMS or web services API are used.
MMD example
The following is an example of an MMD associated with an ebXML document. Interchange generates
MMDs for the ebXML documents that it sends to a back-end system. Your back-end system must
generate the MMDs for the ebXML documents that Interchange retrieves from the back end. The
metadata elements of the MMD are defined in ebXML message metadata on page 548.
</MessagePayloads>
</MessageMetadataDocument>
You can send a ping MMD to check network connectivity and the operational status of your and
your partner’s systems. The receiver sends a pong response if all is well.
In Message Tracker on page 826 a ping is reported as a payload and a pong as a receipt. You can
confirm a ping or pong by viewing the message contents.
Ping
The first example is the ping message sent by PartnerA.
Content-Type: text/xml
SOAPAction: "ebXML"
Content-Length: 1637
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/
http://www.oasis-
open.org/committees/ebxml-msg/schema/envelope.xsd">
<soap:Header xmlns:eb="http://www.oasis-open.org/committees/ebxml-
msg/schema/msg-header-
2_0.xsd" xsi:schemaLocation="http://www.oasis-open.org/committees/ebxml-
msg/schema/msg-header-
2_0.xsd http://www.oasis-open.org/committees/ebxml-msg/schema/msg-
header-2_0.xsd">
<eb:MessageHeader eb:id="ID6572235551131040785875coronation"
eb:version="2.0"
soap:mustUnderstand="1">
<eb:From>
<eb:PartyId
eb:type="string">PartnerA</eb
:PartyId>
</eb:From>
<eb:To>
<eb:PartyId
eb:type="string">PartnerB</eb
:PartyId>
</eb:To>
<eb:CPAId>PartnerA-PartnerB-cpa-
1</eb:CPAId>
<eb:ConversationId>ab102b17-4724-4ecb-8572-
8dc050a0f1a7</eb:ConversationId>
<eb:Service>urn:oasis:names:tc:ebxml-
msg:service</eb:Service>
<eb:Action>Ping</eb:Action>
<eb:MessageData>
<eb:MessageId>M1131040785868.
792@
coronation7786261718245588383
</eb:MessageId>
<eb:Timestamp>2005-11-
03T17:59:45.868Z</eb:Timestam
p>
</eb:MessageData>
</eb:MessageHeader>
</soap:Header>
<soap:Body xmlns:eb="http://www.oasis-open.org/committees/ebxml-
msg/schema/msg-header-2_0.xsd"
xsi:schemaLocation="http://www.oasis-open.org/committees/ebxml-
msg/schema/msg-header-2_0.xsd
http://www.oasis-open.org/committees/ebxml-msg/schema/msg-header-2_
0.xsd"/>
</soap:Envelope>
Pong
The second example is the pong reply from PartnerB.
<soap:Header xmlns:eb="http://www.oasis-
open.org/committees/ebxml-msg/schema/msg-header-
2_0.xsd" xsi:schemaLocation="http://www.oasis-open.org/committees/ebxml-
msg/schema/msg-header-
2_0.xsd http://www.oasis-open.org/committees/ebxml-msg/schema/msg-
header-2_0.xsd">
<eb:MessageHeader
eb:id="ID268087701131040580929gnaraloo"
eb:version="2.0"
soap:mustUnderstand="1">
<eb:From>
<eb:PartyId
eb:type="string">PartnerB</eb
:PartyId>
</eb:From>
<eb:To>
<eb:PartyId
eb:type="string">PartnerA</eb:PartyId>
</eb:To>
<eb:CPAId>PartnerA-PartnerB-cpa-
1</eb:CPAId>
<eb:ConversationId>ab102b17-4724-4ecb-8572-
8dc050a0f1a7</eb:ConversationId>
<eb:Service>urn:oasis:names:tc:ebxml-
msg:service</eb:Service>
<eb:Action>Pong</eb:Action>
<eb:MessageData>
<eb:MessageId>M1131040580919.
411688@
gnaraloo8174619434348129230
</eb:MessageId>
<eb:Timestamp>2005-11-
03T17:56:20.919Z</eb:Timestam
p>
<eb:RefToMessageId>
M1131040785868.792@coronation7786261718245588383
</eb:RefToMessageId>
</eb:MessageData>
</eb:MessageHeader>
</soap:Header>
<soap:Body xmlns:eb="http://www.oasis-
open.org/committees/ebxml-msg/schema/msg-header-2_0.xsd"
xsi:schemaLocation="http://www.oasis-open.org/committees/ebxml-
msg/schema/msg-header-2_0.xsd
http://www.oasis-open.org/committees/ebxml-msg/schema/msg-header-2_
0.xsd"/>
</soap:Envelope>
The following figure is an example of a StatusRequest MMD. To use this MMD, you must provide an
ebXML message ID as the value of the StatusRequest element near the top of the MMD. You also
must provide your own values for From, To and CPAId.
A StatusRequest MMD follows. Note that the second line ("StatusRequest") contains the message
ID.
<Payload id="01234">
<MimeContentId>XmlPo</MimeContentId>
<MimeContentType>application/xml</MimeContentType>
<Schema location="http://schema.com/po.xsd" version="1.0"/>
<Description language="en-GB">xmlpo</Description>
For inbound messages the Schema and Description values are copied from the message and
included as message metadata. In addition, for an inbound message where an MMD is created, the
MMD message in Message Tracker contains the description and schema metadata of the first
unpackaged payload.
In an MMD for an outbound message the Payload element can contain multiple Description elements
but only one Schema element. The Schema element has two attributes: location, which is a URL,
and version. The Description element has a language attribute. The Description element text
should contain the actual description.
Once an MMD with these elements has been parsed, Interchange reports the metadata as follows.
See ebXML metadata descriptions on page 548 for more information.
l ebXML.Payload.SchemaLocation
l ebXML.Payload.SchemaVersion
l ebXML.Payload.Description
l ebXML.Payload.DescriptionLang
For general information about creating adding trading pickups and deliveries see:
l Add a trading pickup on page 261
l Add a partner trading delivery on page 262
Note If you use embedded HTTP with client authentication (clients must use SSL to connect to
this server), the community default SSL client authentication certificate is used, not the
SSL certificate defined in the CPA. For more about SSL, see SSL authentication on page
775.
For more information about trading transports, see Community trading pickups and partner
deliveries on page 256.
When choosing application transports, decide what ebXML message metadata accompany the
payloads.
Normally a metadata element accompanying a picked-up payload provides the CPA ID (literally
CPAId) of the CPA to use. But Interchange can dynamically determine a CPA ID based on other
metadata. If, for example, the MMD for an outgoing ebXML message does not include the CPA ID,
the following metadata are used to find the correct CPA: Service, Action, FromRole, ToRole, From
and To. If two or more CPAs match these conditions, Interchange chooses the CPA with the most
recent Start date. However, if the MMD contains a ConversationId, Interchange selects the CPA used
for an earlier related document. This process is valid for any integration protocol.
The following topics describe the pickup and delivery integration options.
For more information about application pickups and deliveries, see:
l Application pickups on page 160
l Application deliveries on page 162
l File system – The metadata is contained in message metadata documents (MMDs). The MMD
contains a pointer to the location of the document to be sent to the partner. See ebXML message
metadata documents (MMDs) on page 552.
l JMS – The metadata must be set as JMS properties. The metadata are attached to the
BytesMessage containing the payload.
l Web services API server – The metadata are forwarded using the MessageService class. For
more information about this transport, see Web Services API pickup and delivery configuration
on page 200.
The only metadata items you need to specify are “from” or SenderRoutingId(type) and “to” or
ReceiverRoutingId(type) in the user interface. Use the From address or To address pages in the
exchange wizard or the From address and To address tabs on the exchange maintenance page.
The following figure shows an application pickup From address tab.
If you want to use this method, there are the following limitations:
l If a CPAId metadata item is not specified, Interchange looks up the default CPA for the given
sender and receiver. The default CPA is the first in the list of imported CPAs for a community, if
the sender and receiver have more than one.
l If the ToRole and FromRole metadata items are not specified, Interchange looks up the default
Role for the sender party (FromRole). From this Interchange determines the ToRole and the
Service. The default Role is the first in the list of roles, so this should be used with a CPA with
only one Role.
l If the Action is not specified, Interchange uses the default CanSend action in the FromRole.
If the CPA is complex with many Roles and Actions or a community has more than one CPA, the
“from” and “to” static metadata method is not recommended.
An alternative to setting up only the “from” and “to” address is to add more static metadata. With
this method, rather than having a back-end system generate message metadata, you can configure
any integration pickup transport to attach to every message metadata that you have defined.
For a list of the minimum name-value pairs, see Required, optional metadata for back-end
application integration on page 551.
To enable, you have to specify compression in the CPA Packaging element. Also, the CanSend and
CanReceive elements must reference the defined Packaging element. An example Packaging element
is shown in the following example: Elements in CPA to specify compression.
See Communities on page 134 and Add a community on page 136 for details not specific to ebXML
about setting up a community.
l The routing ID (party ID) must be a Universal Resource Identifier (RFC 1630). For example,
urn:myroutingid. When the routing ID is a URI, an ebXML party ID type is not necessary.
or
l When the routing ID (party ID) is not a URI, enter an ebXML party ID type in addition to a unique
routing ID. The ebXML party ID type can be any string (a URI, a DUNS number or something
else) and the routing ID can be any unique string. For example: urn:mystring 123456789.
The type value must match the PartyId /@type attribute value for the PartyInfo entry in the
CPA for the community.
The user interface lets you set up routing IDs either way.
Moreover, if you trade with the same partner using both ebXML and any other message protocol, the
community needs separate routing IDs for each protocol. The ebXML routing ID must not be the
default. The default must be the routing ID used for the other message protocol.
When you import a complete CPA to Interchange, several things occur. The CPA is associated with
the importing community and the system creates a partner for the partner specified in the CPA. The
system extracts from the CPA the public key certificate data and the URL or e-mail address for
sending messages and adds them to the partner profile.
Your community is not affected when a CPA is imported. During the importing process, however,
Interchange checks whether the community keystore contains the corresponding private keys for all
the signing and encrypting public keys in the PartyInfo section of the CPA.
Before a community can import a complete CPA, the community must be set up on Interchange.
The community name, routing ID, and certificate data must be the same in the community and the
CPA.
Once the community and partner are configured and a CPA is associated with the community,
message exchanges can begin.
l Add a trading pickup on page 261
l Add a partner trading delivery on page 262
The CPA used by the true sender must include the URI for connecting to the intermediary instead of
the true receiver. Other than this one change, the CPA is written as though the true sender and true
receiver exchange messages directly between each other. An exception for the CPA, however,
applies when trading is via HTTPS (see Intermediary trading with HTTPS on page 566).
The following figure illustrates the flow for sending an ebXML message via an intermediary.
Partner A’s Interchange packages and sends the ebXML message in the usual way. Upon receiving
the message, the intermediary parses the message header to identify the true receiver, but does not
unpack the message. The intermediary then sends the message as received to Partner B. Partner B
receives the message as though it was sent directly by Partner A. See the following ebXML message
sent via an intermediary.
The true sender packages the message as if it is being sent to the true receiver. Except in the case of
trading via HTTPS, the true sender’s only knowledge of the intermediary is the URI used to send to
the intermediary.
After receiving the message from the true sender, the intermediary parses the following metadata
from the packaged ebXML message header:
l Action
l ConversationId
l CPAId
l ebXML.SignalType
l ebXML.StatusResponse.RefToMessageId
l FromRole
l MessageId
l ReceiverRoutingId
l ReceiverRoutingIdType
l RefToMessageId
l SenderRoutingId
l SenderRoutingIdType
l Service
l ServiceType
l ToRole
When the intermediary parses the received message, it only reviews the ebXML header before
performing the re-routing. The intermediary re-routes messages internally; it does not write
messages to integration. Of the preceding metadata items parsed from the ebXML message header,
the intermediary only needs the sender and receiver IDs and the routing ID types. The intermediary
does not use the other metadata.
The ebXML intermediary message protocol is proprietary to Interchange. The protocol does not
implement any standards relating to re-routing SOAP or ebXML messages. Interchange must be used
in the intermediary role, but the true sender and true receiver can use any interoperable trading
engine that supports ebXML.
l The intermediary does not unpack or repackage messages. The intermediary message protocol
supports end-to-end signing and encryption.
l The intermediary does not validate signatures.
l Because the intermediary message protocol is exclusively for re-routing ebXML messages, the
protocol overrides the message re-routing control a community optionally may have available for
determining whether to re-route partners’ messages.
l Receipts are not matched up to the payloads in the intermediary’s Message Tracker. The
intermediary only passes messages through. No context is kept from message to message.
l Synchronous acknowledgments, synchronous signals and synchronous business responses are
not supported. A SOAP fault is returned to the sending system for any message that requests a
synchronous response of any type.
l The intermediary does not check for duplicate messages. The true receiver should perform
duplicate checking.
l SOAP faults are not passed from the true receiver back to the true sender. This is because
synchronous responses are not supported through the intermediary. Also, there is no standard
way to match asynchronous SOAP faults to the original message.
Supported transports
See Community trading pickups and partner deliveries on page 256 for the transports supported by
the ebXML intermediary message protocol.
Configuration of intermediary
The intermediary does not use CPAs. The intermediary must:
l Configure a delivery in the community to receive messages via the ebXML intermediary message
protocol from the true sender. The community must have its own unique routing ID. This
routing ID is used for logging and tracking messages, but is not included in packaged messages.
l Add a partner for the true sender. Use the true sender’s routing ID as the partner’s routing ID.
Add the ebXML intermediary message protocol to the partner.
l Add a partner for the true receiver. Use the true receiver’s routing ID as the profile’s routing ID.
Add the ebXML intermediary message protocol to the partner.
Certificates do not have to be associated with the partners for the true sender and true receiver.
However, if HTTPS with client authentication is used, each partner’s client certificate must be
trusted for SSL by the intermediary community. See Intermediary trading with HTTPS on page 566.
A community can be configured to receive messages via both the regular ebXML message protocol
and the ebXML intermediary message protocol.
Moreover, a single partner can be configured to use both the ebXML message protocol and the
ebXML intermediary message protocol. But to support point-to-point messaging, the ebXML
message protocol must be listed as the default protocol in the partner. This is because Interchange
always uses the first listed protocol to send to the partner. The ebXML intermediary message
protocol must be listed as the secondary protocol to support re-routing.
A community acting as an intermediary optionally can perform in-line processing. But such
processing must not change the content of re-routed messages. Any change to the content could
corrupt the ebXML message.
Certificates in the CPA must be the certificates of the end points, not the intermediary. The CPA
should ignore the intermediary, except the transport end point URIs must point to the ebXML
intermediary exchange point configured in the intermediary instance.
Two end points trading via ebXML through an intermediary can use one CPA. Not only must the
TransportReceiver element reference the intermediary's HTTPS URL, the ServerCerticateRef and
ClientSecurityDetailsRef elements must point at the intermediary's SSL certificate. The following CPA
snippet illustrates these points.
<tp:Transport tp:transportId="transportHttps">
<tp:TransportSender>
<!-- References endpoint certificate -->
<tp:TransportProtocol tp:version="1.1">HTTP</tp:TransportProtocol>
<tp:TransportClientSecurity>
<tp:TransportSecurityProtocol tp:version="3.0">SSL</tp:Transport
SecurityProtocol>
<tp:ClientCertificateRef tp:certId="Esx6_Cert"/>
<tp:ServerSecurityDetailsRef tp:securityId="Esx6_Security"/>
<tp:TransportClientSecurity>
</tp:TransportSender>
<tp:TransportReceiver>
<tp:Endpoint
tp:uri="https://intermediary.example.com:4334/exchange/ebxml-
intermediary" tp:type="allPurpose"/>
<tp:TransportServerSecurity>
<tp:TransportSecurityProtocol tp:version="3.0">SSL</tp:Transport
SecurityProtocol>
<tp:ServerCertificateRef tp:certId="ebxml-intermediary_SSL_Server_
Cert"/>
<tp:ClientSecurityDetailsRef tp:securityId="ebxml-intermediary_SSL_
Server_Security"/>
</tp:TransportServerSecurity>
</tp:TransportReceiver>
</tp:Transport>
Export the community or partner certificate to a file. The file must have an extension of .cer, .p7b or
.p7c. The tool for extracting the KeyInfo element information is keyInfoWriter.cmd (Windows)
or keyInfoWriter (UNIX). The tool is in <install directory>\tools.
This command line tool must be run from the tools directory in the following format:
The following is an example use of the tool:
Manage CPAs
The Manage CPAs link at the bottom of the community summary page opens a page for viewing
details of CPAs that have been imported by a community. You also can use the page for importing
CPAs and CPA templates.
On the Manage CPAs page you can:
l View details of an imported CPA by clicking the CPA name. At the bottom of the details page are
links for viewing the CPA as HTML and XML and for exporting and deleting. (Clone options are
available only for users with peer network licensing.)
l View a CPA as a HTML document by clicking HTML. The full view transforms the CPA XML
document into an easy-to-read HTML format. The full view provides details about all possible
actions in the CPA. The MMD view displays the metadata elements required for a back-end
system to build all possible MMDs for the CPA.
The following figure shows the CPA full view (only the top of the view is shown due to length).
The following figure shows the CPA MMD view (only the top of the view is shown due to length).
l View a CPA as an XML document by clicking XML.
l Export a CPA to a file or registry by clicking Export.
l Delete a CPA by clicking Delete.
The following describes the links at the bottom of the Manage CPAs page:
l Click Import a CPA to import a fully configured CPA that contains the trading details for your
community and a partner. CPAs also can be imported automatically by copying the CPA files to
<install directory>\profiles\autoimport.
l Click Manage CPA templates to import templates that partners can use with the partner
registration wizard to build complete CPAs. See ebXML partner self-registration on page 576 for
more information.
l Click Clone CPAs to clone CPAs to peer partners. This feature is available only if your user
license supports the peer network.
Import a CPA
Before you can import a CPA, it must be properly configured for your community and one partner.
Building a CPA requires knowledge of the Collaboration-Protocol Profile and Agreement
Specification Version 2.0 and the trading preferences of both parties.
Once a CPA has been created, you can import it to Interchange and associate it with a community.
The name of the community importing the CPA must be the same in the community and the CPA.
The community importing the CPA must have a certificate matching the one in the CPA associated
with the community. The action of importing a properly configured CPA creates a partner for the
partner specified in the CPA.
To import a CPA, click Manage CPAs at the bottom of the community summary page and click
Import a CPA. Select Import the CPA from a file and type the path of the file to import or use
the Browse button. Click Import to import the CPA.
Once imported, you can export a CPA to an XML file by clicking Export. You also can delete a CPA.
If you want to change a CPA, delete it, change it and import it again. Removing a CPA deletes the
CPA XML document, but does not delete the partner in the CPA.
To import a CPA template, click Manage CPAs at the bottom of the community summary page and
click Manage CPA templates. Type the path of the file to import or use the Browse button. Also
type a description of the template. This description is how partners recognize this template in the
registration wizard. Click Add to import the template.
Once imported, you can delete a CPA template. If you need to change a template, delete the
template, change it and import it again.
When one of these tools call for entering a file name and path, the path must be in the form of a
URL. For example, if the target file is at:
c:\data\cpa.xml
Type the path as:
file:\\\c:\data\cpa.xml
ebxmlCpaSchematronValidator
The ebxmlCpaSchematronValidator tool performs tests on the content of a CPA. The tool makes sure
matching elements in each PartyInfo element of the CPA are consistent.
Schematron is an XML schema language that can be used to validate XML. For information about
Schematron, go to http://xml.com/ and search for Schematron.
Run the tool in the following format:
ebxmlCpaSecurityGuard
The ebxmlCpaSecurityGuard tool is used for digitally signing CPAs. Its various functions all relate to
signing and verifying digital signatures of a CPA.
The certificates you and your partner use to sign the CPA must be trusted by your community in
Interchange.
The following are example formats for running the script to achieve different results:
l Sign
ebxmlCpaSecurityGuard -s –n SigningPartyName –x
file:///c:/cpatest/certNoPassWord.p12 -c
file:///C:/cpaTest/cpaToBeSigned.xml -d C:/cpaTest/output -f
oneSigCpa.xml
l Verify
ebxmlCpaSecurityGuard -v -c file:///C:/cpatest/SignedCpa.xml
ebxmlCpaSecurityGuard -z -c file:///C:/cpaTest/tempCpaSigned.xml -d
C:/cpaTest/output -f oneSigCpa.xml
The following describes the parameters.
Parameter Description
(long)
--directory Location of the output directory.
--file-name Name of the CPA to be written to the output directory.
--help Prints tool help.
--info Prints security information for the CPA.
Parameter Description
(long)
--force Forces signing or validating the CPA without validating the ds:Reference
element in each ProcessSpecification element.
--password The certificate password. If the certificate does not have a password or has an
empty password, omit this option.
--remove-all- Removes all signatures from the CPA.
signatures
--sign Signs the CPA.
--clean The same as calling the following two together:
r(remove-all-signatures) and
y(remove-all-ds:References)
--verify Verifies the CPA.
--add-all- Removes pre-existing ds:Reference and ds:Signature elements and then
ds:References adds ds:Reference elements to each ProcessSpecification.
--certificate URL of the certificate that signs the CPA. For example: file:///
C:/ebxml/certs/signingCert.p12.
--remove-all- Removes all ds:References elements from each ProcessSpecification in the
ds:References CPA.
--remove-last- Removes the last signature from the CPA.
signature
ebxmlCpaValidator
The ebxmlCpaValidator tool performs a schema validation on a CPA.
Run the tool in the following format:
The following describes the parameters.
Parameter Description
-help Prints tool help.
-offline Offline: Do not access the Internet to retrieve XML schemas; all required schemas
or are available locally. This the default.
-online Online: Access the Internet to retrieve XML schemas.
-cpa Paths for one or more CPAs referenced as URLs. For example:
file:///tmp/cpa.xml or http://www.server.com/sampleCPA.xml).
mmdGenerator
The mmdGenerator is for generating all possible MMDs or a specific MMD for a CPA. It can be run
from a command line, but also has a user interface option.
This tool primarily is for testing whether MMDs can be generated correctly from CPAs. But if you use
the tool to generate a specific MMD, it could be submitted through integration as a production MMD
to Interchange. If you use the tool to generate all MMDs from a CPA, the generated MMDs could not
be used in production unless you manually edit the payload location file path in each MMD.
To see the command-line usage for the tool, use the –h parameter.
Use the following procedure to generate MMDs from the user interface.
1. To open the mmdGenerator user interface, run the command without parameters or double-
click mmdGenerator in the tools directory. The mmdGenerator, shown here, displays:
l Synchronous reply
l Duplicate elimination
l Signed acknowledgment
l Acknowledgment requested
5. On the Settings tab, select one of the following options for generating MMDs:
l Generate All MMDs – Click to generate all possible MMDs for the CPA. The tool prompts
you to select the from party. After selecting the party, the tool generates the MMDs and
writes the files to the output directory.
l Generate A Specific MMD – Click to generate a single MMD for the CPA. The tool
prompts you to type a valid service and action and provide the path to the payload file.
Click Generate. The tool then prompts you to select the from party. After selecting the
party, the tool generates the MMD and writes the file to the output directory.
Interchange can handle business object documents (BODs) that conform to Standards for
Technology in Automotive Retail (STAR), the information technology standards body for the
automotive industry.
The configuration is the same as for any community engaged in ebXML trading, with the additional
step of setting up an inline processing action. This is so Interchange can discern the sender,
receiver, collaboration role and action.
This functionality provides XML schema validation and parses a STAR BOD for information needed to
route an ebXML document. This makes it possible for a back-end system to provide only STAR BOD
content, but not routing information.
This does not work as part of the ebXML message service handler. It is called before the MSH to
discover information needed to process the message.
Interchange identifies a STAR BOD in the following way:
The document must have a content type of application/xml or text/xml.
One of the following conditions must be met:
There is a metadata element of IsStarBOD with a value of true, or
There is a namespace declaration in the XML equal to http://www.starstandards.org/STAR.
The following fields are parsed in an outbound STAR BOD:
l ApplicationArea/Sender/DealerNumber – Sender from document location
l ApplicationArea/Destination/DealerNumber – Receiver from document location
l ApplicationArea/Sender/Task – Process specification from document location
l DataArea/oa:* – Action from document location for STAR BOD documents earlier than version
3.0. The asterisk indicates the first child element name of the DataArea element.
l DataArea/* – Action from document location for version 3.0 and later STAR BOD documents.
The asterisk indicates the first child element name of the DataArea element.
Do the following to set up STAR BOD processing in the user interface.
If you want Interchange to validate the STAR BODs, type validate in the Parameter field. If
you do, you must obtain the STAR BOD schemas and put them in your computer’s root
directory (C:\ or /). Schemas are available from http://www.starstandard.org.
6. Click Finish to complete the action configuration.
The configuration is the same as for any community engaged in ebXML trading, with the additional
steps of setting up an inline processing action and a CPA ID. This is so Interchange can discern the
CPA, sender, receiver, collaboration role and action.
Leave the Parameter field blank.
6. Click Finish to complete the action configuration.
7. Set the CPA ID one of the following ways:
On the maintenance page for the integration pickup exchange, select the Message attributes tab
and add an attribute named CPAId. Give the attribute a value equal to the CPA ID of the CPA
you are using.
Or, set the CPA ID using an inline processing action.
This topic is for partners who want to trade via the ebXML message protocol. For AS1 or AS2, see
AS1 / AS2 partner self-registration on page 497.
Hub-and-spoke trading network illustration:
The hub must take the first steps in setting up the ebXML hub-and-spoke network. Its trading engine
must be installed and configured properly. The hub’s community must be configured.
The hub also must have at least one CPA template. Constructing a template requires a thorough
understanding of ebXML practices. Such knowledge is a prerequisite for implementing Interchange
for trading via ebXML.
Although spoke partners must be familiar with the operations of their trading engines, they do not
need to know much about ebXML.
1. Set a password for the partner user, if this has not already been done.
When you log on to the user interface for the first time after installing, there is a link on the
getting started page for Set a password for partner self-registration. Click the link and
type a password for the partner user. This link only appears if your user license allows you to
run the partner registration wizard.
The system creates the partner user for you. Later, your partners will log on to your server’s
registration wizard with the user ID partner and the password you specify.
If the partner user already has been set up, check the users and roles area. Select Users and
roles > Manage users or Users and roles > partner registrant.
2. Create and configure your community. This includes setting up deliveries and a public-private
key certificate for secure trading. The user interface provides guidance for creating and
configuring a community. The user documentation also provides information. See
Communities on page 134.
Make sure the profile is fully configured. When partners use the registration wizard, information
is extracted from your profile and combined with each partner’s information to turn a CPA
template into a completed CPA.
3. Import a CPA template document to your community. Go to the community summary page,
click Manage CPAs at the bottom of the page, click Mange CPA templates and complete
the fields for adding a template.
4. Give your partners the following information:
l URL – The URL for connecting to the page for logging on to the registration wizard. The
URL is in the following format: http://<host>:6080/ui/
The variable host is the fully qualified domain name or IP address of the computer running
Interchange.
l User name and password – The user name and password the partner must use for
logging on to the registration wizard. Have the partner use partner and the password you
specified for the partner user.
l Community name – The name of the community the partner should select to join in the
registration wizard.
l Template name – The name of the CPA template the partner should select when using the
registration wizard.
When a partner uses the registration wizard, the system uses the CPA template to build a
complete CPA. Your system imports the CPA and creates a partner for the just-registered
partner. Meanwhile, the wizard prompts the partner to save the CPA on the partner’s local file
system. If the partner uses Interchange 5.0 or later and imports the CPA, the partner’s system
creates your profile based on the information in the CPA.
5. After a partner registers via the wizard, a message displays on the user interface home page,
prompting you to approve the registration and associate the partner with your community.
Click Trading Partners in the navigation graphic at the top of the community summary page,
click Add a partner to this community, select Choose an existing partner and click
Next. Select the partner and click Add.
1. If you use Interchange 5 or later, install Interchange, set up a database, and log on to the user
interface.
2. If you use Interchange 5 or later, create and configure your community. This includes setting
up delivery exchanges and a public-private key certificate for secure trading. The user interface
provides guidance for creating and configuring a community. The user documentation also
provides information. See Add a community on page 136.
3. Export your encryption certificate and public key to a file. Include all certificates in the
certification path, if possible.
If you use Interchange 5 or later, export your community default encryption certificate and
public key to a file. On the community summary page, click Certificates in the navigation
graphic at the top of the page, click the certificate name and click Export this certificate. If
you are exporting a self-signed certificate, you can export to a CER or PKCS #7 file. If you are
exporting a third-party certificate, export to a PKCS #7 file and include all certificates in the
certification path if possible.
Keep this file. You need it later when you use the registration wizard.
4. Collect and record the following information. This is information you need when using the
registration wizard.
l The name of the community the hub wants you to join. The hub must provide this
information.
l The name of the CPA template to use. The hub must provide this information.
l Your community name.
l Your community routing ID.
l Your community contact name, phone number and e-mail address.
l The URL the hub should use to send messages to you. This is a URL or e-mail address for the
ebXML message protocol HTTP or SMTP transport. If you use Interchange 5 or later, you
can find this by clicking Application delivery in the navigation graphic at the top of the
community summary page. The URL or e-mail address is in the location column. You may
want to consult with the hub about the URL to use.
5. Open a new browser session and connect to the URL the hub provided for the registration
wizard.
6. To log on, type partner and the password the hub provided.
7. Follow the prompts to complete the registration wizard. When prompted to provide the URL for
sending messages to your community, this can be a usual HTTP URL (for example,
http://<host>.com:4080/exchange/1234) or for SMTP an e-mail address expressed as a
URL (for example, mailto:company@mailserver.com).
8. When prompted, save the CPA to your file system.
9. Use the CPA to configure your Interchange to exchange ebXML messages with the hub.
If you use Interchange 5 or later, import the CPA. Go to the community summary page, click
Manage CPAs at the bottom of the page, click Import a CPA and complete the field for
importing a CPA from a file. If the CPA is successfully imported, the system generates a partner
for the hub and associates it with your community.
ebXML troubleshooting
A first step in ebXML troubleshooting is to turn on debug level event messaging. This results in
verbose messages about ebXML activity being written to system log files. To enable debug level
ebXML events:
3. Change the info value to debug.
4. Save and close the file.
Common ebXML issues and possible solutions:
Recommended email applications are Microsoft Office Outlook 2003 or later and Outlook Express 6
or later. Lotus Notes is not supported.
A partner who uses an e-mail client sends documents as attachments. The partner can send more
than one attachment per email. The attachments can be any combination of EDI, XML or binary
documents. EDI documents have an extension of .edi, .edifact, .tradacoms or .x12. XML
documents have an extension of .xml. Interchange treats inbound documents without extensions
as binary documents.
The following topics cover the most common case for trading partners who use email clients to send
messages with document attachments to an Interchange community. The reverse scenario –
Interchange sending documents to an email client – is not presumed.
Procedures
l Trade without certificates on page 580
l Trade with certificates on page 582
l Send from email partner on page 583
l Configure Interchange on page 580
l Configure email client partner on page 581
Configure Interchange
Use this procedure to configure Interchange to trade documents with a partner who uses an email
client application.
This procedure presumes you already have a community. If not, see Add a community on page 136.
1. In your community, add a generic email protocol delivery for receiving messages from a
partner. You must use the generic email protocol and not AS1.
The best practice is to use an external server (SMTP/POP) rather than an embedded SMTP
server. Although it is possible to use an embedded server, the configuration is more complex.
Make sure to properly set the “from” and “to” address on the POP pickup delivery exchange
transport maintenance page. On the from and to address tabs, select Always parse for the
address. Also select If the document is EDI, parse for the address, and If the
document is XML, use XPaths to locate the address and the XPath.
2. Give your email client partner the email address for the delivery added in step 1. Your partner
uses this address to send messages to your community.
On the community summary page, click Trading pickup on the navigation graphic at the top
of the page to open the Trading pickups page. Find the generic email transport and click to
open the transport’s maintenance page. The email address is listed on the settings tab.
3. Add a partner for your email client partner. Give it a meaningful name and routing ID.
4. Add a generic email protocol delivery for sending messages to the partner via SMTP. You must
use the generic email protocol and not AS1.
In adding the transport, type the partner’s email address. This is the address your community
uses to send messages to the partner.
5. Make sure message signing and encryption for inbound messages from this partner are turned
off. Do the following:
1. In Outlook, add your Interchange partner as a contact. Use the partner’s email address for
receiving documents as the contact’s e-mail address.
2. Set the mail client to compose messages in plain text. This makes sure the Interchange partner
does not receive excess messages composed of MIME parts in addition to the document
attachment.
In Outlook, select Tools > Options. On the Mail Format tab, select Plain Text for the
Compose in this message format field.
Configure Interchange
Use this procedure to configure Interchange to trade documents with a partner who uses an email
client application.
This procedure presumes you already have a community. If not, see Add a community on page 136.
1. In your community, add a generic email protocol delivery for receiving messages from a
partner. You must use the generic email protocol and not AS1.
The best practice is to use an external server (SMTP/POP) rather than an embedded SMTP
server. Although it is possible to use an embedded server, the configuration is more complex.
Make sure to properly set the “from” and “to” address on the POP pickup delivery exchange
transport maintenance page. On the from and to address tabs, select Always parse for the
address. Also select If the document is EDI, parse for the address, and If the
document is XML, use XPaths to locate the address and the XPath.
2. Give your email client partner the email address for the delivery added in step 1. Your partner
uses this address to send messages to your community.
On the community summary page, click Partner delivery on the navigation graphic at the top
of the page to open the Partner deliveries page. Find the generic email transport and click to
open the transport’s maintenance page. The email address is listed on the settings tab.
3. Add a partner for your email client partner. Give it a meaningful name and routing ID.
4. Add a generic email protocol delivery for sending messages to the partner via SMTP. You must
use the generic email protocol and not AS1.
In adding the transport, type the partner’s email address. This is the address your community
uses to send messages to the partner.
5. Export a community certificate and public key to a file and give it to the email client partner.
The partner’s email client uses this certificate to encrypt messages sent to your community.
A self-signed certificate or one issued by a certificate authority can be used.
Export the certificate to a file with an extension of .cer or .p7b. Select the option “Include all
certificates in the certification path if possible” when exporting (see Export a certificate to a file
on page 799). Send the certificate file to your partner by a secure means. Do not send your
private key to your partner.
Export the certificate with an extension of .cer or .p7c. Then send the certificate file to your
partner by a secure means. Do not send your private key to your partner.
1. In Outlook, add your Interchange partner as a contact. Use the partner’s email address for
receiving documents as the contact email address.
2. Set the mail client to compose messages in plain text. This makes sure the Interchange partner
does not receive excess messages composed of MIME parts in addition to the document
attachment.
In Outlook, select Tools > Options. On the Mail Format tab, select Plain Text for the
Compose in this message format field.
3. Have your Interchange partner send you the certificate to use for encrypting message
attachments.
4. Import the partner’s certificate to the partner’s contact information in Outlook. On the
certificates properties window, make sure to specify that Outlook is to explicitly trust the
certificate.
If upon importing the certificate, Outlook displays a message that the email address in the
certificate is not found in the contact’s email list, click Yes to accept the certificate.
1. Each email message can have one or more attachments. Upon receiving the email, Interchange
treats each attachment as a separate document. In the case of multiple attachments,
Interchange identifies each document as being split from an original message.
2. Use the Interchange partner’s email address as the “to” address.
3. If the Interchange partner is the true receiver of the message, leave the subject line of the
message blank. In other words, leave the subject line blank when the Interchange partner does
not re-route the message to a third party.
4. If the Interchange partner plans to re-route the message to a third party, add to the message
subject line the routing ID of the ultimate receiver (the party to whom the Interchange partner
forwards the message) and the routing ID of the sending party (the email client). The subject
line format must be:
truereceiverID;truesenderID
If the routing IDs contain spaces or non-alphanumeric characters, enclose the IDs in quotes like
so:
"true receiver ID";"true sender ID"
Although supported, non-alphanumeric characters in routing IDs is not a best practice.
If the email sender does not know what routing ID to use, ask the Interchange partner who
performs the re-routing.
In a re-routing the scenario, the Interchange partner who performs the re-routing is called the
hub. The hub partner must enable re-routing. To do so, click Trading partners on the
navigation graphic at the top of the community summary page. Select Allow messages to be
re-routed and click Save changes.
If your infrastructure does not require HTTP traffic to navigate a proxy to access the Internet, you do
not need to use this feature.
Note This note applies only to users whose license supports DMZ nodes. If you have enabled an
outbound connection proxy for Secure Relay DMZ nodes, a community-specific HTTP
proxy takes precedence for outbound HTTP connections. For more information, see
Configure outbound connection proxy on page 488.
Proxies are “one-hop” by nature, so if you set up an HTTP proxy, it overrides any other proxy
definitions that your partners may have set up. If you know that one or more of your partners use a
proxy for incoming HTTP connections, you should not use an HTTP proxy or work with your partner
to establish some other connection method.
To set up the HTTP proxy, click HTTP proxy in the navigation graphic on the community summary
page. If your user license supports DMZ nodes, click DMZ settings in the graphic instead.
Select a community to proceed with the test. The displayed test results indicate the success or
failure of the connection.
The following steps provide the navigation for performing a test.
test.
3. Select a community to proceed with the test.
l HTTP (embedded) server on page 586
l External staged HTTP server on page 588
This level of security is sufficient for most applications.
Advantage: High level of security with minimal per-partner maintenance overhead.
Disadvantage: Does not protect against denial-of-service attacks.
This level of security, in combination with requiring signed and encrypted payloads, is very high and
should be sufficient for virtually all applications.
Advantage: Protects against denial-of-service attacks.
Disadvantage: IP address filtering requires updating firewall rules when a partner is added or
removed.
Option 3. SSL
If receiving any unencrypted messages, you should require your partners to connect using HTTPS
(SSL) so no one on the Internet can eavesdrop on the contents.
Advantage: Eavesdroppers are thwarted even if messages are not encrypted.
Disadvantage: Extra CPU load introduced by SSL (but see option 5). The user cannot configure
the encryption algorithm for HTTPS. It is better to require message-level security because the
encryption algorithms are stronger.
If you choose to allow unsigned payloads, it is highly recommended that you require client-
authenticated SSL to prevent connections from being accepted from unknown parties.
Advantage: Unwanted connections are refused as early as possible, before any part of the payload
is received.
Disadvantage: Within Interchange you must maintain a list of trusted SSL client-authentication
certificates for each partner. This is in addition to the list of partner certificates you must maintain
for encrypting messages and verifying signatures.
Your existing load balancer may be able to do this or you may be able to purchase an add-on SSL
module. Alternatively, some vendors offer SSL accelerator cards that can be installed in a server to
terminate SSL connections.
Advantage: Off-loads CPU-intensive SSL processing from Interchange to the hardware device.
Connections are refused in the DMZ before they reach Interchange. Very high resistance to denial-
of-service attacks.
Disadvantage: Requires external hardware device or card. If client-authenticated SSL is used,
requires a list of trusted SSL client-authentication certificates to be maintained outside of
Interchange using software included with your hardware device.
Summary of options
In summary, most users choose one of the following levels of security when employing the
embedded HTTP server.
l High security – The default behavior of Interchange in requiring payloads to be signed and
encrypted affords a very high level of security right out of the box, even if connections are
terminated within your private network by the embedded HTTP server. This level employs the
security described in option 1.
l High security and denial-of-service resistance – Adding IP and port filtering rules to your
firewall prevents connections from being accepted even before the payload has been examined.
This level combines the security described in options 1 and 2.
l Maximum security – The highest possible interoperable level of security can be achieved by
using firewall rules in combination with client-authenticated SSL, terminated by a hardware
device in your DMZ. In this case, payloads do not need to be signed or encrypted, but can be if
an additional level of security is desired. This level combines the security described in options 1
and 2 in addition to either option 4 or option 5.
The following topics describe advantages and disadvantages to this transport.
Advantages
1. Some argue that an external HTTP server provides better security than the embedded server.
This is because the external server terminates inbound connections from the Internet in the
DMZ. It also does not allow any inbound connections all the way through to the protected
network, since Interchange polls the embedded server for new files.
However, the better security argument is more a matter of perception than fact, as state-of-the-
art levels of security can be achieved with the embedded HTTP server, as described in HTTP
(embedded) server on page 586.
2. If Interchange is shut down, inbound messages queue on the external server, allowing
maintenance to be performed without causing partners to experience connection errors.
However, it should be noted that partners generally would employ retries to deal with
connection errors. Also, using an Interchange cluster achieves a similar result since one node
can be serviced while another continues to do work.
3. Under peak load conditions messages queue on the external server if Interchange is too busy to
process them, reducing the chances of partners receiving 503 (busy) errors.
Disadvantages
1. Some argue that staging the files to a file system that is accessible from the DMZ introduces
security risks. However, this argument is questionable if the payloads are encrypted. After all,
the encryption was good enough when the files were passing through the Internet.
2. Having to poll the external server introduces latency that is not present with the embedded
server.
3. Adding an external server increases the total complexity of the system, increasing the number of
things that could break or introducing security holes.
These charts also apply to HTTPS (HTTP over Secure Sockets Layer). HTTPS uses an SSL certificate
to encrypt the connection. Message traffic passing back and forth through the encrypted SSL tunnel
is pure HTTP.
HTTP is a popular transport available under many message protocols, including AS2, secure file,
ebXML, web services, RosettaNet, and the no packaging protocol. For more information see
Community trading pickups and partner deliveries on page 256. The following figure shows the
HTTP connection troubleshooting flow chart.
The following is the read and response time-outs flow chart:
MLLP
Minimal Lower Layer Protocol (MLLP) is a transport protocol primarily designed for the health
industry to send HL7 documents. It can also be used to send XML documents. You can configure
Interchange to exchange documents over MLLP with back-end applications and with remote trading
partners. In an MLLP exchange you can configure Interchange to act as either an MLLP client or an
MLLP server.
This MLLP server can consume requests from clients either in the back end (applications) or over the
internet (trading partners).
l Asynchronous transfers
l Synchronous transfers
A doctor edits a medical summary for a patient and submits the summary (via an MLLP client) to a
health organization (hosting an MLLP server). The server immediately acknowledges the transfer
request (protocol-level acknowledgement) and delivers the document to a back-end application of
the health organization for processing, billing, etc.
1. Create a community to represent the doctor's organization.
See Add a community on page 136.
2. On the community, add a file system type application pickup to consume the medical summary
from the doctor's file system outbound folder.
See File system transport configuration on page 189.
3. Create a partner to represent the remote MLLP server of the health organization.
See Add a partner on page 143.
4. On the partner, create a trading partner delivery to define the connection to the MLLP server.
l When you create the delivery, select the delivery type MLLP.
l In the delivery settings, enter the network address and access port of the MLLP host.
l In the Advanced tab of the delivery, select the option Acknowledgement expected
from the target MLLP server.
See Add or modify an MLLP trading delivery on page 602.
1. Create a community to represent the health organization.
See Add a community on page 136.
2. On the community, add a trading pickup to enable the consumption of the client request.
l When you create the pickup, select the pickup type MLLP.
l In the pickup settings, enter the machine name and port for connections.
Interchange automatically sets up an embedded MLLP server.
See Add or modify an MLLP trading pickup on page 605.
3. Open the maintenance page for the MLLP embedded server Advanced tab, and select the
acknowledgement mode Send transport level MLLP acknowledgement.
See MLLP (embedded) fields on page 608.
4. On the community create an application delivery to transfer the HL7 document to the
destination application. For example we can create a file system delivery with a reception
destination folder.
Add an application delivery on page 162.
A doctor has a patient's local-office identification but requires the patient's alternate global ID.
Using an MLLP client application, the doctor sends the local ID to a remote patient ID repository
which hosts an MLLP server and master patient database. The MLLP server receives the query, and
forwards it to the master patient database where a patient reference table is set up. The patient ID
database application returns the resolved patient ID to the MLLP server in the form of an MDN. The
MDN also specifies the original request connection ID so that Interchange can tie the resolved
patient global ID to the doctors original request. The MLLP returns the global ID to the doctor over
the same MLLP connection that was opened for the query.
1. Create a community to represent the doctor's organization.
See Add a community on page 136.
2. On the community, add a file system type application pickup to consume the HL7 patient
ID resolution request deposited by the doctor.
See File system transport configuration on page 189.
3. Create a partner to represent the remote MLLP server (in this case, the MLLP server is linked to
an ID repository database application).
See Add a partner on page 143.
4. On the partner, create a trading partner delivery to define the connection to the MLLP server.
l When you create the delivery, select the delivery type MLLP.
l In the delivery settings, enter the network address and access port of the MLLP host.
l In the Advanced tab of the delivery, select the option Acknowledgement expected
from the target MLLP server.
See Add or modify an MLLP trading delivery on page 602.
1. Create a community to represent the MLLP server.
See Add a community on page 136.
2. On the community, add a trading pickup to enable the consumption of the client request, and
synchronous response.
l When you create the pickup, select the pickup type MLLP.
l In the pickup settings, enter the machine address and port for connections.
Interchange automatically sets up an embedded MLLP server.
See Add or modify an MLLP trading pickup on page 605.
3. Open the maintenance page for the MLLP embedded server Advanced tab, and select the
acknowledgement mode Send synchronous application acknowledgement generated
in back end.
See MLLP (embedded) fields on page 608.
4. On the community create an application delivery to transfer the HL7 document to the patient
ID repository server.
See Add an application delivery on page 162.
Prerequisites
The application delivery resides in a community object. Before you add an application delivery you
must add a community to represent the MLLP client. See Add a community on page 136.
Procedure
1. In the user interface, select Trading configuration > Manage trading configuration to
open the Communities page.
2. Select the community you want to use to represent the MLLP client.
3. On the community map of the community summary page, click the Application delivery
icon.
4. On the Application deliveries page, click Add an application delivery.
5. On the Choose transport protocol page, select MLLP and click Next.
6. On the Configure the MLLP settings page, complete the fields:
7. On the Configure the MLLP settings page, complete the fields:
l MLLP server – Enter the address of the MLLP server to which you are connecting.
l Port – Enter the server port for MLLP connections.
l Client must use TLS to connect to this server – Select this option if TLS is required
for the client connection to the MLLP server.
l Enable host name verification – If you require TLS use for connection to the server,
you can optionally select this additional security feature.
8. On the Configure the file system settings page / Directory name field– Use the Browse
button or type the full path for a unique directory where Interchange routes messages. If the
directory does not exist, Interchange creates it for you. Use a unique directory name. The
delivery exchange wizard suggests a name that you may use or modify.
9. On the Exchange name page, enter a name for the application delivery.
10. Click Finish.
Filenames tab
Example with the original file extension: dabeed45_4cb.edi
Example without the original file extension: z47e4120_4ce
o Define custom filename construction – Interchange generates a file name using a
pattern that you specify. Enter the pattern in the Pattern field.
Schedule tab
See Schedule tab on page 208.
Advanced tab
l Maximum concurrent connections – The number of total open connections Interchange
server can make to a partner. If you are operating in a cluster environment, this is the total
number across the entire cluster, no matter how many JVM nodes are running. For example, if
the value is 100 connections and there are 150 messages to send, Interchange opens only 100
connections to that partner. The remaining 50 messages are queued until connections become
available.
The default value is suitable in almost all cases. However, if a partner says your Interchange is
overrunning his receiving system, decrease the value. (This advice does not apply to OFTP X.25
or X.25 over ISDN, as the default maximum value is 1 for those transports.)
l Retries – The number of times Interchange retries connecting to the partner’s transport if the
initial attempt to connect and send the message failed. The following are common reasons for
triggering retries.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners. Backup files are stored in \<install
directory>\common\data\backup, unless you specify otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands.
Prerequisite
You must have a community defined.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
3. Click Application pickup in the navigation graphic to open the Application pickups page.
4. Click Add an application pickup.
5. Choose the message protocol No packaging and click Next.
6. Complete the From address page and click Next.
7. Complete the To address page and click Next.
8. On the Choose transport protocol page, select MLLP and click Next.
9. Configure the MLLP server:
l Server name – Server name, for example MyServer.
l Port – MLLP Server access port on your hosting machine.
l Clients must use TLS to connect to this server – Select this option if you require TLS
for this connection.
l This server requires client authentication. The partner must present an
authentication certificate trusted by the server when connecting – If you
selected the TLS requirement option above, select this option to require your partners to
submit a certificate to verify their identity before the pickup allows the connection. Clear
this option to use non-authenticated MLLP. If you select this option, you must add an
authentication certificate for the partner.
10. Enter a name for the pickup to identify it in the user interface. Hint: Enter a name that is easily
identifiable in a list of pickups in the user interface.
11. Click Finish.
To address tab
See From address and To address tabs on page 204.
Schedule tab
See Schedule tab on page 208.
Advanced tab
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners. Backup files are stored in \<install
directory>\common\data\backup, unless you specify otherwise.
l Restrict maximum file size for this transport – Optionally specify the maximum size of
files that this transport can handle. If Interchange receives a file larger than the maximum, the
file is rejected and a message is written to the events log.
l Maximum files per polling interval – The highest number of messages the system can
retrieve each time it polls.
l Polling interval (seconds) – The interval, in seconds, Interchange waits before polling for
messages to retrieve.
Prerequisites
The partner delivery resides in a partner object. Before you add a partner delivery you must add a
partner object to represent the MLLP client partner.
Procedure
1. In the user interface, select Partners > Manage partners to open the Partners page.
2. Select the partner you want to use to represent your MLLP client partner.
3. On the partner map of the partner summary page, click the Partner delivery icon.
4. On the Delivery exchanges page, click Add a delivery.
5. On the Choose message protocol page, select No packaging and click Next.
6. On the Choose transport protocol page, select MLLP and click Next.
7. On the Configure the MLLP settings page, complete the fields:
l MLLP server – Enter the address of the MLLP server to which you are connecting.
l Port – Enter the server port for MLLP connections.
l Client must use TLS to connect to this server – Select this option if TLS is required
for the client connection to the MLLP server.
l Enable host name verification – If you require TLS use for connection to the server,
you can optionally select this additional security feature.
8. On the Exchange name page, enter a name for the partner delivery.
9. Click Finish.
Schedule tab
See Schedule tab on page 208.
Advanced tab
l Maximum concurrent connections – The number of total open connections Interchange
server can make to a partner. If you are operating in a cluster environment, this is the total
number across the entire cluster, no matter how many JVM nodes are running. For example, if
the value is 100 connections and there are 150 messages to send, Interchange opens only 100
connections to that partner. The remaining 50 messages are queued until connections become
available.
The default value is suitable in almost all cases. However, if a partner says your Interchange is
overrunning his receiving system, decrease the value. (This advice does not apply to OFTP X.25
or X.25 over ISDN, as the default maximum value is 1 for those transports.)
l Retries – The number of times Interchange retries connecting to the partner’s transport if the
initial attempt to connect and send the message failed. The following are common reasons for
triggering retries.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Connect timeout (seconds) – Time in seconds Interchange waits for a connection to the
delivery exchange before the attempt times out. Although the default value is 30 seconds, this
may be longer than the interval allowed by your operating system (OS). For example, Windows
XP by default allows a maximum timeout of 20 seconds. The actual connect timeout interval is
the lesser of the OS timeout and the value set in Interchange.
l Read timeout (seconds) – Time in seconds Interchange waits to read data from the delivery
exchange before terminating the connection.
l Start block character – The decimal byte value to use for the start block character. Start and
stop block characters enclose the message data that is sent or received in through MLLP
messages. At runtime Interchange converts this decimal value to hexadecimal. Default = 11
(hexadecimal B). The default value is the customary MLLP value. You must use the same values
for the client and server sides of the MLLP exchange.
Prerequisite
You must have a community defined. See Add a community on page 136.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
3. Click Trading pickup in the navigation graphic to open the Trading pickups page.
4. Click Add a pickup.
To address tab
See From address and To address tabs on page 204.
Schedule tab
See Schedule tab on page 208.
Advanced tab
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners. Backup files are stored in \<install
directory>\common\data\backup, unless you specify otherwise.
l Restrict maximum file size for this transport – Optionally specify the maximum size of
files that this transport can handle. If Interchange receives a file larger than the maximum, the
file is rejected and a message is written to the events log.
To change settings:
l Port – The TCP port on which the embedded server listens for connection requests.
Advanced tab
l Minimum threads – The least number of threads Interchange must dedicate to the server.
l Maximum threads – The most threads Interchange can dedicate to the server.
l Start block character – The decimal byte value to use to identify the start block character.
Start and stop block characters enclose the message data that is sent or received in through
MLLP messages. At runtime Interchange converts this decimal value to hexadecimal. Default =
11 (hexadecimal B). The default value is the customary MLLP value. You must use the same
values for the client and server sides of the MLLP exchange.
l End block character – The decimal byte value to use to identify the end block character. Start
and stop block characters enclose the message data that is sent or received in through MLLP
messages. At runtime Interchange converts this decimal value to hexadecimal. Default = 28
(hexadecimal 1C). The default value is the customary MLLP value. You must use the same values
for the client and server sides of the MLLP exchange.
l Acknowledgement mode – Select an option:
o Send no acknowledgement – (MLLP version 1 option) Select this option to implement
MLLP connections without acknowledgements.
o Send transport level MLLP acknowledgement – (MLLP version 2 option) Select this
option to enable transport-level acknowledgements for connections to this MLLP server.
o Send synchronous application acknowledgement generated in back end –
(MLLP version 2 option) Select this option if you want connections to this MLLP server kept
open until an application acknowledgement is generated in the back end.
l Override SSL and TLS cipher suites – Select this option and then use the Add and
Remove buttons to specify the cipher suites supported for the embedded server.
If you do not select this option, all cipher suites are supported by default. Keeping the default
cipher list is less secure than specifying a restricted set of cipher suites.
The cipher suites that are displayed in the "Available" column depend on your runtime
environment (JRE version, IACK or FIPS enablement, Secure Relay configuration, ....).
The default order in the "Available" column is the preferred order of use. Once ciphers are moved
to the Selected column, you can arrange the order. Interchange uses the ciphers in the order
listed.
A cipher suite is a collection of security algorithms used in making connections via Secure
Sockets Layer or Transport Layer Security. For example, an SSL or TLS protocol requires signing
messages using a message digest algorithm. But the choice of algorithm is determined by the
particular cipher suite being used for the connection. Typically, you can select an MD5 or SHA
digest algorithm.
Of the many algorithms for encrypting data and computing the message authentication code,
there are varying levels of security. Some provide the highest levels of security, but require a
large amount of computation for encryption and decryption. Others are less secure, but provide
rapid encryption and decryption. The length of the key used for encryption affects the level of
security. The longer the key, the more secure the data.
The option for overriding cipher suites lets you select the level of security that suits your needs
and enables communicating with others who might have different security requirements. For
example, when an SSL connection is established, the client and server exchange information
about the cipher suites they have in common. Then they communicate using the common
cipher suite that offers the highest level of security. If they do not have a cipher suite in
common, secure communication is not possible.
In versions of Interchange earlier than Interchange 5.9, cipher suites configuration was handled
by a file named sslciphersuites.xml. As data in that file is saved in the database, the
custom cipher suites configuration is retained upon upgrading and is displayed in the Selected
list under the option in the user interface. The sslciphersuites.xml file is no longer used.
OFTP
The following topics describe using the Odette File Transfer Protocol V1 or V2 to trade messages
with partners. Also included are topics for using OFTP V1 delivery exchanges over X.25 and over
X.25 over Integrated Services Digital Network (ISDN). You can use X.25 if your user license enables
you to use OFTP V1.
Concepts
l OFTP overview on page 612
l TSL support for OFTP2 on page 613
l Use X.25 with OFTP on page 628
l Use X.25 over ISDN on page 632
l X.25 requirements on page 634
l X.25 troubleshooting on page 635
Procedures
l Configure TSL for a community on page 614
l OFTP transport configuration on page 617
l Configuration outline for X.25 on page 634
l Add or edit an X.25/B-ISDN router on page 635
OFTP overview
Communities can use the Odette File Transfer Protocol V1 or V2 to trade messages with partners.
To use OFTP V1, your partner must use Interchange or Activator 5.8 or later or an interoperable
trading engine that supports OFTP V1. For information about OFTP V1 over X.25 see OFTP on page
611.
To use OFTP V2, your partner must use Interchange or Activator 5.5.2 or later or an interoperable
trading engine that supports OFTP V2. (OFTP V2 is commonly known as OFTP2.)
Note If you are upgrading from a pre-5.8.0 version of Interchange and have any ODETTE File
Transfer Protocol (OFTP) delivery exchanges, delete the exchanges before upgrading to
this release. After installing the upgrade, you can reconfigure the exchanges. If OFTP
exchanges are not deleted before upgrading, Interchange server will fail to start after
upgrading.
Interchange implements OFTP as an embedded server. In a community, OFTP is configured as a
embedded server to receive messages from clients (your partners). In a partner, the client
connection is set up to send messages to a community embedded server.
Bi-directional messaging
OFTP supports bi-directional messaging. When Interchange has connected to a partner’s OFTP
server to send a message, it also can receive messages from the partner via the same connection. If
the partner has multiple messages queued, all can be sent on the same connection. Similarly,
Interchange can send multiple messages to the partner over the same connection.
However, Interchange compensates for this. If an OFTP delivery exchange consumes a file with a
name longer than 26 characters, Interchange shortens the name to an acceptable length. Without
this change, the message would fail due to the protocol limitation.
For example, if a file whose name is too long is consumed, such as:
windows_TO_linux_39001001.edi
Interchange renames the file as:
1_ws_TO_linux_39001001.edi
Interchange makes sure the changed names are unique by attaching an incremental counter as a
prefix. In this example, the counter number is 1_.
In Message Tracker the consumed, long file name is reported as the original file name and the
shortened file name is reported as the delivery file name. The renaming also is reported in
Interchange events log file.
Troubleshooting
To generate debug-level events related to OFTP delivery exchanges, do the following:
Set the following property in the log4j.properties file to debug:
log4j.category.com.cyclonecommerce.tradingengine.
transport.oftp=info
In addition, add the following property to the file:
log4j.category.com.cyclonecommerce.businessprotocols.
oftp2=debug
For OFTP V1 delivery exchanges the statistics monitor also can generate information useful in
troubleshooting.
Resource links
l http://www.faqs.org/rfcs/rfc2204.html: This accesses RFC 2204, the standard for OFTP V1.
l http://www.faqs.org/rfcs/rfc5024.html: This accesses RFC 5024, the standard for OFTP2.
l https://forum.odette.org/: This accesses the Odette Forum. If registered as a user you can
download publications, including a document about SCX TSL at
https://forum.odette.org/publications/security/security-certificate-exchange.
About TSLs
A TSL is an XML document that contains entries for the certificates issued by certificate authorities
(CAs). A certificate entry can contain an intermediate or root CA certificate. When an entry contains
an intermediate CA certificate, it also contains the remainder of the certificate chain up to and
including the root CA certificate. A TSL also contains a large amount of metadata about the list itself,
including:
l The name of the list
l A version identifier for the list
l A sequence number of the list
l The date and time the list was issued
l The date and time the list is scheduled be updated
Odette publishes three files for each TSL:
l An XML file containing the TSL itself
l A text file containing the date and time the TSL was last updated
l A text file containing the policy for the certificates in the TSL
Each TSL is signed using the XML digital signature mechanism to ensure the authenticity and
integrity of the TSL. The signature verification certificate is included in the digital signature. Odette
also publishes its TSL signature verification certificates in the file http://www.odette.org/TSL/TSL_
signing.P7B.
You must get end-entity certificates from the CAs whose certificates are in the TSL and then import
the acquired certificates to Interchange. When a community is configured to use a TSL, it gets its
trusted root and intermediate certificates solely from the TSL. You cannot change (delete from or
add to) the community's trusted certificates.
When a TSL contains an intermediate CA certificate, the community is configured to trust that
intermediate CA certificate and not the root CA certificate. This is different from the standard
certificate trusting behavior within Interchange where the root certificate is trusted. This is because
many of the intermediate CA certificates in a TSL may share a common root CA certificate, and
trusting the root CA certificate could resulting in trusting more certificates than intended.
A TSL does not contain a mechanism for indicating the intended usage (signing, encryption, TLS
server authentication or TLS client authentication) of certificates issued by the CA certificates in the
TSL. Because of this, all CA certificates in the TSL are put in both the community's Trusted root
certificates and Trusted SSL root certificates.
1. Click Certificates in the navigation graphic at the top of a community summary page. This
opens the Certificates page.
If you review the Trusted root certificates tab and Trusted SSL root certificates tab and any
certificates are listed, these certificates are replaced by TSL certificates after you complete the
next steps. TSL root and intermediate certificates supplant any non-TSL root and intermediate
certificates a community may have.
2. Click the task Manage use of Trust-service Status List (TSL) near the bottom of the page.
This opens the Manage use of Trust-service Status List (TSL) page.
Choose a TSL
3. Type one of the following values in the Select TSL field. These are the names of TSLs that
Odette has been publishing. If one or more of these TSLs are already used by another
community, you can select a name from the drop-down list. If not present, you must type the
name. The names are not case sensitive. A community can use only one TSL at a time.
l OFTP2– This is generally the TSL to use if your community is engaged in production
trading.
l Basic – This is a superset of the OFTP2 TSL.
l Test – This TSL is only intended for testing purposes.
Odette manages these lists and could decide to expand or reduce the number of lists it
publishes.
4. Click Save changes to add the specified TSL. Interchange connects to Odette and downloads
the most recent list.
Details of the TSL are displayed on the Manage use of Trust-service Status List (TSL) page. The
URL field links to an XML file that contains the TSL. The Policy URL field links to a text file that
describes the policies for using the certificates in the TSL. If you cannot open the links, you
may have to adjust your browser to connect though a proxy managed by your network.
Interchange checks randomly for newer versions of TSLs to download. To check instantly for a
new list, click the task Update the TSL being used by this community.
If Interchange cannot connect to download the TSL, it may be because your network requires
routing outbound connections through a proxy. For more information see TSL support for
OFTP2 on page 613.
If you use Secure Relay, use of the DMZ retrieval option requires enabling Use outbound
connection proxy on the Configure outbound connection proxy page (see Configure outbound
connection proxy on page 488). However, even with that enabled you can still use the Local
option.
Transport type
Select the option for receiving messages from remote partners:
Network type
Select the network protocol. The options are:
l TCP. Transmission Control Protocol is the basic communications protocol of the Internet.
l X.25. An ITU-T standard protocol suite for packet-switched wide area network communications.
l X.25 over ISDN (B-channel). Integrated Services Digital Network broadband channel
supports data transfers over telephone networks.
If you select an X.25 option, you are prompted to select a router. You can select an existing router
or add one to use.
l Friendly name – The name of this router. A meaningful name is suggested. If not specified,
Interchange uses a name in the following format: Router on [host name or IP].
l Host – The fully qualified domain name or IP address of the internal interface of the router. It
must be accessible from all Interchange nodes.
o Maximum concurrent outbound connections – The maximum number of outbound
X.25 logical connections that can be made by this router. This is tied to the X.25 network’s
number of allowed virtual channels and bandwidth.
As the virtual channels are used for inbound and outbound connections, and OFTP requires
receipts to be delivered, be careful when specifying this value. For example, if the maximum
number of channels is 10, set this value to 4. This makes sure at least 6 channels stay
available for receipts and inbound connections, if any.
o SNMP community password – The SNMP password with at least read-only rights over the
SNMP tables in the router.
l Friendly name – The name of this router. A meaningful name is suggested. If not specified,
Interchange uses a name in the following format: Router on <host name or IP>.
l Host – The fully qualified domain name or IP address of the internal interface of the router. It
must be accessible from all Interchange nodes.
l Remote CAPI port – The TCP port for the remote CAPI service on the router. This is used to
remotely control the ISDN features of the router. The factory default value for the R4300 is
2662.
l Controller index – The physical number of the ISDN controller within the router, which is
roughly equivalent to a physical ISDN modem connected to one ISDN line. Numbering starts at
1, but there can empty slots (for instance, only one controller with index 2 can be installed).
l Controller description – The name for this controller. A meaningful name is suggested. If not
specified, Interchange uses a name in the following format: Controller <index> on <host
name or IP>.
l Maximum concurrent outbound connections – The maximum number of outbound ISDN
physical calls that can be made on the B-channels by this controller. This is tied to the ISDN
network’s number of B-channels (2 for BRI, 24 or 30 for PRI). As the B-channels are used for
inbound and outbound calls, and OFTP requires receipts to be delivered, be careful specifying
this value. For example, if the maximum number of B-channels is 2, set the value to 1 to make
sure at least 1 channel is available for receipts and inbound connections, if any.
See the following figure: OFTP V1 embedded server in delivery exchange wizard.
l Server name – The name for the embedded OFTP server. This can be any name you want.
l SSID identification code – The start session identification (SSID) of the local or remote
party. Trading partners exchange SSIDs to identify each other in the protocol handshake and
session setup.
l Port – If TCP, the port on which the server listens for connections.
l OFTP protocol version – The protocol version being used (1.3 or 1.4).
l Partner uses RFC 2204, not RFC 5024 – For OFTP V1 only when protocol version is 1.3,
this check box tells Interchange the protocol release level (SSIDLEV) to use for the trading
partner. Select the check box if the partner uses the RFC 2204 implementation. This means the
SSIDLEV field in the start session (SSID) command has a value of 1. Do not select this option if
the partner uses the RFC 5024 implementation. This means the SSIDLEV field in the SSID
command has a value of 2. (Note that in either case the exchange point is being defined for
OFTP protocol revision level 1.3.)
l Clients must use TLS to connect to this server – Select this to set up Transport Layer
Security for the OFTP delivery exchange. When selected, the following sub-field displays.
o This server requires client authentication – If you selected TLS, select this check box
to require your partners to submit a certificate to verify their identity before the delivery
exchange allows the connection.
Transport type
Select the option for receiving messages from remote partners:
Network type
Select the network protocol. The options are:
l TCP. Transmission Control Protocol is the basic communications protocol of the Internet.
l X.25. An ITU-T standard protocol suite for packet-switched wide area network communications.
l Friendly name – The name of this router. A meaningful name is suggested. If not specified,
Interchange uses a name in the following format: Router on <host name or IP>.
l Host – The fully qualified domain name or IP address of the internal interface of the router. It
must be accessible from all Interchange nodes.
o Maximum concurrent outbound connections – The maximum number of outbound
X.25 logical connections that can be made by this router. This is tied to the X.25 network’s
number of allowed virtual channels and bandwidth.
As the virtual channels are used for inbound and outbound connections, and OFTP requires
receipts to be delivered, be careful when specifying this value. For example, if the maximum
number of channels is 10, set this value to 4. This makes sure at least 6 channels stay
available for receipts and inbound connections, if any.
o SNMP community password – The SNMP password with at least read-only rights over the
SNMP tables in the router.
l Friendly name – The name of this router. A meaningful name is suggested. If not specified,
Interchange uses a name in the following format: Router on <host name or IP>.
l Host – The fully qualified domain name or IP address of the internal interface of the router. It
must be accessible from all Interchange nodes.
l Remote CAPI port – The TCP port for the remote CAPI service on the router. This is used to
remotely control the ISDN features of the router. The factory default value for the R4300 is
2662.
l Controller index – The physical number of the ISDN controller within the router, which is
roughly equivalent to a physical ISDN modem connected to one ISDN line. Numbering starts at
1, but there can empty slots (for instance, only one controller with index 2 can be installed).
l Controller description – The name for this controller. A meaningful name is suggested. If not
specified, Interchange uses a name in the following format: Controller <index> on <host
name or IP>.
OFTP settings
l Hostname – If TCP, the fully qualified domain name or IP address of the OFTP server.
Click Next if you want to name the exchange. Otherwise, click Finish.
The user interface only allows selecting exchanges of unrestricted partners. For example, if your
user is associated with a role that restricts accessing partner X, any OFTP exchanges owned by
that partner are not available to share. However, if the exchange was shared before partner X
became restricted, the sharing partner can still use the shared exchange, but cannot view or
change the original exchange.
Click Next if you want to name the exchange. Otherwise, click Finish.
See the following figure: add OFTP V2 client in delivery exchange wizard.
OFTP settings
l Hostname – If TCP, the fully qualified domain name or IP address of the OFTP server.
l Port – The TCP port on which the server listens for connection requests. This field does not
apply to OFTP V1 X.25.
l SSID identification code – The start session identification (SSID) of the local or remote
party. Trading partners exchange SSIDs to identify each other in the protocol handshake and
session setup.
l OFTP protocol version – The protocol version.
l Require secure OFTP authentication – For OFTP V2 only, this is an extra layer of security to
enable senders and receivers to validate each other as genuine. There are two requirements to
enable secure OFTP authentication:
o Both the sender and receiver must enable secure OFTP authentication. If one party turns it
on and the other party does not, a protocol error is generated and the session between the
parties is disconnected.
o Both the sender and receiver must be using certificates. These are the normal certificates
used by a community and its partners to securely exchange messages. These are not TLS
certificates, which are additional certificates needed if TLS is configured for a delivery
exchange.
This is how the authentication works: The initiator of the connection uses the partner’s public
key to encrypt and send a short, random message to the partner. The partner decrypts the
message with its private key and sends the message back. The initiator compares the response to
the original message. If the messages match, the initiator has authenticated the partner. The
partner repeats the process to validate the initiator.
o Select a different encryption certificate for secure authentication – Select the
partner certificate to use for secure authentication other than the default certificate.
l Clients must use TLS to connect to this server – Select this to set up Transport Layer
Security for the OFTP delivery exchange. When selected, the following sub-field displays.
o Enable host name verification – If selected, Interchange compares the name of the TLS
server to the name in the server’s certificate to ensure they are the same.
If you use DMZ nodes, we recommend against selecting this. If host name verification is
enabled, messages may fail because the client is connecting to the DMZ node and not to
Interchange server.
l Set OFTP session password – Enter a password only when required. The password can be no
longer than eight alphanumeric characters and is case sensitive.
If this is an exchange for receiving messages from a partner, your community presents this
password to the partner. The password is compared to the one the partner has stored for your
community.
If this is an exchange for sending messages to a partner, the partner must present this password
to your community. The password is compared to the one your community has stored for the
partner.
In either case, the passwords must match to establish the connection.
Note If prompted, you can select a Secure Relay DMZ zone to route messages to the partner.
This option displays only for transports for sending to partners when your user license
supports Secure Relay and a DMZ zone has been added. For details, see Secure Relay DMZ
nodes on page 474.
Click Next if you want to name the exchange. Otherwise, click Finish.
Outbound messages
The following figure illustrates sending a message to a remote partner via X.25. The delivery is set
up in a partner object.
Outbound calls are made when you contact a remote partner that hosts an OFTP over X.25 server.
One router is associated to each partner delivery, but multiple deliveries can use the same router. For
simplicity, the figure shows only one router; the setup is the same for multiple routers.
The following are the types of connections that are made when sending a message to a remote
partner.
l The OFTP over X.25 producer establishes the control connection and requests an outgoing X.25
call to be placed to the remote NUA.
l Once the call has been placed, the connection is reused as a data connection. All OFTP over X.25
protocol frames are forwarded over TCP from and to the router, where they are exchanged with
the remote endpoint over X.25.
Monitoring connection
A monitoring connection is established on the SNMP UDP port defined in the router’s configuration.
Interchange uses this service to monitor the status of current connections. To make the connection,
Interchange has at least read access to the SNMP tables. This means a valid read-only community
password must be entered in the router’s configuration in Interchange user interface.
Inbound messages
The following figure illustrates receiving a message from a remote partner via X.25. The delivery is
set up in a community. The delivery uses an embedded OFTP server.
The previous figure shows a simple case with one embedded OFTP server per machine in a clustered
configuration of Interchange. Hosts A and B are two computers. Interchange cluster has three
processing nodes, two on host A and one on host B. As in a standard cluster, only one instance of
an embedded server is started on each host.
The following figure illustrates a more complex case of multiple embedded OFTP over X.25 servers,
using multiple routers. Two instances of Interchange are shown on the same host for clarity, but in a
cluster of multiple hosts the single distributed embedded server case applies to all embedded
servers.
Points of importance in the multiple case are:
l One embedded server uses only one router.
l Multiple embedded servers can use the same router, as long as they are not linked to the same
local NUA.
l There are as many local access points as there are embedded servers.
The following are the types of connections that are made when receiving a message from a remote
partner.
Control connection
A control connection is established on TCP port 146 on the router. Its role is to request the
establishment of an X.25 access point on the router, linked to a call-back port opened on
Interchange. Once established, it controls the lifespan of this listening point. When the control
connection is closed, so is the access point.
Monitoring connection
A monitoring connection has the same role as in outbound calls.
Data connection
Inbound messages are received over the data connection. When Interchange asks to establish an
access point on the router, it also locally creates an access point. Each inbound X.25 call is
transformed into its own separate TCP connection to this particular access point. Once the
connection has been established, data are routed between TCP and X.25 the same way as with
outbound calls.
X.25 terminology
NUA
Network user address identifies an X.25 endpoint. It can be local (corresponding to the
identity of one of the routers) or remote (designating a partner’s endpoint).
SNMP
Simple Network Management Protocol is for monitoring and managing network hardware.
Usually used over UDP on port 161 (port can be changed in the router’s configuration).
TP0 bridge
Service provided by the router, specified by RFC1086, to translate TP0-encapsulated
packets from TCP to X.25 and back. The service is associated with TCP port 146 on the
router (cannot be changed).
l Point-to-point. The ISDN call is made directly to the partner’s server, which has a compatible
OFTP over X.25 over ISDN server. X.25 routing is not needed, as the network is self-contained in
the ISDN connection.
l Point-to-multipoint. The ISDN call is made to a provider’s service that routes the X.25 frames
over the X.25 network. Providers are available in most countries, such as Transpac in France or
Datex-P in Germany. In that case, providing X.25 routing information is mandatory for the call
establishment to succeed.
The implementation of OFTP over X.25 over ISDN in Interchange complies with the RFC 5024
recommendations and only supports operating over the B-channel.
Usually transports user data (voice, fax, digital information).
B-ISDN
ISDN over B-channel is a standard for transmitting voice, video and data at the same time
over fiber optic telephone lines.
BRI interfaces
Two 64-kbps B-channels, and one 16-bps D-channel. (Exact values can vary from country
to country.)
D-channel
Usually dedicated to signaling information for the connections of B-channels. Some
countries support using D-channel to establish X.25 connection instead of the B-channel.
ISDN
Integrated Services Digital Network.
ISDN controller
A hardware port on the ISDN router where the physical ISDN line is connected. Each
controller acts as an ISDN modem.
ISDN interface
Depending on the need, the ISDN router hardware and the contract with the ISDN
provider, one ISDN line can be a BRI (basic rate interface) or a PRI (primary rate interface).
ISDN router
The required hardware that acts as a set of Ethernet-enabled ISDN modems.
PRI interfaces
Thirty 64-kbps B-channels and one 64-kbps D-channel. (Exact values can vary from
country to country.)
Remote CAPI
A service provided by the ISDN router that implements the industry standard CAPI
(Common ISDN API) over an Ethernet network.
Subscriber number
The number corresponding to an ISDN endpoint. Its format depends on the numbering
plan of the countries where the initiator and the responder are located.
X.25 requirements
Using the OFTP V1 over X.25 or over X.25 over ISDN requires a router to bridge the TCP and X.25
networks. Both transports have been tested with Funkwerk router models R4300 and X8500.
For the CAPI service connection for X.25 over ISDN:
l Source – All Interchange hosts, random port
l Destination – All ISDN routers, TCP port 2662 (unless changed)
1. Add an OFTP V1 over X.25 delivery exchange in a community and a partner. See OFTP transport
configuration on page 617.
2. If necessary, add or change the configuration of a router. See Add or edit an X.25/B-ISDN
router on page 635.
3. If necessary, fine-tune delivery exchange settings. See Modify an OFTP pickup or delivery on
page 637.
4. If necessary, fine-tune the embedded server settings. See OFTP (embedded) fields on page
461.
X.25 troubleshooting
To generate debug-level events related to OFTP delivery exchanges:
1. Set the following property in the log4j.properties file to debug:
log4j.category.com.cyclonecommerce.tradingengine.transport.oftp=info
2. Add the following property to the file:
log4j.category.com.cyclonecommerce.businessprotocols.oftp2=debug
The log4j.properties file is at <install directory>\conf. See Troubleshooting with the
log4j file on page 1095 for more information about using the file.
For OFTP V1 delivery exchanges the statistics monitor also can generate information useful in
troubleshooting.
General tab
l Friendly name – The name of this router. A meaningful name is suggested. If not specified,
Interchange uses a name in the following format: Router on <host name or IP>.
l Host – The fully qualified domain name or IP address of the internal interface of the router. It
must be accessible from all Interchange nodes.
l X.25 enabled – Select this check box for the router to access an X.25 network. Complete or
edit the associated fields.
o Maximum concurrent outbound connections – The maximum number of outbound
X.25 logical connections that can be made by this router. This is tied to the X.25 network’s
number of allowed virtual channels and bandwidth.
As the virtual channels are used for inbound and outbound connections, and OFTP requires
receipts to be delivered, be careful when specifying this value. For example, if the maximum
number of channels is 10, set this value to 4. This makes sure at least 6 channels stay
available for receipts and inbound connections, if any.
o SNMP community password – The SNMP password with at least read-only rights over the
SNMP tables in the router.
o Confirm password – The password entered again.
l Change SNMP community password – Select this check box to show fields for entering a
new password. This check box displays only when editing router configuration, not when
adding one.
l B-ISDN enabled – Select this check box for the router to access an ISDN network using the B-
channel. Complete or edit the associated fields.
o Capi Port – The TCP port for the remote CAPI service on the router. This is used to remotely
control the ISDN features of the router. The factory default value for the R4300 is 2662.
o Controller index – The physical number of the ISDN controller within the router, which is
roughly equivalent to a physical ISDN modem connected to one ISDN line. Numbering starts
at 1, but there can empty slots (for instance, only one controller with index 2 can be
installed).
o Description – The name for this controller. A meaningful name is suggested. If not
specified, Interchange uses a name in the following format: Controller <index> on
<host name or IP>.
o Maximum concurrent outbound calls – The maximum number of outbound ISDN
physical calls that can be made on the B-channels by this controller. This is tied to the ISDN
network’s number of B-channels (2 for BRI, 24 or 30 for PRI). As the B-channels are used for
inbound and outbound calls, and OFTP requires receipts to be delivered, be careful
specifying this value. For example, if the maximum number of B-channels is 2, set the value
to 1 to make sure at least 1 channel is available for receipts and inbound connections, if any.
Advanced tab
The following fields are available only when editing a router configuration, not when adding one.
The maintenance pages display the transport fields that can be changed, while the delivery or
pickup exchange wizard has only the most commonly used. The following are the fields on the
settings and advanced tabs.
For general information about pickup and delivery maintenance see:
l Modify an application pickup or delivery on page 202
l Modify a trading pickup on page 326
l Modify a partner trading delivery on page 327
The fields for configuring OFTP V1 and OFTP V2 are the same, except as noted.
Field descriptions:
l Embedded OFTP and OFTP TLS settings tab (community) on page 638
l Embedded OFTP X.25 and embedded OFTP X.25 over ISDN settings tab (community) on page
639
l OFTP and OFTP TLS settings tab (partner) on page 639
l OFTP and OFTP TLS settings tab (partner) on page 639
l OFTP X.25 settings tab (partner) on page 641
l OFTP X.25 over ISDN settings tab (partner) on page 642
l OFTP shared settings tab (partner) on page 642
l Sharing partners tab (partner) on page 643
l Advanced tab (community) on page 643
l Advanced tab (partner) on page 644
l Advanced tab for X.25 (partner) on page 646
l Advanced tab for X.25 over ISDN (partner) on page 647
l OFTP polling settings tab (community) on page 650
l Advanced tab (OFTP polling) on page 650
If this is an exchange for sending messages to a partner, the partner must present this password
to your community. The password is compared to the one your community has stored for the
partner.
In either case, the passwords must match to establish the connection.
Embedded OFTP X.25 and embedded OFTP X.25 over ISDN settings
tab (community)
l Server name – The name for the embedded OFTP server. This can be any name you want.
l View settings for this embedded server – Click this link to manage the embedded server.
For details, see the embedded transport servers chapter.
l Connection string used by partners – When you export your community profile as a
partner profile and give it to partners, this is the string partners use to connect to your
embedded server. If your network uses a load balancer or a firewall, you may need the help of
your network administrator to edit this field.
l SSID identification code – The start session identification (SSID) of the local or remote
party. Trading partners exchange SSIDs to identify each other in the protocol handshake and
session setup.
l OFTP protocol version – The protocol version being used (1.3 or 1.4).
l Partner uses RFC 2204, not RFC 5024 – For OFTP V1 only when protocol version is 1.3,
this check box tells Interchange the protocol release level (SSIDLEV) to use for the trading
partner. Select the check box if the partner uses the RFC 2204 implementation. This means the
SSIDLEV field in the start session (SSID) command has a value of 1. Do not select the check box
if the partner uses the RFC 5024 implementation. This means the SSIDLEV field in the SSID
command has a value of 2. (Note that in either case the exchange point is being defined for
OFTP protocol revision level 1.3.)
l Set OFTP session password – Enter a password only when required. The password can be no
longer than eight alphanumeric characters and is case sensitive.
If this is an exchange for receiving messages from a partner, your community presents this
password to the partner. The password is compared to the one the partner has stored for your
community.
If this is an exchange for sending messages to a partner, the partner must present this password
to your community. The password is compared to the one your community has stored for the
partner.
In either case, the passwords must match to establish the connection.
If this is an exchange for sending messages to a partner, the partner must present this password
to your community. The password is compared to the one your community has stored for the
partner.
In either case, the passwords must match to establish the connection.
The tab displays a link to the delivery exchange being shared. The link includes the name of the
partner that owns the exchange point. Click the link to display the original delivery exchange. If the
name is not an active hyperlink, you do not have permissions to view or change the original delivery
exchange.
The Advanced tab for a shared delivery exchange only displays the fields the sharing partner can
change. Other advanced settings only can be changed by changing the Advanced settings in the
original delivery exchange. If your user is associated with a role that restricts access to partners, it is
possible you may lack permissions to change settings of the original delivery exchange.
The tab lists the names of the other partners who also use the exchange. If the exchange is not
being shared, no partners are listed. Click the name of the partner to go to the partner’s
maintenance page for the shared delivery exchange.
If the delivery exchange is shared, any changes on the OFTP settings tab or to settings on the
Advanced tab unique to the original exchange also affect any partners that share the exchange. In
addition, an exchange that is shared cannot be deleted unless the exchanges of the sharing partners
are deleted first.
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners.
Backup files are stored in \<install directory>\common\data\backup, unless you
specify otherwise.
l Restrict maximum file size for this transport – Optionally lets you specify the maximum
size of files a transport can handle.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log. If received via HTTP, a 413 response also is sent and the connection is
closed. A 413 message is Request Entity Too Large.
The maximum size must be expressed in bytes. Do not use commas. For instance, a kilobyte is
1024 bytes, a megabyte is 1048576 bytes, a gigabyte is 1073741824 bytes.
The smallest maximum allowed is 1000 bytes. On the opposite extreme, you can enter the
largest number the field can accommodate.
This control is available only for transports used for picking up messages from integration or
receiving messages from partners.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Read timeout (seconds) – The maximum number of seconds the server waits when reading
data from a partner.
l Credit counter – The number of consecutive data exchange buffers sent by the speaker before
it must wait for a credit (CDT) command from the listener.
The credit value is only applied to data flow in the data transfer phase.
The speaker's available credit is initialized to SSIDCRED when it receives a start file positive
answer (SFPA) command from the listener. It is zeroed by the end file (EFID) command.
After negotiation, the smallest size must be selected in the answer of the responder or a protocol
error aborts the session.
l Data exchange buffer – The length in octets of the largest acceptable data exchange buffer.
The length includes the command octet, but not the stream transmission header. After
negotiation, the smallest size is selected. The value in this field maps to the SSIDSDEB field in
the SSID OFTP protocol command.
l Override local SSID code and password – Select this check box to have this partner
exchange use an SSID code and password different than the values set on a community’s OFTP
delivery exchange. If selected, you must enter the override SSID code. Entering an override
password is optional. This password overrides the password in the field named “This server
requires a session password,” which is an optional field for a community OFTP delivery
exchange.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners.
Backup files are stored in \<install directory>\common\data\backup, unless you
specify otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for community integration delivery exchanges and partner
trading delivery exchanges.
l DMZ Zone – If you use DMZ nodes and want to send or receive messages via a specific DMZ
zone, select the zone. This field is available only when the user license supports Secure Relay and
a DMZ zone has been added. For details, see Secure Relay DMZ nodes on page 474.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o An OFTP protocol error occurred. For example, the partner returned a negative response to a
query on whether to start the file transfer.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Packet size – For OFTP X.25, the size of the X.25 packet. If the value is blank the network’s
default value is used. You must enter a hexadecimal value.
l Window size – For OFTP X.25, the number of X.25 packets that can be sent without
acknowledgment. If the value is blank the network’s default value is used. You must enter a
hexadecimal value.
l Credit counter – The number of consecutive data exchange buffers sent by the speaker before
it must wait for a credit (CDT) command from the listener.
The credit value is only applied to data flow in the data transfer phase.
The speaker's available credit is initialized to SSIDCRED when it receives a start file positive
answer (SFPA) command from the listener. It is zeroed by the end file (EFID) command.
After negotiation, the smallest size must be selected in the answer of the responder or a protocol
error aborts the session.
l Data exchange buffer – The length in octets of the largest acceptable data exchange buffer.
The length includes the command octet, but not the stream transmission header. After
negotiation, the smallest size is selected. The value in this field maps to the SSIDSDEB field in
the SSID OFTP protocol command.
l Override local SSID code and password – Select this check box to have this partner
exchange use an SSID code and password different than the values set on a community’s OFTP
delivery exchange. If selected, you must enter the override SSID code. Entering an override
password is optional. This password overrides the password in the field named “This server
requires a session password,” which is an optional field for a community OFTP delivery
exchange.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners.
Backup files are stored in \<install directory>\common\data\backup, unless you
specify otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for community integration delivery exchanges and partner
trading delivery exchanges.
l DMZ Zone – If you use DMZ nodes and want to send or receive messages via a specific DMZ
zone, select the zone. This field is available only when the user license supports Secure Relay and
a DMZ zone has been added. For details, see Secure Relay DMZ nodes on page 474.
The default value is suitable in almost all cases. However, if a partner says your Interchange is
overrunning his receiving system, decrease the value. (This advice does not apply to OFTP X.25
or X.25 over ISDN, as the default maximum value is 1 for those transports.)
If sending messages to Transfer CFT via PeSIT, the value in this field must be less than the
CFTTCP setting in Transfer CFT.
This setting applies only to transports that send messages to partners or deliver messages to
integration.
l Retries – This is the number of times Interchange will retry connecting to the partner’s
transport if the initial attempt to connect and send the message failed. The following are
common reasons for triggering retries.
o The connection attempt failed immediately for a reason such as host not found.
o The host was found, but the connection process took longer than the connect timeout
interval specified on the Advanced tab.
o An OFTP protocol error occurred. For example, the partner returned a negative response to a
query on whether to start the file transfer.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Local ISDN number – The ISDN number identifying the caller (the instance of Interchange).
Depending on the telecom operator’s configuration, you must set this to your number or let the
telecom equipment fill it in for you.
l Limit bandwidth to 56 kbps – Select this when a provider uses 56 kbps-bit transparent
operation with byte-framing from the network as its physical layer protocol instead of the default
64-kbps with HDLC framing. For such cases, this check box must be selected for the ISDN
connection to be properly established.
l Layer 2 window size – Specifies how many layer 2 (ISO 7776) packets can be sent before an
acknowledgment is required from the partner. If blank, use the network’s default value.
l Layer 3 window size – Specifies how many layer 3 (ISO 8208) packets can be sent before an
acknowledgment is required from the partner. If blank, use the network’s default value.
l Layer 3 packet size – Specifies the size of the layer 3 packets. If blank, use the network’s
default value.
l Lowest incoming channel – The starting value for the incoming channels identifier counter.
If blank, use the network’s default value.
Backup files are stored in \<install directory>\common\data\backup, unless you
specify otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for community integration delivery exchanges and partner
trading delivery exchanges.
l Zone – If you use DMZ nodes and want to send or receive messages via a specific DMZ zone,
select the zone. This field is available only when the user license supports Secure Relay and a
DMZ zone has been added. For details, see Secure Relay DMZ nodes on page 474.
PeSIT
Interchange trading communities can use the PeSIT message protocol to exchange files with back-
end applications and with remote trading partners.
PeSIT is an abbreviation for Protocole d'Echange du Système Interbancaire de Télécompensation.
In English this translates as "Inter-bank electronic payment system protocol". For more information
about PeSIT, see http://www.pesit.com/US/Default.htm.
The PeSIT protocol exists in several profiles: (SIT, Hors SIT), in several versions (PeSIT D, PeSIT E)
and in sub-versions that correspond to the supported network type (TCP/IP, X25, …). The version
of PeSIT handled by Interchange is PeSIT HSE (PeSIT Hors SIT version E).
PeSIT is a very effective and secure protocol for transferring files. Notable features of PeSIT are:
l Checkpoint indicators to ensure that a transfer can be restarted from a point near the point of
interruption, in the event of a transfer error
l Transfer of metadata along with a payload
l Acknowledgments, compression, priority, file naming, file format control
l TLS security support
Interchange supports exchanges with any back-end or remote-partner application that supports
PeSIT HSE.
l If you also have a Peer Networking license, note that additional routing IDs added to PeSIT
pickups on the main system are not cloned. They must be manually added to the backup system
or the mail trading may, in some cases, fail.
Back-end configuration
To configure Interchange for PeSIT exchanges with applications, you create the following objects:
l Community – Specifies the characteristics of Interchange as an exchange partner. In this object
you specify internal processes for handling messages and define how Interchange expects to
receive messages from the back-end and from trading partners.
l Partner – Specifies the characteristics of a remote partner with which Interchange can trade
(send and/or receive).
l Application Delivery – Specifies how Interchange sends messages to an application. You
require a PeSIT type application delivery for each application you want to send messages to
using PeSIT.
When you create the application delivery you:
o Select PeSIT as the protocol type. This enables the embedded PeSIT client process to handle
sending of files to the application.
o Identify the host name and access port of the target application.
o Specify the identity of Interchange as a sender (caller ID) and the identity of the receiving
back-end (server ID). If Transfer CFT is your back-end PeSIT application, then Interchange
caller ID = CFT nrPart, Interchange server ID = CFT nsPart.
l Application Pickup – Specifies how Interchange receives messages from an application.
When you create this object you:
o Select PeSIT as the protocol type. This enables the Interchange-embedded PeSIT server
process to handle the reception of files from the application.
o Set the name and listening port of the Interchange-embedded PeSIT Server that receives
messages from the application. You must also provide these server and port values to the
sending application.
Once Interchange receives a file from an application using PeSIT, it can forward the file to a remote
trading partner using any of its available protocols.
l Community – Specifies the characteristics of Interchange as an exchange partner. In this object
you specify internal processes for handling messages and define how Interchange expects to
receive messages from the back-end and from trading partners.
l Trading Pickup Exchange – Specifies how Interchange receives messages from remote
trading partner applications. You add the trading pickup to the Community object.
l Partner – Specifies the characteristics of a remote partner with which Interchange can trade
(send and/or receive).
You create as many partners as you require, each with a specific set of trading characteristics.
l Trading Delivery Exchange – Specifies how Interchange sends messages and files to a
specific remote trading partner application. You associate the partner delivery with a specific
partner object to identify both the partner identity and the protocol to use when sending files to
that partner.
Once Interchange receives a file from a remote trading partner using PeSIT, it can forward the file to
an application using any of its available protocols.
Interchange uses the application pickup to collect the message. It then forwards it to the correct
remote partner, using information specified in the partner and trading delivery exchanges.
In this example the transport protocol on the partner side is not specified. It is possible to use PeSIT
for trading on the partner side as well as on the application side. To do this, you would configure
the partner trading delivery to trade using PeSIT.
In this example the transport protocol on the partner exchange side is not specified. it is possible to
use PeSIT for trading on the partner side as well as on the application side. To do this, you would
configure the community trading pickup to trade using PeSIT.
l Delivery exchanges
l Pickup exchanges
l Polling exchanges
Each of these exchange types are available for exchanging files with both applications and remote
trading partners.
Each or these exchange types can be configured over clear or secured TLS connections.
The following sections describe the characteristics and functions of PeSIT exchanges.
Delivery Send
Fetch
–
Pickup Polling
Multi-community
Respond to fetch
Common Restarts
Metadata
attachments
TLS handling
Ack handling
Pickup exchange Protocol IDs (PI3 and PI4)
identifier
l Initiator-Sender role (back-end integration and partner trading)
This is the default role for PeSIT delivery exchanges.
The delivery exchange extracts the file and attributes from the message and sends them to a
remote PeSIT Server (using PeSIT CREATE). If some attributes are missing, default values will be
taken from the delivery settings. Any additional missing attributes are taken from the delivery
exchange configuration settings.
l Initiator-Receiver role (partner trading only)
If you he message Action attribute equals Fetch, the delivery exchange extracts the attributes
from the message, builds a fetch request (PeSIT SELECT) and sends the request to the remote
server.
If any attributes are missing, default values are taken from the delivery exchange configuration
settings.
If a file on the remote server corresponds to the request (File name and File type), the file is
returned. This triggers creation of a new incoming message in Interchange, assigned to the
matching community’s PeSIT server. The attributes from the request are used and updated with
the effective transfer characteristics (File name, File type, Transfer Id and so on). The payload is
included as a file.
If no file is available on the remote server, no incoming message is generated
For details about how to configure, view and modify PeSIT exchanges, see Manage PeSIT pickups
and deliveries on page 659.
When you create a PeSIT pickup on the application side, the pickup is shared between
communities.
When you create a PeSIT pickup on the trading side, the pickup is not shared between the
communities. It is dedicated to a single community.
A PeSIT pickup exchange operates in one of two roles:
l Responder-Receiver (back-end integration and partner trading)
In this role, the PeSIT pickup:
1. Responds to a client (caller) connection and checks that:
o The PeSIT server identifier (PI4) corresponds to a routing ID of the community.
o On the trading side only, the PeSIT caller identifier (PI3) must correspond to a
routing ID of a partner that is linked to that community and that has a PeSIT
delivery configured. It’ll use the parameters of both pickup and delivery exchanges
for the verification (password…). If the verification fails, the PeSIT connection will
be refused immediately
2. Creates a new incoming message
3. Fills the message with the metadata received through the PeSIT CREATE
4. Receives the payload and attaches it as a file to the message
l Responder-Sender (back-end integration and partner trading)
In this role, the PeSIT pickup:
1. Responds to a client (caller) connection and checks that:
o The PeSIT server identifier (PI4) corresponds to a routing ID of the community.
o On the trading side only, the PeSIT caller identifier (PI3) must correspond to a
routing ID of a partner that is linked to that community and that has a PeSIT
delivery configured. It’ll use the parameters of both pickup and delivery exchanges
for the verification (password…). If the verification fails, the PeSIT connection will
be refused immediately
2. Reads a PeSIT SELECT request. It looks for a message in the HeldForPickup state that
matches the SELECT criteria.
3. If it finds one, it takes the oldest matching message and produces it over the delivery
exchange of the partner.
4. If it doesn’t find a matching message, it returns a standard PeSIT “No file” response to
the caller.
For the server to act in the Responder-Sender role, you must prepare messages in the
HeldForPickup state, so that there is content a remote client can fetch. There are two ways to do
this:
o Select the option Hold all outbound messages for pick up by the remote client
option on the delivery exchange.
o Set the message.HoldForPickup attribute to true. This attribute will override the delivery
exchange setting.
In this case, the message is sent to the partner or the back end, but with the "Hold for pickup"
option set. The message stops just before sending and remains (with all necessary information),
ready for the intended partner or back end application to pick it up.
For procedures on how to add PeSIT pickup exchanges of the non-polling type, see:
l Add or modify a PeSIT application pickup (embedded server) on page 667
l Add or modify a PeSIT trading pickup ( embedded server) on page 689
For details about how to configure, view and modify all PeSIT exchanges, refer to Manage PeSIT
pickups and deliveries on page 659.
l On the application side, dedicated to a community (this is an exception due to PeSIT’s need for
party identification)
l On the partner trading side, attached to a community
Plays Initiator-Receiver role on both sides
The polling pickup always polls the same pattern of files for the same community and partner/back
end pair. You need to set one polling pickup per type of polling you want to do.
You can use the wild card “*” when you specify the file name to pickup, to select multiple files.
l If the polled server has a file that matches the pattern of the polled file, the server sends the file
to the Interchange polling pickup. The polling pickup:
o Creates a new incoming message,
o Fills the incoming message with the metadata received through the ACK SELECT
o Receives the payload and attaches it as a file to the message.
The polling session continues until either:
l The polled server has no matching file
l The polling pickup reaches the Maximum files per polling interval setting
The next polling session starts after the polling interval specified in the exchange configuration (if
within the scheduled time window).
For procedures on how to add polling-type PeSIT pickups, see:
l Add or modify a PeSIT application pickup (polling client) on page 670
l Add or modify a PeSIT trading pickup (polling client) on page 684
For details about how to configure and modify all PeSIT exchanges, refer to Manage PeSIT pickups
and deliveries on page 659.
When you back up a community, application side PeSIT polling pickups are not backed up. They
are handled by the back-up tool as if they are "normal" pickups that belong to any community.
l Add or modify a PeSIT application pickup (embedded server) on page 667
l Add or modify a PeSIT trading pickup ( embedded server) on page 689
l Add or modify a PeSIT application pickup (polling client) on page 670
l Add or modify a PeSIT trading pickup (polling client) on page 684
Prerequisite
You must have a community. If you need to add a community, see Add a community on page 136.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
3. Click Application delivery in the navigation graphic to open the Application delivery
exchanges page.
4. Click Add an application delivery exchange to open the Exchange Wizard.
5. Choose the PeSIT transport protocol and click Next.
6. Complete fields of the Configure PeSIT client settings page.
l Hostname – The IP address or the network name of the back-end PeSIT server to connect
to. This must be the fully qualified domain name or IP address of the PeSIT server your
community connects to for sending messages.
l Port – The port on which the back-end PeSIT server listens for connection requests.
l Hold all outbound messages for pickup up by the remote client:
o Not selected: The messages sent to this delivery are produced and sent to the server.
o Selected: The messages sent to this delivery stop in HeldForPickup state, and are
available for the remote client to fetch.
l Server settings – In this section you set the back-end server’s protocol identity (PI4).
o Use the final destination ID from the message – Select this option to have
Interchange read pesit.finalDestinationId.out (which corresponds to PI62),
and use it as PI4.
o Use this identifier, PeSIT Identifier (PI4) – If you select this option, you must
then enter a specific identifier for PI4. This value must correspond to the value used by
the application to identify the server.
o Use password (This is the password expected from the server) – Select this
option if you expect an authentication from the back-end server.
l Clients must use SSL to connect to this server – If the back-end server is configured
to transfer over SSL/TLS. You must import the root certificate of the remote server to the
community trusted SSL root certificates.
o Enable host name verification – If you select this option, Interchange verifies that
the name of the server is the same as the name in the server’s certificate. This requires
that you import the server certificate chain in the partner’s personal certificates and then
select the option Trust this for SSL server and/or client authentication.
Interchange automatically adds the root certificate to the linked communities' trusted
SSL root certificates.
If you do not select this option, Interchange only verifies that the server certificate is
signed by a certificate that is among the community trusted SSL root certificates.
o Enable CFT compatibility – When you select this option, Interchange aligns the
PeSIT record size on TLS packets. This is the only method handled by Axway Transfer
CFT before version 3.0, and is the default method for the Axway products Gateway and
Interpel.
If you do not select this option, Interchange adds the record size as a header of the
record, as for non-TLS communications. This is the default and the recommended
handling (when the remote application supports it).
7. Enter a name for the exchange to identify it in the user interface.
8. Click Finish.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
3. Click Application delivery in the navigation graphic to open the Application delivery
exchanges page.
4. From the list of available exchanges, click the name of an exchange to open the maintenance
page for that exchange.
5. View and modify fields as required. The fields are described in the following section.
Use this tab to modify the basic default PeSIT parameters for this delivery exchange. These values
are only used if no corresponding attribute is found in the message.
The initial settings that are displayed on this tab represent the default settings for the protocol. If
you change any settings on this tab, you replace the protocol defaults.
If you use any of the supported PeSIT metadata elements in a message handler action or other
process, those elements will override the settings on this tab. For example, if you use the
pesit.filelabel metadata element in a message handler action, that setting overrides the setting on
this tab for Filename (nfname). For a list of the PeSIT metadata elements, see Metadata definitions
on page 414.
l File name (PI12) – Name of the file, forced to uppercase at runtime. Often, the real name of the
file is shipped in File label.
Maximum length = 76 characters. If the name is longer, it is truncated to 71 characters and
prefixed with a unique 4 digit counter in the format xxxx_<71 first char of filename>.
At runtime, the file name takes the first non-empty value from the following list:
o pesit.filename.out
o UI value
o pesit.filename.in
o pesit.filelabel.out
o « NOT-SPECIFIED » – if nothing was set
l File type (PI11) – This is the file type, which is used by some monitors. The default value is 0.
If pesit.filetype.out is set in the message, at runtime it overrides the value you set in this
UI field.
l File label (PI37) – Logical name of the file.
Maximum length = 80 characters. If the label is longer, it is truncated to 76 characters and
prefixed with a unique 3 digit counter in the format xxx_<76 first char of filelabel>.
At runtime, the file label takes the first non-empty value from the following list:
o pesit.filelabel.out
o UI value if Use original is not selected
o Production file name
o Consumption file name
l Expect acknowledgments – Select this option if you expect the remote application or partner to
send a receipt to acknowledge receiving each message sent. In this case, the message is marked
"to be acknowledged", until the remote sends the expected acknowledgment.
You can additionally select whether to Support negative acknowledgments.
l Free text (PI99) – Free text often used to transfer metadata.
Maximum length = 4096 characters
If pesit.serviceParam.out is set in the message, at runtime it overrides the value you set in
this UI field.
l Data encoding (PI16) – Text for ASCII files, and Binary for all others (including EBCDIC).
Protocol values: Text = 0 , Binary = 2
If pesit.fileEncoding.out is set in the message, at runtime it overrides the value you set in
this UI field (the attribute uses the numeric value).
l Record format (PI31) – Select Fixed for fixed length records and Variable for variable length
records
Protocol values: Fixed = 0, Variable = 128
If pesit.recordFormat.out is set in the message, at runtime it overrides the value you set in
this UI field (the attribute uses the numeric value).
If you set an On the Fly transformation, the transformation overrides
pesit.recordFormat.out
l Record length (PI32) – Record length for fixed records, or maximum record length for variable
records.
If pesit.recordLength.out is set in the message, at runtime it overrides the value you set in
this UI field.
If you set an On the Fly transformation, the transformation overrides
pesit.recordLength.out.
l Compression (PI21) – Controls the compression of the file during the transfer (compression on
the fly). Select a compression method:
o None (0) – (default) No compression.
o Horizontal (1) – Compresses the consecutive identical characters in the records.
o Vertical (2) – Records are compared to one another and the consecutive identical columns
are compressed.
o Both (3) – Combination of the above two compression methods.
If pesit.compressionType.out is set in the message, at runtime it overrides the value you
select in this UI field (the attribute uses the numeric value).
Note: The compression is negotiated between the caller and the server. If the server can’t handle
the compression setting, a lower type of compression or no compression is applied.
l Priority (PI17) – Select an option:
o High (0) – Highest priority
o Medium (1) – Default
o Low (2) – Lowest priority
If pesit.priority.out is set in the message, at runtime it overrides the value you set in this
UI field (the attribute uses the numeric value).
Advanced tab
This tab is identical for PeSIT application delivery and for PeSIT trading d elivery exchanges.
Note: This tab enables you to view and modify advanced parameters. In most cases the default
values are the correct values. Do not modify values without first consulting with the administrator of
the remote server.
number across the entire cluster, no matter how many JVM nodes are running. For example, if
the value is 100 connections and there are 150 messages to send, Interchange opens only 100
connections to that partner. The remaining 50 messages are queued until connections become
available. The default value is suitable in almost all cases. However, if a partner says your
Interchange is overrunning his receiving system, decrease the value. This setting applies only to
transports that send messages to partners or deliver messages to back-end applications.
PeSIT tries to reuse open sessions so that connections are not closed and reopened too often.
If you are sending files to Axway Transfer CFT, the value in this field must be less than the
CFTTCP setting in Transfer CFT.
l Retries – The number of times Interchange retries connecting to the back-end application if the
initial attempt to connect and send the message fails.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
l Destination file size delta for transformed files (+/- in %) – If you configure an “on
the fly” transformation, you can use this setting to adjust the file size info sent with the PeSIT
CREATE order. That is because the “on the fly” transformation changes the file size while
sending. If no transformation is configured, this value is ignored.
Considerations:
o This value applies only for size units in Kb (PI41=0), and not in records (PI41=1)
o This value is useful for receivers that run on a system that needs to pre-allocate the file on the
disk (not Windows or UNIX). Because these systems allow a margin, the file size info can be
approximate.
o The sent file size is: local file size * (1 + percentage/100) (rounded to Kb and put in PI42).
o If the transformed file is likely to be bigger than the original file, enter a positive percentage.
o If the transformed file is likely to be smaller than the original file, enter a negative
percentage.
o In most situations, you can accept the default value 0.
l Max data unit size in bytes (PI25) – The largest of chunk of data, in bytes, to be
transferred at one time. For high-speed networks, use the default 3 2700 bytes.
This value is related to the client setting for record length on the PeSIT parameters tab.
The value of this field must be the same or larger than the value of the record length field. Do
not change this value unless advised by the administrator of the back-end PeSIT application you
are trading with.
l Synchronization option (PI7) –
o Intervals between sync points (Kbytes): – Each time an amount of data equal to this
value has been sent, the client is expected to ask the server to confirm whether data totaling
this value has been received. The server responds optionally with a confirmation. This
represents a check point in the progress of a file transfer. If a connection is lost before a file
transfer has been completed, the transfer resumes, upon restart of the transport, at the point
of the last successful check point.
The default value is 1024 kilobytes (1 megabyte).
This setting corresponds to the pacing setting in Axway Transfer CFT.
o Sync acknowledgement window – The number of check-point cycles that the client
waits for the server to respond to a request to confirm file-transfer progress.
For example, if the value of Kb per sync point (pacing) is 1024 (1 megabyte) and the value
of this field is 1, the client stops sending data after 1024 kilobytes unless the server
responds, although the transfer remains active.
If this value is 2, the client keeps sending until 2 megabytes (1024 x 2) of data are sent, and
so on.
If the client’s value for this field is 0 (zero), the client does not ask the server to confirm at
intervals the amount of data received.
If the server’s value for this field is 0, the server does not send confirmations at intervals of
data received.
The default value is 3. In most situation this is the correct value.
This setting corresponds to chkw setting in Axway Transfer CFT.
l Read timeout (seconds) – Time in seconds Interchange waits to read data from the delivery
exchange before terminating the connection.
l Connection timeout (seconds) – PeSIT Tc timeout. The time the caller waits for a
connection acknowledgment from the server.
Of the many algorithms for encrypting data and computing the message authentication code,
there are varying levels of security. Some provide the highest levels of security, but require a
large amount of computation for encryption and decryption. Others are less secure, but provide
rapid encryption and decryption. The length of the key used for encryption affects the level of
security. The longer the key, the more secure the data.
The option for overriding cipher suites lets you select the level of security that suits your needs
and enables communicating with others who might have different security requirements. For
example, when an SSL connection is established, the client and server exchange information
about the cipher suites they have in common. Then they communicate using the common
cipher suite that offers the highest level of security. If they do not have a cipher suite in
common, secure communication is not possible.
In versions of Interchange earlier than Interchange 5.9, cipher suites configuration was handled
by a file named sslciphersuites.xml. As data in that file is saved in the database, the
custom cipher suites configuration is retained upon upgrading and is displayed in the Selected
list under the option in the user interface. The sslciphersuites.xml file is no longer used.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners. Backing up files.
This is required for the system to perform fail-over operations such as attempting to send
messages again (retries) in case of a transport connection failure. Without backups, a message
in process cannot be recovered if the server or a processing node stops or restarts. Backups are
needed to resubmit messages to applications or resend messages to partners.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for community integration delivery exchanges and partner
trading delivery exchanges.
Prerequisite
Add a community. For details, see Add a community on page 136.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage application
pickup exchanges.
2. Click Add an application pickup exchange to open the exchange wizard.
3. Select PeSIT and click Next.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
3. Click Trading pickup in the navigation graphic to open the Delivery exchanges page.
4. From the list of available exchanges, click the name of an exchange to open the maintenance
page for that exchange.
5. View and modify fields as required. The fields are described in the following section.
6. After making any modifications, click Save changes.
o Click on the ellipsis button ( ...) to select the community that sends the acknowledgment,
and then select the connection string that corresponds to the back-end server which should
receive the acknowledgment. This is how you select the delivery exchange that is used to
send the acknowledgement.
An acknowledgment is sent to the Sender/Server pair, when the reception is completed and the
corresponding incoming message is successfully unpackaged. This means that it is a protocol
acknowledgment (Interchange received the file). A receipt message is generated and sent
through the selected integration delivery exchange.
Advanced tab
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from the back end. This is required for the system to perform
fail-over operations such as attempting to send messages again (retries) in case of a transport
connection failure. Without backups, a message in process cannot be recovered if the server or a
processing node stops or restarts. Backups are needed to resubmit messages to back-end
applications or resend messages to partners.
l Restrict maximum file size for this transport – Select this option to specify the maximum
size of files a the exchange can handle.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log.
l Maximum file size – Enter the maximum file size in bytes. Do not use commas.
Unlike embedded server application pickups, each polling application pickup is dedicated to a single
specific community. That is because PeSIT exposes the caller and the server identity in every polling
connection.
Prerequisite
You must have a community. If you need to add a community, see Add a community on page 136.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
3. Click Application pickup in the navigation graphic to open the Application pickup exchanges
page.
4. Click Add an application pickup exchange.
5. Choose the transport protocol PeSIT and click Next.
6. Select the From address and To address that match your needs. These pages are common
to all application pickup exchanges.
7. Select Define a new PeSIT polling client and click Next.
8. Complete the fields of the Configure the PeSIT client settings page.
l Hostname – Enter the IP address or the network name of the back-end PeSIT server to
poll.
l Port – Enter the Port on which the back-end PeSIT server listens.
l Community settings (caller) – These fields determine the identity the caller uses to poll
the back-end server.
o PeSIT Identifier (PI3) – Use the Pick requester ID button to select the
community routing ID to use as the caller ID.
o Use password – Use this option to enter a password if the back-end server expects
one.
l Server settings
o PeSIT Identifier – Enter the PeSIT PI4 server ID of the back-end server.
o Use password – Select this option if you want the server to provide a password to
connect to your community. Enter the required password.
l File name (PI12) – Enter the name of the file you want to poll from the server. Use a
wildcard character (*) at the end of a character string to select all files starting with those
characters.
l Clients must use SSL to connect to this server – Select this option if the back-end
server is configured for exchanges over SSL/TLS. You must import the root certificate of the
remote server to your community’s trusted SSL root certificates.
o Enable host name verification – If you select this option, Interchange verifies that
the name of the server is the same as the name in the server’s certificate. If you don’t
select this option, Interchange only verifies that the server certificate is signed by a
certificate that is included in the community trusted SSL root certificates.
o Enable CFT compatibility
When selected, Interchange aligns the PeSIT record size on TLS packets. This is the only
method handled by Transfer CFT until version 3.0, and the default method for Gateway
and Interpel.
When unselected, Interchange adds the record size as a header of the record, as for non
TLS communications. This is the default, which is recommended.
9. Enter a name for the exchange to identify it in the user interface. Hint: Enter a name that is
easily identifiable in a list of exchanges in the user interface.
10. Click Finish.
Because the polling pickup must expose its identity to the polled server, it must be linked to a
community.
If you do not select this option, Interchange adds the record size as a header of the record,
as for non TLS communications. This is the default and the recommended handling (when
the remote application supports it).
l Community settings (caller) – These fields determine the identity that Interchange uses to
poll the back-end server.
o PeSIT Identifier (PI3) – Use the Pick requester ID button to select the community for
which the polling is done, and then select the routing ID to use as the caller identifier
o Use password – Select this option if the back-end server expects you to provide a
connection password. Enter your password to connect to the back-end server.
l Server settings
o PeSIT Identifier (PI4) – Enter the PeSIT PI4 ID of the back-end server.
o Use password – Select this option if you want the server to provide a password to connect
to your community. Enter the required password.
l Acknowledge each fetched file - Select this option if the polled back-end server expects an
acknowledgment for each file fetched.
Select a community and the URL of the PeSIT delivery to use to send the acknowledgment.
Select the same community and the delivery that matches the server to poll. Alternatively, you
can select another community for special use (for example, 3rd party monitoring).
This tab is identical for PeSIT application and trading polling pickup exchanges.
l Priority (PI17) – In most cases, you can accept the default value (medium). Check with the
remote server administrator to know if you can make use of this setting. As a server, Interchange
ignores the priority and handles every request at the same level.
o High (0) – Highest priority
o Medium (1) – Default
o Low (2) – Lowest priority
l Free text (PI99) – Free text often used to transfer metadata. In most cases, you can leave this
field blank, unless the server makes a special use of it. Check with the remote server
administrator to know if you can make use of this setting.
Maximum length = 4096 characters.
Advanced tab
l Max data unit size in bytes (PI25): The largest of chunk of data, in bytes, to be transferred
at one time. For high-speed networks, use the default 3 2700 bytes. This value is related to the
client setting for record length on the PeSIT parameters tab. The value of this field must be
the same or larger than the value of the record length field. Do not change this value unless
advised by the administrator of the back-end PeSIT application you are trading with.
Prerequisites
l You must have a community with a PeSIT pickup.
To add a community, see Add a community on page 136.
To add a PeSIT pickup, see Add or modify a PeSIT application pickup (embedded server) on
page 667 or Add or modify a PeSIT trading pickup (polling client) on page 684.
l You must have a partner that is linked to your community. For details see, Add a partner on page
143.
Procedure
1. In the Interchange user interface, select Partners > Manage partners.
2. From the list of partners, click the name of a partner to display the Summary page for that
partner.
3. Click Delivery exchange in the navigation graphic to open the Deliveries page.
4. Click Add a delivery exchange, to open the exchange wizard.
5. Choose the message protocol PeSIT, and click Next.
6. Complete fields of the Configure PeSIT client settings page.
l Hostname – The IP address or the network name of the trading partner PeSIT server to
connect to. This must be the fully qualified domain name or IP address of the PeSIT server
your community connects to for sending messages.
l Port – The port on which the partner PeSIT server listens for connection requests.
l Hold all outbound messages for pickup up by the remote client:
o Not selected: The messages sent to this delivery are produced and sent to the server.
o Selected: The messages sent to this delivery stop in HeldForPickup state, available
for the remote client to fetch them.
l Override community settings (caller) – This controls the caller’s protocol identity
(PI3). Select the following, as needed.
o Allow any valid community routing ID – Select this option to use the message’s
SenderRoutingID as the community (caller) identifier (PI3). If you select this option,
Interchange does not check the sender identity for the transfer.
o Restrict to specific community routing ID –Select this option and then choose a
community routing ID from the list of available IDs to identify the community (caller)
identifier to use. When you select this option, if the SenderRoutingId from the
message is different from the selected value, Interchange rejects the transfer.
o Use Password (This is the password the server expects) – Select this option
and enter a password if the remote partner server expects a password from you.
l Remote partner settings – In this section you set the partner server’s protocol identity
(PI4) and password requirements.
o Allow any valid partner routing ID– Select this option to use the message’s
ReceiverRoutingID as the partner (server) identifier (PI4). If you select this option,
Interchange does not check the receiver identity for the transfer.
o Restrict to specific partner routing ID – Select this option and then choose a
partner routing ID from the list of available IDs to set the partner (receiver) identifier to
use. When you select this option, if the ReceiverRoutingId from the message is
different then the selected value, Interchange rejects the transfer.
o Override password settings – Select this option to override the expected password
setting on the PeSIT community pickups. Either enter no password if no password is
required, or select the Use password option and enter the required password to use.
l Clients must use SSL to connect to this server – select this option If the partner
server is configured to transfer over SSL/TLS. You must import the root certificate of the
remote server to the community trusted SSL root certificates.
o Enable host name verification – If you select this option, Interchange verifies that
the name of the server is the same as the name in the server’s certificate. This requires
that you import the server certificate chain to the partner’s personal certificates and
select the option Trust this for SSL server and/or client authentication.
Interchange automatically adds the root certificate to the linked community's trusted
SSL root certificates.
o Enable CFT compatibility
When you select this option, Interchange aligns the PeSIT record size on TLS packets.
This is the only method handled by Transfer CFT up to version 3.0, and the default
method for the Axway products Gateway and Interpel.
When unselected, Interchange adds the record size as a header of the record, as for non
TLS communications. This is the default, which is recommended.
7. Enter a name for the exchange to identify it in the user interface.
8. Click Finish.
Procedure
1. In the Interchange user interface, select Partners > Manage partners.
2. From the list of partners, click the name of a partner to display the Summary page for that
partner.
3. Click Partner delivery in the navigation graphic to open the Delivery exchanges page.
4. From the list of available exchanges, click the name of a PeSIT partner delivery to open the
maintenance page for the delivery.
5. View and modify fields as required. The fields are described in the following section.
6. If you make any changes, click Save Changes.
Use this tab to modify the basic default PeSIT parameters for this delivery exchange. These values
are only used if no corresponding attribute is found in the message.
The initial settings that are displayed on this tab represent the default settings for the protocol. If
you change any settings on this tab, you replace the protocol defaults.
If you use any of the supported PeSIT metadata elements in a message handler action or other
process, those elements will override the settings on this tab. For example, if you use the
pesit.filelabel metadata element in a message handler action, that setting overrides the setting on
this tab for Filename (nfname). For a list of the PeSIT metadata elements, see Metadata definitions
on page 414.
l File name (PI12) – Name of the file, forced to uppercase at runtime. Often, the real name of the
file is shipped in File label.
Maximum length = 76 characters. If the name is longer, it is truncated to 71 characters and
prefixed with a unique 4 digit counter in the format xxxx_<71 first char of filename>.
At runtime, the file name takes the first non-empty value from the following list:
o pesit.filename.out
o UI value
o pesit.filename.in
o pesit.filelabel.out
o « NOT-SPECIFIED » – if nothing was set
l File type (PI11) – This is the file type, which is used by some monitors. The default value is 0.
If pesit.filetype.out is set in the message, at runtime it overrides the value you set in this
UI field.
l File label (PI37) – Logical name of the file.
Maximum length = 80 characters. If the label is longer, it is truncated to 76 characters and
prefixed with a unique 3 digit counter in the format xxx_<76 first char of filelabel>.
At runtime, the file label takes the first non-empty value from the following list:
o pesit.filelabel.out
o UI value if Use original is not selected
o Production file name
o Consumption file name
l Expect acknowledgments – Select this option if you expect the remote application or partner to
send a receipt to acknowledge receiving each message sent. In this case, the message is marked
"to be acknowledged", until the remote sends the expected acknowledgment.
You can additionally select whether to Support negative acknowledgments.
l Free text (PI99) – Free text often used to transfer metadata.
Maximum length = 4096 characters
If pesit.serviceParam.out is set in the message, at runtime it overrides the value you set in
this UI field.
l Data encoding (PI16) – Text for ASCII files, and Binary for all others (including EBCDIC).
Protocol values: Text = 0 , Binary = 2
If pesit.fileEncoding.out is set in the message, at runtime it overrides the value you set in
this UI field (the attribute uses the numeric value).
l Record format (PI31) – Select Fixed for fixed length records and Variable for variable length
records
Protocol values: Fixed = 0, Variable = 128
If pesit.recordFormat.out is set in the message, at runtime it overrides the value you set in
this UI field (the attribute uses the numeric value).
If you set an On the Fly transformation, the transformation overrides
pesit.recordFormat.out
l Record length (PI32) – Record length for fixed records, or maximum record length for variable
records.
If pesit.recordLength.out is set in the message, at runtime it overrides the value you set in
this UI field.
If you set an On the Fly transformation, the transformation overrides
pesit.recordLength.out.
l Compression (PI21) – Controls the compression of the file during the transfer (compression on
the fly). Select a compression method:
o None (0) – (default) No compression.
o Horizontal (1) – Compresses the consecutive identical characters in the records.
o Vertical (2) – Records are compared to one another and the consecutive identical columns
are compressed.
o Both (3) – Combination of the above two compression methods.
If pesit.compressionType.out is set in the message, at runtime it overrides the value you
select in this UI field (the attribute uses the numeric value).
Note: The compression is negotiated between the caller and the server. If the server can’t handle
the compression setting, a lower type of compression or no compression is applied.
l Priority (PI17) – Select an option:
o High (0) – Highest priority
o Medium (1) – Default
o Low (2) – Lowest priority
If pesit.priority.out is set in the message, at runtime it overrides the value you set in this
UI field (the attribute uses the numeric value).
Advanced tab
This tab is identical for PeSIT application delivery and for PeSIT trading d elivery exchanges.
Note: This tab enables you to view and modify advanced parameters. In most cases the default
values are the correct values. Do not modify values without first consulting with the administrator of
the remote server.
o The sent file size is: local file size * (1 + percentage/100) (rounded to Kb and put in PI42).
o If the transformed file is likely to be bigger than the original file, enter a positive percentage.
o If the transformed file is likely to be smaller than the original file, enter a negative
percentage.
o In most situations, you can accept the default value 0.
l Max data unit size in bytes (PI25) – The largest of chunk of data, in bytes, to be
transferred at one time. For high-speed networks, use the default 3 2700 bytes.
This value is related to the client setting for record length on the PeSIT parameters tab.
The value of this field must be the same or larger than the value of the record length field. Do
not change this value unless advised by the administrator of the back-end PeSIT application you
are trading with.
l Synchronization option (PI7) –
o Intervals between sync points (Kbytes): – Each time an amount of data equal to this
value has been sent, the client is expected to ask the server to confirm whether data totaling
this value has been received. The server responds optionally with a confirmation. This
represents a check point in the progress of a file transfer. If a connection is lost before a file
transfer has been completed, the transfer resumes, upon restart of the transport, at the point
of the last successful check point.
The default value is 1024 kilobytes (1 megabyte).
This setting corresponds to the pacing setting in Axway Transfer CFT.
o Sync acknowledgement window – The number of check-point cycles that the client
waits for the server to respond to a request to confirm file-transfer progress.
For example, if the value of Kb per sync point (pacing) is 1024 (1 megabyte) and the value
of this field is 1, the client stops sending data after 1024 kilobytes unless the server
responds, although the transfer remains active.
If this value is 2, the client keeps sending until 2 megabytes (1024 x 2) of data are sent, and
so on.
If the client’s value for this field is 0 (zero), the client does not ask the server to confirm at
intervals the amount of data received.
If the server’s value for this field is 0, the server does not send confirmations at intervals of
data received.
The default value is 3. In most situation this is the correct value.
This setting corresponds to chkw setting in Axway Transfer CFT.
l Read timeout (seconds) – Time in seconds Interchange waits to read data from the delivery
exchange before terminating the connection.
l Connection timeout (seconds) – PeSIT Tc timeout. The time the caller waits for a
connection acknowledgment from the server.
l Transfer timeout - caller mode (seconds) – PeSIT Td timeout. The time the caller keeps the
connection open, waiting for another message to send.
The polling pickup is linked to a trading partner delivery.
Prerequisite
l You must have a community with a PeSIT pickup.
To add a community, see Add a community on page 136.
l You must have a partner that is linked to your community. For details, see Add a partner on page
143.
l You must add PeSIT delivery exchange to the partner. For details, see Add or modify a PeSIT
partner delivery on page 675.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
3. Click Trading pickup in the navigation graphic to open the Trading pickups page.
4. Click Add a pickup.
5. Choose the transport protocol PeSIT and click Next.
6. Select Define a new PeSIT polling client and click Next.
7. Complete the fields of the Configure the PeSIT client settings page.
l Remote partner URL – Use the Pick polling URL button to select the URL that
corresponds to the delivery exchange of the partner to poll. The URL has the format:
pesit://<Server Address>:<Port>
This polling pickup uses all of the settings from the selected partner delivery exchange.
l FileName (PI12) – Enter here the name of the file you want to poll from the server. You
can enter a star (*) at the end to select all files starting with the characters before the star.
8. Enter a name for the pickup to identify it in the user interface. Hint: Enter a name that is easily
identifiable in a list of pickups in the user interface.
9. Click Finish.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
3. Click Trading pickup in the navigation graphic to open the community's Trading pickups
page.
4. From the list of available pickups, click the name of a PeSIT pickup to open the maintenance
page for that pickup.
5. View and modify fields as required. The fields are described in the following section.
6. After making any modifications, click Save changes.
To change these settings, do one of the following:
This tab is identical for PeSIT application and trading polling pickup exchanges.
Note: The compression is negotiated between the caller and the server. If the server can’t handle
the compression set in this field, a lower type of compression or no compression is applied.
l Priority (PI17) – In most cases, you can accept the default value (medium). Check with the
remote server administrator to know if you can make use of this setting. As a server, Interchange
ignores the priority and handles every request at the same level.
o High (0) – Highest priority
o Medium (1) – Default
o Low (2) – Lowest priority
l Free text (PI99) – Free text often used to transfer metadata. In most cases, you can leave this
field blank, unless the server makes a special use of it. Check with the remote server
administrator to know if you can make use of this setting.
Maximum length = 4096 characters.
Advanced tab
Note This tab enables you to view and modify advanced parameters. In most cases the default
values are the correct values. Do not modify values without first consulting with the
administrator of the remote server.
For example, if the value of Kb per sync point (pacing) is 1024 (1 megabyte) and the value
of this field is 1, the client stops sending data after 1024 kilobytes unless the server
responds, although the transfer remains active.
If this value is 2, the client keeps sending until 2 megabytes (1024 x 2) of data are sent, and
so on.
If the client’s value for this field is 0 (zero), the client does not ask the server to confirm at
intervals the amount of data received.
If the server’s value for this field is 0, the server does not send confirmations at intervals of
data received.
The default value is 3. In most situations this is the correct value.
This setting corresponds to chkw setting in Axway Transfer CFT.
l Read timeout (seconds) – Time in seconds Interchange waits to read data from the delivery
exchange before terminating the connection.
l Connection timeout (seconds) – PeSIT Tc timeout. The time the caller waits for a
connection acknowledgment from the server.
l Transfer timeout - caller mode (seconds) – PeSIT Td timeout. The time the caller keeps the
connection open, waiting for another message to send.
l Network timeout (seconds) – PeSIT Tr timeout. The time the caller waits for an expected
and effective network disconnection, before forcing it.
l Protocol timeout (seconds) – PeSIT Tp timeout. The time the caller waits for the response of
the remote, in the middle of a protocol action (such as a transfer).
each location has its own local transport servers. In this situation, you would use this setting to
ensure the exchange points associated with the transport servers are assigned to nodes in the
vicinity of the transport servers.
Prerequisite
You must have a community. If you need to add a community, see Add a community on page 136.
Procedure
1. In the Interchange user interface, select Trading configuration > Manage trading
configuration.
2. From the list of communities, click the name of a community to display the Summary page for
that community.
3. Click Trading pickup in the navigation graphic to open the Deliveries page.
Advanced tab
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from the remote partner. This is required for the system to
perform fail-over operations such as attempting to send messages again (retries) in case of a
transport connection failure. Without backups, a message in process cannot be recovered if the
server or a processing node stops or restarts.
l Restrict maximum file size for this transport – Select this option to specify the maximum
size of files a the exchange can handle.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log.
l Maximum file size – Enter the maximum file size in bytes. Do not use commas.
l A PeSIT partner delivery exchange used for sending the MMD.
l A community-embedded PeSIT server type delivery exchange used for receiving the fetched
files.
To send a payload to a partner PeSIT delivery exchange, use a generic MMD request. See Use
generic MMDs on page 954. Collaboration rules identify the PeSIT send. The partner must be valid.
To issue a fetch request to a partner PeSIT delivery exchange, use an MMD request with defined
fetch parameters. The partner must have a PeSIT delivery exchange to re-use. The following
metadata specifies the maximum number of files to be fetched:
pesit.max.xfers.per.polling.interval. Message Tracker displays the MMD which initiated
the fetch and the received responses.
Sample MMD:
<Metadata name="Action">Fetch</Metadata>
PGP certificates
Using PGP certificates is similar to using X.509 certificates, but there are some important
distinctions.
PGP certificates can be used only with FTP or SFTP to exchange messages with remote partners.
Special FTP and SFTP delivery exchanges for PGP must be used.
l PGP certificates only are used to sign and encrypt or decrypt messages. Any certificates used to
make secure connections (for example, SSL) are X.509 certificates.
l Most of the user interface dedicated to certificate management deals with X.509 and not PGP
certificates. Look for links or labels that reference PGP explicitly.
l Most of the topics about certificates in this documentation relate to X.509 certificates. Look for
topics that reference PGP explicitly.
Interchange enables you to generate self-signed PGP certificates in the user interface. You also can
import PGP certificates that have been generated by a third-party PGP tool or sent to you by remote
partners. When PGP certificates for encrypting and signing messages have been added to a
community, the public keys and certificates are included when the profile is exported as a partner
profile. You can give such profile files to remote partners who also use Axway products B2Bi,
Interchange or Activator. A community’s certificates also can be exported to files manually and
given to partners. In short, the user interface provides similar usability features for PGP certificates
as for X.509 certificates.
To read the PGP specification RFC 2440 go to http://www.ietf.org/rfc/rfc2440.txt.
5. Select FTP or SFTP, then click Next and follow the prompts.
The subsequent steps are identical to adding any FTP or SFTP trading pickup. See Exchange links
below for links to details of setting up FTP and SFTP exchanges.
When you add a community, you have the option of adding a certificate for the community. This
option is for X.509 certificates only. You can associate a PGP certificate with an existing community
following this procedure.
512 Normal encryption
1024 Strong encryption. 1024 or higher is recommended for high-value EDI transactions
2048 Very strong encryption
3072 Very strong encryption
4096 Very strong encryption
For the validity period, to modify the default value of 2 years, type the length of time you want
the certificate to be valid in the validity period field. Select days, months or years from the drop-
down list.
If your partner uses Interchange, skip this procedure. PGP certificates are included when a
community profile is exported as a partner profile. Exchanging profiles is typical when both parties
in a trading relationship use Interchange.
1. Click Certificates on the navigation graphic on the community summary page to display the
certificates page.
2. Select the PGP personal certificates tab.
3. Click the key ID of a certificate to open its details page.
If your partner uses Interchange, skip this procedure. PGP certificates are included when a
community profile is exported as a partner profile. Exchanging profiles is typical when both parties
in a trading relationship use Interchange.
This procedure presumes you previously added a partner for the partner and only must import the
partner’s certificate.
1. Get from your partner the file containing your partner’s PGP certificate and public key. Put the
file in an accessible directory on your system.
2. Click Certificates on the navigation graphic on the partner summary page to display the
certificates page.
3. Click the task Add a PGP certificate near the bottom of the page to launch the import wizard.
4. Click Next.
5. Click Browse, select a public key file with an extension of ASC and click Finish to import it.
6. Make sure the partner has a default PGP certificate. If a partner has only one PGP certificate,
Interchange makes it the default. But if a partner has two or more, you can pick one as the
default for encrypting messages. The following are the steps:
a. Click Certificates on the navigation graphic on the partner summary page to display the
certificates page.
b. Select the PGP certificates tab.
c. Select a PGP certificate from the drop-down list and click Save changes to make it the
default.
For a partner, details about PGP certificates can be viewed on the PGP certificates tab.
To display the PGP certificates tab:
l Click Certificates on the navigation graphic at the top of a community or partner summary
page.
l If a community, select the PGP personal certificates tab. If a partner, select the PGP certificates
tab.
l Click the key ID of a certificate to open its details page.
The following describes the fields on the details page for a PGP certificate.
General tab
l Name – A name for the certificate. This can be any name you want.
l User name – The name of the person or entity owning the certificate. For a self-signed
certificate generated by Interchange, the name defaults to the community name and the e-mail
address of the community contact.
l Key ID – The identification of the master key. This key also is known as the signing key.
l Fingerprint – Fingerprints are a way to verify the source of a certificate. After you import or
export a certificate, you can contact your partner and ensure the fingerprints at both ends are
identical. Do this before attempting to exchange documents. If the fingerprints do not match,
one of the certificates might be corrupted or out of date.
l Key Algorithm – The algorithm used to generate the certificate.
l Key Length – Key length indicates encryption strength. The larger the number the stronger the
key.
l Created – The date the certificate was generated.
l Expires – The date the certificate expires. Some PGP certificates do not have expiration dates.
Subkeys tab
This tab displays all keys within a certificate. If it is a self-signed certificate generated by
Interchange, the first key in the list is the master key and the second is the encryption key. Imported
certificates may have many subkeys, some of which may be expired or revoked. This provides a view
of the certificate’s key history.
Signatures tab
This tab displays all entities that have signed a certificate. A signer indicates a level of trust ranging
from low to high. For example, a self-signed certificate is by default signed by the community that
generated the certificate within Interchange. The community gives the certificate a positive level,
which is a high level of trust.
Related topics
l PGP secure trading on page 693
l PGP certificates on page 693
l Add a PGP pickup or delivery on page 693
l Manage PGP certificates on page 695
RosettaNet
The following topics describe how to use Interchange to exchange documents via the RosettaNet
message protocol. Your organization must have a thorough understanding and working knowledge
of RosettaNet to trade documents successfully with this protocol. For information about RosettaNet
see www.rosettanet.org.
RosettaNet overview
RosettaNet is the name both of a consortium of companies and of a set of processes and standards
for conducting electronic business transactions. Interchange supports two versions of the
RosettaNet Implementation Framework (RNIF). RNIF 1.1 and 2.0 are implementation guidelines for
companies that want to create interoperable software that execute Partner Interface Processes
(PIPs).
Interchange is the packaging and transport interface to the back-end PIP engine. The back-end
determines what message is next in the PIP process, whether inbound or outbound. The back-end
also can optionally generate message metadata documents and submit them to Interchange. MMDs
are interface XML documents that include metadata in the packaging of RosettaNet headers
(preamble, service header, delivery header).
There are two broad categories of messages involved in the exchange of PIP business documents.
These are business action messages and business signal messages:
l Business actions are messages with a business-related content, such as a purchase order or
request for quote. DTDs, schemas and message guidelines for their corresponding PIPs define
these messages.
l Business signals are positive or negative acknowledgments sent in response to a business action.
Signal messages, which are part of RNIF, are never acknowledged.
A request is the act of initiating some aspect of a business process. A response is the act of
responding to a request. Business action messages are used to implement requests and responses.
The following figure shows a message flow.
Interchange does duplicate checking for RosettaNet. The unique identification for a RosettaNet
message is the MessageTrackingId. This cannot be disabled in Interchange. RosettaNet requires that
the PIP instance ID be unique across all PIP instances and that the MessageTrackingId be unique
within that PIP.
1. Install Interchange.
2. Log on to the user interface.
3. Add and configure your community. This includes setting up delivery and a public-private key
certificate for secure trading. The user interface and documentation provide guidance for
creating and configuring a community. See Communities on page 134.
For the trading pickup for receiving messages from partners, select RosettaNet 1.1 or
RosettaNet 2.0 as the message protocol. See Community trading pickups and partner deliveries
on page 256.
If you need to produce message metadata documents (MMDs) when routing messages from
partners to a back-end file system, select File system with message metadata as the
application delivery transport. If you do not need MMDs, you can use any other application
delivery transport. See Application deliveries on page 162.
If a partner uses Interchange or Activator 4.x, be aware of the following: If the community
profile you export has trading pickups for both RNIF 1.1 and 2.0, the partner’s trading engine
ignores one of the exchanges upon importing the profile. Consult with your partner about
which exchange to use, and inform the partner to edit the partner information accordingly.
4. Set up partners by importing profiles or manually adding them. Associate the partners with your
community. See Add a partner on page 143. Make sure the message protocol for sending
messages to partners is RosettaNet 1.1 or RosettaNet 2.0. If a partner uses Interchange or
Activator4.x, the partner profile you import has trading deliveries for sending messages for both
RNIF 1.1 and 2.0. Consult with your partner about which exchange to use, and delete the
unused exchange in the profile.
5. Consult with your trading partners on the PIPs to use.
6. Add PIPs. For DTD-based PIPs, Add PIP DTDs to the dtds directory. See Add DTD-based PIP on
page 701. For schema-based PIPS, add PIP schemas to the schemas directory. See Add
schema-based PIP on page 702.
7. Check collaboration settings for document encrypting and signing options of outbound
documents. You can configure settings by partner rather than use default settings. See RNIF
1.1 default settings on page 925 or RNIF 2.0 default settings on page 925.
8. Define the PIPs in the pipdefinitions.xmlfile. See Configure pipdefinitions.xml file on page
702. The community now is ready to begin trading messages.
Interchange supports a number of DTD-based PIPs. The PIP document type definitions (DTDs) are
in <install directory>\conf\rosettanet\dtds.
1. Obtain the correct version of the PIP package from RosettaNet at www.rosettanet.org.
A PIP package is a zip file containing the PIP specification in a Word document, one or more
XML DTDs and one or more HTML message guidelines files. The DTDs, one per PIP message,
define the structure of the messages involved in the PIP. The HTML message guidelines files,
one per PIP message, describe the elements of the message in detail.
2. Copy the DTDs to <install directory>\conf\rosettanet\dtds.
3. Define the PIP in the pipdefinitions.xml file. See Communities on page 134.
4. When you upgrade later to a newer version of Interchange, you must copy the DTDs to the
dtds directory of the new application. You also must change the pipdefinitions.xml file
for the new application.
Interchange supports a number of schema-based PIPs. The PIP schemas are in <install
directory>\conf\rosettanet\schemas.
1. Obtain the correct version of the PIP package from RosettaNet at www.rosettanet.org.
A PIP package is a zip file containing a readme file, an XML folder with the machine-readable
PIP standard and a descriptive folder with the human-readable form of the PIP standard. The
XML folder has schemas defining the structure and allowable content of the messages involved
in the PIP.
2. Unzip the PIP zip file. Copy the resulting directory to <install
directory>\conf\rosettanet\schemas.
3. Define the PIP in the pipdefinitions.xml file. See Configure pipdefinitions.xml file on page
702.
4. When you upgrade later to a newer version of Interchange, you must copy the PIP directory to
the schemas directory of the new application. You also must change the
pipdefinitions.xml file for the new application.
The file is at <install directory>\conf\rosettanet.
The following figure shows an example of the pipdefinitions.xml file. This example shows the
definition for using the Asynchronous Request-Confirm test PIP. The PIP is defined between the
beginning and ending Pip element tags. You can define as many PIPs as you want in this file.
See the following example of a pipdefinitions.xml file.
rootElement="Pip0C2AsynchronousTestRequest" fromService="Initiator
Service" toService="Responder Service">
<Signal timeToAcknowledge="5"/>
</Action>
</Activity>
<Activity name="Asynchronous Test Confirmation" retryAttempts="3">
<Action name="Asynchronous Test Confirmation Action" dtd="0C2_MS_
R01_02_AsynchronousTestConfirmation.dtd"
rootElement="Pip0C2AsynchronousTestConfirmation" fromService="Responder
Service" toService="Initiator Service">
<Signal timeToAcknowledge="5"/>
</Action>
</Activity>
</Pip>
<Pip code="3B13" name="Shipping Order Confirmation Notification"
version="V01.01">
<Activity name="Notify of Shipment Confirmation" retryAttempts="3">
<Action name="Shipping Order Confirmation Notification Action"
dtd="3B13_MS_V01_01_ShippingOrderConfirmationNotification.dtd"
rootElement="Pip3B13ShippingOrderConfirmationNotification"
fromService="Initiator Service" toService="Responder Service">
<Signal timeToAcknowledge="15"/>
</Action>
</Activity>
</Pip>
<Pip code="3B3" name="Distribute Shipment Status" version="V11.00">
<Activity name="Shipment Status Distribution" retryAttempts="3">
<Action name="Shipment Status Distribution Action"
dtd="ShipmentStatusDistribution_01_02.xsd"
rootElement="ShipmentStatusDistribution" fromService="Transport Service
Provider Service" toService="In-transit Information User Service"
fromRole="Transport Service Provider" toRole="In-transit Information
User" globalDocumentFunctionCode="Request"
fromGlobalPartnerClassificationCode="Carrier"
toGlobalPartnerClassificationCode="Distributor">
<Signal timeToAcknowledge="120"/>
</Action>
</Activity>
</Pip>
</PipDefinitions>
Note Interchange supports asynchronous responses, but not synchronous responses for RNIF.
The following describes the elements in the pipdefinitions.xml file.The following figure is an
example of how the elements are used. Most of the information is used to build RosettaNet headers.
But some elements, such as retryAttempts and timeToAcknowledge, affect performance of
Interchange.
l PipDefinitions – The PIP definitions are placed between the beginning and ending
PipDefinitions elements.
l xsi:noNamespaceSchemaLocation – The default schema is pipdefinition.xsd. The file is at
<install directory>\conf\rosettanet\schemas.
l dtdValidation – Indicates (on or off) whether Interchange validates the document against a
DTD or schema. If on, copy the DTD to <install directory>\conf\rosettanet\dtds or
the schema to <install directory>\conf\rosettanet\schemas. If off, you still must
copy to the dtds or schemas directory, but Interchange does not perform validation.
A third option, noload, turns off validation regardless whether you have copied a DTD to the
dtds directory or a schema to the schemas directory. The noload option allows trading of
documents with a DOCTYPE declaration, but the DTD or schema does not have to be in the dtds
or schemas directory. The DTD name still must be configured within each DTD Action element.
The DTD name is used for document recognition. If an outbound document includes a
DOCTYPE declaration and there is no matching DTD attribute, the message is rejected.
l guidelineValidation – For DTD-based PIPs only, indicates (on or off) whether Interchange
validates the document against a guidelines XML file. If on, copy the file to <install
directory>\conf\rosettanet\guidelines.
l Pip – Each PIP is defined between beginning and ending Pip elements.
l code – An attribute of the Pip element, this code identifies the PIP. The code is available in the
RosettaNet PIP specification document. For example, for the Asynchronous Request-Confirm
PIP, the code is 0C2. This is required to build the RosettaNet headers. It is not specified by the
service content. Interchange determines the PIP code and PIP version based on the document
type of the service content.
l name – An attribute of the Pip element, this is the name of the PIP. The name is available in the
RosettaNet PIP specification document.
l version – An attribute of the Pip element, this is the version of the PIP. The version is available
in the RosettaNet PIP specification document. For example, for the Asynchronous Request-
Confirm PIP, the version is R01.02.This is required to build the RosettaNet headers. It is not
specified by the service content. You can have multiple versions of a PIP, but the document
types need to be different. RosettaNet usually gives service contents a different document type
based on the version.
l Activity – The activity as defined in the RosettaNet PIP specification document. A PIP can have
multiple activities. Each activity must be listed in the pipdefinitions.xml file in parallel with
the specification.
l name – An attribute of the Activity element, this is the activity name as defined in the RosettaNet
PIP specification document.
l retryAttempts – An attribute of the Activity element, this specifies how many times to resend a
message when a signal is not received within the time specified in the timeToAcknowledge
attribute. This value is specified in the RosettaNet PIP specification document.
l Action – The action for the parallel activity as specified in the RosettaNet PIP specification
document
l name – An attribute of the Action element, this is the name of the action. This is the business
message payload. The name is available in the RosettaNet PIP specification document.
l dtd – This is an attribute of the Action element. For DTD-based PIPs, if dtdValidation=“on”, the
value is the name of the DTD to validate against. The name is available in the RosettaNet PIP
specification document. The DTD must be copied to <install
directory>\conf\rosettanet\dtds. For schema-based PIPs, if dtdValidation=”on”,
the value is the name of the schema to validate against. The name is available in <install
directory>\conf\rosettanet\schemas. Look in the XML\Interchange directory for the
desired PIP. If validation is off, this attribute is not used.
l rootElement – An attribute of the Action element, the rootElement is used to identify the action
when there is no DOCTYPE definition. The value of rootElement is in the service content. This
handles the case where there is no DOCTYPE definition and provides for a means to validate the
XML (given the dtd attribute). If there is a DOCTYPE definition, the DOCTYPE is used to validate
the XML, otherwise the dtd attribute is used. The document is rejected if there is no DOCTYPE,
DTD validation is on and the dtd attribute is missing or blank.
l fromService – An attribute of the Action element, this is the service from which the message is
being sent. This value is specified in the RosettaNet PIP specification document. This is required
to build the RosettaNet headers. It is not specified by the service content.
l toService – An attribute of the Action element, this is the service to which the message is being
sent. This value is specified in the RosettaNet PIP specification document. This is required to
build the RosettaNet headers. It is not specified by the service content.
l fromRole – An attribute of the Action element, this is the role the trading partner who sends the
message plays in the PIP. This value is specified in the RosettaNet PIP specification document.
This is required to build the RosettaNet headers. The value is parsed from the service content for
DTD-based PIPs. However, the value in pipdefinitions.xml is used only when the value is
not found in the service content. The value is required for schema-based PIPS. It is not specified
in the service content of schema-based PIPs.
l fromRoutingIdXpath – This is an optional attribute of the Action element. If the location of
fromRoutingId changes from the usual location
(fromRole/PartnerRoleDescription/PartnerDescription/
BusinessDescription/GlobalBusinessIdentifier)
then mention the new path inside this attribute. For example:
fromRoutingIdXpath=”fromRole/PartnerRoleDescription/
PartnerDescription/BusinessDescription/
BusinessIdentification/GlobalBusinessIdentifier”
l toRole – An attribute of the Action element, this is the role the trading partner who receives the
message plays in the PIP. This value is specified in the RosettaNet PIP specification document.
This is required to build the RosettaNet headers. The value is parsed from the service content for
DTD-based PIPs. However, the value in pipdefinitions.xml is used only when the value is
not found in the service content. The value is required for schema-based PIPS. It is not specified
in the service content of schema-based PIPs.
l toRoutingIdXpath – This is an optional attribute of the Action element. If the location of
toRoutingId changes from the usual location
(toRole/PartnerRoleDescription/PartnerDescription/
BusinessDescription/GlobalBusinessIdentifier)
then mention the new path inside this attribute. For example:
toRoutingIdXpath=”toRole/PartnerRoleDescription/
PartnerDescription/BusinessDescription/
BusinessIdentification/GlobalBusinessIdentifier”
l globalDocumentFunctionCode – This is an attribute of the Action element. The possible
values are:
o Request. The business document is a request for a business action to be performed by a
partner.
o Response. The business document is a response to a requesting partner.
This is required to build RNIF 1.1 headers. The value is ignored when packaging RNIF 2.0
messages. This attribute is ignored for DTD-based PIPs. The value is required for schema-based
PIPS when using RNIF 1.1 packaging.
l fromGlobalPartnerClassificationCode – An attribute of the Action element, this is a
classification of the role the trading partner who sends the message plays in this PIP. The valid
values are specified in the RosettaNet Service Header Message Guidelines for RNIF 1.1 and RNIF
2.0. This is required to build the RosettaNet headers. The value is parsed from the service
content for DTD-based PIPs. However, the value in pipdefinitions.xml is used only when
the value is not found in the service content. The value is required for schema-based PIPS. It is
not specified in the service content of schema-based PIPs.
l toGlobalPartnerClassificationCode – An attribute of the Action element, this is a
classification of the role that the trading partner receiving the message plays in this PIP. The
valid values are specified in the RosettaNet Service Header Message Guidelines for RNIF 1.1 and
RNIF 2.0. This is required to build the RosettaNet headers. The value is parsed from the service
content for DTD-based PIPS. However, the value in pipdefinitions.xml is used only when
the value is not found in the service content. The value is required for schema-based PIPS. It is
not specified in the service content of schema-based PIPs.
l PipInstanceId – Used to specify when special handling of RosettaNet metadata within the
service content is enabled. This functionality aids in the trading of dual-action PIPs when MMDs
are not used.
l parseFromServiceContent – Enables or disables parsing and writing pipInstanceId,
ReplyToTrackingId and Global Usage Code from or to service content. Defaults to false.
l separator – This attribute is used to specify the separator character to delineate
pipInstanceId, ReplyToTrackingId and Global Usage Code when reading from or writing
to the service content. The default separator character is a colon ( : ).
l xpath – This attributes specifies the XPath expression to parse or write pipInstanceId,
ReplyToTrackingId and Global Usage Code from or to.
For DTD-based service content, defaults to:
/*/thisDocumentIdentifier/ProprietaryDocumentIdentifier for DTD based service
contents.
For schema-based service content, defaults to:
/*/ssdh:DocumentHeader[1]/ssdh:DocumentInformation[1]/
ssdh:DocumentIdentification[1]/ssdh:Identifier[1]
The XPath must include namespace prefixes for schema-based service contents.
l Signal – This element specifies the conditions for the response to the message action.
l timeToAcknowledge – An attribute of the Signal element, this specifies the time in minutes
within which the message acknowledgment must be received. If not received within the
specified time, the message is to be resent up to the limit in the retryAttempts attribute. After
each resend, the timeToAcknowledge interval must elapse before another resend is
attempted. This value is specified in the RosettaNet PIP specification document.
These elements are listed in the correct format. When using metadata elements, make sure to use
the proper case.
For a broader list of elements and more information about metadata, see Message metadata and
attributes on page 412.
Description of elements
The following are the metadata elements. In the case of MMDs, some exceptions apply. See MMD
elements on page 710.
l BusinessActivityIdentifier – RosettaNet activity identifier of the message as defined in the
PIP specification. Required.
l BusinessProtocolVersion – The version of the RNIF messages to be traded, either 1.1 or 2.0.
Required.
l CidxPackaging – For use with Chemical Industry Data Exchange (CIDX) messages only with
RNIF 1.1.
l FromGlobalPartnerClassificationCode – The role specified in the PIP. This value is from the
service header.
l FromGlobalSupplyChainCode – A value from the service content.
l FromLocationId – The sender partner identification location ID in the delivery header.
Optional.
l FromRole – The role the trading partner sending the message plays in this PIP. Optional.
Overrides GlobalPartnerRoleClassificationCode in the service content in this hierarchy:
fromRole
GlobalPartnerRoleClassificationCode
l FromService – The service from which the message is being sent, as defined in the PIP
specification. Required.
l GlobalBusinessActionCode – The action code corresponding to the action to which the
message is in reply, as defined in the PIP specification. Required.
l GlobalBusinessSignalCode – The signal code, if the message is a signal. This is parsed from
inbound signal messages. It is not specified in an MMD.
l GlobalDocumentFunctionCode – Required for RNIF 1.1 action messages.
l GlobalUsageCode – Determines whether the message is to be used in Test mode or in
Production mode. Required.
l InitiatingLocationId – The initiating location identification in the service header.
l InitiatingRoutingId – Specifies the initiating routing ID.
l InitiatingRoutingIdKnown – Specifies whether the initiating partner is known.
l InReplyToActionCode – This code is parsed from a signal message. The code is specified in
the PIP specification.
l InReplyToTrackingId – Helps to identify the message to which this message is in reply.
l PipCode – RosettaNet PIP Code of the message. Set by the initiating partner. Defines what PIP
code is being traded. Required.
l PipInstanceId – The ID of this PIP instance. This must be unique within the context of the
initiating partner. Optional.
l PipVersion – RosettaNet PIP Version of the message. Set by the initiator of this transaction.
Required.
l MessageTrackingId – Uniquely identifies the message for tracking purposes. Must be unique
within the context of the message sender. This value is parsed from the delivery header.
l OriginalMessageDigest – The MIC value of the original message (in the signal).
l ProprietaryReferenceIdentifier – The partner defined PIP payload binding ID proprietary
reference identifier in the service header.
l ReceiverRoutingId – The ID of the receiving partner. This must be a DUNS number. Optional.
If not specified, the value comes from the GlobalBusinessIdentifer in the service content in this
hierarchy:
DTD
toRole
PartnerRoleDescription
PartnerDescription
BusinessDescription
GlobalBusinessIdentifier
Schema
sshd:DocumentHeader
sshd:Receiver
upi:PartnerIdentification
udt:*[1]
l SenderRoutingId – The ID of the sending partner. This must be a DUNS number. Optional. If
not specified, the value comes from the GlobalBusinessIdentifer in the service content in this
hierarchy:
DTD
fromRole
PartnerRoleDescription
PartnerDescription
BusinessDescription
GlobalBusinessIdentifier
Schema
sshd:DocumentHeader
sshd:Sender
upi:PartnerIdentification
udt:*[1]
l service-content – The mandatory payload ID of the service content in an MMD.
l ServiceContentDocType – The document type extracted from the service content.
l ServiceContentMessageStandard – The document standard. The value is set on or extracted
from the service header.
l ServiceContentStandardVersion – The document standard version. The value is set on or
extracted from the service header.
l SignalDigestAlg – Defines the algorithm to use for signing a signal (the same as the one used
for the original message).
l SignalEncryptionAlg – Defines the algorithm to use for encrypting a signal (the same as the
one used for the original message).
l SignalEncryptionStrength – Defines the algorithm strength to use for encrypting a signal
(the same as the one used for the original message).
l ToGlobalPartnerClassificationCode – The role specified in the PIP. This value is from the
service header.
l ToGlobalSupplyChainCode – A value from the service content.
l ToLocationId – The receiver partner identification location ID in the delivery header. Optional.
l ToRole – The role the trading partner receiving the message plays in this PIP. Optional.
Overrides GlobalPartnerRoleClassificationCode in the service content in this hierarchy:
toRole
GlobalPartnerRoleClassificationCode
l ToService – The service to which the message is being sent, as defined in the PIP specification.
Required.
l TransactionIdentity – For RNIF 1.1 only, a unique identifier for a specific transaction (action -
signal pair) within a specific instance of the process. A single-action PIP has one transaction with
a unique TransactionIdentity. A dual-action PIP has two distinct transactions, each with a
unique TransactionIdentity. This value is from the service header.
MMD elements
The following elements are applicable only to MMDs.
For MMDs, some names of metadata elements are slightly different than those listed in Description of
elements on page 707, but the usage is the same. The following lists these discrepancies.
l RemovePayloadAfterProcessing – Indicates (true or false) whether Interchange deletes the
payload from the file system after processing the message. (MMDs always are deleted after
processing.) Use of this element is optional. If not used, the payload is not deleted, which is the
same behavior as using the element with a value of false. If RemovePayloadAfterProcessing is
true, payloads are deleted after being picked up. This also works for the resubmit case in which
payloads are retrieved from the backup directory.
l ToRoutingId – Same as ReceiverRoutingId, earlier in this section.
l FromRoutingId – Same as SenderRoutingID, earlier in this section.
l ToClassificationCode – Same as ToGlobalPartnerClassificationCode, earlier in this
section.
l FromClassificationCode – Same as FromGlobalPartnerClassificationCode, earlier in this
section.
l KnownInitiatingRoutingId – Same as InitiatingRoutingIdKnown, earlier in this section.
Interchange generates MMDs for the documents it sends to a back-end system. To do this you must
use the file system with message metadata integration option. Your back-end system must generate
the MMDs for documents Interchange retrieves from the backend.
The following figure is an example of an MMD associated with a RosettaNet document. For metadata
descriptions, see RNIF metadata elements on page 707.
The following is an example of an MMD for RosettaNet.
<MessageMetadataDocument id="metadataID51736371109613218815JAPPLEGATE-
T40" protocol="RosettaNet" protocolVersion="2.0">
<!--
<Metadata name="PipInstanceId">12345678901</Metadata>
-->
<Metadata name="PipCode">3B13</Metadata>
<Metadata name="ToService">Provider Service</Metadata>
<Metadata name="FromService">Initiator Service</Metadata>
<Metadata name="BusinessActivityIdentifier">Shipping Order Confirmation
Notification</Metadata>
<Metadata name="GlobalBusinessActionCode">Shipping Order Confirmation
Notification Action</Metadata>
<Metadata name="GlobalUsageCode">Test</Metadata>
<Metadata name="PipVersion">V01.01</Metadata>
<MessagePayloads>
<Payload id="service-content">
<RemovePayloadAfterProcessing>true</RemovePayloadAfterProcessing>
<Location type="filePath">/Users/mmdIntegration/remery-rnif2esx6-
rnif-svccontent.xml</Location>
</Payload>
</MessagePayloads>
</MessageMetadataDocument>
You should use MMDs when you want to override data in service content or when there are payloads
in addition to the service content. In the latter case, when it is not necessary to override service
content data, you do not have to specify metadata in the MMD. The MMD in such a case acts as the
glue between the service content and additional payloads.
You do not have to use MMDs when the service contents contains all the data needed to generate
headers and there are no payloads in addition to the service content.
With MMDs
For inbound integration, if MMDs are used Interchange produces an MMD to integration containing
values for the GlobalUsageCode and PipInstanceId (see the folllowing figure). For outbound
integration the GlobalUsageCode and PipInstanceId can be included in the MMD. For response
messages of dual-action PIPs, the PipInstanceId and InReplyToTrackingId also must be included in
the MMD. If included within the MMD, the GlobalUsageCode, PipInstanceId and
InReplyToMessageId values from the MMD are used in the packaged RNIF message.
The following example illustrates an MMD produced for inbound integration.
<MessageMetadataDocument id="ID92102651105484506795birddog-mac.local"
protocol="RosettaNet" protocolVersion="2.0">
<Metadata name="PipCode">OC2</Metadata>
<Metadata name="ToService">Responder Service</Metadata>
<Metadata name="BusinessActivityIdentifier">Asynchronous Test
Request</Metadata>
<Metadata name="ToRoutingId">ZZRNIF2</Metadata>
<Metadata name="FromServive">Initiator Service</Metadata>
<Metadata name="GlobalUsageCode">Production</Metadata>
<Metadata name="FromRole">Responder</Metadata>
<Metadata name="PipInstanceId">1105484499336.978@BirdDog</Metadata>
<Metadata name="ToRole">Initiator</Metadata>
<Metadata name="GlobalBusinessActionCode">Asynchronous Test Request
Action</Metadata>
<Metadata name="PipVersion">R01.02</Metadata>
<Metadata name="FromRoutingId">ZZRNIF1</Metadata>
<MessagePayloads>
<Payload id="ID69561991105484506795birddog-mac.local">
<Location type="filePath">../data/in/RN_Service_Content_
1105484499336_978_BirdDog_7</Location>
</Payload>
</MessagePayloads>
</MessageMetadataDocument>
Without MMDs
If MMDs are not used, the outbound service content can be parsed to determine the PipInstanceId,
GlobalUsageCode, InReplyToTrackingId and InitiatingRoutingId to use in the packaged document.
By default this functionality is disabled, but can be enabled in pipdefinitions.xml. See
Configure pipdefinitions.xml file on page 702.
For response messages of dual-action PIPs the PipInstanceId and InReplyToTrackingId must be
included in the service content. If included, the GlobalUsageCode, PipInstanceId,
InReplyToTrackingId and InitiatingRoutingId values from the service content are used in the
packaged RNIF message.
thisDocumentIdentifier/ProprietaryDocumentIdentifier
The location to parse can be modified in pipdefinitions.xml (see the following figure).
The following figure illustates DTD-based service contents.
<thisDocumentIdentifier>
<ProprietaryDocumentIdentifier>
[proprietary document ID]:[GlobalUsageCode]
PipInstanceId]:[InReplyToTrackingId]:[InitiatingRoutingId]
</ProprietaryDocumentIdentifier>
</thisDocumentIdentifier>
The value of the ProprietaryDocumentIdentifier element should take the form of a colon-
separated list of strings. The first string is the proprietary document ID. Optionally include:
l GlobalUsageCode second
l PipInstanceId third
l InReplyToTrackingId fourth
l InitiatingRoutingId fifth
Blank fields are acceptable within the string. For example, to set only the proprietary document ID
and pipInstanceId the string would look like:
Myid::12346
Where Myid is the proprietary document ID and 12346 is the PipInstanceId.
The GlobalUsageCode, PipInstanceId, InReplyToTrackingId and InitiatingRoutingId
values from the outbound message are used in building the protocol headers in the packaged RNIF
message.
Note that the PipInstanceId, GlobalUsageCode, InReplyToTrackingId and
InitiatingRoutingId values are stripped from the service content that is packaged and
produced to the trading partner. The identifier value is included in the packaged service content.
If enabled, the PipInstanceId, GlobalUsageCode, InReplyToTrackingId and
InitiatingRoutingId are written to the received service content produced to integration. This
enables back-end systems to know the values necessary for sending response documents for dual-
action PIPs.
/*/ssdh:DocumentHeader[1]/ssdh:DocumentInformation[1]/
ssdh:DocumentIdentification[1]/ssdh:Identifier[1]
The location can be changed in pipdefinitions.xml. See the following figure: schema-based
service contents.
<ssdh:DocumentIdentification schemaVersion="">
<ssdh:Identifier>
[identifier]:[GlobalUsageCode]:[PipInstanceId]:[InReplyToTrackingId]
:[InitiatingRoutingId]
</ssdh:Identifier>
<ssdh:StandardDocumentIdentification schemaVersion="">
<ssdh:Standard>RosettaNet</ssdh:Standard>
<ssdh:Version>PIP3B3v11.00</ssdh:Version>
</ssdh:StandardDocumentIdentification>
</ssdh:DocumentIdentification>
The value of the Identifier element should take the form of a colon-separated list of strings. The first
string is the identifier. Optionally include:
l GlobalUsageCode second
l PipInstanceId third
l InReplyToTrackingId fourth
l InitiatingRoutingId fifth
Blank fields are acceptable within the string. For example, to set only the identifier and
pipInstanceId the string would look like:
Myid::12346
Where Myid is the identifier value and 12346 is the PipInstanceId.
The GlobalUsageCode, PipInstanceId, InReplyToTrackingId and
InitiatingRoutingId values from the outbound message are used in building the protocol
headers in the packaged RNIF message.
Note that the PipInstanceId, GlobalUsageCode, InReplyToTrackingId and
InitiatingRoutingId values are stripped from the service content that is packaged and
produced to the trading partner. The identifier value are included in the packaged service content.
If enabled, the PipInstanceId, GlobalUsageCode, InReplyToTrackingId and
InitiatingRoutingId are written to the received service contents produced to integration. This
allows back-end systems to know the values necessary for sending response documents for dual-
action PIPs.
The CidxPackaging attribute must be set on the community integration pickup exchange. You can
add CidxPackaging = true by opening the pickup exchange's maintenance page in the user interface
and adding it on the message attributes tab. Alternately, you can add it in an inline process or as
JMS metadata. Do not add the attribute to MMDs picked up from integration; the attribute cannot be
parsed from MMDs.
Service content alone does not provide sufficient information to trade CIDX messages. You must use
MMDs or an equivalent means (JMS metadata, inline process).
Do not set the CidxPackaging attribute on the community delivery exchange for receiving messages
from partners. Interchange can identify CIDX messages when unpacking messages sent by partners.
Web services
Web services are self-contained, application functions that can be described, published, located,
and invoked over the Internet. Web services use XML to code and to decode data, and SOAP to
transport data using open protocols, typically HTTP.
A Web Services Provider creates and exposes a service and can publish the availability of
the WSDL that describes the service.
A Web Services Consumer discovers a desired service and launches a request to the service
provider.
A Web Services Relay acts as both consumer and provider in an intermediary position for an
exchange between an endpoint consumer and provider pair. In this intermediary role,
Interchange may provide additional processing.
l Web Services consumer configuration
l Web Services provider configuration (exposes Web Services)
l Web Services relay – The Web Service Relay is a role in which Interchange acts as both consumer
and provider.
l Tracking
l SOAP version 1.1 or 1.2
l One-way and two-way services
l Synchronous and asynchronous exchanges
l Content and transport security (HTTP(s), WS-Security, SSL/TLS, WS-Encryption, WS-Signature)
l DMZ integration
The Web Services that you provide to partner service consumers are typically two-way services.
l One-way and two-way (request/response) services
l Synchronous and asynchronous exchanges
l Content and transport security: (HTTP(s), WS-Security, SSL/TLS, WS-Encryption, WS-Signature
l DMZ integration
l Wizard driven WSDL import and configuration
The web services that you consume from partner service providers are typically two-way services.
Related topics
In the context of a Web Service exposed by Interchange, and configured for synchronous response:
1. A partner connects to Interchange over HTTP in client mode, and sends a service request.
2. Interchange maintains the HTTP connection open while processing the request in a service
(through a series of components).
3. Interchange generates a service response (or a fault).
4. Interchange applies outbound collaboration settings to control how the response is sent to the
Web Service consumer partner.
5. Interchange sends the response back through the pending HTTP connection.
6. The partner closes the HTTP connection.
1. A partner connects to Interchange over HTTP in client mode, and sends a service request.
2. Interchange acknowledges (at protocol level) the receipt of the message.
3. The partner closes the HTTP connection.
4. Interchange processes the request in a service (through series of components).
5. Interchange applies outbound collaboration settings to control how the response is sent to the
destination application or partner.
6. Interchange delivers the message(s) to the final destination
Configuration overview
To configure a Web Services provider, you complete two principal tasks:
In this mode, Interchange behaves as a client requesting a service from a remote server.
In the context of an Interchange exchange between two endpoints (application or partner exchange
participants), we configure a component with a Web Services map to collect data through a Web
Service interface. During the message processing, Interchange:
1. Applies the processing of the Web Services map. This map uses the Web Services connection
that is linked to the Web Services delivery.
2. Opens a connection to the Web Service provider using the Web Services partner delivery.
3. Applies the outbound collaboration settings to control how the Web Service request is sent to
the Web Service provider partner.
4. Submits the request.
5. Consumes the response.
6. Closes the connection to the Web Service provider.
7. Continues the configured message processing of the participant-to-participant exchange (using
the response).
Prerequisites
To complete the Web Service consumer configuration you require:
l Interchange, licensed for Web Services functions.
l The WSDL file for the service you want to consume.
l Optionally set validation rules for inbound web service message authentication.
For configuration details, see Validation rules: Web Services tab on page 943.
Order of tasks
1. Task 1: Add a community on page 719
2. Task 2: Add a partner on page 719
3. Task 3: Add a Web Service trading delivery and Web Service connection on page 719
Interchange enables you to configure message processing in such a way that you can open a
connection to a Web Service provider in the course of a message-processing sequence. Interchange
essentially pauses message processing for the time it takes to open a connection and launch a
request/response exchange with the Web Service provider. Once the requested data is obtained,
Interchange resumes the message processing sequence.
In order to open the Web Service connection, the processing resource calls the Web Service type
trading delivery in order to use the connection information it contains.
In this Web service consumer case, the trading delivery is not used in a standard way to deliver a
message at the end of message processing.
The following procedure describes how to::
l Add a trading partner delivery that enables you to request and consume services from a Web
Services provider
l Add a Web Service type connection to enable a message processing component to open and use
the Web Service trading delivery channel configuration.
In this procedure you are aided by a wizard that parses connectivity and message format information
from the Web Service provider's WSDL.
Prerequisites
l Add a Community to represent your organization. See Add a community on page 136.
l Add a Partner to represent the Web Service provider. See Add a partner to a community on page
148.
l Obtain the Web Service Provider's WSDL, or note the URL to the Web Service, in order to retrieve
the WSDL during configuration.
Procedure
1. In the user interface select Partners > Manage partners to open the Partners page.
2. Select the partner you want to use to represent the Web Service provider.
3. On the partner graphic, click the Partner delivery icon.
4. On the Partner deliveries page, click Add a delivery.
5. On the Choose a message protocol page, select Web Services (HTTP) and click Next.
6. On the Choose configuration type page, select Configure delivery by parsing a WSDL, if
you have a WSDL file available on your file system, and click Next.
7. On the same page, select one of the following:
l Browse to WSDL file – Select this option if you have a copy of the Web Service
provider's WDSL on your file system. Click Chose file, and then browse and select the file.
l Retrieve WSDL from URL – Select this option if you want to retrieve the WSDL from the
Web Service Provider's server. Enter the URL of the service. If the WSDL is located behind a
proxy, you must also enter the proxy connection information:
o Proxy user
o Proxy password
o Proxy port
o Proxy host
8. Click Next.
9. On the Choose community page, select the community that represents your organization as a
Web Service consumer, and then click Next. The communities you see in the drop-down list
are communities that are currently linked to the partner.
10. On the Processing connection page, complete the following fields and then click Next:
l Configure a new processing connection — This field is selected by default to
automatically create the connection. You can de-select it if you want to manually create the
connection.
l Application name — Enter a name for the processing connection or keep the default.
l Sending Party — You previously entered this name.
l Receiving party — You previously entered this name.
l SOAP action — This information comes from the Web Service.
l Request mode — Select the appropriate request mode from the drop-down list for this
connection to indicate a synchronous or asynchronous call.
l Body type — Select the appropriate body type from the drop-down list for this
connection.
11. On the Choose transport protocol page accept the default HTTP protocol and click Next.
12. On the Configure the HTTP settings page, complete the fields and then click Next:
l URL — This field is automatically populated with information parsed from the WSDL.
l Clients must use SSL to connect to this server — Select this option if you must
connect to this server using SSL. If you select this option, you can also select the Enable
host name verification option.
l This server requires a user name and password — Select this option if the partner's
server requires this information, then complete the following fields:
o User name — Enter the client's user name.
o Password — Enter the client's password.
o Confirm password — Enter the client's password again for verification.
13. On the Exchange Name page, enter a name for this delivery. This is the friendly name that is
used to identify this delivery in the user interface.
14. Click Finish.
The collaboration settings you set at the level of a partner delivery override any other level of
delivery settings (default, community, category).
Web Services collaboration settings exist for each community/partner pair that are linked through a
Web Services partner delivery.
If you created a Web Services partner delivery using the WSDL parsing wizard, the collaboration
settings were automatically generated for community/partner pair. For more information, see Add a
Web Services trading delivery on page 322.
Note: To view the URL that is associated with a delivery exchange in this list, hover the mouse
over the delivery exchange name in the tree.
4. Select the partner delivery for which you want to view the settings.
5. In the right pane, select the categories of settings you want to view or modify for this delivery.
You can choose as many categories as you want. The following categories may have an impact
on Web Service outbound messages:
l Pick the sender routing ID
l Pick the receiver routing ID
l Set sending rules for the WebServices message protocol
l Set resend attempts and interval for reliable messaging
l Specify the signing certificate to use
l Specify the receipt signing certificate to use
l Specify the partner's encryption certificate to use
l Specify whether to encrypt or sign messages and choose algorithms
l Specify the delivery exchange to send messages to
The interface displays the settings for the categories you select. You can modify these settings.
6. After making any modifications, click Save Changes.
From the drop-down box, select the sender routing ID to use.
Receiver routing ID
From the drop-down box, select the receiver routing ID to use.
Web Services
Setting Description
Payload Select an option:
location l SOAP body (default)
l MIME attachment
l None – Setting the payload location to none has the effect of not
attaching the payload as an attachment or in the SOAP body. In
this case, a SOAP handler must be configured to attach the
payload where desired.
SOAP action The SOAP action header value. If specified for outbound messages, the
value is used when packaging. If no value is specified, SOAPAction
defaults to a blank string.
SOAP version Select a version for the outbound call:
l 1.1
l 1.2
This setting is overwritten by any metadata specifying a SOAP version
that is linked to a message that is being handled.
Setting Description
Encrypt Select this option to encrypt outbound messages
messages When you select this option, you can also select the following options:
l Encrypt attachments
l Encrypt SOAP body
l Xpaths to encrypt – Click Add to specify one or more xPaths
l ID refs to encrypt – Click Add to specify one or more ID refs
Sign Select this option to digitally sign the messages you send.
messages When you select this option, you can also select the following options:
l Sign attachments
l Sign SOAP body
l Xpaths to sign – Click Add to specify one or more xPaths
l ID refs to sign – Click Add to specify one or more ID refs
Use MTOM to Select this option to specify parts of the payload to use Message
encode Transmission Optimization Mechanism (MTOM) encoding of outbound
messages messages. This is base 64-encoding for preserving the integrity of non-
ASCII parts of payloads (for example, blank spaces). To use MTOM
encoding of outbound messages, the receiving partner must be able to
auto-detect the encoded parts and decode them.
The transaction engine auto-detects and decodes such messages when
it receives payloads from partners.
When you select this option, you can also select the following options:
l Xpaths to encode – Click Add to specify one or more xPaths
l ID refs to encode – Click Add to specify one or more ID refs
Use Select this option to require that messages sent via the Web Services
username delivery contain a UsernameToken element in the SOAP header. The
token when Username token element includes the user name and password
sending specified below.
l Use password digest in place of plain text during
authentication – Select this option to have Interchange convert
the password to digest form. The digest is a hash of the password
that is base 64-encoded.
l User name – Enter the user name
l Change password
Setting Description
Enable web Select this option to enable reliable messaging on outbound messages
service to this partner.
reliable When you select this option, you can also select the following option:
messaging l Enable WebServices reliable messaging anonymous
addressing
Resend attempts
Setting Description
Resend attempts The maximum number of resend attempts allowed.
Resend interval in minutes Interval between resend attempts.
Signing certificate
From the drop-down list of available certificates, select the certificate to use to sign
outbound messages to this partner.
From the drop-down list of available certificates, select the certificate to use for signing
receipts to this partner.
From the drop-down list of available certificates, select the certificate to use for encrypting
files sent to this partner.
From the drop-down list, select the delivery to use in the event that there is no delivery
point that matches the default delivery for this partner.
l In the SOAP body
l In the SOAP header
l In the SOAP header and body
l Included as MIME attachments
The framework also supports WS-Security and WS-Addressing. Additionally, you can configure
custom SOAP handlers to perform processing on SOAP messages. Possible processing operations
include payload transformation, payload validation and WS header processing.
Architecturally, the Web Services framework passes messages through a chain of handlers. Each
handler performs an action on a message. For example, for an inbound message the WS-Security
handlers are responsible for decrypting and signature validation. For an outbound message, the WS-
Security handlers are responsible for encryption and signature creation. Other handlers are
responsible for other message actions. These actions are broken down into phases, with several pre-
defined built-in phases such as pre-dispatch, dispatch, and so on. Each phase is a collection of
handlers. Axis2 enables the user to choose the phases for the handlers, as well as the order of
execution of handlers. You can also define handlers in a module that you plug into a running Axis2
system. One such module is Rampart, which provides an implementation of WS-Security.
Adding a transport in the delivery exchange wizard for the Web Services message protocol is just like
setting up an HTTP exchange. For information see HTTP (embedded) trading c onfiguration on page
268 and HTTP (external) trading configuration on page 267.
Also see:
l Web Services transport user accounts on page 730 for information about user accounts owned
by communities and partners for advanced tuning controls
l Web Services collaboration settings on page 722 for information about collaboration settings
Payload packaging
The payload that is transported in a SOAP message can be located in the SOAP body, header, header
and body, or packaged as a MIME attachment.
When packaging an outbound message, a decision must be made on where to place the payload.
The packaging decision is specified as part your exchange agreement with your trading partner. By
default outbound payloads are placed in the SOAP body of the packaged message. To specify that
the payload should be packaged as an attachment, change the payload location field on the
WebServices tab in the collaboration settings area of the user interface. Setting the payload
location to none has the effect of not attaching the payload as an attachment or in the SOAP body.
In the none case, you must configure a SOAP handler to attach the payload where desired. To do
this you require the optional Interchange Software Development Kit.
To override the payload location collaboration setting in the user interface, set the metadata items
named AxisShouldAddPayload and AxisAddPayloadAsAttachment.
l AxisShouldAddPayload – Set the value to true to add the payload to the body or as an
attachment. set the value to false to not automatically include the payload.
l AxisAddPayloadAsAttachment – Set the value to true to package payloads as attachments.
Set the value to false to package payloads as part of the SOAP body.
The SOAP body can only contain XML payloads. Package other payload types and large XML
payloads as attachments.
Payload unpackaging
An inbound SOAP message can have payloads in the SOAP body, header, header and body, or as
attachments.
By default, Interchange integrates payloads found in the SOAP body and integrates any MIME
attachments. To disable the default SOAP body and attachment integration, use the Advanced tab
of the Community Web Services delivery exchange modification page.
To override the payload integration values that you set on the Advanced tab, you can set override
values for the AxisShouldIntegrateSoapBody and AxisShouldIntegrateAttachments
message metadata attributes.
Message metadata
The following defines the message metadata elements.
l AxisShouldAddPayload – Overrides the value of the payload location field in the
Collaboration settings area of the user interface. Specifies whether to automatically add the
payload to an outbound SOAP message. A value of false indicates the payload should not be
added to the SOAP message. AxisAddPayloadAsAttachment specifies the location to add the
payload if AxisShouldAddPayload is true.
l AxisAddPayloadAsAttachment – Overrides the value of the "Payload location" field in the
Collaboration settings screen of the user interface. Specifies whether to add the payload as an
attachment or in the SOAP body.
l AxisShouldIntegrateSoapBody – Overrides the "Integrate SOAP body" setting on the
Advanced tab of the maintenance page for a community Web Services delivery exchange.
Specifies whether to integrate the contents of the SOAP body.
l AxisShouldIntegrateAttachments – Overrides the integrate attachments setting on the
Advanced tab of the maintenance page for a community Web Services delivery exchange.
Specifies whether to integrate the attachments of the SOAP message. The value defaults to true.
l AxisMessageType – Specifies whether a message is a request or a response. This is set by
Interchange.
l AxisToEndpointReference – Specifies the address of the Axis service to which inbound
WebServices messages are directed for handling and processing.
l SOAPAction – Specifies the SOAP action header value. If specified for outbound messages, the
value is used when packaging. If no value is specified, SOAPAction defaults to
handleMessage.
l ValidateBodyXML – Specifies whether XML payloads should be schema-validated before
adding the payload to the SOAP body of an outbound message. A value of true enables
validation. Validation is false by default.
WS-Security handler
Interchange uses Apache’s Axis2 implementation to handle the WS-Security for the SOAP messages.
The Rampart module in Axis2 has WS-Security handlers to use for signing and encrypting SOAP
messages and for validating signatures and decrypting.
The Rampart module supports signature and encryption operations on the SOAP envelope and
Body. Axway added support for signature and encryption operations on SOAP attachments in the
Rampart implementation. The Rampart module is defined under axis2.xml.
The collaboration settings area of the user interface allows configuration of signing and encryption
parameters. See Web Services collaboration settings on page 722.
WS-Addressing handler
Interchange uses the Apache Axis2 implementation to handle the WS-Addressing for SOAP message.
Interchange provides two versions of the Axis2 file:
l axis2.xml
This file has handlers for adding routing information to the SOAP header and interpreting
routing information. If you want to use WS-addressing you must use this file.
l axis2NoWSAddressing.xml
This file disables WS-Addressing. If you do not want to use WS-addressing, select this file.
To select the axis file version to use:
l In client (consumer) mode – Go to the Web Services settings of the community collaboration
settings. Then select the axis2.xml version in the Send handler config file field.
For more information, see Web Services collaboration settings on page 722.
l In server (provider) mode – Go to the management page for the community Web Services
pickup. Select the Advanced tab and then select the axis2.xml version in the Receive
handler config file field.
Default configuration
The default configuration of the Web Services message protocol enables trading of secure XML
payloads between two instances of Interchange. The default configuration is useful to get two
instances of Interchange trading quickly. Typically, users will need to modify the default
configuration. This requires the use of the optional Interchange Software Development Kit.
l Payload is placed in the SOAP body.
l WS-Security is enabled. The SOAP body is signed and encrypted.
l SOAP action value is blank.
l WS-Addressing header is added. Included are the sender and receiver routing IDs and a message
ID.
l SOAP body contents are integrated.
l Attachments are integrated.
l Synchronous acknowledgements are not enabled, so a 204 HTTP response is sent immediately
on completion of unpackaging.
l WS-Addressing header is expected. Sender and receiver routing IDs and message ID are
expected.
l Community accounts are owned by communities. Any partner can use community accounts.
l Partner accounts are owned by specific partners. Only the specified partner can use a partner
account.
Implement MTOM encoding
Message Transmission Optimization Mechanism (MTOM) is used to optimize selected nodes of XML
outbound Web Services messages that contain Base64 data sent to partners, when the selected
node is above a size threshold of 100 bytes. This optimizing or encoding speeds up the message
transfer since the large elements are moved outside of the HTTP message into a MIME attachment.
MTOM does not change the envelope other than to add a reference to the attachment that contains
the content of a specified node. The element is replaced by a link to the attachment. The link is what
is parsed instead of a large element.
To use MTOM encoding for outbound messages, the receiving partner must be able to auto-detect
the encoded parts and decode them. You must configure your Communities to use the outbound
MTOM.
When an inbound Community receives embedded HTTP payloads from partners, if the inbound
Pickup Exchange is configured to receive Web Services HTTP messages, Interchange auto-detects
and decodes the MTOM messages.
The following XML is an example of an MTOM policy found in a WSDL associated with the service.
This policy indicates to your trading partners that your service supports MTOM encoding and
decoding.
<wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-
policy"><wsoma:OptimizedMimeSerialization optonal="true" />
</wsp:Policy>
To configure a Community to send outbound MTOM Web Services messages:
The user is locked out for a specified number of minutes. The user must wait until the lockout
interval expires, unless an administrator unlocks the user before the interval ends.
4. Edit the following fields.
l Maximum retries before a user is locked out – The number of times a user can try
unsuccessfully to log on before the user is locked out.
l Lock out length (in minutes) – The interval in minutes that a lockout is in effect.
5. Click Save changes.
Problem: Web Services addressing inter-operation with non-Interchange Web Services partners
In the Interchange WS-addressing header, From and To values use the default routing ID for the
community and partner. These are normally AS2-like values, such as ZZCOMMUNITY, ZZPARTNER.
However, non Interchange Web Services endpoints create WS-Addressing headers that use From
and To values that are the URL of the endpoints.
Solution: For inbound messages, enter the URLs sent by partner for From and To as default values,
or use alternate routing IDs in the community and partner settings.
For outbound messages, either set the expected URL value as the default routing ID, or use
collaboration settings to set the desired values. See Web Services collaboration settings on page
722.
WebSphere MQ configuration
Interchange supports the use of WebSphere MQ as a JMS provider. You can use WebSphere with
Interchange when you configure any of the following transports:
l JMS community trading pickup
l JMS partner trading delivery
l JMS application pickup
l JMS application delivery
Before you can use WebSphere with Interchange, you must perform preliminary tasks in both the
WebSphere and in the Interchange environments.
Configuration in MQ Explorer
Working in MQ Explorer:
1. Add an initial context.
2. In the file system path, specify the path in the bindings directory where you want to store
bindings file.
3. Create a new connection factory of type “Queue connection factory”. Select Transport to be
MQ Client if your MQ installation is on some other system than your Interchange installation.
4. Set properties for the QMGR you are trying to connect, hostname (listener port) of your MQ
installation, and specify the Server connection channel you use for connecting.
5. Create the destination JMS queues to use.
6. When WebSphere MQ configuration is complete, copy the created .bindings file to any folder
on your JMS client machine.
1. Copy the following files from the MQ Installation JAVA path (Windows example: C:\Program
Files (x86)\IBM\WebSphere MQ\java\lib) to an Interchange integration engine
accessible directory (example C:\Axway\Interchange\site\jars\).
l com.ibm.mq.jar
l com.ibm.mqjms.jar
l connector.jar
l fscontext.jar
l jms.jar
l dhbcore.jar
l jndi.jar
l providerutil.jar
l com.ibm.mq.jmqi.jar
2. Configure the Trading Pickup of type secure file (JMS) as a Community Delivery Pickup.
Example configuration / JMS settings tab:
Example configuration / Advanced tab:
For the use case described in this topic:
l WebSphere MQ is installed on two servers.
l One queue manager, QM1, has been created.
l One instance of QM1 is active, and is running on one server.
l The other instance of QM1 is running in standby mode on the other server. This server performs
no active processing, but is ready to take over from the active instance of QM1, if the active
instance fails.
It is important to take into account the time required for the standby instance of a multi-instance
queue manager to become active after the active instance becomes unavailable. Preliminary tests
indicate that the required time may vary between 30 seconds and two minutes, depending on
configuration and reason for failure.
Set up WebSphere MQ
To use a WebSphere MQ queue manager as a multi-instance queue manager:
1. Use the crtmqm command to create a single queue manager on one of the servers.
2. Place the queue manager data and logs in shared network storage directory.
3. On the other server, rather than create the queue manager again, use the addmqinf command
to create a reference to the queue manager data and logs on the network storage.
All the connection information for the standby server must be the same as for the main server,
including the port.
Set up Interchange
After you install the MQ multi-instance queue manager, you must configure Interchange to use the
multiple instances. To do this you can create a new pickup or modify an existing pickup.
During the MQ pickup or delivery creation, the creation wizard displays the Settings page. On
this page:
3. Enter settings for the main MQSeries server.
4. Select the option Multi-instance queue manager. When you select this option, the
following field is displayed: MQSeries standby server. Enter the standby server address.
5. Click Save.
Existing pickup
Alternatively, you can add the multi-queue instance to an existing IBM MQ pickup. To do this:
1. Open the modification page for an existing MQSeries pickup or delivery.
2. Select the IBM MQSeries settings tab.
3. Select the option Multi-instance queue manager. When you select this option, the
following field is displayed: MQSeries standby server.
4. Enter the standby server address.
5. Click Save changes.
During the period when neither of the WebSphere MQ server instances is available, Interchange tries
to connect to the primary and to the secondary server on each retry. After a connection is
successfully made to a server instance, the WebSphere MQ cache is updated. In the cache, the last
functional host for the exchange point is specified, so that all future messages are exchanged
directly with the active WebSphere MQ server.
X.400
The following topics describe how to set up and maintain X.400 delivery exchanges and the X.400
subsystem, which includes X.420 and X.435 embedded servers.
Caution Interchange provides X.400 support primarily for legacy users of the X.420 and X.435
electronic mail standards or users who need to conduct e-commerce messaging with new
partners via X.400. Other users and their partners should first consider adopting AS1 or
another EDIINT protocol.
This documentation presumes you have a comprehensive knowledge of X.400.
For a list of supported systems, see the Interchange Installation Guide.
Concepts
l X.400 subsystem on page 739
l Valid characters for O/R addresses on page 740
l X.400 (embedded) servers on page 751
l X.400 log events on page 763
l X.400 glossary on page 763
X.400 subsystem
The X.400 subsystem within Interchange supports trading via the X.420 and X.435 electronic mail
standards. The subsystem, which is configured and managed through Interchange user interface,
runs as a native process. Interchange communicates with the subsystem via a socket-based API.
The following figure illustrates a two-computer cluster of Interchange with two X.420 community
delivery-pickup exchanges.
Two machine cluster with two X.420 exchanges:
When Interchange runs in a cluster, one X.400 subsystem is loaded across the cluster for each
configured X.420 and X.435 embedded server for a delivery exchange. Each processing node in
Interchange can send and receive from each running subsystem. Interchange starts and stops the
subsystem on the appropriate machine within the cluster.
An X.420 or X.435 delivery set up in a community defines the local user and whether a local
message transfer agent (MTA) or external MSP7 is used. The remote MTA is defined on the
subsystem settings tab of the X.420 or X.435 embedded server for the community.
l Apostrophe
l Colon
l Comma
l Equal sign
l Forward slash
l Hyphen
l Left and right parentheses
l Period
l Plus sign
l Question mark
l Space
To launch the wizard, open the summary page for a community or partner. Click Trading pickup
or Partner delivery in the navigation graphic at the top of the summary page. On the page that
opens, click Add a delivery.
l External (RFC1006) – The X.400 subsystem listens on this port for connections from other
(most likely external) subsystems. Exchange of data between subsystems is accomplished over
this port.
Interchange communication is done using the User Agent API port.
This port must be 102 or greater than 1023. Click inside the field to display a list of ports in use
by Interchange. If 102 is in use, type a port number greater than 1023, but not a port already
used.
l System starter – The port used by Interchange and the X.400 subsystem to monitor the status
of each other. If Interchange loses the connection on this port, it tries to restart the X.400
subsystem. If the X.400 subsystem loses the connection, it assumes Interchange has shut down
and shuts itself down as well.
l OSITP – The listening port for the lower layer OSI stack process within the X.400 subsystem.
l User agent API – The API port used by Interchange and the X.400 subsystem user agent. All
messages exchanged between Interchange and the UA go through this port.
Local configuration
l MTA name – The name of the message transfer agent in the X.400 subsystem.
l Alias/Routing ID – Depending on whether the delivery is associated with a community or
partner, the routing ID of the community or partner in Interchange, selected from a drop-down
list of the profile’s available routing IDs.
l Country name – The two-character ISO country code. For a community delivery exchange, this
should be the code of the community’s country. If a partner delivery exchange, this should be
the code of the partner’s country.
For a list of codes see the International Organization for Standardization (ISO):
http://www.iso.org/iso/home.html.
Connect to an Administration Management Domain (ADMD) – When selected, the following field
displays.
l Administration domain name – Identifies an administrative domain name (ADMD).
This is the name of an ADMD service provider for client organizations (PRMDs) that subscribe to
an ADMD provider for X.400 message routing and related services. For clients who connect
directly to other PRMDs, bypassing an ADMD, set the name to a single space character.
For a community delivery exchange, this should be the code of the community’s ADMD. If a
partner delivery exchange, this should be the code of the partner’s ADMD.
The X.400 subsystem is started upon adding the delivery exchange. You can check the log files for
the status. The log files are at:
<install directory>/<common
directory>/subsystems/X400/<subsystem name>/runtime/log
Note If you and your trading partner both use Interchange, you do not have to manually add the
partner’s X.400 exchange and other data to the partner. Instead, export your community
profile as a partner profile and have your partner import the profile file. Have the partner do
the same. Exchanging profiles is the norm when both parties use Interchange.
Choose subsystem
l Subsystem – The name of the X.400 subsystem, selected from a drop-down list, your
community uses to send messages to the partner.
Remote configuration
l Alias/Routing ID – Depending on whether the delivery is associated with a community or
partner, the routing ID of the community or partner in Interchange selected from a drop-down
list of the available routing IDs.
l Country name – The two-character ISO country code. For a community delivery exchange, this
should be the code of the community’s country. If a partner delivery exchange, this should be
the code of the partner’s country.
For a list of codes see the International Organization for Standardization (ISO):
http://www.iso.org/iso/home.html.
l Connect to an Administration Management Domain (ADMD) – When selected, the
following field displays:
o Administration domain name – Identifies an administrative domain name (ADMD). –
This is the name of an ADMD service provider for client organizations (PRMDs) that subscribe
to an ADMD provider for X.400 message routing and related services. For clients who
connect directly to other PRMDs, bypassing an ADMD, set the name to a single space
character. For a community delivery exchange, this should be the code of the community’s
ADMD. If a partner delivery exchange, this should be the code of the partner’s ADMD.
Select the use existing option and click Next to select an existing remote MTA from a drop-down
list.
If there are not any existing MTAs or you want a new one, select the new option and click Next.
The following are the fields on the settings and advanced tabs.
To open the maintenance page for an X.400 pickup or delivery, open the summary page for a
community or partner. Click Application delivery on the navigation graphic at the top of the
summary page. On the Application deliveries page, click a transport type.
l External hostname – The computer a partner’s remote X.400 system connects to when
sending messages to your community. The host name can be an IP address or a fully qualified
domain name.
The default value can be used only if your instance of Interchange runs on a single computer
with a single processing node. That is, the instance does not run in a clustered environment of
multiple processing nodes (multiple nodes on the same or different computers).
If you run Interchange in a cluster, change the value to your external load balancer. You must
do this to make sure inbound messages can be delivered to your community.
While multiple processing nodes are the norm in a clustered environment of Interchange, only
one instance of an X.400 system can exist per cluster. There can be multiple X.400 systems
within a cluster, but only a single instance of each system on a single machine. This is why the
load balancer, not the host of a single processing node, must be specified as the host.
When you export your community profile as a partner profile for your partners to import on their
instances of Interchange, the partners send messages to the host specified in this field.
l External port – The port a partner’s remote X.400 system connects to when sending messages
to your community. Just as with the external hostname field, the default port value can be used
only if your instance of Interchange runs on a single computer with a single processing node. If
you run Interchange in a cluster, specify the port of your external load balancer.
When you export your community profile as a partner profile for your partners to import on their
instances of Interchange, the partners will send messages to the port specified in this field.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners.
Backup files are stored in \<install directory>\common\data\backup, unless you
specify otherwise.
Restrict maximum file size for this transport – Optionally lets you specify the maximum
size of files a transport can handle.
If Interchange receives a file larger than the maximum, the file is rejected and a message is
written to the events log. If received via HTTP, a 413 response also is sent and the connection is
closed. A 413 message is Request Entity Too Large.
The maximum size must be expressed in bytes. Do not use commas. For instance, a kilobyte is
1024 bytes, a megabyte is 1048576 bytes, a gigabyte is 1073741824 bytes.
The smallest maximum allowed is 1000 bytes. On the opposite extreme, you can enter the
largest number the field can accommodate.
This control is available only for transports used for picking up messages from integration or
receiving messages from partners.
l Maximum files per polling interval – The highest number of messages the system can
retrieve each time it polls.
l Polling interval (seconds) – The interval in seconds Interchange waits before polling for
messages to retrieve.
directly to other PRMDs, bypassing an ADMD, set the name to a single space character. For a
community delivery exchange, this should be the code of the community’s ADMD. If a
partner delivery exchange, this should be the code of the partner’s ADMD.
l Private Domain Name – Identifies a private domain name (PRNM) relative to the
administration domain name or country. Typically, this is a company name.
l Organization name address attribute – Identifies an organization relative to the PRNM.
l Organization unit name address attribute 1 – Identifies units such as divisions and
departments within the organization. There are four optional fields available for this information.
Do not use fields 2 to 4 without also using the preceding field. For example, enter information in
field 3 only if you have first entered information in fields 2 and 1.
l Organization unit name address attribute 2 – Field 2 if needed.
l Organization unit name address attribute 3 – Field 3 if needed.
l Organization unit name address attribute 4 – Field 4 if needed.
l Common name – An address attribute that can contain any information, up to 64 characters.
l Free-form name address attribute of the O/R descriptor – Any text you want, up to 64
characters.
l Telephone number address attribute of the O/R descriptor – The telephone number of
the originator or the recipient.
l Domain-defined attribute type address attribute 1 – DDA type for attribute 1. A domain-
defined attribute or DDA has two parts: type and value. Four pairs of type-value fields are
available to use at your discretion.
o The connection was successful, but the partner’s HTTP server took longer than the response
timeout interval to return a 200 OK response indicating the message was successfully
received. A 200 OK response is a transport response, separate from a message protocol
response such as an AS2 receipt.
Note that in the last case, the 200 OK response also will include the receipt if synchronous
receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if
an asynchronous receipt was requested, the partner will connect later to send it.
Retries occur according to an algorithm that starts at 5 minutes. The interval between retries
increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60
minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the
fifth and each subsequent retry occurs at 60 minute intervals.
For example, if retries is 3, the system will try connecting again in 5 minutes if the initial
connection attempt fails. If this retry attempt also fails, the system attempts a second retry in
10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the
message is given a failed status. So after four attempts (the first attempt plus 3 retries), the
message fails. You can search for and manually resubmit failed messages in Message Tracker.
Retries do not occur precisely at these intervals because each connection attempt takes some
seconds, which varies by computer. So retries actually occur after the connection attempt time
plus the interval.
This control applies only to retrying to send messages, not receiving. It applies only to retrying
to send related to transport issues. It does not apply to successfully sent messages for which
receipts have not been received as expected. Another control, resends, determines how many
times the system will resend a message when a receipt is not received from the partner. For
information about resends, see reliable messaging in the collaboration settings chapter.
l Back up the files that go through this transport – Indicates whether the system backs up
copies of the messages it retrieves from integration or receives from partners.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure. Without backups, a message in process cannot be recovered if the server or a processing
node stops or restarts. Backups also are needed if you want the ability to resubmit messages to
back-end applications or resend messages to partners.
Backup files are stored in <install directory>\common\data\backup, unless you specify
otherwise.
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for partner trading deliveries.
There are various places in the user interface where you can open the maintenance page for an
embedded server. But the embedded servers page is the primary page for managing these servers.
On this page you can view a list of all embedded servers and open the maintenance page of any
server by clicking its name.
Not only can you use this page to manage embedded servers, but your DMZ or network
administrator may find it a useful guide for configuring ports for load balancers and firewalls. Text
on the page describes how an administrator should use the displayed information.
The following are ways to open the embedded servers page:
Lastly, you can open an embedded server’s maintenance page by opening the maintenance page of
a delivery exchange that references the embedded server. On a community summary page, click
Delivery exchanges in the navigation graphic at the top of the page. Click an embedded transport
to open the maintenance page for the delivery exchange. On the settings tab click the link for
opening the maintenance page of the embedded server.
X.25 over X.400 in Interchange has been tested only on AIX and Windows operating systems. An
AIX computer must have an AIX-compliant X.25 card. A Windows computer must have an Eicon
X.25 card. In addition, properties in files under common\subsystems\X400 must be edited. Editing
the files requires expert technical knowledge of Interchange and X.25. You may need the help of an
Axway professional services consultant to implement X.25 over X.400.
TCP settings
l Port – The port used by partners to connect to your X.400 subsystem.
X.25 settings
l X.25 gateway port – The internal subsystem port for communicating to its X.25 process. This
can be any port not already in use. Click the field to display a list of ports in use.
l Bind to host – If you run Interchange in a cluster of multiple computers, you can select a
single computer in the cluster as the designated host. This field is available for users who may
not have multiple X.25 cards for each computer in the cluster and need to lock the X.25-enabled
subsystem to the one computer with an X.25 card. If you have a clustered environment and do
not use this field, you may need an X.25 load balancer to compensate.
User agent
l Delivery timeout (minutes) – Minutes a delivered message can stay in the UA’s in-queue. If
the UA does not read the message but accepts responsibility for it, the MTA removes the message
from the in-queue and sends a non-delivery notification to the message originator.
A value of 0 means the UA has a retrieval queue. This imposes responsibility for the message on
the UA once the message is placed in the UA’s in-queue. The MTA does not supervise this queue.
l Anonymous addressing – When set at Allowed the UA accepts messages from a sender with
an O/R address that does not match any of the remote nodes. Forbidden is the default setting.
l Change UA password – Select to type a new password to authenticate communication
between Interchange and the X.400 subsystem. The original password was randomly generated.
There is no need to remember this password, as it is only used internally. This field is provided in
case the password should be changed for some reason.
l Default time notification expected within (minutes) (X.435 only) – If EDI notifications
are requested for a transfer, the maximum time to wait. If exceeded without an EDIN, the
original message is marked NACKED.
l Time notification expected within (minutes) (X.420 only) – If notifications are requested
for a transfer, the maximum time to wait. If exceeded without a notification, the original
message is marked NACKED.
l Log size (bytes) – The maximum size the log file can grow to before an action specified in the
next field is triggered.
l Log full action – When the log file reaches the maximum size specified in the preceding field,
one of the following actions is taken.
o Stop logging. Logging is stopped.
o Rename log file. The log rolls to a new file and logging continues.
l Log level – Use the drop-down list to select the kind of information to log.
Advanced OSITP
l Maximum transport connections – The maximum number of transport connections the
transport module can accept. The memory required for transport connections is calculated as
Max transport connections * Buffer size. Memory is reserved for each new transport
connection at connection time. If memory cannot be reserved, the connection is not
established.
l Maximum network connections – The maximum number of network connections the
transport module can handle.
o Make sure a heavy workload in one direction does not block traffic in the opposite direction.
For example, assume an X.25 subscription allows a maximum of connections to 8 logical
channels. If Maximum inbound is set to 6 and Maximum outbound to 2, heavy
incoming traffic does not block outgoing traffic because there always are two logical
channels available for outgoing transfers.
o Divide X.25 resources between processes. For example, if an X25 subscription provides 8
logical channels, setting both Maximum inbound and Maximum outbound to 2 makes
sure at least 4 logical channels are always available for other processes.
Bandwidth is not limited by these parameters. If Maximum inbound is 6 and Maximum
outbound is 2, an outgoing connection receives full bandwidth if it is the only current
connection.
Although primarily for distributing X.25 resources, the parameters can be used to distribute
TCP/IP resources. With TCP/IP:
o The limit on the number of concurrent connections typically is higher than for X.25.
o The system administrator can change these limits locally on the computer. The network
supplier does not influence these limits.
l Maximum queued messages – The maximum number of messages that can be queued for
the local MTA routing. If reached, a new incoming connection is rejected with a code indicating
temporary congestion.
l RTS window size – Specifies the number of checkpoints that can be transmitted without
receiving an acknowledgment from the remote MTA. Checkpoints are used to synchronize a
sending MTA with a receiving MTA. This value must be larger than 0.
l RTS checkpoint size – Specifies the maximum amount of data that can be transmitted
between two checkpoints. Valid values are within the range of 0 to 100 KB. 0 means check
pointing is disabled.
l RTS recovery – Determines whether recovery should be carried out on broken connections. As
recovery is seldom enabled, the default selection is disabled.
MTA logging
l Log size (bytes) – The maximum size the log file can grow to before an action specified in the
next field is triggered.
l Log full action – When the log file reaches the maximum size specified in the preceding field,
one of the following actions is taken.
o Stop logging. Logging is stopped.
o Rename log file. The log rolls to a new file and logging continues.
l Log level – Use the drop-down list to select the kind of information to log.
MTC logging
l Log size (bytes) – The maximum size the log file can grow to before an action specified in the
next field is triggered.
l Log full action – When the log file reaches the maximum size specified in the preceding field,
one of the following actions is taken.
o Stop logging. Logging is stopped.
o Rename log file. The log rolls to a new file and logging continues.
l Log level – Use the drop-down list to select the kind of information to log.
Advanced MS
l Maximum message size (bytes) – The maximum size of messages to retrieve from the
message store (MS). If a larger message is found, it is deleted from the MS.
l Message fetch limit – Maximum number of messages retrieved per MS poll. This an be used to
control flow at peak hours. When the limit is 0, no messages are retrieved, which can be useful
when testing the MS connection without retrieving any messages.
l Minimum transfer speed (bytes/second) – Specifies the lowest expected network transfer
speed. This value is used to calculate maximum transfer times. A message transfer is aborted
when the maximum transfer time is exceeded.
l Transport class – Transport class proposed when a connection is made.
External MSs
Lists the external message stores that have been set up for the server. If there are none, click Add
and see MSP7 for an X.400 server on page 759.
Remote MTAs
Lists the remote message transfer agents that have been set up for the server. If there are none, click
Add and see Remote MTA for an X.400 server on page 761.
Click the port field to display a list of ports already in use.
l Zone – If you want to receive messages through a Secure Relay DMZ zone, select a zone. This
drop-down field is available only if zones have been set up.
See Enable port forwarding for an exchange on page 484 for more information.
Once you add an external message store, you must add at least one polling schedule. See P7 client
polling schedules on page 760.
Communication parameters
The PSAP, SSAP and TSAP fields identify the service access points for the different communication
layers. At least one — typically TSAP — must be specified. To specify a hexadecimal value, enclose
the value in single quotes (for example, '7C,A2').
l TSAP – The MS TSAP selector. TSAP can be a maximum of 20 characters.
l Local TSAP – The local MS TSAP selector. TSAP can be a maximum of 20 characters.
l SSAP – The MS SSAP selector. SSAP can be a maximum of 16 characters.
l PSAP – The presentation service access point field specifies the MS OSI address for the net,
transport, session and presentation layer.
To add or manage polling schedules, open the maintenance page for an embedded X.400 server.
Scroll down the Subsystem settings tab to the External MS section. Click Manage under the
Manage scheduling column for a message store. If there are not any message stores, add one
(see MSP7 for an X.400 server on page 759).
The following figure shows an example of a schedule for polling continuously at one minute
intervals every day but Sunday. This illustrates the default schedule. However, you can set up any
schedule or multiple schedules. See the following figure: Continuous polling at one minute intervals
l Click Add to add a polling schedule.
l Click Details to change a schedule.
l Click Add or Modify to save changes.
l Name – The name of the remote message transfer agent.
l TCP host – The fully qualified domain name or IP address of the computer running the remote
message transfer agent.
l TCP port – The port the remote message transfer agent listens for connections.
l Remote MTA password – Password the local MTA uses to access the remote MTA.
l Local MTA password – Password the remote MTA uses to access the local MTA.
Communication parameters
The PSAP, SSAP and TSAP fields identify the service access points for the different communication
layers. At least one — typically TSAP — must be specified. To specify a hexadecimal value, enclose
the value in single quotes (for example, '7C,A2').
l TSAP – The MS TSAP selector. TSAP can be a maximum of 20 characters.
l SSAP – The MS SSAP selector. SSAP can be a maximum of 16 characters.
l PSAP – The presentation service access point field specifies the MS OSI address for the net,
transport, session and presentation layer.
l Country name – The two-character ISO country code. For a community delivery exchange,
this should be the code of the community’s country. If a partner delivery exchange, this should
be the code of the partner’s country. For a list of codes, see ISO (International Organization for
Standardization): http://www.iso.org/iso/home.html.
Advanced settings
l Version 84 – Select only if the MTA version is 84. Typically the MTA version is greater than 84.
l RTS X.410 mode – Select to specify RTS x.410 mode. Typically MTA version 84 only uses RTS
x.410 mode.
l External name – Specify an external name if more than one remote MTA has the same name.
Although the MTA identity in the Name field must be unique, this field is for specifying a name
an MTA may have in common with another MTA. If an external name is specified, it is used when
contacting the MTA. If an external name is not specified, the value of the Name field is used.
Interchange
See Troubleshooting with the log4j file on page 1095 for using the log4j.properties file to monitor
events related to the X.400 subsystem within Interchange. Following are two additional properties
you can add to the file:
log4j.category.com.cyclonecommerce.tradingengine.transport.
system.consumption.active.consumers.x400Consumer=debug
log4j.category.com.cyclonecommerce.tradingengine.transport.
system.production.producers.X400Producer=debug
These properties generate events about message production and consumption.
X.400 subsystem
You can review the X.400 logs at:
<install directory>/<common
directory>/subsystems/X400/<subsystem name>/runtime/log
There is a PDF manual that describes codes in the logs. The PDF file is named X400_Error_
Codes.pdf. The file is at:
<install directory>/<common
directory>/subsystems/X400/<subsystem name>
X.400 glossary
Term Description
ADMD Administrative management domain name. This is an X.400 address attribute.
DDA type Domain-defined attribute type. This is an X.400 address attribute.
DDA value Domain-defined attribute value. This is an X.400 address attribute.
Term Description
EDIM An EDI message (EDIM) is the message payload exchanged by trading partners.
This is applicable to X.435 only and not X.420.
EDIN An EDI notification (EDIN) is a receipt returned to the message originator by the
message recipient. This is applicable to X.435 only and not X.420. An EDI
notification can be positive, indicating the recipient accepted the message, or
negative, indicating the recipient rejected the message.
external The X.400 subsystem within Interchange has one running local MTA. The local
MTA MTA exchanges messages with external (remote) MTAs.
lower OSI Lower protocol levels of the X.400 subsystem.
layer
message See MTA in this table.
transfer
agent
MHS Message handling service. MHS is an electronic mail system that provides store-and-
forward services for sending messages to users of the mail system.
MS Message store. A mail box for storing messages. The message store P7 access client
is used for accessing a remote message store mailbox
MS P7 Terms for the process in the X.400 subsystem that accesses an external message
client store to retrieve or deliver messages. This is using the standardized X.400 protocol
called P7.
MTA Message transfer agent. This is the message switch within an X.400 network. It
accepts messages submitted by message originators' UAs for transmission to
recipients' UAs. The transmission is normally done through other MTAs.
MTC Message transfer communication process. A process in the X.400 subsystem that
process handles the communication with external MTAs. The MTC process is a part of the
local MTA.
MTS Message transfer service. The functional component of MTS is MTA.
O/R Originator/recipient (O/R) addresses identify message senders and receivers. An
address O/R address consists of required and optional values organized hierarchically.
O/R Originator/recipient descriptor is the standardized X.420 address. The O/R
descriptor descriptor has some optional user friendly address attributes in addition to the O/R
address.
OSI Open system interconnection.
Term Description
OSITP OSITP (open system interconnection transport) is the name of the process in the
process X.400 subsystem that handles the lower protocol levels in the OSI protocol stack
(the transport and network layers).
P7 client Message store P7 client.
PRMD Private management domain name. This is an X.400 address attribute.
UA The X.400 user agent. In Internet email this is the same as the mail user agent
(MUA).
upper OSI Upper protocol levels of the X.400 subsystem.
layer
user agent See UA in this table.
X.400 A suite of ITU-T recommendations defining standards for data communication
networks for message handling systems. More commonly known as email.
X.400 The X.400 trading engine that runs as a sub-system of Interchange.
subsystem
X.420 Developed in 1984, X.420 preceded X.435 as an X.400 standard. Also known as
IPM for interpersonal messaging, X.420 was intended as an electronic mail system
for people and not applications. But as e-commerce exchanges grew, some
companies adopted X.420 for business-to-business electronic data interchange. In
1990 the X.435 standard was introduced for EDI message exchanges (see X.435 ).
However, X.420 remained the more commonly used standard.
X.420 A local X.420 user. Defines the X.400 addresses of the community.
local
partner
X.420 A partner with whom X.420 messages are exchanged. Defines the X.400 addresses
remote of the partner.
partner
X.420 UA The X.420 user agent is the interface between the user (application) and the X.400
message transfer system. It helps the user to encode and decode inbound and
outbound messages according the X.420 protocol.
X.420 UA The X.420 user agent process in the X.400 subsystem.
process
Term Description
X.435 An X.400 standard for exchanging EDI messages between trading partners. X.435
supports use of receipts named EDINs that are signed by message recipients and
sent to message originators. EDINs are proof for originators that messages were
received by the intended recipients. X.435 supports the following EDI message
types: X12, EDIFACT and TRADACOMS.
X.435 The security services in the X.435 protocol are comprised of digitally signed EDI
security transmissions and acknowledgments. The generation and verification of digital
signatures are based on RSA, a public-key cryptography system. The local X.435
UA has an RSA key pair consisting of one private and one public key. The private
key is stored encrypted locally. The public key must be made available to your
partners before any communication involving digital signatures can take place.
X.435 UA The X.435 user agent is the interface between the user (application) and the X.400
message transfer system. It helps the user to encode and decode inbound and
outbound messages according the X.435 protocol.
X.435 UA The X.435 user agent process in the X.400 subsystem.
process
See RFC 3280 at http://www.ietf.org/rfc/rfc3280.txt for complete information about Internet X.509
Public Key Infrastructure. For a glossary of Internet security terms, go to
http://www.ietf.org/rfc/rfc2828.txt.
Concepts
l PKI description on page 768
l Why use encryption and digital signatures on page 770
l Interchange encryption method on page 771
l Encryption and signing summary on page 772
l Ensure data integrity and trust on page 773
l Certificate basics on page 774
l SSL authentication on page 775
l Distribute certificates to partners on page 776
l Self-signed or CA certificates on page 777
l When to get certificates on page 777
l Manage expiring certificates on page 777
l Trusted roots on page 779
l Auto import intermediate and root certificates on page 780
l FIPS compliance on page 781
l Manage certificates on page 782
l Replace certificates automatically on page 811
PKI description
Interchange supports public key infrastructure (PKI) to securely trade business documents over the
Internet. PKI is a system of components that use digital certificates and public key cryptography to
secure transactions and communications.
PKI uses certificates issued by certificate authorities (CAs) to provide authentication, confidentiality,
integrity and non-repudiation of data. The following defines these in more detail.
l Authentication – Authentication is verification of the identity of a person or process.
Authentication confirms that a message truly came from the source that sent it.
l Confidentiality – Confidentiality is the assurance that a message has been disclosed only to
the parties authorized to share the information.
l Integrity – Integrity is the assurance that the information has not been altered in any way and
is precisely true to the source.
l Non-repudiation – Non-repudiation is proof that a recipient received a message. This protects
a sender from a false denial that a recipient did not receive a message.
PKI options
There are two PKI options, and Interchange supports both. They are self-signed certificates and
commercial PKIs. The option you choose can depend on a number of factors, such as cost, human
and system resources, and the degree or sophistication of security desired.
Self-signed certificates generated by Interchange and certificates generated by commercial PKIs all
support the X.509 standard for public key certificates. You can use any X.509 certificate, regardless
of the source, in document transactions with partners. For example, you can generate a self-signed
certificate for your community and export a public encryption key in a certificate with the profile to
a partner for use in encrypting and signing documents sent to you. Meanwhile, you can engage in
trading with partners who have sent you public keys in Entrust or VeriSign certificates.
The following explains each security option in more detail.
Self-signed certificates
Interchange can generate root certificates in which you are, in effect, acting as your own certificate
authority. Interchange supports single-key pair self-signed certificates for both encrypting and
signing documents and dual-key pair self-signed certificates in which one certificate is used for
encrypting and the other for signing.
Self-signed certificates are easy to make and use. They are best suited for use within relatively small
trading groups. This is because you must implicitly trust a partner’s self-signed certificate; there is
no chain of trust to independently vouch for the certificate. Such a trust relationship can more
suitably be managed among a small number of partners.
Although self-signed certificates can provide a high-degree of security, the degree depends on the
vigilance and administrative skills of the persons managing them. Generally speaking, the use of
self-signed certificates does not have the rigorous discipline and orderly structure inherent to a
commercial PKI.
Commercial PKIs
A commercial PKI is an organization set up for the centralized creation, distribution, tracking and
revocation of keys for a potentially large community of partners. A commercial PKI has a
documented certificate policy (CP) that indicates the applicability of a public key certificate to a
specific community or class of applications with common security requirements. A commercial PKI
also has a certification practice statement (CPS), which details the practices the CA follows for
issuing public key certificates.
There are two types of commercial PKIs:
l In house – An in-house PKI enables you to achieve complete control of security policies and
procedures, but also carries the burden of management and cost to set up and maintain the
system.
l Outsourced – You can leverage the services of PKI systems such as VeriSign, Entrust and other
third-party certificate authorities. You purchase keys and certificates for use in trading partner
relationships and let the CA manage security policies and such details as certificate revocation.
The level of outsourcing can range from purchasing an end-entity public key certificate of a
certain validity period from a commercial PKI to outsourcing all of the PKI services that your
organization requires.
Interchange has a local trust list for storing and managing established trust relationships ( Add a
certificate on page 792). The application maintains a list of common public CA certificates similar to
those kept in web browsers. Although convenient, this pre-determination of trust might not
complement your organization’s security policy. The decision of who to trust rests with your
organization. For example, a trader might accept certificates issued by its own root CA and its
trading partners’ root CA, but not from partner B, who the trader has not done business with in the
past. If you choose not to accept partner B’s root CA certificate, your system does not accept any
certificates issued by partner B. The greater the number of root CA certificates you choose to accept,
the more open your community is to others.
Scalability
The use of self-signed certificates relies on users to exchange certificates and establish trust in each
other. This informal web of trust works for small groups, but can become unmanageable for large
numbers of partners. In contrast, an in-house or outsourced PKI uses hierarchies, where a certificate
authority serves as a trust anchor for many users. Once trust has been established for the certificate
authority, it is unnecessary to re-establish the trust for other certificates the CA issues. Establishing
hierarchies of users scales equally well for small and large groups.
Certificate revocation
A certificate is expected to be usable for its entire validity period. However, there are circumstances
when a certificate should no longer be considered valid even though it has not expired. Possible
circumstances range from a user name change to suspected compromise of the private key. In such
circumstances an in-house or outsourced CA can revoke the certificate. Interchange can be
configured to compare your partners’ certificates against lists of revoked certificates issued by CAs.
However, self-signed certificates cannot be revoked. You must notify all partners using the
certificate that it should no longer be trusted.
Dual-key pairs
Support for two pairs of public-private keys is a fundamental requirement for some PKIs (for
example, Entrust). One key pair is for data encryption and the other key pair is for digitally signing
documents. Encryption key pairs and signing key pairs are a result of conflicting requirements. One
such requirement is to support different algorithms for encryption and digital signature pairs and
different validity periods. Another reason is to support data recovery, which requires the private keys
for decrypting to be securely backed up, but non-repudiation, which requires the private keys for
signing, not to be backed up. There also might be the requirement to support updating encryption
key pairs and managing decryption key histories even though this conflicts with the requirement to
securely destroy the private key used for signing when updating signing key pairs. Using two key
pairs — an encryption key pair and signing key pair — solves these conflicting requirements.
l Only the addressee can read the message, not any unauthorized persons. Encryption provides
this assurance.
l The message cannot be tampered with. That is, data cannot be changed, added, or deleted
without you knowing it. A document's digital signature provides this assurance.
l Partners who send you documents are genuinely who they claim to be. Likewise, when partners
receive documents signed by you, they can be confident the documents came from you. A
document's digital signature provides this assurance.
l The partners who send you documents cannot claim they did not send them. This is referred to
as non-repudiation of origin. A document's digital signature provides this assurance.
l Partners to whom you send documents cannot claim they did not receive them. This is referred
to as non-repudiation of receipt. A signed document acknowledgment provides this assurance.
The advantage of symmetric key encryption is that it performs the encryption task more quickly than
asymmetric encryption. The advantage of asymmetric encryption is that it allows you to send an
encrypted message to a partner who does not hold your secret key.
To use the best of both, Interchange uses the faster symmetric key to encrypt the document, such
as a lengthy EDI transaction set, and the asymmetric key for the smaller task of encrypting the one-
time session key. The session key can then be securely included with the message for transmission
and allows your partner to decrypt the contents without sharing your secret key.
You can use two types of asymmetric RSA keys:
l Keys issued to you, typically by a certificate authority, and subsequently imported into
Interchange. Such keys are sometimes called managed keys.
l Keys generated by you in Interchange. Such keys are called self-signed keys.
Outbound documents
The document contains the data that needs to be protected. The encryption and signing processes
take place for every document that Interchange sends over the Internet.
Interchange encrypts and signs each document by building three parts: the encrypted document,
the encrypted session key and the digital signature. The following is the process for an outbound
document:
1. A hashing routine (MD5 or SHA-1) creates a digital digest of the document. This digest is a
number. If the data in the transaction are changed, added to or subtracted from, reapplying the
hashing routine produces an entirely different digest. This characteristic of hashing routines
makes it easy for a partner to verify the integrity of an inbound document.
2. The digital digest is encrypted using your private key. This encrypted digest is the digital
signature for this document. It ensures that the data in the document were not changed and
that the document came from you and only you.
3. Interchange generates a one-time session key. This is the symmetric key part of Interchange's
hybrid encryption method.
4. The session key is used to encrypt the document.
5. Your partner's public key is provided in the certificate inside the profile your partner gave you.
It is used to encrypt the session key for transmission. Thus, the key to decrypting the document
has itself been encrypted by your partner's public key and can be decrypted only by your
partner's private key.
6. The document is then sent using whatever transport method you choose for this partner.
Inbound documents
When a document is received by your trading partner, the process is reversed according to the
following steps:
1. Upon receiving the document, Interchange begins security processing.
2. Your partner uses the private key (the matching half to the asymmetric public key you used to
encrypt it) to decrypt your symmetric key.
3. The one-time key that was just decrypted is used, in turn, to decrypt the document. Your
partner now has your message in clear text.
4. With the public half of your public-private key pair that you sent your trading partner in your
certificate (inside your community), your trading partner decrypts the digital signature.
5. Your partner uses the same hashing routine (MD5 or SHA-1) to create a digital digest of the
document. This is called rehashing. Your trading partner then compares this to the digest in the
digital signature you sent. If the two are identical, your partner has proof that the contents of
the document were not altered and that it came from you and only you.
6. The document is now ready to be read into and used by your partner's business application.
Any documents that cannot be successfully processed are failed.
1. Verifying the signature.
2. Validating the verification certificate.
The verification certificate is the certificate containing the public key corresponding to the private
key that was used to create the signature in the first place. This certificate is almost always provided
as part of the signature that is transported along with the signed data.
Signature verification
Signature verification consists of the following steps:
1. Compute a hash value over the signed data.
2. Using the public key in the verification certificate, decrypt the encrypted hash value in the
signature.
3. Ensure the two hash values are equal. If so, the signature is verified. It is known the data has
not been changed since it was signed.
Validating a certificate consists of the following steps:
1. Construct the path from the certificate to its root certificate.
2. Verify the signature of each certificate in the path.
3. Ensure that each certificate in the path has not expired.
4. Ensure that each certificate in the path has not been revoked. See Manage certificate revocation
lists (CRLs) on page 802.
5. Ensure at least one certificate in the path is trusted. A certificate is trusted if it appears in the
appropriate trusted root store (also known as a PSE or personal security environment).
Interchange must always be able to build and validate the complete path of certificates from
verification certificate to its root certificate. However, under security implemented for some other
systems, the process stops with the first encounter of a trusted certificate.
Certificate basics
A certificate contains the public half of your public-private key pair along with other identifying
information about your community and point of contact. You use the public key in your partner's
certificate to encrypt a document for transmission over the Internet. Your partner uses the public
key in your certificate to verify the digital signature of a document received from you.
The following is some basic information about how Interchange uses certificates:
l A community must have a certificate to exchange secure documents. Interchange can generate
the certificate or it can be generated externally.
l Each partner also must have a certificate.
l A community or partner can have only one certificate designated as the default encryption or
signing certificate.
l A community or partner can have multiple certificates.
l The key length for a community certificate does not have to be the same as for a partner’s
certificate.
SSL authentication
Interchange optionally allows certificates to be used for authenticating the identity of trading
partners. Secure Sockets Layer (SSL) protocol authentication provides an added layer of security to
trading relationships.
A community can be in the client or the server role when trading with a given partner.
When setting up a partner trading pickup, you also can specify that "clients must use SSL to
connect to this server." Optionally, you also can require "client-side certificate authentication,"
which means a partner's certificate is used to verify the partner's identity when a connection is
made.
These controls are further described in the topics under Add a partner trading delivery on page 262
and Modify a partner trading delivery on page 327.
Note If you have a partner who uses webMethods, and the webMethods server runs HTTPS and
requires client authentication, and you have not selected an SSL client authentication
certificate, the connection is closed. The reason is not apparent in Interchange.
Interchange produces a socket closed error message, but does not indicate the SSL
handshake failed. To resolve this, select a certificate for SSL authentication in the
community.
The following summarizes what happens when a client connects to an SSL server. These steps apply
whether the community is connecting to the partner's SSL server (meaning the community is
playing the client role) or the partner is connecting to the community's SSL server (meaning the
community is playing the server role). Note that the way Interchange performs these tasks may not
precisely mirror this order. The steps are presented to illustrate the various checks that may occur.
1. The client establishes a socket connection to the SSL server. This could be an HTTP, FTP or
another kind of server.
2. The server sends the client its SSL server certificate. This is a required step in the SSL
handshaking sequence.
3. The client checks whether it trusts the server's certificate.
If the client trusts the server's certificate, the connection is maintained. Otherwise, the client
drops the connection if it does not trust the server's certificate.
This is the end of the authentication process, unless the server is configured to require client
authentication. If client authentication is called for, the following additional steps are performed.
1. The server explicitly asks the client to send its SSL client certificate.
2. The client sends the server its SSL client certificate.
3. The server checks whether it trusts the client's certificate.
4. If the server trusts the client's certificate, the authentication process is completed (unless host
name verification is required as noted in the next step). Otherwise, the server drops the
connection if it does not trust the client's certificate.
5. If host name verification also is called for, the client takes the additional step of comparing the
name of the SSL server to the name in the server's certificate. If the names are not the same, the
client drops the connection.
The private half of your key pair always remains on your computer. The public half is given to your
partners when you send them your community, which includes the certificate and public key, or the
certificate alone.
The following topics describe how to give your certificate to partners. In all cases, we recommend
confirming the certificate fingerprints with your trading partner before exchanging documents.
Self-signed or CA certificates
You and your partners should decide whether to use self-signed certificates or certificates from a
third-party certificate authority. Consider the following when deciding:
l Self-signed certificates are easily created. The primary disadvantage is lack of verification by a
trusted third party.
l The primary advantage of CA certificates is that the identity of the certificate holder is verified by
a trusted third party. Disadvantages include the extra cost and administrative effort.
l A CA provides a centralized source for posting and obtaining information about certificates,
including information about revoked certificates.
l You know or suspect a certificate has been compromised.
l You need to replace a certificate that is about to expire.
l You want to change your encryption key at planned intervals just as you would change a
password.
For procedure see Set up certificates for a community on page 792 or Import certificates for partners
on page 798.
If possible, perform certificate updates when your server is not processing outbound documents. By
observing this precaution you can avoid documents being rejected by partners.
If you generate a new self-signed certificate because the old one has expired, become defective or
corrupted or cannot be used for any other reason, you should export your certificate to a file and
distribute it to your partners by a secure means, which includes in-person, standard mail, or private
delivery service.
Interchange checks
Interchange server checks at least once a day for certificates that are close to their expiration dates.
A check is performed after the server is started. Thereafter, Interchange performs a daily check. The
time the check is performed depends on the value of the Interval element in the alerts.xml file,
which is at <install directory>\conf. If the interval is less than or equal to 60 minutes, the
check is performed between midnight and 1:00 a.m., server time. If the interval is much less than 60
minutes, the check may be performed twice or more before 1:00 a.m. If the interval is greater than
60 minutes, the check is performed at the time past midnight equal to the interval length. For
example, if the interval is 90 minutes, the check is performed at 1:30 a.m.
Interchange posts a message on the user interface home page 14 days before a community or
partner certificate expires. It also displays an alert message on the Tasks and Alerts toolbar menu. If
your license allows users to have certificates (for example, CSOS functionality), Interchange also
generates messages about user certificates that are about to expire.
Expiring certificates
If there are outstanding alerts for a certificate about to expire, Interchange continues generating
alerts at the interval specified in the alerts.xml file, regardless of time of day, until the certificate
is replaced.
The messages about expiring certificates remain until the certificates are deleted. The messages give
you time to replace certificates before they expire. We recommend replacing certificates before,
rather than after, expiration so that trading is not disrupted. Regardless, expired certificates must be
replaced. Expired certificates cannot be used for encryption, decryption or signing.
1. If a partner's certificate is about to expire, notify the partner and ask for a replacement.
2. In <install directory>\common create a subdirectory named certarchive. Create
subdirectories of certarchive named community and partner.
3. On the home page, click the message about an expiring certificate to open the certificate's
maintenance page.
4. Click Export this certificate.
If a community or user certificate, select the option to export the private key to a .p12 file.
Save the file in <install directory>\common\certarchive\community.
If a partner certificate, select the option to export the public key to a .p7b file. Select Include
all certificates in the certificate path if possible. Save the file in <install
directory>\common\certarchive\partner.
5. Obtain a replacement certificate.
If a community certificate, create a self-signed certificate or obtain a CA certificate. See Set up
certificates for a community on page 792.
If a user certificate, see Axway CSOS on page 1008.
If a partner certificate, import the replacement certificate the partner sends you. See Import
certificates for partners on page 798.
6. Delete the old certificate. On the community or partner summary page, click Certificates on
the navigation graphic at the top of the page, select the certificate and click Delete this
certificate. If a user certificate, open the user maintenance page certificates tab, select the
certificate and click Delete this certificate.
Trusted roots
Trusted roots are the foundation upon which chains of trust are built in CA certificates. Underlying a
certificate issued by a certificate authority is a root, self-signed certificate. There can also be
intermediate certificates in the chain. In Interchange, trusting a CA root means you trust all
certificates issued by that CA. Conversely, if you elect not to trust a CA root, Interchange does not
trust any certificates issued by that CA. Document trading fails in Interchange when a non-trusted
certificate is used.
The self-signed certificates you can generate in Interchange are root certificates. This is because you
are, in effect, your own CA when you generate a self-signed certificate. Interchange by default trusts
the self-signed certificates that it generated for you. Interchange also by default trusts the roots of
the CA-issued certificates of a community's partners.
Interchange is pre-loaded with intermediary and trusted root certificates in <install
directory>\conf\certs. The pre-loaded roots are not trusted, but are simply available in the
certificate store for validating end-entity certificates as they are imported and used.
Interchange can import trusted roots contained in files with the following extensions: .cer, .crt,
.der, .p7b and .p7c. Using a directory hierarchy, as Interchange does in \conf\certs, is
recommended for arranging certificates by issuer.
There are various ways you can obtain such trusted root files:
l You can use Interchange to export a certificate file with an extension of .p7c. See Export a
certificate to a file on page 799.
l You can check whether trusted root files are available for download on the website of the public
CA that issued the certificate.
l If the certificate was issued by an in-house CA such as Entrust, you can ask the CA administrator
for a trusted root file.
l If the certificate is present in a browser, you can use the application's trusted roots option to
export the trusted root to a file.
Trusted root certificate files can be imported one by one in the user interface. Alternately, you can
copy trusted roots en masse to <install directory>\conf\certs, where the certificates are
loaded when the server is restarted. See Auto import intermediate and root certificates on page 780.
When you import a trusted root for a certificate to Interchange, we recommend that you compare
the MD5 fingerprints in both the trusted root and the certificate to verify that they match.
To successfully trade using CA-issued certificates, Interchange must be able to establish the chain of
trust running through end-entity, intermediate and root certificates. This is why Interchange is pre-
loaded with many intermediate and root certificates issued by various CAs. These certificates are
available for trusting upon importing end-entity certificates containing public-private encryption key
pairs or only public keys.
Intermediate subdirectory. These certificates are added to the database upon starting the server the
first time. If certificates are added, these are added to the database when the server is re-started. See
the following <install directory>\conf\certs:
To add certificates, copy the files to the directory for the appropriate CA. If a CA is not already
represented, add a directory for it.
Typically, root certificates have extensions of .cer, .crt or .der. Add root certificates to the Root
directory for the appropriate CA. Intermediate certificates should have extensions of .p7b or .p7c.
An intermediate certificate should contain both the intermediate certificate and the root certificate.
Interchange ignores any files in the certs directory with extensions other than .cer, .crt, .der,
.p7b and .p7c. So you can add readme files if you want to document added certificate files.
Errors or warnings that occur when certificates are imported are written to the _cn.log file.
FIPS compliance
All CSOS, CSOS Activator, and eSubmissions applications, and some Interchange implementations
must adhere to the Federal Information Processing Standards (FIPS). In Interchange, FIPS is a
license key-enabled option that turns on FIPS-compliant implementations of certain cryptographic
algorithms. If it is enabled, your organization and your trading partners must use certificates with
key lengths that adhere to the standard, or trading will be blocked.
If your implementation requires FIPS compliance, ensure you understand the standard and security
algorithms. National Institute of Standards and Technology (NIST) requirements are available at
http://csrc.nist.gov/publications/PubsFIPS.html.
Caution Once the FIPS-compliant license key is enabled in your implementation and trading begins,
you must not disable it. Conversely, if trading begins on an non-FIPS enabled
implementation, you must not enable it.
Manage certificates
The following topics describe how to manage Interchange certificates. If your software license
allows users to have certificates, see Axway CSOS on page 1008.
Concepts
l Globally prohibit exporting private keys on page 801
l Manage certificate revocation lists (CRLs) on page 802
l Advanced CRL settings on page 805
l Analyze certificates for errors on page 809
l Collect data about certificates on page 810
Procedures
l Certificates pages on page 786
l Add a certificate on page 792
l Set up certificates for a community on page 792
l Import certificates for partners on page 798
l Export a certificate to a file on page 799
l Delete certificate on page 801
l Add a CRL on page 804
l Manage CRL lists on page 804
The page primarily is for searching for and diagnosing certificates. It is not for importing certificates,
changing the usage of certificates or generating certificates.
In addition to the certificates search page, there are other places in the user interface for viewing
certificates (see Certificates pages on page 786). The search page, however, provides the broadest
view of all certificates at once.
When you open the page the first time, before adding any end-entity trading or server certificates,
many certificates are displayed on the search results side of the page. These are pre-loaded
certificates from certificate authorities. All are intermediate, root CA or self-signed certificates. None
are end-entity certificates. If you have not added any certificates, you can confirm this by searching
for end-entity certificates only.
To successfully trade using CA-issued certificates, Interchange must be able to establish the chain of
trust running through end-entity, intermediate and root certificates. This is why Interchange is pre-
loaded with many intermediate and root certificates issued by various CAs. These certificates are
available for trusting upon importing end-entity certificates containing public-private encryption key
pairs or only public keys.
For information on the types and uses of certificates, see Certificates and keys on page 767.
The primary parts of the certificate search page are the certificates search panel on the left side and
the search results area on the right. Controls for performing searches based on conditions are on the
left panel. Certificates matching search conditions display on the right, along with links for viewing
more details.
The certificates search panel on the left side has controls for specifying conditions for searching for
certificates and displaying results. You can click Show/Hide to collapse or expand the panel as
desired.
The following fields enable you to launch, manage and save searches:
Search name
If you leave the field blank and click Find, messages matching conditions set in the certificates
search panel are searched for. Once search results are displayed, you can type a name for the search
in the search name field and click Save. Later you can run the same search again by selecting the
saved search from the search name drop-down list under the Saved searches section of the
certificates search panel.
Search commands
l Find – Click to search for all certificates matching any conditions specified on the search page.
If no conditions are specified, the default action is to search for all certificates.
l Save – Click to save the conditions for a search you have performed. Use saved searches to
repeat the application of search criteria without re-entering the criteria.
l Clear – Click to clear the page of search conditions and begin a search from scratch.
Saved searches
l Search name – Use the drop-down box to display and select the name of any saved searches.
Then use the commands in this section to Remove or Execute the selected saved search.
l Manage shared searches - Click this command to open screens that enable you share or
unshare any of your saved certificate searches.
Filters
Use the filter options in this section of the panel to filter your search results:
l Friendly name – Friendly name of the certificate.
l Serial number – Decimal or hexadecimal certificate serial number.
l Type:
o Root CA
o Intermediary
o End Entity
o Self-signed
l Key usages:
o Encryption
o Signing
o Non-repudiation
o Encryption and signing
o Unknown
l State:
o Pending
o Operational
o Expired
o Failed
o Revoked
o Unknown
l Application usage:
o Encryption
o Sign EDIINT messages and receipts
o SSL
o Unused
l Filter by:
o Subject
o Issuer
Extensions
Pick from a list of predefined extensions, or create your own custom extensions to use as search
filters. To use a custom extension you must use an object identifier (OID). For a list of OIDs, see
http://www.alvestrand.no/objectid/top.html.
Date validity
Use the date validity fields to specify a validity beginning and/or end date for the certificate.
Save a search
To save a search:
1. Set conditions for a search and click Find to run the search.
2. When the search results are displayed, type a name for the query in the search name field at the
top left of the certificates search panel.
3. Click Save.
A plus sign ( + ) located next to a certificate indicates that you can expand the view to include
related intermediate or root certificates.
Click Details on an entry to open a details pop-up window for a certificate. The window provides
much information about the certificate on multiple tabs.
You can use the Details window to:
l Attribute a friendly name to the certificate
l Delete the certificate
l Export the certificate to a file.
To the left of the Details link for a certificate is the Find descendants icon. Click this icon to open
to open the Certificate descendants page. The page lists details about the certificate as well as the
descendants of the certificate, if any exist. A descendant is a certificate that is issued by the
certificate you are currently viewing, or by another descendant of the same certificate.
A plus sign ( + ) located to the left of a results row, indicates that the certificate has other certificates
in its path. Click the plus sign to display the roots.
Certificates pages
To manage certificates for communities and partners you work in the Certificates page.
To open the Certificates page, click the Certificates icon located on the navigation graphic at the
top of the community or partner summary page.
The pages for the certificates of communities and partners are different, but have some of the same
information. You open the certificate pages the same way for both a community and a partner: by
clicking Certificates on the navigation graphic at the top of a community or partner summary
page.
Use the certificates page to:
l View a list of all certificates for a community or partner.
l View detailed information about certificates.
l Open the certificate wizard to generate or import a key pair and certificate for a community.
l Export a certificate and public key to a file for transmittal to your partners.
l Import a partner’s certificate.
l Delete a certificate.
l Designate a different certificate as the default used by a community or partner.
l Manage PGP certificates, if your user license supports PGP.
l The default certificate for signing documents (if any).
l The default certificate for encrypting documents.
l The default certificate for use in authenticating SSL connections (see SSL authentication on
page 775).
l A list of all certificates associated with the community along with state, usage and expiration
dates of each certificate.
The displayed certificates also are known as end-entity certificates. In the case of CA-issued
certificates, end-entity certificates have a chain of trust that includes intermediate and root CA
certificates. In the case of a self-signed certificate, it is both the end-entity and root certificate.
If the community has more than one certificate, you can select another as the default certificate
and click Save changes.
The Default signing certificate field displays the default signing certificate for the community. If
the community has more than one certificate with either digitalSignature or nonRepudiation
usage specified (or both), you can select another certificate from the drop-down list as the default
certificate and click Save changes.
The State column displays one of the following certificate states for each certificate:
l Operational – The certificate is valid and can be used. This state only means the certificate can
be used, not that it is in use. Interchange rejects an outbound message when packaging is
attempted with an expired or revoked certificate.
l Expired – The certificate is past its validity period and no longer can be used.
l Revoked – A certificate authority has invalidated the certificate and it no longer can be used.
l Pending – The certificate is not yet valid, usually because it is before the date that begins the
certificate's validity period.
l Failed – The certificate is corrupted and cannot be used, usually due to an error while importing
it to the certificate store.
The Usage column displays the usage that was selected for the certificate during certificate
creation:
l Encryption – The certificate is only used for keyEnciperment.
l Non-repudiation – The certificate is only used for nonRepudiation.
You can elect not to trust a root certificate by clicking Untrust to the right of the root certificate
name. If you do untrust, the system no longer recognizes the end-entity partner certificate as
valid. This could affect many end-entity partner certificates. You cannot restore trust on this tab.
To trust the roots again, import the partner end-entity certificate or the root certificate. The
easier method is importing the end-entity certificate, as the system trusts the root by default.
A single CA might be listed multiple times on the tab, because each has multiple roots, each with
unique fingerprints under which it issues certificates. To view the fingerprints, select a root and
review the MD5 and SHA1 fingerprints on the details tab. By comparing fingerprints you can
choose to trust some but not all of a CA's certificates.
To import a trusted root, click Add a trusted root certificate and see Import certificates for
partners on page 798.
l Trusted SSL root certificates tab – The trusted SSL root certificates tab displays the trusted
roots of partners' certificates that, when presented by partners, enable the partners to connect to
the community's SSL servers that require client authentication. For an explanation of trusted
roots and the consequences of untrusting, see Trusted roots certificates tab. See SSL
authentication on page 775.
To import a trusted root, click Add a trusted root certificate for SSL servers on the
certificates page and see Import certificates for partners on page 798.
more than one certificate, you can select another as the default certificate and click Save changes.
This tab displays only if your user license supports PGP. For more information, see PGP secure
trading on page 693.
The displayed certificates also are known as end-entity certificates. In the case of CA-issued
certificates, end-entity certificates have a chain of trust that includes intermediate and root CA
certificates. In the case of a self-signed certificate, it is both the end-entity and root certificate. The
trusted roots of partner end-entity certificates are displayed on the trusted root certificate tabs of the
communities that trust them.
If the partner has more than one certificate, you can select another as the default certificate and
click Save changes.
Valid certificate states are:
l Operational – The certificate is valid and can be used. This state only means the certificate can
be used, not that it is in use.
l Expired– The certificate no longer can be used.
l Revoked – A certificate authority has invalidated the certificate and it no longer can be used.
l Pending – The certificate is not yet valid, usually because of a difference between the valid date
and time in the certificate and the host clock.
l Failed – The certificate is corrupted, usually due to an error while importing it to the certificate
store.
PGP certificates – If your user license supports PGP, the PGP certificates tab displays the default
certificate, if any, for encrypting documents. It also lists all PGP certificates associated with the
partner. If the partner has more than one certificate, you can select another as the default certificate
and click Save changes. See PGP secure trading on page 693 for more information about PGP
certificates.
If you change anything, click Save changes.
The following topic explains the tabs on the certificate information page.
General tab
l Name – A user-defined name for a certificate. Naming the certificate can help identify the
community or partner it belongs to.
Immediately below the Name field, one or more messages might be displayed. Such messages
provide information about the certificate's status. Possible messages are:
o This is the default signing certificate – Indicates that the certificate is the default for
signing documents.
o This is the default encryption certificate – Indicates that the certificate is the default
for encrypting documents.
o This is the default SSL certificate – Indicates that the certificate is the default certificate
submitted to servers to authenticate your identity. See SSL authentication on page 775.
l Intended usage – Describes the functions that the certificate can perform. The intended
usage does not mean the certificate is being used for that purpose, only that it can be:
o Signing (digitalSignature)
o Non-repudiation (nonRepudiation)
o Encryption (keyEncipherment)
l State – Indicates whether the certificate can be used. Valid states are:
o Operational – The certificate is valid and can be used. This state only means the certificate
can be used, not that it is in use.
o Expired – The certificate no longer can be used.
o Revoked – A certificate authority has invalidated the certificate and it no longer can be
used.
o Pending – The certificate is not yet valid, usually because of a difference between the valid
date and time in the certificate and the host clock.
o Failed – The certificate is corrupted, usually due to an error while importing it to the
certificate store.
l Subject – The name of person or entity who was issued the certificate.
l Issuer – The name of the person or entity that issued the certificate. If the issued to and by
names are the same, the certificate is self-signed.
l Valid from – The date range the certificate is valid.
l Certificate path – If a CA certificate, the certificate path or chain of trust for the certificate
appears. This field does not apply to self-signed certificates. A chain of trust or certificate chain
is an ordered list of certificates that includes the certificate of the end-user and certificates of the
issuing CA. A trusted root is a public key that is verified as belonging to an issuing CA, which is
called a trusted third party.
Details tab
The X.509 standard defines the information displayed on the Details tab.
l Version – The version of the X.509 standard that applies to the certificate.
l Issuer – The issuer is the X.500 distinguished name of the CA or entity that signed the
certificate. In cases of a self-signed certificate, the issuer and subject are the same. Using the
certificate implies trusting the signer.
l Serial number – The serial number uniquely identifies the certificate. The CA or entity that
issued the certificate assigned this number. If the issuer revokes a certificate, it can place the
serial number on a certificate revocation (CRL) list.
l Subject – The subject is the X.500 distinguished name of the entity whose public key the
certificate identifies. A distinguished name has the following parts:
C — Two-letter ISO country code
L — City or locality name
O — Organization name
OU — Organizational unit
CN — Common name of a person
l Valid to – The date the certificate expires, provided it is not compromised or revoked before
that date.
l Valid from – The date the certificate became valid.
l Signature algorithm – The algorithm the CA used to sign the certificate.
l Public key information – An algorithm identifier that specifies the public key crypto system
this key belongs to and any associated key parameters, such as key length.
l Public key – The public key of the certificate.
l MD5 and SHA1 fingerprints – Fingerprints are a way to verify the source of a certificate.
After you import or export a certificate, you can contact your partner and ensure the fingerprints
at both ends are identical. Do this before attempting to exchange documents. If the fingerprints
do not match, one of the certificates might be corrupted or out of date.
l Key usage – Identifies the purpose of the key in the certificate, such as encipherment, digital
signature or certificate signing.
Trusts tab
The Trusts tab identifies the communities and SSL servers that trust the certificate.
Add a certificate
A community has the following options for adding a certificate:
l Create a self-signed certificate. See Generate self-signed certificates on page 793.
l Import a certificate and private key from a file. See Import key pair in certificate file on page 797.
l Retrieve a certificate from a certificate authority. See the following topics:
o Import Entrust certificate on page 794
o Import RSA Keon certificate on page 796
A partner has the single option of importing a certificate from a file. See Import certificates for
partners on page 798.
If your software license allows users to have certificates, see PGP secure trading on page 693.
If generating or importing a replacement certificate and you and your partners trade via the AS2
message protocol, you can use CEM to send certificates to partners.
If you want to import a certificate from a third-party CA, such as VeriSign, you must obtain the
certificate using your Internet browser and export it to a file before you begin this procedure. You
must export the certificate to a file that contains the private key and the entire chain of trust. You
need the password used to export the file from your browser to load the certificate into Interchange.
If your organization has a CA server, check with the server administrator about certificate generating
requirements before using this procedure.
This is not the procedure to use for importing a partner’s certificate. For that, see Import certificates
for partners on page 798.
1. To associate a certificate with a community, click Certificates on the navigation graphic on
the community summary page to display the certificates page.
2. Click Add a certificate to launch the certificate wizard.
3. Select one of the following:
l Create a self-signed certificate – Click if you want Interchange to generate one self-signed
certificate, for both signing and encrypting, or two self-signed certificates (dual key), one for
signing and one for encrypting. Go to Generate self-signed certificates on page 793.
l Import a certificate and private key from a file – Click if you want to use a third-party
certificate. Go to Import key pair in certificate file on page 797.
l Retrieve a certificate from a certificate authority – Select if your organization has a
certificate authority server. The following certificate authorities are supported:
Entrust Technologies. Go to Import Entrust certificate on page 794.
RSA Keon. Go to Import RSA Keon certificate on page 796.
The following are the steps for generating and associating with a community either a single self-
signed certificate for both encrypting and signing documents or two self-signed certificates (dual
key), one for encrypting and one for signing.
512 Normal encryption.
1024 Strong encryption.
2048 Very strong encryption (Default).
3072 Very strong encryption.
4096 Very strong encryption.
4. For the validity period, either accept the default value of two years, or type the length of time
you want the certificate to be valid in the validity period field. Select days, months or years from
the drop-down list.
5. Select one or more options to specify how the key will be used for this community. By default,
all options are selected. You must select at least one of the following:
l Signing (digitalSignature)
l Non-repudiation (nonRepudiation)
l Encryption (keyEncipherment)
6. Click Next to review your certificate request.
7. On this page you can review your selections for:
l Key type (single key pair or dual key pair)
l Key length
l Key validity period
l Key usage
Review the information on the page. If you want to make any changes. click Back.
8. Click Next to display the certificate details page.
9. Optionally type a name for the certificate in the Name field. This name can help you identify
the certificate in the display lists of the user interface. By default the system uses the community
name as the certificate name.
On this page you can select an option for making the certificate the default certificate. The
options that are displayed vary depending on the usage that you selected for the certificate:
l Make this the default signing certificate – Appears only if the certificate is used for
digitalSignature or nonRepudiation, or both. If this option is displayed, it is selected by
default.
l Make this the default encryption certificate – Appears only if the certificate is used
for keyEncipherment. If this option is displayed, it is selected by default.
l Make this the default certificate for SSL client authentication – Appears only if
the certificate is used for digitalSignature or nonRepudiation, or both. The community
presents this certificate to a partner who requests client authentication to connect to a SSL
server. See SSL authentication on page 775. If this option is displayed, it is not selected by
default.
10. If there is a checkbox for Send certificate exchange messages to partners, see Replace
certificates automatically on page 811 for information about CEM and SCX certificate
exchanges.
11. Click Finish to generate the certificate. After the certificate is generated, the certificates page
reappears and displays the new certificate.
The following are the steps for importing a new Entrust certificate into Interchange. Before you can
use this procedure, you must consult with your organization's Entrust administrator about the
information required to connect with the Entrust/PKI server and import a new or updated certificate
for your community.
Interchange fulfills a client role in supporting the certificate management tasks of an Entrust server.
The prerequisites for this client-server relationship are your Entrust server and a person who is
designated as your organization's Entrust administrator. Lacking these two requirements, your
organization cannot use Entrust certificates in exchanging documents with your trading partners
through Interchange.
Interchange enables an organization with an Entrust/PKI server to create Entrust X.509 certificates.
The following describes the certificate-generation process involving Interchange and the Entrust
server.
After Interchange creates the key pair for signing documents, the application hands the public key
to the Entrust server. The Entrust server creates the signing certificate and passes the certificate to
Interchange. The public key is within the certificate. Interchange retains the private signing key. The
private signing key is not disclosed to the Entrust server; the private key remains secure within
Interchange. This guarantees security integrity.
Meanwhile, the Entrust server creates the encryption key pair and creates an encryption certificate,
which includes the public key. The Entrust server passes to Interchange the encryption key pair and
the encryption certificate.
If you need to distribute your certificate to your trading partners who use other interoperable
software, see Export a certificate to a file on page 799.
Before you attempt to exchange encrypted and signed documents, you should contact each
partner with whom you exchanged certificates and confirm that the fingerprints in both your
certificates are identical. For more information see MD5 and SHA1 fingerprints.
The following are the steps for importing an RSA Keon certificate into Interchange and associating it
with a community. Before you can use this procedure, you must consult with your organization’s
RSA Keon certificate authority administrator about the information required to connect with the
Certificate Management Protocol (CMP) server and import a certificate for your community.
The CMP server must be running for Interchange to acquire a certificate. Further, the RSA Keon
Certificate Authority system must be configured for automatic vetting of CMP requests. For details
see the certificate enrollment protocols chapter in the RSA Keon Certificate Authority user
documentation.
In this process Interchange generates the private-public key pair. The RSA Keon Certificate Authority
system creates the certificate and certifies your organization as the owner of the public key.
If you need to distribute your certificate to your trading partners who use other interoperable
software, see Export a certificate to a file on page 799.
Before you attempt to exchange encrypted and signed documents, you should contact each
partner with whom you exchanged certificates and confirm that the fingerprints in both your
certificates are identical. For more information see MD5 and SHA1 fingerprints.
The following are the steps for importing a third-party CA certificate into Interchange and
associating it with a community. Such a certificate file contains both the public and private keys.
Before you can use this procedure, you must perform the following tasks:
l Obtain a certificate from a certificate authority such as VeriSign.
l Export the certificate from a browser or mail client to a file. Assign a password when exporting
the file; you need this same password upon importing the file.
l Export both the public and private keys with the certificate. A certificate file with both keys is a
P12 or PFX file.
l If you export the certificate from Microsoft Outlook or Internet Explorer, select the check box for
“include all certificates in the certification path if possible.” You want the exported file to include
the entire chain of trust.
If Interchange cannot import a P12 certificate file, import the file in Internet Explorer, making sure
to mark the private key as exportable when you do so. When you have imported the certificate, view
the certification path to verify that the entire path is present. Export the certificate with the private
key and include all certificates in the certification path. Then try again to import the P12 file in
Interchange.
Certificate default options:
l To make the certificate your default signing certificate, click Make this the default
signing certificate. This option is selected by default.
l To make the certificate your default encryption certificate, click Make this the default
encryption certificate. This option is selected by default. See SSL authentication on
page 775.
7. If there is a checkbox for Send certificate exchange messages to partners, see Replace
certificates automatically on page 811 for information about CEM and SCX certificate
exchanges.
If there is a checkbox for Send certificate exchange messages to partners, see the online
help for topics about replacing certificates automatically with CEM and SCX.
8. Review the certificate information on the page. Click Finish to import the certificate.
After the certificate is imported, the certificates page reappears, displaying the new certificate.
9. If you are setting up a community for the first time, you must distribute your certificate
information by sending it to partners by e-mail or some secure means. This can be done by
exporting your certificate as part of your community. See Back up a community as a partner on
page 855.
If you need to distribute your certificate to your trading partners who use other interoperable
software, see Export a certificate to a file on page 799.
Before you attempt to exchange encrypted and signed documents, you should contact each
partner with whom you exchanged certificates and confirm that the fingerprints in both your
certificates are identical. For more information see MD5 and SHA1 fingerprints.
If a trading partner also uses Axway software, the partner’s certificate and public key normally is
inside the imported partner profile. You need to import a partner’s certificate file when:
l A partner uses other interoperable software and you must import the partner’s certificate file after
creating the partner’s profile.
or
l A partner sends you an updated certificate file to replace one that is associated with the partner’s
profile on your system.
If your partner uses other interoperable software and wants to send you a self-signed certificate,
advise the partner to export the certificate to a PKCS#7 file (.p7c) and include all certificates in the
certification path, if possible.
1. Make sure you have access on your system to the certificate file your partner sent you.
2. In the partners area of the user interface, go to the summary page for the partner you want.
3. Click Certificates on the navigation graphic at the top of the partner summary page to open
the partner’s certificates page.
4. Click Add a certificate to start the certificate wizard.
5. Click Next to display the file selection page.
6. Click Browse to open the Browse dialog box.
7. Select the certificate file you want to import and click Open to redisplay the certificate wizard.
8. Click Next to display the view certificate details page.
9. If you want, type a name for the certificate in the Name field. This name can help you tell one
certificate from another.
To make the certificate the default encryption certificate, select Make this the default
encryption certificate. This option is selected by default.
To make the certificate the default SSL authentication certificate, select Trust this for SSL
server and/or client authentication. This means the partner presents this certificate when
the community requests client authentication to connect to a SSL server.
10. Click Finish. The partner certificates page is redisplayed with the certificate you imported.
11. Before you attempt to exchange encrypted and signed documents, contact the partner and
confirm that the fingerprints in the certificate you imported are identical to the partner’s. For
more information see MD5 and SHA1 fingerprints.
After exporting a community certificate, you can send the file to your partners by e-mail or other
means.
For your partner, export a community certificate that contains your public key. Never give your
partner a community certificate that contains your private key.
For yourself for backup purposes, you can export a community certificate that contains your private
and public keys. If you do, keep this certificate in a secure place and never give it to anyone.
You might want to export a partner certificate and public key to a file to keep as a backup. If the
partner certificate is deleted from the system, you can import the certificate again if needed.
1. In the community or partner area of the user interface, go to the summary page for the
community or partner you want.
2. Click Certificates on the navigation graphic at the top of the community or partner summary
page to open the certificates page.
3. Click the name of the certificate to export to open the certificate information page.
The control to disable exporting of all private keys is in the crossworks.properties file. The file
is at <install directory>\conf. The property is:
privateKey.export.enable
The default value of the property is true. This means users associated with roles that permit
exporting private keys can do so. Even with the property enabled, however, users can be associated
with roles that block exporting private keys.
When the value is set to false, all users are prohibited from exporting private keys. This includes
users, such as administrators, who are associated with roles that allow exporting private keys. When
false, all user interface related to exporting private keys no longer displays.
Changes to the crossworks.properties file take effect upon saving the file. Interchange does not
have to be restarted.
If the privateKey.export.enable property is deleted from the crossworks.properties file,
Interchange behaves as though the value is true. This ensures backward compatibility with earlier
versions of Interchange that do not have the property in the crossworks.properties file.
This property provides an additional safeguard against private keys becoming compromised. The
property does not affect exporting of public keys.
Delete certificate
Use this procedure to delete certificates that you or your partners no longer use for verifying
signatures, encrypting messages or SSL authentication.
Once you delete a certificate, you cannot retrieve it. If you find that you need a deleted certificate,
you must import it from a file.
1. On the certificates page, click the name of the certificate you want to delete to open its details
page.
2. Click Delete this certificate. A dialog box appears with a message asking whether you want
to delete the certificate.
3. Click OK to delete the certificate or Cancel to abort the operation.
A certificate revocation list (CRL) is a list of third-party certificates that are no longer valid. Certificate
authorities maintain such lists of certificates they issued but later invalidated for one reason or
another. CRLs are accessible on the Internet, and you need an Internet connection to use them.
The Interchange always attempts to do CRL checking for each traded message. Whether it succeeds
in the attempt, and whether it fails a message with a revoked certificate, depends on whether a CRL
is available to check a certificate against. CRL checking is only attempted for CA-issued certificates,
never for self-signed certificates.
A certificate is checked if a CRL can be obtained from a CA. If there is a CRL for a given certificate,
that CRL is issued and signed by the same issuer as the certificate. The CRL may have been
downloaded from a distribution point that matches one specified in a CRL distribution point
extension in the certificate. Most CRLs have a thisUpdate time indicating when the CRL was last
updated by its issuer. Most also have a nextUpdate time indicating when the issuer next updates
the CRL. A CRL may be updated before its nextUpdate time.
As an example of CRL checking, when a partner sends you an encrypted document, Interchange
checks the certificate associated with the inbound document against the appropriate CRL. If the
certificate is on the CRL, Interchange fails the inbound document.
Interchange checks a specific certificate only against the appropriate CRL. For example, Interchange
does not check a certificate issued by VeriSign against a CRL issued by GlobalSign.
Although using CRLs can enhance security, the checking process can result in longer processing
times. Consequently, your decision whether to use CRLs should weigh the security advantage
against the performance handicap.
Interchange usually checks a certificate against a previously downloaded CRL. But this can be
extended to on-the-fly CRL downloading and checking by selecting the check box for
Automatically retrieve CRLs on the CRL usage and retrieval configuration page (see Advanced
CRL settings on page 805). With this enabled, Interchange looks for a CRL distribution point URL in
the certificate being checked and downloads the updated CRL if available. It then checks the
certificate against the newly downloaded CRL. If an updated CRL is not available, Interchange
checks the certificate against the previously downloaded CRL. Because of this on-the-fly
downloading and checking capability, there can be multiple CRLs from the same issuer.
You are responsible for obtaining from the certificate authority the information required for
accessing the CRL. Interchange downloads the latest CRL before performing certificate checks. It
also can download updates of the CRL, based on the update interval in the previously downloaded
CRL.
1. The system retrieves the CRL distribution point, if any, from the current certificate. The CRL
distribution point is the first URL found in a CRL distribution points extension in the certificate.
Not all certificates have a CRL distribution point extension and not all such extensions have a
URL.
2. The system looks in its cache of CRLs for an effective CRL with the same issuer and CRL
distribution point (if any) as the current certificate. A CRL is considered to be effective if the
current time is between the CRL's thisUpdate and nextUpdate times. If such a CRL is found, it is
used: Go to step 9.
3. If the option for Automatically retrieve CRLs is selected on the CRL usage and retrieval
configuration page and the certificate contains a CRL distribution point, the system attempts to
retrieve a CRL from that distribution point. If a CRL is successfully retrieved, it is added to the
CRL cache. The system again looks in its cache of CRLs for an effective CRL with the same issuer
and CRL distribution point as the current certificate. If such a CRL is found, it is used. Go to step
9.
4. If the option for Use expired CRLs is selected on the CRL usage and retrieval configuration
page, the system looks in its cache of CRLs for the most recently expired CRL with the same
issuer and CRL distribution point (if any) as the current certificate. A CRL is considered to be
expired if its nextUpdate time is in the past. If such a CRL is found, it is used. Go to step 9.
5. If the current certificate does not contain a CRL distribution point, there is no CRL to check. Go
to step 8.
6. The system looks in its cache of CRLs for an effective CRL with the same issuer as the current
certificate. If such a CRL is found, it is used. Go to step 9.
7. If the option for Use expired CRLs is selected on the CRL usage and retrieval configuration
page, the system looks in its cache of CRLs for the most recently expired CRL with the same
issuer as the current certificate. If such a CRL is found, it is used. Go to step 9. Note that this
step is similar to step 4, with the exception that here the CRL distribution point is not checked.
8. No CRL could be found for checking the current certificate. If the option for Require CRLs is
selected on the CRL usage and retrieval configuration page, the certificate path validation fails.
Otherwise, the CRL check for the current certificate succeeds.
9. The signature of the found CRL is verified using the CRL's issuing certificate. If the verification
fails, the certificate path validation fails.
10. The list of certificates in the CRL is checked whether it contains the current certificate. If the
certificate is listed in the CRL, the certificate path validation fails. Otherwise, the CRL check for
the current certificate succeeds.
CRLs are usually made available via one of three protocols: HTTP, HTTP/S, and Lightweight
Directory Access Protocol (LDAP). For example, VeriSign CRLs are accessed via HTTP and Entrust
CRLs are accessed via LDAP.
You can obtain the CRL information by viewing the details of a CA-issued certificate. See Details tab
on page 791. The information, if present, is labeled as a CRL distribution point.
The following URL is an example of the CRL distribution point specified in a VeriSign certificate:
http://crl.verisign.com/class1.crl
You would enter this URL to add a VeriSign CRL to Interchange.
Add a CRL
Use this procedure to download a CRL.
3. Type the URL to download the CRL. See Obtain CRL access information on page 804.
If you must connect through a proxy server to retrieve a CRL, see the proxy server fields
described in Advanced CRL settings on page 805.
4. Click Next to display the get CRL updates page.
5. Select the interval for downloading an updated CRL.
6. Click Next to display the download the CRL page.
7. Select whether you want to download the CRL now or later.
8. Click Finish. If you elected to download the CRL now, the CRL is listed on the CRL list page
with a status of Success.
CRL files are stored in subdirectories of common\conf\crls. Once a subdirectory reaches the
maximum CRL file limit, the server creates another subdirectory and begins storing additional
CRLs in the new folder. This is intended as an aide to users who may have thousands of CRL
files. By default, the maximum limit for each subdirectory is 500 files.
On this page you can click the URL of a CRL and open another page that lets you change the URL for
downloading the CRL or the updating interval. You also can view details of the CRL.
In most cases the default settings on this page are adequate. You may want to change settings for
special requirements. When the default values are used and no current CRLs are in <install
directory>\common\conf\crls, CRL checking does not occur.
Select this to mandate CRL checking for all non-root (not self-signed) certificates and to
fail certificate path validation when Interchange cannot find a certificate's CRL. In most
cases, Require CRLs is turned off by default. However, if you are licensed to perform CSOS
processing, Require CRLs is on by default because CRL checking is presumed for CSOS.
When Require CRLs is turned off and a CRL cannot be found for a certificate, the certificate
is presumed valid and certificate path validation continues.
When Require CRLs is turned on, Interchange must find a CRL for each non-root certificate.
If a CRL is not found, the certificate is considered revoked and the certificate path
validation fails.
When selected, make sure update schedules are set on the manage CRL page for all CRLs
needed to check non-root and intermediary certificates in the certificate path.
Select this option to enable the use of an expired CRL when Interchange cannot find a
current CRL in <install directory>\common\conf\crls. Interchange looks for a
current CRL with the same issuer name as the certificate being checked. In a current CRL,
the current time stamp is between the CRL's thisUpdate and nextUpdate time stamps. If
Interchange cannot find such a CRL, it looks for a CRL with the same issuer name as the
certificate and with a nextUpdate time stamp that is before the current time stamp. If more
than one such expired CRL is found, the most recently expired CRL is used to check
whether the certificate has been revoked. Clear the check box to use only CRLs that have
not expired. Use expired CRLs s turned off by default.
Select this option to automatically retrieve CRLs using the information in certificates' CRL
distribution points extension. When this option is selected and Interchange does not
already have an effective CRL for a certificate, it attempts to use the certificate's CRL
distribution point extension to retrieve the CRL for that certificate.
If Interchange fails to retrieve a CRL and the Require CRLs option is selected,
Interchange will fail to validate the certificate. In most cases, Automatically retrieve
CRLs is turned off by default. However, if you are licensed to perform CSOS processing,
Automatically retrieve CRLs is on by default because CRL checking is presumed for CSOS.
l None – Retrieval through a proxy is turned off.
l Local – Retrieval is through the proxy configured on this page.
o Host – The name or IP address of the proxy server to use when retrieving CRLs via
HTTP or HTTPS.
o Port – The port number of the proxy server to use when retrieving CRLs via HTTP or
HTTPS.
o This proxy requires a user name and password – Select this option if a user
name and password are required to connect to the proxy server. Type the
authentication information in the user name and password fields.
l DMZ – Retrieval is through a Secure Relay DMZ node. This option displays only if your
user license supports Secure Relay. If you select DMZ, no other action is required
unless you have set up one or more DMZ zones. If so, you can select a zone for the
retrieval or no zone. If you use Secure Relay, use of the DMZ retrieval option requires
enabling Use outbound connection proxy on the Configure outbound connection
proxy page (see Configure outbound connection proxy on page 488). However, even
with that enabled you can still use the Local option.
You can elect not to trust a root certificate by clicking Untrust to the right of the root certificate
name. If you do untrust, the system no longer recognizes the end-entity partner certificate as
valid. This could affect many end-entity partner certificates. You cannot restore trust on this tab.
To trust the roots again, import the partner end-entity certificate or the root certificate. The
easier method is importing the end-entity certificate, as the system trusts the root by default.
A single CA might be listed multiple times on the tab, because each has multiple roots, each with
unique fingerprints under which it issues certificates. To view the fingerprints, select a root and
review the MD5 and SHA1 fingerprints on the details tab. By comparing fingerprints you can
choose to trust some but not all of a CA’s certificates.
To import a trusted root, click Add a trusted root certificate and see Import certificates for
partners on page 798.
l Trusted SSL root certificates tab – The trusted SSL root certificates tab displays the trusted
roots of partners’ certificates that, when presented by partners, enable the partners to connect to
the community’s SSL servers that require client authentication. For an explanation of trusted
roots and the consequences of untrusting, see Trusted roots certificates tab. See SSL
authentication on page 775.
To import a trusted root, click Add a trusted root certificate for SSL servers on the
certificates page and see Import certificates for partners on page 798.
CRL caching
As CRLs are used, they are cached in memory. The CRL cache is implemented as a bounded most
recently used (MRU) cache. The cache grows to a maximum number of entries, after which the least
recently used entry is removed to make room for the addition of a new entry. Every time an entry is
added or used, it is moved to the top of the list of most recently used entries.
The default maximum size for the CRL cache is 150 entries.
Every node in Interchange maintains its own CRL cache according to what CRLs are used by that
node.
Note Users must have the Access APIs permission to run crlPurgeHttpsClient. See Manage roles
on page 116.
crlPurgeHttpsClient is located in the Tools directory: <install directory>\tools. Run the
script from the command line.
The connection to Interchange is made either over HTTP or HTTPS protocol, depending on the
parameters entered. There are five required parameters:
l Protocol: HTTP or HTTPS
l Host: IP address or host name
l Port number
l User name
l User password
When the process has been successfully started, a confirmation message will appear on the
command line. This is the only feedback given. To monitor the removal progress, check the control
node log for references to CrlRemover. This log shows when the process completes and how many
records in the CRLs table have been removed, as well as how many files have been removed from the
file system. The event log shows when the removal has started (CrlPurgeInitiated) and finished
(CrlPurgeCompleted).
Example:
response code:200
purge response code=204 and message: No Content
purge task successfully started, start time: Mon Jan 26 14:35:11 MST
2015
See event logs for purge complete event.
Possible error messages include:
The script was called without any parameters, or with one or more parameters missing.
l response code: 401 authToken=null
The script was called with an invalid login.
l response code: 200
The script was called by a user without the Access APIs permission.
This tool is for scanning files of public-key certificates. Those are files with extensions of .cer,
.crt, .der, .p7b and .p7c. It cannot scan certificates with private keys, meaning files with
extensions of .p12 and .pfx.
One use for this tool is to scan certificates from partners before importing the certificate files to
Interchange. This may be advisable if you have a partner who has provided unreliable certificates
that adversely affected message trading.
The tool can scan a single certificate file or a directory of certificate files.
Run the tool from the tools directory. The format is:
where file is the path to a single certificate file and directory is the path to a directory
containing multiple certificate files.
Each certificate file is presumed to contain one or more certificates. When a file contains more than
one certificate, it is assumed the multiple certificates form a chain from end-entity certificate to CA
root certificate.
When a directory is specified, the tool finds all certificate files in that directory and all subdirectories,
recursively.
The tool displays the following data:
l Info – An interesting characteristic of the certificate that does not violate any standards and
does not affect the certificate's performance in Interchange.
l Warning – An anomaly in the certificate that violates RFC 3280, but does not affect the
certificate's performance in Interchange.
l Error – A serious problem with the certificate that may violate RFC 3280, but would cause the
certificate not to function properly in Interchange.
RFC 3280 is the standard for X.509 certificates of the Internet Engineering Task Force. A copy of
RFC 3280 is at: http://www.ietf.org/rfc/rfc3280.txt.
You can run certStats with or without parameters. The tool can be invoked as:
Where:
l -file <file> instructs the tool to dump its results to the specified file as well as to standard
output.
l -export <dir> instructs the tool to export all certificates to the specified directory. Within the
directory are created the subdirectories ca/root, ca/intermediate, user/endentity and
user/selfsigned. Certificates are exported appropriately to the subdirectories.
l -clean instructs the tool to clean the specified export directory and all subdirectories before
exporting any certificates.
l -cross instructs the tool to check for cross certificates.
The tool inspects all certificates in the database and collects statistics. The tool does its best to
differentiate between CA certificates and user certificates. However, it sometimes classifies a CA
certificate as a user certificate.
The tool further differentiates between CA root, CA intermediate, user self-signed and user end-
entity certificates. For each of these four classes of certificates, the tool gathers statistics including
how many certificates contain subject key identifier information and how many certificates contain
authority key identifier information. The tool also finds each certificate's issuing certificate. Note
that CA root and user end-entity certificates are their own issuer, so a problem finding the issuer
indicates a problem with the certificate itself, such as a corrupted certificate.
If the -export <dir> option is supplied, each certificate is exported to the appropriate
subdirectory of the indicated directory. Each certificate file is named based upon the certificate's
subject name. If the certificate's subject name does not contain the information required to
construct a file name, then cert is used as the file name. If a file with the determined name already
exists, a sequence number is added to the name to avoid the conflict. All certificate file names are
suffixed with the .cer extension.
After all statistics are collected, the results are dumped to standard output and to the designated file
if the -file <file> extension is supplied.
If the -cross extension is supplied, the tool looks for cross certificates. Cross certificates are two
intermediate certificates that are used to sign each other. For each pair of cross certificates found,
the tool also finds all related certificates that are issued by or an issuer of each cross certificate. After
all sets of cross certificates are found they are dumped to standard output and to the designated file
if the -file <file> option is supplied.
Concepts
l Automatic replacements on page 812
l Types of CEM messages on page 814
l SCX details on page 816
Procedure
l Send a CEM or SCX request on page 818
Automatic replacements
Interchange can send end-entity certificates to a community’s partners to replace certificates.
Interchange can send partners a replacement once a community has generated or imported a new
self-signed certificate or imported a new CA certificate. Partners can signal acceptance or rejection
of the new certificate. Administrators can make the process fully or semi-automatic.
Interchange supports two standards:
The primary purpose of CEM and SCX is to replace certificates with new ones. CEM is not intended as
a way to distribute certificates to partners the first time. SCX in theory can be used to send
certificates to partners the first time, but that is not supported in Interchange.
The user interface uniformly handles CEM and SCX through:
l Sending certificate exchange messages
l Managing sent certificate exchange trust requests
l Managing received certificate exchange requests
If the community chooses not to send any CEM or SCX certificate exchange messages, the certificate
is installed normally. However, if the community chooses to send any certificate exchange
messages, the UI stops short of installing the new certificate and just adds it to the certificate store
and the proper key store.
When selecting the partners to receive certificate exchange messages, the community sets a date
and time for partners to respond, else the new certificate is installed automatically. CEM defines this
“respond by date.” SCX, however, does not support this, so the date is not included in any SCX
messages. But the respond by date is still used to trigger the automatic installation of the new
certificate if not all partners have responded by that date and time. Once every partner has
responded to accept, the certificate is installed automatically, and any previously scheduled
installation is cancelled.
Encryption
When a community sends a request for a new encryption certificate, the community must be
prepared immediately to receive messages from partners encrypted with the new certificate and the
old certificate the new certificate is intended to replace. Interchange handles this without user
intervention. Upon receiving an encrypted message, Interchange determines the public key used to
encrypt and uses the proper private key from its key store to decrypt.
When a community sends a request for a new signing or SSL certificate, the community does not
implement the certificate unless one of the following conditions is met:
l The respond-by date in the request has passed and no partners have sent a response rejecting
the certificate. This means absent any responses — positive or negative — by the respond-by
date, the community implements the certificate when the respond-by date has passed.
l On or before the respond-by date, all partners have returned responses accepting the certificate.
If all partners respond positively before the respond-by date, the community implements the
certificate when the final positive respond has been received.
If only one partner sends a response rejecting the certificate, the community does not implement
the certificate.
Moreover, upon accepting a new signing certificate, a partner must be able to accept messages from
the community signed by either the new certificate or the old certificate the new certificate is
intended to replace.
External resources
CEM is a draft standard of the Internet Engineering Task Force (IETF). The IETF draft is available at
the following URL:
http://tools.ietf.org/html/draft-meadors-certificate-exchange-14
SCX is a recommendation of Odette and is documented in the “OFTP2 Implementation Guidelines”
available on the Odette forum at:
http://forum.odette.org/OFTP/oftp2
CEM messages always concern replacement end-entity certificates. The CEM standard presumes
partners already have exchanged public-key certificates, either to begin or continue a trading
relationship.
Before sending a CEM request, a community obtains a replacement certificate and public-private key
pair. In the certificate wizard, the community can generate a self-signed certificate or import a CA
certificate.
The following describes how Interchange handles request and response messages.
CEM request
A CEM request is an XML message sent by a community to one or more partners. The message asks
partners to begin using the included public-key certificate in the trading relationship.
The message includes a respond-by date. Partners are asked to tell the community by that date
whether the new certificate has been accepted.
The message also states the use for the new certificate (for example, signing, encryption, SSL). The
following figure illustrates a CEM request.
CEM response
A CEM response, illustrated in the following figure, is an XML message sent by one or more partners.
The message tells the community whether the partner has accepted the certificate in the CEM
request.
If all partners accept the certificate before or on the respond-by date, the community installs the
certificate. If even a single partner rejects the certificate, the community does not implement the
certificate. The following figure illustrates a CEM response.
SCX details
The following topics provide details about how SCX is implemented in Interchange.
Usage rules
Interchange applies rules to determine the intended usage of certificates received in SCX messages.
First, a default set of usages is determined in the following order:
1. If the received certificate contains an extended key usage extension, and the extension contains
the server or client authentication key purpose, it is assumed the certificate can be used for TLS
server authentication or TLS client authentication or both. No further checking is performed.
2. If the received certificate does not contain a key usage extension, it is assumed the certificate
can be used for signing and encrypting normal OFTP messages. No further checking is
performed.
3. If the received certificate's key usage extension has the digital signature or key encipherment
bits set, it is assumed the certificate can be used for signing or encrypting normal OFTP
messages.
Matching certificates
Once a received certificate's default usages are determined, Interchange looks for matching
certificates already in use in the trading relationship between the partner and community that sent
and received the new certificate. If no matching certificate is found, it is assumed the certificate is
intended to be used for the default purposes as just determined.
If matching certificates are found, they are arranged in order from newest to oldest. Additionally, for
each matching certificate the following checks are made to possibly limit the default usage of the
new certificate:
1. If the matching certificate is not the default encryption certificate for the partner that sent the
new certificate, encryption is removed from the potential certificate usages.
2. If the recipient community of the new certificate does not already trust the matching certificate
for normal trading, signing and encryption are removed from the potential certificate usages.
3. If the recipient community of the new certificate does not trust the matching certificate for SSL
or TLS server or client authentication, TLS server and client authentication are removed from
the potential certificate usages.
If applying these rules for a matching certificate does not eliminate all potential usages of the new
certificate, the matching object is deemed to be the matching certificate, and the limited certificate
usages are used as the intended certificate usages.
If after going through all the matching certificates no potential certificate usages are found, the
originally determined default certificate usages are used, and it is assumed there is no matching
certificate.
It is likely a community sends either a CEM or SCX request. However, if a community trades with
some partners via EDIINT and some via OFTP2, the community could send CEM and SCX requests at
the same time. If so, only one respond-by date could be selected for both request types.
1. In the user interface, launch the certificate wizard within a community to generate a self-signed
certificate or import a CA certificate. See Add a certificate on page 792.
2. On the View certificate details page in the certificate wizard, select the use for the certificate
(signing, encryption, SSL).
3. Select Send certificate exchange messages to partners.
4. If a the request is a CEM request, select the Respond by date and the partners to send the
request. See the View certificate details page for CEM requests below. Go to step 6.
The SCX message types are:
o Request – A request message contains one certificate that may match an existing
certificate associated with the sender. The recipient can accept or reject the certificate,
but either way must respond with one or more deliver messages containing its current
certificates. This message can be used for an initial certificate exchange. Interchange
can send up to four deliver messages in response to a received request message,
containing the recipient community’s current default signing certificate, default
encryption certificate, default client authentication certificate and certificate for the first
enabled TLS OFTP2 server. Only one deliver message is sent for any certificates that are
duplicates of others.
o Deliver – A deliver message contains one certificate that should match an existing
certificate associated with the sender. The recipient should start using the new
certificate some time before the current matching certificate expires. The recipient can
accept or reject the certificate.
o Replace – A replace message contains one certificate that should match an existing
certificate associated with the sender. The recipient should start using the new
certificate immediately and the current matching certificate should be removed from
service immediately. When Interchange receives a replace message the matching
certificate is removed from service by disassociating it from the partner that sent the
replace message. The matching certificate is not untrusted. The reason for this is that
OFTP users most likely use CA-issued certificates, and when Interchange trusts a CA-
issued certificate, it frequently trusts the root CA certificate. It could be dangerous to
untrust a root CA certificate, as this may affect other trading relationships.
6. To generate the request, click Finish to complete the process of generating or importing the
certificate. This action also sends the request to the selected partners.
7. Open the Sent certificate exchange trust requests page to view the status of CEM and SCX
requests. See Sent certificate exchange trust requests page on page 823.
Page Description
Received This page provides information about the CEM and SCX requests your
certificate community has received from partners. This includes the date the message
exchange was received, the name of the partner who sent the message and the number
requests page of public-key certificates in the message.
on page 821 To open the page, select Trading configuration on the top toolbar. On the
Communities page, click Manage received certificate exchange
requests in the task list at the bottom of the page.
Sent certificate This page provides information about the CEM and SCX requests your
exchange trust community has sent to partners. This includes the sent and respond-by dates,
requests page the number of partners to whom the request was sent and the number of
on page 823 public-key certificates in the message.
To open the page, select Trading configuration on the top toolbar. On the
Communities page, click Manage sent certificate exchange trust
requests in the task list at the bottom of the page.
More details about these pages are provided in the following topics.
CEM requests
The following are the options for CEM requests.
SCX requests
The following are the options for SCX requests.
Internal checks
Whether you choose the automatic or manual option, Interchange performs the following internal
checks before accepting a certificate:
After a request has been accepted or rejected, a Delete button appears on the Received requests
page. This lets you clear the page of old request records.
On the Received certificates exchange requests page click Request details to open a details page.
The details pages are tailored for CEM and SCX requests(shown in the following two illustrations).
The name of the certificate is displayed in the Name column. Click the name to open a View
certificate page, which contains details about the public-key certificate (see Certificate field
descriptions on page 790).
If you selected the manual option on the Received certificate exchange requests page on page 821,
determine whether to accept the certificate and click Accept or Reject to send a response to the
partner who sent the request. The Response column updates with a message reflecting whether you
accepted or rejected the certificate.
If you reject a certificate, you can type a reason. The reason displays on the details page and is
included in the response to the partner who sent the request.
After accepting or rejecting the request, you can click the link in the Response column to open a
details page in Message Tracker on page 826 for the response message you sent to the partner who
sent the request.
After the respond-by date for a request has passed or has been canceled, a Delete button displays.
You can click it to delete the record from the page. This only clears the display of the specific
request; deleting does not affect the certificate.
A respond-by date is canceled either when all partners who received the request have rejected the
certificate or when the request is canceled on the Sent certificate exchange trust request details
page.
Click a link in the Recipients column to open the Sent certificate exchange trust request details page
(see the following figure).
Click the certificate name to open a View certificate page, which contains details about the
public-key certificate (see Certificate field descriptions on page 790).
On the details page you can also select the following:
Message Tracker uses database records and files stored in the backup directory. To get full use of
Message Tracker, you must enable document backups. Backing up is the default behavior when
pickups and deliveries are set up. See Message backup configuration on page 849.
In addition to the custom searches you create in the Search panel, you can also use the default
searches that are listed in the Message tracker menu on the top toolbar. These searches are set up
to find all messages traded within past hours or days and also to find failed messages or negative
responses to messages within a certain number of days. You can adjust the default searches on the
Message Tracker global settings page (see Manage default search settings on page 843).
The following figure shows a partial view of the main Message Tracker page as it may appear when
first opened.
Custom search
The following describes the controls and fields on the custom search panel on the left side of the
main Message Tracker page.
l Search name – If you leave the field blank and click Find, messages matching conditions set
in the trading information and date areas on the custom search panel are searched for. Once
search results are displayed, you can type a name for the search and click Save. Later you can
run the same search again by selecting Message tracker > [name of saved search] under
My searches on the menu.
l New – New is a clear action. Use this button to clear the page of search results and begin a
search from scratch.
l Save – Save lets you save the conditions for a search you have performed. This button lets you
perform the search again without having to set up the conditions again. To save a search, set
conditions for a search and click Find to run the search. When the search results are displayed,
type a name for the query in the search name field at the top left of the main transaction search
page and click Save. To perform a saved search, select Message tracker > [name of saved
search] under My searches on the menu.
l Remove – Remove deletes the search identified in the search name field from the My
searches menu list.
l Find – Find searches for all records matching the conditions specified on the search page, if
any have been specified. If no conditions are specified, the default action is to search for all
messages traded within the number of days specified in the Number of days for default searches
field on the Message Tracker global settings page (see Manage default search settings on page
843).
l Messages per page – The value of this field is the maximum number of search results to
display per search results page. If the number of found messages exceeds the page limit, the
results are displayed across multiple pages. You can set this maximum on a search-by-search
basis.
l Maximum # of search results – The value of this field is the maximum number of messages
that return after a search is executed. If a search finds more than this number, the results are
trimmed to return only the number up to the maximum. You can set this value on a search-by-
search basis, but only to the maximum allowed by a field on the Message Tracker global settings
page. Administrators also can change the default value of this field on the global settings page.
For more information see Manage default search settings on page 843.
Trading information
The following describes the fields under the trading information heading. Use of these fields is
optional.
l From – The message sender. You can type a community or partner name or routing ID. Or, click
the ellipsis button to select a party. Also, wildcard characters can be used in this field (see Search
with wildcard characters on page 833).
l To – The message receiver. You can type a community or partner name or routing ID. Or, click
the ellipsis button to select a party. Also, wildcard characters can be used in this field (see Search
with wildcard characters on page 833).
Note: If you click the ellipsis button to select a partner and have more than 25 partners, a search
criteria panel displays to aid in finding the partner you want. The panel enables searching for a
partner by name, routing ID and partner category. If your license supports WebTrader, you can
limit the search to WebTrader partners only.
l Original filename – The original name of the message file received from a partner or picked up
from integration. Using this in conjunction with date or time conditions may result in more
useful search results. Wildcard characters can be used in this field (see Search with wildcard
characters on page 833).
l Delivery filename – The name of the message file sent to a partner or delivered to integration.
Using this in conjunction with date or time conditions may result in more useful search results.
Wildcard characters can be used in this field (see Search with wildcard characters on page 833).
l Document ID – The control ID of an EDI document. Wildcard characters can be used in this
field (see Search with wildcard characters on page 833).
l Status – The status of the messages to search for: any, delivered, failed, ignored, in process,
interrupted, negative response, receiving, resubmitted, resubmitted original, scheduled
production, sending, split and waiting for receipt.
Messages fail for various reasons. Commonly, messages fail because the sender or receiver could
not be identified. Interchange may have been unable to find a sender or receiver’s routing ID in a
parsed message. If a message fails because the sender or receiver could not be determined,
check the document for valid routing IDs. You also can search the TE log files in the logs
directory for document parsing errors. Look for error or warn events containing the words
“parse” or “parsing.”
If you search for any status, all states but ignored are included. The ignored status is applied
to messages Interchange has determined lack worthwhile content (for example, an extraneous
message received in addition to a message receipt).
If you search for negative response, Message Tracker returns payloads with negative responses
from partners. If you turn off Hide receipts, a search also returns negative response receipts.
If you search for messages with delivered status, negative responses also are returned. This is
because a negative response is a delivered state.
Interchange marks as delivered any outbound message for which an acknowledgment was
received, whether positive or negative. An outbound message also is marked as delivered when
no acknowledgment is requested. An outbound message in a delivered state has an indicator,
viewable in the message details, showing the acknowledgment as positive or negative.
For a message sent via HTTP, Interchange marks a message as delivered when it receives an
HTTP 200 OK response. The response is 200 OK for an asynchronous connection and 200 OK
plus an acknowledgment for a synchronous connection. If the acknowledgment indicates the
receiver had an issue with routing IDs, both parties need to check routing IDs to make sure the
IDs match.
l Direction – The direction of the messages to search for:
o any – all messages are included in the search results regardless of origination and destination
o inbound – Partner to Community messages are returned in search results
o outbound – Community to Partner messages are returned in search results
o internal – Inbound (from Partner) messages picked up from the Application Pickup are
returned in search results
o external– Messages exchanged Partner to Partner are returned in the search results
o no directions selected – Messages with no routing ID are returned in the search results
l If you search for any direction, all messages are included in the search regardless of origination.
A search for inbound finds messages received from partners and routed to integration. A search
for outbound finds messages Interchange picked up from integration, packaged and sent to
partners. If you are a community sponsor with WebTrader partners, a search for internal may
find messages awaiting action by a WebTrader.
A search for external does not yield useful results.
l Consumption URL – Allows you to search for messages based on the transport used by a
community to pick up messages from integration or receive messages from partners. For
example, if a community uses file system integration, copy the pickup location (such as
C:\data\ediout) from the transport maintenance page and paste the path in the consumption
URL field in Message Tracker.
l DMZ zone – If you are licensed to use Secure Relay, have set up trading to route through a DMZ
node and use DMZ zones, you can enter a zone name as a search condition.
l Document type – This is EDI document types such as 850, 862. For ebXML, you can use
values such as MessageError, Ping, Pong, StatusRequest, StatusResponse, SOAP Fault. For
RosettaNet, values include Signal and Action. When you start typing in this field, autocomplete
values display, unless an administrator has disabled attribute collecting.
l Document class – Values include Tradacoms, X12, XML, Edifact, Binary. For other classes, you
can use the content MIME type without the application/ prefix (for example, use octet-stream
instead of application/octet-stream). When you start typing in this field, autocomplete values
display, unless an administrator has disabled attribute collecting.
l MIME type – The content MIME type of a document. For example:
MIME type Description
application/EDI-consent Tradacoms messages
application/EDIFACT EDIFACT messages
application/EDI-X12 X12 messages
application/octet-stream Binary messages
application/xml XML messages
When you start typing in this field, autocomplete values display, unless an administrator has
disabled attribute collecting.
l Attribute – A message attribute or metadata element. For examples of attributes, select
Message tracker > Select attributes for pop-up windows. When you start typing in this
field, autocomplete values display, unless an administrator has disabled attribute collecting. If
you add a searchable attribute, a search field is added under the trading information area. If you
add an unsearchable attribute, a field is not added, but a search results column is added as well
as a check box for the attribute under the Columns on page 832 area.
The following attributes are not searchable:
o Business protocol
o Business protocol version
o Consumption exchange point ID
o Consumption filename extension
o Delivery protocol
o Pickup protocol
o Receipt content
o Rejected reason
l Message ID – A unique identification Interchange generates and assigns to a message.
l Core ID – A unique identification Interchange generates and assigns to a message. Core IDs are
also displayed in log files.
l Conversation ID – Useful when searching for ebXML messages.
l Integration ID – If you have a back-end system or an inline process that supplies a specific
value to the available IntegrationId metadata element, you can include the integration ID in a
search. See Message metadata and attributes on page 412.
l Hide receipts – Show or hide message receipts in search results.
l Hide protocol messages – Show or hide protocol messages in search results.
l Hide subordinate messages – Show or hide subordinate messages in search results. A
subordinate message is one that was split from a parent document. A subordinate message also
can be described as a child message of a parent document. In ebXML trading if hide
subordinates is turned off, Message Tracker reports two payload messages: the original MMD
picked up from integration and the message split from the original MMD. If hide subordinates is
turned on, only the original MMD picked up from integration is reported.
l Hide pings – Show or hide peer network ping messages in search results. This option applies
only if you are licensed to use the peer network.
Date
To search by date, expand the Date area on the left side below the Trading information area. The
selection Don’t search by date means date conditions are not used in searches. To search by
date, select Origination or Delivered and select the date or time conditions.
The After and Before option lets you search for messages traded after or before the date and time
you specify. You can set the maximum days after or before the specified date and time on a search-
by-search basis. Administrators can change the default maximum days value on the Message Tracker
global settings page (see Manage default search settings on page 843).
Columns
Use the Columns section of the left Message Tracker panel to select the columns you want to
display when you view search results.
The customized views you create by selecting columns apply only to you and not to other users.
From the list of column names, click the names of columns you want to view. When you select a
column name, the column instantly appears in your current results view. If you clear the selection of
a column name, the column immediately disappears from the results view.
To rearrange the column order, in the left panel, drag the name of any selected column to a new
position in the list. When you do this, the order of columns dynamically changes in the search
results panel on the right side of the page.
Non-persisted method:
1. Run a message tracker query to obtain a list of results.
2. Modify the column view of the results by adding or removing one or more columns. (The
information for any new columns is automatically displayed.)
3. Click on any transaction in your list of results to view the detail page for that transaction.
4. Click the browser back arrow to return to the results list view.
Result: The browser displays the default results view, removing your custom changes
Persisted method:
To avoid losing a custom view after you open the detail view:
1. Run a message tracker query to obtain a list of results.
2. Modify the column view of the results by adding or removing one or more columns. (The
information for any new columns is automatically displayed.)
3. Click on any transaction in your list of results to view the detail page for that transaction.
4. On the menu bar, click the name Message tracker to return to the search results list view. Do
not elect any options that appear in the menu
Result: The browser displays your custom column selections.
l From
l To
l Original filename
l Delivery filename
l Document ID
The wildcard characters are * and ?.
The * is used in place of multiple characters. The ? is used in place of a single character. For
example, if searching for the word wildcard, you could type wildc*, where * is in place of ard. A
search of this type finds all records beginning with wildc. You also could type wil?ca?d, where ?
is a request to find any character in the specified positions.
There also is an escape character — the back slash \ — when the * or ? wildcards are needed as
literal filtering conditions. For example, if you want to search for an asterisk as the literal part of a
string, use \*.
The following figure is an example of a search results page with the controls hidden. Click
Show/Hide to toggle the view.
You can click some of the values in the returned search results to display options for searches based
on a single value. Move your cursor over the table of search results. When the cursor displays as a
hand symbol, you can click the table cell for more searching options.
For example, in the following figure, the From ID value ZZacme was clicked to display two search
options.
These search options are:
The most comprehensive option is to click the Details link for a message. This action opens a
message details page organized by tabs. These pages provide a large amount of information about
traded messages. For more information see Message details tabbed pages on page 835.
Another option is to place your cursor over the Details link and wait two seconds until a pop-up
window displays. Initially, these pop-ups do not display any data. But you can choose message
attributes to display. The pop-ups are a quick way to view attributes and values related to messages
without opening the message details tabbed pages. For more information see Search results
attributes in pop-up windows on page 838.
The following figure shows the document summary tab of a message details page. Only the top
portion of the page is shown due to length.
Trading activity information is provided on the following tabs. If a search finds more than one
message, click the Next and Previous buttons at the bottom of each tab to scroll through
messages.
Document summary
This tab identifies the message type and status (delivered, negative response, failed, in process,
waiting for receipt, resubmitted). It also reports the message direction (for example, inbound from a
partner or outbound to a partner). If a failed message, a reason is given at the bottom of the tab.
Links are provided for viewing and downloading the message payload.
On the document summary tab, you can click Add a note to type notes regarding the message.
The tab also displays messages that were added earlier and lets you change or delete notes.
If you want to search for user-authored notes about messages or display notes in a column on the
search results page, do the following:
2. After the administrator assigns the attribute as in use, go to the search page, type u in the
Attribute field and wait for the autocomplete values to display. Select UserAnnotation and
click Add. This adds a User annotation column to the search results page. User annotation also
is added as a option under the Columns section of the custom search panel on the left side of
the page.
ebXML activity
This tab reports metadata specific to ebXML messages. The information is view-only. Use the
Message attributes on page 837 tab to perform metadata searches.
This tab only displays for an ebXML message. If you do not process ebXML messages, this tab does
not display.
RosettaNet activity
This tab reports metadata specific to RosettaNet messages. The information is view-only. Use the
Message attributes on page 837 tab to perform metadata searches.
This tab only displays for an RosettaNet message. If you do not process RosettaNet messages, this
tab does not display.
Document activity
This tab provides the dates and times for events related to a message’s processing history.
Message attributes
This tab reports values for metadata attributes related to messages. You can use the metadata to
perform narrower message searches based on specific values.
Some of the metadata on this tab is self-explanatory (for example, Direction, ReceiverRoutingId,
SenderRoutingId). Other metadata may seem esoteric. Also, the list of data can vary depending on
the message type. You may find this tab provides more information than needed for monitoring
normal message traffic. But if you are working with technical support to troubleshoot an issue,
support may refer you to this tab for information. This metadata also may be helpful for users who
employ APIs to manipulate message metadata or who exchange messages via the ebXML message
protocol.
The table on this tab shows the metadata names or the attribute names. A metadata name is the
name Interchange uses internally. An attribute name is a friendly name for a metadata element. For
example, ConsumptionUrl is the metadata name and Consumption URL is the attribute name.
You can toggle between name types by clicking Show metadata names and Show attribute
names.
You can select metadata to include in a new search, and you can include the metadata element in
saved searches. If you clear the check box for Find messages originating within the last [n]
days, the new search includes all dates. The default number of days for this option can be changed
(see Manage default search settings on page 843).
Initially, these pop-ups do not display any data. But you can choose message attributes to display.
This feature is engaged by default but can be disabled. The following shows a pop-up without any
message attributes.
You can close a pop-up window by moving the cursor outside the window and left-clicking once, or
click Close inside the window.
Although there are many attributes from which to choose, we suggest selecting only a few of the
ones most helpful to you. Remember, all attributes you select display in the pop-ups, regardless
whether a value exists for a given attribute. The idea is to select attributes common to many of the
messages you look up in Message Tracker.
To select attributes to display in the pop-up windows on Message Tracker search results pages:
1. Click Select attributes for pop-up windows in a pop-up.
or
2. Select Message tracker > Select attributes for pop-up windows on the top toolbar.
Either action opens the page titled, “Select attributes for pop-up windows.”
Either action opens the page titled, “Select attributes for pop-up windows” shown in the figure
below.
The attributes you select apply only to you and not to other users. After selecting the attributes you
want, click Save. Go back to the Message Tracker search results page and place the cursor over a
Details link until a pop-up window displays.
The following figure shows a pop-up window displaying selected attributes for a message on the
Message Tracker search results page.
In addition to selecting attributes for their own use in the available attributes section at the top of
the page, administrators can make changes affecting themselves and all other users. These are:
Icon Description
Indicates the routing ID does not agree with the party profile configuration. This icon
can appear in the From ID and To ID columns, if the columns are selected for search
results and if conditions warrant displaying the symbol.
When you move the cursor over the icon a message appears: “Routing ID does not
correspond to the receiver” or “Routing ID does not correspond to the sender.”
If the icon appears next to From ID, the routing ID does not belong to the partner who
sent the message. If the icon appears next to To ID, the routing ID does not belong to
the community that received the message.
Indicates a message was re-routed.
Message receipts
If the community collaboration settings request partners to send receipts (see Collaboration settings
on page 909), Message Tracker creates reports of the receipts from partners that c onfirm message
deliveries,
Message receipts also go by other names such as acknowledgments and message disposition
notifications (MDNs). In Message Tracker, the word "receipt" is used.
When a signed receipt is requested, but an unsigned receipt is received, the unsigned receipt is
rejected (ignored). This results in a resend of the original document until a signed receipt is received
or the maximum number of resends is reached.
All signed receipts must contain a Received-Content-MIC value. Any signed receipt that does not
contain a Received-Content-MIC is rejected.
When a signed receipt is received, its Received-Content-MIC is compared to the MIC of the original
document. This is the case whether the original document requested a signed or unsigned receipt.
When a receipt is received for a document that did not request a receipt, the received receipt is
rejected.
Received-Content-MIC values in unsigned receipts are ignored. This is because there is no way to
guarantee the validity of any information in an unsigned receipt. And since the primary purpose of
the Received-Content-MIC value is for non-repudiation, it does not make sense to give any weight to
such a value in an unsigned receipt.
Not all actions are valid for all types of messages, but the user interface indicates when an action
you select can be applied. If an action is valid for a message, you can select the check box at the
beginning of the results record line. If an action is not applicable, you cannot select the option.
l Delete – Delete messages and receipts from the database and backup directory. Only messages
in a final processing state can be deleted. Only parent messages can be deleted. To delete child
messages or receipts, the related parent must be selected.
l Resend – The following can be resent:
o Receipts for messages received previously from partners can be resent to partners.
Resent receipts are not packaged (no signing, encryption, compression).
o Messages previously sent to partners can be resent to partners. A previously sent
message is not repackaged. Rather, the previously sent packaged message is sent again.
Transport retries and business protocol resends are respected for the resent message, as if
the original send did not occur.
o Messages previously sent to integration can be resent to back-end applications.
Transport retries are respected for the resent message.
Message Tracker also can resend individual child documents split from batch EDI documents
by Interchange’s bundled EDI splitter, which can be enabled on consumption exchanges.
This applies only to resends and not the reprocess action. Moreover, child documents of
outbound parent messages sent via the ebXML, RosettaNet and Web services protocols are
not affected, as with those protocols it is the parent payloads that are packaged and sent.
l Reprocess – Reprocessing is applicable to messages outbound to partners and inbound from
partners.
o Reprocessing an inbound message again unpacks the received message, resends the
message to back-end applications and resends the receipt to the partner if the receipt is not
synchronous.
o Reprocessing an outbound message repackages the original message and resends it to
the partner.
If you resend a message a partner already has acknowledged, the partner’s trading engine may reject
the resent message as a duplicate unless steps are taken to anticipate the resend.
When a message is resent or reprocessed, Message Tracker marks original messages as resubmitted
and creates and submits a new message with the content of the original message. The original
message and the resubmitted new message are linked together when viewing details in Message
Tracker.
For reprocessing, if an original outbound message was retrieved from an application pickup
configured with message metadata element values, the original metadata is resubmitted with the
message. If the metadata configuration for the pickup was changed between the original
submission and the resubmission, it is the original metadata that is resubmitted and not the
currently configured metadata.
Use of the resend and reprocess options relies on whether Interchange is configured to back up
message payloads. For more information, see Backup options and Message Tracker on page 851.
Note Whether you select messages to resend or reprocess, Message Tracker reports the status of
both actions as resubmitted. For the purpose of reporting status, Message Tracker cannot
differentiate between a resent message and a reprocessed message. Instead, the status of
both actions is given as resubmitted.
Sharing allows other users to execute searches without having to recreate the conditions that
administrators already have set up for saved searches.
To share and remove searches, your user name must be associated with the admin role or a role that
includes the administrator permission.
The Share searches menu option opens a page for managing shared searches. The page has two
tabs:
l The list of system-defined default searches that appear on the Message Tracker menu.
l Values that control the maximum number of search results that can be displayed or deleted.
l Enable or disable message attribute collecting for optional display in pop-up windows on the
Message Tracker search results page.
There are several ways to open the page:
The following describes the fields on the Global message tracker settings page. Click Save changes
after making any changes.
Query restrictions
l Number of days for default searches – The value in this field is the number of days that
appears in the search option Within the last [n] days under the date area on the custom
search panel of the Message Tracker page.
This also is the value for a search condition on the message attributes tab of the message details
page. The value applies to the check box for Restrict search to messages that originated
within the last [n] days at the bottom of the tab.
Moreover, if you click Find without specifying search conditions on the Message Tracker search
page, the search finds all messages traded within this number of days.
This field’s value also sets the number of days for the default searches Failed messages and
Negative responses on the Message tracker menu on the top toolbar.
l Maximum search results allowed to delete – The maximum number of search results you
can delete with a single delete action on the Message Tracker page. For example, if more than
the maximum number of search results are returned and you try to delete all results, Interchange
does not delete any of the messages. Instead you are prompted to define a search that returns
fewer records than the maximum allowed to delete. Limiting the number of search results that
can be deleted at once helps maintain database performance.
l Default number of search results to return – The number in this field is the default value
of the Maximum # of search results field on the custom search panel of the Message Tracker
page.
l Maximum number of search results to return – The number in this field is the highest
allowed value of the Maximum # of search results field on the custom search panel of the
Message Tracker page. If you are performing a search and enter a number in the Maximum # of
search results field that is larger than this value, an error message displays.
l Default days for before or after date searches – The number in this field is the default
value for the on a maximum [n] days period field for the After and Before option under date
searches on the custom search panel of the Message Tracker page.
1. In Message Tracker, expand the Columns category in the custom search area on the left side of
the page. Select document type as a column for display in search results.
2. Execute a search. Note the document type of the document you want to display with a
stylesheet. If the document is XML, the document type is blank. See Force a document type for
XML on page 848 for how to remedy this.
3. Select Message tracker > Configure payload view on the toolbar. The Document type
page displays.
5. In the name field, type the document type you noted in step 2.
6. Optionally, type a description.
7. Select the stylesheet to apply for display from the stylesheet list.
The following stylesheets may be available by default.
defaultEDI.xsl Formats an EDI document that has been converted to XML via rules files.
defaultXML.xsl Formats any XML document.
defaultXML2.xsl Formats any XML document.
e222.xsl Formats CSOS documents. This stylesheet is intended for CSOS EDI
documents.
Depending on your license agreement, other stylesheets may be available. You also can use
your own stylesheets rather than the default stylesheets.
For EDI, note that the default stylesheets work only if your system has the proper rules files for
converting EDI to XML. These files are in <install directory>\conf\tx\oboe_rules. As
part of the default installation, you should already have the rules files you need. If not, contact
technical support.
For XML documents, if you want to use your own stylesheet, test the stylesheet with a sample of
the XML document to make sure it works. Then copy the stylesheet to <install
directory>\conf\web\documents. Your stylesheet then appears in the stylesheet selection
list in the user interface.
For EDI documents, if you want to use your own stylesheet, contact Axway professional
services for help.
8. Select View formatted using a stylesheet.
9. Click Save.
10. Execute a search in Message Tracker. You can type a value in the document type field to narrow
the search for a single document type.
11. When the search results are displayed, click a Details link for the document type you added to
view message details.
12. On the document summary or message processing details tab, click a view payload link. The
selected stylesheet is used to display the document. In this view, you have the option to switch
to a plain text or browser view or switch back to the stylesheet view.
Forcing a document type value enables you to view future XML documents with a stylesheet, but not
the XML documents traded before forcing the value.
The default backup directory is <install directory>\common\data\backup. You can change
this default directory location.
You can configure the product so that backed-up messages of a certain age are deleted. This lets
you delete unwanted database records and backup files. When triggered, database records about
documents and the corresponding files in the backup directory are deleted. Once deleted, you no
longer can search for, view or reprocess these documents in Message Tracker on page 826.
When you view payloads in the Message Tracker on page 826 area of the user interface, the system
retrieves the documents from the backup directory. When you use Message Tracker to resubmit a
document, a copy must be present in the backup directory. For these reasons, it is important to
ensure the backup directory has the capacity to store all the documents you want.
Delivery exchange configuration controls whether documents are backed up. See Modify an
application pickup or delivery on page 202 for more information.
Backing up files is strongly recommended. This is required for the system to perform fail-over
operations such as attempting to send messages again (retries) in case of a transport connection
failure.
With backups disabled, payloads (up to a certain size) are stored in-memory. If the process is ended,
the memory is cleared and the payloads are lost. Without backups, a message in process cannot be
recovered if the server or a processing node stops or restarts. Backups also are needed if you want
the ability to resubmit messages to the back end or resend messages to partners.
Backup files are stored in <install directory>\common\data\backup, unless you specify
otherwise.
There are two places in the user interface to configure how Interchange backs up the messages it
processes.
l You can turn on or off message backups selectively for each pickup and delivery exchange. By
default, backup is enabled. To change the backup behavior for an exchange, see Community
trading pickups and partner deliveries on page 256 and Modify an application pickup or delivery
on page 202.
l The global backup configuration page has settings affecting how all messages for all
communities are backed up. On this page you can set the root path for directories containing
backed-up files and the frequency for creating back-up directories. You also can ordain whether
the message handler backs up messages. By default, backup is enabled.
l Root path – Use the root path field to specify the path of the backup directory. The backup
directory can store copies of all traded documents in their clear (unencrypted) and encrypted
forms. The default is <install directory>\common\data\backup.
The system supports conventional paths for the backup directory, such as C:\data\backup in
Windows, and paths incorporating a server name (Uniform Naming Convention).
When running Interchange in a cluster on multiple computers, the backup directory must be a
shared directory accessible to all computers.
l Schedule to create backup subdirectories – This field specifies the schedule for creating
backup subdirectories. Interchange creates a subdirectory periodically to limit the number of
backup files in a single directory. Automatic, the default setting, causes a backup subdirectory
to be created about every hour. Subdirectories are created only as needed to accommodate
trading activity. Subdirectories are not added when there is no activity.
The automatic setting is fine in most cases. However, if your volume is low (10,000 documents a
month or less) and you want to minimize the number of subdirectories created, specify the
infrequent value Monthly. If your volume is extremely high (500 documents per minute or
more) specify the high frequency Every minute to reduce the number of files in each
subdirectory and improve performance.
Although the setting Never is available, it is not recommended.
l Message handler backs up messages – Select this option to enable the back up of
messages that pass through the Interchange message handler. The message handler is
responsible for actions such as packaging (encryption, adding MIME headers) and unpackaging.
Caution: Message handler backup is required to successfully split a document. The EDI Splitter
will not work with Message handler backups disabled.
Enabling message handler backups (the default setting) does not result in adding a larger
volume of files to the backup directory, as messages are backed up when content and state have
changed, not simply when the state has changed. However, turning off backups can result in
fewer backed-up states. Regardless, turning this on or off does not affect searching in Message
Tracker.
If security of clear text files is an issue, turn off message handler backups. This ensures all
messages — encrypted and unencrypted — passing through the handler are not backed up.
Furthermore, you must disable backups for transports that handle clear text messages (for
example, integration pickup). Only disabling both guards against backing up clear text
messages.
Disabling message handler backups has consequences that may weigh upon a decision to
disable or not. When disabled, messages in the packaged state bypass the message production
system and go straight to the producer. This means if a schedule has been set for turning on and
off a delivery exchange, the schedule is ignored. Moreover, the exchange’s setting for maximum
concurrent connections is ignored.
l Consumed – Consumed is appended to names of documents that have been received from
partners but not unpackaged or that have been picked up from integration but have not been
packaged or sent.
l UnpackagedRequest – UnpackagedRequest is appended to names of documents that have
been received from partners and unpackaged. These documents are clear text.
l Packaged – Packaged is appended to names of documents that have been packaged and
scheduled to be sent to partners.
l Consumption exchanges (integration pickup and receiving from partners)
l Production exchanges (integration delivery and sending to partners)
l Message handler
There may be reasons for tuning off message backups at one or more points. For example, the field
Message handler backs up messages is used to adjust configuration when backups of clear-text
messages are not wanted.
Turning off backups at all three points would restrict Message Tracker. Although you could still
search for messages based on information stored in the database, you could not view the actual
messages for the lack of backups. You also could not resend or reprocess any messages.
The following table summarizes how changing backup settings affects the ability to resend and
reprocess messages in Message Tracker.
Action Requirement
Resend Backing up must be enabled for production exchanges or the message
handler. If neither backs ups, resending is not possible.
Reprocess Backing up must be enabled for consumption exchanges. If there are
no backups of consumed files, reprocessing is not possible.
The following tables break down in more detail how backup settings affect the ability to resend or
reprocess outbound and inbound messages.
Outbound messages
Application pickup Off No No
Send to partner Off
Message handler Off
Send to partner On
Message handler Off
Send to partner Off
Message handler On
Send to partner On
Message handler On
Inbound messages
Application delivery Off No No
Receive from partner Off
Message handler Off
Receive from partner On
Message handler Off
Receive from partner Off
Message handler On
Receive from partner On
Message handler On
Also included are configurations for all deliveries, except community application pickups, which are
common to all communities and not to a single one.
Message handler actions are not backed up, as these are set up in an area of the user interface
shared by all communities. Moreover, community and partner collaboration settings are backed up,
but not default collaboration settings.
You can back up a community and keep the file in reserve for disaster recovery or other reasons. The
file can be imported to an installation of Interchange with a fresh database, providing instant
configuration of a community and its associated partners.
You cannot export a community from an Interchange running on one type of platform and import it
to a trading engine on another platform. For instance, if you export a community from an
Interchange instance on Windows, you must import it to the same or different instance also on
Windows.
If you have configured any pluggable transports, these are saved to the backup file, except for
application pickups. Pluggable transports are customized message consumption and production
exchanges available to users of the Software Development Kit. Restoring pluggable transports upon
importing the backup file requires having a pluggabletransports.xml file in <install
directory>\conf that describes the transports. For example, if the backup saves two application
deliveries based on a custom transport configured in pluggabletransports.xml, the instance of
the Interchange that imports the backup also must have identical configuration for the custom
transport in its pluggabletransports.xml file.
Back up a community
Use this procedure to back up a community and all of its partners to a single compressed file. Also
see: Import a backed-up community.
2. Click on the name of the community you want to back up, to open the Summary page for that
community.
3. At the bottom of the community summary page, click Export this community and its
partners.
4. Enter a password for the exported file. This protects the community's private keys. You must
provide the password if you later import this file.
5. Click Export.
Interchange generates a community profile XML file, using the community and all associated
partners.
It is best to keep the backed-up file as-is; do not decompress it. Do not open the file or extract
parts of it with the intent of importing individual pieces. If you import the file, Interchange
deploys the community and associated partners. For more information, see Import a backed-up
community and its partners on page 855.
To create a community backup, see Back up a community and its partners on page 853.
You can import a backed-up community file to a new instance of Interchange with a fresh database
or to an existing instance.
You must work in the Interchange user interface to import the community backup. You import the
same compressed file that was exported. Do not copy the file to the profiles\autoImport
directory. The file is not compatible with auto-importing.
5. Enter the password used by the export to protect private key certificates in both the Password
and Confirm password text boxes.
6. Select a type of import:
l Replace if community exists
l Rename the new community
l Ignore if community exists
l Update if community exists
7. If your license supports the peer network, the option Allow application delivery to be
auto-cloned to peers is selected by default. You can clear this option if you do not want
auto-cloning or do not use the peer network.
8. Click Next to import the file. A results page displays details about the imported configuration.
9. Click Finish to import the backed up community and partners. If a duplicate community is
detected, you can overwrite the existing community or rename the imported community.
If you have associated a certificate with the community, the certificate and public key is exported
with the profile.
If the community has more than one trading pickup for receiving messages from partners, the
default pickup is the preferred transport. The default pickup is the one that displays at the top of the
list on the community’ s Trading pickups page. Before you export the community, you can
change the default trading pickup or disable a transport to refine the options available to your
partner.
Distribute the profile to our trading partners by a secure means. If you send the profile file to trading
partners as an e-mail attachment, we recommend compressing it with WinZip or similar software to
ensure file integrity.
You only can export a community in a form usable as a partner profile. You cannot export the
community by itself as a usable community profile. You can, however, export an entire community
(the community profile and all associated partner profiles). For more information see Back up a
community and its partners on page 853.
If you give the profile file to a trading partner who uses Interchange or Activator 4.2.x or earlier, the
partner’s system prompts for additional information in the imported partner profile. The partner’s
system prompts for the community’s address, city and state or zip code. This information is not part
of a community profile. You can either provide your trading partner with this information or the
partner can determine what to enter upon importing the profile.
Back up a partner
You can back up (or "export") a partner and public key certificate to an XML file. You can then use
the backup file (known as a partner profile) deployment, promotion, local restoration, or give it to
your trading partners who use B2Bi, Interchange or Activator. If your partners use other
interoperable trading software, consult with them on the data they require of you to establish
trading relationships.
Similarly, a trading partner who uses B2Bi, Interchange or Activator can export a partner
configuration and public key certificate to a file and give it to you to import as a partner. For trading
partners who use other interoperable software, collect the trading data you need and then manually
create a partner object tor represent the trading partner in the user interface. The Partner data form
on page 151 provides a way to document the data needed to create a partner object.
A backed up partner profile contains information such as the partner name and routing ID, as well as
the configured transports for sending messages to the partner. If there is more than one exchange,
the order of the transports is preserved. The first listed exchange is the default.
Other preferences included in exported partner profile files include:
l All advanced settings that display on transport maintenance pages in the user interface, such as
maximum concurrent connections, retries, connection, response and read time-outs.
l HTTP chunking and attempted restarts for HTTP.
l Transport friendly names.
l The transport’s setting for backing up files.
l The paths and file names of post-processing scripts, but not the scripts themselves.
l Information for inline processing Java classes is included in exported profiles, but not the Java
classes themselves.
l If the profile has an FTP transport with an alternate command set file, that preference is included
in the exported file, but not the command set file itself.
If you are upgrading from earlier versions, you can create backup files of partners and import them
as partner profiles in this version.
Import a partner
You can restore (or "import") a partner configuration and public key certificate that have been
backed up to a partner profile XML file.
For partner configuration backup procedure, see Back up a partner on page 857.
A backed up partner profile contains information such as the partner name and routing ID, as well as
the configured transports for sending messages to the partner. If there is more than one exchange,
the order of the transports is preserved. The first listed exchange is the default.
Other preferences included in exported partner profile files include:
l All advanced settings that display on transport maintenance pages in the user interface, such as
maximum concurrent connections, retries, connection, response and read time-outs.
l HTTP chunking and attempted restarts for HTTP.
l Transport friendly names.
l The transport’s setting for backing up files.
l The paths and file names of post-processing scripts, but not the scripts themselves.
l Information for inline processing Java classes is included in exported profiles, but not the Java
classes themselves.
l If the profile has an FTP transport with an alternate command set file, that preference is included
in the exported file, but not the command set file itself.
If you are upgrading from earlier versions, you can create backup files of partners and import them
as partner profiles in this version.
1. Go to the partner summary page and click Certificates in the navigation graphic at the top of
the page.
2. Click the certificate name and then click the Trusts tab.
3. Check the details of third-party certificates imported with profiles to make sure trusted roots are
present.
After importing a partner profile, go to the partner summary page for the imported partner and
check whether any tasks are required to complete the profile configuration.
<install directory>\tools
The following table shows the types of customizations this tool can back up and restore, and where
they are typically located.
Note: This tool is not limited to these directories and customization types.
Property files and XML files <install directory>\Interchange\conf
Inline processor (from one of the nodes) <install directory>\Interchange\site\jars
JTF %_SHARED%\local\BOM
TF-XSLT %_SHARED%\local\BOM
Procedure:
1. Customize the externalConfigBackupRestore.xml file to include the appropriate paths to
the custom components.
2. Run the externalConfigBackupRestore.cmd tool.
The tool provides information on the available commands.
Profiles written to <install directory>\profiles\autoImport are imported by Interchange
when the server is running. Once imported, the system moves the profiles files from
profiles\autoImport to the appropriate profiles\backup subdirectory, either community or
partner. The system makes all imported partner profiles members of all communities. The system
creates pickups and deliveries for an imported community.
If Interchange is unable to import a profile file in the autoImport directory, the system moves the
file to \profiles\autoImport\rejected.
Note If you have exported a community and its partners to a backup file (see Back up a
community and its partners on page 853 ), do not use the autoImport directory to import
the file. Interchange rejects the file.
The system also has some profile staging directories, as shown in the following illustration. The
system does not write to these directories, except during installation when a user is upgrading from
a previous version. The directories are a place to hold profile files before a user moves them to the
autoImport directory. The software installer, for instance, writes profile files to the staged
directories if the user during installation chooses to have profiles exported from an earlier version of
Interchange.
\backup \community\partner
\staged \community\partner
Interchange cannot import a password-protected profile through the autoImport directory. The
password protects the certificate private key. Make sure to securely handle a company profile
exported without a password.
Events for profile imports and rejects are written to control node events log(hostname_cn_
events.log)in the logs directory. The events are:
l Administration.Configuration.Party.CommunityImported
l Administration.Configuration.Party.PartnerImported
l Administration.Configuration.Party.ImportFailedSecret1
To configure automatic purging:
If you use a database other than Oracle, an event such as the following is written to the event log file
when a message is deleted:
With Oracle, events are handled with a stored procedure, and events such as this are not written to
the log.
We recommend setting the age for deleting messages identical to the age for deleting message-
related events. For more information, see Configure event purge on page 865.
If the page for configuring purge dates calls for deleting records and messages less than 2 years old,
CSOS records and messages do not abide by this schedule and are retained for two years. If the
setting on this page is more than two years, CSOS messages are retained for the longer period.
This tool has special options for use in DB2 environments. See parameter descriptions below.
Caution Make sure Interchange server is turned off before using messagePurgeTool. This includes
servers on all machines if you have a cluster environment.
Parameters
Run messagePurgeTool with one of the following parameters. You can only use one parameter at
a time.
deleteAll
Deletes all records in the database and related backup files regardless of age or state.
Depending on the volume of records in the database and backup files, the utility may have
to run a while to delete all.
Using with DB2 databases:
For DB2 database environments only, this parameter can be run with the -noLog option.
Use the –noLog option to disable transaction logging in DB2. If you do not use the -noLog
option, transaction logging remains enabled.
In a single-host DB2 environment, the only impact of –noLog is to reduce the log space
used on the DB2 system.
Warning: Do not use the -noLog option in clustered DB2 implementations. The
transaction log is needed to maintain the synchronization of clustered databases.
deleteAllSkipFiles
Deletes all records in the database, but does not delete backup files. If you have a large
number of records, this option works faster than the deleteAll option. However, if you use
it, you must manually delete backup files. For example, by deleting the backup directory.
Using with DB2 databases:
For DB2 database environments only, this parameter can be run with the -noLog option.
Use the –noLog option to disable transaction logging in DB2. If you do not use the -noLog
option, transaction logging remains enabled.
In a single-host DB2 environment, the only impact of –noLog is to reduce the log space
used on the DB2 system.
Warning: Do not use the -noLog option in clustered DB2 implementations. The
transaction log is needed to maintain the synchronization of clustered databases.
resetMessages
Changes the purge dates of records in the database and of documents in the back-up
directory. When messages are processed, Interchange assigns future purge dates, based on
the age interval set on the purge configuration page in the user interface. If you change
the age interval, you can use the resetMessages option to change purge dates of existing
records and documents in line with the changed interval.
For example, if the interval is 45 days, the system sets the purge date for messages
processed today as the date 45 days in the future. On day 44, you change the interval to
90 days and then run the resetMessages option. The system re-calculates the purge dates
of existing messages as 90 days in the future of the messages’ origination dates. This
means on day 44, the purge date is set ahead 46 additional days, for a total of 90 days
before purging.
The utility may take a while to run with this option if there are a large number of records to
reset. See Configure automated Interchange purge on page 862.
Example
To delete all records in the database and all related backup files, run the following command:
messagePurgeTool -deleteAll
Event logging
Events related to running the messagePurgeTool are written to the messagePurgeTool.log file
in the <install directory>/logs directory.
The following topics describe how to change the default FTP client implementation when the client
must interact with an FTP server that requires non-standard commands or expects commands in a
different order than the default in the command set document. Such changes can range from
editing the command set document to creating Java classes that implement non-standard FTP
commands.
Any change to the FTP client requires familiarity with Interchange and the FTP protocol as described
in RFC 959. Simple modifications require editing the XML command set document. Advanced
modifications require familiarity with the Java programming language and writing and compiling
Java classes.
Concepts
l Levels of scripting on page 866
l Edit the command set document on page 867
l FTP tester tool on page 868
l FTP scripts for Interchange application exchanges on page 871
Reference
l RFC 959 - http://www.ietf.org/rfc/rfc959.txt
Levels of scripting
The following describe the three levels of possible scripting changes, ordered from simplest to most
complex.
an FTP server immediately prompts for a password rather than first prompting for a user name,
you can remove the line that sends the User command from the authenticate meta-command.
2. Change Java classes containing commands. A Java class implements each command (for
example, User). To change the behavior of a command or to add a command, you must edit or
create the Java class that implements the command. Then compile the class and make it
available to the FTP client. More information is available in the Developer’s Guide for the
optional Software Development Kit available from Axway.
3. Write a custom FTP client implementation. The default client implementation is the
framework of the FTP client. It includes classes that manage the connections with the server
and that read and execute the commands in the script. You can replace the default client
implementation with one that does not use a script. For example, if a user has an FTP client
implementation written in Java, it could be modified to work with Interchange by replacing the
default client implementation with an interface to the user’s existing implementation. More
information is available in the Developer’s Guide for the optional Software Development Kit
available from Axway.
While interacting with the FTP client, Interchange executes meta-commands defined in the script,
such as receive and send. For each meta-command, the script specifies the FTP commands to send
to the FTP server and in what order. Interchange is not aware of the specific FTP commands being
sent to the FTP server, which means changes to the command set document do not require changes
to Interchange.
One example of the changes you can make to the command set document is reordering the FTP
commands comprising a meta-command. As a simple example, the receive meta-command sends
the Type and Size commands, in that order. You could reverse the order by transposing those two
lines in the script.
Users of the FTP client, such as the ftpTester program and Interchange itself, invoke the connect
and authenticate meta-commands before issuing any other commands.
Changes made to the script take effect the next time Interchange needs to access the FTP server;
Interchange server does not have to be restarted.
To use a command set document other than ftpcommandset.xml, you must add an entry for your
document in <install directory>\conf\filereg.xml and restart Interchange server. You
also must do this if you want to use a different command set document for each FTP delivery
exchange.
ftpTester is a console-based application that can verify the operation of the FTP client in
Interchange and a partner’s FTP server. Interchange server does not have to be running to use this
tool. You can use it on UNIX or Windows.
ftpTester duplicates the way Interchange accesses an FTP server. It is a test program to verify
interoperability with FTP servers. If you can send, list, receive and delete files on a FTP server using
ftpTester, this is a good indication Interchange can interoperate with the server.
ftpTester prompts for all the information it needs, as the following illustrates. Two views are shown,
depending on whether you are testing receiving (consuming) or producing (sending).
Consumer options
**** Welcome to the Cyclone FTP test program ****
-> Enter host: localhost
-> Enter user: ftpuser
-> Enter password: cyclone
-> Enter account (leave blank for most servers):
-> Enter pickup directory (blank for "pickup"):
-> Enter c for CONSUMER client (list, receive, delete), p for PRODUCER
(send). (Blank assumes c): c
-> Should temp files be used to avoid read/write collisions? (Y/N -
default is Y):
-> Should a separate inbox dir be used (instead of putting temp files in
the pickup dir)? (Y/N - default is Y):
-> Enter inbox dir where files will initially be uploaded before being
moved to pickup dir (blank for "inbox"):
-> Use SSL? (Y/N - default is N):
-> Should restarts be attempted for binary files if supported by the
host? (Y/N - default is Y):
-> Enter minimum bytes a file must contain to be eligible for restarts
(blank for 100000):
FtpClientSettings - host=localhost pickupDir=pickup ctlPort=21
passive=true type=Binary mode=Stream struct=File user=ftpuser account=
transportId=FtpTester
receiveTempDir=/Applications/cyclone/b1095/bin/ftpRestart_FtpTester
connectTimeoutMs=30000 readTimeoutMs=30000 attemptRestarts=true
evaluateRestartable=true restartableMinBytes=100000
commandSet=../conf/ftpcommandset.xml preserveFilename=true
overwriteIfDupe=true fixOutputFilenames=false tempFileExt=.tmp
useDebounce=true useInbox=true isSSLEnabled=false
Host working directory: "/Users/ftpuser" is the current directory.
Host pickup directory (used by REC, DEL and LIST): pickup
Local working directory (used by REC and LLIST):
/Applications/cyclone/b1095/bin (LCD to change)
-> Enter CONSUMER command (e.g. ?, LIST, RECeive, DELete, LLIST, ASCII,
BIN, LCD, QUIT): ?
CONSUMER metacommands (abbreviations shown in upper case):
? help
LIST list files on host
RECeive filename retrieve file from host
DELete filename delete file from host
ASCII perform ASCII data transfers
BINary perform binary data transfers
LCD change local working directory
LLIST list files in local working directory
PASV perform data transfers in passive mode (the default)
PORT perform data transfers in port mode
QUIT/EXIT/BYE exitNormal FtpTester
Producer options
**** Welcome to the Cyclone FTP test program ****
-> Enter host: localhost
-> Enter user: ftpuser
-> Enter password: cyclone
-> Enter account (leave blank for most servers):
-> Enter pickup directory (blank for "pickup"):
-> Enter c for CONSUMER client (list, receive, delete), p for PRODUCER
(send). (Blank assumes c): p
-> Enter PRODUCER command (e.g. ?, SEND, LLIST, ASCII, BIN, LCD, QUIT):
?
PRODUCER metacommands (abbreviations shown in upper case):
? help
SEND filename write file to host
ASCII perform ASCII data transfers
BINary perform binary data transfers
LCD change local working directory
LLIST list files in local working directory
PASV perform data transfers in passive mode (the default)
PORT perform data transfers in port mode
QUIT/EXIT/BYE exitNormal FtpTester
After prompting for the initial configuration information such as the host, user and password,
FtpTester displays a main prompt that allows you to enter meta-commands to perform simple
operations such as list, send and receive. You can enter a question mark (?) at this point to get more
information.
Script comments
You can add comments to scripts. A comment starts with a # character and continues to the end of
the line. The following is an example:
In this documentation statement keywords are capitalized, but case is not significant.
Variables
There are two types of variables you can reference in scripts:
l Script variables on page 872
l Environment variables on page 873
Script variables
All script variables are of type string. A variable name is preceded by a % character. Use the equal
sign to create and assign variables. For example, the following line creates and initializes the variable
myvariable:
%myvariable = "data";
Variable Description
%EXEC The value returned from the last local command. See Local Command on page
879.
%TMPDIR The path of a temporary directory at the local site (the machine where
Interchange is installed). Temporary files can be stored in this directory.
%FTPSTATUS There are two cases:
For the LIST statement: If the NLIST command was executed, %FTPSTATUS is
set to the reply code from the NLIST command; otherwise, it is set to the reply
code from the last (or only) command executed.
For statements other than the LIST statement: %FTPSTATUS is set to the reply
code from the last (or only) command executed.
If a script is executed locally, Interchange simulates execution of FTP
commands and sets the variable accordingly.
Variable Description
%LOCALFILE Interchange saves a copy of the message being processed to a file at the local
site and sets the variable to the path and file name of this file.
%REMOTEFILE Interchange generates a unique name for the message being processed and
sets the variable to this name. The name is the transfer ID of the message.
Because the name is unique within Interchange, it provides a way of
generating unique file names.
%LOGID Interchange sets this variable to the transfer ID of the message being
processed. In the message log, you can use the transfer ID to identify the log
entry. There is precisely one associated with the message.
Environment variables
For a local host, a script can reference Interchange environment variables. A reference has the
format:
$variablename
where variablename is the name of the environment variable. For example, the following line
references the environment variable:
$CORE_DATA:
CD $CORE_DATA"/ftp/public";
Script execution
RFC 959 (http://www.ietf.org/rfc/rfc959.txt) specifies the valid reply codes for each FTP command.
Reply codes in the range 200-299 are non-error codes. All other reply codes are error codes.
A script either completes with or without unsuppressed errors. When a a script executes,
Interchange opens a connection to the FTP server. Interchange sends the FTP commands one by
one to the FTP server. If a reply code is:
l Not a valid reply code for the given command, the statement terminates.
l A valid code for the given command and an error code, the statement terminates.
l A valid code for the given command and a non-error code, Interchange sends the next
command, if any, to the FTP server.
Normally, if a statement terminates, the script terminates. However, if the statement is preceded by
the “-” qualifier, the error is suppressed and the script does not terminate. Once the script is
completed or terminated, Interchange closes the connection to the FTP server.
Error Suppression
You can use the “-” qualifier to suppress errors. Here is an example:
-DELETE %F;
}
}
FTP commands
This section lists the FTP commands sent to the FTP server when the statement is executed (for a
local host, no commands are sent). Some statements do not generate FTP commands. For such
statements, the section is not present.
A parameter can have the following elements:
l A string surrounded by double quotes (for example, "double-quoted string").
l Names of environment variables preceded by a $ character (local host only).
l Names of script variables preceded by a % character.
APPEND
Append local file to file on FTP server.
l Example:
CD
Change the current directory on the FTP server.
l Example:
DEBUG
Log a partial FTP session in the message log.
l Syntax – DEBUG;
l Description – If a DEBUG statement is executed during execution of a script, Debug is turned
on. By default, Debug is turned off. A receive script normally receives one or more messages. A
send script normally sends a single message. Interchange logs a session record in the message
log under the following conditions.
Condition Session record contains
Send or receive script The entire FTP session.
terminates (with
errors) with Debug on
or off.
Send script completes The entire FTP session.
(no errors) with
Debug on.
Receive script The entire FTP session up to the command that received the given
completes (no errors) message. If the FTP session continued, which is the normal case,
with Debug on. the last line in the session record consists of three periods (...).
Statements (and the generated FTP commands) executed after the
last statement that receives a message are not contained in any
session record.
In all cases for a remote host, the details logged include:
o The FTP statements executed
o The FTP commands sent by Interchange
o The replies sent by the remote host
DELETE
Delete a file on the FTP server.
l Syntax – DELETE filename;
l Description – The DELETE statement deletes the file filename on the FTP server. The
filename parameter can be an absolute or relative path. The format of the path is system
dependent.
l FTP commands
DELE <sp> filename <crlf>
l Example:
GET
Copy a file from the FTP server without processing by an activity.
l Syntax – GET remotefile TO localfile;
l Description – The GET statement copies the remote file remotefile to the local file
localfile. If the file localfile exists, it is overwritten.
The remotefile parameter can be an absolute or relative path. The format of the path is
system dependent.
The localfile parameter must be an absolute path. The format of the path is system
dependent.
The main difference between this statement and the RECV statement is that a file copied using
the GET statement is not processed by the activity of which the method that contains the script is
part.
l FTP commands
PORT <sp> host-port <crlf>
RETR <sp> remotefile <crlf>
l Example:
IF ELSE
Conditional execution.
Expression The expression is true if variable
variable = value Is equal to value.
variable <> value Is different from value.
variable < value Is less than value.
variable <= value Is less than or equal to value.
variable > value Is greater than value.
variable >= value Is greater than or equal to value.
variable IN list Matches an exact value or is within a range of values in list.
variable NOT IN list Is not in list.
The comparisons are string comparisons. The precise meaning of <, <=, >, and >= depends on
the character set used by your operating system.
l Lists
A list is a combination of exact values and/or range(s) of values separated by commas.
A range of values is specified as a pair of values (each in double quotes), and the two values are
separated by a minus sign, for example, "tcp006"-"tdz209".
When a variable is compared to a range of values, the comparison is true if the variable is greater
than or equal to the first value and less than or equal to the second value.
Consider the range "val001"-"val100". The value "val010.tmp" is in this range because
"val010.tmp" is greater than "val001" and less than "val100".
Consider the range "val001.dat"-"val100.dat". All values from "val001.dau", "val001.dav",
"val001.daw", "val001.dax" … "val001.dba", "val001.dbb" …"val099.zzy", "val099.zzz" etc. to
"val100.das" are in the range.
l Example
-RECV %FILE;
IF (%FTPSTATUS IN "200"-"299") {
DELETE %FILE;
}
LIST
Read the contents of a directory on the FTP server.
l Example 1
l Example 2
DEBUG;
TYPE "I";
CD "IB/data/ftp/in";
%Count = "";
# Receive at most four files.
-LIST "." INTO %F {
%Count =%Count"x";
IF (%Count = "xxxxx") {
QUIT;
}
-RECV %F;
IF (%FTPSTATUS IN "200"-"299") {
DELETE %F;
}
}
Local Command
Execute a command at the local site.
l Syntax – ! command;
l Description – The local Command statement executes a command at the local site. The
command, enclosed as a string, is preceded by a ! character. The result of the command is
available in the %EXEC reserved variable. If the result is nonzero, the script terminates, unless
the statement is preceded by the “-” qualifier. The command is executed using the sh shell on
UNIX and the command shell on Windows.
l Example
On Windows systems, running a .bat or .cmd file using a Local Command statement fails with
exit code 255. This is due to Windows problems with redirection of output. The workaround is
to run a Message Builder program using r4edi. Here is an example. Write the following program
filecopy.s4:
The program simply copies a file. Compile the program. You can now copy a file using the
following Local Command statement:
The statement returns 0 if it succeeds and 1 if it fails.
MKDIR
Create a directory on the FTP server.
l Syntax – MKDIR remotedirectory;
l Description – The MKDIR statement creates a directory on the FTP server.
The remotedirectory parameter can be an absolute or relative path. The format of the path is
system dependent.
l FTP commands
MKD <sp> directory <crlf>
l Example
MKDIR "files";
PUT
Copy a local file to the FTP server.
If the value of the store-unique setting is off:
PORT <sp> host-port <crlf>
STOR <sp> remotefile <crlf>
If value of the store-unique setting is on:
PORT <sp> host-port <crlf>
STOU <sp> remotefile <crlf>
For details of the store-unique setting, see SUNIQUE on page 883.
l Example
QUIT
Stop the script.
l Syntax – QUIT;
l Description – The QUIT statement stops the execution of the script without error.
QUOTE
Send an FTP command.
l Syntax – QUOTE "command";
l Description – The QUOTE statement sends an FTP command to the FTP server. Normally, you
would only send a command that is not supported by the script language. The command
parameter is an FTP command.
l FTP commands
command <crlf>
l Example
RECV
Receive a file from the FTP server.
l Syntax – RECV remotefile;
l Description – The RECV statement receives a file remotefile from the FTP server.
The remotefile parameter can be an absolute or relative path. The format of the path is
system dependent.
If the statement completes (that is, a file has been received), Interchange processes the message
contained in the file as defined by the receive activity of which the method that contains the
script is part.
l FTP commands
PORT <sp> host-port <crlf>
TYPE "I";
RECV "file.dat";
RENAME
Rename a file on the FTP server.
The file parameter can be an absolute or relative path. The format of the path is system
dependent.
The newfile parameter can be an absolute or relative path. The format of the path is system
dependent.
The RENAME statement is often used in conjunction with the SEND or PUT statements to make
sure that a file is not accessed until the transfer is complete.
l FTP commands
RNFR <sp> file <crlf>
RNTO <sp> newfile <crlf>
l Example
SEND "file.tmp";
RENAME "file.tmp" TO "file.dat";
RMDIR
Remove a directory on the FTP server.
l Syntax – RMDIR directory;
l Description – The RMDIR statement removes a directory on the FTP server.
The directory parameter can be an absolute or relative path. The format of the path is system
dependent.
l FTP commands
RMD <sp> directory <crlf>
l Example
RMDIR "files";
SEND
Send a file to the FTP server.
If the value of the store-unique setting is off:
PORT <sp> host-port <crlf>
STOR <sp> file <crlf>
If value of the store-unique setting is on:
PORT <sp> host-port <crlf>
STOU <sp> remotefile <crlf>
If the APPEND keyword is specified:
PORT <sp> host-port <crlf>
APPE <sp> remotefile <crlf>
For details of the store-unique setting, see SUNIQUE on page 883.
l Example
TYPE "I";
SEND "file.dat";
SUNIQUE
Toggle the value of the store-unique setting.
l Syntax – SUNIQUE;
l Description – The SUNIQUE statement toggles the value of the store-unique setting. It is useful
for file transfers using the PUT or SEND statements:
If the value of the store-unique setting is on, and the file exists on the FTP server, the transferred
file is given a unique name. Unfortunately, Interchange cannot tell if a unique name has been
used or what that name is (this is due to a limitation of FTP), so a RENAME statement may fail
when used with the SEND or PUT statements.
If value of the store-unique setting is off, and the file exists on the FTP server, the file is
overwritten.
When a script starts, the initial value of the store-unique setting is off.
l Example
SUNIQUE;
SEND "file.dat";
TYPE
Set the representation type for data transfers.
l Syntax – TYPE type;
l Description – The TYPE statement sets the representation type for data transfers. The type
parameter takes one of the following values.
Value Description
"I" Binary files
"A" ASCII files
"E" EBCDIC files. The representation type used corresponds to Code page 500
(International Latin 1), which is the code page used on the AS/400 platform.
l FTP commands
TYPE <sp> type <crlf>
l Example
TYPE "I";
SEND "FILE";
WHILE
Loop control.
l Syntax – WHILE (expression) {statements}
l Description – The WHILE statement executes the statements in statements if the expression is
true. If false, the statements are not executed. See IF ELSE on page 876 for a full description of
the expression parameter.
l Example
TYPE "I";
%Break = "";
# Every time we find files check the directory one more time.
WHILE (%Break = "") {
%Break = "BREAK";
-LIST "." INTO %F {
-RECV %F;
IF (%FTPSTATUS IN "200"-"299") {
-DELETE %F;
}
%Break = "";
}
}
You can perform test trading using the QuickStart partner, which is a file you can download from
Axway Sphere. You can perform test trading with a trading partner, or if you have a support
contract, with the Axway QS test server.
The Axway QS test server provides you with a correctly configured trading partner. By using it you
can validate your community and communications against a thoroughly tested system.
Follow the instructions below to obtain and use the Quickstart partner file. You must have
permission to log on to Interchange and to create a new partner.
1. Log in to Sphere at support.axway.com.
2. Search for quickstart or utility and download the Interchange_5.12.0_Utility*.zip
file. Note that the asterisk represents the build number of the file.
3. Extract the XML file and place it on your local system.
4. Through the Interchange UI, create a new partner and upload the XML file.
The following procedure explains how to configure Interchange to exchange test documents with
Axway. To trade with a partner, see Configure for test trading on page 886.
To trade with the Axway test server:
1. Import the QS partner to your Interchange test environment.
2. Create a community.
3. Export your community profile as a partner profile.
4. Zip the profile to protect it.
5. Open a support case with Axway, attaching the exported partner profile and requesting that the
zipped partner profile be imported into QS.
QS test server limitations:
You are not permitted to do stress testing, or to send extremely large files (multi-Gigabyte), except
on a pre-arranged basis.
See also Document generator on page 97.
1. Complete your test community. See Add a community on page 136.
If you want to test trade with Axway, you can configure the community to receive messages
using any of the supported pickup exchanges. If you need guidance on which transport
method to use, contact technical support. For information about transport options see Add a
trading pickup on page 261.
If you want to test with a trading partner, you and your partner should decide which transport
method to use. Then set up the community to receive messages via the appropriate transport
method. For simplicity, we suggest both of you at first use the same transport method to
receive and send messages.
Also for simplicity, unless you have other integration plans, have the community use file system
integration to pick up outbound messages and send inbound messages to the back end. See
File system transport configuration on page 189.
2. Generate a test self-signed certificate for your test community.
3. Export your community profile as a partner profile. You can send this file to your testing partner
as an attachment to an e-mail. If you send your profile by FTP, make sure to use a binary
transfer.
If you want to test with Axway, send the e-mail to the address Axway provides you. Type
Request for Quickstart Test in the subject line of your e-mail.
If you send the profile file as an e-mail attachment, we suggest using a utility such as WinZip to
compress the file before sending. This is to protect the file from possible corruption during
transmission. Some SMTP servers append verbiage to e-mail attachments, which can harm the
profile file.
4. Obtain your partner’s profile.
If you want to test with Axway, import the Quickstart partner profile file. This file is at
<install directory>\profiles\staged\partner.
If you want to test with a trading partner, have the partner send the profile file to you by e-mail
or another method. Then import the profile. If the partner also uses Interchange, the profile file
should include the partner’s public key and certificate.
If the partner uses other interoperable software, create the profile in Interchange using
information supplied by your partner. The partner also must send the certificate and public key
in a file.
For more information see:
l Add a partner on page 143
l Import a partner on page 858
l Import certificates for partners on page 798
5. In the partner object, select a default transport for sending test documents. If there is only one
transport, that is the default.
If you imported the Quickstart profile, select the delivery exchange you want to use for sending
messages to Axway. On the Quickstart partner summary page, click Partner delivery on the
navigation graphic to display a page that lists the available transports for sending. Use the up
and down arrow keys to move the desired transport to the top of the list. The transport at the
top of the list is the default method.
If testing with a partner and there is more than one transport for sending, you and your partner
should decide which one to use. Then select the appropriate transport to use as the default for
sending.
6. Contact Axway or your trading partner to confirm test arrangements.
You can use your own documents or you can use the Document Generator utility to generate EDI or
XML documents of any size and at any rate. See Document generator on page 97 for how to create
test documents.
1. Start the Server application and log on.
2. To follow trading activity, go to the Message Tracker area of the user interface. For information
about this feature see Message Tracker on page 826.
3. If you are using file system integration, place one test EDI document in the community
outbound integration directory. If you are using another integration method, Interchange must
be able to retrieve the document through that delivery exchange.
Interchange processes these documents and sends them to Axway or your trading partner. Look
at Message Tracker for notification that a message has been sent. Upon receiving the message,
the partner should send a receipt to your community.
If you are using file system integration, Interchange writes the inbound document to the
community integration delivery exchange.
4. After sending and receiving some EDI documents, try trading some XML or binary documents.
l Determine whether it is a sending or receiving problem.
If a sending problem, is Interchange correctly connected to the SMTP server?
If a receiving problem, is Interchange correctly connected to the POP server?
l Check your email account by sending a message from another email account to the community
email account for receiving messages.
l Is your connection to the Internet functioning correctly?
l Determine whether the problem is related to encryption or decryption. If encryption related, can
you verify whether the mail server is S/MIME compliant?
l Determine whether the problem is related to a trading partner’s profile settings.
l Does your organization’s network infrastructure allow email attachments?
l Any changes you made to your system.
l Any customization of Interchange that you did and how to recreate it, if necessary.
l If you encountered problems, any details that might help someone diagnose and correct similar
problems in the future.
Also, delete the Quickstart partner if you tested with Axway.
l Delivery settings on page 889
l Message Simulator on page 890
l Uniqueness in Interchange on page 891
l Message handler on page 892
l Configure error processing on page 904
l Message backup configuration on page 849
l Post-processing configuration on page 905
l Collaboration settings on page 909
l Inbound message validation rules on page 939
l Message metadata and attributes on page 412
l Sequential message delivery on page 947
l Embedded transport servers on page 431
l Use generic MMDs on page 954
l Test trading on page 885
l Document generator on page 97
l AS1 / AS2 partner self-registration on page 497
l ebXML partner self-registration on page 576
Delivery settings
Use the Application delivery settings page to manage the settings that control how Interchange
routes messages after they are consumed by a community trading pickup.
To open the Delivery settings page, open a community Summary page and in the navigation
graphic, click the Delivery settings icon.
You can add as many application deliveries as you want, but only the first (top) application delivery
in the list is used as the default delivery.
If you add more than one application delivery to the delivery settings list, you can use the up and
down arrows to arrange the application deliveries in an ordered list.
Use this page to define the conditions that cause payloads to be delivered to the appropriate
application delivery. If a payload does not satisfy the delivery criteria for any application delivery,
then the first available application delivery is used. An application delivery with no criteria is used
only if it is the first one available.
Message Simulator
Use the Message Simulator to test whether messages are routed through the correct application
delivery. The simulator lets you pretend a community has received a message from a partner via a
particular message protocol. Click Run test to see which delivery the community uses to send the
“message” to an application.
If you have configured delivery criteria for an application delivery, the simulator enables you to test
the configuration. For information about delivery criteria, see Message attributes tab on page 206
and Delivery settings on page 889.
Before using Message Simulator, you need at least one community and one integration delivery for
the community. You do not have to add an exchange for the community to receive messages from
partners to use the simulator.
Message Simulator configuration page:
Message Simulator field descriptions:
Uniqueness in Interchange
In order to process message flows in a coherent and predictable manner, Interchange enforces the
uniqueness of object names.
As a general rule, each object that you create in the Interchange interface must have a unique name.
Object creation: If you try to create an object with a name that already exists, Interchange displays
a message informing you of the naming conflict and instructing you to enter a unique name.
Object importing: If you import an object or set of objects with a name that is already used in a
configuration, the importer executes one of the following actions to insure uniqueness:
l ignore - ignores the imported object and conserves the existing object
l replace - replaces the existing object with the imported version of the object
l update - modifies the existing object by adding, deleting or revaluing attributes from the
imported object
Upgrades: If you upgrade from a previous version, the upgrade logic never deletes previous data.
When the upgrade logic detects or must generate a potentially duplicated object, it automatically
renames the duplicates with unique names. In some cases it may also have to disable the renamed
object to conserve the functional uniqueness of the configuration.
Message handler
The message handler provides optional processing of inbound or outbound messages based on
metadata attributes and actions. Interchange enables you to set up conditions to:
l Copy messages to other than the sending or receiving party
l Re-route messages from one partner to another
l Prohibit re-routing of messages
l Reject messages
l Perform custom processing using your own Java class
l Rename the production file
l Select a message attributes template to apply to associate with the message
l Transform record formats
Message handling involves performing message actions. Message actions are triggered by single or
multiple conditions, which are a combination of attributes and operators. For example, you can
order that whenever a community sends message to partner A, a copy is sent to partner B.
Message actions can be applied to inbound and outbound messages. For inbound messages,
message actions are applied after a message has been validated, unpackaged and parsed, but before
the payload is delivered to a back-end application. For outbound messages, message actions are
applied after a message has been consumed from the originating source, but before it has been
packaged.
l Define message attributes on page 893 – Complete this step if you want to use attributes that are
not the default attributes.
l Define conditions on page 894 – Select an attribute and assign a value to the attribute to set up
a condition for triggering a message action.
For example, you can have the system parse certain XML messages for values of an attribute named
POAmount. Or, you can instruct the system to apply an attribute named SupplyChain with a fixed
value of Retail to certain messages.
You can define attributes to be active only when certain conditions occur. This lets you customize
attributes to a high degree of specificity.
Defining attributes is optional. Attributes you define are in addition to default attributes. The
following are the names of default attributes d isplayed in the user interface. These are not the
internal technical names.
l Document class – The document class of the message payload (for example, X12, XML).
l Content MIME type – The MIME type of the message payload. The following are commonly
used types.
application/EDI-consent Tradacoms messages
application/EDIFACT EDIFACT messages
application/EDI-X12 X12 messages
application/octet-stream Binary messages
application/xml XML messages
For information about other MIME types see:
http://www.mhonarc.org/~ehood/MIME/MIME.html.
l Document type – For EDI documents this is the business document type, such as 894
(invoice) or 850 (purchase order). For XML documents, the document type has to be parsed
from the document.
l Business protocol – The message protocol for transporting the message. For example, AS1,
AS2, AS3, ebXML.
l EDI control ID – For EDI documents, the control ID.
l Is receipt – A boolean indicating whether the message is a receipt acknowledging a message
has been received. Receipts can trigger message actions unless you set up a condition excluding
them. (Note that inbound receipts are processed before reaching the message handler. So Is
Receipt is applicable as a message action only for outbound receipts.)
l Virtual file user data – A text field that can be set to any arbitrary valid OFTP string value.
This attribute provides a way for two endpoints connecting via OFTP to communicate
commands, status or other information outside of the protocol specification. The attribute
corresponds to the protocol element SFIDUSER sent or received during exchanges. The value is
limited to 8 bytes of ASCII text whose semantic is up to the conversing OFTP user applications.
Define conditions
From the pool of available attributes, you select an attribute and also an operator and a value. This
serves as the trigger of the action. For example, you could specify that an action triggers when:
You also can set up an action that compares the value of one attribute to the value of another
attribute. For example, suppose you want to reject inbound messages when the sender ID parsed
from the payload is not the same as the sender ID in the message protocol envelope. To do this, you
could create an attribute named ParsedSenderId whose value is parsed from XML documents.
Then you would set up an action to reject messages that meet the following two conditions. Note
that the Is Receipt condition is needed to make sure the action applies only to inbound messages,
but not outbound receipts.
2. AND
Is Receipt = false
You can set up multiple conditions, all of which must be met for an action to trigger.
The following defines operators. Not all of these are available for all attributes.
l Exists – The operator tests whether an attribute has any value at all.
l Doesn't exist – The operator tests whether an attribute has no value at all.
l Equals – The operator tests whether an attribute has a *specific* value. (Meaning that it both
exists and has that specific value.)
l Not Equal – The operator tests whether an attribute does not match a specific value, meaning
that it exists but not with that specific value.
l Starts with – The operator tests whether an attribute begins with the specified value. This can
be used in wildcard searches. For example, match any string beginning with foo.
l Ends with – The operator tests whether an attribute ends with the specified value. This can be
used in wildcard searches. For example, find any string ending with foo.
l Contains – The operator tests whether an attribute contains the specified value. This can be
used in wildcard searches. For example, match any string containing foo.
Note The operators starts with, ends with and contains are available only with these
attributes: Consumption file name and Production file name.
In addition to equals and not equal, there are the following related operators whose purpose is
self explanatory: greater than, less than, greater than or equal and less than or equal.
There are a number of default attributes. For descriptions of the default attributes see the list under
Define message attributes on page 893.
1. Click the Processing icon on the navigation graphic at the top of the community summary
page to open the Processing Configuration page.
By default, message actions apply to all messages, including messages containing payloads or
receipts. To exclude receipts from a message action, add a condition that sets Is Receipt to false.
Use the up and down arrows in the user interface to set the order for executing actions.
processing pipeline. The custom processing logic, implemented as a user-defined Java class, can
be selectively applied at runtime to inbound or outbound messages as determined by message
actions. Use of this feature requires obtaining an optional developer’s license.
l Rename the production file – Enables you to change the original file name of a message to a
name generated according to a format you specify. In the outbound case, the name is changed
after the message is picked up from integration but before it is sent to a partner. In the inbound
case, the name is changed after the message is received from a partner but before it is sent to the
delivery exchange. Message Tracker reports both the original and delivery file names.
You must construct a valid pattern for the new file names. The correct format consists of one or
more optional text strings and delimited substitution variables in any order. Use of underscores
to separate variables or as character separators within variables is optional. The following is an
example of a valid file pattern:
ProductionFilename%SenderRoutingId%_%ReceiverRoutingId%_$dd_MM_yyyy_hh_
mm_ss$
Do not specify a file name or a date containing any of the following characters: \ / < > ? * : " |
When specifying a date format, use upper-case MM for months and lower-case mm for minutes.
The year format can be yyyy or yy. For the time format, you can use underscores to separate
hours, minutes and seconds.
For details on how to enter a renaming pattern, see File renaming patterns on page 253.
Note: If you rename files transported via OFTP, Interchange can apply names no longer
than 26 characters in accord with the message protocol’s limit on file name length. See
Work-around for OFTP file name length limit on page 612.
l Original format – Specify the format of the source file. The parameters you set are used
instead of the message's local file format attributes. To use the values from the message's local
file format attributes, use these parameters:
o File format – From the drop-down list select a file format option:
o Record length
o Record padding character – Enter 00.
o Character set – Leave blank.
l Target format – The format of the destination file. The formatting information must be
identified on this screen. The message's virtual file record format attributes are ignored.
Message re-routing
Interchange can act as the hub of a hub-and-spoke network to re-route messages. In a hub-and-
spoke architecture, the hub (Interchange) mediates messages exchanged between trading partners.
In such a network, the spoke partners send messages only to Interchange. Interchange then re-
routes messages to the intended receiving partners. This arrangement simplifies the technical
requirements for the spokes, which need to define only a single partner (the hub) for exchanges
with multiple partners.
When Interchange receives a message and determines that the intended recipient is a spoke partner
(and not Interchange), Interchange repackages the message and sends it to the true receiver.
All re-routing takes place within Interchange. Re-routed messages are not shuttled to an inbound
application delivery before being sent on to the true receiver. For this reason, inbound messages
that are re-routed cannot be post-processed in delivery exchanges. Instead, you configure post
processing for outbound re-routed messages. For information about configuring post-processing
through a delivery exchange, see Post-processing configuration on page 905.
The following figure illustrates how re-routing occurs. Partner A sends a message to the hub, but the
true receiver is Partner B. Upon receiving the message, the hub sends a receipt to Partner A and
determines Partner B is the true receiver. The hub then sends the message to Partner B, which sends
a receipt to the hub.
Prerequisites to re-routing
Before setting up re-routing in Interchange, administrators must perform the following tasks:
1. Distribute the hub's community profile as a partner to all of the spoke partners. For secure
trading you must include the community public key certificate. See Add a community on page
136.
2. In the Interchange configuration, set up a partner for each spoke partner. For secure trading
each partner must have a public key certificate. Depending on whether the partner uses Axway
software or an interoperable third-party trading engine, partners can be imported from files or
added manually. See Partners on page 142.
3. Make sure re-routing is enabled for the community. To do this:
Click Trading partners on the navigation graphic at the top of the community summary page.
Select Allow messages to be re-routed.
4. If necessary, advise the spoke partners to configure their trading engines to send messages to
the hub, with other spoke partners as the end recipients of messages.
5. Determine the types of messages to be re-routed. Although Interchange hub can re-route all
document types (EDI, XML and binary), determining type can help in knowing how the system
determines senders and receivers.
6. Determine the re-routing method to use and configure Interchange accordingly:
Re-routing configurations
There are several ways to configure Interchange to act as a hub in re-routing messages.
To do this you work in the Message Handler to set up a re-routing message action that is based on a
message metadata trigger. For details see Set up message-processing actions on page 893.
Notes:
l Message handler re-routing overrides this method.
l This method does not work with No Packaging or PGP deliveries. If your configuration includes
either of these, set up message actions that trigger message re-routing following the instructions
in Set up message-processing actions on page 893.
When the hub community and spoke partners are configured correctly on the hub trading engine,
the system can perform re-routing with little configuration. However, you must make sure re-routing
is enabled for your community. To do this:
l If the spoke partner uses Interchange 5.0.2 or later, EDI and XML documents can be re-routed
through the hub, but not binary documents. Instead of parsing for the receiver when the
partner's system picks up documents from integration, the partner can use a static receiver to
send messages to the hub.
l If a spoke partner uses Interchange, the partner imports the hub's profile as a partner and then
adds other spoke partner's IDs as secondary IDs in the hub profile.
Upon receiving a message from a partner, Interchange unpacks it as usual and determines the
sender and receiver. It does so in a number of ways:
l Interchange (without additional From/To parsing or fixed metadata options), parses for true
sender and true receiver headers in the top-most MIME header of inbound messages. The true
sender is the spoke partner that originated the message. The true receiver is the spoke partner
that is the intended end recipient. These headers are in the following format:
X-Cyclone-True-Receiver: <routing ID>
X-Cyclone-True-Sender: <routing ID>
l Interchange (without additional From/To parsing or fixed metadata options) parses for a subject
header in the top-most MIME header of inbound messages. The subject header identifies the IDs
of the true sender and the true receiver. The header is in the following format:
Subject: true-receiver ID [; true-sender ID]
The true receiver ID is required and the true sender ID is optional.
A spoke partner who uses an email client application to send messages to the hub can add the
true sender and true receiver IDs in the subject line of email messages.
l For any protocol.
l On any type of flow: inbound, outbound, and for exchanges with both back-end or trading
partner endpoints.
For records transformations that you configure in message handler, Interchange reads the original
file containing the records on the hard drive, writes the transformed copy to the hard drive.
Limitation: You can perform only one record transformation on a message. If more than one
record transformation is available, only the first transformation of the list of available record
transformation is executed.
This topic describes only the records transformations that you can configure in message handler.
For a complete list of message handler actions, see Define message actions on page 897.
Configuration
1. Click Processing configuration on the menu bar to open the Processing configuration
page.
2. In the processing graphic at the top of the page, click the Message handler icon, to open the
Message handler page.
This feature does not automatically provide for error processing based on the reason for the
message rejection. To apply message filtering based on the message rejection reason or time, you
must add filtering to the inline processors or to the script that you apply.
If you have set an error processor through the Configure error processor page, Interchange:
l Adds the metadata PreviousState to the rejected message. It sets the value of this metadata to
the name of the previous message state. This enables you to know what the state of message
processing was immediately before rejection.
l Records the reason for rejection in the metadata RejectedReason.
l Calls any inline processing rules that you have defined, in the order they are listed.
l Calls a post-processing script if you have defined one.
o Parameter – If there are any parameters required for implementing the Java class, enter
them here.
l Execute a processing script – Select this option if you want to apply a processing script
to rejected messages, then specify the script:
o Processing script – The name of the post-processing script.
4. Click Save.
Post-processing configuration
You can perform post-processing commands on each inbound message immediately after
Interchange has consumed, processed and written it to an application delivery. You also can
execute post-processing commands after sending messages to partners. Interchange can initiate any
executable or batch file or script you specify. The batch file or script is applied to all messages
passed through the exchange that calls it. Batch files or scripts can be used with several or all
application deliveries or partner deliveries, but they must be called separately. You cannot specify a
global batch file or script.
The post-processing script must be on a drive that Interchange can access and has permission to
execute.
There are two places in the user interface where you can enter the name of a post-processing script.
l On a community summary page: Click Application delivery on the navigation graphic at the
top of the page. Then click the name of an application delivery to open the maintenance page.
Click the Advanced tab. Type the path for the script file in the post-processing script field. Click
Save changes.
l On a partner summary page, click Partner delivery on the navigation graphic at the top of the
page. Then click the name of an outbound transport to open the maintenance page. Click the
Advanced tab. Type the path for the script file in the post-processing script field. Click Save
changes.
When entering the path for a post-processing script in the user interface, we recommend using a
relative path rather than an absolute path. Relative paths are preferred if you export partner profiles
files for back-up purposes or clone partner profiles in a peer network environment.
Interchange by default passes seven items of message metadata to the post process. Your script can
use any or all of them. An example of the syntax of a command that is executed against an inbound
message is:
Windows c:\directoryname\myfile.bat
UNIX /directoryname/myscript.sh
%1 $1 SenderRoutingId The routing ID of the sender of the message.
%2 $2 ReceiverRoutingId The routing ID of the receiver of the message.
%3 $3 ProductionUrl The path of the file if the message was written to
a File System integration delivery exchange.
Otherwise, it is the URL of the destination.
%4 $4 ProductionFilename The file name used when Interchange wrote the
file.
%5 $5 ConsumptionFilename The file name included in the MIME header,
probably the original file name from the sender,
if the message was EDIINT. Otherwise, the name
of the file as when retrieved from the file system
or FTP server.
%6 $6 EdiControlId The control ID of an EDI message. Otherwise,
the ID is XML or BINARY
%7 $7 DocumentClass The document class of the message payload (for
example, X12, XML).
If you are writing a post-processing script in Perl, you cannot use $ in the parameter number. You
must use $ARGV[n], where[n] is the argument number. For example, in the preceding table, the
parameter for SenderRoutingId is $1; for Perl it is $ARGV0 (notice counting starts at zero). Likewise,
the parameter for ReceiverRoutingId is $2, but $ARGV1 for Perl.
Add the metadata elements you want to shellscriptmetadata.xml in <install
directory>\conf. Follow the format as shown for the default elements already in the file. Pay
attention to the order in which the metadata elements are listed. This is important for the
corresponding parameter numbers.
After editing shellscriptmetadata.xml, restart Interchange server for the changes to become
effective. All post-processing script invocations are affected by changes to this file.
Operating Languages
system
Windows Compiled languages (for example, Java, Visual BASIC, C++, Delphi). Also,
.cmd and .bat files.
UNIX Any language. For example, shell script, Java, C or Perl.
@echo off
echo on
rem
rem Batch file to move file to directory based on received files
rem MIME type.
rem set the default destination directory to
rem c:\dest\binary\ReceiverRoutingId\SenderRoutingId.
rem Where ReceiverRoutingId is the Routing Id of the Receiving
Community,
rem and SenderRoutingId is the Sender Routing Id of the Sending Party.
rem If the MIME Type of the content is known, then override the
destination
rem directory
rem if '%7' == 'application/EDI-X12' set
destdir=\\win03.cyclonesoftware.com\haboob\x12
#!/bin/sh
# $Id: UNIXpostprocess.sh to test post-processing.
# This shell script does two things. It moves the received file
# to another directory. Then it appends into a log file all the
# information that CI makes available about that file.
mv "$3"/"$4" /home/cyclone/tmp
echo -----newfile info----- >> /home/cyclone/tmp/postprocess.log
date >> /home/cyclone/tmp/postprocess.log
echo The Sender Routing Id is "$1" >> /home/cyclone/tmp/postprocess.log
echo The Receiver Routing Id is "$2" >>
/home/cyclone/tmp/postprocess.log
echo The Production directory is "$3" >>
/home/cyclone/tmp/postprocess.log
echo The Production Filename is "$4" >>
/home/cyclone/tmp/postprocess.log
echo The Consumption Filename is "$5" >>
/home/cyclone/tmp/postprocess.log
echo The Control Id is "$6" >> /home/cyclone/tmp/postprocess.log
echo The Content MIME Type is "$7" >> /home/cyclone/tmp/postprocess.log
Post-processing events
Interchange generates the following events when performing post processing.
l Messaging_Transport_PostProcessing_Initiated – This event is published before the
script is invoked.
l Messaging_Transport_PostProcessing_Completed – This event is published after the
script has been invoked.
l Messaging_Transport_PostProcessing_Failure – This event is published if there was an
error invoking the script (for example, script not found).
Collaboration settings
Collaboration settings specify how Interchange packages the messages that a community sends
to its partners. You can use default collaboration settings which apply to all messages sent by all
communities to all partners, or you can customize collaboration settings at progressively more
specific levels.
You can specify collaboration settings that apply to messages sent:
l From all communities to all partners. These are the default collaboration settings for sending
messages.
See Manage default collaboration settings on page 910.
l From a specific community to any of the community's partners.
See Manage community-specific collaboration settings on page 931.
l From a specific community to a category (group) of partners. This is a Community-to-category
specific collaboration setting.
See Manage community-to-category collaboration settings on page 932.
l From a specific community to a single specific partner of the community. This is a Community-
to-partner specific collaboration setting.
See Manage community-to-partner specific collaboration settings on page 934.
l From a specific community to a specific partner of the community using a specific delivery. This
is a community-to-delivery specific collaboration setting.
See Manage community-to-partner delivery specific collaboration settings on page 937.
Collaboration settings only affect how messages are sent, not how they are received. To manage
rules for receiving messages, see Inbound message validation rules on page 939.
If you need to check the current collaboration settings between any combination of community and
partner, use the Show collaboration settings tool. For details, see Search and display collaboration
settings on page 910.
Viewing collaboration settings between parties is a way to check whether pickup and delivery
exchanges are properly set up. Although this does not rule out possible infrastructure or
configuration issues that could affect trading, it does help ensure that two parties’ security and
packaging preferences are correct for outbound payloads and receipts from partners.
Before checking collaboration settings between two parties, make sure your community and the
partner use the same type of message protocol and transport.
In addition, the partner’s transport must be the default exchange. This means the transport must be
identified as the default delivery on the Partner deliveries page. Interchange uses the default
protocol to send messages to partners. Click Partner delivery on the navigation graphic on the
partner summary page to check. The only exception is a transport for the ebXML message protocol.
It must be present, but does not have to be the default transport.
Settings for inbound messages are controlled on the message validation page in the user interface.
For more information see Inbound message validation rules on page 939.
1. On the main trading configuration page or a community summary page, click Show
collaboration settings to display the Collaboration settings page.
If you navigated from a community summary page, by default the page uses the current
community as the sender. You can use the default or change it.
2. Click Pick to select the community or partner sender (sent from) and the community or partner
receiver (sent to).
3. Click Show settings. The system searches for the collaboration settings. It checks for any
settings specific to the community or partner that override the default global settings. The page
refreshes with the settings for the sender and receiver.
In some cases, the system reports that a collaboration could not be created between the parties.
A common reason for failed collaboration is that the sender and receiver message protocols are
not the same (for example, not both AS2).
l Manage community-specific collaboration settings on page 931
l Manage community-to-category collaboration settings on page 932
l Manage community-to-partner specific collaboration settings on page 934
l Manage community-to-partner delivery specific collaboration settings on page 937
Depending on the message protocols your license supports, some of these collaboration settings
may not be displayed.
For the procedure for opening this page, see Manage default collaboration settings on page 910.
Recommendations: Make attribute names a single text string. For names that use multiple words,
do not use spaces between the words. Use camel case for names that include two or more words
(for example, AttributeName). Do not use non-alphanumeric characters in attribute names
(for example, commas, periods, hyphens, asterisks, ampersands and so on).
To add attributes to headers of outbound documents, use the Add button on this tab to move a
selected attribute from the available attributes list to the selected attributes list. Click Save
changes when done.
In addition to selecting metadata elements to include in headers, you must separately establish
the values for the attributes. There are several ways to do this, including:
o Message attributes tab – Use the message attributes tab on a transport maintenance
page to set attribute values by use of directory mapping or fixed values. For more
information see the message attributes tab topic in the transport maintenance chapter.
o Message handler – In the message handler area, you can set a fixed value for an attribute.
If the payload is an XML document, the value can be parsed by specifying an XPath. For
more information see the chapter on message handling.
o Inline processing – If you are a licensed SDK user, you can build a Java class and use it to
provide attribute values or perform other message actions.
Upon receiving and unpackaging a message with extra metadata, a partner who uses
Interchange 5.3.2 or later can use the added-metadata for post processing, inline processing or
file system integration. Inform the partner of the metadata elements you add to outbound
messages.
The added metadata in the header of the outbound document is in the following format:
X-Cyclone-Metadata-AttributeName: Value
the sender's original message session. If you trade messages larger than 10 megabytes, we
recommend sending receipts over an asynchronous connection to avoid tying up system
resources.
o Disposition notification URL – Type the URL for the partner to use when sending
asynchronous receipts to acknowledge receiving payloads from your community. You must
enter a URL if you request receipts over an asynchronous connection. The system does not
provide this value for you. Commonly, the URL to use is the URL used by partners for the
HTTP or HTTPS delivery exchange your community has for receiving messages from
partners. To get this value, click Application delivery on the navigation graphic at the top
of the community summary page to open the Application delivery exchanges page. Copy
the URL from the Location column for the desired transport. Return to the collaboration
settings page and paste the URL in the Disposition notification URL field. Instead of an HTTP
or HTTPS URL, you can use an email address for an inbound SMTP delivery exchange, but it
must be in URL format. For example, mailto:community@mail.com.
o Request signed receipts – Select this option to have your partners sign the receipts they
send you.
o Receipt signing algorithm – This is the algorithm you want partners’ trading engines to
use when creating a hash of the unencrypted receipt. This hash is a number that is encrypted
with the partner’s private key. It is decrypted by the community using the partner’s public
key. The community rehashes the decrypted receipt and compares the result with the hash
that came with the receipt. If the two are identical, it ensures the contents have not been
altered.
l Message compression – Select a method for compressing the messages you send. This is
optional. Compressing data before sending increases throughput. You might want to consult
with your partner about compressing and uncompressing as pre- and post-processing steps. You
and your partner can compress or not independently, as long as the receiver’s system supports
uncompressing.
The compression options are:
o None – Select this if you do not want compression. Also, you must select this to exchange
messages with partners whose interoperable software cannot uncompress documents.
o EDIINT/ZLIB – Select to trade with partners who use version 4.2 or later of Interchange or
who use an EDIINT-compliant trading engine other than Interchange.
o MIME/GZIP – Select to trade with partners who use versions of Interchange earlier than
4.2. You also can select this if your partner uses a trading engine other than Interchange that
supports GZIP compression.
l Encrypt messages – Select this option to encrypt the messages you send.
o Message encryption algorithm – If you select encrypt messages, select an algorithm.
l Sign messages. Partners use your certificate to verify you as the sender – Select this
option to digitally sign the messages you send.
o Message signing algorithm – The algorithm for creating a hash of the unencrypted
message. This hash is a number that is encrypted with your community’s private key. It is
decrypted by the partner using the community’s public key. The partner rehashes the
decrypted message and compares the result with the hash that came with the message. If the
two are identical, it ensures the contents have not been altered.
o When receiving messages, return asynchronous receipts to the first enabled
AS2 delivery exchange for the partner instead of the disposition notification
URL from the message – Select this option to override the disposition notification URL for
receipts that your partner set in the message your community received. When selected, the
partner’s disposition notification URL in the MIME header of the inbound message is ignored,
and your community sends the receipt via the first enabled AS2 delivery listed for the
partner.
l Specify message attributes to be packaged with message – This option is available only
if your software license supports allowCustomMetadataInMessageHeaders. Select Help >
License information in the user interface to check whether this license key is enabled.
Checking this enables you to include any metadata elements you want in the MIME headers of
the messages your community sends. This can serve several purposes. It lets your community
forward payload-related information to a partner. It also lets a community or partner use such
data to trigger message handling actions.
The metadata that can be added are in addition to the metadata already in MIME headers, such
as sender and receiver, content type, disposition notification and so on. There are several ways
to add metadata elements to the available attributes list on this tab. You can type an attribute
name in the field below the available attributes list and click Add new. Or, you can go to the
message handler area of the user interface and add an attribute (see the chapter on message
handling). Any attributes added in the message handler area appear on the available attributes
list on this tab.
We recommend these guidelines for attribute names: Make attribute names a single text string.
For names that use multiple words, do not use spaces between the words. Use camel case for
names that include two or more words (for example, AttributeName). Do not use non-
alphanumeric characters in attribute names (for example, commas, periods, hyphens, asterisks,
ampersands and so on).
To add attributes to headers of outbound documents, use the Add button on this tab to move a
selected attribute from the available attributes list to the selected attributes list. Click Save
changes when done.
In addition to selecting metadata elements to include in headers, you must separately establish
the values for the attributes. There are several ways to do this, including:
o Message attributes tab – Use the message attributes tab on a transport maintenance
page to set attribute values by use of directory mapping or fixed values. For more
information see the message attributes tab topic in the transport maintenance chapter.
o Message handler – In the message handler area, you can set a fixed value for an attribute.
If the payload is an XML document, the value can be parsed by specifying an XPath. For
more information see the chapter on message handling.
o Inline processing – If you are a licensed SDK user, you can build a Java class and use it to
provide attribute values or perform other message actions.
Upon receiving and unpackaging a message with extra metadata, a partner who uses
Interchange 5.3.2 or later can use the added-metadata for post processing, inline processing
or file system integration. Inform the partner of the metadata elements you add to outbound
messages.
The added metadata in the header of the outbound document is in the following format:
X-Cyclone-Metadata-AttributeName: Value
l Sign messages. Partners use your certificate to verify you as the sender – Select this
option to digitally sign the messages you send.
o Message signing algorithm – The algorithm for creating a hash of the unencrypted
message. This hash is a number that is encrypted with your community’s private key. It is
decrypted by the partner using the community’s public key. The partner rehashes the
decrypted message and compares the result with the hash that came with the message. If the
two are identical, it ensures the contents have not been altered.
l Specify message attributes to be packaged with message – This option is available only
if your software license supports allowCustomMetadataInMessageHeaders. Select Help >
License information in the user interface to check whether this license key is enabled.
Checking this enables you to include any metadata elements you want in the MIME headers of
the messages your community sends. This can serve several purposes. It lets your community
forward payload-related information to a partner. It also lets a community or partner use such
data to trigger message handling actions.
The metadata that can be added are in addition to the metadata already in MIME headers, such
as sender and receiver, content type, disposition notification and so on. There are several ways
to add metadata elements to the available attributes list on this tab. You can type an attribute
name in the field below the available attributes list and click Add new. Or, you can go to the
message handler area of the user interface and add an attribute (see the chapter on message
handling). Any attributes added in the message handler area appear on the available attributes
list on this tab.
We recommend these guidelines for attribute names: Make attribute names a single text string.
For names that use multiple words, do not use spaces between the words. Use camel case for
names that include two or more words (for example, AttributeName). Do not use non-
alphanumeric characters in attribute names (for example, commas, periods, hyphens, asterisks,
ampersands and so on).
To add attributes to headers of outbound documents, use the Add button on this tab to move a
selected attribute from the available attributes list to the selected attributes list. Click Save
changes when done.
In addition to selecting metadata elements to include in headers, you must separately establish
the values for the attributes. There are several ways to do this, including:
o Message attributes tab – Use the message attributes tab on a transport maintenance
page to set attribute values by use of directory mapping or fixed values. For more
information see the message attributes tab topic in the transport maintenance chapter.
o Message handler – In the message handler area, you can set a fixed value for an attribute.
If the payload is an XML document, the value can be parsed by specifying an XPath. For
more information see the chapter on message handling.
o Inline processing – If you are a licensed SDK user, you can build a Java class and use it to
provide attribute values or perform other message actions.
Upon receiving and unpackaging a message with extra metadata, a partner who uses
Interchange (any version) or Interchange 5.3.2 or later can use the added-metadata for post
processing, inline processing or file system integration. Inform the partner of the metadata
elements you add to outbound messages.
The added metadata in the header of the outbound document is in the following format:
X-Cyclone-Metadata-AttributeName: Value
When you select this option, you can also select the following options:
o Xpaths to encode – Click Add to specify one or more xPaths
o ID refs to encode – Click Add to specify one or more ID refs
l Use username token when sending – Select this option to enable the embedding of user
name tokens within the message. When you select this option you must provide a user name and
password. The user name must be the name of an AS4 account that you create on an AS4
pickup. The user name and password information you use must be shared with the remote
partner you are trading with and the remote partner must use identical authentication
information, or message pull request will fail. For information on creating AS4 user accounts, see
Modify an AS4 embedded pickup / Accounts tab on page 540.
o Use password digest in place of plain text during authentication (optional)
o User name and password (required)
l Specify message attributes to be packaged with message – This option is available only
if your software license supports allowCustomMetadataInMessageHeaders. Select Help >
License information in the user interface to check whether this license key is enabled.
When you select this option, you can include any metadata elements you want in the MIME
headers of the messages your community sends. This can serve several purposes. It lets your
community forward payload-related information to a partner. It also lets a community or partner
use such data to trigger message handling actions.
The metadata that can be added are in addition to the metadata already in MIME headers, such
as sender and receiver, content type, disposition notification and so on. There are several ways
to add metadata elements to the available attributes list on this tab. You can type an attribute
name in the field below the available attributes list and click Add new. Or, you can go to the
message handler area of the user interface and add an attribute (see the chapter on message
handling). Any attributes added in the message handler area appear on the available attributes
list on this tab.
We recommend the following guidelines for attribute names:
o Make attribute names a single text string.
o For names that use multiple words, do not use spaces between the words.
o Use camel case for names that include two or more words (for example, AttributeName).
o Do not use non-alphanumeric characters in attribute names (for example, commas, periods,
hyphens, asterisks, ampersands and so on).
To add attributes to headers of outbound documents, use the Add button to move a selected
attribute from the available attributes list to the selected attributes list. Click Save changes
when done.
In addition to selecting metadata elements to include in headers, you must separately establish
the values for the attributes. There are several ways to do this, including:
o Message attributes tab – Use the message attributes tab on a transport maintenance
page to set attribute values by use of directory mapping or fixed values. For more
information see the message attributes tab topic in the transport maintenance chapter.
o Message handler – In the message handler area, you can set a fixed value for an attribute.
If the payload is an XML document, the value can be parsed by specifying an XPath. For
more information see the chapter on message handling.
o Inline processing – If you are a licensed SDK user, you can build a Java class and use it to
provide attribute values or perform other message actions.
Upon receiving and unpackaging a message with extra metadata, a partner who uses Axway
products B2Bi, Interchange or Activator can use the added-metadata for post processing, inline
processing or file system integration. Inform the partner of the metadata elements you add to
outbound messages.
The added metadata in the header of the outbound document is in the following format:
X-Cyclone-Metadata-AttributeName: Value
o MIME/GZIP is for trading with partners who use versions of Interchange earlier than 4.2.
You also can select this if your partner uses a trading engine other than Interchange that
supports GZIP compression.
l Encrypt messages – Select this option to encrypt the messages you send.
o Message encryption algorithm – If you select encrypt messages, select an algorithm.
l Sign messages. Partners use your certificate to verify you as the sender – Select this
option to digitally sign the messages you send.
o Message signing algorithm – The algorithm for creating a hash of the unencrypted
message. This hash is a number that is encrypted with your community’s private key. It is
decrypted by the partner using the community’s public key. The partner rehashes the
decrypted message and compares the result with the hash that came with the message. If the
two are identical, it ensures the contents have not been altered.
l Specify message attributes to be packaged with message – This option is available only
if your software license supports allowCustomMetadataInMessageHeaders. Select Help >
License information in the user interface to check whether this license key is enabled.
Checking this enables you to include any metadata elements you want in the MIME headers of
the messages your community sends. This can serve several purposes. It lets your community
forward payload-related information to a partner. It also lets a community or partner use such
data to trigger message handling actions.
The metadata that can be added are in addition to the metadata already in MIME headers, such
as sender and receiver, content type, disposition notification and so on. There are several ways
to add metadata elements to the available attributes list on this tab. You can type an attribute
name in the field below the available attributes list and click Add new. Or, you can go to the
message handler area of the user interface and add an attribute (see the chapter on message
handling). Any attributes added in the message handler area appear on the available attributes
list on this tab.
We recommend these guidelines for attribute names: Make attribute names a single text string.
For names that use multiple words, do not use spaces between the words. Use camel case for
names that include two or more words (for example, AttributeName). Do not use non-
alphanumeric characters in attribute names (for example, commas, periods, hyphens, asterisks,
ampersands and so on).
To add attributes to headers of outbound documents, use the Add button on this tab to move a
selected attribute from the available attributes list to the selected attributes list. Click Save
changes when done.
In addition to selecting metadata elements to include in headers, you must separately establish
the values for the attributes. There are several ways to do this, including:
o Message attributes tab. Use the message attributes tab on a transport maintenance page
to set attribute values by use of directory mapping or fixed values. For more information see
the message attributes tab topic in the transport maintenance chapter.
o Message handler. In the message handler area, you can set a fixed value for an attribute.
If the payload is an XML document, the value can be parsed by specifying an XPath. For
more information see the chapter on message handling.
o Inline processing. If you are a licensed SDK user, you can build a Java class and use it to
provide attribute values or perform other message actions.
Upon receiving and unpackaging a message with extra metadata, a partner who uses
Interchange 5.3.2 or later can use the added-metadata for post processing, inline processing
or file system integration. Inform the partner of the metadata elements you add to outbound
messages.
The added metadata in the header of the outbound document is in the following format:
X-Cyclone-Metadata-AttributeName: Value
l Sign messages. Partners use your certificate to verify you as the sender – Select this
option to digitally sign the messages you send.
o Message signing algorithm – The algorithm for creating a hash of the unencrypted
message. This hash is a number that is encrypted with your community’s private key. It is
decrypted by the partner using the community’s public key. The partner rehashes the
decrypted message and compares the result with the hash that came with the message. If the
two are identical, it ensures the contents have not been altered.
l Message compression – Select a method for compressing the messages you send. This is
optional. Compressing data before sending increases throughput. You might want to consult
with your partner about compressing and uncompressing as pre- and post-processing steps. You
and your partner can compress or not independently, as long as the receiver’s system supports
uncompressing.
The compression options are:
o None. Select this if you do not want compression. Also, you must select this to exchange
messages with partners whose interoperable software cannot uncompress documents.
o EDIINT/ZLIB is for trading with partners who use version 4.2 or later of Interchange or
who use an EDIINT-compliant trading engine other than Interchange.
l Message compression – Select a method for compressing the messages you send. This is
optional. Compressing data before sending increases throughput. You might want to consult
with your partner about compressing and decompressing as pre- and post-processing steps. You
and your partner can compress or not independently, as long as the receiver’s system supports
decompressing.
The compression options are:
o Uncompressed– Select this if you do not want compression. Also, you must select this to
exchange messages with partners whose interoperable software cannot decompress
documents.
o ZIP – ZIP is a data compression and archive format. A ZIP file contains one or more files that
have been compressed to reduce file size.
o ZLIB – ZLIB is a software library used for data compression. ZLIB is an abstraction of the
DEFLATE compression algorithm used in the GZIP file compression program.
l Encrypt messages – Select this option to encrypt the messages you send.
o Message encryption algorithm – If you select encrypt messages, select an algorithm.
l Sign messages. Partners use your certificate to verify you as the sender – Select this
option to digitally sign the messages you send.
o Message signing algorithm – The algorithm for creating a hash of the unencrypted
message. This hash is a number that is encrypted with your community’s private key. It is
decrypted by the partner using the community’s public key. The partner rehashes the
decrypted message and compares the result with the hash that came with the message. If the
two are identical, it ensures the contents have not been altered.
l Armor – Select this option to enable ASCII armor. Like base 64 encoding, this is for encoding
binary data to send over a 7-bit transport as text.
l Specify message attributes to be packaged with message – This option is available only
if your software license supports allowCustomMetadataInMessageHeaders. Select Help >
License information in the user interface to check whether this license key is enabled.
Checking this enables you to include any metadata elements you want in the MIME headers of
the messages your community sends. This can serve several purposes. It lets your community
forward payload-related information to a partner. It also lets a community or partner use such
data to trigger message handling actions.
The metadata that can be added are in addition to the metadata already in MIME headers, such
as sender and receiver, content type, disposition notification and so on. There are several ways
to add metadata elements to the available attributes list on this tab. You can type an attribute
name in the field below the available attributes list and click Add new. Or, you can go to the
message handler area of the user interface and add an attribute (see the chapter on message
handling). Any attributes added in the message handler area appear on the available attributes
list on this tab.
We recommend these guidelines for attribute names: Make attribute names a single text string.
For names that use multiple words, do not use spaces between the words. Use camel case for
names that include two or more words (for example, AttributeName). Do not use non-
alphanumeric characters in attribute names (for example, commas, periods, hyphens, asterisks,
ampersands and so on).
To add attributes to headers of outbound documents, use the Add button on this tab to move a
selected attribute from the available attributes list to the selected attributes list. Click Save
changes when done.
In addition to selecting metadata elements to include in headers, you must separately establish
the values for the attributes. There are several ways to do this, including:
o Message attributes tab. Use the message attributes tab on a transport maintenance page
to set attribute values by use of directory mapping or fixed values. For more information see
the message attributes tab topic in the transport maintenance chapter.
o Message handler. In the message handler area, you can set a fixed value for an attribute.
If the payload is an XML document, the value can be parsed by specifying an XPath. For
more information see the chapter on message handling.
o Inline processing. If you are a licensed SDK user, you can build a Java class and use it to
provide attribute values or perform other message actions.
Upon receiving and unpackaging a message with extra metadata, a partner who uses
Interchange 5.3.2 or later can use the added-metadata for post processing, inline processing
or file system integration. Inform the partner of the metadata elements you add to outbound
messages.
The added metadata in the header of the outbound document is in the following format:
X-Cyclone-Metadata-AttributeName: Value
l Sign messages. Partners use your certificate to verify you as the sender – Select this
option to digitally sign the messages you send.
o Message signing algorithm – The algorithm for creating a hash of the unencrypted
message. This hash is a number that is encrypted with your community’s private key. It is
decrypted by the partner using the community’s public key. The partner rehashes the
decrypted message and compares the result with the hash that came with the message. If the
two are identical, it ensures the contents have not been altered.
l Sign Signals – Sign the signals you send to partners.
o Signal signing algorithm – If you choose to sign signals, the signing algorithm to use.
l Encrypt messages – Select this option to encrypt the messages you send.
o Message encryption algorithm – If you select encrypt messages, select an algorithm.
o Encrypt service content and attachments – If encrypt messages is also selected, the
payload is encrypted (service-content and attachments).
l Sign messages. Partners use your certificate to verify you as the sender – Select this
option to digitally sign the messages you send.
o Message signing algorithm – The algorithm for creating a hash of the unencrypted
message. This hash is a number that is encrypted with your community’s private key. It is
decrypted by the partner using the community’s public key. The partner rehashes the
decrypted message and compares the result with the hash that came with the message. If the
two are identical, it ensures the contents have not been altered.
l Sign Signals – Sign the signals you send to partners.
o Signal signing algorithm – If you choose to sign signals, the signing algorithm to use.
l Compress Messages – Compress outbound messages.
l Base-64 Encode HTTP Messages – Convert outbound messages to base 64. If not selected,
messages are sent in binary format.
The default settings enable trading of secure XML payloads between two instances of B2Bi,
Interchange or Activator. The default configuration is somewhat arbitrary, but useful to get two
instances of B2Bi, Interchange or Activator trading quickly. If you want a different configuration,
engage a professional services consultant, obtain the optional Software Development Kit or both.
o ID refs to encrypt – You can add specific SOAP envelope elements and sub-elements to be
encrypted.
l Sign messages. Partners use your certificate to verify you as the sender – Select this
option to digitally sign the messages you send. To use the default configuration, make sure this
check box is selected and do not change values of any of the related fields.
o Sign attachments – Sets whether attachments are signed (on by default).
o Sign SOAP body – Sets whether the SOAP body is signed (on by default).
o XPaths to sign – You can add specific SOAP envelope elements and sub-elements to be
signed. For each you add, specify the namespace prefix, namespace URI and local XPath.
XPath examples:
o ID refs to sign – You can add specific SOAP envelope elements and sub-elements to be
signed.
l Use MTOM to encode messages – Select this option to specify parts of the payload to use
Message Transmission Optimization Mechanism (MTOM) encoding of outbound messages. This
is base 64-encoding for preserving the integrity of non-ASCII parts of payloads (for example,
blank spaces). To use MTOM encoding of outbound messages, the receiving partner must be
able to auto-detect the encoded parts and decode them. Interchange auto-detects and decodes
such messages when it receives payloads from partners.
l Use username token when sending – When this option is selected at the default level, a
global requirement is set that all messages sent via web services delivery exchanges contain a
UsernameToken element in the SOAP header. The element includes the user name and
password specified here. When you also select Require password digest in place of plain
text during authentication, Interchange converts the password to digest form. The digest is
a hash of the password that is base 64-encoded.
When selected on a per-partner basis, the collaboration setting overrides the parallel control
within partners on the Advanced tab of web services delivery exchanges for sending messages.
l Sign messages. Partners use your certificate to verify you as the sender – Select this
option to digitally sign the messages you send.
o Message signing algorithm – The algorithm for creating a hash of the unencrypted
message. This hash is a number that is encrypted with your community’s private key. It is
decrypted by the partner using the community’s public key. The partner rehashes the
decrypted message and compares the result with the hash that came with the message. If the
two are identical, it ensures the contents have not been altered.
l Use shared secret for outbound cXML messages – Select this option if you must provide a
shared secret on outbound cXML messages to partners. If you select this option you must enter
the shared secret in the accompanying field.
l Specify message attributes to be packaged with message – This option is available only
if your software license supports allowCustomMetadataInMessageHeaders. Select Help >
License information in the user interface to check whether this license key is enabled.
Select this option to include any metadata elements you want in the MIME headers of the
messages your community sends. This can serve several purposes. It lets your community
forward payload-related information to a partner. It also lets a community or partner use such
data to trigger message handling actions.
The metadata that can be added are in addition to the metadata already in MIME headers, such
as sender and receiver, content type, disposition notification and so on. There are several ways
to add metadata elements to the available attributes list on this tab. You can type an attribute
name in the field below the available attributes list and click Add new. Or, you can go to the
message handler area of the user interface and add an attribute (see the chapter on message
handling). Any attributes added in the message handler area appear on the available attributes
list on this tab.
We recommend these guidelines for attribute names: Make attribute names a single text string.
For names that use multiple words, do not use spaces between the words. Use camel case for
names that include two or more words (for example, AttributeName). Do not use non-
alphanumeric characters in attribute names (for example, commas, periods, hyphens, asterisks,
ampersands and so on).
To add attributes to headers of outbound documents, use the Add button on this tab to move a
selected attribute from the available attributes list to the selected attributes list. Click Save
changes when done.
In addition to selecting metadata elements to include in headers, you must separately establish
the values for the attributes. There are several ways to do this, including:
o Message attributes tab – Use the message attributes tab on a transport maintenance
page to set attribute values by use of directory mapping or fixed values. For more
information see the message attributes tab topic in the transport maintenance chapter.
o Message handler – In the message handler area, you can set a fixed value for an attribute.
If the payload is an XML document, the value can be parsed by specifying an XPath. For
more information see the chapter on message handling.
o Inline processing – If you are a licensed SDK user, you can build a Java class and use it to
provide attribute values or perform other message actions.
Upon receiving and unpackaging a message with extra metadata, a partner c an use the
added-metadata for post processing, inline processing or file system integration. Inform the
partner of the metadata elements you add to outbound messages.
The added metadata in the header of the outbound document is in the following format:
X-Cyclone-Metadata-AttributeName: Value
o Class 4 – In addition to Class 3 proof of content received is requested. The purpose of this
security facility is for the originator to be certain that the message received by the recipient
was indeed the one sent. Signing EDINs and EDIMs does this. This is akin to the recipient of
a letter sending the originator a photocopy of the letter received
The tab controls how long the system waits for a message receipt and the maximum times it re-sends
the message if a receipt has not been received. For example, if a receipt is not received within the
time in the resend interval field, the system sends the message again. It continues resending until a
receipt is received or the resend limit is reached.
If the resend limit is reached and a receipt has not been received, the message is given a failed
status. You can search for and manually resubmit failed messages in Message Tracker on page 826.
This tab only applies to successfully sent messages for which receipts are expected. It does not
apply to messages that fail to send due to a transport problem. For information about resending due
to transport issues, see information about the Retries field on the Advanced tab of a transport
maintenance page ( Modify an application pickup or delivery on page 202).
l Resend attempts – The maximum number of times Interchange should resend a message if a
receipt has not been received.
l Resend interval in minutes – The time the system waits for a receipt before resending the
message.
These settings:
l Override the default collaboration settings only for the community on which they are applied.
l Are overridden by any collaboration settings that you set between the community and:
o specific partner categories
o specific partners
o specific partner deliveries
Use community collaboration settings to define exceptions to the default outbound message
settings.
Use example: In your default collaboration settings you could specify that messages sent over the
AS2 protocol must return synchronous acknowledgements. For "Community A" only, you might
require asynchronous acknowledgements when using the AS2 protocol. You can specify unique
AS2 collaboration settings for "Community A" to create this requirement, while using the default
collaboration settings for sending message via other protocols.
For any settings you do not change at the community level, Interchange uses the global defaults.
See Default collaboration fields on page 911.
You do not need community-specific collaboration settings if your installation defines only one
community or if all communities want to send messages the same way.
1. Open a community summary page.
2. On the community navigation graphic, click Collaboration settings to open the Configure
community-specific collaboration settings page.
3. Select and modify the settings that you want to specialize for the current community.
See Community and category collaboration fields on page 933 for descriptions.
To specify how a community sends messages to:
l A group of partners, see Manage community-to-category collaboration settings on page 932.
l A specific partner, see Manage community-to-partner specific collaboration settings on page
934.
l A specific partner over a specific delivery, see Manage community-to-partner delivery specific
collaboration settings on page 937.
Manage community-to-category
collaboration settings
You can specify collaboration settings that apply to all partners in a category of partners that is
associated with a community. This enables you to specify exceptions to the default or community-
level collaboration settings for sending messages to groups of partners.
For example, if you have a Community_A and a partner Category_C, you can create a set of
collaboration settings and apply them to any context where Community_A sends a message to
Category_C. You could also apply the same set of override settings to additional categories for
Community_A, if you need to.
To make custom collaboration category settings, you must have at least one collaboration category
that includes one or more partners. See Group partners by categories on page 158.
You only need to specify exceptions to the default or community-level settings. For any settings you
do not change at the category level, the global defaults or any community-level exceptions are
used. See Default collaboration fields on page 911.
l At least one community
l At least one partner
l At least one category
To specialize collaboration between a community and a category:
1. Open a community summary page.
2. On the navigation graphic at the top of the page, click Collaboration settings to open the
Configure community-specific collaboration settings page.
3. In the left pane, from the tasks list, click Specialize collaboration settings for a category
to open the Add special collaboration settings for a collaboration category page.
4. In the To partners in a category field, select a category from the drop-down list of available
categories.
5. Click Add.
The category that you selected is added to the list of partners and categories associated with
the community.
These settings:
l Override:
o Default collaboration settings
o Community-specific collaboration settings
o Partner category-specific collaboration settings
l Are overridden by any collaboration settings that you set between the community and a delivery
of the partner.
Use example: Your default collaboration settings could specify that messages sent over the AS2
protocol should return signed acknowledgements. Partner A might want to send unsigned
acknowledgements. You can specify that Partner A send unsigned acknowledgements for the AS2
protocol, while all other partners in the community use the default or community-level settings.
l At least one community.
l At least one partner.
To specialize collaboration between a community and a partner:
1. Open a community summary page.
2. Click Collaboration settings on the navigation graphic at the top of the page to open the
Configure community-specific collaboration settings page.
3. In the left pane, from the tasks list, click Specialize collaboration settings for a partner
to open the Add special collaboration settings for a partner page.
4. Complete the Messages sent to field. Click Pick a partner and then select a partner from the
list of available partners in the pop-up window.
5. Click Add.
The partner that you selected is added to the list of partners associated with the community.
The following list describes the override options:
These settings are the most specific level. They override:
l Default collaboration settings
l Community-specific collaboration settings
l Community-to-partner category specific collaboration settings
l Community-to-partner specific collaboration settings
Use example: Partner_A might want to send unsigned acknowledgements only with the AS2
protocol but signed in all other cases. You can specify that Partner_A send unsigned
acknowledgements over an AS2 delivery, while all other messages received from Partner_A (or other
partners) require signing
l At least one community
l At least one partner with a defined trading delivery
To specialize collaboration between a community and a partner delivery:
1. Open a community summary page.
2. Click Collaboration settings on the navigation graphic at the top of the page to open the
Configure community-specific collaboration settings page.
3. In the left pane, click the name of a partner that is associated with the community. Then from
the list of tasks, click Specialize collaboration settings for delivery to open the Add
special collaboration settings for a partner delivery page.
4. Complete the Messages sent through field. Click Choose a delivery... and then select a
partner delivery from the list of available partner deliveries in the pop-up window.
5. Click Add.
The partner delivery that you selected is added to the list of categories, partners and partner
deliveries that are associated with the community.
l Duplicate EDI documents
l Signed or unsigned messages
l Encrypted or plain text messages
l CSOS duplicate orders
l Web Services messages
l AS4 messages
l cXML messages
You can combine validation rules. For example you could configure validation so that inbound
messages are rejected if they are either not signed or not encrypted.
You can also set exceptions to your validation rules that are based on the:
l Partner that sent the message
l Collaboration category of the partner that sent the message
l Exchange point that receives the inbound message
For example you could require signing of all inbound messages, except when the messages are
received on a specific Web Services exchange point.
Interchange applies a validation rule only when it parses a valid sender and a valid receiver partner
for a message that it is handling.
For information about collaboration categories, see Group partners by categories on page 158.
For information about packaging of outbound messages, see Collaboration settings on page 909.
Use the tabs of this page to set the conditions for document reception from p artners:
l Validation rules: Duplicate messages tab on page 940
l Validation rules: Signing tab on page 941
l Validation rules: Encryption tab on page 942
l Validation rules: CSOS duplicate orders tab on page 942
l Validation rules: Web Services tab on page 943
l Validation rules: AS4 tab on page 945
l Validation rules: cXML tab on page 946
Select an option:
When Interchange receives a batch parent document and splits it into multiple child documents,
all with the same control number as the parent, Interchange does not consider siblings of the
same parent to be duplicates. This processing exception accommodates custom EDI splitters
that are used in place of the system’s standard EDI splitters.
l Allow duplicate EDI document IDs (default) – Select this option to let Interchange accept
duplicate messages.
Whether you choose to reject or allow duplicate EDI messages, the choice applies to all EDI
messages received for the community, unless you define exceptions. You can set up the following
exceptions to the duplicates rule setting:
Select an option:
You can add multiple partners, c ategories or trading pickups to the exceptions lists. Interchange
applies the opposite of the selected behavior to any partners, collaboration categories, or trading
pickups that display in the exceptions lists.
Select an option:
l Reject messages that are not encrypted – Select this option if the messages a partner
sends must be encrypted with your public encryption key. Your community decrypts the
message with the private key in the digital certificate associated with your community. To send
encrypted messages, the partner must have your certificate and public key.
l Accept messages that are not encrypted – Select this option to accept b oth encrypted and
unencrypted messages.
Whether you choose to reject or accept messages that are not encrypted, the option applies to all
messages received for the community, unless you define exceptions. You can set up the following
exceptions to these options:
CSOS duplicate checking is done for CSOS purchase orders your community receives from partners.
If the community is a WebTrader sponsor, documents received from its WebTrader partners also are
checked. Duplicate checking is not done for orders picked up from integration, unless the
community that picks up the order is the named receiver (a rare case).
If your community only sends signed orders but does not receive any, duplicate checking is not
applicable and you can ignore this tab.
The target documents are the EDI or XML documents defined on the order identification tab of the
identify CSOS purchase orders page.
To configure validation on CSOS duplicate orders, select an option:
Authentication is an optional part of trading via Web Services and AS4.
In the Web Services tab, select a validation rule option:
l Reject messages without user name and password within UsernameToken in SOAP
header
When you select this option, Interchange checks whether the UsernameToken element in the
SOAP header of an Web Services or AS4 inbound message has a user name and password. The
following is an example of a user name and password within a UsernameToken element.
<S:Envelope xmlns:S="http://www.w3.org/2001/12/soap-envelope"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext">
<S:Header>
...
<wsse:Security>
<wsse:UsernameToken>
<wsse:Username>Joe</wsse:Username>
<wsse:Password>ILoveJava</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</S:Header>
</S:Envelope>
<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsse:Security xmlns:wsse="http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
soapenv:mustUnderstand="1">
<wsse:UsernameToken xmlns:wsu="http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
wsu:Id="UsernameToken-19053538">
<wsse:Username>wsbpLaptopCom</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-
200401-wss-username-token-profile-
1.0#PasswordDigest">5UcyqD5Djf5BZu0ZrZSF/5RSv3k=</wsse:Password>
<wsse:Nonce>XIa3LzWkrNvL41RL9JOcMg==</wsse:Nonce>
<wsu:Created>2010-09-28T13:37:08.473Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
l Accept messages that are not authorized using X509 digital signature defined
within SOAP header – Enables the community to consume AS4 and Web Services messages
that do not include X509 tokens.
l Treat SOAP Faults as negative acknowledgements – SOAP faults are SOAP response
messages that contain a single instance of the Fault element inside the SOAP body, with no other
data content. These responses are not automatically flagged by Interchange as negative
acknowledgements. Select this option force Interchange to handle WS fault responses as
negative acknowledgments.
Whether you choose to reject or accept authenticated Web Services or AS4 messages, the choice
applies to all Web Services or AS4 messages received for the community, unless you define
exceptions.
You can specify exceptions for the two main categories of Web Services/AS4 authentication:
Note To set AS4 SOAP header rules for the use of User Name and X.509 tokens, see Validation
rules: Web Services tab on page 943.
Select an option:
Interchange cXML delivery exchanges optionally can require passwords in a SharedSecret element in
the cXML document header.
Select an option:
Supported protocols
You can currently configure sequential message delivery on the following application and partner
pickups:
l AS/2
l FTP and FTPS client
l FTP and FTPS embedded server
l PGP over FTP
l POP
l MQSeries native
l SFTP Client
l SFTP Embedded Server
l SMTP Server
l For FTP and SFTP clients, Interchange assigns the order (generating sequential IDs) according
to the order of the files in the list returned by the FTP LIST command.
Note: The FTP LIST results can vary from one FTP server to another. No Interchange
configuration options are available to change this behavior.
l Interchange assigns the order (generating sequential IDs) o nce the payload starts to be received
by Interchange and Interchange is ready to send the message for processing.
l The order can only be fully controlled from the side of the client who is uploading the files (and
not by Interchange). If messages must be processed in sequence, the client must send them in
sequence over a single session.
Note: Interchange cannot limit the number of allowed sessions for a client. Such a limitation
would otherwise result in connection errors for clients due to connection limitations.
Message processing
There is no sequential message handling during the processing phase. The sequential IDs that are
assigned on consumption (pickup) are only taken into account at production (delivery).
For MQ, SMTP, FTP and SFTP clients:
l Each delivery has one producer per cluster (no multiple parallel production) for sequentially
delivered flows. For all deliveries (partner and application) Interchange o rders messages
according to the message order assigned by the pickup. Messages are released one at a time by
the delivery in sequential order.
Interchange reorders messages according to the order of message assigned by the pickup process
for all deliveries.
l The consummation order can only be fully controlled on the client side (and not by
Interchange). If messages must be processed in sequence, the client must send them in
sequence over a single session.
l If a delivery receives both sequenced and non-sequenced messages, the non-sequenced
messages are delivered immediately, the sequenced messages are ordered according to their
sequential IDs.
Examples
Normal sequence:
Sequence ID Sequence
number
1 1
1 2
1 3
1 4
Sequence with failed message number 3.
Sequence ID Sequence
number
1 1
1 2
Sequence ID Sequence
number
1 3 (failed)
1 4
Sequence with dummy message replacing failed message number 3.
Sequence ID Sequence
number
1 1
1 2
1 3 (dummy/empty)
1 4
For example:
1 Available –
2 Not available –
3 Available 60
4 Not available 5
5 Available 0
In this example, messages 3, 4 and 5 wait until 1 and 2 are available. When 5 expires, Interchange
checks the availability of 4. If 4 is available, Interchange ignores the timer status. This behavior
cascades upstream to generate the new status:
1 Not available –
2 Not available –
3 Available 55
4 Available –
5 Available –
If message number 3 arrives at the time-out limit and messages 1 and 2 are still not available,
Interchange sends messages 3, 4 and 5 in sequence.
In the case of multiple out of sequence gaps, the situation is different. Consider the following
example:
1 Not available –
2 Available 60
3 Not available –
4 Available 55
5 Available 50
If message 5 times out first, Interchange checks the availability of message 4. Because message
number 4 is available, Interchange ignores the timer.
1 Not available –
2 Available 5
3 Not available –
4 Available 0
5 Available –
When message number 4 times out, Interchange detects that message 3 has not yet been received.
Interchange sends message 4, despite the fact that number 2 did not time out yet. Interchange
sends messages number 4 and 5 before message number 2. The order between 4 and 5 is
maintained.
In the case of a larger number of queued messages and multiple sequence gaps between messages,
this logic causes out of sequence message delivery: Interchange sets timers on the various
messages. When the time-outs expire there will likely be a gap between the “expired” entry and the
last processed entry. This causes the expired entry, and everything after it, to be delivered out of
sequence.
For example:
Messages 1, 2 and 3 are ready to be sent. Message 2 is in the actual process of being sent. Message 2
and 3 are in the queue. Then the system stops abruptly. On system restart, messages 1, 2 and 3 are
all pushed back to the queue. Their sequence is maintained and their timers are reset (in this
example to default = 60 seconds).
Before restart:
1 In transfer –
2 Available 5
3 Available 10
After restart:
1 In transfer –
(reintroduced)
2 Available 60
3 Available 60
A side effect of this pattern is that any message that timed out will get a new opportunity for delivery
after the restart. For example, Message 1 is missing and 2 and 3 are still waiting for this message.
When the system restarts, message 2 and 3 are reintroduced by the fail-over coordinator and the
timers for message 2 and 3 are re-started., so message 1 is allotted an additional X seconds to arrive.
1 Not available –
2 Available 60
3 Available 60
Interchange does not reintroduce work in sequential order, so the likelihood of time-outs and gaps
occurring is much higher when there are a lot of messages being processed at shutdown. For
example, if the trading engine has 3 000 sequenced messages to restart, it could end up re-
introducing the messages in random sequence order (299, 1, 1967, 556, etc). Since this occurs at
50% of processing capacity, timeouts are likely.
With larger numbers and gaps between messages, this logic will cause out of sequence message
delivery. For example, if we have a large quantity of messages in the backlog and new messages are
consumed for processing, Interchange sets timers for this “new” work. After the time-out expires,
there will most likely be a gap between the “expired” entry and the last processed entry. The result is
that particular entry (and everything after it) is delivered out of sequence.
The failover coordinator stops injecting old workload if Interchange throttle is invoked due to new
work.
If sequencing is activated on the corresponding pickup, Interchange guarantees that the order in
which messages are re-submitted is kept.
l SequenceId
l SequenceCount
Together these attributes provide a unique sequence identity for messages consumed by
Interchange pickups, when sequential messaging is activated for the pickup.
For messages received from partners and delivered to integration, Interchange generates MMDs for
the inbound documents. You must use the file system with message metadata integration delivery
option to have Interchange generate MMDs for inbound documents.
For outbound messages, your back-end system must generate the MMDs that tell Interchange where
to pick up the documents to send to partners. The MMDs must be written to a file system integration
pickup directory.
For information about setting up file system pickup and deliveries, see File system transport
configuration on page 189.
Depending on the message protocol your community uses to exchange messages with partners,
different rules apply for using MMDs. For most trading protocols, follow the guidelines in this topic.
However, if you trade via the ebXML, RosettaNet or web services message protocol, see the chapter
or topic for that protocol. The MMDs described here are known as generic MMDs because they can
be used in conjunction with most message protocols, except the three noted.
See the following for information about using MMDs with these protocols:
l AS4 metadata on page 503
l Web Services message protocol on page 726
l ebXML on page 545
l RosettaNet on page 699
The following topics describe how generic MMDs are used for outbound and inbound messages.
Outbound messages
You must decide what message metadata accompanies outbound payloads. Any arbitrary metadata
values can be included. Metadata elements are parsed and added as message attributes to a
consumed message. The following is an example:
<Metadata name="MyItem">SomeValue</Metadata>
In this example, an attribute named MyItem with the value SomeValue would be added to the
created message.
In addition to arbitrary metadata, there are some minimum requirements:
l The value of the protocol attribute of the MessageMetadata Document element must be
generic. The value of the protocolVersion attribute does not matter; Interchange ignores it.
l The MMD must specify values for From and To. From is a community routing ID and To is a
partner routing ID.
l For each document to pick up, the MMD must specify a payload ID, Mime content ID and the file
path for the document. The MMD can specify multiple documents.
The following describes elements for a generic MMD for an outbound message. All except
RemovePayloadAfterProcessing are required.
Note Use the optional SubjectHeader attribute to set the subject line of outbound messages
sent via generic email (SMTP), AS1, AS2, AS3 and Secure File message protocols. For
outbound messages, the subject line value can be set by adding SubjectHeader as a
message attribute on integration pickup exchanges or adding it to outbound MMDs.
Interchange sets the attribute and value on inbound email and EDIINT messages.
l MessageMetadataDocument – This element has the following attributes.
o documentId – A unique identifier for the MMD.
o protocol – Always should be generic.
o protocolVersion – The value of this attribute can be anything. Interchange ignores it.
l Metadata name="From" – The name of the sender. This is a community routing ID.
l Metadata name="To" – The name of the receiver. This is a partner routing ID.
l MessagePayloads – One or more payloads can be listed under this element.
l Payload id – A unique identifier for the outbound document. This element has the following
children.
o MimeContentId – An identifier of the payload content.
o MimeContentType – The MIME type of the payload. For example, application/xml.
o Location type – The path and file name of the payload. Payloads can be on a file system or
an HTTP or FTP server, as the following examples illustrate:
File system
<Location type="filePath">C:\smallxmlPO.xml</Location>
HTTP
<Location type="xs:anyURI">http://www.oasis-
open.org/committees/ebxml-cppa/schema/cpp-cpa-2_0.xsd</Location>
FTP
<Location type="xs:anyURI">ftp://acme:acme@cfoster-
dell.cyclonecommerce.com:4021/mailbox/foo.dat</Location>
In the FTP example, acme:acme in the URL represents the user name and password for
connecting to the FTP server. Using an email address as the password is not supported.
o RemovePayloadAfterProcessing – Indicates (true or false) whether Interchange deletes
the payload from the file system after processing the message. (MMDs always are deleted
after processing.)
Use of this element is optional. If not used, the payload is not deleted, which is the same
behavior as using the element with a value of false. If RemovePayloadAfterProcessing
is true, payloads are deleted after being picked up.
This also works for the resubmit case in which payloads are retrieved from the backup
directory.
You can build an MMD based on the example shown here which demonstrates the minimum
requirements. The example of generic MMD for outbound message follows:
Inbound messages
Each MMD contains all metadata associated with the document received from the partner. This is
similar to how metadata are handled for integration delivery via JMS. Your community must use a
file system with message metadata integration delivery option to have Interchange generate MMDs
for inbound documents.
The following code is an example of a generic MMD generated by Interchange for an inbound
message:
This transport is available with the AS2, ebXML, RosettaNet 1.1, RosettaNet 2.0, and secure file
message protocols.
To use this transport, you must have a web server application running in your organization's DMZ
and thorough operations knowledge of the web server.
Caution The staged HTTP transport feature in Interchange contains known vulnerabilities. Axway
recommends that you configure Secure Relay with a global embedded server instead. For
more information, see Secure Relay DMZ nodes on page 474.
See the related topics:
l HTTP security solutions on page 586
l HTTP connection troubleshooting on page 589
The above figure shows how this transport works, and the following describes the process.
1. Your partner sends a document to the web server using a standard message protocol (for
example, AS2). The staged HTTP servlet writes the file to disk pending retrieval by Interchange.
This provides failover protection.
2. At the usual polling interval, Interchange polls the web server and retrieves the document with a
GET method. This is the default manner for picking up documents. Alternately, you can
configure the staged HTTP servlet to forward the incoming message to Interchange
immediately. This bypasses the polling interval, allowing faster throughput, but opens a port
into your trusted network. (See File forwarding to bypass polling on page 966.)
3. Interchange sends a receipt to acknowledge receiving the document. The receipt can be sent
synchronously over the same connection as the inbound message or asynchronously based on
message protocol configuration.
1. Deploy the staged HTTP servlet on your web server. See Staged HTTP files to deploy on page
960 and Deploy the web servlet on page 968.
2. Log on to the HTTP servlet user interface. See Log on to servlet UI on page 960.
3. Add a mailbox for your partner. See Add a mailbox on page 961.
4. For your community in Interchange user interface, add a delivery for receiving messages from
the partner. See Staged HTTP UI fields on page 963.
Log on to servlet UI
Do the following to log on to the staged HTTP servlet user interface after deploying the servlet on
the web server.
Point a web browser to the web server with a URL in the following format:
Note Use stagedhttp in the URL if you followed the deployment recommendation to use this as
a directory name for the servlet on the web server. Otherwise, use the name you selected. If
the port is 80, you do not have to include it in the URL.
Type the user name and password of the mailbox administrator when prompted.
The browser displays the staged HTTP servlet page in the following figure.
Manage mailboxes
You can use the staged HTTP servlet user interface to manage mailboxes and the files they contain.
A mailbox is a web server directory. Partners connect to the web server via the URL for a specific
mailbox. Files the partner sends are written to a temp directory and then moved to the mailbox when
fully received. The sponsor’s trading engine retrieves the files from the mailbox with the same URL.
You can perform the following tasks in the UI:
l Add, edit and delete mailboxes
l View files in mailboxes
l View running totals for file uploads, downloads and deletions
l View and change global settings for the servlet
Add a mailbox
Use this procedure to add a mailbox.
But you must add the domain and port to the URL before passing it along. The URL you provide
must be in this format:
http://webserver.domain.com:port/webmailbox/partner
4. Select the users who can access this mailbox with their user IDs and passwords. The
remoteuser and ecengine users are displayed by default, but not selected. To add a user not
displayed, click Add Privilege. You can select to allow users read and/or write access
depending on the user type.
The # instances permission for users represents the number of clients that can concurrently
access the mailbox. In most cases, make this a large number (for example, 1000000) to make
sure partners can connect to the servlet.
5. Click Save Mailbox to close the mailbox maintenance page and save the mailbox.
A user name and password must always be used to send to the staged HTTP servlet. It is not
recommended to use the standard ecengine user for this purpose, as that user also has permissions
to read from the staged HTTP servlet. A new user can be used for the purpose of sending to the
staged HTTP servlet, as long as the user and its role are configured properly in the web server. If a
new role is configured, edit stagedhttp/WEB-INF/web.xml and add the role to the auth-
constraint element in the security-constraint in the following figure, auth-constraint section of the
web.xml file.
<web-app>
...
<security-constraint>
...
<auth-constraint>
<role-name>mailboxadmin_
role</role-name>
<role-name>communityadmin_
role</role-name>
<role-name>ecengine_role</role-
name>
<role-name>remoteuser_
role</role-name>
<!-- Add role-name element for
new role here. -->
</auth-constraint>
...
</security-constraint>
....
</web-app>
Global settings
You do not normally need to change settings on the configuration manager Global Settings page,
with the possible exception of the synchronous request timeout setting. This setting controls how
long a connection stays open while waiting for a response over the same connection. An advanced
user may have a reason for changing the default time of 600 seconds.
The URL to use is the one set up in the staged HTTP servlet user interface for the mailbox the partner
has for sending documents. The user ID and password to use are those authorized in the servlet UI
for the mailbox.
l URL –The URL for connecting to the web server. If Encode and Decode buttons display, click
Encode if the URL contains spaces or non-alphanumeric characters to encode the characters.
Click Decode to reverse the transformation. For example, if you enter http://foo.com/foo=
bar and click Encode the URL becomes http://foo.com/foo%3D%20%20bar.
AS2
Using staged HTTP to trade AS2 messages does not require any special configuration of the staged
HTTP servlet. The servlet, in conjunction with Interchange, knows how to handle asynchronous and
synchronous receipts correctly.
ebXML
Using staged HTTP to trade ebXML messages does not require any special configuration of the
staged HTTP servlet. The servlet, in conjunction with Interchange, knows how to handle
asynchronous and synchronous acknowledgments correctly.
Secure file
Supporting the secure file message protocol requires special configuration of the staged HTTP
servlet.
The configuration requires editing two files in the staged HTTP servlet’s conf directory on the
application server: configurationrules.xml and webmailboxconfig.xml. After editing the
files, restart the servlet.
Support for the secure file protocol by the staged HTTP servlet is on a mailbox-by-mailbox basis. To
have all mailboxes added from this point forward support the secure file protocol, open the
configurationrules.xml file and add or change the DefaultPostMode element to the Mailbox
element inside the MailboxTemplate element. See the following figure configurationrules.xml
file.
<Rules>
...
<MailboxTemplate id="default">
<Mailbox>
...
<DefaultPostMode>async</DefaultPostMode>
...
</Mailbox>
</MailboxTemplate>
...
</Rules>
To add support for the secure file protocol to specific existing mailboxes, open the
webmailboxconfig.xml file and add or change the DefaultPostMode element in each desired
Mailbox element in the Mailboxes element see the following figure: webmailboxconfig.xml file.
<WebMailboxConfiguration>
...
<Mailboxes>
...
<Mailbox ...>
...
<DefaultPostMode>async</DefaultPostMode>
...
</Mailbox>
...
</Mailboxes>
...
</WebMailboxConfiguration>
To use forwarding, set up a staged HTTP transport for receiving messages in the community as
though you are using the polling method. But also add an embedded HTTP server transport in the
profile. The staged HTTP servlet forwards messages to the embedded server, but polling remains
active with the staged HTTP transport. This provides failover protection. If a message cannot be
forwarded because, for example, Interchange server is not running, the message is retrieved once
the server restarts and polls the web server.
To enable forwarding, configure the forwarding.xml file in the staged HTTP servlet’s conf directory.
The following describes the elements in the file. You must delete or comment out unused elements.
l HTTP Info – The information for forwarding to an embedded HTTP server is placed within this
element. If Interchange server runs on a multiple computer cluster, one HTTP Info block is
needed for each computer. See the URL element.
l uri="/SOMEMAILBOX" - The name of the mailbox created in the staged HTTP servlet user
interface.
l class="com.cyclonecommerce.webmailbox.forwarding.HttpForwardingHandler" –
The Java class for the forwarding function.
l <URL>http://node1:4080/exchange</URL> – This is the URL for connecting to the
embedded HTTP server in Interchange. The URL must be in the following format:
http://<host>:<port>/exchange/<community routing ID>
You can copy most of the URL by looking up the embedded HTTP settings tab on the transport
maintenance page in Interchange user interface. The UI uses <cluster machines> for <host> in
the URL in lieu of a machine name because the Interchange server may run on multiple
computers. You must substitute the computer name. If the Interchange server runs on multiple
computers, use an HTTP Info element with a different host in the URL for each machine. An
example of this set up is shown in the forwarding.xml file.
l <UserName>SOMEUSER</UserName> – If required, the user name for connecting to the
embedded HTTP server.
l <Password>SOMEPASSWORD</Password> – If required, the password for connecting to
the embedded HTTP server.
l <ProxyHost>MYPROXYHOST</ProxyHost> – If the staged HTTP server must connect
through a proxy to the embedded server, the proxy name.
l <ProxyPort>8080</ProxyPort> – If the staged HTTP server must connect through a proxy
to the embedded server, the proxy port.
l <ProxyUserName>SOMEPROXYUSER</ProxyUserName> – If the staged HTTP server
must connect through a proxy to the embedded server, the user name to connect to the proxy.
l <ProxyPassword>SOMEPROXYPASSWORD</ProxyPassword> – If the staged HTTP
server must connect through a proxy to the embedded server, the password to connect to the
proxy.
l <ResponseTimeout>600000</ResponseTimeout> – The time in milliseconds the sender
waits for a response before dropping the connection.
In this clustered example, each instance of Interchange needs a staged HTTP delivery exchange for
receiving messages from partners.
The following describes the process illustrated in the figure.
1. Inbound documents are routed to either staged HTTP servlet.
2. The staged HTTP servlet receives the request and persists it to temporary storage (non-clustered
storage). If the message requires a synchronous acknowledgement, the inbound connection is
held open.
3. Each instance of Interchange is configured to poll each staged HTTP servlet.
4. Interchange receives inbound document by issuing:
a. HTTP GET for listing of all inbound documents.
b. HTTP GET for each inbound document
c. HTTP DELETE to remove the document from temporary storage.
5. If the received message requires a synchronous acknowledgement, Interchange produces the
acknowledgement back to the consuming staged HTTP servlet so it can be produced back to
the original inbound connection.
l Apache Tomcat 8.0.15
l Oracle WebLogic 12c
l IBM WebSphere 8.5.5
After deploying the servlet on the web server, do not edit any of the servlet files, except as
recommended by the user documentation or technical support. In particular, do not change or
move the activation.xml file. This is the license file for the servlet. Changing this file makes the
servlet inoperable.
The servlet uses three file system directories for processing messages and logging information.
Servlet files control the paths for these directories. The following are the default directory paths. The
name of the file that defines each path also is listed. You can change the path by editing the file.
The message directories are created when the servlet is deployed and running. On UNIX make sure
the user has permissions to add directories.
Deploy on WebLogic
Use the following steps to deploy the staged HTTP servlet on a WebLogic web server. These steps
are provided as guidelines. See the web server user documentation for specifics about deploying
servlets.
1. Create a directory called /logs inside the “domain_name” (default: mydomain) folder that the
staged http application will be a part of. Logging related to the staged HTTP application is
written into this /logs folder.
2. Log on to the weblogic administration UI.
3. Create users for communityadmin, ecengine, mailboxadmin, and remoteuser. Do not create
roles for these users.
4. Deploy the servlet by pointing to the war file or to the extracted tar file contents.
5. Use default options for deploying. In particular, the security model option must be DD Only:
Use only roles and policies that are defined in the deployment descriptors.
6. Once deployed, enable start servicing all requests from the summary of deployments page.
7. When the previous steps are complete, confirm that the user can log on to the servlet’s UI.
1. Create a folder called /logs inside the bin folder. This is the folder where you invoke the
startup scripts. Logging related to the stagedhttp application is written into this /logs folder.
2. On the Tomcat installation folder, edit the tomcat-users.xml file, adding the following users
and roles. Follow the format suggested in the file: first declare the roles, and then map the roles
to the user and password.
mailboxadmin mailboxadmin_role
ecengine ecengine_role
remoteuser remoteuser_role
communityadmin communityadmin_role
3. Logon to the Tomcat UI. Access the “Manager App”.
If you do not have logon credentials, you can manage them in the file tomcat-users.xml.
4. Deploy the staged http servlet by pointing to the war file.
5. Log on to the servlet UI.
Deploy on WebSphere
Use the following steps to deploy the staged HTTP servlet on a WebSphere web server. These steps
are provided as guidelines. See the web server user documentation for specifics about deploying
servlets.
1. Stagedhttp-related logging is written into the /logs folder that resides in the profile_root
directory. For example, if the profile name is appserver01, the logs directory is
…profiles/appserver01/logs. This logging directory is created automatically.
2. Log on to the WebSphere administration UI.
3. Working in the Users section of the UI, create the following users. Do not create their
corresponding roles:
l ecengine
l communityadmin
l mailboxadmin
l remoteuser
4. Deploy a new enterprise application by pointing to the stagedhttp.war. Provide the context
root when prompted. The default string for the context root is stagedhttp.
5. Map the newly-created users to the roles that are added as the servlet is deployed:
mailboxadmin mailboxadmin_role
ecengine ecengine_role
remoteuser remoteuser_role
communityadmin communityadmin_role
6. Save changes when prompted.
7. Start the application ‘stagedhttp’ from the Applications list page.
Log on to the servlet UI.
Secure file message protocol supports light-weight packaging for payload POST methods into the
Interchange (for example, using curl).
Secure file message protocol supports transfers and failover restart for recovery from service
interruptions.
If you are administrating WebTraders and want to enable large-file handling for your WebTrader
end-users, you must enable a Secure file trading pickup on your WebTrader sponsor community.
When secure file is enabled on the sponsor community, the sponsor's WebTrader partners use a
dedicated applet to upload documents to the sponsor's server through the Secure file trading
pickup.
The following transports support Secure file protocol:
l HTTP
l HTTPS
l FTP
l FTPS
l SFTP
l File system
l MQSeries
l JMS
l Staged HTTP web servlet
Secure file message protocol pre-dates AS3, and is not the same as AS3. If you are using FTP and
AS3 is available, we recommend using AS3. Moreover, if you and your partner both use Axway file-
trading software, use AS2 rather than Secure file over HTTP.
Sender determination
1. MIME headers are checked for X-Cyclone-From and X-Cyclone-To.
2. Subject line
To aid in true sender and true receiver determination, Interchange supports parsing the MIME
subject line.The format of the subject line is compatible with Interchange 4.x.
There are two valid formats
truereceiver
truereceiver; truesender
We recommend the true receiver and true sender be simple alphanumeric strings without
leading or embedded spaces. If spaces or non-alphanumeric characters are used, enclose the
strings in quotes like so:
'true receiver';'true sender'
Although supported, non-alphanumeric characters in the strings is not a best practice.
3. A message ID MIME header formatted in the style of Interchange 4.x.
4. From header. The From header is typically an email address. Interchange tries to match the
contents of the From header with a configured routing ID. So Interchange may need to be
configured to have a routing ID that is really an email address.
5. Payload parsing. This is not supported for signed and encrypted documents.
6. Exchange points assigned to specific parties. Signed and encrypted messages are not
supported.
Receiver determination
1. MIME headers are checked for X-Cyclone-From and X-Cyclone-To. This is not supported by
Interchange 4.2 or Cyclone Central.
2. Subject line.
3. Pickup exchange point .
4. Payload parsing. This is not supported for signed and encrypted documents.
5. Exchange points assigned to specific parties. Signed and encrypted messages are not
supported.
Outbound packaging
Secure file messages packaged by Interchange always contain the MIME headers and subject line.
The subject line is included for backwards compatibility with Interchange 4.2. Interchange does not
include message ID MIME header in packaged messages. The headers are X-Cyclone-From and X-
Cyclone-To.
Valid Content-Type: headers are:
l Content-Type: application/edi-x12
l Content-Type: application/edifact
l Content-Type: application/xml
l Content-Type: application/octet-stream
Valid Content-Length: entries should contain a precise byte count of the cleartext payload. For
example: Content-Length: 2013
Its critical that the byte count be precise for proper reception and processing of the inbound
payload.
For payload placement, a blank line should follow the Content-Type: and Content-Length: headers
followed by the clear text EDI or XML payload.
The same as AS2. Secure file and AS2 set up with no encryption, or signature is packaged with a
single body part with the content-type header set to the content-type of the payload (for
example, application/edi-x12).
l Does Secure file support synchronous acknowledgments?
No.
l Does Interchange support payload content-types other than the ones referenced?
Yes. Interchange can support arbitrary payload content-types. The limitation is there must be a
way for Interchange to determine the sender and receiver. Parsing cannot be used for sender
and receiver determination unless a custom parser is written.
Curl command
Curl is an example of a third-party command line tool that you can use to post documents to
Interchange. Interchange does not support retrieval of documents.
Curl is a client to get or send documents on a server using any of the supported protocols: HTTP,
HTTPS, FTP, GOPHER, DICT, TELNET, LDAP or FILE. The command works without user interaction
or any kind of interactivity. Curl offers proxy support, user authentication, FTP upload, HTTP POST,
SSL (HTTPS) connections, cookies, file transfer resume and more.
To use curl with Interchange, add a secure file message protocol bound to an embedded HTTP
server to the community. The following are examples of posting files to Interchange with curl.
Optionally, the following can be included to avoid document parsing:
--header X-Cyclone-To:senderroutingid --header X-Cyclone-
From:receiverroutingid
Optionally, the following can be included to avoid document parsing:
--header X-Cyclone-To:senderroutingid --header X-Cyclone-
From:receiverroutingid
Optionally, the following can be included:
--header X-Cyclone- To:senderroutingid --header X-Cyclone-From:receiverroutingid
l SSL–
curl --header from:receiverroutingid --header content-
type:application/octet-stream --data @myfile.bin
https://hostname:port/exchange/ep1
Packaging examples
The following are examples of documents with Secure file packaging.
0€ *†H†÷
€0€ 1‚®0Ú 0C0.10U
namelinux210U
namelinux2 –CÆ´ãÚ]•´0¦S
9n0
*†H†÷
€±ÏY
ž}zbÊvEOe85˘ãßd{Áš?öÀ2šJ¦×Dy”s1»3ênªñ0–/ä«ŠÔ«Íuh8€$öû1‘ëì
==^ï‹Y©ä˘VòÀv1’¹6¬à©Ò…SüòêrëçÕš•¥Ê’e{€YÞr£ý‰“»Þ0Î 070"10
U
haboob10
Uhaboob Çâÿ¸†Ô`aú'/ãv°0
*†H†÷
€‘Àd‹eh†?´Ç[–v¹Ã¢AG¿‡¨ÂܱþõñÅPªmf–Ï~‚í²ž`\”lŠÕåf]…˜Ÿ„,Êtp½~ÔWQlÓGA0¸
#åÙÍx¾rxC÷^žúíýY-
Lë¥î;^Åüˆ\÷?jñú´ÐœÄZ8ê0€ *†H†÷0*†H†÷u‘ñòc“5 €‚
8R½¤«ˆöù Õ."n§eÖ,بœ²¬D¹:·«äsH ö-ãl ƒñRêR®BGÿ蜜Y·²Ô›¾ÚÄÈd¹¤‰÷
Ú¼W2Ä¥Ò#9Âjܑ퀦ë£{w1ü®†bª_ÿ‡˝Š÷Öê\-ŒŒ&¾uñú‚ã«kz#J3µœèZ·fñ,0ÿÍA¹ÿ‰ÔÓ
{lÞNcßjEÙztÛbùËqÀ¥B)ÀtPßpÚ¹ý%#içM·
«i2ê->èÃ(þviàj8jéc%`Db‘ÚÒì5úıO
!~èmŒÚퟕ\´€¼äAÖëB„DxþÔB,ºV¨½õ2åÛ²®”ãk«ÊPŸÍk(Ÿ7꨻Œë(HdIœtv—w§ÂŸ
4‰º¬R†_˝žgãHÏÜ8"<Î-+üK#þVøÖ–‚Ú‘.¢ìÝ…•òòX=Êð$¸é—i;ªZÊ.ÏÔ%jÆ.÷¿ÔãƒIî
{˘UàzÄêiq”'–ŸŽ||”Ô‘NÇ15jÝpcL+øg᪉2d-
rižNË
3E|5mjÛBÆöœË²¤×‰óAs¸›ÇØD<ôâSâk]‡{ÌÓ=åfF˝í8ìOQÆo%‰—Ò!nĹh)„sc8аž²æ
˝CTþ˝t}>Ç…b¬z˝ûg2ïwÌÁrýô•Bt•ÆÌø&°?˝‡ìÛÚNçi-
÷±Y ©¹ó[À̸ü¤hºƒY–ú8Ä>Íø)
ºT½:œßépÿX˘óô8Þ@$¹öÐ@…ì_K¶eUû0™7.ÿ8-‘àÇèçŽ ©]
SEp)·¤ý”¿Ã47íß#FÙ:÷H(ÿŒïShèÚÍ„Jù*ÂñøíAȤ¬÷Í`æÙ˘†¥ÓH½âÒ«úÒ'¾Fü‚º¹
§C˝¥~‚üõé¤Þ&•WüÌ„ êªßYzx…AžÒ[àÏ°ŠSÀ_p L·—´½m%ö—£_×Ȭ¯|çÒû
Öò6-
¬ŒæhÞ¿Ìn«<¯«¸‹²tOxà Ÿ$Ø—â‹ìŽ˘ a–h“¸KÓá÷Þ y´0ôŒ1ÛtyÏ;¥!ˆÒ<š¡
P¦ã4½õÜäbÄè˘Âîßéµà«6ïš/‘6Ü÷úæd²Ú™Ã“{™£Ò^ÔùáhÈFODú0Ä—LÃȹáF@.§6œdˆ
Éy0öŠ–Âã&ægPO@\°»Kû½¼“!|ÊD׊°Œ§Ú
(-‹aT§Ëˆ@ì?ô™§Íˆ€aÀ¯¤r~nRKeÜüûqðКˆÆÀ„¤:êðÅÒ~¹À’bqˆ=q£ ÏkFé†[õ`WÎ^"Ž—
wÀŒNç[¤?»õ¯2è·÷1Eú@.q‰9êN’çô–ÎWü2}(ûndàÆìo›Ü\•<“ÿnäD/>Œ2ÌLÈ^ôÏ
(‚h^JPŽ:+àZþÿ@4uyú(ÄÞ7¥—ÍØëÜ( ²Ù‰(ÚjøвбiŠàxG
¶Ë<·—œ—G±¤»¿™‘3}¬Ÿ QÛp?;e¤‘±Òê”q‘—˝®#ëIáè+Hw‹«™Ù7-IqR9’¶Ua\¤amùà½Ë´
=çŽ_äLžL¥ ›i-J7M+ä]‰EêA˝…w´%¯ô?(vìÍšÃ5ÿòjXUDTs›
ç›gI0“s„„îsEÌÇæÓ)è.Óá.—Žoì^nÌ˘' yE4ZÄ7nÒ|i˜!˜ÖóÀ×v‰ìêÌeMDÒ~:
'5ÂÇ$Ì÷×®º;eÓb®üv£xµïjw˝!¯0äRÔ$nÂn8žJ–p¹ã{&ºEÝí¹ÁèéÛZ”ùòÄ‹µ
1Pý§#`=žvS®.6ëÇDÐýšD8 ‡…§è|”ÈÙýZj5Þ,;À ]¥Nsa† Ô£Joß8ôÓ˜ŸÅq˜ÉŒDŒNˆ
9P몈Á$ú5QéÇ“Ø1n© Hy\¼mŸ 3|Un°¦úfìóÙÚ˜fGŸšàFá¤MÈëñËÅ˝Øz
,ïÈùзMýÚñ #|`=xîú´u`D%«pÜʧŠü–«£[u´8Àèfc®%+dd – ò`dmœPðªm…=´
{8b¢ƒDf=¤*w rè/ëˆaa5@¥#‰¢‘o©yÅƒä› n,6ÚÈ V‚ ‹„’ㆂƒ¬0ÊÈ÷È>êÆŽ9BJóñå’\\þ
[þã¦Í¶ø2ÇÞ}ÖËôÿþuÅ1E!…#»Ô=܉•‚ÇïÄ“¬ú?ˆ¿
[d¾WØÍÊ¡ìд?Î棚ê1Ml]þ$¹À`?£2ªuÒÔÁ"
\·yn{mÔóÆSPÁŒvÀwýă|;;©ñµBLQ±ñ1Ox!e}j!S’$H_TÂÖ åòä^ëðá¼.T˘C‡Æ·jÜEÇ
‘KHé›H g%q€Šv!Ø LÀo/D“ÛÙÁ'Ž’Œ¾ÀVú¢Ü˘l
;X©™OÿµÀâ¢I"Ô_…®°\vßœãý ñ®ŠÝáLQ`vCnü<¡<g6ãì@ÜhéÓZˆb[ÄPãj:%žù•MË´4wƒt
(Þb+¦ è<\›œŠàTú¾ö;ð 1ÚÅJ ’ó¢ïˆæ°Ý”§„Æ'ï¨Ê¿ü)MqåÝ
Œ:S‹-©¦RrÔå_÷OGÙ’ËÆìàgî2Š¿Á«œ‡!˝/<jï{oŠÕ¹Åæƒ5Í‘Á×NÍèoJWË b
“.טKû” vS˜;BP-ÄFë“\ùsO¿P…Ö‰ÒTY¶zÒh|ˆõBGÙr4Û[±„GÕnO
H¥d§+ÙŒf¨–Çûp“´ƒ¹?> fœ-kš;yÀ¯Þ'ä t¤ß²ÓC=܃òNú1åï²ÐLw9-
àãšó
¼²½Ð·Ï«y˝“¬63¾”äº{.ÀÉÙŒ%.ŒÝ›A‰+Ä´4ܬûÍ£!âóƒòœ× ܲtø´ÝÄŠÚ€=ŒáVE_ä(¿)
ºÂ&œÍüõ“Ë*si tb]ât²d¶ÉþÕÀÒå1q’È8ÉŒ?-
ýŠ¤p°•˜"Ã_î{÷©•Q6Œý^„ZsJô\êŸgåD5
@¹×¦4{w~nï"͆yŸÒ£ÈiÏžáÍlÿ`lÊN-b”ƒÈ{•Y´Äû‚92S6ELP”÷„Q¸Þz9|M¹›`
•NFTšÂ4é“÷ˆÁõnÍ2º(µ•D‚kžxꯅ”˘–ÒYÙ‚Å¥Ÿw^øF+JBÀÃ,óQ§Ù!§Èé-
²E_ž_çfî«Ç
‹Ð¡ÿ¬Ýø)#©ªÜz_Gö×Ê(¶“ÌTÆ}Ì\¢I‰_‡æ0éI ‡ØªÚÞý,Cvˆ/1¢KmMQï^&ÛÞNMäIÀ‹ÆHD
5ÆÏSÜáM˝â»Peʵ:ºRlëÛŒ-%®*Ä—~îÞâHb
"ø[~“-
óD?(˘#‘&;?(ò¦6‹ —Χ§ïãa®•ß«ãƒnNj…~„ºa¦Ö«jñ¬+“஘~èn0vñHÔ‹.
•oÌZá’?zu¬ì€ÑlhðHü3Í’ý¯ó¼—!grƒctã‘ágoÝ5÷þÙ¢*">#ô`¾3ëÑ~n˝[- ÿÌ°˘}
‰PVXsíÀ:¥Ú -É^jë¥üx‡vJ„†*ñZïÖ!=aGeºLÖ—:É{~–Ô±rfr9Ðà&¬S™˝+㬄ŽÒh
”A©Ë¤Ö7¡ÝŠâhGGŒ°5¼\u¾ø+qHï”{;"r¯d¾êˆëÑ ÕÕÒÒèŠ$ö–ëõ×!}¤Tw%]è@Âóý,
"×…ºQ*[öqðTSÌkºÀÖU1sÈûµ¦6Ýß l~œš¸¸è#¯£ýB%({þ¯l&×foPz¦ÖICkE¢¾Ø¾v.
”Â㇢ÆûB”Çk1§añ#áwaoߤý¿f˝Çá¹×ì¿!*)
*2*120.000*EA*001810033011****1.0000**CARDS&G83*3
*120.000*EA*001810033691****1.7500**CARDS&G83*4*24.000
*EA*001810033751****.8750**CARDS&G83*5*204.000*EA*001810041405
****1.4750**CARDS&G83*6*8.000*EA*001810044612****1.9750
**CARDS&G83*7*60.000*EA*001810045218****1.1250**CARDS&G83
*8*12.000*EA*001810057869****.6250**CARDS&G83*9*126.000*EA
*001810059319****1.4250**CARDS&G83*10*12.000*EA*001810038620
****1.9750**TY-WALLPAPER&G83*11*18.000*EA*001810058072
****1.7500**TY-BEAR HOLDING HEAR&G83*12*54.000*EA*001810028746
****.9750**CARDS&G83
*13*12.000*EA*001810059988****1.7500**TY-CUTE BEAR
RELEASI&G83*14*12.000*EA*001810029756****.4450**GE-WHITE ROSES
PHOTO&G83*15*12.000*&SE*2591*6300001&GE*1*666&IEA*01*000010734&
*12.000*EA*001810059988****1.7500**TY-CUTE BEAR
RELEASI&G83*14*12.000*EA*001810029756****.4450**GE-WHITE ROSES
PHOTO&G83*15*12.000*83*1*72.000*EA*001810006587****.4750**GREETING
CARD&G83*2*120.000*EA*001810033011****1.0000**CARDS&G83
*3*120.000*EA*001810033691****1.7500**CARDS&G83*4*24.000
*EA*001810033751****.8750**CARDS&G83*5*204.000*EA*001810041405
****1.4750**CARDS&G83*6*8.000*EA*001810044612****1.9750
**CARDS&G83*7*60.000*EA*001810045218****1.1250**CARDS&G83
*8*12.000*EA*001810057869****.6250**CARDS&G83*9*126.000
*EA*001810059319****1.4250**CARDS&G83*10*12.000*EA*001810038620
****1.9750**TY-WALLPAPER&G83*11*18.000*EA*001810058072****1.7500**TY-
BEAR HOLDING
HEAR&G83*12*54.000*EA*001810028746****.9750**CARDS&G83*13*12.000
*EA*001810059988****1.7500**TY-CUTE BEAR
RELEASI&G83*14*12.000*EA*001810029756****.4450**GE-WHITE ROSES
PHOTO&G83*15*12.000*&SE*2591*6300001&GE*1*666&IEA*01*000002749&
Topics in this chapter include:
l WebTrader overview on page 981
l Add a WebTrader partner on page 982
l Manage sponsor and trading relationships on page 984
l Manage trading restrictions on page 985
l Add a WebTrader user to a partner on page 990
l Delete a WebTrader user from a partner on page 991
l Add WebTrader user roles on page 992
l Set WebTrader password policy on page 993
l Additional WebTrader user management options on page 994
l Group WebTrader partners by category on page 994
l Enable trading with non-WebTrader partners on page 995
l Use the WebTrader partner search tool on page 996
l Activate self-registration for WebTrader partners on page 996
l Manage WebTrader p artner and community attributes templates on page 997
l Manage WebTrader d ocument attributes templates on page 1000
l Activate large message handling on page 1002
l Monitor WebTrader exchanges on page 1005
Terminology
These terms are used throughout this chapter:
l WebTrader - A web service hosted on the WebTrader sponsor's server.
l WebTrader sponsor - A web service provider who enables web trading through Interchange.
l WebTrader partner and user - An end user of WebTrader who connects to the Interchange
user interface through a web browser and a personal account.
WebTrader overview
To get started, a WebTrader partner needs a relationship with your Interchange community. The
community, acting as the sponsor, enables the web trader to log on to a user interface in a browser.
The sponsor's remote Interchange server (you) hosts the WebTrader session. Once logged on, a
WebTrader can send and receive documents with the sponsor or a partner in the sponsor's
community.
WebTraders can engage in various trading scenarios. Depending on the configuration, a WebTrader
partner may be allowed to trade only with the sponsor, with any partner in the sponsor's
community, or with a broader combination of sponsors, communities and trading partners. The
partners in the community can include other WebTrader partners or parties who trade other message
types through Interchange. The following are possible trading situations.
A WebTrader partner can trade with other WebTrader partners through the sponsor, which is
acting as a re-routing agent. This can be done only if the sponsor allows such trading to occur.
l Between a WebTrader partner and a non-WebTrader partner
A WebTrader partner can trade with a non-sponsor partner who uses Interchange or an
interoperable third-party B2B application. The sponsor must export the WebTrader partner's
profile to a file and give it to the remote partner to import into Interchange or otherwise set up in
the partner's third-party system. This type of trading can occur only if the sponsor allows it.
l Add a WebTrader partner on page 982
l Manage sponsor and trading relationships on page 984
l Add a WebTrader user to a partner on page 990
l Delete a WebTrader user from a partner on page 991
l Add WebTrader user roles on page 992
l Set WebTrader password policy on page 993
l Additional WebTrader user management options on page 994
l Group WebTrader partners by category on page 994
l Enable trading with non-WebTrader partners on page 995
l Use the WebTrader partner search tool on page 996
l Activate self-registration for WebTrader partners on page 996
If the sponsor requires WebTrader partners to set up their own profiles, skip this procedure and see
Activate self-registration for WebTrader partners on page 996.
Prerequisite
l Your Interchange license must include keys that enable the WebTrader functions.
l You must create a community to represent the sponsor.
Procedure
1. Log on to the Interchange user interface.
2. Select WebTrader manager > Add a WebTrader partner.
The WebTrader partner wizard is displayed.
3. Complete the fields of the Enter WebTrader partner info page:
l General information:
o Partner name - Enter a name to identify the WebTrader in the UI.
o Routing ID - Enter a routing ID to use when handling exchanges with this WebTrader.
o Document store - This is the directory on your file system where all documents that
the WebTrader sends and receives are stored. If you are running Interchange in a
multiple-computer cluster, the directory must be shared across the cluster. The default
directory is:
<install directory>\common\webtrader\<partner name>
l Create login credentials for the user:
o User ID - Enter an account name for the WebTrader partner. The WebTrader partner
uses this ID to log on to the UI.
o Password - Enter a password for the WebTrader partner. The WebTrader partner must
use this password to log on to the UI.
o Confirm password - Re-enter the password to confirm.
o Full name - Enter the full name of the partner that this account represents.
o Email address - Enter an email address for the WebTrader partner.
o Phone number - Enter a telephone number for the WebTrader partner.
o Send an email notification when a document is received from a partner -
(Optional) Select this option to inform the WebTrader partner when new documents are
available for reception.
The content of email notifications is controlled by the webtrader_email.xml file in
<install directory>\conf. Use the default configuration or edit the file to change
the message content. See the notes in the file for directions.
To enable notification by email, you must configure a global external SMTP server. To
configure the server, go to the System management page in the user interface and click
Configure the global external SMTP server. See the Interchange
Installation Guide for more information.
o Enable this user - Use this option to enable or disable this partner. Clear this option to
deactivate a user so the user can no longer log on. You can use this option when you
want to suspend, but not delete, a user.
o Force user to reset password upon initial login - For increased security, force
users to reset their default passwords.
l Choose a sponsor for this partner - From the list of available sponsors, select the
sponsor community for the WebTrader partner. The WebTrader partner becomes a member
of this community. Alternatively, you can elect to choose a sponsor at a later time.
l Choose the trading restrictions for this partner - the options are:
5. Communicate the following information to the WebTrader partner:
l The URL for connecting to the WebTrader log-on page in a browser.
l The user ID and password for logging on to WebTrader. Advise the WebTrader partner to
change the password after logging on for the first time.
l A list of the partners with whom trading is permitted. For example: sponsor only; sponsor
and other WebTrader partners; sponsor, other WebTrader partners and non-WebTrader
partners.
Communities tab – Use this tab to select the communities with whom the WebTrader partner
can trade. You can select multiple communities from the displayed list. The WebTrader partner
can trade with all members of all the communities you select, unless privileges are limited on
the Trading restrictions tab. If no communities are selected, the WebTrader partner can
trade only with its sponsor.
Sponsor tab – Use this tab to select the community sponsor for the WebTrader partner. A
WebTrader partner can have only one sponsor.
Trading restrictions tab – From this tab you can select or deselect the following options:
l Allow trading with all members of subscribed communities
l Allow trading with the sponsor only
l Allow trading with all members of subscribed communities. In addition, any
WebTrader that has been limited to trading with the sponsor will be allowed
to trade with this WebTrader as well
For detailed descriptions of how to apply WebTrader restrictions, see Manage trading
restrictions on page 985.
4. Click Save changes.
1. Allow trading with all members of subscribed communities
2. Allow trading with sponsor and any sponsor representatives (default)
3. Allow trading with all members of subscribed communities and also assume the role of sponsor
representative – This restriction enables any WebTrader user with restriction #2, and with the
same Sponsor, to trade with you.
Restriction descriptions
l Trade with all members of subscribed communities
l Trade with other WebTrader and non-WebTrader trading partners that are members in their
subscribed communities
l Trade with the community sponsor in their subscribed communities
When the WebTrader user sends documents, the WebTrader interface displays list of allowed
recipients. This list is populated according to the following rules:
l The recipient list comprises all members (WebTraders, remote partners, community sponsors)
that are in their subscribed communities
A WebTrader with this trading restriction can:
l Trade with the sponsor community
l Trade with the sponsor representatives in their sponsor community
A WebTrader with this trading restriction cannot:
l Trade with other partners or WebTraders outside their sponsor community
l Trade with communities to which they are subscribed but to which they are not sponsored
When the WebTrader user sends documents, the WebTrader interface displays list of allowed
recipients. This list is populated according to the following rules:
l The recipient list comprises members (community sponsor or sponsor representatives) that are in
their sponsor community
l Trade and allow trading with WebTraders with the same sponsor and with trading restriction (#2
above)
l Trade with all members of subscribed communities
l Trade with WebTrader and non-WebTrader trading partners that are members of subscribed
communities
When the WebTrader user sends documents, the WebTrader interface displays list of allowed
recipients. This list is populated according to the following rules:
l The recipient list comprises all members (WebTraders, remote partners, and community
sponsors) that are in their subscribed communities
Restriction example 1
Use case:
l WT1 is the member of a single community, Community A.
l WT1 has Community A for sponsor.
l WT1 is assigned restriction #1: "Allow trading with all members of subscribed communities"
l A set of trading relationships are configured as illustrated in the following figure:
Result:
WT1 can trade with:
l WT2 l SPA
l WT3 l P1
Restriction example 2
Use case:
l WT2 is the member of a single community, Community A.
l WT2 has Community A for sponsor.
l WT2 is assigned restriction #2: "Allow trading with sponsor and any of that sponsor's
representatives"
l A set of trading relationships are configured as illustrated in the following figure:
Result:
WT2 can trade with:
l SPA
l WT3
Restriction example 3
Use case:
l WT3 is the member of a single community, Community A.
l WT3 has Community A for sponsor.
l WT3 is assigned restriction #3: "Allow trading with all members of subscribed communities and
also assume the role of sponsor representative"
l A set of trading relationships are configured as illustrated in the following figure:
Result:
WT3 can trade with:
l WT1 l SPA
l WT2 l P1
Restriction example 4
Use case:
l WT2 has Community A for sponsor and is additionally subscribed to Community B.
l WT2 is assigned restriction #2: "Allow trading with sponsor and any of that sponsor's
representatives"
l A set of trading relationships are configured as illustrated in the following figure:
Result:
WT2 can trade with:
l WT3
l SPA
Restriction example 5
Use case:
l WT4 has Community B for sponsor and is additionally subscribed to Community A.
l WT4 is assigned restriction #1: "Allow trading with all members of subscribed communities"
l A set of trading relationships are configured as illustrated in the following figure:
Result:
WT4 can trade with:
l WT1 l P1
l WT2 l P2
l WT3 l SPA
l WT5 l SPB
Restriction example 6
Use case:
l WT5 has Community B for sponsor and is additionally subscribed to Community A.
l WT5 is assigned restriction #3: "Allow trading with all members of subscribed communities and
also assume the role of sponsor representative"
l A set of trading relationships are configured as illustrated in the following figure:
Result:
WT5 can trade with:
l WT1 l P1
l WT2 l P2
l WT3 l SPA
l WT4 l SPB
To add additional users to a WebTrader partner:
This field does not appear if you have implemented single sign on.
l Full name – Enter a friendly name for the additional user.
l Email address – Enter an email address for the WebTrader user.
l Phone number – Enter a telephone number for the WebTrader user.
l Send an email notification when a document is received from a partner –
Optionally select this option to inform the WebTrader user when new documents are
available for reception.
The content of email notifications is controlled by the webtrader_email.xml file in
<install directory>\conf. Use the default configuration or edit the file to change the
message content. See the notes in the file for directions.
To enable notification by email, you must configure a global external SMTP server. To
configure the server, go to the system management page in the user interface and click
Configure the global external SMTP server.
l Enable this user – Select this option to enable this user for use after the creation process.
l Force user to reset password upon initial login – Select this option to enforce a
password change requirement.
l Provide name about an alternate contact – Complete the following fields if you to
add additional contact information for this user.
o Full name
o Phone number
o Email address
o Note (Up to 110 characters of additional textual information)
l Choose the roles this user should have – From the list of available roles, select a role
for the current user.
5. Click Add this user.
By default, Interchange provides a single WebTrader role named WebTrader user. To view this
role, from the WebTrader manager menu, select Manage WebTrader user roles. This role
provides all of the permissions available to WebTrader partner users. To view the list of permissions,
double-click the WebTrader user item in the Roles list. The following permissions are listed:
l Basic viewing and management. All WebTrader users must have this permission.
o Change email notification state
o Create, delete and rename folders
o Delete and rename documents
o Download documents to view their contents
o Send documents
You can modify this role. You can create additional roles with different sets of permissions for
different groups of users. A single user can have no roles (no rights), a single role or multiple roles.
The WebTrader users screen is displayed. This screen lists the users who are authorized to log
on to WebTrader as representatives of the WebTrader partner.
3. In the users list, click the name of a user for which you want to change roles.
The change WebTrader user screen is displayed.
4. Select the Roles tab.
5. From the list of roles, add or remover roles for the user by selecting or clearing the check boxes.
A user can have no roles (no rights), a single role or multiple roles if multiple roles exist.
6. Click Save changes.
o Enable/disable status
o Password change requirement
l Alternate contact tab - Use this tab to add or modify alternative contact information
about the user.
l Roles tab– Use this tab to assign or remove user roles. See Additional WebTrader user
management options on page 994.
l Date/Time tab – Use this tab to select the time zone displayed in the user's interface view.
l Sponsor tab – View contact information about the current sponsor.
5. After making any modifications, click Save Changes. To close this screen without making any
changes, click Cancel.
For a review of how to create and manage partner categories, see Group partners by categories on
page 158.
Add a category
1. Select Partners > Manage categories to open the Categories page.
2. Select Add a category to open the Add a category page.
3. Enter a category name for your WebTrader partners.
4. Optionally, for a regular category, select a parent category.
5. Click Add to create the category.
4. Contact the WebTrader partner and provide the URL for connecting to the WebTrader log-on
page in a browser. Also provide the user ID and password for logging on to WebTrader. Advise
the WebTrader partner to change the password after logging on the first time.
The search tool is located in the left panel of the WebTrader Partners page. If the search panel is
hidden, click the SHOW/HIDE tab to display it. By default, this page lists all partners, regardless of
community membership
You can launch searches that use any combination of the following criteria:
l WebTrader partner name
l Routing ID
l Community to which the WebTrader is attached
l Sponsor community
l Category membership
l Custom attributes
You can use wildcard characters "*" and "?" for searches. You can combine wildcards with partial
names. For example *part* would return MyWebTraderPartner if such a partner existed.
Searches are not case sensitive.
You also can specify how many columns of information to display for the WebTrader partners found
in a search. In addition to the partner name column, you can display:
l Default routing ID
l Default protocol
l Default transport
l Contact
l Categories
l Communities
As the WebTrader sponsor, you must activate the service on the Interchange server, and
communicate the access password to your WebTrader partners.
Prerequisite
The webtraderSelfRegistration key in the Interchange license.xml file must be enabled.
Procedure
Complete the following steps to enable your WebTrader partner users to self register.
The variable <host> is the fully qualified domain name or IP address of the computer
running Interchange.
l User name and password — The user name and password the partner must use for
logging on to the registration wizard. This is webtrader and the password you specified.
l Community name — The name of Interchange sponsor community the partner must
select when registering.
After a WebTrader registers using the wizard, Interchange creates a file system delivery exchange for
the WebTrader with the following path: <install directory>\common\webtrader\<partner
name>.
You can use these attributes in two general situations:
l Searching for objects – The search pages of both the Administration interface and of the
WebTrader end-user interface include an attribute name and value filter, so you can search for a
particular object that has a particular attribute or a particular attribute value.
l Message handling – You can use these attributes as you do any other metadata attributes in
Interchange - for message-handling. For example, you could configure routing or processing
only if a specific metadata attribute/value is detected.
After you create either a partner or community attribute, you can change the display order of the
attribute list on the Manage partner and community attributes template page using the following
procedure:
3. On the Manage partner and community attributes template page, select either the up or down
arrow of any attribute to change its position in the list.
3. From the list of templates, locate the name of the template you want to remove, and click
Delete on that line.
The following message is displayed: Are you sure you want to delete this attribute?
4. Select OK to delete the attribute or Cancel if you don't want to delete the attribute.
On the WebTrader user side, WebTrader end-users see the metatdata you attach to their exchanges
in several ways:
l When sending documents, the interface displays additional attribute fields that WebTrader users
may (or may not depending on your configuration) be required to complete before sending a
document.
l The attributes and their values are listed in the table of the Sent folder.
l The attributes and their values are listed in the table of the Inbox folder.
l When using the document search tools, additional filtering criteria are available for locating
documents with associated attributes.
For example, a WebTrader user may wish to search among received documents for documents
that share a common attribute such as "Company Name" or "Priority". You can create a
document template that attaches these attributes to transferred documents and then appears as
informative and searchable information in the WebTrader user interface.
On the server side, you can use the metadata that is attached to WebTrader documents to determine
how documents are routed and processed.
To do this you:
l Provide WebTrader users with licenses in which the webtraderAppletForLargeFiles key is
enabled.
l Enable a Secure file HTTP or HTTPS trading pickup on your WebTrader sponsor community.
When Secure file is enabled on the sponsor community, the sponsor's WebTrader partners use a
dedicated applet to upload documents to the sponsor's server through the Secure file trading
pickup.
To enable a Secure file trading pickup, see Secure file message protocol on page 971.
l Use staged HTTP web servlet
l Define a new embedded HTTP or HTTPS server
8. Complete the remaining screens, depending on the transport type you selected on the previous
screen.
9. Set the exchange to active status. Uploads and downloads work on HTTP and HTTPS
connections.
If you, as the WebTrader sponsor have a license with the webtraderAppletForLargeFiles key
enabled, but you have not enabled Secure client on your sponsor community, the partner will see
the following message displayed on their Send documents page:
When this message is displayed, the WebTrader partner can continue to send documents of less
than 10 MB.
After the applet is downloaded:
l The configuration error message is no longer displayed.
l When the WebTrader user sends files, an Upload Progress window reports upload progress
and warns the sender not to close the browser until the a server response acknowledges the
send. The user must manually close this window to continue working in the interface.
l When selecting messages to send, the WebTrader can select a directory. Interchange then
compresses all files in the directory into a ZIP or TAR file for transmission.
File chunking
WebTrader engages chunking for uploads and downloads of files larger than 2 gigabytes. Chunking
is disabled for smaller payloads.
To activate chunking for all uploads and downloads, set the following property to true:
httpChunkingAlwaysOn=true
Add the property to the applet.properties file.
In Windows the file is on the client WebTrader’s computer at:
In UNIX or Linux the file is on the client WebTrader partner's computer under the user’s home
directory. The file may be hidden. Use the ls –a or ls -la command to reveal hidden files.
The applet that manages uploads and downloads only creates an applet.properties file as
needed. If the file exists, the WebTrader partner can add the property and value to the file. If the file
does not exist, the WebTrader can create a file by that name and add the property and value to it.
<!--
Specify maximum allowed size of the upload.
Defaults to 50 Mb.
-->
<init-param>
<param-name>upload-max-size</param-name>
<param-value>52428800</param-value>
</init-param>
4. Save the file.
5. Restart Interchange for the change to take effect.
Note This value is not conserved on upgrades. If you upgrade your Interchange installation you
will need to reset this value in the upgraded file.
For details of how to use Message Tracker, see Message Tracker on page 826.
For more information, refer to the Java website under the topic of "How do I enable Java in my web
browser?"
Note This download requires, as a prerequisite, that the appropriate Unlimited Strength policy
files exist in the following folder of the WebTrader-licensed Interchange server:
.../Interchange/webapps/wtapplet/jcepolicy
The download of these policy files succeeds but, in typical WebTrader client configurations, the
policy files cannot be copied to the local destination directory ...\Java\jre\lib\security and
an "Access denied" error can be viewed by running a debug on the applet code.
The reason for the failure is that the JRE (by default) is located in the C:\Program Files or
C:\Program Files (x86) folder which is write-protected by Windows User Account Control.
To view the progress of the policy down load you can open a Java console.
l A client machine user with administrator privileges can disable the UAC write protection on the
jre\lib\security folder.
l The WebTrader end user can start the web browser in administrator mode. To do this:
1. Locate the browser command in the Windows Start menu.
2. Right-click the command.
Standards certification
The Interchange trading engine has been certified for
interoperability for AS1, AS2, AS3, AS4, and ebXML. See
http://www.drummondgroup.com for a list of software the
trading engine has been tested with successfully for
interoperability.
Concepts
l Overview of CSOS functionality on page 1009
l CSOS in Interchange on page 1010
l CSOS configuration for sending on page 1011
l CSOS configuration for receiving on page 1012
l About CSOS roles on page 1013
l CSOS WebTrader on page 1014
Procedures
l Import CSOS signing certificate on page 1021
l CSOS certificate revocation lists on page 1021
l Identify CSOS purchase orders on page 1022
l Link EDI 855 PO Acknowledgement to 850 PO on page 1026
l Sign pending orders on page 1028
l Configure PKCS#7-encrypted XML trading on page 1030
For users who receive signed controlled substance orders from partners, Interchange validates the
orders as authentic and unaltered.
When Interchange validates the signature of received orders, it checks the signer's certificate against
a DEA list to make sure the certificate has not been revoked. This is done using a certificate
revocation list (CRL). The CRL is issued and updated by the DEA. Interchange has the ability to
retrieve the CRL over the Internet.
After authenticating the received order, Interchange makes a back-up copy of the order and the
public key and certificate. The default behavior of Interchange is to back up received messages, but
make sure backing up is enabled for the delivery exchange for receiving messages from partners to
ensure CSOS compliance.
Before configuring Interchange to handle CSOS orders, your organization must comply with the
DEA’s rules for CSOS participants, including obtaining a digital signing certificate from the DEA. For
DEA information about CSOS, go to http://www.deaecom.gov/qanda.html.
Security
CSOS extends the FIPS standard (see FIPS compliance on page 781) and installs a separate set of
security libraries in the following directory:
<INSTALL_DIR>/corelib
CSOS relies on digital certificates using secure hash algorithm (SHA) technology to ensure order
security, which includes the SHA-1 and SHA-256 standards. Beginning in 2014, the DEA will require
that orders are signed with SHA-256 certificates. To support your organization during the transition
period, Axway CSOS enables you to use SHA-1 or SHA-256. Be sure your trading partners are using
the same standard.
CSOS in Interchange
The following figure illustrates how CSOS functionality works in Interchange according to the
following scenario.
The following illustration shows the flow of CSOS orders.
1. A back-end ordering system generates a purchase order that conforms to CSOS standards.
2. Interchange picks up the document. Recognizing it as a CSOS order, Interchange places the
document in a signing queue. This action suspends the usual processing routine of packaging
documents for sending to partners. Only the documents you want are handled in this manner.
Other documents are not affected.
3. A CSOS user logs on to Interchange user interface to check for CSOS orders awaiting approval.
4. The users views CSOS purchase orders that were delivered and need approval.
5. The user types a password and approves the order. This action results in Interchange using the
user’s private key to digitally sign the order.
6. The signed order is released for Interchange to continue outbound processing to the partner
vendor.
7. The partner’s system, upon receiving the signed order, verifies the signature using DEA-issued
root and intermediate certificates. The receiver also checks whether the DEA registration
number is the same in the order and the root certificate. Orders that fail verification are rejected.
For orders that pass verification, an acknowledgement is returned.
1. Install Axway CSOS. Follow the instructions in the Interchange documentation to set up a
community and at least one partner. See Add a community on page 136 and Add a partner to a
community on page 148.
A partner is a pharmaceutical supplier that will receive your orders.
2. Select Users and roles > Add a role in the user interface.
3. Type the name for the role. This is the role to assign to the users who log on to view CSOS
orders and sign orders using a DEA-issued signing certificate.
At minimum, select the permission Approve CSOS orders for the role. You can grant other
permissions, depending on how much latitude you want to give to CSOS order signers. You
may not want to give the role the same permissions as the administrator role. For more
information, see About CSOS roles on page 1013 and Role permissions on page 118.
Click Add this role to create the role.
4. Select Users and roles > Add a user.
5. Add the user account for the person who is to log on and sign CSOS purchase orders with a
signing certificate. Assign the user to the CSOS role you added in step 3.
a. Select Send a daily e-mail notification with the number of orders that are in
my signing queue.
b. Set the time for the daily e-mail notification.
c. Click Save.
10. Add the following document type(s) to configure the display of CSOS purchase orders
Document type: 850 Document type: 855 (Optional*)
Name: CSOS 850 Name: CSOS 855
Description: CSOS 850 purchase Description: CSOS 855 purchase order
order acknowledgement
Stylesheet: e222.xsl Stylesheet: 855EDI.xsl
How to view documents: Formatted How to view documents: Formatted through
through use of a stylesheet use of a stylesheet
*Add the 855 document type if you plan to configure Axway CSOSto associate each 855
purchase order acknowledgment your system receives back from a supplier with the original
PO. This enables you to see that each order was authenticated and processed successfully.
11. Configure Interchange to identify outbound CSOS orders and place the documents in a queue
for signing. See Identify CSOS purchase orders on page 1022.
12. Display and approve the orders in the user interface. See Sign pending orders on page 1028.
1. Install Axway CSOS. Follow the instructions in the Interchange documentation to set up a
community and at least one partner. See Add a community on page 136 and Add a partner to a
community on page 148.
A partner is a retail pharmacy or wholesaler that will send you orders.
2. Download the latest DEA/CSOS CA root certificates and intermediate certificates from the DEA
CSOS website at http://www.deaecom.gov/, under the Certificate Management section. These
are required to verify the authenticity of the inbound signed CSOS documents. Use one of the
following methods to import the certificates:
l Automatic import – See Auto import intermediate and root certificates on page 780.
After following the instructions, restart the server.
l Manual import – From the Trading configuration menu, click Manage trading
configuration. Select your community and click Certificates in the graphic. Under
Related tasks, click Add a trusted root certificate. Use the wizard to import each
certificate.
3. Verify CRL checking is active. See CSOS certificate revocation lists on page 1021.
4. Add the following document type to configure the display of CSOS purchase orders.
Document type 850
Name CSOS 850
Description CSOS 850 purchase order
Stylesheet e222.xsl
How to view documents Formatted through the use of a stylesheet
5. Configure Interchange to identify CSOS orders received from partners. See Identify CSOS
purchase orders on page 1022.
Axway does not recommend you give any CSOS user administrator privileges. The following CSOS
order access applies to a user with administrator privileges who does not have an installed DEA
certificate:
l Ability to view all pending orders
l Ability to reject any order
l No ability to approve orders
l Ability to add/edit Notes, Quantity Received, and Date Received on all processed orders
If the user with administrator privileges does have an installed DEA certificate, the following CSOS
order access applies:
l Ability to view orders matching the user's DEA certificate(s) only
l Ability to reject visible orders only
l Ability to approve (with password) orders containing the user's DEA certificate number only
l Ability to add/edit Notes, Quantity Received, and Date Received on all processed orders
CSOS WebTrader
The previous topics explain CSOS functionality as incorporated into Interchange. There is another,
lightweight way to move CSOS orders. That is by using WebTrader.
WebTrader is a way to move documents between a partner equipped only with a computer, a
browser and an Internet connection and a partner who uses Interchange.
In a CSOS context, WebTrader has a specific role. That is to digitally sign purchase orders with the
browser user’s certificate, in compliance with federal regulations. This is performed as one step in an
interactive pharmaceutical ordering process. Much of this process can take place outside of
WebTrader. WebTrader only comes into play in the step where signing is required.
The following outlines such a scenario. In this example, a retail pharmacy plays the role of
WebTrader. A pharmaceutical distribution company is the partner who uses Interchange as its B2B
gateway and is the WebTrader sponsor.
1. Using a browser, the pharmacy logs onto the distribution company’s pharmaceutical ordering
web site.
2. The pharmacy selects items to order. The ordering system constructs a CSOS purchase order
based on the selected items.
3. The pharmacy completes its order selection.
4. The ordering system routes the purchase order document file to Interchange, which in turn
routes the document to the pharmacy’s WebTrader in-box. At this point, the document file is
located on the file system used by the Interchange server and not the pharmacy’s computer.
5. The pharmacy views its WebTrader in-box, which lists the purchase order.
6. The pharmacy selects the purchase order and launches a process to sign the order with a
personal certificate. The document is downloaded from the server to the pharmacy’s computer,
signed and uploaded to the server. Downloading is necessary because the purchase order must
be in the pharmacy’s physical possession during signing.
Depending on how WebTrader is integrated in the ordering process, the pharmacy may be
unaware Interchange and WebTrader are involved. From the browser user’s point of view, the
signing step may appear as part of the distribution company’s ordering web site. For more
information, see Use the CSOS applet on your web page on page 1015.
7. Interchange unpacks and verifies the uploaded signed purchase order.
8. Interchange routes the purchase order to the distribution company’s ordering system or
whatever destination is configured.
http://<host>:6080/wtapplet/csos/testCsosApplet.html
The variable <host> is the IP address or fully qualified domain name of the machine running
Interchange server.
Web traders’ must have JCE policy files added to the JRE plug-in for their browsers (see WebTrader
partner requirements on page 1017). Web traders can perform this task manually. Or, you can use
the applet’s policy installer. This automatically installs the JCE policy files in a user’s browser when
testCsosApplet.html is run. The README.html file has more information. Before version 5.5.1,
installing JCE files was solely a manual process.
Note This download requires, as a prerequisite, that the appropriate Unlimited Strength policy
files exist in the following folder of the CSOS licensed Interchange server:
.../Interchange/webapps/wtapplet/jcepolicy
The download of these policy files succeeds but, in typical client configurations, the policy files
cannot be copied to the local destination directory ...\Java\jre\lib\security and an "Access
denied" error can be viewed by running a debug on the applet code.
The reason for the failure is that the JRE (by default) is located in the C:\Program Files or
C:\Program Files (x86) folder which is write-protected by Windows User Account Control.
To view the progress of the policy down load you can open a Java console.
2. Select the Advanced tab.
3. Select the option Java console > Show console.
4. Click OK.
With the console activated, you can view details of the Unlimited Strength Policy download failure.
l A client machine user with administrator privileges can disable the UAC write protection on the
jre\lib\security folder.
l The CSOS/WebTrader end user can start the web browser in administrator mode. To do this:
1. Locate the browser command in the Windows Start menu.
2. Right-click the command.
3. Select Run as Administrator.
4. Open a CSOS/WebTrader session.
Sponsor requirements
To establish a relationship with a WebTrader partner, an Interchange sponsor must first have its own
community. Next, the sponsor must add a partner for the WebTrader partner. There are two ways to
do this. The sponsor can manually add the partner or direct the WebTrader partner to a self-
registration web site hosted on the Interchange server.
To manually add a WebTrader partner, see Add a WebTrader partner on page 982.
To direct a WebTrader partner to a self-registration web site, see Activate self-registration for
WebTrader partners on page 996.
In your community, set up an application pickup that forces the sender to be the WebTrader partner
and the receiver to be your community. You can do this using the From routing ID and
To routing ID attributes on the message attributes tab of the exchange’s maintenance page. See
Message attributes tab on page 206.
You also need to set up a CSOS order source. See Identify CSOS purchase orders on page 1022.
Once configuration is completed, copy a purchase order document to the application pickup
directory. Interchange consumes the message and writes it to the WebTrader’s document store on
the file system used by Interchange. Typically, WebTraders’ document stores are under <install
directory>\common\webtrader. Message Tracker reports the message as delivered to the
WebTrader partner, although the document file remains on the sponsor’s file system. See Approve
CSOS documents in WebTrader on page 1018 for the WebTrader’s steps to approve and sign the
document.
You can do the following to check the browser for the JRE plug-in and obtain and deploy the JCE
files. An applet also is available to check whether the JCE files are deployed. If the files are missing,
the applet installs them.
http://java.sun.com/j2se/1.5.0/download.jsp
You can download the JCE files on the same page you downloaded the JRE. However, you can skip
this manual process by using the applet to check whether a browser has the JCE files and install
them for you if missing.
Caution If you use Windows, you must deploy the JCE files after installing the JRE the first time and
re-deploy the files each time after installing a JRE upgrade. WebTrader fails if the JRE is
upgraded but the JCE files are not re-deployed. If your computer checks for automatic JRE
updates, you may want to turn off that feature.
Once you have downloaded the JCE files do the following:
1. Unzip the downloaded jce_policy-1_5_0.zip file. This unzips to a folder named jce that
contains four files:
l COPYRIGHT.html
l local_policy.jar
l README.txt
l US_export_policy.jar
You only will use the JAR files.
2. Open the security directory of JRE 1.5.0_05 or later. On Windows this is typically:
C:\Program Files\Java\jre1.5.0_05\lib\security
3. Rename the two JAR files in the security directory in case you need to use them later. These are
local_policy.jar and US_export_policy.jar.
4. Copy local_policy.jar and US_export_policy.jar from the jce folder to the security
directory.
1. Log on to WebTrader with your user ID and password.
2. Check the inbox for documents awaiting approval.
3. Click Approve to display the Approve CSOS order page.
4. Under select a signing certificate, if a certificate is not already selected, click Browse and locate
a signing certificate on your file system.
5. Click Approve to display a dialog box for entering the certificate’s password.
6. Type the password and click OK. An approving purchase order dialog box appears, reporting
the progress of the signing. In this process, WebTrader downloads the document from the
Interchange server, signs the document with the private key in the certificate and uploads the
signed document to the server.
A copy of the signed document is kept on your computer in your Java user home directory. On
Windows, typically this is at:
C:\Documents and Settings\<user ID>\.cyclone\csos_backup
7. Click Close to close the dialog box.
The signed document is listed in the WebTrader p artner's sent folder. Click the Details link for
information about the signed document or to view it.
Message Tracker on the sponsor’s Interchange system reports the document as sent by the
WebTrader p artner to the sponsor’s community or re-routed by the sponsor to a third-party.
A chunked message is a large message broken into smaller pieces for sending to a partner.
The applet on its own chunks messages larger than 2 gigabytes. However, a parameter named
httpChunkingAlwaysOn is available to enable chunking always. A value of true for this
parameter enables chunking in the HTTP client regardless of the size of the uploaded payload.
The applet breaks messages into chunks of 64KB. So a file must be larger for chunking to occur.
There are two ways you can use the parameter to enable HTTP chunking.
After adding the parameter, reload the page for the change to take effect.
2. Applet properties file – The second option is a client-side change.
After you run the signing upload applet and sign a document, a file named applet.properties
appears in your Java user home directory. If you use Windows, your user home directory is your
personal directory in C:\Documents and Settings. In your user home directory is a
subdirectory named .cyclone. In that directory is a file named applet.properties.
Close all browser windows. Add the following line to the applet.properties file:
httpChunkingAlwaysOn=true
Then point your browser at the page with the applet and try uploading.
Caution The pfx or p12 file that DEA provides contains your private encryption key. Make sure to
securely protect this file. Do not share it with anyone.
Whether you are sending or receiving signed orders, you need to have CRL checking in place. With
CSOS functionality enabled in your user license, CRL checking is active by default. Interchange
reads a URL in the CSOS user certificate and downloads a CRL to use in checking for invalid
certificates. CRL files are stored in <install directory>\common\conf\crls.
To verify CRL checking is active, click System management on the top toolbar in the user
interface. Click the task Manage CRLs and then Manage CRL usage and retrieval. Make sure
the following options are selected: Require CRLs and Automatically retrieve CRLs.
For more details about CRLs, see Manage certificate revocation lists (CRLs) on page 802 .
l Order identification tab – If you send or receive signed orders, you must identify CSOS
documents on this tab.
l Order sources tab – Whether you should use the Order sources tab depends on your situation.
For instance, if you receive CSOS orders via certain message protocols — AS1, AS2, Secure file,
Secure e-mail, ebXML — a content MIME type of application/x-csos-signed-order is
included in inbound message headers. This triggers Interchange to validate and unpack the
inbound messages as CSOS documents, and using the Order sources tab is unnecessary. On the
other hand, if you send CSOS orders, you can use the Order sources tab to specify a particular
integration exchange for picking up documents identified on the Order identification tab.
l Related documents tab – This tab enables you to identify documents in the backup directory and
database records that need to be retained for as long as CSOS orders. The DEA requires a
minimum retention of two years for CSOS orders and related documents. You can also use this
tab to link EDI 855 PO acknowledgements to 850 POs. See Link EDI 855 PO Acknowledgement
to 850 PO on page 1026.
l CSOS duplicate orders tab – This tab enables you to specify whether to accept or reject duplicate
CSOS orders.
1. Choose one of the following methods:
l To specify that only 850s that meet certain conditions are handled as CSOS documents, click
Add an EDI document identifier. For each XPath field, enter the appropriate XPath segment
or c lick the ellipse (...) button to use the wizard to select the XPath segment from your sample
850 file.
l CSOS configuration for sending on page 1011
l CSOS configuration for receiving on page 1012
3. Click Save.
4. Click Test and follow the instructions in the wizard to select your sample 850 file. Use the test
results to determine if the XPath segments you configured are correct.
l CSOS configuration for sending on page 1011
l CSOS configuration for receiving on page 1012
3. Click Test and follow the instructions in the wizard to select your sample XML file. Use the test
results to determine if the XPath segments you configured are correct.
4. Click Save.
Whether you should use the Order sources tab depends on your situation. For instance, if you
receive CSOS orders via certain message protocols — AS1, AS2, Secure file, Secure e-mail, ebXML —
a content MIME type of application/x-csos-signed-order is included in inbound message headers.
This triggers Interchange to validate and unpack the inbound messages as CSOS documents, and
using the Order sources tab is unnecessary. On the other hand, if you send CSOS orders, you can
use the Order sources tab to specify a particular application pickup for picking up documents
identified on the Order identification tab. For instance, you may want to specify one application
pickup for CSOS EDI 850 documents if your company also sends non-CSOS EDI 850 documents.
To add an order source:
This default choice means:
l If sending orders – All purchase order documents defined on the Order identification tab
are picked up from any application pickup and queued for signing.
l If receiving orders – All purchase orders defined on the Order identification tab and
received from any partner are unpacked, validated against the root certificate for the user’s
signature and DEA registration number, and routed to an application delivery.
2. To configure more specific conditions, click on the Purchase order picked up, sent from,
or sent to field on the CSOS Orders sources tab. This opens a wizard that lets you choose
application deliveries (inbound or outbound transports) and parties (communities or partners).
The following table shows example configurations.
3. Once you have made your selections, click Save.
You can specify multiple sources, but take care not to set up overlapping conditions. Once
added, you can change or delete a source by using the appropriate buttons. When sending
orders, purchase orders are plucked from the normal processing routine of Interchange and
queued for signing. Once signed, the messages are placed back in Interchange flow. For
example, if you choose file system application pickup as the message source and any party as
the sender and receiver, all properly formatted purchase orders defined on the Order
identification tab are queued for signing. All other EDI documents and document types (XML
and binary) are ignored. Once signed, the orders are placed back in Interchange flow for
packaging and sending to partners.
This tab is similar to the Order identification tab. An important difference is that when you click Add
an EDI document identifier, you can type an EDI document type number in the Identity
XPath/Document number field rather than specify an XPath. This tells Interchange that all EDI
documents of that type are CSOS related.
When identifying related documents, specifying XPaths for a DEA Number and Order Number are
optional. But doing so helps to link CSOS orders and related documents in Message Tracker.
The age of messages and database records to purge normally is set on a global purge configuration
page in the user interface. CSOS orders and related documents have a minimum expiration of two
years, regardless whether the global purge age is less than two years. If the global purge age is set to
more than two years, CSOS orders and related documents are retained for the longer period.
For information about global purge configuration, see Data storage, backups, and purging on page
849.
If your community only sends signed orders but does not receive any, duplicate checking is not
applicable and you can ignore this tab.
The target documents are the EDI or XML documents defined on the Order identification tab.
By default, the radio button for rejecting duplicate purchase orders is selected on the CSOS
duplicate orders tab. When selected, Interchange checks whether an order duplicates a previously
received order in the following ways:
l Duplicate order number
l Duplicate DEA registration number
l Duplicate sender name
l Duplicate receiver name
If all of these values are the same as those in a previously received order, the document is given a
failed status. You can search for failed documents in Message Tracker on page 826.
If you also have configured Interchange to check for duplicate EDI documents, checking for
duplicate CSOS orders is performed in addition to the duplicate EDI checking.
Aside from choosing whether a community can allow or reject duplicates, you can set up exceptions
to the selected behavior on a per-partner basis. Whether you choose to reject or allow duplicate
orders, the choice applies to all orders received for the community, unless you define partner-
specific exceptions.
Note that the CSOS duplicate order tabs can be found on two pages in the user interface. One
location is the identify CSOS purchase orders page at CSOS > Configure CSOS. The other is the
message validation rules page, which is opened by clicking Message validation on the navigation
graphic at the top of a community summary page. To configure CSOS duplicate checking, you only
need to use one of these pages.
Performing this configuration requires some familiarity with XML Path Language (XPath). Before you
begin, ensure you have a sample 855 document in your file system that is structurally identical to
the actual documents to be processed. Review the sample for the data to parse so that you are
prepared to enter this information. You can either enter the XPath segments directly, or use a wizard
to temporarily transform your sample EDI document to XML and select each segment.
To configure 855 acknowledgements as related documents:
1. If the Identify CSOS purchase orders page is not already open, on the CSOS menu, click
Configure CSOS.
To view the updated purchase order:
1. Use Message Tracker to locate a CSOS purchase order.
2. Click the Details link.
3. On the Document Summary tab, View received payload.
The Quantity Confirmed column displays the information that was confirmed in the 855
purchase order acknowledgment. If necessary, you can click the Edit button at the bottom of
the page to modify the Quantity Received and Date Received, and to add any notes.
1. Log on to the user interface and check whether any CSOS orders are awaiting your signature.
The system generates an alert when CSOS orders are awaiting signature. You also can check for
pending orders by selecting CSOS > View pending orders on the toolbar.
Any orders in the signing queue that include your DEA number are listed.
2. If needed, use the following features to limit the list of orders:
l Click the Show/Hide vertical tab to display the Search pane. Enter criteria such as the
order number or a date range and click Find.
l To sort the results, click any column heading.
3. Click the date of a pending order to display it on the approve CSOS order page.
4. Review the order. Perform one of the following:
l To abort signing the order, click x. This message displays: SigningAborted. Click Ok.
l If the document is satisfactory, type your certificate password in the field at the bottom of
the page and click Approve. If you enter an incorrect password, the system prompts you to
try again. Once you click Approve, the CSOS order approval page displays. The approval
status column shows the order approval was successful (see the following figure).
Interchange resumes normal outbound processing of the document. If you have not
already added a user signing certificate, a message prompting you to do so is displayed in
place of the password field.
If the document is unsatisfactory, click Reject. This action opens a page where you can
type a reason for rejecting the document (see the following figure). Click Save reason
when you are done. A rejected CSOS order is reported in Message Tracker as a failed
message. The failure reason you type is displayed in the message details for the rejected
order.
5. You have several options for continuing:
l Click View pending orders to approve another order in your queue.
or
l Click View past orders to go to Message Tracker and follow each document’s trading
status. See Message Tracker on page 826.
Caution Do not configure this enhancement on an existing trading pickup. Configure a new trading
pickup. This message processing will be triggered if the special message attribute is set on
an incoming message.
1. Enable the Message attribute:
a. Log on to the user interface as the system administrator.
b. Navigate to System management > Manage message attributes.
c. In the Add a message attribute - Name field, enter the string csos.pkcs7. Then, click
Add. The page refreshes and the new attribute appears in the table as CSOS PKCS7.
2. Add a new document type for the PKCS7 orders:
a. Navigate to Transaction configuration > Add a document type.
b. Complete the fields to name the document type using your own convention.
c. Select the e222-wm.xsl stylesheet.
d. Click Add.
3. Modify your CSOS Order Identification settings:
a. Navigate to CSOS > Configure CSOS.
b. On the Order identification tab, under the XML documents section, click Add an
XML document identifier. Enter the following:
Field Value
Identify XPath /CSOSSignableOrder
DEA Number /CSOSSignableOrder/Header/PurchaserDEANumber
Order Number /CSOSSignableOrder/Header/CSOSOrderID
Document type [Document type you created in Step 2.]
Concepts
l Overview of eSubmissions on page 1032
Procedures
l Configure eSubmissions on page 1033
l Send messages to the FDA on page 1039
l Manage unlimited strength JCE policy download issues on page 1040
Overview of eSubmissions
eSubmissions lets users of Interchange send messages to the FDA via the AS2 message protocol.
Using eSubmissions requires a proper license.xml file and FDA approval of trading partners.
Intended primarily for sending large messages of up to 8 gigabytes or more, eSubmissions has
payload versatility. You can send a single small file or a directory containing many subdirectories
and files. Regardless of size, Interchange securely packages and compresses all outbound messages
the same way. The following illustrates the process for sending messages to the FDA using
eSubmissions.
You can monitor eSubmissions message activity in Message Tracker on page 826, just as you can
follow the processing trail for any type of e-commerce traffic.
Configure eSubmissions
You must complete the following procedures to properly configure Interchange to use
eSubmissions. These are:
1. Getting started with eSubmissions on page 1033
2. Add an application pickup on page 1034
3. Add partner-specific collaboration settings on page 1037
4. Complete the FDA partner on page 1038
5. Import root certificate for SSL on page 1039
You must complete all of the above tasks before you can you send messages to the FDA.
The following topics explain each procedure in detail.
One of the first tasks in using eSubmissions is to contact the FDA to apply for an electronic
submissions account. Go to the FDA web site http://www.fda.gov/esg/ for details. While waiting for
the FDA to send information, you can partially perform the configuration for Interchange. Once the
FDA responds, you can complete the configuration.
To use eSubmissions, you must add a community as you would in establishing any e-commerce
relationship. The community must have a certificate for encrypting messages and a delivery
exchange for receiving messages via the AS2 message protocol. The transport must be HTTPS, but
without client authentication. You can use an embedded HTTPS server, but you must add an SSL
certificate.
You must manually add a partner for the FDA. The FDA does not send you a partner profile file to
import to Interchange. You can add the partner right away with a minimum of information (for
example, partner name only). Later you can complete the partner information when the FDA sends
you SSL and message encryption certificates, the URL to send messages via HTTPS, and other
information.
When registering for an AS2 electronic submissions account with the FDA, be prepared to provide
the following information about your community:
1. Company name. This must be a unique name not also used by your company for any other FDA
electronic submissions account.
2. Community routing ID.
3. Name, phone number and email address of primary and alternate contact persons for your
company.
4. A file containing the community’s encryption certificate and public key. See Export a certificate
to a file on page 799.
5. A file containing the SSL certificate and public key for your HTTPS server. If you are using an
embedded server, open the server’s maintenance page to add an SSL certificate or export it to a
file (see HTTP (embedded) fields on page 444).
6. If applicable, the user name and password required for the FDA to connect to your HTTPS
server.
7. The external URL the FDA must use to connect to your server. The host, port and path may be
different than the values in the local URL. If your network uses a load balancer or firewall,
contact your network administrator for the correct value. This URL should include the fully
qualified host name or IP address, port number and path where a partner must connect to send
messages.
To configure an application pickup for eSubmissions:
1. If you have not done so already, add a community in Interchange user interface. See Add a
community on page 136.
2. Change the pluggabletransports.xml file to support the eSubmissions. There are several
ways to do this.
If no pluggable transports are in use, copy pluggabletransports.xml from <install
directory>\util\fda to <install directory>\conf. This file, which has the
configuration for the eSubmissions transport, replaces the pluggabletransports.xml file
already in the conf directory. Do this only if the pre-existing conf file was not configured
earlier for other pluggable transports.
If other pluggable transports are in use, edit the pluggabletransports.xml file in the conf
directory to add the configuration for the eSubmissions transport. Copy the block below from
util\fda\pluggabletransports.xml to conf\pluggabletransports.xml:
l Always parse for the address. Regardless of whether the message protocol
provides the address, always parse the document for the address.
Select this option to specify that Interchange should always parse the message for the
sender or receiver address.
For messages from partners, however, Interchange still checks the protocol header for the
sender and receiver. A message with an unknown sender or receiver in the header is
rejected. The always parse option for inbound messages is for finding the identity of true
senders or true receivers.
For messages picked up from applications, the always parse option tells Interchange to find
the sender or receiver in the message body. Messages from integration do not have protocol
headers.
If you select this option, you must configure the address parsing rule. See Address
parsing rule options below.
o Document type – For XML, select a document type from the available list for the
From XPath or To XPath fields. These fields are for specifying the XPaths of the
message sender or receiver. If you use a document type not listed, click XPath and
use the wizard to specify the XPaths using your example of the XML document. You
can use the XPath wizard for the “from” or “to” address or both. Using the XPath
wizard requires knowledge of XML.
If you want to select multiple document types from the list, you must cut the XPath
from the top field and paste it in a lower field. Otherwise, the value in the top field is
replaced when you select another document type.
6. On the To address page, do the same as for the From address in step 5.
7. On the Choose transport protocol page, select Directory file system consumer.
8. On the Enter transport settings page, type the path of a directory. This is the directory
Interchange polls for messages to consume, package and send to the FDA.
You can use any path and name you want for the directory. If the directory does not exist,
Interchange creates it for you. Do not use spaces in the path or directory name. For example,
on Windows the path could be C:\FDA_Reports\out. If you operate in a cluster environment
or the common directory of Interchange is a shared directory, you may want the directory
under common\data.
9. To name the delivery, click Next. Otherwise click Finish.
1. If you have not done so already, add a partner for the FDA. Minimally, add a partner with the
partner name and a placeholder value for the contact name. Select Partners > Add a
partner and choose Manually create a new partner.
You only need to partially configure the partner now. This enables you to set up partner-
specific collaboration settings in the next step. If you have not yet received information from
the FDA about the contact name, routing ID, certificates and the URL to send messages, you
can add that later.
2. Click Collaboration settings in the navigation graphic on the community summary page.
3. Click Specialize collaboration settings for a partner. Pick the FDA partner and click Add.
4. Click the FDA partner name to open the Configure community endpoint to partner
specific collaboration settings page. The community should be identified as your
community and the partner as the FDA.
5. Select Set sending rules for the AS2 message protocol.
6. Scroll down the page until the AS2 settings are displayed.
7. Select Request receipts be sent over an asynchronous connection. Enter a
Disposition notification URL.
l FdaCenter
l FdaSubmissionType
11. Click Save changes.
l The URL for connecting to the FDA’s HTTPS server
l The FDA’s routing ID
l A certificate and public key for encrypting outbound messages
1. Open the FDA partner in the user interface.
2. Add the routing ID for the FDA. On the partner summary page, click Routing IDs on the
navigation graphic at the top of the page.
3. Add the contact information for the FDA. On the partner summary page, click Contact on the
navigation graphic at the top of the page.
4. Import the encryption certificate and public key provided by the FDA. On the partner summary
page, click Certificates on the navigation graphic at the top of the page. Then click Add a
certificate. Make sure to trust the certificate for trading and SSL.
5. Add a delivery for sending messages to the FDA.
a. Select the Add a delivery task at the bottom of the partner summary page to open the
wizard.
b. On the Choose message protocol page select EDIINT AS2.
c. Type the URL the FDA provided for connecting to its HTTPS server.
d. Select Clients must use SSL to connect to this server. But do not select Enable
host name verification.
1. On the community summary page, click Certificates in the navigation graphic at the top of the
page.
2. Click the Add a trusted root certificate for SSL servers task at the bottom of the
Certificates page.
3. Select Import a certificate from a file and click Next.
4. Click Browse and locate the SSL root certificate file the FDA sent you. Click Open and Next.
5. Click Finish.
When Interchange polls the integration pickup directory, it expects the files or directories awaiting
retrieval to be named in the following formats. Note that hyphens are used to separate values.
FDACenter identifies the destination for the message, and FDASubmissionType identifies the type of
electronic submission. You must obtain the values for both variables from the FDA.
Do not use spaces in routing IDs, file names or directory names.
C:\
FDA_Reports\
out\
ZZacme-ZZFDA-ABCD-WXYZ-FileName.txt
ZZacme-ZZFDA-ABCD-WXYZ-DirectoryName
Following these formats, the following figure illustrates messages awaiting retrieval in the
integration pickup directory C:\FDA_Reports\out:
ZZacme is the routing ID of the sender
ZZFDA is the routing ID of the receiver
ABCD is the FDACenter
WXYZ is the FDASubmissionType
FileName.txt is the single file being picked up
DirectoryName is the directory being picked up
Note C:\FDA_Reports\out is only an example of the integration pickup directory path. You
can use any path and directory name you want. See step 8 of Add an application pickup on
page 1034.
The FDA sends your community a receipt for each message it receives.
For more information, refer to the Java website under the topic of "How do I enable Java in my web
browser?"
Note This download requires, as a prerequisite, that the appropriate Unlimited Strength policy
files exist in the following folder of the CSOS licensed Interchange server:
.../Interchange/webapps/wtapplet/jcepolicy
The download of these policy files succeeds but, in typical WebTrader client configurations, the
policy files cannot be copied to the local destination directory ...\Java\jre\lib\security and
an "Access denied" error can be viewed by running a debug on the applet code.
The reason for the failure is that the JRE (by default) is located in the C:\Program Files or
C:\Program Files (x86) folder which is write-protected by Windows User Account Control.
To view the progress of the policy down load you can open a Java console.
l A client machine user with administrator privileges can disable the UAC write protection on the
jre\lib\security folder.
l The eSubmissions/WebTrader end user can start the web browser in administrator mode. To do
this:
1. Locate the browser command in the Windows Start menu.
2. Right-click the command.
3. Select Run as Administrator.
4. Open a CSOS/WebTrader session.
If you are operating Interchange with an Axway Interchange license, the topics in this section do
not apply. For information about the interoperation of Axway components in an Axway Interchange
environment, see the Axway Interchange B2B Hub Implementation Guide.
Axway Sentinel
See Integrate with Axway Sentinel on page 1042.
Axway Integrator
See Integrate with Axway Integrator on page 1048.
Axway Gateway
See Integrate with Axway Gateway on page 1051.
Axway PassPort
See Integrate with Axway PassPort on page 1055.
l Sentinel tab – Displays the primary controls for enabling Interchange to integrate with
Sentinel.
l Filters tab – Sets up conditions for which message events to send. Using this tab is optional.
The default behavior is to send all events.
l Custom objects tab – Allows adding names of your own custom tracked objects that can be
referenced by filters.
Additionally, at the bottom of this page a Related tasks list is displayed.
Sentinel tab
Use the Sentinel tab to configure exchanges between Interchange and Sentinel:
l Primary port – The port Sentinel uses to listen to connections from Interchange. The
default port is 1305.
l Secondary host – The fully-qualified domain name or IP address of the computer running
a second instance of Sentinel, if one has been installed and configured. The secondary
Sentinel is used for fail-over. If Interchange cannot communicate with the primary Sentinel,
it tries to connect to the secondary Sentinel.
l Secondary port – The port the secondary Sentinel uses to listen to connections from
Interchange. The default port is 1305.
l Enable buffer congestion monitoring – Select this option to enable the Interchange
system throttle to make sure events queued for sending to Sentinel are not lost if the
backed-up volume exceeds the specified congestion threshold percentage. Enabling
congestion monitoring is unnecessary unless recommended by technical support.
l Send processing data about traded messages – Select this option if you want to
have Interchange send message metadata to Sentinel about messages exchanged between
exchange endpoints.
l Send heartbeats for the trading engine cluster – Select this option if you want
Interchange to send trading engine node and Secure Relay (DMZ) node data at the
specified interval to Sentinel. Interchange sends heartbeat data for each processing node
and for Secure Relay nodes if they are deployed. In the Sentinel user interface, a user can
view summary information about all nodes or all events for a specific node.
o Heartbeat interval (seconds) – Accept the default (60 seconds) or enter a preferred
heartbeat reporting interval in seconds.
l Send changes about the trading engine cluster – Select this option if you want
Interchange to send each of its node’s events log file data to Sentinel. In Sentinel the events
are reported in XFBLog.
Event levels are mapped as follows:
Error EM
Warning AV
High IG
Low IP
Filters tab
Use the Filters tab to set up conditions for selectively sending message events to Sentinel.
Configuring filters is optional. The default Interchange behavior is to send all events to Sentinel.
You can set up filters to operate differently than the default send-all behavior. Selectively filtering
events can be complex depending on what events you want to send.
For details about using this tab to manage filers, see:
l About Sentinel filters on page 1045
l Add or modify Sentinel filters on page 1046
l Filter expressions on page 1048
Interchange incorporates one Sentinel tracked object named XFBTransfer. This tracked object
meets most needs. In special cases, you may need additional tracked objects. For example, you may
want to forward more attributes and values to Sentinel than supported by the default tracked object.
If you have a custom tracked object, enter its name on the Custom objects tab. Integration filters
can reference the custom tracked objects listed on this tab.
Publishing information to Sentinel with a custom tracked object requires more than entering a name
on this tab. Implementing a custom tracked object requires Java development skills and experience
using Interchange, Sentinel and Composer. You may want to engage Axway professional services
consultants to complete the task.
To implement a custom tracked object you must:
1. Add a tracked object in Axway Composer and export it to Sentinel.
2. Develop Java code for gathering the events in Interchange to publish to Sentinel. The code can
be implemented as a message action, inline process, event router or other plug-in.
3. If selective filtering of events is desired, add the name of the custom tracked object to the
Custom objects tab. Then add one or more integration filters to control the flow of events to
Sentinel.
Filters let you approach Sentinel integration in two opposite ways:
l You can send all or most events to Sentinel, but block specified events.
l You can block all or most events from Sentinel, but send only specified events.
There are two types of integration filters: the default filter and custom filters. There is only one
default filter. You can add as many custom filters as you need.
In the simplest case, only the default filter is required. This presumes that Sentinel integration is
enabled and you want Interchange to send all events without exception. To do so, open the default
filter and make sure Send all events is selected.
Another case is when you want Interchange to send only some events. This requires using the
default filter and at least one custom filter. If filtering conditions are complex, you may need many
custom filters. For example, you could set the default filter to Don’t send any events. Then you
could add two filters, one allowing events related to purchase orders and the other to invoices. The
effect of all three filters is Interchange sends only events related to purchase orders and invoices,
but nothing else.
Custom filters
To have only preferred synchronous response sent to Sentinel, use the default filter in combination
with custom integration filters.
Custom filters act before the default filter. Despite whether you set up one or many custom filters,
the default filter always triggers last. This sequence provides the control necessary for setting up
exact filtering conditions.
You can set up simple or complex filter expressions with custom integration filters. It is the
expressions – working in opposition to the default filter – that provide a high degree of control over
the events sent to Sentinel.
Filter expressions can be used only with custom filters and are not applicable to the default filter.
Although you can adjust some of the default filtering conditions, you cannot turn off or delete the
default filter.
The following examples describe use of custom integration filters.
Filter example 1
To send to Sentinel only events associated with 850 documents (EDI purchase orders):
1. In the Filters tab, click the name of the default filter (Sentinel Default) to open the filter
modification page.
2. In the default filter, select Don’t send any events.
3. Click Save changes to return to the Filters tab.
4. From the list of Related tasks, click Add an integration filter.
5. Add a filter with a filter expression that requires events associated with DocumentType
Equals 850 to be sent.
Because the custom filter triggers first, Interchange sends to Sentinel events related to 850
documents. The default filter then blocks all o ther events, including all events related to all other
document types.
Filter example 2
The second example illustrates the opposite case of sending all events except events related to 850
documents.
1. In the Filters tab, click the name of the default filter (Sentinel Default) to open the filter
modification page.
2. In the default filter, select Send all events.
3. From the list of Related tasks, click Add an integration filter.
4. Add a filter with a filter expression that blocks events related to DocumentType Equals 850.
Because the custom filter triggers first, Interchange blocks events related to 850 documents. The
default filter then sends all other events.
Use the up and down arrows to set the sequence in which custom filters run. The filter at the top
runs first, followed by the next filter on the list and so on.
The Mode column indicates whether or not a filter is set to send events. When the default filter is set
to Don’t send any events, the Mode column shows Don’t send for the default filter and Send
for all other filters. When the default filter is set to Send all events, the Mode column shows Send
for the default filter and Don’t send for all other filters. The Send and Don’t send indicators are
reminders of the opposite relationship between the default filter and custom filters.
On the Filters tab you can enable or disable any filter, except the default filter. This is useful if you
want to suspend but not delete a filter.
To open a filter, click the filter name on the Filters tab. To add a filter, click Add an integration
filter.
Before adjusting the default filter or adding custom filters, determine what you want Interchange to
send or block. This affects how to set the default filter and how many custom filters and expressions
to add.
The following topics describe the fields for changing the default filter and for adding or changing a
custom filter:
After adding or changing a filter, click Save changes.
Filter expressions
Filter expressions can be used to set conditions for applying a custom filter. An expression can be
one statement or multiple statements combining a complex string of and-or conditions.
Interchange recognizes many metadata attributes. To use a known attribute, type one or more
letters in the When attribute field to display a list of autocomplete values that start with those letters.
You can select an autocomplete value or type an attribute of your own.
After completing the expression, click Add. You can add another expression as an AND or OR
condition. Click Save changes when done.
Note To ensure a large pool of autocomplete attributes to choose from, attribute collection must
be enabled. Users with administrative permissions can check this. Select Message tracker
> Configure global message tracker settings. On the page titled Global message
tracker settings, make sure the following is enabled: Collect attributes for use in
message detail pop-up windows. In addition, an administrator may have to assign
attributes as in-use attributes to make sure the proper attributes are available as
autocomplete values. For more information see Manage default search settings on page
843.
Messages are moved between Interchange and Integrator via a special JMS exchange. Setting up the
Axway Integrator integration pickup or delivery exchange is almost like setting up any JMS
integration exchange. The difference is you must select Integrator as the integration pickup or
delivery option in the delivery exchange wizard. Integrator must be configured to use the same JMS
queue as Interchange.
JMS transport configuration on page 294 describes the fields for configuring a JMS transport.
However, for the Integrator JMS transport, specific field values are recommended. The JMS provider
used by Interchange and Integrator is Messaging. For this version of Interchange, you must use
Messaging 5.5.1.
When configuring integration with Integrator via the Axway Integrator transport, follow these
guidelines when using the delivery exchange wizard. The wizard already provides these as the
default values.
JMS queue For integration delivery: queue/GI2IG
For integration pickup: queue/IG2GI
If integrating with an Integrator earlier than 3.4.1:
For integration delivery: queue/CI2XIB
For integration pickup: queue/XIB2CI
This queue requires a Do not select this option
username and password
Use JNDI Select this option
JNDI URL tcp://<host>:4569
The default value presumes Interchange and Messaging are
running on the same computer. If Messaging is on a
different computer, substitute the fully qualified domain
name or IP address of the computer.
JNDI factory com.axway.xms.jms.XmsInitialContextFactory
This provider requires a Do not select this option.
username and password
JMS connection factory factory/QueueConnectionFactory
Use a custom Java Do not select this option.
implementation
Note The Axway Integrator exchange is only for performing JMS integration with Integrator. If
you do not want to integrate with Integrator, use a normal JMS exchange.
A special event router is created when adding an exchange for routing messages from partners to
integration via the Axway Integrator transport. The metadata values allow each component to link
messages exchanged between them. If Interchange is also configured to integrate with Axway
Sentinel, the metadata correlates the messages among all three components.
The following steps describe the flow.
1. Interchange picks up a message from integration. Attached to the message as a string property
are Integrator metadata elements. Interchange changes the element names.
TransferCorrelationId ExternalCycleIdValue
SentinelTrackedObject ExternalCycleIdTOName
At the same time, Integrator can send events to Sentinel.
2. Interchange processes the message. If Sentinel integration is enabled, Interchange sends
events, but also sends information to link ExternalCycleIdValue to its newly generated
SentinelCycleIdValue. Sentinel can use the information to link to the information received
form Integrator in step 1.
The following steps describe the flow.
1. Interchange sends a message received from a partner to integration. Before doing so,
Interchange changes names of key metadata to Integrator-friendly names.
SentinelCycleIdValue TransferCorrelationId
SentinelCycleIdTOName SentinelTrackedObject
If Sentinel integration is enabled, Interchange sends events to Sentinel, but no transaction
linking information is included.
2. Integrator processes the message received from Interchange. Integrator can also send events to
Sentinel. The metadata Integrator sends links back to the metadata received from Interchange.
From the Interchange perspective, this integration is set up almost like a typical trading relationship
between a community and partners who exchange e-commerce business messages. But in this case,
Interchange is not exchanging messages, only retrieving files from a queue within Axway Gateway.
The retrieved files are not packaged, encrypted or compressed. Interchange sends the retrieved files
to back-end integration without further processing. Interchange does not send Gateway receipts or
any other messages.
Once Interchange has retrieved a file, Axway Gateway marks its copy of the file as processed
successfully.
1. Set up HTTP virtual file directories (VFDs) or real file directories (RFDs) for users who represent
the instances of Interchange. One VFD or RFD is required for each user. Interchange polls the
VFD for files to retrieve. See the Axway Gateway documentation for information on how to add
VFDs and RFDs.
2. Edit the template.html file to include only the following lines:
<XFER_LIST>
<REAL_FILE>
<FILE_INFO>
<FNAME>@fname@</FNAME>
<SIZE>@SIZE@</SIZE>
<DATE>@DATE@</DATE>
</FILE_INFO>
</REAL_FILE>
<XFER_AVAIL>
<FILE_INFO>
<FNAME>@FNAME@?local_ident=@LOCAL_ID@&%I</FNAME>
<SIZE>@SIZE@</SIZE>
<DATE>@DATE@</DATE>
</FILE_INFO>
</XFER_AVAIL>
</XFER_LIST>
Template.html is at <install directory>\samples\web\templates.
Including this code directs Axway Gateway to generate a list of files available to consume. Each
listed file is separated by a line feed.
The template.html file is the default template. In a production environment, the default
template is left in place. A special template file, edited as described here, is created. The Axway
Gateway administrator assigns the special template to the Interchange users who are retrieving
files from Axway Gateway.
3. For Interchange to connect with a username and password, web authentication must be set
instead of CGI (common gateway interface) in Axway Gateway.
Select Session > Local and right-click, then select Configure to open the configuration
dialog window. Select Connectivity > Internet protocols > HTTP and click Options.
Under server identification, select Web in the Method field drop-down list.
4. If Interchange is to connect via HTTPS (HTTP over SSL) rather than HTTP, run the following
sample scripts in this order:
a. cert.bat
b. sprof.bat
c. netprof.bat
The Axway Gateway server must be running when you execute the scripts. The scripts are
located at <install directory>\samples\tls\case1.
The scripts import sample certificates and create two security profiles and many network
profiles.
Add a port specification, using 6331 as the port and SPROF_IN as the Transport Layer
Security (TLS) profile. The netprof.bat script creates port 6331; the sprof.bat script
creates SPROF_IN.
Restart the Axway Gateway server for the changes to take effect.
Note If the security options are disabled when creating the port specification,
return to the configuration dialog window and change the SecureRelay
access policy field to Through SecureRelay and directly. You must
delete all existing port specifications to do this.
5. Changing settings for dynamic server processes is recommended.
Select Session > Local and right-click, then select Configure to open the configuration
dialog window. Select Connectivity > Internet protocols > HTTP and click Options, then
click Advanced. Under dynamic server processes, set these values:
l No. processes min 15
l No. processes max 30
l Balance ratio 25
6. Provide necessary information to the Interchange administrator. This can include:
l The URL for connecting to Axway Gateway. Each URL is unique per partner. The following
are examples of URLs:
o HTTP: http://<host>:<port>/<user1>/transfer/<partner1>/
o HTTPS: https://<host>:<port>/<user2>/transfer/<partner2>/
Where:
o <host> is the fully qualified domain name or IP address of the computer running Axway
Gateway.
o <port> is the number of the port Axway Gateway listens for connections from
Interchange.
l If HTTPS, provide a file containing a certificate and public key. Interchange must import
and trust this certificate.
l The username and password that Interchange must use to connect.
Interchange configuration
Use this procedure to enable Interchange to integrate with Axway Gateway.
1. Add and configure a community profile. See Add a community on page 136.
This can be the same profile as the one used to exchange e-commerce messages with partners
other than Axway Gateway. If you use the same profile, make sure the delivery exchange added
in step 3 is not the default. The default should be the exchange you want partners to use for
sending e-commerce messages to your community.
2. Add a partner profile to represent Axway Gateway. See Add a partner to a community on page
148.
Adding this partner is not required, but doing so makes it easier to use Message Tracker on page
1086 to search for messages retrieved from Axway Gateway. Use a partner name you can
identify with Axway Gateway.
When adding the profile, only a partner name and contact name are needed. Associate the
profile with your community. No other setup is required, including no delivery exchange or
certificate.
3. On the community profile summary page, click Delivery exchange in the navigation graphic
at the top of the page. On the Pick a delivery exchange page, click Add a delivery exchange
to open the Delivery exchange wizard.
4. Select No packaging and click Next.
5. For the From address, select Specify the address. Always use a fixed address. Click Pick
party and select the Axway Gateway partner as the sender. Click Next.
If you did not add a partner profile in step 2, select your community as the sender.
6. For the To address, select Specify the address. Always use a fixed address. Click Pick
party and select your community as the receiver. Click Next.
7. Select HTTP and click Next. The Axway Gateway HTTP interface delivery exchange is selected
by default. Click Next to open the HTTP configuration page.
8. Complete the fields and click Finish.
URL
The URL for connecting to the server.
If Encode and Decode buttons display, click Encode if the URL contains spaces or non-
alphanumeric characters to encode the characters. Click Decode to reverse the
transformation. For example, if you enter http://foo.com/foo= bar and click Encode,
the URL becomes http://foo.com/foo%3D%20%20bar.
Select this to have Secure Sockets Layer protocol in use during connections. The server
presents a certificate for verification. To do this, a certificate in a profile must be designated
as the SSL certificate. The server must support SSL. If this is not selected, connections are
not encrypted.
Enable host name verification
If selected, Interchange compares the name of the SSL server to the name in the server's
certificate to ensure they are the same.
If you use DMZ nodes, it is recommended that you do not select this. If host name
verification is enabled, messages may fail because the client is connecting to the DMZ node
and not to the Interchange server. This is not applicable to integration exchanges.
This server requires a username and password
If selected, type a username and password to connect to the server.
If using SSL, import to your community the certificate and public key being used by Axway
Gateway.
l Integration overview on page 1055
l Functional limitations for PassPort AM on page 1055
l Database and installation requirements on page 1055
l Verify PassPort host name on page 1056
l About PassPort AM component instances on page 1056
l Steps after installation on page 1057
Integration overview
Interchange can integrate with PassPort for:
l Identity and access management (IAM). When PassPort AM integration is engaged, PassPort
manages users, user privileges, and roles on behalf of Interchange.
Your user license controls the level of integration you can implement.
The decision whether to integrate with PassPort is made during installation of Interchange. When
integrated, PassPort must be running for Interchange to operate properly. If the PassPort server is
off, Interchange cannot process.
l Using Axway ePedigree.
When installing Interchange, you must select the PassPort option. You cannot integrate with
PassPort unless this option was selected during installation. During installation, you must also
specify the host name and port for PassPort.
After installing Interchange, do not start Interchange server until after completing the configuration
tasks described in Steps after installation on page 1057.
Your user license specifies whether or not you can integrate with PassPort and the level of
integration. During installation, you choose which parts of PassPort to integrate with (AM, PM, PS).
After installing and completing the post-installation steps, there is a page in the Interchange user
interface for changing integration parameters. You cannot, however, turn off integration once
engaged.
Upgrading does not support changing the state of PassPort integration. Any of the following cases
require re-installing with a fresh database:
l Changing from no PassPort integration to any PassPort integration.
l Changing from any PassPort integration to no PassPort integration.
l Changing from some PassPort integration to some other PassPort integration.
During installation, the installer suggests a value for the PassPort server host name. The suggested
name is probably correct if Interchange and PassPort are on the same computer.
If you suspect the PassPort host used by Interchange is incorrect and you have not started the
server, change the serverHostNames value in the Interchange
passportintegrationdefaults.xml file. The file is at <install directory>\conf.
However, if you have already started the server, editing this file has no effect unless you also replace
the database. This file is read-only one time, when the server is first started with a new database.
In passportintegrationdefaults.xml, the values for amPort and pmPort must be the same.
The default is 6090.
Interchange identifies itself to PassPort AM via values for four properties:
l Component name
l Component version
l Component group
l Instance
PassPort AM knows three of these values (name, version, group) when it imports the Interchange
component security descriptor file (see Steps after installation on page 1057). Upon importing the
CSD file, PassPort AM assigns an instance name of default.
All four values within PassPort AM match those in Interchange's
passportintegrationdefaults.xml file, which is generated during the Interchange
installation. If the values do not match, Interchange cannot communicate with PassPort AM. The
code below shows an example of a passportintegrationdefaults.xml file. This example
shows that Interchange is integrated with PassPort AM only, not with PM and PS.
<PassPortIntegrationDefaults>
<serverHostNames>localhost</serverHostNames>
<isAmIntegrated>true</isAmIntegrated>
<amPort>6090</amPort>
<amComponentGroup>Axway</amComponentGroup>
<amComponentName>Interchange</amComponentName>
<amComponentId>default</amComponentId>
<amComponentVersion>5.9.0</amComponentVersion>
</PassPortIntegrationDefaults>
If you were to integrate two instances of Interchange with PassPort AM, the second instance can
have the same values for name, version and group, but it must have a different instance value.
Before starting the server for the second instance, edit the instance value in its
passportintegrationdefaults.xml file. In PassPort AM, add that instance value to the
Interchange component. Do not import another CSD file if the name, version, and group of both
instances are the same.
Caution Interchange reads passportintegrationdefaults.xml into the database only once,
when the server is first started. This is why you must change the instance value in the file
before the server is started the first time.
You may want to integrate two instances when, for example, you want separate installations of
Interchange for testing and production. If Interchange runs in a cluster on multiple computers, the
instance value for the entire cluster is the same.
If Interchange is integrated with PM and PS as well as AM, multiple instances of Interchange can use
the same user ID and password to connect to PM and PS.
The passportintegrationdefaults.xml file is at <install directory>\conf.
The following procedures presume PassPort has been installed, its server is running, and an SMTP
server has been set up for PassPort.
If PassPort AM is performing identity and access management (IAM) by using the imported
Interchange component security descriptor (CSD) file, you must set up in PassPort a user with
Interchange administrator privileges. With this user's credentials, you can log on to the Interchange
user interface.
The same user can also log on to the PassPort user interface. The user at a minimum has the
authority to change their password. The user can also perform broader tasks in the PassPort UI if
associated with a role granting more privileges.
If PassPort AM is not using the Interchange CSD file, but is performing IAM through an external
system such as an LDAP server, contact the PassPort AM administrator for credentials to use for
logging on to the Interchange UI. Do not follow this procedure.
Perform this procedure after installing Interchange, but before starting Interchange for the first
time.
Caution See Advice for PassPort users on page 126 for important information about user
permissions.
1. Log on to the PassPort user interface. You may have to ask the PassPort administrator for the
URL to connect to PassPort in a browser.
The format of the URL is http://<host>:<port>, where <host> is the name or IP address
of the computer running PassPort and <port> is the port where PassPort listens for
connections. If Interchange and PassPort are on the same computer, you can use the same
hostname for both in your browser. The default port is 6090.
The initial username and password for the default PassPort user are system and System01.
These are case sensitive. Contact the PassPort administrator if these credentials are invalid.
2. Select Administration > Components in the PassPort user interface to open the
components area.
3. Click Import CSD to import the Interchange CSD file. The file, named csd_
Interchange.xml, must be accessible on your network. The file is in the Interchangedirectory
tree at <install directory>\extras\PassPort.
When the file has been imported, a confirmation pop-up window displays. Click Show details
to see data about the import action or click Close.
4. Select Community > Users and Contacts to go to that area.
5. Click New User/Contact and do the following:
a. Use the default domain Synchrony.
b. Select Users as the parent organization.
c. Type the last name of the user.
d. Add an email address for the user. Make sure the address is valid. The PassPort server sends
messages about the user account to this address.
e. Type a user ID for the user. For example, TEadmin.
f. Make sure this checkbox is selected: Make this contact a user.
g. Make sure the Active radio button is selected.
h. Click Next to advance to the select groups page. Do not select a group. Click Next again
to advance to the select roles page.
i. Select Interchange_Admin as the role for the user. This role - from the CSD file
imported in Step 4 - gives the user administrator privileges in the Interchange user
interface.
6. Click Finish to add the user. PassPort sends an email message to the new user. The message
contains the user ID and password for logging on to the Interchange UI. The same credentials
and the domain name can be used to log on to the PassPort UI to change the user's password.
7. Click the link in the email message to open the log-on page for PassPort. Log on with the new
credentials.
After logging on, you can change your password if you want. Log off when finished.
8. Start Interchange and log on to the Interchange user interface.
If you added the user under a domain other than the default, Synchrony, you must append
@DomainName to the user ID when logging in. For example, if the user ID is admin and the
domain name is Domain, log on with the user ID of admin@Domain.
Consult with the PassPort AM administrator on the protocol for adding other PassPort users who
need access to Interchange. Either you must log on as the system user and add the new users,
or the PassPort AM administrator must manage other users of Interchange for you.
If integrating with PM and PS, and a user has been set up for use by Interchange, you can
confirm whether Interchange has connected to PassPort by checking the <host>_cn.log file
in the Interchange logs directory, where <host> is the computer running Interchange. Search
for key phrases containing "PassPort," such as "Adding an object sent from PassPort PM" and
"PassPortIntegrationItemProcessor."
l Sentinel – Sentinel is an optional Axway product that provides tools for monitoring business
and technical events that occur in your transfer environment. Sentinel is part of the Axway
Interchange of products. It provides end-to-end monitoring services beyond the functionality
provided by Interchange.
Sentinel monitoring agents reside natively on Interchange. These Sentinel monitoring agents
generate Tracked-Event Messages that contain data about application and platform events.
The agents then send the Tracked-Event Messages to the Sentinel Server environment.
In the Sentinel Server environment, Sentinel compares incoming Tracked-Event messages to a
catalog of Tracked Objects. A Tracked Object is a model containing a set of attributes that
describe an application event. Sentinel uses Tracked objects to extract the data from the fields of
the Tracked-Event Message, and then writes the data to a specific table in the Tracking Database.
A set of pre-built Sentinel tracking requests enable you to view details about the life cycles of
messages that transit in Interchange. You can use these tools to view alerts, performance
indicators, information for monthly reports, day-to-day monitoring as well as document and
message search results.
l Message Tracker – Queries Interchange to provide a detailed analysis of known root error
causes. Results include flow visualization and payload.
l Message Log – Queries the integration engine to provide a detailed analysis of file processing
and communication exchanges. Results include flow visualization and edit and resubmit
capabilities.
Note If you want to send messages about Interchange events by email, see The alerts.xml file on
page 1114.
Topics in this chapter
l User interface home page on page 1085
l Monitor file system health on page 1085
l Message Tracker on page 1086
l Alert activity report on page 1087
l External monitoring of server status on page 1087
l Log file tracking on page 1092
l Real-time viewing of log files on page 1094
l Set up tail as a Windows option on page 1095
l Troubleshooting with the log4j file on page 1095
l Send log files to technical support on page 1100
Sentinel
About Sentinel
Sentinel is an Interchange product that provides tools for monitoring business and technical events
that occur in your transfer environment. Use Sentinel to view information about:
l Interchange inbound and outbound transfer events
l Interchange and Secure Relay node status
l Technical information about exchanged electronic documents
A Sentinel installation for Interchange can include the following elements:
l Sentinel – End-to-end monitoring application that collects data on selected network events
and generates statistics from that data. You install Sentinel from the Axway Interchange
installation ISO.
l Composer (optional) – Sentinel management application that enables you to create and edit
monitoring requests, graphs and monitoring displays (Dashboards). You install Composer from
the Axway Interchange installation ISO.
l Interchange Sentinel objects – A set of objects designed for Interchange monitoring and
installed on both Sentinel and Composer. Interchange provides the following objects for use
with Sentinel:
o Tracked Objects – Sentinel database table templates for organizing and storing the data
generated by monitored network events.
Sentinel then records the data in a database table whose structure is determined by a Tracked
Object. This data is then available for organized searches and for the generation of graphic displays
and alerts.
Monitoring users view data in Dashboards in the Sentinel Dashboard Viewer, or in events lists and
graphs in the Sentinel Monitoring interface.
l HeartBeat Tracked Object on page 1062
l XFBTransfer Tracked Object on page 1065
l XFBLOG Tracked Object on page 1083
If you extend your Interchange installation by integrating additional Axway products, you may have
additional Tracked Objects for handling other system-generated data.
Introduction
heartbeat.xml is a Sentinel Tracked Object that enables you to monitor Interchange and Secure
Relay (DMZ) node status. This Tracked Object also sends information about causes of unexpected
node and Secure Relay shutdowns.
Cluster monitoring
The HeartBeat Tracked Object is of particular value in monitoring Interchange cluster status. You
can use heartbeat to:
l Send a single heartbeat signal to Sentinel for the entire Interchange system. This provides an
indicator of the total validity of all Interchange processing. When all configured Interchange
nodes are running and processing (with no throttling), the Interchange system status is good.
l Generate a warning in Sentinel when one or more Interchange nodes are throttled.
Activate HeartBeat
To activate and use the HeartBeat Tracked Object in your Interchange implementation:
1. Install Sentinel and Composer.
2. Deploy heartbeat.xml to Sentinel.
To do this, you import heartbeat.xml to Composer and then deploy the imported Tracked
Object from Composer to Sentinel.
3. In the Interchange UI, activate the function.
To do this, go to the Integrate the trading engine with Sentinel page, and select the option
Send heartbeats for the trading engine cluster. For descriptions of all Sentinel options
on this page, see Integrate with Axway Sentinel on page 1042.
Deactivate Heartbeat
To deactivate heartbeat notifications to Sentinel:
1. Open a session in the Interchange user interface.
2. Click Trading configuration on the toolbar to open the Communities page.
3. Click Configure Sentinel integration to open the Integrate the trading engine with Sentinel
page.
4. On the Sentinel tab, clear the o ption Send heartbeats for the trading engine cluster.
5. Click Save changes.
Heartbeat attributes
The following table lists the attributes that Heartbeat sends to Sentinel.
XFBTransfer attributes
XFBTransfer includes attributes that you can use to identify:
l Identify the steps in the transfer process on page 1065
l Identify the roles of transfer p artners on page 1067
l Identify Senders and Receivers on page 1069
l Identify transfer users on page 1069
l Identify transfers on page 1070
l Identify transfer validity periods on page 1072
l Identifying transfer d ates and times on page 1072
l Identify transfer protocols on page 1073
l Identify transfer options on page 1074
l Identify the size o f transfers on page 1075
l Identify the structure and content of transfers on page 1076
l Metadata for most messages on page 1077
Attribute descriptions
Sentinel Details
state
CONSUMING Interchange is beginning to receive data from a sending partner. This may be
interrupted and repeat at the transport level.
INTERRUPTED The message processing on Interchange has been interrupted.
Sentinel Details
state
CREATED A sender or receiver initiated a message transfer on Interchange.
PACK Interchange enveloped a message for sending.
PRODUCING Interchange is beginning to transmit data to a receiving partner. This may be
interrupted and repeat at the transport level.
SENDING Interchange is sending data to a receiving partner.
SENT Interchange sent all of the transfer data to a receiving partner.
UNPACK Interchange unpacked an inbound enveloped message.
RECEIVING Interchange is in the process of receiving data from a sending partner.
RECEIVED Interchange has received all of the data from a sending partner.
REJECTED The message processing has failed and is out of retries.
RETRY The message processing is attempting to complete with a scheduled retry.
TO_ACK Interchange expects an acknowledgement of an inbound or outbound transfer.
ACKED Interchange has received an acknowledgement of an inbound or outbound
transfer.
NACKED Interchange has not received an expected acknowledgement of an inbound or
outbound transfer.
From Interchange 5.12, the trading engine generates a message state for each of the following
events in the embedded FTP/SFTP server. Working in Sentinel, you can configure Dashboards and
Requests to track the status of remote partner FTP file pickups (GETs), using these attributes:
DOWNLOADING Interchange is in the process of downloading the message payload.
DOWNLOADED Interchange has completed the download of the message payload.
INTERRUPTED The download of the message payload has been interrupted on Interchange.
REMOVED The message payload has been deleted from the embedded server.
From Interchange 5.12, Interchange generates a message state for each of the following events in
the embedded WebTrader server:
Sentinel Details
state
ACCESSED A WebTrader document has been either viewed or downloaded by a WebTrader
end user.
Sentinel Details
state
REMOVED A WebTrader document has been removed by a WebTrader end user.
RENAMED A WebTrader document has been renamed by a WebTrader end user.
PURGED A WebTrader document has been purged by a WebTrader end user.
SUPPLIED A WebTrader document has been uploaded by a WebTrader end user.
DELIVERED A WebTrader document has been delivered to WebTrader end user.
MOVED A WebTrader document has been moved to a different directory by a WebTrader
end user.
Additional state attributes for AS4, OFTP, and PeSIT protocol message-handling
events
From Interchange 5.12, Interchange generates an AVAILABLE message state for the following
message-handling events:
AVAILABLE Interchange has set a message to one of the following statuses:
l The message is being held for later pickup
l The message-processing schedule in not currently active
l The message is waiting for pull processing to begin (AS4 only)
l A related child message is waiting for pull processing (AS4 only)
l An inbound or outbound message is being pull processed (AS4
only)
For a given transfer, only the following combinations of partner roles are possible:
l Sender/Requester and Receiver/Server
o The partner that the transfer requested the transfer
o The partner that received the transfer listened for the transfer request
l Receiver/Requester and Sender/Server
o The partner that received the transfer requested the transfer
o The partner that sent the transfer listened for the transfer request.
For each Interchange transfer event, the following attributes identify the roles o f the transfer partner
that generated the Tracked Instance.
Example 1: When a transfer occurs between a Sender/Requester and a Receiver/Server, Sentinel
receives the following data for the event.
Example 2: When a transfer occurs between a Receiver/Requester and a Sender/Server,
Sentinel receives the following data for the event.
Identify transfers
To identify a transfer, use the following attributes.
l Network Layer: rules that manage transfer media
l SSL / TLS Layer ( Security Sockets Layer / Transport Layer Security): rules that manage transfer
security
l Protocol Layer: rules that manage transfer communication
l ETB3 (ETEBAC 3 ) l FTP_
HTTP
l ETB5V1 (ETEBAC 5 version 1) l HTTP
l ETB5V2 (ETEBAC 5 version 2) l PEL
l PSIT_HS_E (PESIT, version E) l POP3
l PSIT_HS_D (PESIT, version D) l SMTP
l OFDT (ODETTE File Transfer l SFTP
Protocol)
l FTP
l 0: SSL/TLS did not protect the transfer.
SSLAuth String One of the following:
l S: The Server sent X.509 certificates to the Requester.
l B: Both the Server and the Requester sent X.509 c ertificates to each
other.
l N: Neither the Server nor the Requester sent X.509 c ertificates.
SSLCypher String The cipher suite that the Server and the Requester used during the SSL/TLS
session. The cipher suite identifies the following:
l authentication method
l encryption algorithm
l hash algorithm for MAC calculation
l File and the Receiver's monitor is not a main frame, this attribute
is empty
FileOrganization String If the value of the CommandType attribute is:
l Message, the value of this attribute is org_undefined
l File, the value of this attribute is one of the following:
l org_sequential: The transferred data is not indexed.
l indexed: The transferred data is indexed.
l direct: The transferred data is assigned relative access.
l U: Undefined
TranslationTableId String Translation table identifier. When a transfer p artner uses a translation
table that is delivered with the Axway Managed File Transfer software,
the value of this parameter is INTERNAL.
CommunityPickup The name of the trading ––
pickup that consumed a
message.
DeliveryExchange The name of the trading ––
delivery used to send the
message.
IntegrationDelivery The name of the exchange ––
that a message is sent to for
integration.
IntegrationPickup The name of the exchange ––
that consumed a message
from integration.
ReturnMessage Description for a rejected ––
transaction.
The reject reasons reported
to Sentinel are the same as
the reasons used by
Interchange and reported
in Message Tracker.
SequenceID Together with ––
SequenceCount, identifies
the sequence position of
messages consumed by
pickups when sequential
messaging is activated for
the pickup.
SequenceCount Together with SequenceID, ––
identifies the sequence
position of messages
consumed by pickups
when sequential messaging
is activated for the pickup.
TradeDestination For an outbound message, ––
the routing ID of the
receiving partner.
For an inbound message,
the routing ID of the
receiving community.
TradeDestinationAlias For an outbound message, ––
the name of the receiving
partner.
For an inbound message,
the name of the receiving
community.
TradeOriginator For an outbound message, ––
the routing ID of the
sending community.
For an inbound message,
the routing ID of the
sending partner.
TradeOriginatorAlias For an outbound message, ––
the name of the sending
community.
For an inbound message,
the name of the sending
partner.
Introduction
XFBLog is a Sentinel Tracked Object that enables you to monitor Interchange trading engine transfer
and audit events.
This Tracked Object enables Interchange to send values for attributes to Sentinel that correspond to
fields that are populated Interchange logs .
1. Install Sentinel and Composer.
2. Install Interchange.
3. Deploy XFB_ALL_EN.xml to Sentinel.
To do this, you import XFB_ALL_EN.xml to Composer and then deploy the imported XFBLOG
object from Composer to Sentinel.
XFBLog attributes
Attribute Description Type Length
The user interface has tools for monitoring various types of system activity.
Note If you want to send messages about Interchange events by email, see The alerts.xml file on
page 1114.
Topics in this section include:
l User interface home page on page 1085
l Monitor file system health on page 1085
l Message Tracker on page 1086
l Alert activity report on page 1087
l External monitoring of server status on page 1087
l Create audit files of UI object changes on page 1089
l Log file tracking on page 1092
l Real-time viewing of log files on page 1094
l Set up tail as a Windows option on page 1095
l Troubleshooting with the log4j file on page 1095
l Send log files to technical support on page 1100
Click the Home icon on the toolbar to open the home page.
If Interchange detects that it cannot access or write a test file to a monitored directory, the system
throttle is engaged. This prevents Interchange from taking on new messages to process. When the
problem has been resolved, the throttle turns off. An example of when the throttle engages is when
Interchange loses connectivity to a network file system.
The backup directory is monitored automatically. There is a page in the user interface that lets you
add other directories to be watched. To open the page, select System management on the
toolbar. On the System management page, click the task Monitor file system health to open the
Monitor file system health page.
Use the Browse and Add buttons to add a directory to be monitored. You must restart Interchange
server when you add or delete a directory for the change to become effective.
Note Although the path for the backup directory is displayed on the Monitor file system health
page, you cannot change it here. You must go to the Global backup configuration page to
change the path. For more information, see Message backup configuration on page 849.
Message Tracker
Message Tracker is the primary tool for tracking the messages traded between you and your trading
partners.
Message Tracker lets you search for messages by various conditions, including sending and
receiving parties, processing status and dates. Once the system finds messages matching your
search conditions, you can view trading history details and document payloads. You also can
reprocess documents.
Message Tracker also lets you save searches so you can perform the same searches repeatedly
without having to set up the conditions again.
For more information see Message Tracker on page 826.
You can use the default dates and times in the start and end date fields or select your own. To select
a date, click a date field to open a date selector calendar. To select a time, type a time using the 24-
hour clock standard.
Once the dates and times are set, click Update results to display statistics about generated
transaction SLA and partner status alerts. Click Download results as a CSV text file to save the
report in a comma-delimited value file. Or use the Print button to print the report.
See Message Tracker on page 826.
To use this feature, the server must be running and a community must be set up. Also, for
Interchange at least one node must be started. The community must have a delivery for receiving
messages from partners that uses an embedded HTTP server. For information about configuring a
community, see Communities on page 134.
You can retrieve the default server status message with a URL in the following format:
http://<host>:<port>/ServerStatus
Host is the name or IP address of the computer running Interchange server. Unless it has been
changed, use 4080 as the port. This is the default port of embedded HTTP servers (see Embedded
transport servers on page 431).
You can point a browser to the URL to manually inspect the status message. The default message is
ServerStatus=OK. To refresh the page, press Control while selecting Refresh to force the
browser cache to clear.
Instead of the default message, you can design a status file with any content you like. When you use
the server status URL, your file is displayed. You can use this feature to have external systems
generate a more comprehensive or sophisticated status page.
The name and path of the custom file are controlled by the filereg.xml file in <install
directory>\conf. The following are the default settings:
To use the default configuration for the custom file, create an HTML document and save it as
serverstatus.html. Copy the file to <install directory>\conf.
You do not have to use an HTML file. You can use any file type you want and you can use any file
name. If you do, change the path attribute in filereg.xml to conform to your file name and
location. However, do not edit the name attribute. This value must remain as serverstatus.html.
Introduction
Interchange provides tools for generating audit logs of the changes that users perform on objects in
the UI. This includes changes implemented when creating objects (using the add wizards) and when
modifying objects (working in modification pages). The resulting logs show which user made
changes, at what time and date the change was made, and provide details of the change.
Audit information is collected for changes to the following objects:
l Parties (Partners and Communities)
l Contacts
l Routing IDs
l Certificates
l PGP Certificates
l Delivery Exchanges
l Attributes
Configuration file
The information that Interchange audits is controlled by the audit_config.xml file located in
<install_directory>/Interchange/conf.
Log files
By default, auditing is disabled on system startup, however the CSV audit file, <machine_name>_
cn_audit.csv, file is created for each node in the directory <install_
directory>/Interchange/logs. When you activate object change auditing, Interchange
generates the audit information to this file.
Additionally, by activating an option in the audit_config.xml file, you can generate audit logs to
<machine_name>_cn_audit.xml. This XML formatted file provides raw trace data that you can
use for additional fine tuning of information, which you can then convert to the CSV format. When
activated, the XML version of this log file is also located in the <install_
directory>/Interchange/logs directory.
To activate logging to the XML file, see Activate logging to XML file on page 1090.
When both output types are enabled, the logger formats and outputs information both CSV and
XML files. You must enable at least one of the output types to enable auditing.
l User – Account name of the user who implemented the change.
l Timestamp – Time and date of the change.
l Transaction ID – Unique ID used to group a set of auditing changes. When a user implements
more than one change on a single object and then saves the changes (for example, modifies
several fields in an object configuration page), the modifications are displayed in the audit log as
several actions that share a single Transaction ID.
l Object ID – Database ID of the object that has been changed.
l Object Type – Type of object that was changed (Partner, Certificate, Attribute, ...).
l Object Name – Display name of the object that was changed in the UI.
l Action – Nature of the change (Added, Updated, Deleted, ...).
l Related Object ID – Database ID of the object’s parent.
l Related Object Type – Object type of changed object's parent.
l Related Object Name – Display name of the changed object's parent.
l Attribute Name – Database name (not UI display name) of object's changed attribute.
l Old Value – Value of the attribute before the change.
l New Value – Value of the object after the change. If the modified value is an element of a list, the
entire list is recorded as the new value.
1. Go to <Interchange_install_directory>/conf.
2. Open audit_config.xml in a text editor.
3. Set the following attribute to "true" as in the following line:
<NodeType type="CN" enabled="true">
4. Save the file.
5. Restart Interchange.
1. Go to <install_directory>/conf.
2. Open audit_config.xml in a text editor.
3. Remove the comment from the line:
<!--<AuditedTransactionHandler
class="com.cyclonecommerce.persistence.audit.LogXmlTransactionHandle
r"/>-->
4. Save the file.
5. Restart Interchange.
To control the information that is generated to the output files, you can modify the attributes of the
audit_config.xml file.
By default, the configuration is set to audit specific partner-related configuration changes made in
the UI.
The audit_config.xml configuration file controls which objects are logged, based on the
following class settings:
<IncludedClasses regex=".*ExchangePoint"/>
<IncludedClasses regex=".*PropertyFieldValue"/>
<IncludedClasses regex="com.cyclonecommerce.collaboration.*Party"/>
<IncludedClasses
regex="com.cyclonecommerce.collaboration.messagingids.*MessagingId"/>
<ExcludedClasses
regex="com.cyclonecommerce.cachet.administration.*"/>
<ExcludedClasses
regex="com.cyclonecommerce.cachet.security.session.*"/>
<ExcludedClasses regex="com.cyclonecommerce.alerts.*"/>
<ExcludedClasses regex="com.cyclonecommerce.tradingengine.alerts.*"/>
<ExcludedClasses regex="com.cyclonecommerce.collaboration.alerts.*"/>
Removing any of the above settings affects the type of objects that are logged.
To log all objects, remove the comment markers from the following line:
<!--<IncludedClasses regex=".*"/>-->
Enabling the above setting, and commenting out the “Included/Excluded Classes” settings,
results in the capture of all activity persisted in the database, and enables logging of activities in the
default CSV log file.
Note Only the partner-specific objects are formatted properly in the log file, based on
configuration file settings. All other objects are logged without formatting, and in most
cases will derive names from database naming instead of UI display naming.
Detailed information about system events that users might find useful and how to manage and route
them to various log files is in System events on page 1102.
The following topics describe the log files.
l Event logs on page 1092
l System logs on page 1093
l System statistics logs on page 1093
l User interface logs on page 1093
l HTTP server logs on page 1094
l Class path logs on page 1094
l Console logs on page 1094
Event logs
These logs contain selected events from the event subsystem. These are events related to message
processing activity. If you want to use logs to monitor processing activity, these are the logs you
might want to examine. They are written to <install directory>\logs.
l hostname_te_events.log reports user-initiated configuration events for a machine in a cluster
of Interchange.
The content of the default event logs can be filtered or extended. New event logs can be created
using the event system configuration. For more information see System events on page 1102.
System logs
System logs contain formatted, time-stamped information reported by various components of the
application. The logs, intended for use by software developers in troubleshooting, are not
supported for end users. Interchange uses the Apache Jakarta Project's log4j framework to format
and manage the logs, which are generated by each Java virtual machine during runtime. The
log4j.properties file in <install directory>\conf can be edited to generate debug level
events in log files.
See Troubleshooting with the log4j file on page 1095 for information about changing and using the
file.
The system names the logs based on the names of the source JVM node. They are written to
<install directory>\logs. The logs are:
l hostname.ex.log is created by the system Executive node. This node is the first JVM to come
up and is responsible for bootstrapping all other JVMs.
l hostname.cn.log is created by the Control Node on the host it is named for. Each host in a
cluster gets a single Control Node. This JVM runs the user interface.
l hostname_te.log reports processing activity for each JVM processing node for Interchange.
System logs can report four levels of events. These are, in order of verbosity:
l Error messages indicate a possibly serious error affecting service.
l Warn messages typically have operational significance, but might not affect service.
l Info messages provide general processing information that could be useful in troubleshooting.
l Debug messages usually have much detailed information that can be useful in troubleshooting.
This level should be turned on only when necessary, as it can degrade system performance and
use large amounts of disk space.
The four logging levels are cumulative. Error messages are included at the warn level, both of which
are included at the info level, and everything is logged at the debug level. The debug level also
produces further details about processing.
Although not for end users, these logs are an aid in troubleshooting. If you contact Technical
Support for help, a technician may ask you to send copies of these files.
The log file names use as a prefix the name of the computer on which Interchange software is
installed. The names have the following format: <hostname>_cn_access.log.000001. The cn
stands for control node. The trailing number (000001) identifies rolling logs. Once a log reaches a
certain size, events write to another log (000002). This rolling occurs up to five times before events
again start writing to the first log file.
Console logs
Log files appended with console contain standard output (stdout) and standard error (stderr)
output streams from embedded third-party software.
Note If your operating system is Windows Server 2003 SP1, you need to download the Windows
Server 2003 Resource Kit Tools and use the tail.exe from that package rather than the
tail.exe in <install directory>\bin. The download link is:
http://www.microsoft.com/downloads/details.aspx?FamilyID=9d467a69-57ff-4ae7-96ee-
b18c4790cffd&displaylang=en.
1. Choose the log file you want to monitor. Logs are in the logs directory of the installation
hierarchy.
For example purposes, we choose to monitor a node events log.
2. Open a command window.
3. From <install directory>\bin, run the tail command in the following format:
tail -f path logname
In our example, the command is:
tail -f c:\<install directory>\logs\hostname_te_events.log
1. Create a directory on your local drive. For example, c:\tailoption. It is preferred to create a
separate directory rather than a subdirectory in Interchange root directory.
2. Copy tail.exe from <install directory>\bin to the directory you created in the
previous step.
3. In Windows Explore, select Tools > Folder Options.
4. Click the File Types tab.
5. Scroll down to the LOG extension in the list of file types. Select it and click Advanced.
6. Click New.
7. In the Action field, type something descriptive like Tail.
8. In the Application used to perform action field, type the path of the tail.exe file you copied
in step 2. For example, c:\tailoption\tail.exe.
9. Click OK.
10. In the Actions area, select Tail or whatever you typed in step 7 and click Edit.
11. In the Application used to perform action field, type -f between tail.exe and "%1" as follows:
Before: C:\tailoption\tail.exe "%1"
After: C:\tailoption\tail.exe -f "%1"
12. Click OK.
13. Optionally, click Set Default to make Tail or whatever you typed in step 7 the default action
for log files.
14. Click OK.
15. Click Close.
16. When the application server is running, navigate to <install directory>\common\logs,
right-click a log file, select Tail or whatever you typed in step 7, and then view the log file as it
is being written.
System logs contain formatted, time-stamped information reported by various components of the
application. Interchange uses the Apache Jakarta Project's log4j framework to format and manage
the logs. Logs are generated by each Java virtual machine during runtime.
The log4j.properties file is located in <install directory>\conf. You can edit this file to
generate debug level events in Interchange log files.
You do not need to restart the server after changing levels for message categories. You do need to
restart the server if you add or delete a property.
Caution: Using log files to monitor processing or to troubleshoot requires advanced knowledge of
the system.
The logging level settings you can use in this file are, from lowest to highest verbosity:
l Error – Error messages indicate a possibly serious error affecting service.
l Warn – Warn messages typically have operational significance, but may not affect service.
l Info – Info messages provide general processing information that could be useful in
troubleshooting.
l Debug – Debug messages usually have much detailed information that can be useful in
troubleshooting. This level should be turned on only when necessary, as it can degrade system
performance and use large amounts of disk space.
These four logging levels are cumulative: Error messages are included at the warn level, both error
and warn messages are included at the info level, and everything is logged at the debug level. The
debug level also produces more details per message.
Changing the log level of a category changes the level of all categories beneath it that do not have a
logging level explicitly specified. For example, setting category “com.foo” to debug also sets
“com.foo.fum” to debug, unless there is an explicit entry for “com.foo.fum.”
The following list describes commonly used categories, from general to more specific. In the event
that you are troubleshooting issues with the assistance of Axway support, you may be asked to add
even more specific categories, not listed here.
Once you set a category to a different level (for example, from info to warn), the level remains in
effect until you set the category to something else. Removing or commenting out the category does
not reset its level, unless the server is restarted. For this reason, if you add a category and set it to a
verbose level (for example, debug), we recommend that when you are done debugging, you reset it
to the info level, rather than removing the added category. Otherwise, you would have to wait until
the server is restarted for the verbose logging to stop.
You can change the levels of the following message categories.
l Server messages on page 1097
l Database messages on page 1098
l HTTP messages on page 1098
l FTP messages on page 1098
l SFTP client messages on page 1099
l SFTP server messages on page 1099
l PeSIT server messages on page 1099
l OFTP server messages on page 1099
l DMZ nodes messages on page 1099
l SSH nodes messages on page 1099
l Secure Relay messages on page 1100
l X.400 messages on page 1100
l X.25 messages on page 1100
Server messages
l log4j.category.com.axway=info – A main message category. Includes all system log
messages for all levels below this one.
l log4j.category.de.axway=info – Messages related to X.25 and ISDN.
l log4j.category.com.cyclonecommerce=info – A main message category. Includes all
system log messages for all levels below this one.
l log4j.category.com.cyclonecommerce.alerts.AlertDefinitionsManager=info –
Messages related to Alert system activity
l log4j.category.com.cyclonecommerce.clustercontroller=info – Messages related to
system startup and clustering.
l log4j.category.com.cyclonecommerce.collaboration,peernetwork=info – Messages
related to the peer network. These events are generated only if your user license enables peer
network functionality.
l log4j.category.com.cyclonecommerce.crossworks=info – Messages related to certificate
and cryptographic operations.
l log4j.category.com.cyclonecommerce.ediintmsg=info – Messages related to EDIINT
messages (AS1, AS2, AS3, AS4).
l log4j.category.com.cyclonecommerce.messageprotocols=info – Messages related to
protocol sender and receiver operations.
l log4j.category.com.cyclonecommerce.passportconnector=info – Messages related to
integration with Axway PassPort.
l log4j.category.com.cyclonecommerce.persistence=info – Messages related to
persistence.
l log4j.category.com.cyclonecommerce.tradingengine=info – Messages related to the
handling and routing of messages within Interchange core.
l log4j.category.com.cyclonecommerce.tradingengine.transport.email.pop=info –
Messages related to SMTP/POP delivery exchange.
l log4j.category.com.cyclonecommerce.tradingengine.transport.email.smtp=info –
Messages related to SMTP delivery exchange.
l log4j.category.com.cyclonecommerce.tradingengine.transport.Polling=info –
Messages specifically related to transport polling. Set to debug to log a message each time a
transport is polled (every 60 seconds by default).
l log4j.category.com.cyclonecommerce.tradingengine.transport.system=info –
Messages related to the transport subsystem (consumers and producers).
l log4j.category.com.cyclonecommerce.txm.clusteradmin.service.RestartManager=inf
o – Messages related to document queue processing and restart states.
l log4j.category.com.cyclonecommerce.util=info – Messages from utility classes.
l log4j.category.com.cyclonecommerce.webservices=info – Messages related to ebXML
and SOAP-based messaging.
Database messages
These are messages related to the database interface, Kodo. Typically these properties should only
be changed under direction of technical support.
l log4j.category.kodo.DataCache=warn
l log4j.category.kodo.Enhance=warn
l log4j.category.kodo.jdbc.JDBC=warn
l log4j.category.kodo.jdbc.Schema=warn
l log4j.category.kodo.jdbc.SQL=warn
l log4j.category.kodo.MetaData=warn
l log4j.category.kodo.Query=warn
l log4j.category.kodo.Remote=warn
l log4j.category.kodo.Runtime=error
l log4j.category.kodo.Tool=warn
l log4j.category.net.sf.ehcache.store.DiskStore=fatal
HTTP messages
To troubleshoot HTTP issues, change the levels of all of the following properties to debug.
l log4j.category.com.cyclonecommerce.collaboration.transport.http=info
l log4j.category.com.cyclonecommerce.tradingengine.transport.http=info
l log4j.category.com.cyclonecommerce.tradingengine.transport.http.server=info
l log4j.category.com.axway.transport.http.server=info
l log4j.category.org.mortbay=info
FTP messages
To troubleshoot FTP issues, change the levels of all of the following properties to debug.
l log4j.category.com.cyclonecommerce.collaboration.transport.ftp=info
l log4j.category.com.cyclonecommerce.tradingengine.transport.ftp=info
l log4j.category.com.cyclonecommerce.tradingengine.transport.ftp.SimpleDebug=info
l log4j.category.com.cyclonecommerce.tradingengine.transport.ftp.server=info
l log4j.category.org.apache.ftpserver=info
l log4j.category.com.cyclonecommerce.collaboration.transport.sftp=info
l log4j.category.com.cyclonecommerce.tradingengine.transport.sftp=info
l log4j.category.com.sshtools=info
l log4j.category.com.cyclonecommerce.collaboration.transport.sftp.server=info
l log4j.category.com.cyclonecommerce.collaboration.transport.ssh.server=info
l log4j.category.com.cyclonecommerce.tradingengine.transport.ssh.server=info
l log4j.category.com.maverick.sshd=info
l log4j.category.com.cyclonecommerce.tradingengine.transport.pesit=info
l log4j.category.com.cyclonecommerce.tradingengine.transport.oftp=info
l log4j.category.com.axway.dmznode=info
l log4j.category.com.maverick=info
l log4j.category.com.axway.multiplex=info
l log4j.category.com.axway.niocore=info
l log4j.category.com.axway.packet=info
l log4j.category.com.axway.tools=info
l log4j.category.com.axway.xsr=info
l log4j.category.com.axway.xsr.log.heartbeat=error
l log4j.category.com.axway.xsr.log.incall=error
l log4j.category.com.axway.xsr.log.listen=error
l log4j.category.com.axway.xsr.log.listenOnce=error
l log4j.category.com.axway.xsr.log.outcall=error
X.400 messages
To troubleshoot X.400 issues, change the level of the following property to debug.
l log4j.category.com.cyclonecommerce.tradingengine.transport.x400=info
X.25 messages
To troubleshoot issues for trading with partners using embedded OFTP V1 over X.25 servers, change
the level of the following properties to debug.
l log4j.category.de.axway.lib.tlib.x25OverTcp.SnmpWatcher=fatal
l log4j.category.de.axway.mvhTMP.SnmpTests=off
l log4j.category.com.axway.transport.ioclients.x25client=info
l log4j.category.com.axway.transport.ioservers.x25server=info
To use this option, the machine running Interchange must have an active Internet connection, as
the log files are sent via HTTP. The application does not need to have a running processing node.
The following are the fields on the send logs page.
l Description – Type pertinent information to identify yourself, your organization and the issue
you want resolved. Other information is helpful, such as the version and build number of the
Interchange you are using (found in Help > About). You can also identify the operating
system and database type and describe the sequence of events or actions leading to the
problem.
If you have a technical support contract and have not opened a support ticket for the issue, go
to https://support.axway.com and open one. Or, send a message to support at
support@us.axway.com. If you already have an open ticket, include the number in the
description.
l Proxy – This field is active only if your community routes outbound HTTP messages through a
proxy. If the field is active, select a community. If you are not sure whether a proxy is required,
ask your network administrator. See HTTP outbound proxy on page 584 for more information.
l Perform thread dump (places output in each node log) – Provides a snapshot of all
threads in the Java virtual machines on the running nodes. This checkbox is selected by default.
You can leave the thread dump turned on, unless technical support advises otherwise.
If the option for sending log files to technical support is not available because it is impractical or not
possible to access the user interface, there is a command-line tool you can use instead. See
diagnose on page 103.
System events
Interchange generates, publishes and routes defined events related to system activity
Events are published in various ways: in log files, on the user interface and by email. These are
events as cataloged in Event tables on page 1119.
The events.xml file on page 1102 describes how events are published to log files and JMS routers.
The alerts.xml file on page 1114 describes publishing events about Interchange to the user interface
and by e-mail.
The events.xml and alerts.xml files have default settings for publishing events without user
intervention. Both files, however, are configurable to expand or reduce the volume of published
events.
Related topics
l Event levels on page 1102
l The events.xml file on page 1102
l Log file event router on page 1108
l Oracle AQ event router on page 1110
l XML for JMS and AQ event routers on page 1110
l The alerts.xml file on page 1114
l Event tables on page 1119
Event levels
A “level” indicates the significance of an event. Levels rank events from low to high importance.
There are four levels, which are listed in order of lowest to highest importance: Low, High, Warning
and Error.
Event levels provide different degrees of information. Low level events contain the most detailed
information and high level events contain the most general information. The warning and error
levels do not correspond to a level of detail, but do infer degrees of importance.
Each event contains standard information, including:
l Event type
l Event level
l Time stamp
l Name and address of the node that spawned the event
l Name of the application that spawned the event
An event also may have specific information in the form of metadata content or extended event
content.
The events.xml file that manages logged events is located at <Interchange install
directory>\conf. You can edit this file to control what events are generated and where they are
published. By default, some (but not all) events are configured in events.xml to determine how
they are published to system log files in the logs directory (see Log file tracking on page 1092).
Using event routers, you also can publish events to a JMS queue.
In addition to using event routers that write events to log files or pass events to some other process,
event filters provide a way for determining what events are delivered to a router. Events can be
filtered based on type or level. You can build complex filters from multiple simple filters.
Caution Before editing the events.xml file, it is recommended that you make a copy of it in case
you want to restore the default configuration for events.
The default configuration of events.xml is to write an events log file for each system node to the
logs directory. This results in the generation one or more log files that, for Interchange, are named
in the following format: <hostname>_te_events.log.
One of these event logs is the system control node events log. If you run Interchange on multiple
computers, there is a control node running on each machine. By default the name of the control
node is the host name of the computer. The name of the events log file for the control node looks
like this: <hostname>_cn_events.log.
The number of other events log files that are generated depends on how many JVM processing
nodes you configure and start in the user interface ( see the topic about processing nodes and
clustering in the Interchange Installation Guide) . There must be at least one processing node, but
there can be more.
For details on how to configure routers, see Log file event router on page 1108 and JMS event
router on page 1110.
An example of EventRouters section of events.xml follows:
<EventRouters>
<!---->
<EventROuter id="Important Events to log File"
class="com.cyclonecommerce.events2.router.LogFileRouter" active="true">
<Parameters file="../logs%nodeName%_events.log" rollOnStart="false"
l EventRouter attributes – The EventRouters element can contain any number of EventRouter
elements, each defining an event router to be installed in the event system. Each EventRouter
element must have an id attribute and a class attribute. Other attributes are optional.
o id must specify a unique identifier for the router. If the configuration contains more than
one EventRouter element with the same identifier, only the last router with the same
identifier is installed.
o class must specify the full name of a class that implements the
com.cyclonecommerce.events2.router.EventRouter interface.
o active is optional and specifies whether the event router should be made active when
installed. Only an active router is started when the server starts. The value of the active
attribute must be true (the default) or false.
o priority is optional and specifies the priority of the router relative to other routers. The value
of the priority attribute must be a positive integer. The system event dispatcher sends events
to routers in priority order of highest to lowest. The lower the value of the priority attribute,
the higher the priority, with 1 the highest priority. If multiple routers have the same priority,
events are dispatched to those routers in no particular order. If the priority attribute is not
specified, the priority for the router defaults to the middle between the highest and lowest
possible integer value.
<MetadataProcessors>
<!--
Do NOT remove or change the following MetadataProcessorList
definition!
-->
<MetadataProcessorList id="Messaging">
<MetadataProcessor type="CSOS.Messaging"
class="com.cyclonecommerce.collaboration.events.MessagingMessageMetadata
Processor"/>
<MetadataProcessor type="Messaging.Message
class="com.cyclonecommerce.collaboration.events.MessagingMessageMetadata
Processor"/>
<MetadataProcessor type="Messaging.Transport"
class="com.cyclonecommerce.collaboration.events.MessagingTransportMetada
taProcessor"/>
<MetadataProcessor type="Messaging.Packaging"
class="com.cyclonecommerce.collaboration.events.MessagingPackagingMetada
taProcessor"/>
</MetadataProcessorList>
<!---->
</MetadataProcessors>
Caution Although the following paragraphs explain this section of the file, it is imperative that you
do not change it.
The MetadataProcessors element can have any number of MetadataProcessorList elements, each
defining a list of metadata processors. Each MetadataProcessorList element must have a unique id
attribute and can contain multiple MetadataProcessor elements, but is not required to have any.
Each MetadataProcessor element must have a type attribute specifying an event type and a class
attribute specifying the name of a class that implements the
com.cyclonecommerce.events2.metadata.MetadataProcessor interface.
When an event router needs a metadata event content processor, it searches the referenced
MetadataProcessorList element for the first MetadataProcessor element with an event type that
matches the type of the event being processed by the event router. The event type in the
MetadataProcessor element can be the exact type or a super-type of the router's event type. The
MetadataProcessor elements are searched in the order specified.
An example of the EventFilters section of events.xml follows:
<EventFilters>
<!---->
<EventFilter id="Integrator">
<OrFilter>
<EventTypeFilter type="Messaging.Transport.ReceiveFailure"/>
<EventTypeFilter type="Messaging.Packaging.DecryptionFailure"/>
<EventTypeFilter
type="Messaging.Packaging.SignatureVerificationFailure"/>
<EventTypeFilter
type="Messaging.Packaging.CertificateValidationFailure"/>
<EventTypeFilter type="Messaging.Packaging.DecompressionFailure"/>
<EventTypeFilter type="Messaging.Message.Collaboration"/>
<EventTypeFilter type="Messaging.Message.MessagePackaged"/>
<EventTypeFilter type="Messaging.Transport.SendFailure"/>
<EventTypeFilter type="Messaging.Transport.OutputTransferCompleted"/>
<EventTypeFilter type="Messaging.Transport.RetryFailure"/>
</OrFilter>
</EventFilter>
<EventFilter id="Messaging To Database">
<AndFilter>
<EventTypeFilter type="Messaging"/>
<OrFilter>
<EventLevelFilter level="High"/>
<EventLevelFilter level="Warning"/>
<EventLevelFilter level="Error"/>
</OrFilter>
</AndFilter>
</EventFilter>
The EventFilters element can have any number of EventFilter elements, each defining an event filter.
Each EventFilter element must have an id attribute that specifies a unique identifier for the filter.
Although more than one EventFilter element can have an id attribute with the same value, we
recommend that each EventFilter element have its own id.
A filter defined by an EventFilter element only starts upon server startup when an EventRouter
element references it directly or indirectly.
Each EventFilter element defines a single event filter. A single event filter can be simple or complex.
Simple filters
The following are simple event filters:
l <AllFilter/>
A filter that passes all events.
l <NoneFilter/>
A filter that passes no events.
l <EventTypeFilter type="type"/>
A filter that passes all events of a specified type or any of its sub-types. The type attribute
must be specified and its value must be the name of an event type defined in Event tables
on page 1119.
For example, if you specify a type of Messaging.Message, all events with that prefix pass
through the filter.
l <EventLevelFilter level="level"/>
A filter that passes all events at the specified level and above. The level attribute must be
specified and its value must be, in order of least to most important, Low, High, Warning
or Error.
For example, if you specify a level of Low, all Low level messages pass through the filter, as
well as all High, Warning and Error events. Conversely, if you specify a level of Error, only
Error level events pass.
l <EventFilterRef ref="filterId"/>
A filter that refers to another event filter. Using this mechanism supports the re-use of event
filters. The ref attribute must be specified and its value must equal that of an id attribute in
an EventFilter element. Circular filter references are not allowed.
Complex filters
The following are complex event filters:
l <NotFilter>
A filter that passes all events that do not pass the simple or complex event filter defined
within.
l <AndFilter>
<!-- Any number of event filter definitions may appear here. -->
</AndFilter>
A filter that passes all events that pass all the event filters defined within.
l <OrFilter>
<!-- Any number of event filter definitions may appear here. -->
</OrFilter>
A filter that passes all events that pass any of the event filters defined within.
com.cyclonecommerce.events2.router.LogFileRouter
The default log file event router is configured in a system file for managing events. The file is
<install directory>\conf\events.xml. The following is an example of how the log file
event router is set up in events.xml. For other details about this file, see The events.xml file on
page 1102.
The MetadataProcessorListRef element references an element in the MetadataProcessors section of
events.xml. The EventFilterRef element references a filter in the EventFilters section of
events.xml. The following explains the attributes of the EventRouter and Parameters elements in
the router definition.
l EventRouter attributes on page 1109
l Parameters attributes on page 1109
EventRouter attributes
The following explains the attributes of the EventRouter element in a log file configuration in
events.xml.
l id – A unique identifier of the router.
l class – Specifies the name of the Java class that implements the router interface.
l active – Specifies whether the router should be made active when the server starts.
Parameters attributes
The following explains the attributes of the Parameters element in a log file configuration in
events.xml.
l file – Specifies the name of the event log file.
l rollOnStart – Specifies whether the log file should be rolled when the log file router is started.
Rolling a log file means starting a new log file, saving the current log with an extension of .1 to
the file name and renaming any older log files by incrementing the extension by 1. For example,
a file with an extension of .1 is renamed .2, and so on. The default value is false. This attribute
is optional.
l autoFlush – Specifies whether events are written immediately to the log file. Using a value of
true is handy when tailing the log and you do not want to wait before events are displayed. The
default value is false, which causes a delay in writing events to the log, a lag that varies
depending on the operating system. This attribute is optional.
l gmt – Specifies whether time stamps should be GMT time. If not, time stamps use the local time
zone. The default value is false if not specified. This attribute is optional.
l maxFileSize – Specifies the maximum size of a log file before it is rolled. The size is specified in
bytes. The letters K, M or G (not case sensitive) can follow a numerical value to specify kilobytes,
megabytes or gigabytes, respectively. This option only applies when logging to a file (not
standard output). The default value is the maximum file size supported by the operating system.
This attribute is optional.
l maxBackupFiles – Specifies the maximum number of rolled log files to retain. This is in
addition to the current log file. The default behavior is to retain all archived log files. This
attribute is optional.
l maxContentDepth – Specifies the maximum depth of extended content to display. A value of
0 displays no extended content, a value of 1 displays the top level of extended content, and so
on. The default behavior is to display all extended content. This attribute is optional.
l rollTimes – Specifies when to roll the log, regardless of file size. Times are specified in hours
and minutes, using a 24-hour clock. If the value of the gmt attribute is true, the times in this
attribute are assumed to be GMT times; otherwise, they are assumed to be local times. This
option only applies when logging to a file (not standard output). The default behavior is not to
roll at any specific times. This attribute is optional.
Instructions for configuring a JMS event router are in the events.xml file.
Instructions for configuring an Oracle AQ event router are in the events.xml file.
<MicCheckFailed>false</MicCheckFailed>
<IsResponsePositive>false</IsResponsePositive>
<IsFinalState>false</IsFinalState>
<MaxRetries>0</MaxRetries>
<NextRetryNum>0</NextRetryNum>
<NextRetryTime>1969-12-31T19:00:00</NextRetryTime>
<CompressionType>None</CompressionType>
<ReceiptRequested>None</ReceiptRequested>
<SendAttempt>0</SendAttempt>
<MaxSendAttempts>0</MaxSendAttempts>
<ResendInterval>0</ResendInterval>
</MessageSnapshot>
</metaData>
</CycloneEvent>
l id – Unique event ID. Each event has its own unique ID.
l type – The type of the event.
l level – The level of the event (low, high, warning, error).
l created – Date and time the event was created in yyyy-MM-dd’T’kk:mm:ss format.
l dispatched – Date and time the event was dispatched in yyyy-MM-dd’T’kk:mm:ss format.
l nodeid – The ID of the node that created the event.
l extendedContent – Extended content associated with the event. Name-values pairs that
provide additional data for an event.
l BackupFilename – Name of the message backup file.
l BusinessProtocolType – Business protocol for the current packaging state. The value depends
on a message's state. For example, raw represents an unpackaged state and EDIINT AS1
represents a packaged state for the AS1 protocol.
l BusinessProtocolVersion – Version of the business protocol handler for the current packaging
state of the message. The value depends on a message's current state. The value indicates the
version of the ProtocolSender or ProtocolReceiver handling a message. The value does not
necessarily coincide to a specific packaging specification or RFC.
l CompressionType – The type of compression used to compress a message.
l ConsumptionFilename – Name of the file consumed from the pickup exchange point.
l ContentMic – MIC value of the message.
l ContentMimeType – The MIME type of the message payload.
l CoreId – Unique message identifier within Interchange.
l DigestAlgorithm – Digest algorithm used for the message.
l Disposition – Disposition modifier value used when packaging EDIINT MDN. Only set on MDNs
that indicate an unpackaging error. Only set on an outbound MDN message.
l DocumentId – Control ID if the message payload is EDI.
l ebXMLAction – For ebXML, identifies a process within a service that processes the message.
The action must be unique within the service in which it is defined. The service designer defines
the value of the action element.
l ebXMLConversationId – For ebXML, a string identifying a set of related messages that
comprise a conversation between two parties. It must be unique in the context of the specified
CPA ID.
l ebXMLCpaId – For ebXML, identifies the CPA that governs the collaboration between the
trading parties. This matches the CPA ID in the CPA, not the name of the CPA XML file.
l ebXMLMessageId – For ebXML, a unique identifier for a message that conforms to RFC 2822.
l ebXMLRefToMessageId – For ebXML, when present, this must have a MessageId value of an
earlier message to which this message relates. If there is no related earlier message, this element
must not be used.
l ebXMLService – For ebXML. identifies the service that acts on the message. The designer
defines the service. A service is related actions for an authorized role within a party.
l EncryptionAlgorithm – Encryption algorithm used for the message.
l IntegrationId – Used to attach customer-specific ID to a message.
l IsFinalState – True if the message is in a terminal state (delivered, ignored, rejected, joined,
resubmitting).
l IsResponsePositive – True if the response (acknowledgment) message was positive; false
otherwise.
l MaxRetries – Maximum number of times to retry a message after a transport failure.
l MaxSendAttempts – The maximum number of times to resend a message after a failure to
receive a response (acknowledgment).
l MessageContentSize – The size of the message content when the event was fired. Note that
the message content size changes as the message flows through Interchange; compression,
signing, encryption, packaging affect size at one stage or another.
l MessageId – Business protocol message ID.
l MessageState – The state of a message within Interchange. For example, consumed,
produced, rejected.
l MicCheckFailed – True if MIC checking of inbound EDIINT message fails. Only set on an
outbound MDN message.
l NextRetryNum – The next retry increment.
l NextRetryTime – The time to execute the next retry after a transport failure.
l PeerAddress – URL of a peer in a peer network.
l ProductionFilename – Name of the file produced to the delivery exchange point.
l ReceiptMicAlgorithm – MIC algorithm used for the receipt.
l ReceiptRequested – The type of receipt requested for a message (NONE, SIGNED or
UNSIGNED).
l ReceivedContentMic – Received content MIC value used when packaging EDIINT MDN. Only
set on an outbound MDN message.
l ReceiverRoutingId – Routing ID of the receiving party.
l RefToCoreId – Unique message identifier that relates to this message. Typically set on a receipt
message, RefToCoreId refers to the request message.
l RejectionDescription – Rejection reason for a rejected message.
l ResendInterval – The elapsed time to wait between resend attempts.
l ResponseCoreId – The core id of the response (acknowledgment) message for this message.
l SendAttempt – The number of sends attempted.
l SenderRoutingId – Routing ID of the sending party.
l TransportType – The type of transport that consumed or produced the message. For example,
HTTP, HTTPS, FTP, MQSERIES, JMS, SFTP, FILESYSTEM and PLUGGABLE.
The persistence event router remains in events.xml, but is commented out and inactive. See the
following code example.
The persistence event router example in events.xml follows.
<!--
<EventRouter id="Message Events to Database"
class="com.cyclonecommerce.events2.router.PersistenceRouter"
active="true"
priority="2147483647">
<EventFilterRef ref="Messaging To Database"/>
</EventRouter>
Keeping the router inactive is recommended. The cases for activating the router are rare (for
example, a third-party back-end system retrieves event data from the database). Before activating,
consult technical support.
The default configuration of alerts.xml calls for publishing some but not all of the predefined
events cataloged in Event tables on page 1119. The default configuration reports events in the
following general categories:
l Certificates about to expire
l Message errors involving packaging and invalid sender or receiver
l JVM node errors
l Accessing an unlicensed feature
l Transport errors
l Configuration errors
l Unexpected errors
l Fatal errors
From an XML editor, you can edit the file to extend reporting to other categories of events.
1. Configure a community. Make sure to do the following:
l Configure the global external SMTP server. This is required for emailing events. See
Configure the global external SMTP server on page 60.
l In the contact information for the community, use a valid email address. In some instances,
alerts.xml uses this as the “from” address for emailed events.
l Set up a secure email protocol exchange for the community for receiving messages from
partners. Use a detached server for this transport; do not use an embedded server. Set up
this exchange even though partners might not use it to send messages to your community.
In some instances, alerts.xml uses the SMTP delivery address for this exchange as the
“from” address for emailed events.
2. Make a copy of alerts.xml and keep it as a backup.
3. Open alerts.xml for editing.
<Communities>
<!-- Uncomment and configure
<Community id="PC1">
<ActionParameters>
<Parameter name="AlertEmailAddresses" value="mail@domain.com"/>
</ActionParameters>
</Community>
-->
<!--
Used whenever there is an event for which there is no community
routing ID or there
is no configuration for the community ID for which the event was
generated.
-->
<!-- Uncomment to enable
<Community id="default">
<ActionParameters>
<Parameter name="FromEmailAddress" value="mail@domain.com"/>
<Parameter name="AlertEmailAddresses" value="mail@domain.com"/>
</ActionParameters>
</Community>
-->
</Communities>
The first block of commented-out elements, identified by Community id="PC1", is for
specifying “to” addresses with a specific community as the “from” address. A community
routing ID is the value of the Community id element. By virtue of the routing ID, Interchange
uses the email address of the secure email protocol exchange for the community as the “from”
address. Configuring this block is optional. It is useful if you have two or more communities.
The second block of commented-out elements, identified by Community id="default", is
for specifying default “from” and “to” addresses for emailed events. Configuring default
addresses is required even if you use the optional first block. This is because some events are
not associated with a community routing ID and the default “to” and “from” addresses must be
used for such events.
6. Uncomment the second block of commented-out elements for the default “to” and “from”
addresses. Configuring this is required.
Use a community routing ID as the value of Community id.
Editing alerts.xml
You can edit the alerts.xml file to alter the events that are published to the database or delivered
by email. You must understand XML to change this file. The following describes some of the key
elements in the file.
l Interval minutes – Interchange only fires one action (email or database) for multiple similar
events that occur within a specified interval. If the following metadata matches, the events are
considered duplicates. This is a way to limit the number of email messages sent for the same
events in a given period of time.
o AlertDefinition.Name
o Event.EventType
o Event.EventLevel
o Event.ExtendedEventContent
o Message.SenderRoutingId
o Message.ReceiverRoutingId
o Message.BusinessProtocolType
o Message.BusinessProtocolVersion
l AlertDefinition – AlertDefinition elements define the type of events to publish, where to deliver
the events (database or email) and the information to include in event messages.
l Events – Events elements refer to some of the predefined event types cataloged in Event tables
on page 1119.
l Actions – One or more actions can be taken when an alert definition fires. Two actions are
supported: database and email. The database action delivers triggered events to the user
interface. The email action delivers events by email.
l Address – Each email Action type element has an Address parameter. The default value of
{AlertEmailAddressesses} means the “to” addresses in the Communities elements at the
bottom of the file are used. You can substitute addresses without brackets for the bracketed
parameter value.
l Format – Format elements control the format and content of the email messages. Valid formats
are text and XML. If the format is text, a list of Field elements can be defined that supply the
content of the email message. Each Field element results in a new line in the email message. The
field has a label and a hard-coded value or a reference to some metadata contained in the event.
See Metadata for email events on page 1117.
l Communities – The Communities element defines the values for any bracketed Address
parameters referenced in the Actions element. For every event, if there is a community ID and the
action is email, then the name of the bracketed parameter is looked up for that community ID.
This allows the email address to be configured for each community.
Metadata Description
AlertDefinition.Name Name of the alert definition
Event.Name Name of event
Event.EventType Type of event (usually same as Event.Name)
Event.EventLevel Level of event (high, warning, error)
Event.Timestamp Time event was triggered.
Event.ExtendedEventContent Extra information that may be with the event
Event.NumberOfOccurances Number of times the event has been published
The following metadata are available to events at the Messaging level (see Messaging on page 1120)
in the default configuration of alerts.xml. All of these fields names are included in generated
email messages. Fields without data display as blank in email messages.
l Message.CoreId
l Message.RefToCoreId
l Message.SenderRoutingId
l Message.ReceiverRoutingId
l Message.DocumentId
l Message.MimeType
l Message.MessageState
l Message.MessageContentSize
l Message.TransportType
l Message.PeerAddress
l Message.MessageId
l Message.BusinessProtocolType
l Message.BusinessProtocolVersion
l Message.EncryptionAlgorithm
l Message.DigestAlgorithm
l Message.ContentMic
l Message.RejectedReason
l Message.ReceivedContentMic
l Message.MicCheckFailed
l Message.Disposition
l Message.SenderRoutingIdType
l Message.ReceiverRoutingIdType
l Message.TrueSenderRoutingIdType
l Message.TrueSenderRoutingId
l Message.TrueReceiverRoutingIdType
l Message.TrueReceiverRoutingId
l Message.ResponseCoreId
l Message.IsResponsePositive
l Message.IsFinalState
l Message.EbxmlService
l Message.EbxmlAction
l Message.EbxmlCpaId
l Message.EbxmlConversationId
l Message.EbxmlRefToMessageId
l Message.EbxmlMessageId
l Message.MaxRetries
l Message.NextRetryNum
l Message.NextRetryTime
l Message.CompressionType
l Message.ReceiptTypeRequested
l Message.SendAttempt
l Message.MaxSendAttempts
l Message.ResendInterval
Event tables
Tables of all events are provided in the following topics.
l Peer network on page 1127
l Administration alert on page 1127
l Administration configuration on page 1128
l Trust-server Status Lists (TSLs) on page 1131
l DMZ on page 1132
l CSOS on page 1132
l Certificate exchange messages on page 1133
l Event tables on page 1119
l Terminal events on page 1135
l Administration system on page 1136
l Administration licensing on page 1136
l Administration persistence on page 1137
l Security on page 1137
Events follow a hierarchy that enables you to filter the volume of reported events. For example, the
following event from the table Messaging on page 1120 is the full detail for this event:
Messaging.Message.MessageUnpackaged.Request
Using an event filter, you can specify how many Messaging events are published. If you filter events
at the top level, Messaging, all events at that level and below are reported. This would include all
events in the following tables: Messaging on page 1120, Transport on page 1125 and Packaging on
page 1126.
You could exclude many events by filtering according to the next level in the hierarchy. For
example, if you filtered at the Messaging.Message level, all events in the table Messaging on page
1120 would be reported. No events would be reported from the tables Transport on page 1125 and
Packaging on page 1126.
You could drop another level and exclude even more events. For example, if you filtered at the
Messaging.Message.MessageUnpackaged level, only three events from the table Messaging on
page 1120 would pass the filter.
The tables give the level of each event.
A “level” indicates the significance of an event. Levels rank events from low to high importance.
There are four levels, which are listed in order of lowest to highest importance: Low, High, Warning
and Error.
Event levels provide different degrees of information. Low level events contain the most detailed
information and high level events contain the most general information. The warning and error
levels do not correspond to a level of detail, but do infer degrees of importance.
Messaging
The following are events that occur during business message processing.
Messaging.Message. is the prefix for these events. In other words, the syntax of the first event in
the following table is actually Messaging.Message.ActionTreeExecuted.
MessageIgnored High
Transport
The following are transport events.
Messaging.Transport. is the prefix for these events. In other words, the syntax of the first event in
the following table is actually Messaging.Transport.ConnectionClosed.
Packaging
The following are message packaging events.
Messaging.Packaging. is the prefix for these events. In other words, the syntax of the first event
in the following table is actually Messaging.Packaging.CertificateValidationFailure.
Peer network
The following are peer network events.
Messaging.PeerNetwork. is the prefix for these events. In other words, the syntax of the first
event in the following table is actually Messaging.PeerNetwork.ReceiptForwarded.
Administration alert
The following is an event that occurs when an alert is generated. Such an event also contains
information about the particular alert. See The alerts.xml file on page 1114.
Administration configuration
The following are administration configuration events, which track changes to the system and
resources used and accessed.
Administration.Configuration. is the prefix for these events. In other words, the syntax of the
first event in the following table is actually:
Administration.Configuration.CertificateManagement.PersonalCertific
ateAboutToExpire.
Administration.Configuration. is the prefix for these events. In other words, the syntax of the
first event in the following table is actually:
Administration.Configuration.TslManagement.UpdateInitiated
DMZ
The following events are related to messages processed via Secure Relay.
CSOS
The following are events related to CSOS document processing. These events are generated only if
your user license allows CSOS processing.
CSOS-related events provide extended CsosMetadata content for one or more of the following:
l CsosDeaRegistrationNumber
l CsosPoNumber
l X509Certificate
l X509Certificate is the CSOS signing certificate.
These metadata are reported when available. For example, if a CSOS order verification failed event
occurs because the signing certificate is not trusted, the DEA number and purchase order number
are not available because the CSOS signature could not be validated. In this case, the event contains
only the certificate metadata.
In addition to the events in the following CSOS table, these other events also contain extended
CsosMetadata content if generated when CSOS messages are handled:
l Messaging.Message.MessageRejected
l Messaging.Message.Duplicate.Payload
CSOS events follow.
Terminal events
The significance of the following events, and the reason for presenting them apart from other
events, is these are terminal events, which indicate the end of processing in Interchange.
l Messaging.Message.PayloadDelivered
Level: High
o For an inbound message, the payload was sent to integration.
o For an outbound message, the payload was sent to the partner and a receipt (if expected)
was received.
l Messaging.Message.ResponseDelivered
Level: High
o For an inbound receipt, it has been received and processed successfully,
o For an outbound receipt, it has been sent successfully.
l Messaging.Message.MessageRejected
Level: Error
o An inbound or outbound message containing a payload was rejected.
o This could due to a transport or security failure, application configuration error, or systems
error. The reason for the rejection and other information are provided with the response.
l Messaging.Message.MessageIgnored
Level: High
Processing has reached a point where the message can be safely ignored and not processed
further. The following are the known instances of when a message is ignored.
o When an AS2 message containing a payload or response is sent, the received synchronous
HTTP response is treated as a message. If a synchronous MDN is not expected and the HTTP
response is a 200-level response, the message is ignored.
o When the sender for the raw business protocol is asked to send a message that does not
contain any content (either there really is no content or the content is of zero length), the
message is ignored.
o When the web services protocol receiver receives a duplicate of a previously received
message, the duplicate is ignored.
o When the ebXML protocol receiver receives an asynchronous SOAP fault, the SOAP fault
message is ignored.
o When the ebXML protocol receiver receives a synchronous SOAP fault for an unknown
message, the SOAP fault message is ignored.
o When the ebXML protocol receiver receives a duplicate of a previously received message, all
the messages containing the payloads of the duplicate message are ignored.
o In the peer network, when a receipt is received by a peer who did not send the message the
receipt acknowledges. The peer ignores the receipt, but sends a new peer message, whose
packaged content is the receipt. This ensures the receipt properly finds its way to the peer
who originated the outbound message to the partner.
Administration system
Administration.System. is the prefix for these events. In other words, the syntax of the first event
in the following table is actually Administration.System.ClusterBus.ErrorEvent.
Administration licensing
The following table shows the administration licensing event.
Administration persistence
The following table shows the administration persistence event.
Security
The following events are related to user-level security auditing.
Security. is the prefix for these events. In other words, the syntax of the first event in the following
table is actually Security.Authentication.AuthenticationFailure.
ebXML
See ebXML troubleshooting on page 579.
HTTP
See HTTP connection troubleshooting on page 589.
SFTP
See Troubleshooting SFTP on page 285.
Web service
See Troubleshoot Web Services configurations on page 732.
X.25
See X.25 troubleshooting on page 635.
l Operating system issues
l Product issues
l Configuration issues
Collect logs
The first step in troubleshooting is to collect Interchange logs, and then analyze this data to identify
the module that threw the first error.
Debug mode
If the logs and traces do not provide enough information, the next step is to run the servers in
debug mode.
4. Save the file.
5. Restart Interchange.
To view Interchange debug logs, go to <install director>\logs and open the file <machine
name>_cn_console.log.
Windows
Use the Windows task manager to kill the cn (control node) and the Interchange processes.
View the output files:
l <install directory>/logs/<machine_name_cn_console.log>
l <install directory>/logs/<machine_name>_console.log
UNIX
Use the following commands to kill the control node:
l ps -ef | grep cn
l kill -3 <pid>
View the output file: <install directory>/logs/<machine_name_cn_console.log>
Use the following commands to kill the Interchange node:
l ps -ef | grep te
l kill -3 <pid>
View the output file: <install directory>/logs/<machine_name>_console.log
Most startup scripts start 8 instances of nfsd (RPCNFSDCOUNT=8). You can increase this value to 30
threads (RPCNFSDCOUNT=30). Alternatively, you can change values when starting nfsd, using the
number of instances as a command line option.
Procedure:
1. On each node, go to the /etc directory.
2. In the stab file, set lookupcache=none.
For additional information about nfs stab file formats and options, see
http://unixhelp.ed.ac.uk/CGI/man-cgi?nfs+5 .
To test for the existence of the nsf cache:
1. Go to the same folder on both nodes.
2. On node 1 execute: stat filename
If a filename does not exist, an error is returned.
3. On node 2 execute: touch filename
4. On node 1 execute again: stat filename
You may still obtain errors for a certain period of time.
5. Repeat the stat filename command until the file appears.
NFS read lease bug workaround for Linux distributions running kernel
version 2.x (2012/11/14)
NFS uses a read lease to guarantee that a client can perform local read opens without informing the
server. Axway tests show that under some circumstances this read lease is not updated correctly and
causes inconsistency on what the different nodes see on the shared file system. This can cause the
nodes in a cluster to stop and restart unexpectedly and repeatedly.
Because this issue is not currently resolved in the 2.x Linux kernel, Axway recommends that you turn
off the read lease function on the NFS server. This is done by setting a flag in the /proc/sys file
system to tell the kernel to not allow any use of this feature.
The following procedure provides an example of how to set the flag on a Red Hat machine acting as
NFS server. Similar procedures can be adapted for other distributions.
1. Important: Stop Interchange before you perform this procedure.
2. As root, execute the command:
echo 0 > /proc/sys/fs/leases-enable
3. Restart the NFS daemon:
/etc/init.d/nfs restart
4. After you complete the previous steps, unmount and re-mount from the NFS clients.
Note The change implemented by this procedure disappears when you reboot the server. To
make this change persistent over machine restarts, add the following lines to a start-up
script that is executed before the NFS daemon is started. A good place for this is in
/etc/init.d/nfs in the "start" section, after the check for root UID but before the nfsd
is started (insertion in bold):
Application delivery
An object that specifies an exchange point for messages moving from the trading engine to the
back-end system.
Application pickup
An object that specifies an exchange point for messages moving from the back-end system to
the trading engine.
certificate
A digital certificate contains keys used for encrypting and signing messages, and also for
decrypting and verifying signatures. A certificate can contain a public-private key pair or a
public key only.
cipher suite
A cipher suite is a collection of security algorithms used in making connections via Secure
Sockets Layer or Transport Layer Security. For example, an SSL or TLS protocol requires signing
messages using a message digest algorithm. But the choice of algorithm is determined by the
particular cipher suite being used for the connection. Typically, you can select an MD5 or SHA
digest algorithm.
cluster
A network environment where two or more computers are running the trading engine as players
in a single distributed application. Clustering can enhance fail-over capability and improve
performance. This is available by licensing agreement.
collaboration settings
Control packaging for messages a community sends to partners. Determines whether messages
are sent in cipher or plain text, and whether partners must acknowledge receiving messages.
Community
A community is an object that represents your local way of grouping trading partners. You use
it to define your organization’s internal processes for handling messages, and how the
organization expects to send messages to and receive messages from remote partners.
consumption exchange
Transports used for picking up messages from integration or receiving messages from partners
are consumption delivery exchanges. The trading engine is said to consume messages from
such exchanges.
CPA
Collaboration Protocol Agreements. A CPA is an XML-based document that specifies an ebXML
trading agreement between trading partners.
CSOS
Controlled Substance Ordering System. For licensed users, the trading engine supports digital
signing and verification of controlled substance orders in compliance with the Controlled
Substance Ordering System of the U.S. Drug Enforcement Administration.
Deliver
A deliver message contains one certificate that should match an existing certificate associated
with the sender. The recipient should start using the new certificate some time before the
current matching certificate expires. The recipient can accept or reject the certificate.
delivery exchange
The message protocol or transport or both a community or partner uses to send and receive
messages.
DMZ node
DMZ nodes in the demilitarized zone (DMZ) or perimeter network securely relay messages from
partners to the trading engine in the protected, internal network. This is an optional feature
that your software license may not support.
document
A business document such as a purchase order, invoice, shipping notice, and so on.
EDI
Electronic data interchange.
EDIFACT
Electronic Data Interchange For Administration Commerce and Transport. An EDI standard of
the International Organization for Standardization (ISO).
ePedigree
An electronic audit trail that follows a drug from the time it is manufactured through the
distribution system to a pharmacy. The Axway ePedigree product is comprised of software that
generates and manages pedigrees, a trading engine that transfers pedigrees among partners,
and a viewer (Pedigree Viewer) that can be used to search for and perform tasks on stored
pedigrees, as well as to initiate electronic pedigrees from paper pedigrees.
events
Events are activities about the movement of documents. For instance, events note that
documents have been packaged, sent, received, unpackaged and so on.
FIPS
Federal Information Processing Standards (FIPS) have been developed by the U.S.
government. FIPS describes document processing, cryptographic algorithms and other
information technology standards for use within non-military government agencies and by
government contractors and vendors who work with the agencies. Your user license for this
software supports FIPS-compliant implementations of certain cryptographic algorithms or IAIK
implementations of those algorithms. Also see IAIK in the glossary. For more information about
FIPS, perform a Web search Federal Information Processing Standards Publications
IAIK
The Institute for Applied Information Processing and Communications (IAIK) researches
information and computer security. This includes design and implementation of cryptographic
algorithms and protocols in hardware and software, network security and trusted computing.
Your user license for this software supports FIPS-compliant implementations of certain
cryptographic algorithms or IAIK implementations of those algorithms. Also see FIPS in the
glossary. For more information about IAIK, perform a Web search on The Institute for Applied
Information Processing and Communications (IAIK).
inbound
A message received over the Internet from a partner. An inbound message is unpacked and sent
to inbound integration.
integration
The transport to the back-end system for picking up outbound messages or delivering inbound
messages. Supported integration transports include file system, FTP, JMS and MQSeries.
key
Keys are contained in digital certificates. There are two kinds of keys: Private and public. A
private key is your secret key for decrypting messages or signing messages. A public key is also
your key, but it can be used by a partner to encrypt messages that only you can decipher with
your private key.
listener
A listener is an agent that moves copies of payloads and event meta-data from any point in the
pipeline of messages traded among partners to an aXML Agent. A listener can be a database
trigger, script, daemon or process.
listeners
A listener is an agent that moves copies of payloads and event meta-data from any point in the
pipeline of messages traded among partners to an aXML Agent. A listener can be a database
trigger, script, daemon or process.
MAT
message attributes template
message
The cargo or payload the trading engine handles. A message can be a business document or a
receipt that you or a partner send to acknowledge receiving a document.
message protocol
A standard or convention for handling the exchange of e-commerce business messages over
the Internet, and sometimes between back-end systems and the trading engine. A message
protocol supports one or more transports. Supported message protocols include AS1, AS2,
AS3, ebXML and RNIF.
Message Tracker
Message Tracker is a tool in the user interface for monitoring database records of traded
messages. You can search for and view payloads and receipts.
message validation
Rules stating whether a community accepts messages from partners that are encrypted or plain
text and signed or unsigned. In the case of EDI documents, a community also can specify
whether to accept duplicate messages.
meta-data
Labels describing documents or events.
MinimumExpirationTime
Minimum message expiration date. The earliest date the message can be purged. The expiration
date can be set to a date after this. Also see ExpirationTime.
MMDs
Meta-data documents (MMDs) are XML documents that point to documents on a file system and
contain information o r a back-end system uses for processing.
outbound
A message sent over the Internet to a partner. The trading engine picks up the message from
outbound integration and packages it before sending.
packaging
How an outbound message is prepared before it is sent to a partner. Packaging normally
involves signing, encrypting and MIME-wrapping the payload.
payload
The business document within a packaged message.
Pickup delivery
An object that specifies the method remote partners use to send messages to your local
community, and the method your local community endpoint uses to retrieve messages that
have been sent.
processing node
A Java virtual machine (JVM). A processing node performs the processing work of the trading
engine. You can have one or many processing nodes on a single or multiple computers (a
cluster), depending on license permissions.
receipt
A transport-level message that you or a partner send to acknowledge receiving a document.
Replace
A replace message contains one certificate that should match an existing certificate associated
with the sender. The recipient should start using the new certificate immediately and the
current matching certificate should be removed from service immediately. When Interchange
receives a replace message the matching certificate is removed from service by disassociating it
from the partner that sent the replace message. The matching certificate is not untrusted. The
reason for this is that OFTP users most likely use CA-issued certificates, and when Interchange
trusts a CA-issued certificate, it frequently trusts the root CA certificate. It could be dangerous
to untrust a root CA certificate, as this may affect other trading relationships.
Request
A request message contains one certificate that may match an existing certificate associated
with the sender. The recipient can accept or reject the certificate, but either way must respond
with one or more deliver messages containing its current certificates. This message can be used
for an initial certificate exchange. Interchange can send up to four deliver messages in response
to a received request message, containing the recipient community’s current default signing
certificate, default encryption certificate, default client authentication certificate and certificate
for the first enabled TLS OFTP2 server. Only one deliver message is sent for any certificates that
are duplicates of others.
resend
After waiting for the partner to send a receipt acknowledging receiving a message, the trading
engine sends the message again on the presumption the partner did not receive the earlier
message. This sometimes is confused with retry.
retry
A subsequent attempt to connect to the partner’s transport when the initial attempt to connect
and send the message failed. This sometimes is confused with resend.
TRADACOMS
TRAding DAta COMmunicationS. An EDI standard of the Article Numbering Association. Widely
used in the United Kingdom.
trading
The exchange of e-commerce messages over the Internet between trading partners.
trading engine
A generic term for Axway Interchange, Axway Activator, and interoperable third-party e-
commerce gateways.
transport
The protocol for moving messages between the trading engine and partners over the Internet
or a back-end system. Supported transports include, SMTP, HTTP, FTP, SFTP, JMS and file
system.
unpackaging
The action of unwrapping an inbound packaged message.
X12
An EDI protocol of the American National Standards Institute. It is the primary North American
standard for defining EDI transactions.