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
What's new in Interchange 5.12 28

Product enhancements 28
Documentation enhancements 33
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
Interchange 5.12 Administrator Guide 3

Reverse proxy 44
Run the UI over HTTPS 44
Configure HTTPS 45
Switch between HTTP and HTTPS 47
Data backup recommendations 47
Document custom configurations 48
Trade large messages 49
Disk space 49
Databases, firewalls and large messages 49
Considerations by transport 50
3 Network and server administration 52

System Management page 52
Open the System Management page 52
Tabs 52
Related task links 53
Add a trading engine node 54
View and manage nodes 54
Node status 54
Add a trading engine node 55
Start the trading engine node 55
Stop the trading engine node 55
Pause/restart pickup message consumption 55
Configure UI connection 56
Configure HTTPS 57
Switch between HTTP and HTTPS 59
Configure server IP binding 59
Configure global transport settings 60
Configure the global external SMTP server 60
Generate cluster thread dumps 61
Manage the system throttle 62
About the system throttle 62
System throttle management 63
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

Large-scale and global enterprises 74
Staging for upgrades 75
Compare peer network and trading network objects 76
Configure a peer network 77
Peer network settings 78
Tabs and fields 79
Peer rules 80
Open the Peer partner rules page 80
Tabs and fields 81
Peer network cloning restrictions 85
Manually clone an application delivery 86
Start the wizard 86
Wizard page descriptions 86
Manually clone an application pickup 87
Start the wizard 87
Manually clone a partner 87
Start the wizard 87
Manually clone a trading pickup 88
Manually clone CPAs 89
Start the wizard 89
Manage duplicate messages in peer network 89
Have the back-end perform duplicate checking 90
Use a smart router to direct inbound messages 90
Log peer network debug events 90
Track peer messages 91
Peer Tracker controls 91
Peer Tracker versus Message Tracker 92
5 Tools and options 93

Trading engine governance script 93
Tools in bin directory 93
Database configuration tool 95
Document generator 97
Tools in tools directory 101
Check the collaboration and action trees 107
6 User interface 110

Open the user interface 110
Before logging on the first time 110
Logon procedure 110
The toolbar 111

Navigation aids for the Interchange user interface 112
7 Interchange user administration 114

Admin user 114
Manage users 115
Add a user 115
Modify a user 115
Delete a user 115
Tips to manage users 115
Change password 116
Manage roles 116
View available roles 117
Add a role 117
Modify a role 118
Delete a role 118
Role permissions 118
Partner restrictions for roles 121
Manage multiple partner-restricted roles 122
Application restrictions for roles 123
Community restrictions for roles 125
Advice for PassPort users 126
Date and time preferences 126
Global user settings 127
Session management tab 127
User security tab 127
Unlock a blocked user 128
Manage password policies of transport users 129
Add, change transport user password policy 129
Transport users password policy settings 130
Assign password policy to transport user 131
8 Trading configuration 132

How configurations work 133
Communities 134
Work with communities 136
Add a community 136
Modify a community 138
Use the community search tool 141
Checklist for community configuration 141
Partners 142
Work with partners 143
Add a partner 143
Community trading partners 147
Add a partner to a community 148

Partner data form 151
Modify a partner 156
Delete a partner 158
Group partners by categories 158
Use the partner search tool 159
Application pickups 160
When to use an application pickup 160
Work with application pickups 161
Add an application pickup 161
Application deliveries 162
When to use an application delivery 162
Work with application deliveries 162
Add an application delivery 162
Application pickup and application delivery fields 163
From address and To address wizard fields 164
FTP (external) transport configuration 166
FTP (embedded) transport configuration 169
SFTP (external) transport configuration 176
SFTP (embedded) transport configuration 180
File system transport configuration 189
JMS transport configuration 190
IBM MQSeries transport configuration 196
Add an MLLP application delivery 198
Add an MLLP application pickup 199
Web Services API pickup and delivery configuration 200
Pluggable server 202
Modify an application pickup or delivery 202
Fields for modifying application pickups and application deliveries 203
Common fields and tabs 203
Transport-specific tabs 203
General fields 203
Proxy tab 204
From address and To address tabs 204
Message attributes tab 206
EDI splitter tab 207
Inline processing tab 208
Schedule tab 208
Modify an FTP (embedded) pickup or delivery 209
Modify an FTP (external) pickup or delivery 213
Modify an SFTP (embedded) pickup or delivery 223
Modify an SFTP (external) pickup 226
Modify a file system pickup or delivery 232
Modify a JMS pickup or delivery 236
Modify an MQSeries pickup or delivery 240

Modify a Web Services API server application pickup or delivery 245
Modify an MLLP application delivery 249
Modify an MLLP application pickup 252
File renaming patterns 253
Community trading pickups and partner deliveries 256
Work with trading pickups and deliveries 261
Add a trading pickup 261
Add a partner trading delivery 262
Trading pickup and trading delivery fields 263
View certificates 302
Add certificate 303
Remove certificate 303
View certificates 303
Add certificate 304
Remove certificate 304
Modify a trading pickup 326
Modify a partner trading delivery 327
Fields for modifying community pickups and partner deliveries 328
Routing IDs 408
Work with routing IDs 409
Add a routing ID 409
Modify a routing ID 410
Message metadata and attributes 412
Attributes 412
Metadata uses 413
Metadata definitions 414
Metadata for record file management 418
Add a community attribute 421
Add a partner attribute 422
Add or delete message attributes 423
Message attributes templates 424
Export and import profiles 426
Export a community as a partner profile 427
Export a partner profile 428
Import a partner profile 428
Automatic profile imports 429
Create profiles outside the application 430
9 Embedded transport servers 431

Concepts 431
Pages and fields 431
Types of embedded servers 432
Global and community-specific servers 432
FTP and SFTP servers 432

ODETTE FTP servers 433
MLLP servers 433
PeSIT servers 433
Servers for the user interface 434
X.400servers 434
Usage summary of embedded servers 434
Manage embedded servers 435
Types of embedded server pages 436
UI navigation for embedded servers 437
Global embedded HTTP server 437
Lockout settings for cXML (embedded HTTP) users 439
Set lockout rules 440
Modify a global embedded SMTP server 440
Settings tab 441
DMZ ports tab 441
Advanced tab 442
Set the system property to permit EDI processing 442
Global embedded Web Services API server 442
User interface embedded servers 443
HTTP (embedded) fields 444
FTP (embedded) fields 446
Lockout settings for FTP (embedded) server users 452
SFTP (embedded) server fields 453
Lockout settings for SFTP (embedded) users 458
SMTP (embedded) configuration 459
Modify the configuration 459
Set the system property to permit EDI processing 461
OFTP (embedded) fields 461
Settings tab (without TLS) 462
Settings tab (with TLS) 462
DMZ ports tab 462
Advanced tab 463
OFTP X.25 over ISDN (embedded) fields 463
Settings tab 464
Advanced tab 464
PeSIT (embedded) fields 465
Settings tab 465
DMZ ports tab 466
Advanced tab 466

HTTP (embedded) business cases 468
Case A 469
Case B 469
Case C 470
Case D 471
Case E 472
Case F 473
10 Secure Relay DMZ nodes 474

Can you use DMZ nodes? 474
Overview of Secure Relay nodes 474
Types of secure connections 476
Encryption and authentication keys 477
Load balancing 478
Security features 478
Add DMZ zones 478
Add a DMZ node 481
Prerequisites 481
Add a node 482
Export the node 483
Run node as Windows service 484
Enable port forwarding for an exchange 484
Steps for port forwarding 485
Port forwarding details 486
Configure load balancer or firewall 487
Configure load balancer 487
Update load balancer as needed 488
Configure outbound connection proxy 488
Open the outbound proxy page 488
Enable outbound proxy and exceptions 489
Manage IP address whitelists 490
How IP addresses are checked 491
Add, change IP address whitelist 492
Enable IP address checking 493
HTTP trading and Secure Relay 493
11 Work with protocols, formats, and standards 494

Exchanges with applications 494
Application exchanges managed by Interchange 494
Managing Interchange exchanges with applications 495
Exchanges with trading partners 495
Trading partner exchange types 495
Managing Interchange exchanges with trading partners 496
Registration wizard for partners 496

Additional information for working with protocols, formats and standards in Interchange 496
AS1 / AS2 partner self-registration 497
Wizard preparation 498
Using the partner wizard 499
AS4 499
Can you use AS4? 499
AS4 overview 500
AS4 messages 501
AS4 metadata 503
Message Partition Channels (MPC) 515
AS4 user authentication 518
Large message splitting and joining 521
Enable handling of empty SOAP Body messages 523
Configure a one-way client pull 524
AS4 use case: One-way push (MMD initiated) 527
AS4 use case: One-way pull (MMD initiated) 529
AS4 tasks 533
ebXML 545
Can you use ebXML? 545
ebXML overview 545
ebXML message lifecycle 546
ebXML message metadata 548
ebXML message metadata documents (MMDs) 552
Supported ebXML trading transports 558
Supported ebXML application transports 558
ebXML message compression 561
Set up a community for ebXML trading 561
Send ebXML via an intermediary 562
Extract KeyInfo element for a CPA 567
Manage CPAs 567
Tools for CPAs 570
STAR BODs with ebXML 574
HL7 payloads with ebXML 575
ebXML partner self-registration 576
ebXML troubleshooting 579
Email client partners 579
Procedures 580
Trade without certificates 580
Trade with certificates 582
Send from email partner 583
HTTP outbound proxy 584
HTTP security solutions 586
HTTP (embedded) server 586
External staged HTTP server 588

HTTP connection troubleshooting 589
MLLP 592
MLLP server configuration 592
MLLP client configuration 592
MLLP use cases 592
Use case 1: Asynchronous MLLP exchanges 592
Use case 2: Synchronous MLLP exchanges 594
Add or modify an MLLP application delivery 595
Add or modify an MLLP application pickup 599
Add or modify an MLLP trading delivery 602
Add or modify an MLLP trading pickup 605
MLLP (embedded) fields 608
OFTP 611
Concepts 611
Procedures 611
OFTP overview 612
TSL support for OFTP2 613
OFTP transport configuration 617
Use X.25 with OFTP 628
Use X.25 over ISDN 632
X.25 requirements 634
Configuration outline for X.25 634
X.25 troubleshooting 635
Add or edit an X.25/B-ISDN router 635
X.25/B-ISDN router fields 635
Modify an OFTP pickup or delivery 637
PeSIT 651
Using PeSIT with Axway Transfer CFT 651
PeSIT limitations and special usages 651
About your PeSIT license 652
PeSIT configuration overview 652
Pickups and deliveries for PeSIT 655
Manage PeSIT pickups and deliveries 659
Add or modify a PeSIT application delivery 659
Add or modify a PeSIT application pickup (embedded server) 667
Add or modify a PeSIT application pickup (polling client) 670
Add or modify a PeSIT partner delivery 675
Add or modify a PeSIT trading pickup (polling client) 684
Add or modify a PeSIT trading pickup ( embedded server) 689
PeSIT send and fetch using an MMD 691
PGP secure trading 693
Can you use PGP? 693
PGP certificates 693

Add a PGP pickup or delivery 693
Manage PGP certificates 695
PGP collaboration settings 699
RosettaNet 699
Can you use RosettaNet? 699
RosettaNet overview 699
RosettaNet configuration outline 700
Add DTD-based PIP 701
Add schema-based PIP 702
Configure pipdefinitions.xml file 702
RNIF metadata elements 707
Message metadata documents 710
Special handling of metadata 711
Trade CIDX messages 714
Web services 715
Web Services roles 715
Interchange Web Services support 715
Interchange Web Services provider mode 716
Interchange Web Services consumer mode 716
Web Services provider configuration overview 716
Web Services consumer configuration 718
Web Services collaboration settings 722
Web Services message protocol 726
Implement MTOM encoding 730
Lockout settings for Web Services (HTTP embedded) users 731
Troubleshoot Web Services configurations 732
WebSphere MQ configuration 733
Configuration in MQ Explorer 733
Configuration of the Interchange environment 733
WebSphere MQ multiple instances 736
Set up WebSphere MQ 736
Set up Interchange 736
How the multi-instance functions 737
X.400 737
Can you use X.400? 738
Operating system exception 738
Concepts 738
X.400 subsystem 739
Valid characters for O/R addresses 740
X.400 trading configuration 740
Modify an x400 pickup or delivery 744
X.400 (embedded) servers 751
MSP7 for an X.400 server 759

P7 client polling schedules 760
Remote MTA for an X.400 server 761
X.400 log events 763
X.400 glossary 763
12 Certificates and keys 767

Do you use PGP? 767
Concepts 767
PKI description 768
PKI options 768
The role of trust in PKI 769
Scalability 770
Certificate revocation 770
Dual-key pairs 770
Why use encryption and digital signatures 770
Interchange encryption method 771
Symmetric key lengths 771
Public-private (asymmetric) key algorithms 771
Public-private (asymmetric) key lengths 772
Support for dual keys 772
Encryption and signing summary 772
Outbound documents 772
Inbound documents 773
Ensure data integrity and trust 773
Signature verification 773
Certificate path validation 774
Certificate basics 774
SSL authentication 775
Distribute certificates to partners 776
Certificate exchange with Axway partners 776
Certificate exchange with other partners 776
Self-signed or CA certificates 777
When to get certificates 777
Manage expiring certificates 777
View expiration dates 778
Interchange checks 778
Expiring certificates 778
Certificate replacement and archiving 778
Trusted roots 779
Import root certificates 780
Auto import intermediate and root certificates 780
FIPS compliance 781
Manage certificates 782
Do you use PGP? 782

Concepts 782
Procedures 782
Certificates search results page 783
Certificates pages 786
Add a certificate 792
Set up certificates for a community 792
Generate self-signed certificates 793
Import Entrust certificate 794
Import RSA Keon certificate 796
Import key pair in certificate file 797
Import certificates for partners 798
Export a certificate to a file 799
Globally prohibit exporting private keys 801
Delete certificate 801
Manage certificate revocation lists (CRLs) 802
Analyze certificates for errors 809
Collect data about certificates 810
Replace certificates automatically 811
Do you use PGP? 811
Concepts 812
Procedure 812
Automatic replacements 812
Types of CEM messages 814
SCX details 816
Send a CEM or SCX request 818
Track CEM and SCX requests 820
13 Message Tracker 826

Message Tracker search controls 826
Message Tracker page 826
Custom search 827
Peer Network Tracker 828
Trading information 828
Date 831
Columns 832
Search with wildcard characters 833
Search results page 833
View details of search results 835
Message details tabbed pages 835
Search results attributes in pop-up windows 838
Icons on search results page 841
Message receipts 841

Delete, resend, reprocess options 842
Share saved searches 843
Manage default search settings 843
Default menu items 844
Query restrictions 845
Peer Network Tracker query restrictions 845
Collect message attributes 846
Configure payload view 846
Force a document type for XML 848
14 Data storage, backups, and purging 849

Message backup configuration 849
Backup configuration page field descriptions 850
States of backed-up files 851
Backup options and Message Tracker 851
Back up a community and its partners 853
Back up a community 854
Import a backed-up community and its partners 855
Back up a community as a partner 855
Community backup as partner procedure 856
After you back up a community as a partner 856
Back up a partner 857
Import a partner 858
Import a single partner profile 858
Import all partner profiles found in a directory on the server 859
After you import a partner profile 860
Back up and restore a custom configuration 860
Automatic profile importing 861
Configure automated Interchange purge 862
Purge Interchange manually 863
Parameters 863
Example 864
Event logging 864
Configure event purge 865
15 FTP client scripting interface 866

Concepts 866
Reference 866
Levels of scripting 866
Edit the command set document 867
FTP tester tool 868
Consumer options 868
Producer options 869
FTP scripts for Interchange application exchanges 871

Script comments 871
Variables 871
Script execution 873
Error Suppression 873
FTP commands 874
16 Test trading 885

Configure for test trading 886
Start the test 887
Troubleshoot email testing 888
Complete the testing 888
17 Extend and tune your flow configuration 889

Delivery settings 889
Add an application delivery setting 889
Manage application delivery settings 890
Message Simulator 890
Uniqueness in Interchange 891
Unique object names 892
Message handler 892
Set up message-processing actions 893
Define message attributes 895
Define message actions 897
Message re-routing 899
Configure record transformation in message handler 902
Configure error processing 904
About error processing 904
Configure error processing 904
Post-processing configuration 905
Post-processing message metadata 906
Add post-processing elements 906
Methods for writing scripts 907
Post-processing events 908
Post-processing points to consider 909
Collaboration settings 909
Search and display collaboration settings 910
Manage default collaboration settings 910
Default collaboration fields 911
Manage community-specific collaboration settings 931
Manage community-to-category collaboration settings 932
Community and category collaboration fields 933
Manage community-to-partner specific collaboration settings 934
Manage community-to-partner delivery specific collaboration settings 937
Inbound message validation rules 939

Configure message validation rules 940
Validation rules: Duplicate messages tab 940
Validation rules: Signing tab 941
Validation rules: Encryption tab 942
Validation rules: CSOS duplicate orders tab 942
Validation rules: Web Services tab 943
Validation rules: AS4 tab 945
Validation rules: cXML tab 946
Sequential message delivery 947
How Interchange manages sequential delivery 947
Supported protocols 947
Sequential delivery behavior 947
Previous message sequence saved as metadata 949
Empty message handling 949
Out of sequence behavior 950
Recovery on shut down 952
Manual resubmission and sequential delivery 953
Unique identities in metadata for sequenced messages 953
Sequential delivery limitations 954
Use generic MMDs 954
Outbound messages 955
Inbound messages 957
18 Staged HTTP 958

Overview of staged HTTP 958
Staged HTTP configuration outline 960
Staged HTTP files to deploy 960
Log on to servlet UI 960
Manage mailboxes 961
Add a mailbox 961
Partner connection to staged HTTP 962
Edit, delete, view mailboxes 963
Global settings 963
Staged HTTP UI fields 963
Message protocols for staged HTTP 964
AS2 964
ebXML 964
RosettaNet 1.1 and 2.0 964
Secure file 964
File forwarding to bypass polling 966
High availability staged HTTP 967
Deploy the web servlet 968
Deploy on WebLogic 969
Deploy on Apache Tomcat 969

Deploy on WebSphere 970
19 Secure file message protocol 971

Sender and receiver determination 971
Sender determination 972
Receiver determination 972
Outbound packaging 972
Minimal MIME headers 973
Frequently asked questions 973
Curl command 974
Packaging examples 975
Secure file signed encrypted request signed ack 975
Secure file no security 977
Secure file from curl 978
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

Activate large message handling 1002
Activate large message sending for WebTrader partners 1003
UI behavior for WebTrader users 1003
File chunking 1004
Reset standard upload limit 1005
Monitor WebTrader exchanges 1005
WebTrader end user browser issues 1005
Manage unlimited strength JCE policy download issues 1006
Analyze the issue 1006
Correct the issue 1006
Confirm the resolution 1007
21 Axway CSOS 1008

Can you use CSOS? 1008
Standards certification 1008
User validation with PassPort 1008
Concepts 1008
Procedures 1009
Overview of CSOS functionality 1009
Security 1009
CSOS in Interchange 1010
CSOS configuration for sending 1011
CSOS configuration for receiving 1012
About CSOS roles 1013
CSOS WebTrader 1014
Use the CSOS applet on your web page 1015
Sponsor requirements 1016
WebTrader partner requirements 1017
Approve CSOS documents in WebTrader 1018
Turning on HTTP chunking 1020
Import CSOS signing certificate 1021
CSOS certificate revocation lists 1021
Identify CSOS purchase orders 1022
Order identification tab 1022
Order sources tab 1024
Related documents tab 1025
CSOS duplicate orders tab 1025
Link EDI 855 PO Acknowledgement to 850 PO 1026
Sign pending orders 1028
Configure PKCS#7-encrypted XML trading 1030
22 eSubmissions 1032
Can you use eSubmissions? 1032

Concepts 1032
Procedures 1032
Overview of eSubmissions 1032
Configure eSubmissions 1033
Getting started with eSubmissions 1033
Add an application pickup 1034
Add partner-specific collaboration settings 1037
Complete the FDA partner 1038
Import root certificate for SSL 1039
Send messages to the FDA 1039
FDA WebTrader end user browser issues 1040
Analyze the issue 1041
Correct the issue 1041
Confirm the resolution 1041
23 Interoperability with other Axway products 1042

Integrate with Axway Sentinel 1042
Open the Integrate the trading engine with Sentinel page 1042
Organization of the page 1043
Sentinel tab 1043
Filters tab 1044
Custom objects tab 1044
Related tasks list 1045
About Sentinel filters 1045
Add or modify Sentinel filters 1046
Filter expressions 1048
Integrate with Axway Integrator 1048
Message picked up from Integrator 1050
Message sent to Integrator 1051
Integrate with Axway Gateway 1051
Axway Gateway configuration 1052
Interchange configuration 1053
Integrate with Axway PassPort 1055
Integration overview 1055
Functional limitations for PassPort AM 1055
Database and installation requirements 1055
Verify PassPort host name 1056
About PassPort AM component instances 1056
Steps after installation 1057
24 Track activities and events 1060

Sentinel 1061
About Sentinel 1061

How Sentinel works 1061
Interchange Tracked Objects for Sentinel 1062
HeartBeat Tracked Object 1062
XFBTransfer Tracked Object 1065
XFBLOG Tracked Object 1083
Activity tracking and logs 1085
User interface home page 1085
Monitor file system health 1085
Message Tracker 1086
Alert activity report 1087
External monitoring of server status 1087
Create audit files of UI object changes 1089
Log file tracking 1092
Real-time viewing of log files 1094
Set up tail as a Windows option 1095
Troubleshooting with the log4j file 1095
Send log files to technical support 1100
System events 1102
Event levels 1102
The events.xml file 1102
The alerts.xml file 1114
Event tables 1119
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

Preface

The Interchange Administrator Guide provides information necessary for configuring and
administering Axway Interchange 5.12.
Who should read this guide

This guide is intended for administrators and advanced users who are responsible for the
configuration of Interchange for:
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.

Preface
About this guide

This guide describes how to configure and manage Interchange from the user interface.
What's new in Interchange 5.12 — Describes the new features and functional improvements in
this release of Interchange. See What's new in Interchange 5.12 on page 28.
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.
Network and server administration — Describes processing nodes and configuration

considerations. See Network and server administration on page 52.
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.
Tools and options — Describes the tools available for use with Interchange. See Tools and options

on page 93.
Interchange user interface — Describes the various component of the UI. See User interface on

page 110.
Interchange user administration — Describes how to manage users, passwords, roles, and

other configuration settings. See Interchange user administration on page 114.
Trading configuration — Learn about the trading configuration used by Interchange. See
Trading configuration on page 132.
Embedded transport servers — Describes the embedded servers provided for use with

Interchange. See Embedded transport servers on page 431.
Secure Relay DMZ nodes — Describes Secure Relay and DMZ nodes and zones. See Secure Relay

DMZ nodes on page 474.
Work with specific protocols and standards — Describes several of the different protocols and

standards that can be used with Interchange. See Work with protocols, formats, and standards on
page 494.
Certificates and keys — Describes how Interchange offers true security by providing

authentication, confidentiality, integrity and non-repudiation of documents. See Certificates and
keys on page 767.
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.
Backup and restore — Explains and lists the steps for data storage, backing up the data, and

purging data. See Data storage, backups, and purging on page 849.

Preface
Extend and tune a flow configuration — Describes how to use the features of the Interchange

user interface to fine tune your flow configurations. See Extend and tune your flow configuration
on page 889.
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.
Integration with Sentinel, Integrator, Gateway, and PassPort — Learn about the

interoperability between Interchange and these products. See Interoperability with other Axway
products on page 1042.
Activity and event tracking — Describes the activity reports and system events. See Track

activities and events on page 1060.
Troubleshooting — Describes the steps you can take if you are having trouble installing or using
Interchange. See Troubleshooting on page 1139.

Accessibility

At Axway, we strive to create accessible products and accessible documentation for all users.
This section describes the accessibility features of the Interchange product and its documentation.
Accessibility features of Interchange

Interchange provides the following accessibility features:
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

Accessibility
Screen reader support

Interchange supports JAWS. Before you can use JAWS with Interchange, you must first configure
your screen reader.
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.
Accessibility features of the

documentation
The product documentation includes the following accessibility features:
l Screen reader support on page 27
l Graphic readabilty on page 27
Screen reader support

l Text is provided as an alternative to displayed images throughout the documentation.
l PDFs are optimized for screen reader navigation.
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.

What's new in Interchange
5.12
Axway Interchange 5.12 introduces the following new features and functional improvements.
l Product enhancements on page 28
l Documentation enhancements on page 33
Product enhancements
The following product changes have been made:
What's new Description
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.

What's new in Interchange 5.12
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.

About Interchange
1
Interchange provides organizations with a secure, scalable gateway for B2B collaboration. The
unified framework helps establish relationships with trading partners, transact business over the
Internet, and integrate with back-end systems. The gateway provides flexibility in connecting to
partners and legacy systems using widely used protocols, transports, and integration methods.
Interchange enables you to organize and automate the flow of electronic documents between
participants located both inside and outside your enterprise network.
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.
Features and services

Interchange provides the following features and services in support of exchanges between
participants.
Support for transport protocols

In the Interchange user interface, administrative users configure Community and Partner objects to
specify the participants in message exchanges. Administrative users can then select the message
protocols and transport protocols that support these exchanges. Additionally, administrative users
can define application pickups and application deliveries to specify p atterns of interaction with the
various applications in the trading community.
Support for trading exchanges

Interchange supports the following trading exchange formats and protocols:
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)

1 About Interchange
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.)
Support for security protocols

Interchange supports the following security protocols:
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.

1 About Interchange
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.
Trading partner management

Interchange provides the following trading partner management services:
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.

1 About Interchange
Security services and operations

Interchange provides the following security-related features:
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.

Planning considerations
2
The practices described in this section are recommended to make production operations,
upgrading, and disaster recovery easier.
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.

2 Planning considerations
Firewalls and proxy servers

Many organizations have firewalls to prevent unauthorized access to their computer networks. A
firewall is a server placed outside of a network. The firewall intercepts all inbound connections from
the Internet, allowing only authorized users to connect to a server on the organization’s network. In
addition, a firewall may limit the outbound connections you can make.
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.
Interchange in a firewall environment

The following figure depicts a standard architecture for deploying Interchange in an environment
where firewalls are present. To maintain document and back-end security throughout the entire
process, we recommend placing the transport servers in a demilitarized zone (DMZ) and Interchange
in the data layer. A DMZ is the area between an organization’s trusted internal network and an
untrusted, external area such as the Internet.
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.

Editing URLs to allow for firewalls

If you use the embedded HTTP or HTTPS inbound transport in your community, you may have to
make sure your partners have the right URL. This is because the URL Interchange uses may not be
the one your partners need to send documents to you through your company’s firewall or load
balancer or both.
When you configure the embedded HTTP or HTTPS inbound transport, the default local URL is in
the following format:
http://<cluster machines>:4080/exchange/<routing ID>
https://<cluster machines>:4080/exchange/<routing ID>
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:
http://<fully qualified domain name or IP

address>:4080/exchange/<routing ID>
https://<fully qualified domain name or IP

address>:4080/exchange/<routing ID>
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.
Getting a partner’s external connection

details
If you must send documents via HTTP or FTP, contact your partner to determine the correct external
host, port and path (if applicable) for connecting to the partner’s server. If your partner uses
Interchange 5 or later, the partner may already have provided the correct public URL in the profile
the partner sent you to import as a partner on Interchange.
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.
User interface with proxy servers

The following topics are for system administrators who must deploy Interchange in a network
environment where end-user browsers make HTTP connections through proxy servers.
l Deployment in proxy environment on page 42
l Forward proxy on page 43
l Reverse proxy on page 44
Deployment in proxy environment

Interchange has a web-based user interface served by a built-in servlet container. When the server is
running, it listens for HTTP connections on port 6080.

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.
Run the UI over HTTPS

The default way for browsers to connect to the application server's user interface is via HTTP.
Typically, the URL a browser uses to connect is http://<host>:6080/ui, where <host> is the
name or IP address of the computer running the server. Optionally, you can have browsers connect
instead via HTTPS (HTTP over SSL). You can also allow connections via HTTP and HTTPS at the
same time. The following sections explain how to configure this.

Configure HTTPS
Use this procedure to configure the server so that browsers can log on to the user interface via
HTTPS.
1. Click System management on the toolbar in the user interface to open the System

management page.
2. Click Configure UI connection to open the Configure UI connection page.
If you are opening the page for the first time, the connections via HTTP option is already
configured by default. You can leave the page as-is or add a 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.
Although port 6443 is suggested, you can change the number as your situation requires.
4. 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 more
information about port forwarding.
This option is available only if your software license supports DMZ nodes functionality.
5. Optionally, select the checkbox for overriding cipher suites. The following describes this
feature.
Override SSL and TLS cipher suites

Select this checkbox to specify, using the Add and Remove buttons, the specific cipher suites
supported for the embedded server. If not 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
listed.
A cipher suite is a collection of security algorithms used to make connections via Secure
Sockets Layer (SSL) or Transport Layer Security (TLS). For example, an SSL or TLS protocol
requires signing messages using a message digest algorithm. However, 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 checkbox 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 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.
11. If you are configuring HTTPS and have selected Require client authentication, select the

Trusted roots certificate 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 only must 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, 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.

Switch between HTTP and HTTPS

Once connections via HTTPS have been configured, you can return to the UI configuration page
and select to allow browser connections via HTTP or HTTPS or both.
If you change the configuration, click Save. You also must do one of the following:
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.
Data backup recommendations

The following lists recommended practices for backing up application files and external databases.
These guidelines cover regular operation of Interchange and before upgrading to a new version or
service pack.
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.
Document custom configurations

Managing Interchange typically involves making custom changes to fit your processing needs. This
can mean editing system files or adding your own scripts and Java classes for purposes such as post-
processing, in-line processing, parsing, pluggable transports or other custom changes.
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.
Trade large messages

Although Interchange has no inherent limitations on the size of the messages it can process, a
number of factors – singly or in combination – can affect the capacity for handling large
documents.
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.
Databases, firewalls and large messages

Since the contents of messages are stored on the file system and not in the database, there is no
need to allow additional database space to handle large messages. However, if you are trading a
large volume of messages, this can be a consideration because a fixed amount of storage is required
in the database for each message.

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.
Restarts (FTP and HTTP only)

If you know that your partner’s server supports restarts, you may want to enable the Attempt
restarts option for the associated delivery exchanges. This enables the transfer to continue where it
was interrupted, rather than starting over from the beginning. In the case of FTP you also can
enable restarts for pickup exchanges.
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.
AS2 response time-out

Beginning with version 5.4.2, Interchange automatically adjusts the response time-out for
synchronous receipts on both the client and server side to an appropriate value based on the size of
the message.
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.
Firewall idle time-out

If you expect to receive large messages, adjust your firewall idle time-out accordingly.
For example, if your partners send large AS2 messages that request synchronous receipts (not
recommended), you must set your idle time-out to be longer than it takes Interchange to unpack
the largest message and return the response.
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.
FTP versus HTTP

There is a general belief that FTP is better than HTTP for large messages. If asynchronous receipts
are requested and firewall idle time-outs are set appropriately, there is no reason to prefer FTP over
HTTP. This is the case particularly when both parties are using Interchange or Activator, which
support restarts over HTTP as well as FTP.

Network and server
administration 3
The following topics provide information about the administration of the Interchange network and
server(s):
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
System Management page

Use the System Management page to perform system-related management tasks. In particular, you
can view and manage the status of Interchange system operating nodes, DMZs and X.25/B-ISDN
routers from this page.
You can also perform a variety of system management tasks to develop the health, security, and
connectivity of your production environment.
Open the System Management page

To open the System Management page, click System management on the toolbar.
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

3 Network and server administration
l DMZ zones tab
l X.25/B-ISBN routers tab
Cluster nodes tab

Users with Interchange administrative rights can use the Cluster nodes tab of the System
Management page to view and manage cluster nodes.
The following topics provide information and procedures for working in the Cluster nodes tab:
l View and manage nodes on page 54
DMZ nodes tab

l Add a DMZ node on page 481
X.25/B-ISBN routers tab

The following topics provide information and procedures for working in the X.25/B-ISBN routers
tab:
l Configuration outline for X.25 on page 634
l Add or edit an X.25/B-ISDN router on page 635
Related task links

The following topics describe the pages you can access from the System Management page
Related Tasks links:
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
Add a trading engine node

After you log on to the user interface for the first time, you must add a trading engine (TE) node. A
node is an instance of a Java virtual machine. Your license might allow you to run many TE nodes.
TE nodes perform the work of the application. Having multiple TE nodes is a way of managing
processing workloads in a computer cluster.
1. From the menu bar, select System management.

The System management page displays the server on which Interchange was recently installed.
Initially, only a control node is displayed for the server in the "System nodes" list.
2. On the System management page, on the Cluster nodes tab, click Add a trading engine
node in the task list at the bottom of the page.
You can only add one TE node at a time. If you want to add another TE node, repeat this
procedure, up to the limit specified in the license.xml file.
3. Select the computer to add the TE node. As a new user, you probably want to select the
computer where Interchange was recently installed. However, if a computer cluster has been set
up, you can select another computer provided Interchange has been started on that computer.
4. Select Add to add the TE node.
The System management page displays the trading engine node you added for the selected
server. The status is not running.
5. Click Start to the right of the trading engine node name to start the node. When the TE node
starts, the status changes to running.
6. With a running trading engine node in place, you can configure the application and users.
View and manage nodes

After you add and start Interchange nodes you can view information about the nodes on the System
management page. This same information is also visible on the UI home page.
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
Add a trading engine node

1. From the menu bar select System management > System management.
2. On the System management page, click Add a Trading engine node.
3. On the Add a node page, make sure the Trading engine node type is selected and the correct
Host machine is selected.
4. Click Add.
Interchange adds a trading engine node to the lists of nodes on this machine.
Start the trading engine node

To start a trading engine node, either
l Click the Start all nodes command, located below the lists of trading engines.

l Click the Start button located on a trading engine node entry.
Stop the trading engine node

You stop one or more trading engine nodes using a single command.
To stop one or more trading engine nodes, do one of the following:
l Click the Stop all nodes command, located below the lists of trading engines.
l Click the Stop button located on a trading engine node entry.
When you execute either of these actions:
l The trading engine stops.
l The new status of the engine is displayed in the node status column.
Pause/restart pickup message consumption

Users with the right to manage nodes can pause (or "throttle") the consumption of messages on the
Interchange system from the System management page. This is useful, for example, when it is
necessary to flush all current messages from the system.
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.

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:
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.
Switch between HTTP and HTTPS

Once connections via HTTPS have been configured, you can return to the UI configuration page
and select to allow browser connections via HTTP or HTTPS, or both.
If you change the configuration, click Save. You also must do one of the following:
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.
Configure server IP binding

Server IP binding is an advanced system task that is generally reserved for network managers. Do
not change values on this page without the assistance of the appropriate administrators.
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.
Configure global transport settings

Use the Configure global transport settings page to configure the lockout b ehavior of the following
Interchange embedded server users:
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
Configure the global external SMTP server

When you have started the Interchange server and logged on to the user interface for the first time,
one of the first things you should do is configure an external SMTP server. The system uses this
SMTP server by default to send mail, unless its use is overridden in certain cases.
1. Click System management on the top toolbar to open the System management page.

2. Click Configure the global external SMTP server to set up the server.
Consult with your network or email administrator for the information needed to complete the
configuration fields. Typically, only the "Server name" and "Port" fields need to be populated.
The "User name" and "Password" fields are available, but are rarely used.
3. Click Test… to test the connection to the SMTP server.
4. If the connection test is successful, click Save changes....

Generate cluster thread dumps

Click the Generate cluster thread dumps link on the System management page to g enerate a
file of system statistics to use for troubleshooting. Technical Support may ask you to generate and
send one of these files while investigating a problem for you. These files do not contain user-
consumable information.
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

Manage the system throttle
About the system throttle

The Interchange system throttle prevents JVM node hard-crashes due to overload. The system
throttle does not prevent processing, but rather limits the consumption of new work. The system
throttle operates automatically. Throttle behavior is normally applied separately for each node of the
cluster. You can also engage the throttle manually on all nodes of the cluster enable the system to
finish processing all active messages. The occasional automatic engagement of a system throttle is
good for Interchange, and is a normal operating experience. When the system throttle engages, it
does not mean that the JVM is not working at all, rather, it means that the JVM is working on tasks
already in queue, until sufficient headroom is regained to accept new tasks.
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):
WARN [SystemThrottle] (SystemThrottle.run:213) - Engaging the

SystemThrottle, TaskScheduler load is too large (limit = 150, current =
158)
62 Administrator Guide Interchange 5.12

Manage the system throttle
Message Tracker dependency

When system throttling is engaged, Message Tracker resend and reprocess attempts will fail. Resend
and reprocess attempts will eventually generate "max attempt exceeded" errors.
System throttle management

Note System throttle settings should be changed only as part of a comprehensive tuning effort,
best conducted with the help of Axway Professional Services.
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 tuning.properties file

You manage the general system throttle behavior from the tuning.properties file, located in
<install_directory>/conf.
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
Force throttling on startup

In some cases, you may want to force system throttling on startup. This is useful, for example, if you
want to empty the system of messages waiting to be processed.
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.
Modify the Task Scheduler load limit

By default, when Interchange Task Scheduler load exceeds 150, the system throttle is engaged. You
can modify this value. While there is no real limit to this value, there are practical limits due to
environmental factors (physical memory size, server hardware, network speed, etc.).
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.
systemThrottle.maximumTaskQueueSize
3. Set the value of the property to the desired value, for example:
systemThrottle.maximumTaskQueueSize=175
4. Save the file.
When the system restarts, it will engage throttling at the new load limit threshold.

Peer network
4
The peer network is a powerful tool for distributing trading capability, enabling disaster recovery,
and providing a staging platform for growing communities or application upgrades. The peer
network is a management layer on top of the usual e-commerce trading relationships between
parties, represented in Interchange by communities and partners.
Can you use peer network?

You can use the peer network if your software license enables this functionality.
This icon on the user interface toolbar indicates that your user license supports the features:
Additionally, to check all license-enabled features, you can select Help > License information on

the toolbar in the user interface.
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

4 Peer network
Peer network overview

The Interchange peer network provides a means of connecting multiple instances of Interchange
managed by your company or enterprise. An Interchange instance can range from a one trading
engine running on a single processing node, to many trading engines running on multiple clustered
machines with many nodes. Each Interchange instance has its own database.
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.)
Protocols for peer communication
Default protocol for peer exchanges

When you set up a peer network, as described in Configure a peer network on page 77, the AS2
protocol is automatically installed as your peer network communication protocol. Axway
recommends the use of the default AS2 protocol for peer exchanges, because of its ease of
installation and setup.
Alternative protocols for peer exchanges

Interchange additionally supports the use of other protocols for peer exchanges.
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.
Trading protocols supported for peer

cloning
When you set up a peer network, you can automatically or manually clone trading and application
pickups and deliveries that support any of the following protocols:
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)
Cloneable objects and their dependent

objects
You set up peer networking in order to share object configurations between networks. This topic
lists the dependent (or child) objects and attributes that are shared when you clone each of the
principal cloneable objects in Interchange.
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)

4 Peer network
Trading protocol limitations

The following protocols have not yet been validated for cloning in the peer network:
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.

4 Peer network
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.

Peer network business use cases
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.

The peer network can be used for:
l Disaster recovery on page 72
l Staging environment on page 72
l Large-scale and global enterprises on page 74
l Staging for upgrades on page 75
The peer network business use cases describe how trading partner profiles are distributed in each
case.

4 Peer network
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:

4 Peer network
The following figure shows the relationship in a peer network with multiple staging peers and
multiple production peers:
Large-scale and global enterprises

There are constraints imposed by the amount of data that can flow through shared physical
resources such as the database, network, and file system. At some point, an Interchange cluster
cannot be scaled further by adding more processing nodes. A peer network has the potential for
almost unlimited scaling because each peer is connected to a separate network, database, and file
system.
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.

Staging for upgrades

Before upgrading to a higher version of Interchange, you can first upgrade one peer cluster and
conduct tests to make sure the upgraded software performs to expectations. Then you can install
the upgrade for the other peer clusters.
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.

4 Peer network
Compare peer network and trading

network objects
Although the peer network is separate from your e-commerce trading community, peer network
relationships are similar. Peers use community and partner objects, transports and certificates.
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.

Configure a peer network
Configure a peer network

The procedure in this topic shows the basic steps for setting up a peer network. You must apply
these steps to each instance or cluster of Interchange that you want to belong to the peer network.
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.

4 Peer network
9. Optionally, on one Interchange instance, click Configure peer network on the peer network

page and change the ping configuration. Any changes you make affect ping behaviors for all
peers. See Peer network settings on page 78.
10. You may need to manually perform one or more of following tasks to ensure consistency across
the network.
l Inbound message validation – All peer communities should use the same settings for
inbound message validation across the peer network. This becomes a maintenance issue if
peer communities use other than the default settings. Note that for a peer community, the
setting for duplicate EDI messages is not applicable.
l Outbound collaboration settings – All peer communities should use the same settings
for outbound collaboration settings across the peer network. This becomes a maintenance
issue if peer communities use other than the default settings. If you configure peer partner
settings, these must be replicated manually across the peer network. Trading partners that
are sent as peer messages are packaged just like any outbound trading message.
l Configuration files – Configuration of Interchange can require editing various system
files. You may want to make sure that a change to a configuration file for one peer instance
of Interchange is reflected in the same file for another peer instance. You need to know
which system files have been changed and then determine whether to duplicate the
changes across the peer network.
For instance, you may want one peer instance to send email notifications to different
recipients than another peer instance. In that case, the alerts.xml file should not be the
same across all instances. Conversely, you may want custom settings in the
log4j.properties file to be the same for all peer communities so all peer instances
generate logs at the same event levels.
l Post-processing scripts – The names of post-processing scripts configured in trading
communities and partners are replicated across the peer network, but not the script files
themselves. If you are using post-processing scripts, you must make sure the script files are
available on each peer. If you update a script, you also must update it on each peer.
11. For each Interchange instance, go to the peer network page where all peer partners are listed.
Click Rules next to each partner name and set the rules for distributing trading partner profile
updates within the peer network. See Peer rules on page 80 and Peer network business use
cases on page 71.
Peer network settings

Use the Peer network settings page to:
l Turn the peer network on and off for your peer community
l Set how the peer community sends and receives ping messages
l Determine whether inbound peer messages are written to a back-end file

Peer network settings
To open the Peer network settings page, click Configure peer network at the bottom of the Peer

network page.
Tabs and fields

The following sections describe the tabs and fields of the Peer network settings page.
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.

4 Peer network
Ping interval
The time in minutes between ping broadcasts.
Hours to retain ping history
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 inbound ping messages
Write only inbound ping messages to a back-end file system folder.
Write other inbound peer messages
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.
Open the Peer partner rules page

Before you can open a Peer partner rules page, you must have at least one peer partner. See
Configure a peer network on page 77.
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.

Peer rules
Tabs and fields
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.
Auto-clone added, changed and deleted trading partners to the 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.
Important: For auto-clone to work, the option Allow this partner to be cloned to

peers must be selected in the trading partner object definition. The "allow cloning" option
can be set for the trading partner in two places:
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.

4 Peer network
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.
Application deliveries tab

Accept application delivery additions, changes and deletions from the
peer partner
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.
Auto-clone added, changed and deleted application deliveries to the 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
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.
Application pickups tab

Accept application pickup additions, changes and deletions from the peer
partner
Enables the peer community to accept application pickups sent by this peer partner.
absolutely sure that the peer community does not accept application pickups from this
peer partner.

Peer rules
Auto-clone added, changed and deleted application pickup to the 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
trading community application pickups received from this peer partner to other peer
partners for whom auto-cloning is active.
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.
Trading pickup tab

Accept trading pickup additions, changes and deletions from the peer
partner
Enables the peer community to accept trading pickups sent by this peer partner.
absolutely sure that the peer community does not accept trading pickups from this peer
partner.
Auto-clone added, changed and deleted trading pickup to the 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.
For auto-clone to work, the option Allow this partner to be cloned to peers must be

selected in the trading partner object definition. The "allow cloning" option is located in
the add trading partner wizard and under Properties in the trading partner summary page.
Relay to the peer partner any trading pickup additions, changes and
trading community trading pickups received from this peer partner to other peer partners
for whom auto-cloning is active.

4 Peer network
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.
absolutely sure that the peer community does not accept CPAs from this peer partner.
Auto-clone added, changed and deleted CPAs to the 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.
For auto-clone to work, the option Allow this partner to be cloned to peers must be

selected in the trading partner object definition. The "allow cloning" option is located in
the add trading partner wizard and under Properties in the trading partner summary page.
If auto-cloning ebXML CPAs, make sure to select Allow this CPA to be auto-cloned to

peers when importing or managing a 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
CPAs received from this peer partner to other peer partners for whom auto-cloning is
active.
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.

Peer network cloning restrictions
Peer network cloning restrictions

The following information details the restrictions of the peer network cloning process.
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
Deleting objects when auto-cloning is turned off
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.
Generated SSL certificates
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.
Asynchronous AS2 message disposition notifications (MDNs)
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 pickup routing IDs
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.

4 Peer network
Importing a backed-up Interchange system configuration
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.
Manually clone an application delivery

Use the application delivery cloning wizard to send new and updated application deliveries from a
peer community to peer partners. The wizard is helpful when you have disabled auto-cloning or
when you want to send updated application deliveries to a peer partner who has been off line for a
time.
Start the wizard

To start the application delivery profile cloning wizard, select Peer network > Clone application
deliveries from main task bar. This link displays only if the peer network has been enabled.
Wizard page descriptions

Communities – Community configurations may include application delivery settings. These
settings determine which application delivery will handle the different messages that are consumed
by each community.
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.

Manually clone an application pickup
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.
Peers to receive cloned application deliveries — Use the second page of the wizard to select

the peer partners to receive the community application deliveries. When sending application
deliveries via the clone wizard, your peer partners accept them, overwriting any identical deliveries
already present, whether older or newer.
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.
Manually clone an application pickup

Use the application pickup cloning wizard to send new and updated application pickups from a peer
community to peer partners. The wizard is helpful when you have disabled auto-cloning or when
you want to send updated application pickups to a peer partner who has been off line for a time.
Start the wizard

To start the application pickup cloning wizard, select Peer network > Clone application
pickups from the main task bar. This link displays only if the peer network has been enabled.

Peers to receive cloned application pickups — Use the wizard page to select the peer partners
that will receive the cloned application pickups.
You cannot use the clone wizard to direct a peer partner to delete an application pickup. That is an
Manually clone a partner

Use the trading partner cloning wizard to send new and updated trading partner definitions from a
peer community to peer partners. The wizard is helpful when you have disabled auto-cloning or
when you want to send updated trading partner definitions to a peer partner who has been off line
for a time.
Start the wizard

To start the trading partner profile cloning wizard, click Clone trading partners on the Peer
network page. This link displays only if the peer network has been enabled.

4 Peer network

Trading partners to clone – Use the first page of the wizard to select the trading partners to
clone.
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.
Peers to receive cloned partners – Use the second page of the wizard to select the peer partners

to receive the trading partner profiles. When sending trading partners via the clone wizard, your
peer partners accept them, overwriting any identical trading partners already present, whether older
or newer.
You cannot use the clone wizard to direct a peer partner to delete a trading partner. That is an
Manually clone a trading pickup

To send a new or updated trading pickup from a peer community to one or more peer partners, you
work in the Change this pickup page of the pickup.
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.

Manually clone CPAs
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.
Manually clone CPAs

The CPA cloning wizard provides a way for a peer community to send new and updated CPAs to peer
partners. The wizard is helpful when auto-cloning is disabled or to send updated CPAs to a peer
partner who has been off line for a time.
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.
Start the wizard

To start the CPA cloning wizard, click Clone CPAs on the Peer network page. This link displays only
if the peer network has been enabled.

CPAs to clone — Use the first page of the wizard to select the CPAs to clone.
Peers to receive cloned CPAs — Use the second page of the wizard to select the peer partners to

receive the CPAs. When sending CPAs via the clone wizard, your peer partners accept them,
overwriting any identical CPAs already present, whether older or newer.
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.
Manage duplicate messages in peer

network
If you plan on using the peer network to link instances of Interchange that are actively trading, you
must implement a solution for detecting duplicate messages.
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.

4 Peer network
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.
Have the back-end perform duplicate

checking
This solution presumes the peer network has a common back-end system to which inbound
messages from all peers are sent. If the back-end system does not perform duplicate checking, a tool
would have to be developed for detecting duplicate messages based on parsing document content.
Use a smart router to direct inbound

messages
An intelligent router could be employed as an advanced load balancer. The router would ensure
duplicate messages are predictably routed to the same peer, making duplicate checking reliable.
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.
Log peer network debug events

As a troubleshooting aid, you can generate verbose debug-level events related to the peer network
by changing the value of the following line to debug in the log4j.properties file:
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.

Track peer messages
Track peer messages

Peer Network Message Tracker (or Peer Tracker) is an extension of Message Tracker. (See Message
Tracker on page 826.) It lets users of the peer network search for and view messages processed by
all peer partners. Peer Tracker monitors e-commerce and peer message traffic of your peer partners
just as Message Tracker monitors messages exchanged between your community and trading
partners. The prerequisite for using Peer Tracker is configuring a peer network.
When search results from a peer are displayed, dates and times reflect the time zone of the currently
logged on user.
Peer Tracker controls

The Peer Tracker add-on to Message Tracker operates like Message Tracker. Simple controls on the
custom search panel on the left side of the Message Tracker page engage Peer Tracker. With these
controls, you can search for and view details for any combination of messages processed by your
instance of Interchange and by peer network partners. When you execute a search on a peer
partner, the results display on a separate tab with the peer partner's name on the Message Tracker
page.
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.)
l Maximum peer records to display

If you select to search for messages of any peer partners, this is the highest number of results
that can be displayed. This maximum does not apply to search results for your community; that
is set by the value of the Maximum # of search results field.
l Local server
This is your instance of the trading engine. If you run the trading engine in a cluster of multiple
computers, it represents your cluster, too. If you select Local server but not any peers, Message
Tracker performs just as it would if you did not have a peer network.
l Peer-[name]
This is the list of the peer partners whose messages are searchable. When you select a peer
partner and perform a search, the results are displayed on a tab with the peer partner's name.
l Response timeout
The interval in seconds peer partners are allotted to return search results requested by your local
server. If results for a peer are not returned in the allowed time, a message saying the peer did
not respond displays on the Peer-[name] tab.
Aside from these, Peer Tracker uses the same controls as Message Tracker. See Message Tracker
search controls on page 826.

4 Peer network
Peer Tracker versus Message Tracker

Although Peer Tracker and Message Tracker are much alike, there are some differences. One
noticeable difference is that Peer Tracker responds more slowly than Message Tracker because the
trading engine must connect to a peer partner's database to retrieve search results and message
details.
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.
Feature Message Peer

Tracker Tracker
Delete, resend, reprocess message actions. yes yes
Attributes pop-up windows on search results pages yes no
Sorting of search results yes yes
Click table cell in search results to display filtering options yes yes
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.
Search by attributes on the message details page message attributes yes yes

tab.

Tools and options
5
The following topics describe tools available for checking configurations and troubleshooting.
Information also is provided on how to plan for upgrading and disaster recovery.
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
Trading engine governance script

A script is available for starting or stopping Interchange server or checking the server status. The
script is named Interchange.bat on Windows and Interchange on UNIX or Linux. The script is
located in the trading engine root directory.
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.
Tools in bin directory

The bin directory at <trading engine install directory>\bin contains a number of tools,
some of which can be useful in certain cases. The following table summarizes the tools and provides
links for more information about some you may have occasion to use.

5 Tools and options
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.

5 Tools and options
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.
Database configuration tool
About the database configuration tool

After you install Interchange, it is good practice to verify your database connectivity. To do this, you
can use the database configuration tool, dbConfig.
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.

5 Tools and options
Run dbConfig
Windows
To run dbConfig on Windows machines:
From the Start menu

1. Stop the server. Make a backup copy of the datastoreconfig.xml file in the application's
conf directory.
2. Start the tool: Select Start > Programs > Axway Software > Axway Interchange >
Interchange Server> DB Configuration.
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.
From the installation folder

conf directory.
2. Locate the tool: Go to <install directory>\bin and click dbConfig.cmd.
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.
From the command line

conf directory.
2. Use the cd command to go to <install directory>\bin.
3. Execute the command dbConfig.cmd -b2bx true
4. Test the connection and if necessary change the details.
5. Save.
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.

5 Tools and options
The tool can be run in a command line with the following parameters:
[-? | -help] [-d (sqlsrvr|ora|db2|derby|mysql)] [-p port] [-h

host] [-n dbname] [-u username] [-pd password]
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
Create EDI or XML test documents

Use this procedure to create EDI or XML test documents in Document Generator and put them in an
output directory.
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.

5 Tools and options
2. Click EDI or XML to open the EDI or XML Document Generator window. The two windows are

similar, but only the EDI window has Control ID and Input template fields.
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.

5 Tools and options
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.
Run from a command line

You can use Document Generator from a command line without the graphical user interface (GUI).
You do this by running a command with parameters for the test documents you want to create. The
command is docGen. Run the tool from the application’s bin 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.
Command line parameters

The following table shows the command line parameters for the Document Generator. You do not
have to use the parameters in the order listed.
Parameter Description Usage
-type Valid document types are EDI or XML. Required
-sender Routing ID of the sender. Required

5 Tools and options
Parameter Description Usage
-receiver Routing ID of the receiver. Required
-outpath The directory where the Document Generator writes the outbound Required

documents. This is typically the sender’s EDI-out or XML-out
directory.
-size Any value between 1 and 999999 KB to indicate the size of each Required

document you want to create.
-ndocs Any value between 1 and 999999 to indicate the number of Required

documents you want to create per unit of time. The Document
Generator creates all of these documents at once.
-docid The number to use as the control ID of the first EDI document to be Required

generated. for EDI
Do not use for XML documents because they do not have control IDs. N/A for
XML
-infile The path to the EDI document on your system that you want to use as Optional

the template for generating test documents. for EDI
You can use copies of your own EDI document as the test documents N/A for
rather than the test documents that Document Generator creates for XML
you. If you use your own EDI document as the template, Document
Generator copies it and inserts your specified sender, receiver and
control ID.
-interval Any value between 1 and 999999 to indicate the time in minutes the Optional

Document Generator waits to create the next document or set of
documents.
If you do not use a value, Document Generator creates the number of
documents specified by -ndocs once. If you use a value, Document
Generator creates the specified number of documents at the specified
interval until you stop the tool.
-maxuncon This is a fail-safe control to stop generating documents in the output Optional

sumed 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.
-h, -help or Displays a list of the parameters. (In Windows, see docgen.log in Optional

? logs directory for list.)

5 Tools and options
Command line format

The following are examples for running Document Generator from a command line. Be sure you run
the utility from Interchange bin directory.
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.
./docGen -type edi -sender company1 -receiver partner1 -docid 302

-outpath /home/axway/ci400/data/company1/ediout -size 3 -ndocs 7
-interval 5
If you run the docGen command without any parameters, the GUI opens.
To stop the generator:
1. Run ps -ef | grep java to find the process ID (PID).

2. Run kill -9 [PID], where PID is the number found in the previous step.
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.
Tools in tools directory

The tools directory at <install directory>\tools contains many tools. The following table
summarizes the tools and provides links for more information about some of them. Some of these
tools are easy to use, but others are not intended for use by end users or should be used only on the
advice of technical support.

5 Tools and options
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.
asxTool Packages, unpackages and dumps EDIINT messages. This
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.

5 Tools and options
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.

5 Tools and options
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.

5 Tools and options
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.

5 Tools and options
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.

5 Tools and options
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.
Check the collaboration and action trees

A command-line tool is provided to detect corrupted action or collaboration tree. The treeScan
tool is in the tools directory.
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.

5 Tools and options
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.

5 Tools and options
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.

User interface
6
The following topics provide information about the Interchange user interface:
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
Open the user interface
Before logging on the first time

Before logging on for the first time to the user interface, make sure:
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
Browser JRE plugin requirement for WebTrader, CSOS, and FDA

WebTrader/eSubmissions
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:

6 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.
Icon Name Description
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.

6 User interface
Icon Name Description
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.
Navigation aids for the Interchange user

interface
The Interchange user interface has graphics that help you manage c onfigurations for communities
and partners. When you place the cursor over an element, a red box illuminates the area. You can
click any element to go to the named area.
The following figure shows the community navigation graphic:
The following figure shows the partner navigation graphic:

6 User interface
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.

Interchange user
administration 7
Use the Users and roles menu of the Interchange user interface to add and manage user access.
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.
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.

7 Interchange user administration
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.
Tips to manage users

l Usernames and passwords are case sensitive.
l Selecting the request email notification checkbox makes the user eligible to receive alerts and
reports by email.
l Clearing the enable this user checkbox deactivates 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.
l When adding a user, remember to assign a role. A user without a role can log on, but can do
nothing else. Use the Roles tab to add or change a role for a user.

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.
View available roles

From the menu bar select Users and roles > Manage roles.
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 Approve CSOS orders – Allows outbound CSOS orders to be signed and verification of

inbound signed CSOS orders. This permission only applies for licenses with CSOS authorization
for Interchange.
l Access APIs – Allows users with this permission to view, create, modify and delete trading
engine resources via the Interchange REST APIs. For information about REST API user, see the
Interchange Developer Guide.

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.
o Manage global message search settings – Allows changing settings and values on the

Message Tracker global settings page.
o Restrict searching to selected communities – Allows limiting the role to specific
communities. Users with this role can only search for and view data related to the specified
communities. See Community restrictions for roles on page 125. For unrestricted access to
all communities, do not select this.
o Restrict searching to selected partners – Allows limiting the role to specific partners.
Users with this role can only search for and view data related to the specified partners. See
Partner restrictions for roles on page 121. For unrestricted access to all partners, do not
select this.
o Resubmit messages – Allows resubmitting messages in Message Tracker.
o Save, change and delete searches – Allows users to perform custom searches and to
save and delete their own searches.
o View payloads and backups – Allows viewing backed-up copies of traded 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.
o Manage the nodes – Allows adding and deleting processing nodes, and starting and

stopping nodes.
o Perform system level backup and restore operations – Allows system backup and
restore.
o View trading configuration – Allows viewing communities.
o Manage trading configuration – Enables adding and modifying communities. This
permission is also necessary to do peer network tasks.
Note: You must normally use the Manage partners configuration and Manage
trading configuration settings together for the desired result. Manage partners
configuration enables adding a partner, but a user needs Manage trading
configuration to assign a partner to a community. A user can delete a partner assigned
to a community only when associated with a role enabling both settings. Only Manage
partners configuration is needed to delete a partner not assigned to any community.
A user can change the community of a partner only when associated with a role enabling
both settings. This permission has the following child permissions, which apply only if
the parent permission is selected.
o Add, modify, export, and delete community and server certificates – Can
be selected only when Manage trading configuration also is selected. Allows the users
with this role to manage certificates owned by communities as well as server
certificates. This has the following child permission:

– Export private key from any certificate with a private key – Allows users

of the trading engine to export private encryption keys when exporting certificates to
files. See Export a certificate to a file on page 799 and Globally prohibit exporting
private keys on page 801.
o Restrict management to selected communities – Select this option if you want
to limit the Manage trading configuration permission to one or more
communities that you specify. Click the Restrict to selected communities
hyperlink to open the community selection page. See Community restrictions for
roles on page 125.
o Restrict viewing to selected communities – Select this option if you want to limit
the View trading configuration option to one or more communities that you specify.
Click the Restrict to selected communities hyperlink to open the community
selection page. See Community restrictions for roles on page 125.
o View partners configuration – Allows viewing partners.
o Manage partners configuration – Enables adding and changing partners. This
permission also is necessary to do peer network tasks.
o Add, modify, export, and delete partner certificates – Allows the role to
manage trading partner certificates.
o Restrict management to selected partners – Select this option if you want
to limit the Manage partners configuration permission to one or more
partners that you specify. Click the Restrict to selected communities
hyperlink to open the community selection page. See Partner restrictions for roles
on page 121.
o Restrict viewing to selected partners – Select this option if you want to limit the
View partners configuration permission to one or more partners communities that
you specify. Click the Restrict to selected communities hyperlink to open the
community selection page. See Partner restrictions for roles on page 121.
l View user activity – Allows viewing of user and roles area of the user interface. This
permission has the following child permission.
o Administrator – This is the single most powerful permission. A user assigned to a role with
this permission has unlimited permissions, regardless of other permissions selected. When
this permission alone is selected, users with this role can perform all tasks and navigate to all
areas in the user interface. Select this permission only for a role for administrators.
Partner restrictions for roles

When adding or changing a role, you can give users broad or narrow access to partners of your
Interchange communities. This is done by specifying partners on the Partner restrictions tab. You
can define by role the partner data users can search for and view in Message Tracker. For users with
administrator authority, you can limit the partners the administrators can change.
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.
Manage multiple partner-restricted roles

The system allows assigning multiple roles to a user. In the case of roles with partner restrictions,
limits are applied in an cumulative sense. For instance, as the system builds the list of allowed
partners, the roles can only add partners to the list, but not take them away. This way the roles can
be applied in any order. The examples in the following table show the effect of assigning multiple
roles with different partner restrictions.

Partner Role 1 restrictions Role 2 restrictions Result
Partner A allows does not allow access granted
Partner B does not allow allows access granted
Partner C does not allow does not allow access denied
Partner D allows allows access granted
Application restrictions for roles

When you add or change a role, you can specify the application pickup and delivery exchanges that
the users who are assigned the role can view and modify. To do this, you specify application
exchanges on the Application restrictions tab.
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
Delete an application Manage applications; limited based on view and
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
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
Add/remove keys for an SFTP user Manage applications. Not affected by Manage
Access password policy details View trading configuration. Not affected by
restrictions.
Community restrictions for roles

When you add or change a role, you can specify the communities that the users who are assigned
the role can search, view, and manage. To do this, you specify communities on the Community
restrictions tab.
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.
Advice for PassPort users

If you use Axway PassPort for identity and access management (IAM), be aware of the following
when using the PassPort user interface to manage permissions for users of Interchange. This applies
when the Interchange component security descriptor (CSD) file has been imported to PassPort. It
does not apply if PassPort uses an external system, such as an LDAP server, for IAM.
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.
Date and time preferences

Users can set preferences for the display of dates and times in the user interface.
To set preferences, select Users and roles > Change my user account. Or, if you are an
administrator, select Manage users and click a user name. On the user’s page, select the
Date/Time tab.

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.
Global user settings

Change global settings on the Users and roles menu opens a page that lets you configure user
interface session settings affecting all users.
Only users assigned to a role with the “manage users and roles” permission can view or change
global user settings.
This page has two tabs: Session management and User security. The following topics describe

the fields on each tab.
Session management tab

l Maximum session length (minutes) – The number of minutes a session can be idle before
the system logs off the user.
l Login retries – The number of times a user can try unsuccessfully to log on to the user
interface before the system locks out the user. This is a safeguard against possible efforts by
unauthorized users to access the system.
l Lockout length (minutes) – The interval in minutes that a lockout is in effect. When the

lockout expires, the user can try again to log on. If you want to unlock a user immediately see
Unlock a blocked user on page 128.
l Allow a user to have concurrent browser sessions – Selecting this allows all users to log
on multiple times to the user interface simultaneously. When unchecked, each user can have
only a single browser session. If you select this, make sure the maxUserSessions element in
the license.xml file in the system conf directory can support many concurrent user sessions.
l Allow browsers to remember user IDs – Select this to display a checkbox for Remember
my user ID on the log-on page. This gives users the option of having their browsers remember
their user IDs the next time they log on. Clear the checkbox on the global settings page if you do
not want browsers to remember user IDs. After disallowing browsers from remembering user IDs,
users may not notice the change until logging on for the second time following the change.
User security tab

Any changes to the password settings take effect the next time a user changes a password.
l Minimum user ID length – The minimum number of characters allowed for user IDs. A user
ID can be any combination of alphanumeric characters and is case sensitive. If you change the
minimum user ID length, the new minimum is enforced only for new users. IDs of users who pre-
date the change remain valid.

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 Elapsed days before disabling an inactive user – The number of days before an inactive
user’s account is disabled. A disabled user can be re-activated. If a value of 0 is used, a user
remains active forever, regardless how much time has elapsed since the user logged on.
l Force new users to reset their passwords upon initial logon – Selecting this compels all
new users to change their passwords after logging on the first time.
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 Passwords must have at least one number (0 to 9) – Forces users to include at least one
number in passwords.
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: `~!@#$%^&*
()-=[]{}\|;:",.<>?.
Unlock a blocked user

You can unlock a user who has been blocked from logging on to the user interface. A lockout
occurs after a user repeatedly fails to log on with an incorrect username or password. You can
immediately unlock a user without waiting for the lockout interval to elapse.
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”.

Manage password policies of transport

users
You can specify password policies for users of cXML, FTP, SFTP, and Web Services embedded
servers. This includes users who connect to servers that are used for both back-end application and
trading partner exchanges. You can assign a password policy when a user account is being set up or
changed.
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
Add, change transport user password policy

Use this procedure to add or change a password policy for users of FTP, SFTP and Web Services
embedded servers.
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.
Transport users password policy settings

Use the following fields to set password policies for users of FTP, SFTP and Web Services embedded
servers.
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 Passwords must have at least one number (0 to 9) – Forces users to include at least one

number in passwords.
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: `~!@#$%^&*()-=[]{}
\|;:",.<>?.
Assign password policy to transport user

Use one of the following methods to assign a password policy for FTP, SFTP and Web Services
users.
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.

Trading configuration
8
Setting up a trading relationship involves adding a community, which contains information about
an organization and how it wants to receive messages from partners. Completing the configuration
involves adding one or more partners to the community. A partner configuration contains
information about a partner and how to send messages to it. The user interface provides helpful
links and prompts for adding communities and partners.
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

8 Trading configuration
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
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
How configurations work

The trading engine organizes the information needed to exchange documents with partners in
community and partner configurations. The use of configurations makes it easy to set up and
maintain trading relationships. A community configuration defines how you receive documents
from partners. A partner configuration defines how you send documents to a partner. The user
interface guides you through most of the steps needed for setting up community and partner
configurations.
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.
Work with communities

l Add a community on page 136
l Modify a community on page 138
l Add a community attribute on page 421
l Add an application delivery on page 162
l Add an application pickup on page 161
l Add a trading pickup on page 261
Add a community
For a description of communities, see Communities on page 134.
Select an method for adding a community

There are several methods for adding a community. When you launch the Add Community
Wizard, you begin by selecting one of the following creation methods:
l Manually create a new community – If you choose this option, the system prompts you to

provide much of the required configuration information.

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.
Manually create a new community

Use the following steps in the Add a community wizard to create a community with a certificate.
1. From the Trading configuration menu, select Manage trading configuration.

2. Click Add a community.
3. Select an option for your community creation method:
4. Manually create a new community and click Next.
5. Complete the fields:
l Community name – Enter a name to identify this community in the user interface.
l Country code – Select a country for this community from the drop-down list.
l Full name – Enter an administrative contact name for this community.
l Phone number - Enter the complete phone number for the community contact.
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
Import a backed-up Interchange version 5

community profile and its partners in a compressed
file
Use this procedure to import a backed-up file containing a community profile and its associated
partner profiles.

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.
1. From the Trading configuration menu, select Manage trading configuration.

2. Click Add a community to open the Add a community wizard.
3. Select Import a backed-up Interchange version 5 community and its partners in a
compressed file and click Next.
l File name – Use the browse tool to select the backed-up community file.
l Password – Optionally enter the password for access to the backed-up file. Entering the
password is optional, but recommended. If you do not use a password, the community
private keys are not imported. However, the community profile and all associated partner
profiles are imported.
l Overwrite existing partners – This option is selected by default. Clear this option if you
do not want an imported partner profile to overwrite a profile already in the trading engine.
l Allow integration delivery 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.
5. Click Finish.
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.
After you create a community

The community creation wizard enables you to create a community with a basic set of configuration
characteristics. After you create a community, you can view, modify, delete, and extend the
community c onfiguration. See Modify a community on page 138.
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.
Additional community summary page features
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.
Related tasks list

The community summary page provides a task list with hyperlinks to the following commonly-
preformed tasks:
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
Use the community search tool

When you have a large number of communities to manage, it is useful to use the search tool on the
Communities page to find and display specific communities.
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.
Checklist for community configuration

The following are items to consider when configuring a community.
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.
Work with partners

l Add a partner on page 143
l Modify a partner on page 156
l Group partners by categories on page 158
l Use the partner search tool on page 159
l Delete a partner on page 158
Add a partner
For a description of partners, see Partners on page 142.
Select a method for adding a partner

There are several methods for adding a partner. When you launch the Add Partner Wizard, you
select one of these methods from the first screen that is displayed:
l Manually create a new partner – If you choose this option, the system prompts you to

provide much of the required configuration information. The system adds additional
configuration information by default. You can modify this information after you complete the
creation steps.
See Manually create a new partner on page 144.
l Import a partner profile from a file – Use this option is to import a partner definition that
was previously exported as a partner profile. Use this method to import one partner definition at
a time.
See Import a partner profile from a file on page 145.

l Import all partner profiles found in a directory on the server – Use this method to

import all partner definition files that reside in a specified directory. You typically use this
method to import multiple partner definitions that were exported from an earlier version of the
trading engine.
See Import all partner profiles found in a directory on the server on page 146.
Manually create a new partner
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.
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.
Import a partner profile from a file

Use this procedure to import an XML file containing a partner profile. If your trading partners use
Interchange software they can export partner definitions (partner profiles) and provide them to you.
Upon receiving a partner profile from a trading partner, make sure the file is accessible on your file
system.
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.
4. Next to the File name box, click Browse and locate the .xml partner file.

5. Under Choose the import mode, select how the system should handle the partner if a current
partner exists with the same name.
6. Select the appropriate options:
7. Click Finish.
The partner is imported. The new partner is added to the list of available partners on the
Partners page.

Import all partner profiles found in a directory on the

server
Use this procedure to import multiple partner profiles only. To import a single profile, see Import a
partner profile from a file on page 145.
You typically use this procedure to migrate profile data from Interchange 4.2.x to Interchange 5.x
or later.
1. From the Partners menu, select Manage partners.

2. Click Add a partner to open the wizard.
3. Select Import all partner profiles found in a directory on the server and click Next.
4. Next to the Directory name box, click Browse to locate the directory where you store one or
more partner definition files.
5. Under Choose the import mode, select how the system should handle instances where a
partner currently exists with the same name as a partner you are importing.
l Allow these partners to be auto-cloned to peers – If your license supports the peer
communities, select the communities that you want each imported 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.
7. Click Next to define partner attributes. This option is displayed only if attributes are optional.
If there are mandatory attributes, this option does not display and the Finish button is
displayed.
8. Click Finish.
The partners are imported. The new partners are added to the list of available partners on the
Partners page.
After you create a partner

The partner creation wizard enables you to create a partner with basic configuration settings. After
you create a partner, you can view, modify and extend the partner configuration. See Modify a
partner on page 156.

Community trading partners

The trading partners that you can view and manage from a community are Interchange partners that
are associated with the community for message exchanges. You add trading partners to a
community in order to specify the partners that the community can trade with.
Note A partner can exist in your Interchange configuration without being associated with any
community. A partner can also be associated with multiple communities.
Where to view and manage community trading

partners
You view and manage the partners that are subscribed to a community from the community
Trading Partners page. To open this page:
1. From the menu bar select Trading configuration > Manage trading configuration to

open the Communities page.
2. From the list of communities, click the name of the community for which you want to view and
manage trading partners.
The interface opens the Summary page for the selected community.
3. In the navigation graphic at the top of the Summary page, click the Trading partners icon,
to open the community's Trading Partners page.
Trading partner page features

From the community Trading Partners page you can view and modify the following elements:
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.
Add a partner to a community
About these procedures

A trading partner is an Interchange partner that is associated with a community for message
exchanges. You add trading partners to a community in order to specify the partners that the
community can trade with.
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
Initial step – select the partner source

To add a partner to a community, you first select the partner source:

1. From the menu bar select Trading configuration > Manage trading configuration to

2. From the list of communities, click the name of the community to which you want to add a
partner.
The interface opens the Summary page for the selected community.
3. In the navigation graphic at the top of the Summary page, click the Trading Partners icon,
to open the community's Trading Partners page.
4. From the Related tasks list at the bottom of the page, click Add a partner to this
community, to open the partner wizard.
The first screen of the wizard prompts you to select the source of the partner configuration:
l Manually create a new partner
l Import the profile information from a file
l Import all profiles found in a directory on the server
l Choose an existing partner
5. Depending on your selection, complete the steps described in the following sections.
Manually create a new partner
Prerequisites
Optionally, use the partner data form to collect information about the partner. See Partner data form
on page 151.
Procedure
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 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.
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.
Import the profile information from a file
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.
4. Click Finish.
Partners page and on the community Trading partners page.
Import all profiles found in a directory on the server

You typically use this procedure to migrate profile data from an Interchange 4.2.x environment.

1. Next to the Directory name box, click Browse to locate the directory where you store one or

more XML partner definition files.
2. Under Choose the import mode, select how the system should handle instances where a
partner currently exists with the same name as a partner you are importing.
l Allow these partners to be auto-cloned to peers – If your license supports the peer
4. Click Next to define partner attributes. This option is displayed only if attributes are optional.
If there are mandatory attributes, this option does not display and the Finish button is
displayed.
5. Click Finish.
Partners page and on the community Trading partners page.
Choose an existing partner

1. From the list available partners, select one or more partners to add to the current community.
2. Click Finish.
The selected partners are added to the list of available partners on the community Trading
partners page.
Partner data form

Use the following form to record data about a partner who uses a trading engine other than
Interchange. You can use the information on the completed form to create a partner in the user
interface.
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.
Field Partner's data
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.
Protocol Partner's data
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
Setting Partner's data
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
Binary and XML documents

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:
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. At the top of the Summary page is a navigation graphic for the partner. This graphic represents
the parts of the partner configuration and provides active links to screens in which you manage
these parts.
4. In the user interface, place your cursor over a label. A red box appears around that part of the
graphic. Click inside the red box to go to the page the label references.
You can use the partner graphic links to view and edit the following user interface pages for the
partner:
l Community membership – Enables you to view and manage the communities the
partner belongs to. A partner should belong to at least one community. If the partner does
not belong to a community, a note on the partner summary page reminds you that should
subscribe, and provides a link for this task.
l Categories – Enables you to organize partners into groups. The use of this feature is
optional. For more information see Group partners by categories on page 158.
l Partner Delivery – Displays the message protocols and transports a community uses to
send messages to a partner. A partner can have multiple delivery exchanges, but only the
first in the list is used. If you intend to trade with a single partner using multiple message
protocols (for example, AS1 and AS3), set up one partner for each message protocol. For
more information see Community trading pickups and partner deliveries on page 256.

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.
Group partners by categories

Use partner categories to group partners in a way that suits your needs. For instance, you can add
categories representing geographic regions and then assign partners to the applicable regions.
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.
How to use categories

To use categories, first you create one or more categories, and then you add partners to the
categories.
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.
Add a partner to a category

1. 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. 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.
Use the partner search tool

When you have a large number of partners to manage, it is useful to use the search tool on the
Partners page to find specific partners.
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
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.
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
When to use an application pickup

Use an application pickup when you want to enable Interchange to consume messages from an
application.

Work with application pickups

Add an application pickup

1. In the user interface, select Trading configuration > Manage trading configuration.
that community.
3. Click the Application pickup icon in the navigation graphic to open the Application pickup
page.
4. Click Add an application pickup to open the wizard.
5. Choose a transport protocol to use for this application pickup and click Next.
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 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
When to use an application delivery

Use an application delivery when you want to enable Interchange to send messages to an
application.
Work with application deliveries

Add an application delivery

configuration.
that community.
3. Click Application delivery in the navigation graphic to open the Application delivery page.
4. Click Add an application delivery to open the wizard.
5. Choose a transport protocol to use for this application delivery and click Next.

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:
Transport-specific pages:
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
Application pickup and application

delivery fields
The following chapters describe the fields you complete when you add the various types of
application pickups and application deliveries:
Common screens:
Transport-specific screens:
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

From address and To address wizard fields

When you add a pickup that consumes messages, the pickup wizard displays the From address and
To address pages. Use these p ages to specify sender and receiver rules for consumed files.
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.
rule options below.

Address parsing rule options

l If the document is EDI, parse for the address – If an EDI document is picked up, use the
“to” and “from” addresses specified within it. Properly formatted EDI documents contain this
information.
o Perform enhanced EDI parsing to match partner messaging IDs – This setting
applies to X12, EDIFACT, and TRADACOMS. If selected, Interchange performs additional
parsing of the header information to create routing IDs with a colon separator between
values. For example, information from an EDIFACT file would be parsed in the following
format:
ID:interchange ID:internal ID:sub-internal ID
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 If the document is XML, use XPaths to locate the address – If an XML document is

picked up, use the “to” and “from” addresses specified by the XPaths within it. XML Path
Language or XPath is a language for addressing parts of an XML document.
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.
After you add the pickup

After you add a pickup, the From address and To address tabs are displayed on the maintenance
pages of all consumption transports.

FTP (external) transport configuration

The FTP transport can be used as a partner trading or back-end application transport. Back-end
application transports do not support the SSL options.
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:
<original file name>__<unique message ID>.<original file extension>

Configure FTP settings page

Use the following fields in the exchange wizard to configure this exchange.
l FTP Server – The name of the FTP server.
l Port – The port on which the server listens for incoming connections. The default is 21
(embedded FTP default is 4021).
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.
If connecting to a partner’s Interchange embedded FTP server, use mailbox if picking up. Leave
the field blank if delivering.
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. 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 check box and take steps of your own to make sure collisions do not
occur. If connecting to a partner’s Interchange embedded FTP server, clear the check box.
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 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.

o Use special extension in pickup directory for temporary files – If you prefer not to

use an inbox, select this option. When a file is being written to the pickup directory, a
temporary extension is added so that 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 User name – The user name to connect to the server.
l Password – The password to connect to the server.
l Confirm password – The password to connect to the server.
l Preserve original filenames – (Delivery exchange only) Select this option if you want
original file names to be preserved when Interchange delivers messages.
o Overwrite duplicate filenames – This option is available when you select the Preserve
original file names option above. If duplicate file names are detected, the trading engine
overwrites the existing file.
o Sequentially number duplicate filenames – This option is available when you select
the Preserve original file names option above. If duplicate file names are detected,
Interchange appends a number to the new file. For FTP and SFTP the appended number is
hexadecimal, with the format: filename_c4.
l Clients must use SSL to connect to this server – (For trading partner configuration only.)
Select this for FTPS. The Secure Sockets Layer protocol is 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.
l Enable host name verification – (For trading partner configuration only.) 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 the Interchange server. This is not applicable to integration exchanges.
o Use implicit SSL – (For trading partner configuration only.) Select this if you want to use
implicit SSL rather than explicit SSL, which is the default mode. FTP supports two methods
to accomplish security through a sequence of commands passed between two computers.
The sequence is initiated with explicit (active) or implicit (passive) security.
o Explicit security – To establish the SSL link, explicit security requires the FTP client to
issue a specific command to the FTP server after establishing a connection. The default
FTP server port is used.
o Implicit security – Implicit security begins with an SSL connection as soon as the FTP
client connects to an FTP server. The FTP server defines a specific port for the client to be
used for secure connections. Not all FTP servers support implicit security. Check the
documentation for your server.
File collision handling section
prevent Interchange from attempting to retrieve partially written files. When this option is
selected, you must select one of the two options listed below:

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.
with periods.
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
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.
FTP (embedded) transport configuration

A community can use an embedded FTP server to receive messages from partners or applications.

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
Types of embedded FTP servers

There are two types of embedded FTP servers:
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.
Embedded FTP user accounts

When you add an exchange that uses an embedded FTP server, you must specify an FTP user
account. You can select an existing account (if one exists) or define a new one. Interchange
internally associates user accounts with home directories for sending (PUT) or retrieving (GET)
messages. There are three types of accounts.

Account type Usage
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.
Community FTP accounts

Community FTP accounts are associated only with community pickups for receiving messages from
partners.
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
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.

Partner FTP accounts

Partner FTP accounts are used only for trading. The accounts typically are used for outbound
trading via deliveries set up for partners. But the same accounts can be used for inbound trading via
pickups set up in communities. In this case they can be used in lieu of, or in addition to, community
accounts.
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.
Outbound trading example
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:
p1/mailbox/c1 p1 GETS messages from community1
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.
Inbound trading example
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.
FTP accounts for back-end application exchanges

Application FTP accounts are associated only with application pickups and deliveries for retrieving
messages from, or delivering messages to, back-end systems. Application pickup exchanges are not
tied to a particular community.
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.
Firewalls, load balancers and embedded FTP

FTP servers present challenges with firewalls and load balancers. If you have a corporate firewall and
the computer running Interchange also has a Windows firewall, turn off the Windows firewall. Ask
the network administrator to open the control port for your embedded FTP server (default is 4021)
on the network firewall. You also may need to ask the administrator to open a range of ports for
passive connections (see Advanced tab on page 449, Allowed passive ports field).
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.
Embedded FTP fields
Configure server fields

When you add a new embedded FTP server to a community, you complete the following fields in
the exchange wizard.
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.
Select or create user account fields

You have the following 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

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 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 FTP account. It is where a partner sends messages to your community via FTP. If you use the
default location for the common directory, the directory is at <install
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 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.
Select a destination directory

l Enter a new path – This field enables you to associate the same embedded server and user
account to multiple sub-directories. Each sub-directory can be used by a single partner to send
messages to your community via FTP.
If you leave this field blank, the effective directory where a partner uploads messages is the top-
level directory. For example:
common\data\ftp\users\trading\<user account>
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.

nodes on page 474.
SFTP (external) transport configuration

You can use Secure FTP (SFTP) as a trading partner or application transport.
Note This topic describes configuring an external SFTP server. For an embedded SFTP server,
see SFTP (embedded) transport configuration on page 286.
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.
l SFTP server – The name of the SFTP server.

l Port – The port on which the server listens for incoming connections. The default is 22.
inbox directory.
must select one of the two following options.


with periods.
name:
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.

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.
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
5. Ensure the /etc/ssh/sshd_config file contains the following line:

HostbasedAuthentication yes
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:
**** Welcome to the Cyclone Sftp test program ****

-> Enter host: localhost
-> Enter user: ftpuser
-> Enter password: ftpuserpwd
-> Enter C for CONSUMER client (list, receive, delete), P for PRODUCER
(send). (Blank assumes C):
-> Enter pickup directory (blank for "pickup"):
-> Enter public key path/filename: ssh_host_dsa_key.pub
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
-> Enter PRODUCER command (e.g. ?, SEND, LLIST, LCD, QUIT): ?

PRODUCER metacommands (abbreviations shown in upper case):
? help
SEND filename write file to host
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
SFTP (embedded) transport configuration

A community can use an embedded Secure FTP (SFTP) server to receive messages from partners or
as an application transport.
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, you must choose a subdirectory within that account’s home directory that is not assigned
If you choose to define a new embedded SFTP server, the wizard prompts for a server name and port

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
Types of embedded SFTP servers

There are two types of embedded SFTP servers:
SFTP 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 SFTP — where your community
end systems.
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.
SFTP user accounts

When you add an exchange that uses an embedded SFTP server, you must specify an SFTP user
account. You can choose an existing account or define a new one. Interchange internally associates
user accounts with home directories for sending (PUT) or retrieving (GET) messages. There are
three types of accounts.
Account type Usage
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

Community SFTP accounts

Community SFTP accounts are associated only with community pickups for receiving messages from
partners.
a result, community SFTP accounts can be referred to as shared accounts.
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
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.
Partner SFTP accounts

Partner SFTP accounts are used only for trading. The accounts typically are used for outbound
accounts.
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

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:
Since partner SFTP accounts are partner-specific, message attribute mapping only is needed for
Message attribute mapping also can be used to sort messages into arbitrary subdirectories based on
items to outbound messages that would cause them to be sorted into subdirectories based on
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
The user interface suggests / as the home directory for the SFTP account where partners can drop
Note Embedded SFTP servers treat paths beginning with a slash as starting at the home directory

Application SFTP accounts

Application SFTP accounts are associated only with application pickups and deliveries for retrieving
When you create an SFTP account you can choose to either use an existing account, a new account
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.
Firewalls, load balancers and embedded SFTP

If you have a corporate firewall and the computer running Interchange also has a Windows firewall,
turn off the Windows firewall. Ask the network administrator to open the control port for your
embedded SFTP server (default is 4022) on the network firewall.
Embedded SFTP fields

When you add a new embedded SFTP server to a community, you complete the following fields in
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.
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.
User account fields

l Select an existing account from the drop-down list (if an account has been previously defined)
If you elect to define a new account, complete the fields for the authentication option you selected
on the previous wizard page.
l User name – The user name to connect to the server. This field applies to both authentication

options. 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 SFTP account. It is where a
partner sends messages to your community via SFTP. If you use the default location for the
common directory, the directory is at <install
directory>\common\data\ssh\users\trading. But if you are configuring a back-end
application transport, the path is <install
directory>\common\data\ssh\users\integration.
common\data\ssh\users\trading. Doing so could result in operational difficulties.
The back-end system always should interact with trading engine application-type
transports, and allow Interchange to route messages to and from trading-type transports.
Password authentication
l Password – The password to connect to the server. Anonymous connections are not
supported.
l Confirm password – Confirm the password.


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.
Destination directory fields

account to multiple subdirectories. Each subdirectory can be used by a single partner to send
messages to or receive messages from your community via SFTP. If you leave this field blank, the
effective directory where a partner uploads or downloads messages is the top-level directory. For
example:
common\data\ssh\users\trading\<user account>
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
SFTP servers.
nodes on page 474.

Public-private key and password authentication

The following procedures together describe how to use public-private key authentication and
password authentication for SFTP.
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.
Procedure 1: Local community exports a community profile for the

remote trading partner
1. Use an external tool such as PuTTY-Gen to generate an OpenSSH public-private key pair. You
cannot use Interchange to generate the key. Export the public-private key pair in OpenSSH
format.
In step 12 you give the public key in the key pair to your partner. Using your external tool,
export the pubic key in SSH1 single-line format.
2. On the community summary page, click Certificates in the navigation graphic at the top.
3. Select the SSH keys tab on the Certificates page.
4. Click Add an SSH key to add to the community the public-private key pair generated in step
1.
5. Select the key as the default SSH key and click Save changes.
6. In the community, add an embedded SFTP pickup for receiving messages from a partner. Set
up a user name and password for password authentication when adding the exchange.
7. Click the Embedded SFTP link of the exchange added in step 6 to open its maintenance page.
8. On the Directories tab, under Accounts owned by this community, be sure the user
added in step 6 is the default user. This user and password are exported to the local
community’s partner profile in step 12.
9. On the Embedded SFTP settings tab, click View settings for this embedded server.
10. On the server’s Settings tab, select the option This server requires the SFTP client to
authenticate using a password. Click Save changes.

11. Export the community profile as a partner profile. Give the public key from step 1 and the
profile file to the remote partner.
Procedure 2: Remote partner imports the community's profile and

exports a profile for the community
1. Import the profile of the local community (exported in the previous procedure) as a partner
profile in Interchange of the remote partner. (The remote partner also uses Interchange.)
2. Add an embedded SFTP trading pickup for receiving messages from a partner to the community
of the remote partner.
l Select public-private key pair authentication for the SFTP exchange.
l Select Configure SFTP user account later.
3. Click the Embedded SFTP link of the exchange added in the previous step, to open its
maintenance page.
4. On the Directories tab, click Add under Accounts owned by partners.
5. When prompted to pick a party, select the partner for the local community.
6. Click Create a new user.
l Enter a user name. This user name will be used again in the next procedure.
l Enter a password.
l Select a transport user password policy (see Manage password policies of transport users on
page 129).
l Click Browse and locate the public key file provided by the local community in the
imported profile.
l Click Save.
7. Return to the maintenance page of the SFTP trading pickup for the community.
authenticate using a public/private key pair. Click Save changes.
10. Export the community profile of the remote partner as a partner profile. Give the profile file to
the local community.
Procedure 3: Local community imports the trading partner's profile

1. Import the profile of the remote partner as a partner profile (exported in the previous
procedure).
2. Open the partner that represents the remote trading partner. On the partner summary page click
Application pickup on the navigation graphic at the top.
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.
File system transport configuration

When you specify inbound and outbound file system application directories, the system creates
subdirectories for its own use. The system must have permissions to create the subdirectories. Do
not delete these subdirectories or copy files to them or retrieve files from them.
File system deliveries with metadata

Use the file system with message metadata transport when you want a community to produce
MMDs to the file system on inbound deliveries. You configured this transport the same way you
configure as the basic file system transport. See the following topics for additional information
about using MMDs:
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
Configure the file system settings page

l Directory name – Enter the path to a directory on the trading engine server file system. If the
directory does not exist, the system creates it. If you use the trading engine in a multiple
computer cluster, make sure the directory is shared between computers.
l Preserve original filenames (application delivery only) – Select this option if you want
original file names to be preserved when Interchange delivers messages. This field applies to
delivery exchanges only.
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.
o Overwrite duplicate filenames – This option is available when you select to preserve
original file names. If duplicate file names are detected, Interchange overwrites the existing
file.

o Sequentially number duplicate filenames – This option is available when you select 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 ( application delivery only) – Select this option 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
Exchange name page

l Name – Enter a name to identify the delivery exchange. This is the name that will be displayed
in the interface.
JMS transport configuration

To use this exchange, you must have JMS experience and a working JMS system.
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.

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:
<NodeType type="TE" class="com.axway.clusterold.startup.Boot">

...
<Classpath>../jars/custom.jar</Classpath>
<Classpath>/JMSProviderJarPath</Classpath>
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.

...
</NodeType>
4. Save and close the file.
JMS fields
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
l This provider requires a user name and password – Select this if JMS requires a user

o User name – A user name for the JMS provider. This can be the same as your JNDI user
name. However, this depends on your JMS provider and how it is configured.
o Password – A password for the JMS provider. This can be the same as your JNDI password.
However, this depends on your JMS provider and how it is configured.
o Confirm password – The password again for confirmation.
l JMS connection factory – The connection factory as defined within the JMS provider. This
value can be either in the form factoryname@routername or the JNDI public symbol for the
QueueConnectionFactory. Examples: plainsocket@router1 or QueueConnectionFactory22. This
depends on your JMS provider and how it is configured.
l Use a custom Java implementation – Select this for a JMS provider that does not require a
JNDI implementation. For example, Oracle Advanced Queuing facility (Oracle AQ). When
selected the applicable fields display.

o Class name – The name of the Java class for implementing the connection to the message

queue. A Java class for Oracle AQ is available. The class name is:
com.cyclonecommerce.tradingengine.transport.jms.OracleAQQueueUtil
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.
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
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:
**** Welcome to the Cyclone JMS test program ****

-> (n)ew client, (c)onnect, (d)isconnect, (s)end, (r)etrieve, (a)cknowledge, (q)
uit: n
-> Use JNDI (Y/N - default is yes):
-> JNDI URL (): url
-> JNDI Factory (): factory
-> JNDI Username (): name
-> JNDI Password (): pwd
-> JMS Queue Connection Factory(null): :
-> JMS Queue (null):
-> JMS Username (null):

-> JMS Password (null):

-> Use Transacted Queue (Y/N - default is no):
-> Send using Bytes or Text Message type: (bytes):
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
IBM MQSeries transport configuration

You can use the MQSeries transport as a trading or an application transport.
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.
Note on MQ Server client authentication

configuration
Interchange supports MQSeries client authentication on the trading pickup side only. It does not
support client authentication on the application side. When you set up the connection between an
application pickup and an MQSeries Server, be sure to disable the option requiring client
authentication on the IBM MQ Server side.
Exchange point configuration

Complete the following fields in the exchange wizard to configure this transport:

l MQSeries connection type – Select an option:

o Client connection – Select this option to use a channel connection, on the local machine
or via the network, to connect to a queue manager.
o Server binding – Select this option to use an API connection, via shared memory, to a
local queue manager.
l MQSeries server – Enter the fully qualified domain name or IP address of the MQSeries host.
l Multi-instance queue manager – Select this option if you are using an MQSeries multi-
instance queue manager. See WebSphere MQ multiple instances on page 736.
l MQSeries standby server – Enter the MQSeries standby server address.
l Port – Enter the port where the application listens for incoming documents. Default = 1414
l Channel – Enter the name of the MQSeries communications channel configured on the
MQSeries server.
l Queue name – Enter the name of the MQSeries queue that receives incoming documents.
l Queue manager – Enter the name of the MQSeries queue manager.
l Convert data – Select this option if you want to convert the characters set of messages
received from a queue to the set specified in the Characters set field. Clear the check box to turn
off data conversion. This setting does not apply to messages outbound to a queue.
l Characters set – Specify the character set used by the queue manager. This number should
match the number used by the queue manager. Default = 819
l This server requires a user name and password – If the MQSeries server requires a user
name and password for connections, select this option, and then complete the fields:
o User name – Enter the user name for connecting to the server
o Password – Enter the password for connecting to the server
o Confirm password - Confirm the password
l Use SSL to connect to the IBM MQSeries server – Select this option if you want to use
SSL on connections to this MQSeries server.
Note: For SSL 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.
Interchange JSSE cipher suite Cipher specification (MQSeries

name)
SSL_RSA_EXPORT1024_WITH_DES_CBC_ DES_SHA_EXPORT1024
SHA
SSL_RSA_EXPORT1024_WITH_RC4_56_SHA RC4_56_SHA_EXPORT1024


name)
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_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
Add an MLLP application delivery

An application delivery is an object that specifies how you want your local community to send
messages to a back end application. This topic describes how to create an application delivery for
sending client requests to a back-end MLLP server application.
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
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:
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 the trading engine routes messages. If the
directory does not exist, the trading engine 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.
Add an MLLP application pickup

A community application pickup is an object that specifies how you want your local community
to consume messages from a back-end application. In this case, Interchange is in a server role,
consuming an MLLP client application request.
Prerequisite
You must have a community defined.
Procedure
configuration.
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.
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.
Web Services API pickup and delivery

configuration
The Web Services API transport can be used for application exchanges only.
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.
To modify the global API HTTP embedded server, select System management > Manage

embedded servers. Because the global server is shared by all communities, any configuration
changes affect all communities.

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.
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:

1. Click Application delivery in the navigation graphic at the top of the community Summary

page.
2. In the list of deliveries, click the Web Services API client exchange.
3. Click the Advanced tab.
4. Select Send the payload URL only.
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 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.
Modify an application pickup or delivery

After you create an application pickup or application delivery, use this procedure to view and modify
the settings for the exchange:

that community.
3. Click either Application pickup or Application delivery in the navigation graphic to open
the Application pickup or Application delivery page.
4. From the list, click the name of a pick up or delivery to open the modification page for that
exchange.
5. View or modify the fields for the exchange.

Fields for modifying application pickups

and application deliveries
The following chapters describe the fields you use to view and modify various types of application
pickups and application deliveries.
Common fields and tabs

l General fields on page 203
l From address and To address tabs on page 204
l Message attributes tab on page 206
l EDI splitter tab on page 207
l Inline processing tab on page 208
l Schedule tab on page 208
l Proxy tab on page 204
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.
l Use a proxy to access this server – Select this check box if you must pass through a proxy

to reach the delivery exchange server. For partner exchanges, the proxy is located between
Interchange and the partner’s HTTP server.
l Host – The URL of the proxy host.
l Port – The port where the proxy host listens for connections.
l This proxy requires a user name and password – Select this check box if the proxy
requires a user name and password before it accepts the connection. Obtain this information
from your partner.
From address and To address tabs

The following fields are displayed on the maintenance pages for all types of pickups:
l Specify the address – Specifies that the trading engine 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.
protocol address only– Select this option if the “from” or “to” address or both is configured
using the Message attributes tab. This option is available only for the file system transport.
the address – Select this option to use the protocol address if available. If not available, the
additional parse settings below apply.
l Always parse for the address – Specifies that the trading engine should always parse the
message for the sender or receiver address.

For messages from partners, however, the trading engine still checks the protocol header for the
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.
Additional parse settings

information.
applies to X12, EDIFACT, and TRADACOMS. If selected, the trading engine performs
additional parsing of the header information to create routing IDs with a colon separator
between values. For example, information from an EDIFACT file would be parsed in the
following format:
InterchangeID and ID values. For example, 1:partner is parsed as the sender and rendered
A:
:B
A:B


Message attributes tab

Use the Message attributes tab to attach metadata to the messages Interchange p icks up from
applications or receives from partners.
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
Message attributes template

Prerequisite: To have this feature available, you must first create at least one Message attributes
template.
l Default message attributes template to apply – From the drop-down list, select the

template to use as the default for this delivery exchange. If you do not select a template, a
message attributes template is not applied.
l Use message attributes template provided by the protocol – This option is available
only for OFTP and PeSIT exchanges. You can specify the template name in the file name of the
message submitted by the sender or by the setting on this tab. The choices are:
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.
Fixed message attributes

Use these fields to associate attributes with fixed values to messages picked up on an exchange.
Whenever the exchange handles a document, the metadata are attached. This is useful when, for
instance, you want to trigger processing actions based on an attribute or engage in ebXML trading
using static metadata.
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.
Attributes for email addresses

The trading engine supports the following email address attributes on the Message attributes
tabs of SMTP delivery exchanges:
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
EDI splitter tab

Use the EDI splitter tab to break apart documents containing more than one interchange into
separate documents.
l Enable the EDI splitter – Select this option to enable splitting.

Caution: If you select this option you must enable file backups on the Advanced tab. The EDI
splitter does not work when the backup option is disabled.
The EDI splitter works for X12, EDIFACT, and TRADACOMS documents. The splitter looks for
segments bracketed between interchange control headers. These are:
EDI document type Header segment Trailer segment
X12 ISA IEA

EDI document type Header segment Trailer segment
EDIFACT UNB UNZ
TRADACOMS STX END
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.
Inline processing tab

The extensible architecture of Interchange enables system integrators to apply custom logic to in-
process messages as an integral part of the processing pipeline. You can selectively apply the
custom processing logic to inbound or outbound messages at runtime, implemented as a user-
defined Java class.
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.
Modify an FTP (embedded) pickup or

delivery
After you create an FTP (embedded) pickup or delivery, you can view and modify the fields that
define the object.
This chapter provides information for completing fields in the maintenance pages.
For related information, see the following chapters:
FTP (embedded) settings tab (pickup)

l Embedded FTP server – The name of the server. A link is provided to view the settings for the
embedded server. You also can change servers.
l View settings for this application – Click this link to open the Modify Application
Pickup screen for this exchange. For a description of the fields you can view when you click this
link, see FTP (embedded) transport configuration on page 275.
l Host – The name used by Interchange for the computer running the embedded server. You
cannot change this field.
l Host used by partners – This is the fully qualified domain name or IP address your partners
use to send messages to this delivery exchange. When you export your community profile as a
partner profile, the host information becomes part of your exported partner profile.

You can change this field by clicking View settings for this embedded server and

changing the External host or IP address field. If your network uses a load balancer or firewall,
contact your network administrator for the correct value. Any change to this field affects all
delivery exchanges that reference the server.
FTP (embedded) settings tab (delivery)

Directories tab (pickup and delivery)

l FTP user – The name of the user.
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.
Filenames tab (delivery)
Delivery file name definition

l Preserve original filenames – (default) Select this option if you want the original file names
to be preserved when Interchange delivers messages.
Preserving original file names enables your back-end application to process binary messages

l Generate unique filenames – Select this option to have the system provide a unique file

name (instead of using the original name).
o Automatically generate unique filenames – Interchange appends to the file name a
hex representation of a monotonically increasing file name counter that is maintained in the
database. Names are 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.
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.
For additional information about entering renaming patterns, see File renaming patterns on
page 253.
Duplicate file name handling

l Overwrite duplicate filenames – If Interchange detects a duplicate file name, it overwrites
the existing file, replacing it with the duplicate file.
l Sequentially number duplicate filenames – (default) When you select this option you
must also select a name generation option:
o Automatically generate unique filenames – (default). If Interchange detects a
duplicate file name, it generates a sequentially numbered file name. Interchange appends a
number to the new file in the format: filename_c4
page 253.
l Append to existing files – Append the duplicate file content to the content of the original
file.
Advanced tab (pickup)

l Allow FTP clients to add, remove subdirectories – Enable subdirectory management on
the client side.
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 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.
Advanced tab (delivery)

l Maximum concurrent connections – (For partner trading delivery only.) 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 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 (PeSIT), the value in this field must be less than the CFTTCP setting in
Transfer CFT.
l Retries – (For partner trading delivery only.) The number of times Interchange retries to
connect to the partner’s transport if the initial attempt to connect and send the message failed.
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.
the client side.
copies of the messages it retrieves from applications or receives from partners.
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
l Post-processing script – The full path to an executable file that contains post-processing
commands. This field is available for both application and partner deliveries.

Modify an FTP (external) pickup or delivery

After you create an external FTP pickup or delivery, you view and modify the fields that define the
object.
FTP or FTPS settings tab (pickup and delivery)

l FTP Server – The network name of the FTP server.
l Select the file type – From the drop-down list, select the format of the files that are
transmitted over this delivery:
o Binary (default)
o ASCII - automatic line ending
o ASCII - user CR/LF
o ASCII - use LF only
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.

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 in a Community or Partner definition must be designated as the SSL certificate.
The server must support SSL. If this option is not selected, connections are not encrypted.
l 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.
l Use Implicit SSL – Select this option if you want to use implicit SSL rather than explicit SSL
(which is the default mode). FTP supports two methods to accomplish security through a
sequence of commands passed between two computers. The sequence is initiated with explicit
(active) or implicit (passive) security.
o Explicit security – To establish the SSL link, explicit security requires the FTP client to issue a
specific command to the FTP server after establishing a connection. The default FTP server
port is used.
o Implicit security – Implicit security begins with an SSL connection as soon as the FTP client
connects to an FTP server. The FTP server defines a specific port for the client to be used for
secure connections. Not all FTP servers support implicit security. Check the documentation
for your server.

inbox directory. If connecting to a partner’s Interchange-embedded FTP server, use mailbox if
picking up. Leave the field blank if delivering.
If connecting to a partner’s Interchange-embedded FTP server, clear the check box.
with periods.
name:

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.
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.



system generates.
dabeed45_4cb.edi
z47e4120_4ce

page 253.

number to the new file in the format: filename_c4.
page 253.
file.
File name security (external FTP servers only)

l Make output filenames safe for all FTP servers by prefixing them with a letter if
they start with numbers, and by applying the regular expressions in
filenamebeautifier.xml – (For external FTP servers only) Select this option to have
Interchange add a letter prefix to file names that begin with a numeral. This is for servers that
cannot process files with names that begin with a numeral.


l Maximum concurrent connections (for trading pickups only)– 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 consume,
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.
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"/>

l Delete file after it is downloaded – Select this if you want the server to delete files after

they have been downloaded from it. This option should be enabled in most cases. Most servers
do not delete files after clients have downloaded them. However, some servers do. If an external
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 the
back end 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 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

back-end applications or resend messages to partners.

Backup files are stored in \<install directory>\common\data\backup, unless you
specify otherwise.
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.
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.

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.
running his receiving system, decrease the value.
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, 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.
more information.



applies only to delivery exchanges using external FTP servers for picking up messages from
integration or receiving messages from partners.
consume or ignore. Use conventional wild card characters for file names or extensions or both.
rat, rot and rut.
case letter.
| Use the pipe character to separate multiple file-name formats. For example,


back-end application or resend messages to partners.
specify otherwise.
Modify an SFTP (embedded) pickup or

delivery
After you create an SFTP pickup or delivery, you can view and modify certain fields that define the
object.
SFTP (embedded) settings tab (pickup)

l Embedded SFTP server – The name of the server. A link is provided to view the settings for
the embedded server. You also can change servers.
o View settings for this embedded server – Click this link to open the Change this
embedded server screen for this exchange. This enables you to configure settings for the
screens described below. For a description of the fields you can view when you click this
link, see SFTP (embedded) server fields on page 453.
l Host used by partners – The fully qualified domain name or IP address your partners use pick
up messages from this exchange. When you export your community profile as a partner profile,
the host information becomes part of your exported partner profile.
You can change this field by clicking View settings for this embedded server (see above)
and changing the External host or IP address field. If your network uses a load balancer or
firewall, contact your network administrator for the correct value. Any change to this field affects
all delivery exchanges that reference the server.

SFTP (embedded) settings tab (delivery)

Pickup screen for this exchange. This enables you to configure settings for the screens
described below. For a description of the fields you can view when you click this link, see SFTP
(embedded) transport configuration on page 286.
l Host used by partners – The fully qualified domain name or IP address your partners use to
send messages to this delivery exchange. When you export your community profile as a partner
profile, the host information becomes part of your exported partner profile.
You can change this field by clicking View settings for application (see above) and
l Preserve original filenames – Select this option if you want original file names to be
preserved when Interchange delivers messages.
o Overwrite duplicate filenames – An option when you choose to preserve original file
names. If duplicate file names are detected, Interchange overwrites the existing file.
o 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 SFTP, the appended number is hexadecimal and has the format:
filename_c4.
name instead of using the original name.
When this option is selected, files are given arbitrary names. The names always have less than 30
characters and often have less than 20 characters.
o dabeed45_4cb.edi
o z47e4120_4ce

Directories tab (pickup)

On this tab you configure pickup directories associated with SFTP user accounts. Paths begin from
the home directory of the SFTP user account. Interchange places messages in these directories for
the partners or for the back-end system to download.
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.
Directories tab (delivery)

On this tab you configure delivery directories associated with SFTP user accounts. Paths begin from
the partners or for the back-end system to upload.
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.

l Allow SFTP clients to add, remove subdirectories – Enable subdirectory management on
the client side.
specify otherwise.
l Restrict maximum file size for this transport – Select this option to specify the maximum
size of files 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.

they have been downloaded from it.


the client side.
specify otherwise.
commands.
Modify an SFTP (external) pickup

After you create an external SFTP pickup, you can view and modify the fields that define the object.
An external SFTP pickup resides outside of Interchange.
SFTP settings tab

l Current public key – The RSA or DSA public key for the SFTP server. Interchange uses the key
to authenticate the server.
l New public key – Select this check box to display options for designating a new RSA or DSA
public key for the SFTP server. Interchange uses the key to authenticate the server. If the server
is modified to use a new public-private key pair, the public key must be updated.
file path. See Public-private key and password authentication on page 292.

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
inbox directory.
with periods.
name:
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
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.
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
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.
available.

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.
plus the interval.
receipts have not been received as expected. Another control, resends, determines how many
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.

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.
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:
rat, rot and rut.
case letter.



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
l Polling interval (seconds) – The interval in seconds Interchange waits before polling for

configured.
distribution among nodes. This option is available for integration pickup and trading delivery
exchanges that poll for messages.
transport servers.

Modify a file system pickup or delivery

After you create a file system pickup or delivery, you can view and modify certain fields that define
the object.
File system settings tab (pickup)

l Directory name – Use the Browse button or type the full path for a unique directory where
Interchange picks up or routes messages, depending on whether the transport is used for
sending or receiving. If the directory does not exist, Interchange creates it for you. Use a unique
directory name. When adding a file system transport, the exchange wizard suggests a name. You
may want to give the directory a name that indicates whether the transport is being used for
inbound or outbound integration, receiving messages from partners or sending messages to
partners. For example, for outbound integration you could name the pickup directory
\data\out; for inbound integration \data\in.
File system settings tab (delivery)

directory name. When adding a file system transport, the delivery exchange wizard suggests a
name. You may want to give the directory a name that indicates whether the transport is being
used for inbound or outbound integration, receiving messages from partners or sending
messages to partners. For example, for outbound integration you could name the pickup
directory \data\out; for inbound integration \data\in.



system generates.
dabeed45_4cb.edi
z47e4120_4ce

page 253.

page 253.
file.

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.)
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.
plus the interval.
copies of the messages it retrieves from the back end or receives from partners.

commands.

l Enable file filtering – Select this option if you want to enable filtering on the files that are
consumed by this pickup. When you select this option you must then enter a filter pattern to
apply to consumed file names, and indicate if the filter acts inclusively (only pick up files that
have names that match the filter) or exclusively (ignore only files that have names that match the
filter and pick up all others).
specify otherwise.
size of files the exchange can handle.
l Maximum file per polling interval – The highest number of messages the system can
l Polling interval – The interval in seconds Interchange waits before polling for messages to
retrieve.
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.
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.

On this tab you configure a directory associated with an SFTP user account. The path begins from
the home directory of the SFTP account. Interchange places messages in these directories for the
back-end system to download.
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.
Modify a JMS pickup or delivery

After you create a JMS pickup or delivery, you can view and modify certain fields that define the
object.
JMS settings tab (pickup and delivery)

configured.
configured.


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:
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.


l Receive time out (seconds) – If your JMS provider is slow to respond to the receive request

by Interchange, increase the response interval. The default value of 0 is acceptable in the case of
most JMS providers. However, if unacceptable for your JMS provider, use trial-and-error to
determine a workable interval between 1 and 32767 seconds.
l Use transacted queue – Select this option if the provider is Oracle AQ. Otherwise, do not
select it.
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.
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
configured.
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 following are all possible fields for polled and listener modes.

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.) 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.
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.
select it.
otherwise.
l Post Processing script – The full path to an executable file that contains post-processing
commands.
Modify an MQSeries pickup or delivery

After you create an MQSeries pickup or delivery, you can view and modify certain fields that define
the object.
IBM MQSeries settings tab (pickup and delivery)

l MQSeries connection type:
o Client connection – select this option to use a channel connection, on the local machine
l MQSeries server – The fully qualified domain name or IP address of the MQSeries host.
l Multi-instance queue manager – In the case where you have a multi-instance MQSeries
queue manager, you can select this option, and then select the MQSeries manager instance to
use as the standby server.
l Port – The port where the application listens for incoming documents. The default is 1414.
l Channel – The name of the communications channel.

l Queue name – The name of the MQSeries queue that receives incoming documents.

l Queue manager – The name of the MQSeries queue manager.
l Character set – The character set used by the queue manager. This number should match the
number used by the queue manager. The default is 819.
l Convert data – Select this option to convert the characters set of messages received from a
queue to the set specified in the Characters set field. Clear the check box to turn off data
conversion. This setting does not apply to messages outbound to a queue.
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.
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.


name)
SHA
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.



otherwise.
closed. A 413 message is Request Entity Too Large.
accommodate. This control is available only for transports used for picking up messages from
commands. This field applies to both application and partner deliveries.
configured.

transport servers.

engine is over running his receiving system, decrease the value. (This advice does not apply to
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.
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.
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.

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.
otherwise.
Modify a Web Services API server

application pickup or delivery
Web Services API server settings tab (server)

Embedded Web Services API server – Displays the name of the Web Services API server as a
hyperlink to the server 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. 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.

Web Services API client settings tab (client)

l URL – The URL Interchange uses to post messages to a back-end system for integration delivery.
Advanced tab (server)

otherwise.
Advanced tab (client)

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.

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.
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.
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 Send the entire payload contents – Send the payload through this transport. This option is

only for integration delivery.
l Send the payload URL only – Send only the URL that points to the payload and not the
payload itself.
l Response timeout (seconds) – How long in seconds that Interchange waits for the delivery
exchange to respond to a request before terminating the connection.
l Enable HTTP chunking – If you are sending files larger than 2 gigabytes, select this option 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.
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.


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.
Modify an MLLP application delivery

After you create an MLLP application delivery, you can view and modify the fields that define the
delivery.
File system settings tab

Interchange routes messages. If the directory does not exist, Interchange creates it for you. Use
a unique directory name.
Filenames tab

system generates.
dabeed45_4cb.edi
z47e4120_4ce


page 253.

page 253.
file.

See Message attributes tab on page 206.

See Inline processing tab on page 208.
Schedule tab
See Schedule tab on page 208.
Advanced tab
available.

triggering retries.
plus the interval.
commands.

Modify an MLLP application pickup

After you create an MLLP application pickup, you can view and modify fields that define the pickup.
MLLP (embedded) settings tab

l Embedded MLLP server – Name of the embedded MLLP server. To make changes in the
embedded server name or connection parameters, click View settings for this embedded
server.
l Local URL – You cannot modify this setting from this page. 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.
l URL used by partners – The URL used by MLLP client partners to connect to this server. This
URL is part of the partner profile when you export it. 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.
MLLP TLS (embedded) settings tab

l Embedded MLLP TLS server – Name of the embedded MLLP server. To make changes in the
server.
From address tab

See From address and To address tabs on page 204.
To address tab


EDI Splitter tab

See EDI splitter tab on page 207.

Schedule tab
Advanced tab
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
l Polling interval (seconds) – The interval, in seconds, Interchange waits before polling for
File renaming patterns

This chapter describes the use of file renaming patterns when you create or manage partner and
application deliveries of the type:
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.
Delivery exchange and Message Handler rename

patterns
You can enter any combination of the following elements it the Pattern field for Delivery exchange
file naming and duplicate handling, and Message Handler file renaming actions:
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.
Pattern Example result
New$filename$$extension$ NewTestFile1.txt
My$filename$_$sequence$$extension$ MyTestFile1_53.txt
$filename$_$sequence$$extension$ TestFile1_54.txt
%ReceiverRoutingId%_%metadata that is not ZZHERE__ZZP_101.txt

found%_%SenderRoutingId%_$sequence$$extension$

Delivery exchange duplicate file name patterns

In the Filename tab for FTP and File System exchanges you can set Duplicate file renaming by
entering a renaming pattern in the Pattern field. The patterns that you can enter in this field are
similar to the renaming patterns listed above, with the following differences:
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$
How Interchange handles file and duplicate file

naming
The Interchange trading engine sets the filename and extension values immediately before it parses
the name value for any pattern-based naming modification. This means that file renaming is based
on the current filename value, immediately before the renaming operation. When the filename value
is changed during a renaming operation, the new file name is used for the next renaming operation
that occurs in the message flow. So in the case where the file name is changed, it is no longer the
original incoming filename value that is used in the next rename operation, but the actual current
value.
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

About dots (.) in extension tags

In renaming patterns, the existing metadata element ConsumptionFilenameExtension always
includes the dot.
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.
Community trading pickups and partner

deliveries
Trading pickups are located in community objects. A trading pickup specifies how you want the
community to pick up or receive documents over the Internet from a remote partner.
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.
Message protocol Transport options Packaging options
AS4 Embedded HTTP Signing

Embedded HTTPS Encryption
Compression
EDIINT AS1 SMTP/POP Signing

Embedded SMTP Encryption
Compression
EDIINT AS2 Embedded HTTP Signing

Staged HTTP web Compression
servlet

EDIINT AS3 FTP Signing

Embedded FTP Encryption
SFTP Compression
Embedded SFTP
Secure file File system Signing

(see Secure file FTP Encryption
message protocol on Embedded FTP Compression
page 971) SFTP
Embedded SFTP
Embedded HTTP
Embedded HTTPS
JMS
MQSeries
Staged HTTP web
servlet
WebDAV
Generic email SMTP/POP Signing

(formerly Secure SMTP Encryption
e-mail)
(see About generic
email on page 260
below)
ebXML Embedded HTTP Signing

Staged HTTP web
servlet
Embedded SMTP
SMTP/POP
ebXML intermediary Embedded HTTP Not applicable. This protocol

Embedded HTTPS only re-routes messages. See
Staged HTTP web Send ebXML via an intermediary
servlet on page 562.
Embedded SMTP
SMTP/POP
Web services Embedded HTTP Signing


RosettaNet 1.1 Embedded HTTP Signing

Embedded HTTPS Compression
Staged HTTP web
servlet
RosettaNet 2.0 Embedded HTTP Signing

Staged HTTP web Compression
servlet
Odette FTP V1 OFTP V1 TCP/IP Signing

OFTP V1 X.25 Encryption
OFTP V1 X.25 over Compression
ISDN
Odette FTP V2 OFTP V2 Signing

Encryption
Compression
EBICS HTTPS Signing
X.420 X.420 None
X.435 X.435 Signing
PGP FTP Signing

SFTP Encryption
Compression
cXML HTTP Signing

HTTPS
PeSIT PeSIT None

No packaging HTTP None

FTP
Embedded FTP
SFTP
Embedded SFTP
File system
JMS
MQSeries
WebDAV
Pluggable embedded
server
No packaging notes
Development Kit. If you are an SDK user, see the pluggable embedded server chapter in the SDK
Developer’s Guide for configuration information.
About generic email

The generic email message protocol is exclusively for use when trading with partners who use email
client applications like Microsoft Outlook. For this reason, when a community has added a generic
email delivery exchange for receiving messages from partners, the transport configuration is
excluded upon exporting the profile to a file. This is to discourage partners who use trading engine
systems such as Interchange from trading via the generic email protocol. Trading engine partners
should trade instead via AS1 or another message protocol.
For other conditions about trading via the generic email protocol, see Email client partners on page
579.
If your partner uses Axway Gateway

If a partner uses Axway Gateway and your community wants to send messages to the partner via
secure file message protocol HTTP, note that there is a special field on the Advanced tab of the
maintenance pages for HTTP transports: 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.
Work with trading pickups and deliveries

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
Add a trading pickup

For an overview of trading pickups and deliveries, see Community trading pickups and partner
deliveries on page 256.

that community.
3. Click the Trading pickup icon in the navigation graphic to open the Trading pickups page for
that community.
4. Click Add a pickup to open the Exchange Wizard.
5. Choose a transport protocol to use to consume messages from partners and click Next.
6. Complete the fields on the following pages. The pages and fields vary depending on the
transport protocol you selected in the previous step.
Note After you complete the transport protocol configuration, your Trading pickup displays on
the same row as the associated Trading delivery if the transport settings are the same (for
example, both HTTP). If the transport setting are different (for example, pickup is POP and
delivery is SMTP), then the pickup displays on one line with the delivery on a separate line
immediately following the pickup line.
Common pages:
View the following topics for information on configuring specific trading pickup types:
l Staged HTTP on page 958

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
Add a partner trading delivery
Prerequisite
You must have a partner. See Add a partner on page 143.
Procedure
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:
View the following topics for information on configuring specific exchange types:

l ebXML on page 545
Trading pickup and trading delivery fields

The following chapters describe the fields you complete when you add the various types of
community trading pickups and partner deliveries.
Common pages:
View the following topics for information on configuring specific trading pickup types:
l Add or modify a PeSIT partner delivery on page 675
l ebXML on page 545
From address and To address wizard fields

When you add a pickup that consumes messages, the pickup wizard displays the From address and
To address pages. Use these p ages to specify sender and receiver rules for consumed files.
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
protocol address only .
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.
the address.
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.
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.
rule options below.
Address parsing rule options

information.
applies to X12, EDIFACT, and TRADACOMS. If selected, Interchange performs additional
parsing of the header information to create routing IDs with a colon separator between
values. For example, information from an EDIFACT file would be parsed in the following
format:

Interchange ID and ID values. For example, 1:partner is parsed as the sender and rendered
o A:
o :B
o A:B

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.
After you add the pickup

After you add a pickup, the From address and To address tabs are displayed on the maintenance
pages of all consumption transports.
File system transport configuration

When you specify inbound and outbound file system application directories, the system creates
subdirectories for its own use. The system must have permissions to create the subdirectories. Do
not delete these subdirectories or copy files to them or retrieve files from them.
File system deliveries with metadata

Use the file system with message metadata transport when you want a community to produce
MMDs to the file system on inbound deliveries. You configured this transport the same way you
configure as the basic file system transport. See the following topics for additional information
about using MMDs:

l ebXML on page 545
l AS4 on page 499
Configure the file system settings page

l Directory name – Enter the path to a directory on Interchange server file system. If the
directory does not exist, the system creates it. If you use Interchange in a multiple computer
cluster, make sure the directory is shared between computers.
l Preserve original filenames (application delivery only) – Select this option if you want
original file names to be preserved when Interchange delivers messages. This field applies to
delivery exchanges only.
o Overwrite duplicate filenames – This option is available when you select to preserve
original file names. If duplicate file names are detected, Interchange overwrites the existing
file.
o Sequentially number duplicate filenames – This option is available when you select 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 ( application delivery only) – Select this option to have the
system provide a unique file name instead of using the original name. This field applies to
community integration delivery exchanges and partner delivery exchanges only.
When selected, files are given arbitrary names. The names always have less than 30 characters
and often have less than 20 characters.
o dabeed45_4cb.edi
o z47e4120_4ce
Exchange name page

l Name – Enter a name to identify the delivery exchange. This is the name that will be displayed
in the interface.

HTTP (external) trading configuration

Communities can send messages to partners using an external HTTP server.
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
nodes on page 474.

HTTP (embedded) trading configuration

A community can use an embedded HTTP server to receive messages from partners.
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:
l Use the system’s global embedded HTTP server – If you select this option, the wizard

uses the default routing ID for the community as the last string in the URL. You can accept or
change the string. No other configuration is required.
l Use staged HTTP web servlet – If you select this option, you must install and configure a
web servlet application in addition to using the delivery exchange wizard to add the transport.
For details see Staged HTTP on page 958.
l Use a previously defined embedded HTTP server (if available) – 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. No other
configuration is required.
l Define a new embedded HTTP server – If you choose to use a previously defined
embedded HTTP server, the wizard prompts for the server name and a community routing ID to
append to the URL. No other configuration is required.
o 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.
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.

Community trading pickups and partner deliveries
o This server requires client authentication – If you selected SSL, select this check box

to require your partners to submit a certificate to verify their identity before the delivery
exchange allows the connection. Clear this box to use non-authenticated HTTPS. If you
select this, you must add an authentication certificate for the partner.
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.
Email partner transport configuration

When you add a Community pickup and select either EDINT AS1 (email) or Generic email as the
message protocol, on the following page you must select the type of email server you want to use:
l Use a detached email server – Select this option to use an external POP server retrieve

messages sent by partners.
To configure the email pickup to use this option, see Email (detached) trading configuration on
page 271.
l Use the system's global embedded SMTP server – Select this option to use the system’s
default global embedded SMTP server to receive messages from partners.
To configure the email pickup to use this option, see Email (embedded) trading configuration
on page 270.
l Use a previously defined embedded SMTP server (if available) – This selection is
available if you have already added a new embedded SMTP server.
on page 270.
l Define a new embedded SMTP server – Select this option to add a new embedded SMTP
server for use to receive messages from partners.
on page 270.

Email (embedded) trading configuration

A community can use an embedded SMTP server to receive messages from partners.
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 Use the system’s global embedded SMTP server – If you select this option, Interchange

sets up the email address for you.
l Use a previously defined embedded SMTP server (if available) – If you select this option,
the wizard prompts you to select the server.
l Define a new embedded SMTP server – If you select this option, the wizard prompts for a
server name and port number.
The following fields are used in the delivery exchange wizard for adding an embedded SMTP server
transport by defining a new embedded SMTP server.
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.
Set the system property to permit EDI processing

To enable Interchange to automatically process the incoming EDI files that are attached to emails,
regardless of the used Mime type, after you configure Interchange for the reception of email
messages you must set a system property to force Interchange to ignore the ContentMimeType
attribute value. To do this:
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.

After you configure the transport

Once you have set up the transport, you can modify the server settings, if necessary. See Modify a
global embedded SMTP server on page 440 or SMTP (embedded) configuration on page 459.
Email (detached) trading configuration

When you add a community trading pickup with a detached email server to a community,
Interchange splits the information you provide into separate POP and SMTP entries on the Delivery
exchanges page. The POP settings indicate how Interchange retrieves email messages from partners.
You must provide the SMTP settings to your trading partners so they know how to send messages to
the community.
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 Email address – The email address that the remote partner uses to send messages to your local

community.
l POP server – The name of the POP server that Interchange polls for messages sent by your
partner. This must be a fully qualified domain name or IP address.
l Port – The POP server port. Default = 110
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.
Set the system property to permit EDI processing


6. Click Add.
FTP (external) transport configuration

The FTP transport can be used as a partner trading or back-end application transport. Back-end
application transports do not support the SSL options.
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.
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:
<original file name>__<unique message ID>.<original file extension>

Configure FTP settings page

Use the following fields in the exchange wizard to configure this exchange.
l FTP Server – The name of the FTP server.
inbox directory.
If connecting to a partner’s Interchange embedded FTP server, use mailbox if picking up. Leave
the field blank if delivering.
must select one of the two following options. 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 check box and take steps of your own to make sure collisions do not
occur. If connecting to a partner’s Interchange embedded FTP server, clear the check box.
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.
with periods.
name:
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.


use an inbox, select this option. When a file is being written to the pickup directory, a
temporary extension is added so that 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 Preserve original filenames – (Delivery exchange only) Select this option if you want
original file names to be preserved when Interchange delivers messages.
o Overwrite duplicate filenames – This option is available when you select the Preserve
original file names option above. If duplicate file names are detected, the trading engine
overwrites the existing file.
o Sequentially number duplicate filenames – This option is available when you select
the Preserve original file names option above. If duplicate file names are detected,
Interchange appends a number to the new file. For FTP and SFTP the appended number is
hexadecimal, with the format: filename_c4.
l Clients must use SSL to connect to this server – (For trading partner configuration only.)
Select this for FTPS. The Secure Sockets Layer protocol is 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.
l Enable host name verification – (For trading partner configuration only.) 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 the Interchange server. This is not applicable to integration exchanges.
o Use implicit SSL – (For trading partner configuration only.) Select this if you want to use
implicit SSL rather than explicit SSL, which is the default mode. FTP supports two methods
to accomplish security through a sequence of commands passed between two computers.
The sequence is initiated with explicit (active) or implicit (passive) security.
o Explicit security – To establish the SSL link, explicit security requires the FTP client to
issue a specific command to the FTP server after establishing a connection. The default
FTP server port is used.
o Implicit security – Implicit security begins with an SSL connection as soon as the FTP
client connects to an FTP server. The FTP server defines a specific port for the client to be
used for secure connections. Not all FTP servers support implicit security. Check the
documentation for your server.
File collision handling section
prevent Interchange from attempting to retrieve partially written files. When this option is
selected, you must select one of the two options listed below:

If you are connecting to a partner’s Interchange-embedded FTP server, do not select this option.
with periods.
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
retrieved.
Click Next to name the exchange.
After you name the exchange, Finish.
nodes on page 474.
FTP (embedded) transport configuration

A community can use an embedded FTP server to receive messages from partners or applications.
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, you must choose a sub-directory within that account’s home directory that is not assigned
If you choose to define a new embedded FTP server, the wizard prompts for a server name and port
Note For a description of configuring an external FTP server, see FTP (external) transport
Types of embedded FTP servers

There are two types of embedded FTP servers:
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
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.
Embedded FTP user accounts

When you add an exchange that uses an embedded FTP server, you must specify an FTP user
account. You can select an existing account (if one exists) or define a new one. Interchange
internally associates user accounts with home directories for sending (PUT) or retrieving (GET)
messages. There are three types of accounts.
Account type Usage
Community FTP accounts on page 277 Community exchanges, trading servers only
Partner FTP accounts on page 277 Community and partner exchanges, trading
servers only

Account type Usage
FTP accounts for back-end application exchanges Community exchanges, application servers
on page 279 only
Community FTP accounts

Community FTP accounts are associated only with community pickups for receiving messages from
partners.
a result, community FTP accounts can be referred to as shared accounts.
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:
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.
Partner FTP accounts

Partner FTP accounts are used only for trading. The accounts typically are used for outbound
accounts.

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
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:
Since partner FTP accounts are partner-specific, message attribute mapping only is needed for
Message attribute mapping also can be used to sort messages into arbitrary sub-directories based on
items to outbound messages that would cause them to be sorted into sub-directories based on
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

The user interface suggests / as the home directory for the FTP account where partners can drop
Note Embedded FTP servers treat paths beginning with a slash as starting at the home directory
FTP accounts for back-end application exchanges

Application FTP accounts are associated only with application pickups and deliveries for retrieving
When you create an FTP account you can choose to either use an existing account, a new account
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.
Firewalls, load balancers and embedded FTP

FTP servers present challenges with firewalls and load balancers. If you have a corporate firewall and
the computer running Interchange also has a Windows firewall, turn off the Windows firewall. Ask
the network administrator to open the control port for your embedded FTP server (default is 4021)
on the network firewall. You also may need to ask the administrator to open a range of ports for
passive connections (see Advanced tab on page 449, Allowed passive ports field).
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.
Embedded FTP fields
Configure server fields

When you add a new embedded FTP server to a community, you complete the following fields in
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.
5021 for an integration server. For security reasons, trading and integration servers must use
different ports.
Select or create user account fields

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.

the FTP account. It is where a partner sends messages to your community via FTP. If you use the
default location for the common directory, the directory is at <install

directory>\common\data\ftp\users\trading. But if you are configuring an application
transport, the path is <install directory>\common\data\ftp\users\integration.
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.
supported.
Select a destination directory

account to multiple sub-directories. Each sub-directory can be used by a single partner to send
messages to your community via FTP.
If you leave this field blank, the effective directory where a partner uploads messages is the top-
level directory. For example:
common\data\ftp\users\trading\<user account>
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>
change this.
Interchange keeps track of the embedded FTP directory structure for you. Do not manually
FTP servers.
nodes on page 474.
SFTP (external) transport configuration

You can use Secure FTP (SFTP) as a trading partner or application transport.
Note This topic describes configuring an external SFTP server. For an embedded SFTP server,
see SFTP (embedded) transport configuration on page 286.

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

inbox directory.
with periods.
name:

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.
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.
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.
Select the key as the default SSH key after it has been added.
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
5. Ensure the /etc/ssh/sshd_config file contains the following line:

HostbasedAuthentication yes
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
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:

**** Welcome to the Cyclone Sftp test program ****

-> Enter password: ftpuserpwd
-> Enter C for CONSUMER client (list, receive, delete), P for PRODUCER
(send). (Blank assumes C):
-> Enter public key path/filename: ssh_host_dsa_key.pub
sftpTester displays a main prompt that allows you to enter meta-commands to perform simple
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): ?
? help
Producer commands
-> Enter PRODUCER command (e.g. ?, SEND, LLIST, LCD, QUIT): ?

? help
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
SFTP (embedded) transport configuration

A community can use an embedded Secure FTP (SFTP) server to receive messages from partners or
as an application transport.
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, you must choose a subdirectory within that account’s home directory that is not assigned
If you choose to define a new embedded SFTP server, the wizard prompts for a server name and port
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
Types of embedded SFTP servers

There are two types of embedded SFTP servers:
SFTP 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 SFTP — where your community
end systems.

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.
SFTP user accounts

When you add an exchange that uses an embedded SFTP server, you must specify an SFTP user
account. You can choose an existing account or define a new one. Interchange internally associates
user accounts with home directories for sending (PUT) or retrieving (GET) messages. There are
three types of accounts.
Account type Usage
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
Community SFTP accounts

Community SFTP accounts are associated only with community pickups for receiving messages from
partners.
a result, community SFTP accounts can be referred to as shared accounts.
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:
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.
Partner SFTP accounts

Partner SFTP accounts are used only for trading. The accounts typically are used for outbound
accounts.
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
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:

Since partner SFTP accounts are partner-specific, message attribute mapping only is needed for
Message attribute mapping also can be used to sort messages into arbitrary subdirectories based on
items to outbound messages that would cause them to be sorted into subdirectories based on
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
The user interface suggests / as the home directory for the SFTP account where partners can drop
Note Embedded SFTP servers treat paths beginning with a slash as starting at the home directory
Application SFTP accounts

Application SFTP accounts are associated only with application pickups and deliveries for retrieving
When you create an SFTP account you can choose to either use an existing account, a new account
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.

Firewalls, load balancers and embedded SFTP

If you have a corporate firewall and the computer running Interchange also has a Windows firewall,
turn off the Windows firewall. Ask the network administrator to open the control port for your
embedded SFTP server (default is 4022) on the network firewall.
Embedded SFTP fields

When you add a new embedded SFTP server to a community, you complete the following fields in
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.
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.
– 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.
public/private key pair –
Select this option to require both a password and public/private key pair.
public/private key pair – Select this option to require either a password or a public/private
key pair.

User account fields

l Select an existing account from the drop-down list (if an account has been previously defined)
If you elect to define a new account, complete the fields for the authentication option you selected
on the previous wizard page.
l User name – The user name to connect to the server. This field applies to both authentication

options. 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 SFTP account. It is where a
partner sends messages to your community via SFTP. If you use the default location for the
common directory, the directory is at <install
directory>\common\data\ssh\users\trading. But if you are configuring a back-end
application transport, the path is <install
directory>\common\data\ssh\users\integration.
common\data\ssh\users\trading. Doing so could result in operational difficulties.
The back-end system always should interact with trading engine application-type
transports, and allow Interchange to route messages to and from trading-type transports.
Password authentication
l Password – The password to connect to the server. Anonymous connections are not
supported.
l Confirm password – Confirm the password.
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.
Destination directory fields

messages to or receive messages from your community via SFTP. If you leave this field blank, the
effective directory where a partner uploads or downloads messages is the top-level directory. For
example:
common\data\ssh\users\trading\<user account>
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
SFTP servers.
nodes on page 474.
Public-private key and password authentication

The following procedures together describe how to use public-private key authentication and
password authentication for SFTP.
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.
Procedure 1: Local community exports a community profile for the remote

trading partner
1. Use an external tool such as PuTTY-Gen to generate an OpenSSH public-private key pair. You
cannot use Interchange to generate the key. Export the public-private key pair in OpenSSH
format.
In step 12 you give the public key in the key pair to your partner. Using your external tool,
export the pubic key in SSH1 single-line format.
2. On the community summary page, click Certificates in the navigation graphic at the top.
3. Select the SSH keys tab on the Certificates page.
4. Click Add an SSH key to add to the community the public-private key pair generated in step
1.
5. Select the key as the default SSH key and click Save changes.
6. In the community, add an embedded SFTP pickup for receiving messages from a partner. Set
up a user name and password for password authentication when adding the exchange.
7. Click the Embedded SFTP link of the exchange added in step 6 to open its maintenance page.
8. On the Directories tab, under Accounts owned by this community, be sure the user
added in step 6 is the default user. This user and password are exported to the local
community’s partner profile in step 12.

authenticate using a password. Click Save changes.
11. Export the community profile as a partner profile. Give the public key from step 1 and the
profile file to the remote partner.
Procedure 2: Remote partner imports the community's profile and exports a

profile for the community
1. Import the profile of the local community (exported in the previous procedure) as a partner
profile in Interchange of the remote partner. (The remote partner also uses Interchange.)
2. Add an embedded SFTP trading pickup for receiving messages from a partner to the community
of the remote partner.
l Select public-private key pair authentication for the SFTP exchange.
l Select Configure SFTP user account later.
3. Click the Embedded SFTP link of the exchange added in the previous step, to open its
maintenance page.
4. On the Directories tab, click Add under Accounts owned by partners.
5. When prompted to pick a party, select the partner for the local community.


l Enter a user name. This user name will be used again in the next procedure.
l Enter a password.
l Select a transport user password policy (see Manage password policies of transport users on
page 129).
l Click Browse and locate the public key file provided by the local community in the
imported profile.
l Click Save.
7. Return to the maintenance page of the SFTP trading pickup for the community.
authenticate using a public/private key pair. Click Save changes.
10. Export the community profile of the remote partner as a partner profile. Give the profile file to
the local community.
Procedure 3: Local community imports the trading partner's profile

1. Import the profile of the remote partner as a partner profile (exported in the previous
procedure).
2. Open the partner that represents the remote trading partner. On the partner summary page click
Application pickup on the navigation graphic at the top.
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.
JMS transport configuration

To use this exchange, you must have JMS experience and a working JMS system.
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.
Troubleshooting
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:

...
<Classpath>../jars/custom.jar</Classpath>
<Classpath>/JMSProviderJarPath</Classpath>
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:
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.

...
</NodeType>
JMS fields
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.
configured.
configured.



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:
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.
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
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:
**** Welcome to the Cyclone JMS test program ****

-> (n)ew client, (c)onnect, (d)isconnect, (s)end, (r)etrieve, (a)cknowledge, (q)
uit: n
-> Use JNDI (Y/N - default is yes):
-> JNDI URL (): url
-> JNDI Factory (): factory
-> JNDI Username (): name
-> JNDI Password (): pwd

-> JMS Queue Connection Factory(null): :

-> JMS Queue (null):
-> JMS Username (null):
-> JMS Password (null):
-> Use Transacted Queue (Y/N - default is no):
-> Send using Bytes or Text Message type: (bytes):
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
IBM MQSeries transport configuration

You can use the MQSeries transport as a trading or an application transport.
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.
Note on MQ Server client authentication configuration

Interchange supports MQSeries client authentication on the trading pickup side only. It does not
support client authentication on the application side. When you set up the connection between an
application pickup and an MQSeries Server, be sure to disable the option requiring client
authentication on the IBM MQ Server side.
Exchange point configuration

Complete the following fields in the exchange wizard to configure this transport:

l MQSeries connection type – Select an option:

o Client connection – Select this option to use a channel connection, on the local machine
l MQSeries server – Enter the fully qualified domain name or IP address of the MQSeries host.
l Multi-instance queue manager – Select this option if you are using an MQSeries multi-
instance queue manager. See WebSphere MQ multiple instances on page 736.
l MQSeries standby server – Enter the MQSeries standby server address.
l Port – Enter the port where the application listens for incoming documents. Default = 1414
l Channel – Enter the name of the MQSeries communications channel configured on the
MQSeries server.
l Queue name – Enter the name of the MQSeries queue that receives incoming documents.
l Queue manager – Enter the name of the MQSeries queue manager.
l Convert data – Select this option if you want to convert the characters set of messages
received from a queue to the set specified in the Characters set field. Clear the check box to turn
off data conversion. This setting does not apply to messages outbound to a queue.
l Characters set – Specify the character set used by the queue manager. This number should
match the number used by the queue manager. Default = 819
l This server requires a user name and password – If the MQSeries server requires a user
name and password for connections, select this option, and then complete the fields:
o User name – Enter the user name for connecting to the server
o Password – Enter the password for connecting to the server
o Confirm password - Confirm the password
l Use SSL to connect to the IBM MQSeries server – Select this option if you want to use
SSL on connections to this MQSeries server.
Note: For SSL you must add a trusted certificate for access to the IBM MQSeries server after
completing the configuration of this delivery exchange.

name)
SHA


name)
SSL certificates for MQSeries transports

For SSL exchanges between Interchange and an MQSeries server, you require two certificates:
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.

3. Select the Trusted SSL root certificates tab.

The interface displays the list of SSL trusted certificates available for the community.
Add certificate
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
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.
Community application pickup certificate

The community uses this certificate to consume messages from the MQSeries server.
View certificates
To view community application pickup SSL certificates:
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
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
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.
OFTP transport configuration

A community can use an OFTP transport to trade messages with partners. The following paragraphs
describe the fields in the exchange wizard for adding OFTP trading pickups and trading deliveries.

OFTP V1 server or polling fields

The following are the fields for adding an OFTP V1 delivery in a community.
Transport type
Select the option for receiving messages from remote partners:
l Define a new embedded OFTP server. Add an embedded server for clients to connect to

and send messages to the community. Go to Network type on page 305.
l Select a partner OFTP exchange to poll. Poll a partner’s server for inbound messages to
retrieve. Click Next and select the server to poll. Then 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.
X.25 router configuration

The following fields display only if you select to add an X.25 router. For more about X.25 see Use
X.25 with OFTP on page 628.
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.

ISDN router and controller configuration

The following fields display only if you select to add an ISDN router and controller defintion. For
more about X.25 over ISDN see Use X.25 over ISDN on page 632.
Interchange uses a name in the following format: Router on <host name or IP>.
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.

OFTP V1 server fields (TCP)

The following are the server fields, unless you selected X.25 or X.25 over ISDN. See OFTP V1 server
fields (X.25 or X.25 over ISDN) on page 307.
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
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.
OFTP V1 server fields (X.25 or X.25 over ISDN)

session setup.
l Server network user address – The NUA to wait for an incoming call via OFTP V1 X.25.

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.
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
community.
partner.

Transport type

and send messages to the community. Go to OFTP V2 server fields on page 309.
See the following figure: add OFTP V2 embedded server in delivery exchange wizard.

OFTP V2 server fields

session setup.
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
community.
partner.
OFTP V1 client fields

The following are the fields in the delivery exchange wizard for configuring this transport. These are
the fields for adding an OFTP V1 delivery for a partner.
OFTP transport type

l Define a new external OFTP server – Set up the delivery exchange to connect to an
external server to send messages to a remote partner. See Network type on page 310.
l Select the partner OFTP exchange to share – Set up the delivery exchange to connect to
an external server already in use by another remote partner. See Select partner OFTP exchange
on page 310.
Select partner OFTP exchange

l Partner OFTP exchange to share – Select the partner delivery exchange to share, if any are
available. The available choices are OFTP V1 or OFTP V2 delivery exchanges for other partners.
The user interface only allows selecting delivery exchanges of the same type being added. For
example, if you are adding an OFTP V1 exchange, only OFTP V1 selections are available.
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.
Network type

or add one to use.



more about X.25 over ISDN see OFTP on page 611.
2662.
name or IP>.


See the following figure: add OFTP V1 (TCP) client in delivery exchange wizard.
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.
session setup.
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).


o Enable host name verification – If selected, Interchange compares the name of the TLS
o Set OFTP session password – Enter a password only when required. The password can
be no longer than eight alphanumeric characters and is case sensitive.
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.
nodes on page 474.

the fields for adding an OFTP V2 delivery exchange for a partner.
OFTP transport type

external server to send messages to a remote partner. See OFTP settings on page 314.
on page 314.


See the following figure: add OFTP V2 client in delivery exchange wizard.
OFTP settings
session setup.


exchange.
o Select a different encryption certificate for secure authentication – Select the
partner certificate to use for secure authentication other than the default certificate.
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.
community.
partner.
nodes on page 474.
WebDAV transport configuration

The WebDAV transport can be used as an application or trading transport.

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.
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.
You have these options for selecting a user 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.
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.
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.
supported.

messages to your community via WebDAV. If you leave this field blank, the effective directory
where a partner uploads messages is the top-level directory. For example:
common\data\webDAV\users\trading\<user account>
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>

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.
Secure file message protocol

Secure file message protocol is an Axway-proprietary protocol that provides EDIINT packaging over
transport protocols not supported by EDIINT AS1 / AS2 / AS3.
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
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.
Add an MLLP trading pickup

A community trading pickup is an object that specifies how you want your local community to
consume messages from a remote partner. In this case, Interchange is in a server role, consuming an
MLLP client request.
Prerequisite
Procedure
configuration.
that community.

4. Click Add a pickup.
8. In the Choose transport protocol page, select MLLP and click Next.
authentication certificate trusted by the server when connecting –
11. Click Finish.

Add an MLLP trading delivery

A trading partner delivery is an object that specifies how you want your local community to
send messages over the Internet to a remote partner. This topic describes how to create a trading
partner delivery for sending client requests to an MLLP server.
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.
8. On the Exchange name page, enter a name for the partner delivery.
9. Click Finish.
Add a Web Services trading delivery

partner delivery for consuming services from a Web Services partner that is acting in a Web Services
provider role.
Prerequisites
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.
About the WSDL parsing wizard

Community collaboration settings specify how a community packages the messages it sends to
partners. When you create a delivery using the WSDL parser wizard, the wizard automatically
generates a set of community collaboration settings by parsing a WSDL file that you specify.
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)
Option 1: Configure with WSDL parsing wizard

1. In the user interface, from the Partners menu select Manage partners to open the Partners
page.
2. Select the partner you want to use to represent your WebService partner.
4. On the Delivery exchanges page, click Add a delivery exchange.
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, 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.

Option 2: Manual configuration

page.
2. Select the partner you want to use to represent your Web Services partner.
4. On the Partner deliveries page, click Add a delivery.
6. On the Choose configuration type page, select the option Configure delivery manually and
click Next.
7. On the Choose transport protocol page, HTTP displays as the default. Click Next.
8. On the Configure the HTTP settings page, complete the fields:
l URL — Enter the partner's web service URL.
l This server requires a user name and password — Select this option if the partner's
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.
After you create the Web Services trading partner delivery

The delivery is added to the list that displays on the partner's Partner deliveries p age.
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.

Add a Web Services trading pickup

consume messages over the Internet from a remote partner. This topic describes how to create a
community trading pickup for Web Services exchanges.
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
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).
6. On the Choose transport protocol page the only option is HTTP.

7. On the Choose HTTP transport type page select the option Use the sytem's global
embedded HTTP server
8. On the Configure URL page, enter the URL that you will use to expose this Web Service.
9. On the Exchange name page - Enter a name for the trading pickup. For example, MyWS_
pickup. This is the name that is displayed in the Interchange user interface.
10. Click Finish.
After you create the Web Services community trading pickup

The pickup is added to the list that displays on the community's Trading pickups p age.
l You can tune or modify the Web Services pickup.
Modify a trading pickup

When you add a trading pickup, the exchange wizard prompts you to provide a basic set of
parameters. After you create the pickup, you can open the maintenance page to view and manage a
comprehensive set of parameters for the pickup. Some of these parameters were automatically set
when you added the object and can only be modified after you add the object.

To view and modify a trading pickup:

configuration.
that community.
4. From the list of available exchanges, click the name of a trading pickup or delivery to open the
maintenance page for that exchange.
5. View and modify the fields as required.
For details about the configuration of the various pickup types, use the links below.
l SMTP (embedded) configuration on page 459
l ebXML on page 545
Modify a partner trading delivery

After you create a trading partner delivery, use this procedure to view and modify the delivery
settings:

partner.
3. Click the Partner delivery icon in the navigation graphic to open the Partner deliveries
page.
4. From the list of deliveries, click the name of a delivery to open the Change this delivery page for
the selected delivery.
This page displays a set of tabs and fields that vary depending on the delivery type.
5. View and modify the fields as required.
6. Click Save changes when you are done modifying.

For details about the fields you can view and modify, see Fields for modifying community pickups
and partner deliveries on page 328.
Fields for modifying community pickups

and partner deliveries
The following chapters describe the fields you use to view and modify various types of community
pickups and partner deliveries.
Common fields and tabs

l General fields on page 203
l Proxy tab on page 204
l From address and To address tabs on page 204
l Message attributes tab on page 206
l EDI splitter tab on page 207
l Inline processing tab on page 208
l Schedule tab on page 208
Transport-specific tabs
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
Modify a file system pickup or delivery

After you create a file system pickup or delivery, you can view and modify certain fields that define
the object.
File system settings tab (pickup)

directory name. When adding a file system transport, the exchange wizard suggests a name. You
may want to give the directory a name that indicates whether the transport is being used for
inbound or outbound integration, receiving messages from partners or sending messages to
partners. For example, for outbound integration you could name the pickup directory
\data\out; for inbound integration \data\in.
File system settings tab (delivery)




system generates.
dabeed45_4cb.edi
z47e4120_4ce

page 253.


page 253.
file.

available.

integration.
triggering retries.
plus the interval.
copies of the messages it retrieves from the back end or receives from partners.

commands.

l Enable file filtering – Select this option if you want to enable filtering on the files that are
consumed by this pickup. When you select this option you must then enter a filter pattern to
apply to consumed file names, and indicate if the filter acts inclusively (only pick up files that
have names that match the filter) or exclusively (ignore only files that have names that match the
filter and pick up all others).
specify otherwise.
size of files the exchange can handle.
l Maximum file per polling interval – The highest number of messages the system can
l Polling interval – The interval in seconds Interchange waits before polling for messages to
retrieve.


On this tab you configure a directory associated with an SFTP user account. The path begins from
the home directory of the SFTP account. Interchange places messages in these directories for the
back-end system to download.
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.
Modify an FTP (embedded) pickup or delivery

After you create an FTP (embedded) pickup or delivery, you can view and modify the fields that
define the object.
For related information, see the following chapters:
FTP (embedded) settings tab (pickup)

Pickup screen for this exchange. For a description of the fields you can view when you click this
link, see FTP (embedded) transport configuration on page 275.


FTP (embedded) settings tab (delivery)


l FTP user – The name of the user.
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.



system generates.
dabeed45_4cb.edi
z47e4120_4ce

page 253.


number to the new file in the format: filename_c4
page 253.
file.

the client side.

back-end application or resend messages to partners. Backup files are stored in \<install
accommodate.

l Maximum concurrent connections – (For partner trading delivery only.) The number of total
open connections Interchange can make to a partner. If you are operating in a cluster
are running. For example, if the value is 100 connections and there are 150 messages to send,
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.
l Retries – (For partner trading delivery only.) The number of times Interchange retries to
connect to the partner’s transport if the initial attempt to connect and send the message failed.
the client side.
copies of the messages it retrieves from applications or receives from partners.
commands. This field is available for both application and partner deliveries.

Modify an FTP (external) pickup or delivery

After you create an external FTP pickup or delivery, you view and modify the fields that define the
object.
FTP or FTPS settings tab (pickup and delivery)

l FTP Server – The network name of the FTP server.
l Select the file type – From the drop-down list, select the format of the files that are
transmitted over this delivery:
o Binary (default)
o ASCII - automatic line ending
o ASCII - user CR/LF
o ASCII - use LF only
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.


this, a certificate in a Community or Partner definition must be designated as the SSL certificate.
The server must support SSL. If this option is not selected, connections are not encrypted.
l Use Implicit SSL – Select this option if you want to use implicit SSL rather than explicit SSL
(which is the default mode). FTP supports two methods to accomplish security through a
sequence of commands passed between two computers. The sequence is initiated with explicit
(active) or implicit (passive) security.
o Explicit security – To establish the SSL link, explicit security requires the FTP client to issue a
specific command to the FTP server after establishing a connection. The default FTP server
port is used.
o Implicit security – Implicit security begins with an SSL connection as soon as the FTP client
secure connections. Not all FTP servers support implicit security. Check the documentation
for your server.

inbox directory. If connecting to a partner’s Interchange-embedded FTP server, use mailbox if
picking up. Leave the field blank if delivering.
If connecting to a partner’s Interchange-embedded FTP server, clear the check box.
with periods.
name:

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.


system generates.
dabeed45_4cb.edi
z47e4120_4ce

page 253.

page 253.
file.
File name security (external FTP servers only)

l Make output filenames safe for all FTP servers by prefixing them with a letter if
they start with numbers, and by applying the regular expressions in
filenamebeautifier.xml – (For external FTP servers only) Select this option to have
Interchange add a letter prefix to file names that begin with a numeral. This is for servers that
cannot process files with names that begin with a numeral.


If you select the consumption order option "Process by timestamp" on this tab, the software
automatically sets the value of this field to "1".
more information.


applies only to delivery exchanges using external FTP servers for picking up messages from the
back end or receiving messages from partners.

consume or ignore. Use conventional wildcard characters for file names or extensions or both.
rat, rot and rut.
case letter.
| Use the pipe character to separate multiple file name formats. For example,

specify otherwise.
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.

l Polling configuration:
o Maximum files per polling interval – The highest number of messages the system can
o Polling interval (seconds) – The interval in seconds Interchange waits before polling for
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.
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.

This setting applies to the following types of exchanges: FTP, SFTP, JMS, MQSeries, POP, X420,
X435, and Pluggable Server.
configured.
messages.


available.
running his receiving system, decrease the value.
integration.

plus the interval.
receipts have not been received as expected. Another control, re-sends, determines how many
more information.


applies only to delivery exchanges using external FTP servers for picking up messages from
consume or ignore. Use conventional wild card characters for file names or extensions or both.
rat, rot and rut.
case letter.

specify otherwise.

Manage users of embedded FTP servers

There are various places in the user interface where you can view user accounts associated with
embedded FTP servers. The separate areas reflect the three distinct types of accounts:
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.
View community FTP accounts

To view community FTP accounts, open the summary page for a community and click FTP users in
the navigation graphic at the top of the page. The FTP users icon displays only if an embedded FTP
has been added for a community.
View application FTP accounts

To view application FTP accounts, open the summary page for a community and click Application
delivery or Application pickup in the navigation graphic at the top of the page. Click Manage
application FTP users in the task list at the bottom of the page. The link displays only if an
embedded FTP p ickup or delivery has been added.
View partner FTP accounts

To view partner FTP accounts, open the summary page for a partner and click FTP users in the
navigation graphic at the top of the page. The FTP users icon displays only if FTP users owned by a
partner have been defined by a community for a community or partner embedded FTP exchange.
Lockout settings for FTP (embedded) server users

You can set the number of times an FTP user can attempt to connect with an invalid password to an
embedded FTP server before Interchange locks out the user. This is a safeguard against possible
efforts by unauthorized users to access the server.
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.

Set lockout rules

Use this procedure to set the lockout rules for an embedded FTP server. The rules apply to all FTP
users.

2. Click the Configure global transport settings task to open the global transport settings
page.
3. Select the Global FTP settings tab.
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.

To unlock a locked out user of an FTP (embedded) server, before the lockout interval expires:
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.
Programmatically submit via FTP (embedded) servers

The following is an example of a Java method to programmatically submit a message to Interchange
through an FTP (embedded) server.
/**
* 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

* subdirectory to identify the sender and receiver. This is

necessary for trading files that contain no
* sender/receiver information. On the trading side it wouldn’t be
necessary if the protocol (e.g. AS3)
* identifies the sender and receiver.
*/
private void submitFtp(byte[] message) throws IOException
{
// User/pw are both “integration”. Assumes 2 levels of msg attr
mapping under “out”: lev1=sender, lev2=rcvr
URL url = new URL
("ftp://integration:integration@localhost:5021/out/ed/anne”);
FtpURLConnection con = new FtpURLConnection(url);
OutputStream os = con.getOutputStream();
os.write(message);
os.close();
}
Modify an SFTP (embedded) pickup or delivery

After you create an SFTP pickup or delivery, you can view and modify certain fields that define the
object.
SFTP (embedded) settings tab (pickup)

o View settings for this embedded server – Click this link to open the Change this
embedded server screen for this exchange. This enables you to configure settings for the
screens described below. For a description of the fields you can view when you click this
link, see SFTP (embedded) server fields on page 453.
l Host used by partners – The fully qualified domain name or IP address your partners use pick
up messages from this exchange. When you export your community profile as a partner profile,
the host information becomes part of your exported partner profile.
You can change this field by clicking View settings for this embedded server (see above)
and changing the External host or IP address field. If your network uses a load balancer or
firewall, contact your network administrator for the correct value. Any change to this field affects
all delivery exchanges that reference the server.

SFTP (embedded) settings tab (delivery)

Pickup screen for this exchange. This enables you to configure settings for the screens
described below. For a description of the fields you can view when you click this link, see SFTP
(embedded) transport configuration on page 286.
l Host used by partners – The fully qualified domain name or IP address your partners use to
send messages to this delivery exchange. When you export your community profile as a partner
profile, the host information becomes part of your exported partner profile.
You can change this field by clicking View settings for application (see above) and
l Preserve original filenames – Select this option if you want original file names to be
preserved when Interchange delivers messages.
o Overwrite duplicate filenames – An option when you choose to preserve original file
names. If duplicate file names are detected, Interchange overwrites the existing file.
o 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 SFTP, the appended number is hexadecimal and has the format:
filename_c4.
name instead of using the original name.
When this option is selected, files are given arbitrary names. The names always have less than 30
characters and often have less than 20 characters.
o dabeed45_4cb.edi
o z47e4120_4ce

Directories tab (pickup)

On this tab you configure pickup directories associated with SFTP user accounts. Paths begin from
the partners or for the back-end system to download.
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.
Directories tab (delivery)

On this tab you configure delivery directories associated with SFTP user accounts. Paths begin from
the partners or for the back-end system to upload.
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.

the client side.
specify otherwise.
size of files the exchange can handle. If Interchange receives a file larger than the maximum, the



the client side.
specify otherwise.
commands.
Modify an SFTP (external) pickup

After you create an external SFTP pickup, you can view and modify the fields that define the object.
An external SFTP pickup resides outside of Interchange.
SFTP settings tab

l Current public key – The RSA or DSA public key for the SFTP server. Interchange uses the key
to authenticate the server.
l New public key – Select this check box to display options for designating a new RSA or DSA
public key for the SFTP server. Interchange uses the key to authenticate the server. If the server
is modified to use a new public-private key pair, the public key must be updated.
file path. See Public-private key and password authentication on page 292.

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
inbox directory.
with periods.
name:
retrieved.

Filenames tab
application to process binary messages based on their file names. This field applies to both
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
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.
o dabeed45_4cb.edi
o z47e4120_4ce
Advanced tab
available.

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
integration.
plus the interval.
l Read timeout (seconds) – How long in seconds that Interchange waits to read data from the
delivery exchange before terminating the connection.
available for production delivery exchanges.

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.
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:
rat, rot and rut.
case letter.



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.

configured.
exchanges that poll for messages.
transport servers.

Lockout settings for SFTP (embedded) users

You can set the number of times an SFTP user can attempt to connect with an invalid password to
an embedded SFTP server before Interchange locks out the user. This is a safeguard against possible
Set lockout rules

Use this procedure to set the lockout rules for an embedded SFTP server. The rules apply to all SFTP
users.

2. Click the Configure global transport settings task to open the Configure global transport
settings page.
3. Select the Global SFTP settings tab.


Use this procedure to unlock a locked out user of an embedded SFTP server before the lockout
interval expires.
1. Click Delivery exchange in the navigation graphic at the top of a community summary page.

2. Click an embedded SFTP transport to open its maintenance page.
Manage users of embedded SFTP

There are various places in the user interface where you can view user accounts associated with
embedded SFTP servers. The separate areas reflect the three distinct types of accounts:

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.
View community SFTP accounts

To view community SFTP accounts, open the summary page for a community and click SFTP users
in the navigation graphic at the top of the page. The SFTP users icon displays only if an embedded
SFTP server has been added for a community.
View integration SFTP accounts

To view integration SFTP accounts, open the summary page for a community and click
Application delivery or Application pickup in the navigation graphic at the top of the page.
Depending on which icon you click, a page displays listing application deliveries or pickups. Click
Manage integration SFTP users in the task list at the bottom of the page. The link displays only
if an embedded SFTP integration exchange has been added.
View partner SFTP accounts

To view partner SFTP accounts, open the summary page for a partner and click SFTP users in the
navigation graphic at the top of the page. The SFTP users icon displays only if SFTP users owned by
a partner have been defined by a community for a community or partner embedded FTP exchange.
Modify an HTTP transport

The following topics document the fields on the maintenance pages for HTTP transports.
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.
Embedded HTTP settings tab

l Embedded HTTP server – A link is provided to view the settings for a particular embedded
server or for the global embedded server. If a particular server, you can change servers.
l Local URL – This URL describes 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.
l URL used by partners – This is the URL your partners use to send messages to this delivery
exchange. 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. This URL should include the fully qualified host name or IP address, port
number and path where partners must connect to send messages.
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.
Advanced tab (community)

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.
specify otherwise.
Restrict maximum file size for this transport – Optionally lets you specify the maximum size of
files a transport can handle.

HTTP or HTTPS settings tab (partner)

l Clients must use SSL to connect to this server – Select this to have Secure Sockets Layer
a certificate in a Community or Partner definition must be designated as the SSL certificate. The
server must support SSL. If this is not selected, connections are not encrypted.
Interchange server. This is not applicable to integration exchanges.
Advanced tab (partner)

available.
The default value is suitable in almost all cases. However, if a partner says your Interchange is
If sending messages to Transfer CFT via PeSIT (PeSIT), the value in this field must be less than
the CFTTCP setting in Transfer CFT.
integration.

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.
plus the interval.
l Response timeout (seconds) – The limit in seconds that Interchange waits for the delivery
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.

l Enable HTTP chunking – 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.
If you enable chunking because of large messages, you should also request that receipts be sent
over an asynchronous connection. See the chapter on collaboration settings for details.
l Attempt restarts – Select this 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.
l Enable use of 102-processing – This option is available to ensure 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
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.

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
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.
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.


specify otherwise.
Modify a staged HTTP transport

The following topics document the fields on the maintenance pages for the staged HTTP web
transport.
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.
HTTP settings tab

HTTPS settings tab


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
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.
Note that in the last case, the 200 OK response also will include the receipt if


l Response timeout (seconds) – The interval, in seconds, that Interchange waits for the
delivery exchange to respond to a request before terminating the connection.
otherwise.
This control is available only for transports used for picking up messages from the back end or
This option is available for application and trading pickup exchanges that poll for messages.

transport servers.
Modify a JMS pickup or delivery

After you create a JMS pickup or delivery, you can view and modify certain fields that define the
object.
JMS settings tab (pickup and delivery)

configured.
configured.



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:
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.

l Receive time out (seconds) – If your JMS provider is slow to respond to the receive request
by Interchange, increase the response interval. The default value of 0 is acceptable in the case of
most JMS providers. However, if unacceptable for your JMS provider, use trial-and-error to
determine a workable interval between 1 and 32767 seconds.
select it.
otherwise.


configured.

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 following are all possible fields for polled and listener modes.


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.
select it.


otherwise.
l Post Processing script – The full path to an executable file that contains post-processing
commands.
Modify an MLLP trading pickup

After you create an MLLP trading pickup, you can view and modify fields that define the pickup.

server. See MLLP (embedded) fields on page 608.


embedded server name or connection paramters, click View settings for this embedded
From address tab


To address tab

EDI Splitter tab


Schedule tab
Advanced tab
Modify an MLLP trading delivery

After you create an MLLP trading partner delivery, you can view and modify fields that define the
delivery.
MLLP settings tab

l MLLP server – Network address of the MLLP server.
l Port – Access port of the MLLP server.


Schedule tab
Advanced tab
available.
triggering retries.

plus the interval.
l Connect timeout (seconds) – Interval, in seconds, Interchange waits for a connection to the
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
(hexadecimal 1C). The default value is the customary MLLP value. You must use the same values
l Acknowledgement expected from the target MLLP server – Select this option to keep
the connection with the MLLP server open while waiting for acknowledgement.
commands.
Modify an MQSeries pickup or delivery

After you create an MQSeries pickup or delivery, you can view and modify certain fields that define
the object.

IBM MQSeries settings tab (pickup and delivery)

l MQSeries connection type:
o Client connection – select this option to use a channel connection, on the local machine
l MQSeries server – The fully qualified domain name or IP address of the MQSeries host.
l Multi-instance queue manager – In the case where you have a multi-instance MQSeries
queue manager, you can select this option, and then select the MQSeries manager instance to
use as the standby server.
l Port – The port where the application listens for incoming documents. The default is 1414.
l Channel – The name of the communications channel.
l Queue name – The name of the MQSeries queue that receives incoming documents.
l Queue manager – The name of the MQSeries queue manager.
l Character set – The character set used by the queue manager. This number should match the
number used by the queue manager. The default is 819.
l Convert data – Select this option to convert the characters set of messages received from a
queue to the set specified in the Characters set field. Clear the check box to turn off data
conversion. This setting does not apply to messages outbound to a queue.
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.


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.

name)
SHA
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.

otherwise.

configured.
transport servers.

engine is over running his receiving system, decrease the value. (This advice does not apply to

Tracker.
chapter.
otherwise.
Modify a pluggable server pickup or delivery

After you create a pluggable server pickup or delivery, you can view and modify certain fields that
define the object.
Pluggable server settings tab (pickup)

l Server name – This field displays the name of the pluggable server.
l Server class - This field displays the server class of the pluggable server.
l Add custom settings for this pluggable server – Enter name/value pairs as custom
parameters.

Pluggable server settings tab (delivery)

application to process binary messages based on their file names. This field applies to
community integration delivery exchanges and partner delivery exchanges only.
original file names. If duplicate file names are detected, the trading engine appends a number to
the new file. For most transports, the appended number is consecutively numbered. For FTP and

name instead of using the original name. This field applies to community integration delivery
exchanges and partner delivery exchanges only. When selected, files are given arbitrary names.
The names always have less than 30 characters and often have less than 20 characters.
o dabeed45_4cb.edi
o z47e4120_4ce



commands.

l Maximum messages per connection – Default = 1. 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 effects load balancing. Depending on your message volume and
the load on each node, this value can be modified to control the overhead associated with
reconnecting to the transport server.
configured.

l Allow SFTP clients to add, remove subdirectories –m Enable subdirectory management
on the client side.

specify otherwise.
size of files a the exchange can handle.
Modify an SMTP (embedded) transport

After you create an embedded SMTP pickup or delivery, you can view and modify the fields that
define the object.
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
SMTP (embedded) settings tab (pickup only)

l Embedded SMTP server – A link is provided to view the settings for a particular embedded
server or for the global embedded server.
l Host – The fully qualified domain name of the computer on which the embedded SMTP server
runs. This field cannot be changed.
l Host used by partners – The email address that partners should use to access your embedded
SMTP server. Interchange maps this email address to the correct delivery exchange.
While this field is visible on the delivery exchange maintenance page, you can only edit it on the
embedded server maintenance page. See Modify a global embedded SMTP server on page 440
or SMTP (embedded) configuration on page 459.
l Email address – The email address that the remote partner uses to send messages to your local
community.
Accounts tab (pickup only)

Select an option for authorizing the reception of email from a sender:

l Identify the sender using partner delivery defined e-mail addresses - (Default) When

you select this option, Interchange consumes email on this transport only if the sender email
address is well-defined and configured in a partner SMTP delivery.
l Identify the sender using partner associated e-mail accounts – Select this option if
you want to create a list of authorized sending-partner email accounts. Use this feature, for
example, if you want this pickup to allow multiple members of a remote partner organization to
send email, without a validation of the complete sender email address.
You can create the list of authorized senders by selecting accounts that already exist on pre-
existing partners, or you can enter accounts directly to the list for this pickup.
The local element of the email address is case sensitive. For example,
myaccount@organization.com is evaluated as a different address than
MyAccount@oragnization.com.
See the rules sections below, for additional configuration details.
Rules for the use of wildcard characters

The list of authorized senders can include entries composed with wild-card characters.
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".
Rules for sender identification on a single pickup

If a single pickup consumes email from an external POP3 server, the Interchange partner (from the
list of authorized partners) with the most specific rule is selected first.
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.
Rules that apply on multiple trading pickups

When two or more email trading pickups point to the same external POP3 server, the same email
account or pattern can be associated with different Interchange Partners. For example, one pickup
may indicate that the a@a.com email account resolves to PartnerA, while another may specify that

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.
Advanced (pickup only)

l Include attachments only – This oprion is applicable when you have partners who send
messages using a mail client such as Microsoft Outlook. The control lets you eliminate
extraneous message fragments. This control is available under the generic email message
protocol, but not AS1.
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 option causes the incidental MIME body parts to be ignored while preserving the
important document attachments.
size that the pickup c an handle.

SMTP settings tab (delivery only)

l Email address – The email address for sending messages to a partner.
l Use the global external SMTP server – Selecting this means the system’s external SMTP
server is used to send messages to the partner. A link is provided to configure the system’s
external SMTP server. See Configure the global external SMTP server on page 60.
l Use a partner-specific SMTP server – Selecting this means you can specify an external
SMTP server to send messages to the partner that is different from the system’s external SMTP
server.
l SMTP server – Enter an SMTP server for sending messages only to this partner. Enter a fully-
qualified domain name or IP address for the server. If you leave this field blank, the system
inserts its external SMTP server.
l Port – The default port for sending mail is 25.
l This server requires a user name and password – Select this if a user name and password
are required to connect to the server and then complete the name and password fields. SMTP
servers usually do not require user names and passwords for sending.
Advanced tab (delivery only)

l Retries – This is the number of times Interchange retries connecting to the partner’s transport if
for triggering retries.

plus the interval.
copies of the messages it retrieves from back-end applications or from partners.
specify otherwise.
commands. This field is available for community integration delivery exchanges and partner
trading delivery exchanges.

Modify an SMTP/POP (external) transport

After you create an external SMTP pickup or delivery, you can view and modify the fields that define
the object.
SMTP settings tab (delivery only)

l Email address – The email address for sending messages to a partner.
l Use the global external SMTP server – Selecting this means the system’s external SMTP
server is used to send messages to the partner. A link is provided to configure the system’s
external SMTP server. See Configure the global external SMTP server on page 60.
l Use a partner-specific SMTP server – Selecting this means you can specify an external
SMTP server to send messages to the partner that is different from the system’s external SMTP
server.
l SMTP server – Enter an SMTP server for sending messages only to this partner. Enter a fully-
qualified domain name or IP address for the server. If you leave this field blank, the system
inserts its external SMTP server.
l Port – The default port for sending mail is 25.
l This server requires a user name and password – Select this if a user name and password
are required to connect to the server and then complete the name and password fields. SMTP
servers usually do not require user names and passwords for sending.
Advanced tab (delivery only)


plus the interval.
l Connect timeout (seconds) – Interval in seconds Interchange waits for a connection to the
specify otherwise.

POP settings tab (pickup only)

l POP server – The name of the POP server that Interchange polls for messages sent by your
partner. This must be a fully qualified domain name or IP address.
l Port – The POP server port. Default = 110
l User name – The user name for connection to the POP server.
l Change password – Select this option to change the password of the user who connects to
the POP server. Then complete the password fields.
l Authentication type – Select the authentication type to use for the POP server:
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.
Accounts tab (pickup only)

Select an option for authorizing the reception of email from a sender:
l Identify the sender using partner delivery defined e-mail addresses - (Default) When

you select this option, Interchange consumes email on this transport only if the sender email
address is well-defined and configured in a partner SMTP delivery.
l Identify the sender using partner associated e-mail accounts – Select this option if
you want to create a list of authorized sending-partner email accounts. Use this feature, for
example, if you want this pickup to allow multiple members of a remote partner organization to
send email, without a validation of the complete sender email address.
You can create the list of authorized senders by selecting accounts that already exist on pre-
existing partners, or you can enter accounts directly to the list for this pickup.
The local element of the email address is case sensitive. For example,
myaccount@organization.com is evaluated as a different address than
MyAccount@oragnization.com.
See the rules sections below, for additional configuration details.
Rules for the use of wildcard characters

The list of authorized senders can include entries composed with wild-card characters.
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".
Rules for sender identification on a single pickup

If a single pickup consumes email from an external POP3 server, the Interchange partner (from the
list of authorized partners) with the most specific rule is selected first.
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.
Rules that apply on multiple trading pickups

When two or more email trading pickups point to the same external POP3 server, the same email
account or pattern can be associated with different Interchange Partners. For example, one pickup
may indicate that the a@a.com email account resolves to PartnerA, while another may specify that
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.
Advanced tab (pickup only)

may be longer than the interval allowed by your operating system (OS). For example, some
Windows platforms by default allow a maximum timeout of 20 seconds. The actual connect
timeout interval is the lesser of the OS timeout and the value set in Interchange.
If you handle files larger than 200 megabytes, it is recommended to set this to a minimum of
150 seconds (2.5 minutes), but preferably to 300 seconds (5 minutes).
l Include attachments only – This option is applicable when you have partners who send
messages using a mail client such as Microsoft Outlook. The control lets you eliminate
extraneous message fragments. This control is available under the generic email message
protocol, but not AS1.

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.
specify otherwise.
configured.
messages.

transport servers.
Modify a Web Services API client application pickup or

delivery
This topic describes the fields on the maintenance pages for Web Services API client pickups and
deliveries.
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.
Web Services API client settings tab

URL
The URL Interchange uses to post messages to a back-end system.
Advanced tab (Web Services API client)

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.
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
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.
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 entire payload contents
Send the payload through this transport. This option is only for integration delivery.
Send the payload URL only
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.

Response timeout (seconds)
Time long in seconds Interchange waits for the delivery exchange to respond to a request
before terminating the connection.
Enable HTTP chunking
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.
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.
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.

Enable use of 102-processing
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.
Back up the files that go through this transport
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.
specify otherwise.
Post-processing script
The full path to an executable file that contains post-processing commands.
Web Services API server settings tab

Embedded Web Services API server
Click the link to display the settings for the global Web Services API server.
Advanced tab (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.
Restrict maximum file size for this transport –
Optionally lets you specify the maximum size of files a transport can handle.
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
Modify a Web Services trading pickup

After you add a Web Services trading pickup to a community, you can view and modify pickup
characteristics.
Prerequisite
Add a Web Services trading pickup on page 326
Procedure
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.
Make this the default delivery
Select this option if you have multiple exchanges and you want this pickup to be selected
for the community d efault pickup.
HTTP (embedded) settings tab

Local URL
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.
URL used by partners
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.
Web Services user
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.

Inline processor tab

Use the fields of this tab to implement custom processing logic as a user-defined Java class. The
processing can be selectively applied at runtime to inbound or outbound messages.
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.
WSDL 2.0 file
See WSDL file field description above.
Header
Generate new WSDL
Use this command to open the WSDL configuration wizard and define a new service.
Parse SOAP headers into message metadata
Select this option if you want to SOAP headers to be carried as metadata attributes with the
message.

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.
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.
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 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.

Timeout to apply for out of sequence messages (seconds)
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
Restrict maximum file size for this transport
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.
Modify a Web Services trading delivery
Prerequisites
Add a Web Services trading partner delivery. For details, see Add a Web Services trading delivery on
page 322.
Procedure
page.
2. Select the partner that represents your Web Service partner.
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.
Make this the default delivery
When you have multiple deliveries, one of the deliveries must be designated as the default
delivery.
HTTP settings tab

URL
The partner's web service URL.
This server requires a user name and password
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.
This proxy requires a user name and password
Select this option if the proxy server requires a user name and password. Then complete
the fields: User name, Password, Confirm password.
Inline processor tab

Use the fields of this tab to implement custom processing logic as a user-defined Java class. The
processing can be selectively applied at runtime to inbound or outbound messages.

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.

Enable HTTP chunking
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.
Enable use of 102-processing
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.
Modify a WebDAV pickup or delivery

The following are the fields on the maintenance pages for the WebDAV transport.
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.
Embedded WebDAV settings tab (community)

l Embedded HTTP or HTTPS server – A link is provided to view the settings for the embedded
server. You also can change servers.
l Local URL – This URL describes 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.
l URL used by partners – This is the URL your partners use to send messages to this delivery
exchange. When you export your community profile as a partner profile, the URL becomes p art
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. This URL should include the fully qualified host name or IP address, port
number and path where partners must connect to send messages.
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.

Directories tab (community)

Aside from using this tab, you can manage WebDAV users owned by communities or partners by
clicking WebDAV users in the navigation graphic at the top of a community or partner summary
page.
l Accounts owned by this community – A list of the users and associated directory paths

belonging to this community. A specific combination of user and directory can be associated
with only one exchange. You can add, change or delete users.
l Accounts owned by partners – A list of the users and associated directory paths belonging to
partners. A specific combination of user and directory can be associated with only one
exchange. You can add, change or delete users.
l Specify what to do when partners upload messages to subdirectories of the
directories listed above
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.
Directories tab (partner)

Aside from using this tab, you can manage WebDAV users owned by communities or partners by
clicking WebDAV users in the navigation graphic at the top of a community or partner summary
page.
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.

otherwise.


l Retries – The number of times Interchange will retry connecting to the partner’s transport if
for triggering retries.
Tracker.

chapter.
otherwise.
commands. This field is available for community application and partner delivery exchanges.
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

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.
Work with routing IDs

l Add a routing ID on page 409
l Modify a routing ID on page 410
If you use the ebXML message protocol, see Routing ID for ebXML on page 561 for special
requirements.
Add a routing ID
Add a community routing ID

display the Communities page.
2. From the list of communities, click the name of a community, to display the Summary page for
that community.
3. In the graphic map at the top of the screen, click the Routing IDs icon to open the Routing
IDs page.
4. In the Add a routing ID section, complete the fields:
l Routing ID – Enter a routing ID. 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.
l Party ID type – 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. For more information, see Routing ID for ebXML on page 410.
5. Click Add.
Add a partner routing ID

partner.
IDs page.


spaces.
l ebXML party ID type or cXML domain – 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 410.
5. Click Add.
Routing ID for ebXML

When setting up a community for ebXML, the routing ID must be set up in one of two ways:
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.
Modify a routing ID
After you create a Community or Partner, you can:
l Add additional routing IDs
l Delete routing IDs
Add a community routing ID

that community.
3. In the navigation graphic at the top of the screen, click the Routing IDs icon to open the
Routing IDs page.

Routing IDs

spaces.
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.
Add a partner routing ID

partner.
IDs page.
spaces.
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.


If you trade with the same partner using both ebXML and any other message protocol, the
Message metadata and attributes

Metadata are information about messages handled by Interchange. Metadata can be used to trigger
processing actions within Interchange. Interchange also can attach metadata to messages routed to
back-end integration systems.
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:
l Searching for objects – The search pages 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 configure a service, for example, to run only if a specific
attribute/value is detected. For example, if the sender is JohnSmith, then the message is routed
to a particular Partner, such as XYZPlumbing. In another 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.
Attribute templates are reusable. You access them from a link on the associated object page. After
you create a template, it is automatically displayed on the attributes tab for that object. You flag the
Attribute as either:
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.
Metadata for record file management

You use metadata attributes to control how Interchange handles the file records that are transported
in messages.
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.
Local and virtual attributes

Metadata attributes for file records are classed as either local or virtual attributes:
l Local attributes (for example, LocalFileRecordFormat) apply to document files stored on
the Interchange file system. Local attributes describe how file records are structured and in what

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
LocalFileCharSet l ASCII Name of the character set used in the

local file.
l EBCDIC
l Free
LocalFilePaddingChar l 0x00…0x7F Padding character used in the local file.
LocalFileRecordFormat l FIXED_ Format of the local file record.

BINARY To turn off transcoding, set this value to
l VARIABLE_ OCTET_STREAM
BINARY
l FIXED_TEXT
l VARIABLE_
TEXT
l OCTET_
STREAM
LocalFileRecordLength l Length in Size (for fixed length) or maximum size

bytes (for variable length) of the file record.
VirtualFileCharSet l ASCII Name of the character set for the file

l EBCDIC flowing over the network
l Free
VirtualFilePaddingChar l 0x00…0x7F Padding character used in the file over

the network

Attribute Value Description
VirtualFileRecordFormat l FIXED_ Format of the virtual file record.

BINARY To turn off transcoding, set this value to
l VARIABLE_ OCTET_STREAM
BINARY
l FIXED_TEXT
l VARIABLE_
TEXT
l OCTET_
STREAM
VirtualFileRecordLength l Length in Size (for fixed length) or maximum size

bytes (for variable length) of the file record.
message.attributes.template l Message Indicates the Message Attribute

.in/out Attributes Template applied on reception/ on
Template sending
name
Add a community attribute

1. In the user interface, from the Trading configuration menu, select Manage trading
that community.
3. In the graphic map at the top of the page, click the Properties icon to open the Properties
page.
4. From the task list at the bottom of the page, click Manage partner and community
attributes template. This type of attribute works for both partners and communities and you
can edit it in either location.
5. Click Add new attribute field.
6. Complete the following fields:
l Name — Enter a name for this attribute. This name displays in the list on the Manage
partner and community attributes template page and on the Properties pages for partners
and communities.
l Make this a required attribute — Select this option if the attribute is to be included on
all exchanges with this partner. You must enter a value for processing on every partner
record if you select this check box. If a Partner Summary does not contain a particular

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 a partner attribute

partner.
3. In the graphic map at the top of the page, click the Properties icon to open the Properties
page.
4. From the task list at the bottom of the page, click Manage partner and community
attributes template. This attribute works for both partners and communities and you can
edit it in either location.
5. Click Add new attribute field.
6. Complete the following fields:
l Name — Enter a name for this attribute to identify it in the user interface.
l Make this a required attribute — Select this option if the attribute is to be included on
all exchanges with this partner.
l Make available for searching — Select this option if the attribute is to be a valid search
criteria for partner.
l Make available for message processing – Select this option if the attribute is available
as a criteria for conditional message processing.

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 or delete message attributes
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.
1. Select S ystem management > Manage message attributes to open the Message

attributes page. The page lists any message attributes that have been added.
2. The Name is what Interchange uses. The Friendly name is the display name for the user
interface.
3. Add an attribute by selecting one from the available pool of attributes or by typing your own
custom attribute.
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

Message attributes templates are groups of attribute-value pairs. Templates are a way to share and
reuse standard and custom attributes. Attribute is the term for metadata used within Interchange.
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.
Manage message attributes templates
Add a message attributes template

Use this procedure to add a message attributes template to Interchange. A template is a collection of
attribute-value pairs. See Message attributes templates on page 424.
1. Select System management > Manage message attributes templates to open the

Message attributes templates page.
2. Click Add a message attributes template.
3. Type a name for the template and, optionally, a description.
4. Select an attribute to add to the template from the Name field drop-down list.
If the attribute you want to add is not listed, click Add attribute, select an attribute from the
drop-down list and click Add.
5. Type a value for the selected attribute. This can be a fixed value or a value assigned at runtime.
For example, assign a value by referencing another attribute from the collaboration message or
the template. Suppose A stands for attribute. In the collaboration message A1= foo and in the
template A2 = %A1% and A3 = %A2% bar. This leads to A2 = foo and A3 = foo bar.

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.
Duplicate a message attributes template

To save data entry time, you can duplicate a message attributes template and then edit the template.

2. Select the checkbox next to the template you want to copy.
3. In the Select an action box, select Duplicate. Then click Selected.
A new instance of the template appears in the list with - Copy appended to the name.
4. Click the new template and change the name. Then, change the message attributes as needed:
l Use the Add a message attribute to template area to add new attribute-value pairs.

l Click Delete next to a message attribute to remove it.
5. Click Save to save the template and its attribute-value pairs.
Export and import a message attributes template

You can export one or more message attributes templates to a single xml file for later import. You
can also export a single message attributes template from the edit page of the template by clicking
Export this template.

2. Select the checkbox of one or more message attributes templates to export.
3. In the Select an action box, select Export.
4. Click Selected to export the selected templates, or All to export all templates.
5. If you are exporting all templates, click OK to verify you want to export the templates to a
single xml file.
6. Select to open or save the file, and then click OK. You must save the file to later import the file.

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.

2. Select Import a message attributes template file to start using the wizard.
3. On the Enter profile path page, complete the File name field by browsing to select the xml file
to import.
4. Choose one of the following:
l Replace the existing message attributes templates – This selection overwrites
templates with the same name.
l Ignore duplicate message attributes templates during import – This selection will
not overwrite templates with the same name and will import only those templates from the
xml file with unique names.
5. Click Next. The import results display and identify the templates imported or ignored.
6. Click Finish.
Delete a message attributes template

You can delete one or more message attribute templates at once. You can also delete a single
message attributes template from the edit page of the template by clicking Delete this template.
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.

2. Select the checkbox next to one or more message attributes templates to delete.
3. In the Select an action box, select Delete.
4. Click Selected to delete only the selected templates, or All to delete every template.
5. Click OK to verify you want to delete the selected template(s).
Export and import profiles

For ease of exchanging profile data, you can export a community profile and public key certificate
to an XML file and give it to partners who use Interchange 4.2.x or later. For partners who use other
interoperable trading software, consult with them on the data they require of you to establish
trading relationships.

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).
Export a community as a partner profile

Before exporting a community profile as a partner profile, make sure the profile has been completely
configured. On the community summary page, click Export this community as a partner
profile at the bottom of the page. Save the file to a directory of your choosing. If you have
associated a certificate with the profile, the certificate and public key are exported with the profile.
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.

Export a partner profile

To export a partner profile to an XML file, click Partners on the toolbar and then select a partner. At
the bottom of the partner summary page, click Export this partner's profile.
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.
Import a partner profile

Upon receiving a profile from a partner, make sure the profile file is accessible on your file system.
Go to the partners area of the user interface and click Add a partner. Then click Import a
partner profile from a file. Point the browser to the file to import, select a community for the
partner, and click Finish.
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.

Automatic profile imports

Interchange on its own imports community or partner profiles written to a certain system directory.
These must be profiles that have been exported from Interchange or are compatible (see Create
profiles outside the application on page 430).
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.
Note If you have exported a community and its partners to a backup file ( Back up a community

on page 854), do not use the autoImport directory to import the file. Interchange rejects
the file. See Import a backed-up community and its partners on page 855 for the correct
procedure.
The system also has some profile staging directories, as shown here:
\profiles \autoImport \rejected

\community
\backup
\partner
\community
\staged
\partner
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

Create profiles outside the application

In addition to using Interchange to create, export and import profiles, you can generate profiles
outside of the application by using the profiles schemas. For example, you can generate profiles
using your own partner management system and import them to Interchange.

Embedded transport
servers 9
Interchange provides embedded servers with some delivery exchanges. Interchange provides these
transport servers so that you do not require a connection to an external server for trading messages.
Some embedded servers also are available for exchanging messages with back-end systems.
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
Pages and fields

l Global embedded HTTP server on page 437
l Modify a global embedded SMTP server on page 440
l Global embedded Web Services API server on page 442
l User interface embedded servers on page 443
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

9 Embedded transport servers
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
Types of embedded servers

The following sections describe the types of embedded servers. See Usage summary of embedded
servers on page 434 for a quick-reference table of functionality for embedded servers.
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
Global and community-specific servers

When you define HTTP and SMTP delivery exchanges for a community, you can choose to use the
global server, which can be shared by any community. Alternatively, you can define a community-
specific server on a new port. Typically, the global server is the best choice.
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.
FTP and SFTP servers

These servers use a slightly different model than the HTTP and SMTP servers. They are never tied to
a particular community. Furthermore, they can host outbound exchanges for partners in addition to
inbound exchanges for communities. An FTP server can be used in either a plain context (FTP) or a

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.
ODETTE FTP servers

ODETTE FTP servers have a one-to-one relationship with delivery exchanges. For this reason, there is
no global embedded ODETTE server. Each time you add an OFTP exchange, you also define a new
server instance on a new port. This means OFTP servers cannot be shared by multiple communities.
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.

Servers for the user interface

There are two embedded servers available for running the user interface. The default HTTP
embedded server enables users to log on to the UI via HTTP. An HTTPS server is available if you
want users to connect to the UI by a more secure method.
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.
Usage summary of embedded servers

The following table provides a quick-reference summary of functionality for embedded servers.
Server Appli- Comm- Partner SSL Comm- Part- Delivery

cation unity out- or unities ners exchange
ex- in- bound TLS can can deter-
changes bound share share mined by
Global HTTP no yes no no yes n/a HTTP URL
Commun- no yes no yes no n/a HTTP URL

ity-specific
HTTP
Web Services yes no no no n/a n/a HTTP URL

API
MLLP yes yes no yes no n/a one-to-one

relationship
between
servers and
exchanges
defined by
MLLP URL
Global SMTP no yes no no yes n/a email address

Server Appli- Comm- Partner SSL Comm- Part- Delivery

cation unity out- or unities ners exchange
ex- in- bound TLS can can deter-
changes bound share share mined by
Community- no yes no no no n/a email address

specific SMTP
FTP yes yes yes yes yes yes user account

and
subdirectory
SFTP yes yes yes yes yes yes user account

and
subdirectory
OFTP no yes yes* yes no n/a one-to-one

relationship
between
servers and
exchanges
PeSIT yes yes yes yes no no one-to-one

relationship
between
servers and
exchanges
Pluggable yes yes no n/a yes no Custom

server configuration
required
* 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.
Manage embedded servers

After setting up an exchange that uses an embedded server, you can change the server’s settings.
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.
Types of embedded server pages

Your software license determines what version of the embedded server page displays in the user
interface.
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.

UI navigation for embedded servers

To open the embedded servers page, do one of the following:
l Select System management > Manage embedded servers on the toolbar.

l Click Trading configuration on the toolbar. On the Communities page, click the link near the
bottom named Manage all embedded servers.
l Click System management on the toolbar. On the System management page, click the link
near the bottom named Manage embedded servers.
Another path to perform embedded server maintenance is to open a community summary page and
click the link near the bottom named Change an embedded transport server. This opens a
page that lists all servers used by that community only.
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.
Global embedded HTTP server

The global embedded HTTP server is available after a community adds an HTTP transport for
receiving messages from partners. Communities can share it. You can change the server’s port and
advanced options.
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.
Port – The port on which the server listens for connection requests.
DMZ ports tab

Note This tab displays in the user interface only if your software license enables Secure Relay
DMZ nodes. The tab only applies to servers used for trading and not integration.
l Enable DMZ port forwarding –Select this check box if you want the external firewall or load

balancer to send inbound connections to Secure Relay DMZ nodes rather than directly to
embedded servers in the protected network.
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 security termination in DMZ – Select this check box to have various security

functions performed in the DMZ. If connections are via SSL, the secure connection is terminated
at the router agent in the DMZ. For delivery exchanges that require a user name and password to
connect (for example, FTP, SFTP, WebDAV), the router agent authenticates the user.
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.
o 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 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.
l Restartable minimum size (KB) – 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 kilobytes. The system only resumes transfers of files that meet this minimum. The
system starts over the transfer of smaller files whose processing is interrupted.
l 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.
Lockout settings for cXML (embedded

HTTP) users
You can set the number of times a cXML user can attempt to connect with an invalid password to an
embedded HTTP server before Interchange locks out the user. This is a safeguard against possible

Set lockout rules

Use this procedure to set the lockout rules for an embedded HTTP server. The rules apply to all cXML
users.

settings page.
3. Select the Global cXML settings tab.

Use this procedure to unlock a cXML user who is locked out of an embedded server before the
lockout interval expires.

2. Click the embedded server that the cXML user wants to connect to, to open the server
maintenance page.
Modify a global embedded SMTP server

The global embedded SMTP server is available after you add an SMTP transport for receiving
messages from partners to a community. Communities can share this transport. You can change the
server’s port and advanced options.
To change settings:

embedded servers.

Settings tab
l Host – The fully qualified domain name of the computer on which the embedded server runs.
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.
DMZ ports tab

DMZ nodes. The tab only applies to servers used for exchanges with trading partners and
nor for exchanges with back-end applications.
l Enable DMZ port forwarding – Select this check box if you want the external firewall or load

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

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
Set the system property to permit EDI

processing
6. Click Add.
Global embedded Web Services API server

The global embedded Web Services API server is available after a community adds a Web Services
API server application pickup or delivery. Communities can share it. You can change the server’s
port and advanced options.
To change settings:

embedded servers.
For information about how to configure the server for use in trading, see Web Services API pickup
and delivery configuration on page 200.
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.
Advanced tab
l Read timeout (seconds) – How many seconds of inactivity to allow before Interchange

terminates the connection.
User interface embedded servers

There are two embedded servers for connecting to the user interface from browsers. In use by
default is the embedded HTTP server. There also is an available HTTPS server.
The UI embedded servers are displayed on the page for managing all embedded servers.
To change settings:

embedded servers.
The server names are CnHttpServer and CnHttpsServer. If you click a server name, the page for
configuring the UI connection displays. See Configure UI connection on page 56 for how to switch
from HTTP to HTTPS.

HTTP (embedded) fields

An embedded HTTP server is available after a community adds a delivery exchange that uses an
embedded HTTP server other than the global server. You can change the server’s settings and
advanced options.
To change settings:

embedded servers.
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.
The following display only for an HTTPS server.
l This server requires client authentication – Select this to use the partner’s certificate to

authenticate the partner when the partner connects to the server.

l Add an SSL server certificate or SSL server certificate – An HTTPS server requires an SSL

certificate. If the server has a certificate, the name of the certificate is displayed. You can click
the certificate link to open a details page, where you can export the certificate to a file. If the
server does not have an SSL certificate, you are prompted to provide one.
DMZ ports tab



Advanced tab

l Restartable minimum size (KB) – 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 kilobytes. The system only resumes transfers of files that meet this minimum. The
system starts over the transfer of smaller files whose processing is interrupted.
l 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.
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.
listed.
digest algorithm.
FTP (embedded) fields

An embedded FTP server is available after a community adds a trading or application delivery
exchange that uses an embedded FTP server. You can change the server’s settings and advanced
options.

To change settings:

embedded servers.
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.


authenticate the partner when the partner connects to the server. This field displays only if you
have added an SSL certificate for the server.
l Use implicit SSL – Select this if you want to use implicit SSL rather than explicit SSL, which is
the default mode. FTP supports two methods to accomplish security through a sequence of
commands passed between two computers. The sequence is initiated with explicit (active) or
implicit (passive) security.
o Explicit security. To establish the SSL link, explicit security requires the FTP client to issue
a specific command to the FTP server after establishing a connection. The default FTP server
port is used.
o Implicit security. Implicit security begins with an SSL connection as soon as the FTP client
secure connections.
This field displays only if you have added an SSL certificate for the server.
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
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.
DMZ ports tab (trading only)



o Match IP address against partner definition – When IP address checking is enabled,

l FTP passive ports – If you enable port forwarding for embedded FTP, go to the Advanced tab
and specify a range of ports. The default value of 0 is not compatible with DMZ nodes.
When port forwarding is enabled for an embedded FTP server, the same range of passive ports
specified on the Advanced tab also is used in the DMZ. Temporary forwarding rules are
established and canceled as FTP data connections come and go. Make sure none of the passive
ports in the range is in use on any cluster machine or any DMZ machine.
If you do not allow SSL connections, the external firewall automatically opens FTP passive ports
on an as-needed basis, assuming you explicitly tell it which control ports are being used for FTP.
If you allow SSL connections, you must open the entire range of passive ports on the firewall.
Otherwise it cannot eavesdrop on the control connection to dynamically open the passive ports.
Configuring the load balancer to work correctly with DMZ nodes and passive FTP ports requires
special care. See the example script in <install directory>\util\dmzNode\
loadBalancer for more information. This script is intended for use by someone who is familiar
with the complexities of the FTP protocol and load balancer configuration.
Advanced tab
available.
integration.
l Read/idle timeout (seconds) – The maximum number of seconds the server waits when
reading data from a partner.

l Allowed passive ports – Ports for inbound passive data connections from FTP clients. You

can enter multiple ports. Each port number must be separated by a comma or you can specify a
range of ports. The following example uses comma-separated port numbers and a range of
ports:
50000,50001,50010-50020
No other computers other than the machine running Interchange server can use this same range
of ports. If you operate multiple instances of Interchange in a cluster, the same applies to all
machines in the cluster.
If clients are to make secure data connections to the server, these ports must be opened in the
firewall. If secure connections are not required, most firewalls are FTP-aware and automatically
open the data connection port based on the fact that a client already has a connection to the
FTP control port.
If you use a Windows operating system, we strongly suggest disabling the Windows firewall. Use
instead an FTP-aware external firewall. Otherwise, you must add an exception for each passive
port in the Windows firewall.
In the case of SSL connections, even FTP-aware firewalls cannot dynamically open passive ports.
If clients are to connect over SSL, open the same range of ports in the firewall as you specify in
this field. Failure to do so results in clients experiencing hangs when performing LIST, GET and
PUT operations.
For help with this field, ask your network administrator.
listed.
digest algorithm.

Trusted roots certificates tab

The trusted roots certificates tab displays the roots of clients’ certificates that a server trusts. In the
case of a self-signed certificate, the trust is for the certificate itself, as a self-signed certificate is a
root certificate. In the case of a certificate authority certificate, the trust is for the root certificate in
the chain of trust of a client’s certificate.
Home directories tab

Use the Home directories tab to force messages to be directed to a single directory. Specifying home
directories is optional.
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:
Exchange point User User subdirectory
AS3 foo foo\AS3
Secure file foo foo\SecureFile
No packaging foo foo\NoPackaging
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.
Lockout settings for FTP (embedded)

server users
You can set the number of times an FTP user can attempt to connect with an invalid password to an
embedded FTP server before Interchange locks out the user. This is a safeguard against possible
Set lockout rules

Use this procedure to set the lockout rules for an embedded FTP server. The rules apply to all FTP
users.

2. Click the Configure global transport settings task to open the global transport settings
page.
3. Select the Global FTP settings tab.
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.

To unlock a locked out user of an FTP (embedded) server, before the lockout interval expires:
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.

SFTP (embedded) server fields

After you add an SFTP-type trading delivery or application delivery to a community, an embedded
SFTP server is available in the UI. You can then change the server settings and advanced options.
To change settings:

embedded servers.
The following are the maintenance fields for an embedded SFTP server that has been added to a
community.
Settings tab
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.
– 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.
public/private key pair – Requires the partner to provide both of the above authentication
methods.
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
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.
DMZ ports tab (trading only)


at the router agent in the DMZ. For deliveries that require a user name and password to connect
(for example, FTP, SFTP, WebDAV), the router agent authenticates the user.
o Match IP address against partner definition – When IP address checking is enabled,
Advanced tab
available.

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.

l Allow uploads on configured delivery exchanges – Select this option to allow documents

to be uploaded to application deliveries or partner deliveries. By default, document uploads are
not allowed for deliveries. This setting does not impact pickups.
available for production deliveries.
listed.
Home directories tab

Use the Home directories tab to force messages to be directed to a single directory. Specifying home
directories is optional.
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:
Exchange point User User subdirectory
AS3 foo foo\AS3
Secure file foo foo\SecureFile
No packaging foo foo\NoPackaging
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.

Lockout settings for SFTP (embedded)

users
You can set the number of times an SFTP user can attempt to connect with an invalid password to
an embedded SFTP server before Interchange locks out the user. This is a safeguard against possible
Set lockout rules

Use this procedure to set the lockout rules for an embedded SFTP server. The rules apply to all SFTP
users.

settings page.
3. Select the Global SFTP settings tab.


Use this procedure to unlock a locked out user of an embedded SFTP server before the lockout
interval expires.


SMTP (embedded) configuration

An embedded SMTP server is available after you add a delivery exchange that uses an embedded
SMTP server other than the global server to a community. You can modify the server’s settings and
advanced options.
Modify the configuration

embedded servers.
The following are the maintenance fields for an embedded SMTP server that has been added by a
community.
Settings tab

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
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.
DMZ ports tab



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.

Set the system property to permit EDI

processing
6. Click Add.
OFTP (embedded) fields

An embedded OFTP V1 or V2 server is available after a community adds a delivery exchange that
uses an embedded ODETTE File Transfer Protocol server. You can change the server’s settings and
advanced options.
To change settings:
1. Select System management > Manage embedded servers.

Alternatively, you can click Trading configuration on the toolbar, click on the Communities
page, and then click the link near the bottom of the page named Change an embedded
transport server.
2. From the list of embedded servers, click the name of an OFTP server to open the modification
page.
3. Click Save changes when you are done.
The following are the maintenance fields for an embedded OFTP transport server. The fields for
OFTP V1 and V2 are the same.

Settings tab (without TLS)

Settings tab (with TLS)

l Add a TLS server certificate or TLS server certificate – For optional TLS, the server
requires a TLS certificate. If the server has a certificate, the name of the certificate is displayed. If
the server does not have a certificate, you are prompted to provide one.
If you use a self-signed certificate, it displays on the trusted root certificates tab. A self-signed
certificate is a root certificate. For a server certificate issued by a certificate authority, you may
also have to use the trusted root certificates tab to import a CA-issued root certificate for the
server certificate
DMZ ports tab




Advanced tab
OFTP X.25 over ISDN (embedded) fields

An embedded OFTP X.25 over ISDN server is available after an ODETTE File Transfer Protocol V1
delivery exchange X.25 over ISDN for receiving messages from partners has been added in a
community. You can change the server’s settings and advanced options.
To change settings:

embedded servers.

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 ISDN controller – The ISDN controller, selected from a drop-down list, to use for the outgoing
call.
number.
Advanced tab
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 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.

l Highest incoming channel – The highest value for the incoming channels identifier’s

l Lowest outgoing channel – The starting value for the outgoing channels identifier’s counter.
If blank, use the network’s default value.
l Highest outgoing channel – The highest value for the outgoing channels identifier’s
l Lowest two-way channel – The starting value for the two-way channels identifier’s counter.
l Highest two-way channel – The highest value for the two-way channels identifier’s counter.
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:

embedded servers.
The following are the maintenance fields for an embedded PeSIT (PeSIT) transport server that has
been added by a community.
Settings tab

DMZ ports tab



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.)
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 Server timeout (milliseconds) – Controls how long the server waits after receiving a file to

see if the client is going to be sending another file on the same session. Setting this too low may
cause abort errors on the client side. Setting this too high may cause tread pool depletion on
Interchange side.
l Connection timeout (seconds) –Time in seconds Interchange waits for a connection to the
l Transfer timeout - server mode (seconds) – Time in seconds a transfer times out.
l Network timeout (seconds) – Time in seconds the network times out.
l Protocol timeout (seconds) – Time in seconds the protocol times out.
l Send buffer (resize) – This represents the largest of chunk of data, in bytes, to be transferred
at one time. For high-speed networks, this should be 32,700 bytes, which is the default value.
In addition, 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 component.
The parenthetical term after the field name (rusize) is the term for this setting.
l Kb per sync point (pacing) – 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). Do not change this value unless advised by
the administrator of the component.
The parenthetical term after the field name (pacing) is the term for this setting.
l Max outstanding sync points (chkw) –This controls how many check point cycles 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. Do not change this value unless advised by the administrator of the
component.
The parenthetical term after the field name (chkw) is the term for this setting.

listed.
digest algorithm.
HTTP (embedded) business cases

This topic provides examples of using various remote URL and proxy settings to achieve different
results with the embedded HTTP transport servers. These business c ases apply to the global and
community embedded HTTP transport servers.
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
Field Sample setting
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
Embedded HTTP with remote URL

A partner connects to host:port from a remote URL and sends a POST request containing the path
part of the remote URL. The firewall or reverse proxy maps the remote host and port to a real server.
In the following example, edi.domain.com:5080 would be mapped to a server in the cluster
listening to port 4080.

UI settings
Remote URL http://edi.domain.com:5080/exchange/routingID
Proxy (none)
Results
Action Value
Partner connects to edi.domain.com:5080
HOST edi.domain.com:5080
Case C
Embedded HTTP with remote URL including path remapping

This case is the same as the previous case, except that the remote URL has a different path than the
local one, which means a proxy is present that is rewriting the path in the POST request based on an
internal mapping. In the following example, the path is changed from /inbound/stuff to
/exchange/routingID.
UI settings
Remote URL http://edi.domain.com:5080/inbound/stuff
Proxy (none)

Results
Action Value
Case D
Embedded HTTP with proxy and remote URL including path

remapping
This case is similar to the previous case, except the host and port of the proxy are explicitly
specified. The partner connects to the proxy host:port and sends a POST request containing the full
remote URL. The proxy uses this information to establish a connection to the real endpoint server. In
the following example, the proxy sends the POST request for edi.domain.com:5080 to one of the
servers in the cluster listening to port 4080. It also translates the external /inbound/stuff path to
/exchange/routingID.
UI settings
Remote URL http://edi.domain.com:5080/inbound/stuff
Proxy proxy.domain.com:8080
Results
Action Value
Partner connects to proxy.domain.com:8080

Action Value
Partner request POST http://edi.domain.com:5080/inbound/stuff HTTP/1.1
Case E
Embedded HTTPS (SSL) with remote URL

A partner connects to host:port from remote URL and sends POST request containing the path part
of the remote URL. The firewall or reverse proxy maps the remote host and port to a real server. In
the following example, edi.domain.com:1453 is mapped to a server in the cluster listening to port
1443. This example does not show path remapping, though that might be present as well.
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

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
Partner connects to proxy.domain.com:8083
Partner request 1 CONNECT edi.domain.com:1453
Partner request 2 POST /exchange/routingID HTTP/1.1

Secure Relay DMZ nodes
10
Secure Relay DMZ nodes in the demilitarized zone (DMZ) or perimeter network securely relay
messages from partners to Interchange in the protected, internal network. For security reasons, DMZ
nodes do not initiate connections to the protected network. DMZ nodes also do not connect to the
database or write messages to the file system. Secure Relay, which uses Axway technology, supports
inbound and outbound proxying.
Can you use DMZ nodes?

You can use DMZ nodes if your software license enables DMZ nodes. To check, select Help >
License information on the toolbar in the user interface. DMZ nodes are supported only if the
license key DMZNodes is listed on the enabled features tab.
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 Configure load balancer or firewall on page 487
l Manage IP address whitelists on page 490
l HTTP trading and Secure Relay on page 493
Overview of Secure Relay nodes

Secure Relay is a way to exchange messages with trading partners via an agent with a port-
forwarding service. The agent is deployed on a computer in your DMZ. This is secure because:
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.

10 Secure Relay DMZ nodes
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:


Types of secure connections

The master agent hosted by Interchange control node connects to the router agent and sets up two
secure connections. These are the only connections between Interchange cluster hosts and DMZ
hosts. The master agent sets up and manages port-forwarding rules for inbound connections. For
each delivery exchange point configured to use DMZ nodes, the master agent tells the node to
forward connections through the secure multiplex connection. An example of such a forwarding
instruction is:
fwd sr1:4080 to te1:4080

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.
Encryption and authentication keys

The first time you add a Secure Relay node in the user interface, Interchange generates a self-signed
root certificate. The public key is stored in a PEM file. Also created are two private keys in P12 files:
one for the master agent and one for the router agent. Both private-key certificates are signed by the
self-signed root certificate. The private key password is stored in a secure DAT file. The certificates
have an expiration of five years from the generation date. Interchange gives copies of the PEM file,
the router agent P12 file and the password DAT file to each Secure Relay node via an exported setup
file, which is explained in Add a DMZ node on page 481. The master agent uses its P12 certificate to
encrypt the administrative and multiplex connections to the router agent. The router agent
authenticates the connections with the root public key in the PEM file. In turn, the master agent
uses the public key to authenticate the router agent.
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.
Add DMZ zones

Use this procedure to set up and use DMZ zones with DMZ nodes. Using DMZ zones with Secure
Relay is optional.

About DMZ zones

DMZ zones are a way to direct messages through specific zones. For example, you may want to
exchange messages with some partners over the public Internet, but exchange messages with other
partners over a virtual private network. You could deploy DMZ nodes so some nodes send over the
Internet and some over the VPN. Then you can assign nodes to zones and assign zones to
embedded servers and partners.
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.
1. Select System management > System management on the top toolbar in the user

interface to open the System management page.
2. On the DMZ zones tab, click Add a zone to open the Configure secure relay zone page.
3. Type a name and description for the zone. These can be any text you want. We suggest using
text meaningful to the intended use of the zone.
4. Click Add to add the zone. The DMZ nodes tab displays and lists the new zone. Under the Hosts
column is the message not in use. The next step is to associate the zone with a DMZ computer
(host) running a DMZ node.

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.

Add a DMZ node

Use this procedure to add a DMZ node in the user interface and export a file for use by a DMZ or
network administrator to get the node running on a computer in the DMZ.
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:
Prerequisites
JRE version
The Secure Relay router node requires JRE 7 (or later) on the machine where the node is installed.
JCE policy file requirement

Ensure that the latest unlimited strength JCE policy files are installed in the lib/security directory
of the JVM on your DMZ machine.
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.
Export the node

After adding a node, export the node file to a directory.
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.

Run node as Windows service

Use this optional setup procedure to run the Secure Relay node as a Windows service.
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.
Enable port forwarding for an exchange

Use this procedure to add a community delivery associated with an embedded server and enable
port forwarding for DMZ nodes. This procedure presumes you already have added a community. If
not, see Add a community on page 136 and return to this procedure. It is also presumes you already
have added a DMZ node. If not, see Add a DMZ node on page 481.

Steps for port forwarding

1. Open the summary page for your community in the user interface.
2. Add a trading pickup for receiving messages from partners. Do one of the following to open the
exchange wizard:
l Click Set up a delivery for receiving messages from partners.

l If that option is not available, click Trading pickup in the navigation graphic at the top of
the page. Then click Add a delivery.
3. Add a delivery that uses an embedded server. For details about adding the exchange, see Add a
trading pickup on page 261.
4. Enable port forwarding for the embedded server.
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:
l Enable security termination in DMZ – Select this check box to have various

security functions performed in the DMZ. If connections are via SSL, the secure
connection is terminated at the router agent in the DMZ. For delivery exchanges that
require a user name and password to connect (for example, FTP, SFTP, WebDAV), the
router agent authenticates the user.
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.
o 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.)
e. If you use DMZ zones, select a zone. The Zone field displays only if you have added one or
more zones. See Add DMZ zones on page 478. The following screen shows the tab with the
additional Zone field when DMZ zones are used.

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.
Port forwarding details

Enable DMZ port forwarding – Select this check box if you want the external firewall or load
balancer to send inbound connections to Secure Relay DMZ nodes rather than directly to embedded
servers in the protected network.
machine in the cluster that can host the embedded server must be assigned a unique corresponding
port in the DMZ.

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:
dmz1:4021 -> te1:4021

dmz1:4022 -> te2:4021
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:
dmz2:4021 -> te1:4021

dmz2:4022 -> te2:4021
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.
Configure load balancer or firewall

The embedded servers page provides information a DMZ or network administrator needs to
configure the load balancer or firewall to send external connections to the correct ports. One way to
open the page is to select System management > Manage embedded servers. See Manage
embedded servers on page 435 for more information about the page.
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.
Configure load balancer

It is imperative to configure your load balancer to correctly recognize the complete set of DMZ hosts
and ports. It must send connections to all the listed ports on all the listed DMZ hosts.

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:
dmz1:4021, dmz1:4022, dmz2:4021, dmz2:4022
Update load balancer as needed

When you make changes that affect ports, Interchange cannot verify the settings of devices in the
DMZ. For example, if you add a host machine to your cluster, the user interface automatically
suggests additional DMZ ports on the embedded servers page. But it cannot automatically add the
ports to your load balancer configuration. It is important for you to follow up by working with your
DMZ or network administrator.
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.
Configure outbound connection proxy

Use these procedures to configure outbound connection proxying for Secure Relay:
l Open the outbound proxy page on page 488
l Enable outbound proxy and exceptions on page 489
Open the outbound proxy page

Before you can enable outbound proxying for Secure Relay, open the Configure outbound
connection proxy page. There are two ways to open the page:
1. Select System management > Manage embedded servers to open the Embedded

servers page. Click Configure outbound connection proxy via Secure Relay.
or
2. Open a community summary page. Click DMZ settings in the navigation graphic at the top of
the page. This opens the Configure DMZ settings page. Click Configure outbound
connection proxy via Secure Relay.
Caution If you open the Configure outbound connection proxy page without first adding a Secure
Relay node, messages on the page prompt you to add a node.

Enable outbound proxy and exceptions

To enable the proxy and engage secure connections:
1. Select Use outbound connection proxy.

2. Click Save changes on the Configure outbound connection proxy page. Once enabled, all
outbound connections go through the DMZ, provided one or more Secure Relay nodes are in
place.
3. Select Begin secure connection in the DMZ to have secure connections engaged at the
router agent in the DMZ rather than by Interchange. This page applies to outbound messages
sent to trading partners by all communities. It has no effect on inbound messages sent to the
back end. Even if you enable an outbound connection proxy for Secure Relay, a community-
specific HTTP proxy, if set up, takes precedence for outbound HTTP connections for that
community. For more information, see HTTP outbound proxy on page 584.
Note If outbound proxying is enabled, JMS cannot be used as a delivery exchange point for
trading. However, JMS can be used for back-end application pickup or delivery.

Bypass the proxy

Optionally, you can specify whether to bypass the proxy and connect to a server directly. For
example, if you do not want connections to your FTP server in the DMZ to use the outbound proxy,
add it to the Add a proxy exception list. (Connections from application delivery exchange points
automatically bypass the proxy even if no exceptions are defined.)
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:
Manage IP address whitelists

IP whitelists provide optional additional layer of security for Secure Relay DMZ nodes. Whitelists
only allow connections from trusted partners.
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
How IP addresses are checked

IP address checking is done in two steps:
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.
Without user authentication

This processing applies to transports such as HTTP.
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.
With user authentication

This processing applies to transports such as FTP and SFTP.
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.
Add, change IP address whitelist

Use this procedure to add or change IP addresses on the global whitelist. The global whitelist is for
managing the whitelisted IP addresses of all communities and partners. The only users who can do
this must have administrator permissions or must be associated with a role enabling the “Manage IP
address whitelist” permission.
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.
1. Select System management > Manage IP addresses to open the page for globally

managing all whitelisted IP addresses.
2. Click Add IP address and complete the fields.

The start and end fields are used for specifying a range of IP addresses. If you only need to
specify one IP address, complete the start field and leave the end field blank.
3. Click Pick party and select a community or a partner to associate with the IP address or range
of addresses. Multiple parties can be registered to the same IP address. For example, two parties
may share the same computer.
You must register a party who submits a user name and password to connect. This applies to
delivery exchanges such as FTP, SFTP, WebDAV. Registration is required so Interchange can
validate the user’s credentials and verify the user is associated with the party’s IP address.
Registration is optional for parties connecting via a transport not involving a user name and
password.
4. Click Save to add the IP address.

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 Enable IP address checking on page 493.
Enable IP address checking

Enabling IP address checking for Secure Relay requires selecting a check box on an embedded
server’s DMZ ports tab.
1. Select System management > Manage embedded servers on the top toolbar.

2. Select the name of an embedded server used for Secure Relay to open the server’s maintenance
page.
3. Select the DMZ ports tab. Make sure Enable DMZ port forwarding is selected.
4. Select Enable IP address checking in DMZ.

See Embedded transport servers on page 431 for more information about embedded servers.
See How IP addresses are checked on page 491 and Add, change IP address whitelist on page 492.
HTTP trading and Secure Relay

When using Secure Relay and your community trades with partners via HTTP, follow these
guidelines:
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.

Work with protocols,
formats, and standards 11
Interchange supports the exchange of messages and files over a wide array of protocols and
standards.
Interchange message exchanges can be classified in two general categories:
l Exchanges with applications
l Exchanges with trading partners
Exchanges with applications

You can configure Interchange to exchange (send and consume) messages and files with
applications on your private network. You set up application pickups and deliveries within a
community.
Application exchanges managed by

Interchange
Interchange supports the following protocols for exchanges with applications:
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

11 Work with protocols, formats, and standards
Managing Interchange exchanges with

applications
The following topics describe application pickups and deliveries, and how to manage them:
Exchanges with trading partners

You can configure Interchange to exchange (send and consume) messages and files with trading
partners located in both private and public networks. You set up community trading pickups in
community objects, and partner trading deliveries in partner objects.
Trading partner exchange types

Interchange supports the following protocols and standards for exchanges with trading partners:
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
Managing Interchange exchanges with

trading partners
The following topics describe community trading pickups and partner trading deliveries, and how to
manage them:
l Community trading pickups and partner deliveries on page 256
Registration wizard for partners

The registration wizard helps your company join a trading community. The wizard prompts for
information to establish a relationship between your company and the community. The community
uses the information to build a partner for your company. This gives the community your
preferences for receiving e-commerce messages over the Internet. In the case of ebXML, the wizard
builds a Collaboration Protocol Agreement (CPA) for use by you and your partner.
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
Additional information for working with

protocols, formats and standards in
Interchange
The following chapters provide additional information about how to manage specific protocols and
standards in Interchange:

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 MLLP on page 592
l OFTP on page 611
l PeSIT on page 651
l PGP secure trading on page 693
l Email client partners on page 579
l Web services on page 715
l WebTrader on page 980
l X.400 on page 737
AS1 / AS2 partner self-registration

The registration wizard helps members of a trading community generate partner information for
Interchange. This topic is for partners who want to trade via the AS1 or AS2 message protocol. For
ebXML, see ebXML partner self-registration on page 576.
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.
Using the partner wizard

Before using the partner wizard, you need the following information at hand:
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
Can you use AS4?

You can use AS4 if your software license enables both WebServices and AS4 functionality. To check
enabled license keys, select Help > License information on the toolbar in the user interface. The
list of enabled license keys must include the following two keys:

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 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.
Metadata attribute MMD element name Description
Standard Metadata
SenderRoutingId From Routing ID of the sender

party.
SenderRoutingIdType type attribute in <From> ebXML routing ID type of

element the sender participant.
ReceiverRoutingId To Routing ID of the receiver
participant.
ReceiverRoutingIdType type attribute in <To> element ebXML routing ID type of

the receiver participant.
ebXML Metadata

FromRole FromRole The ebXML from role is

used together with the
"from" attribute. The role
attribute indicates the role
the party is playing in the
business transaction, such
as the "buyer" role.
This attribute is required
for AS4 user messages.
ToRole ToRole The ebXML to role is used

together with the "to"
attribute. The role
attribute indicates the role
the party is playing in the
business transaction, such
as the "seller" role.
Service Service References the upper

business-level
collaborative business
process.
ServiceType type attribute in <Metadata An option of the service

name="Service"> element element of the ebXML
message. Only required if
the trading partners
require a "type" in order
to properly identify the
service.
Action Action Specifies the action of the

overall upper-level
business process. An
action is typically an
individual business
transaction of a
process.

ConversationId ConversationId Correlates all messages

belonging to a
process. The conversation
ID is required in an ebXML
message.
ebXML.PModeId PModeId Optional attribute that

specifies the association
of the message with a P-
Mode.
ebXML.AgreementRef AgreementRef String value that identifies

the agreement that
governs the exchange.
ebXML.AgreementRefType type attribute in <Metadata Optional attribute that

name="AgreementRef"> specifies how the sender
element and receiver interpret the
value of the reference.
ebXML.MessageProperty MessageProperty.[PROPERTY_ Defines user-specific

NAME] properties or meta-data
that qualifies or abstracts
the payload data.
ebXML.Payload.PartProperty <PartProperty name= Defines user-specific

[PROPERTY_NAME]> element properties or meta-data.
as child element of <Payload>
ebXML.Payload.SchemaVersion <Schema version=[SCHEMA_ Defines the version of

[NUM] VERSION] …> element as child schema(s) that can be
element of <Payload> used for validating the
document identified b y
PartInfo element.
ebXML.Payload.SchemaNamesp <Schema namespace= Defines the namespace of

ace[NUM] [SCHEMA_NAMESPACE] …> schema(s) that can be
element as child element of used for validating the
<Payload> document identified b y
PartInfo element.

ebXML.Payload.SchemaLocatio <Schema location=[SCHEMA_ Defines the location of

n[NUM] LOCATION] …> element as child schema(s) that can be
element of <Payload> used for validating the
document identified b y
PartInfo element.
Signal-processing Metadata
ebxml.SignalType SignalType Specifies the type of

Value can be any of following : signal message the
message represents.
l ebXML.PullRequest
l ebXML.Receipt for AS4 signal messages.
l ebXML.Error
ebXML.Error.Code Error.Code Unique identifier for the

ebms error type.
ebXML.Error.Category Error.Category Identifies type of error

related to a particular
origin. For example:
Content, Packaging,
Unpackaging,
Communication, Internal
process.
ebXML.Error.Severity Error.Severity The severity of the error.
ebXML.Error.Description Error.Description Short description of the

error.
ebXML.Error.Detail Error.Detail Additional details about

the context in which the
error occurred.
Pull-related Metadata
message.WaitForPull message.WaitForPull Default=false.

When set to true, stops a
message for being
processed in the action
tree and moves it to a wait
for pull state.

message.WaitForPull.MaxRewin message.WaitForPull.MaxRewin Default=3

dAttempts dAttempts Specifies the number of
times a message can
rewind back to a wait for
pull state.
message.WaitForPull.RewindAtt message.WaitForPull.RewindAtt Tracks the number of

empts empts times a message is
rewound to a "wait for
pull" state.
ebXML.MessagePartitionChanne MessagePartitionChannel Identifies the Message

l Partition Channel where
the message is queued.
AS4.ResponseProcessingExcha AS4.ResponseProcessingExcha Indicates the friendly

ngePoint ngePoint name of an AS4 trading
pickup to correctly apply
the business protocol
settings when processing
response user messages.
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.
PollingCycleMaximumRequests PollingCycleMaximumRequests Maximum number of pull

requests per cycle.
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
SplitMessage SplitMessage Default=false

When set to "true",
triggers AS4 splitting on
the message being
processed.
FragmentSize FragmentSize Default= Value of System

Property
"as4.fragmentSize".
Overrides the global
system property
"as4.fragmentSize".
SplitCompressionAlgorithm SplitCompressionAlgorithm Defines the type of

compression to be applied
before splitting the MIME
envelope
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.

Metadata used by processing

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 .
Metadata to control message validation
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
Message Metadata Documents (MMD)

Interchange supports AS4 business processes using Message Metadata Documents (MMDs) as the
interface between it and the back-end. MMDs are XML documents that point to an AS4 document on
a file system, and contain information Interchange uses to process documents.
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
Example 1: Initiate a push

The following is an example of an MMD for initiating an AS4 push to a remote partner.
<?xml version="1.0" encoding="UTF-8"?>

<MessageMetadataDocument protocol="ebXML" protocolversion="3.0">
<Metadata name="From" type="String">AS4BUYER</Metadata>
<Metadata name="To" type="String">AS4SUPPLIER</Metadata>
<Metadata name="PModeID>TradePO</Metadata>
<Metadata name="FromRole" type="string">http://docs.oasis-open.org/ebxml-
msg/ebms/v3.0/ns/core/200704/initiator</Metadata>
<Metadata name="ToRole" type="string">http://docs.oasis-open.org/ebxml-
msg/ebms/v3.0/ns/core/200704/responder</Metadata>
<Metadata name="Service" type="string">POService</Metadata>
<Metadata name="Action" type="string">ProcessPO</Metadata>
<Metadata name="ConversationId" type="string">trade-po-001</Metadata>
<Metadata name="AgreementRef" type="string">Trading-PO</Metadata>
<MessagePayloads>
<Payload id="12345" packagingLocation="SOAPBody">
<Location
type="filePath">C:\Axway\Interchange\common\data\PurchaseOrder.xml</Location>
</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.
Example 2: Generate a queued message for pulling

The following is an example of an MMD that generates a message to a client pulling queue.

<Metadata name="PModeID>TradePO</Metadata>
<Metadata name="FromRole" type="string">http://docs.oasis-open.org/ebxml-
msg/ebms/v3.0/ns/core/200704/initiator</Metadata>
<Metadata name="ToRole" type="string">http://docs.oasis-open.org/ebxml-
msg/ebms/v3.0/ns/core/200704/responder</Metadata>
<Metadata name="Service" type="string">POService</Metadata>
<Metadata name="Action" type="string">ProcessPO</Metadata>
<Metadata name="ConversationId" type="string">trade-po-001</Metadata>
<Metadata name="AgreementRef" type="string">Trading-PO</Metadata>
<Metadata name="message.WaitForPull" type="string">true</Metadata>

<MessagePayloads>
<Payload id="12345" packagingLocation="SOAPBody">
<Location type="filePath">C:\Axway\Interchange\common\data\BusinessDocument_
1.xml</Location>
</Payload>
<Payload id="123456" packagingLocation="Attachment">
<MimeContentId>POAttch1</MimeContentId>
<MimeContentType>application/gzip</MimeContentType>
<Location
type="filePath">C:\Axway\Interchange\common\data\BusinessDocument21.xml</Loca
tion>
<Schema location=test1 namespace="t1" version="1.1"/>
<Schema location=test2 namespace="t2" version="1.2"/>
</Payload>
</MessagePayloads>
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.
Example 3: Initiate a pull request

This is an example of an MMD that could be used to manually initiate a pull request (for example, in
place of a scheduled polling event).

<Metadata name="SignalType" type="string">PullRequest</Metadata>
<Metadata name="MessagePartitionChannel" type="string">http://docs.oasis-
open.org/ebxmlmsg/ebms/v3.0/ns/core/200704/defaultMPC</Metadata>
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.
Example 4: Initiate a receipt send

This is an example of an MMD that could be used to manually initiate a the sending of a receipt to a
partner (for example, in place of an automatically-generated receipt setting in the configuration).



<Metadata name="SignalType" type="string">Receipt</Metadata>
<Metadata name="RefToMessageId" type="string">eec1aad9-74b8-4608-961f-
213066ab0e70@AS4SUPPLIER</Metadata>
In this MMD:
l Receipt sender is: AS4SUPPLIER
l Receipt requester is: AS4BUYER
l Message is signal type: Receipt
Example 5: Initiate an error message send

This is an example of an MMD that could be used to manually initiate a the sending of a processing
error message to a partner.

<MessageMetadataDocument protocolVersion="3.0" protocol="ebXML">
<Metadata type="String" name="From">AS4SUPPLIER</Metadata>
<Metadata type="String" name="To">AS4BUYER</Metadata>
<Metadata type="string" name="SignalType">Error</Metadata>
<Metadata type="string" name="ErrorCode">EBMS:0010</Metadata>
<Metadata type="string" name="Category">Processing</Metadata>
<Metadata type="string" name="ErrorDescription">Error reason</Metadata>
<Metadata type="string" name="ErrorDetail">Error Location</Metadata>
<Metadata type="string" name="ConnectionId">dbf86a9f-bf2d-4353-bfe5-
4df56ed5e9fd</Metadata>
<Metadata type="string"
name="RefToMessageId">urn:uuid:E1E424CA5832EB21A61361174114991@SUNSUPER</Metadata>
<Metadata type="string" name="FromRole">Buyer</Metadata>
<Metadata type="string" name="ToRole">Seller</Metadata>
<Metadata type="string" name="Action">ProcessAck</Metadata>
In this MMD:
l Error message sender is: AS4SUPPLIER
l Error message receiver: AS4BUYER
l Message is signal type: Error
Message Partition Channels (MPC)

Message Partition Channels (MPC) enable the partitioned transfer of AS4 messages between AS4
exchange participants. MPCs are used for both pushed and pulled messages. A single MPC is used
for a single message exchange between two participants.
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:
Implicit default MPC
If no MPC is explicitly assigned in the exchange configuration, Interchange implicitly
assumes the blank MPC.
Explicit default 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.
Explicit non-default MPC
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.
Message Interchange Where to set MPC MPC Options

Exchange role
Pattern
Simple push Sender MMD, metadata or Trading AS4 Default / Specified

Partner Delivery
Simple pull Server Trading AS4 Partner Delivery (used Default / Specified

for validation/ authorization)

Message Interchange Where to set MPC MPC Options

Exchange role
Pattern
Simple pull Client Trading AS4 Polling Pickup: Default / Specified /

l Implicit via selected Partner Specified override
Delivery
l Overridden/Explicit via polling
client setting
Alternatively, you can set the MPC
using and MMD.
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
About non-default MPCs

You can create a non-default MPC for AS4 trading by simply naming one in your Interchange
configuration.
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.
Pulling client behavior

When Interchange is configured as an AS4 pull client, it uses the settings of the Partner Trading
Delivery/Polling Settings tab to build AS4 pull requests.
Based on the MPC setting in the community trading pickup Polling Settings tab, the polling client
request will contain one of the following values:
l If the Message partition channel field is blank, no MPC value is included in the pull request

and the default MPC is assumed (unless overridden by the next field).
l If the Message partition channel field contains a value, that value is included in the pull
request (unless overridden by the following field.) You can enter any value in this field, as long
as the same value is agreed upon with your exchange partner.

l If the Override message partition channel field contains a value, this value is included in

the pull request.
When the server analyzes the client pull request, it looks for a server-side partner MPC that
corresponds to the client request. If no such MPC exists, it returns an error. If the MPC exists, it lets
the client execute polling actions (configured number of pull requests and frequency).
Pulling server behavior

Inbound pull requests may contain an MPC. The server validates the MPC on the resolved partner, to
see if the defined MPC is assigned on any AS4 Partner Delivery Exchange.
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).
AS4 user authentication

To authenticate the AS4 message pushes and AS4 pull requests, Interchange supports the use of:
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.
How to activate UserName tokens

For outbound pushes and for outbound client pull requests:
Activate UserName 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, Use username token when sending. You can optionally choose to
include this in the SOAP header as a digest in place of plain text.
5. Enter the user name and password that is required by your receiving partner.
For additional AS4 validation rules information, see AS4 default settings on page 918.
For inbound reception:
Step 1: Create a user account on the AS4 pickup:
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:
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)
X.509 security tokens

X.509 security tokens are supported for user authentication in AS4 message exchanges, as
described in the WSS: SOAP Message Security specification.
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.
How to activate X.509 tokens

For outbound pushes and for outbound client pull requests:
Activate X.509 tokens in the AS4 Collaboration Settings:
2. On the community graphic, click on the Collaboration settings icon to open the Configure
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.
For additional AS4 Collaboration settings information, see AS4 default settings on page 918.
For inbound reception:
Set the Validation Rule for inbound AS4 messages:

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
Large message splitting and joining

Interchange supports the splitting and joining of large AS4 messages.
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.
Receipt handling of split messages

To generate a receipt signal with non-repudiation for the reassembled message (since the
reassembled message is not signed), Interchange in receiving mode automatically computes a hash
value for the payload parts. This differs from regular AS4 processing, where the non-repudiation
receipt can be generated using the elements of the security header in the received signed user
message.
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
Set the default fragment size and join time-limit

2. Manually enter the following URL in your browser: http://{localhost or
machinename}:6080/ui/core/SystemProperties
The Systems properties page is displayed.
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.
Set Collaboration Settings

To enable outbound AS4 splitting:
1. From the Trading configuration menu, select Change default collaboration settings.

The Collaboration defaults for sending messages page is displayed.
2. Click the AS4 tab.
3. In the AS4 Collaboration Settings section, select:
l Split messages - Enables Interchange to fragment outbound AS4 user messages.
l MIME envelope compression – Optionally apply GZIP compression on the MIME
envelope for outbound user messages, before splitting.
See Collaboration default settings / AS4 default settings on page 918.
Enable spitting in an AS4 MMD

Setting up the following metadata in an MMD, overrides the Splitting configuration in collaboration
settings.
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.
Enable handling of empty SOAP Body

messages
There is a special case in Interchange handling of AS4 messages when:
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.
About the tuning.properties file

To enable AS4 empty SOAP Body handling you must edit Interchange tuning.properties file.
This file is located in <install directory>/conf.
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.
Enable empty SOAP Body handling

To enable empty AS4 empty SOAP Body handling:
1. Go to <install directory>/conf and open the tuning.properties file in a text editor.

ws.allowEmptySOAPBody
3. Set the value of the property to "true":
ws.allowEmptySOAPBody=true
4. Save the file.
6. Repeat this procedure for each node.
Configure a one-way client pull
About this topic

This topic describes options for configuring Interchange as an AS4 pull client.
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
Pull initiation options

With Interchange, there are several ways to initiate an AS4 message pull from a remote server:

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.
Scheduled pull configuration

To schedule AS4 client polling, you work in the AS4 polling client Pickup/ Advanced tab.
On the Advanced tab you can set the following poll scheduling parameters:
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 "interval" field below.
l Polling interval (seconds) – (Default = 60) The interval, in seconds, Interchange waits
between polling actions for messages to retrieve.
When you have set these poll scheduling parameters (along with the proper connection and
enveloping information) the polling client will automatically execute pulls of available messages
according to the settings. PullRequests are generated iteratively, as long as a user message or a
message fragment is received in response to generated PullRequest. If an eb:Error is received in
response to a pull request, then the remaining PullRequests in the cycle are not generated.
MMD-initiated pull configuration

To use an MMD to initiate the polling of a remote AS4 server queue:
l Create an AS4 MMD with pull request metadata. The following file is an example of an AS4 pull
request MMD:

<Metadata type="String" name="From">AS4SUPPLIER</Metadata>
<Metadata type="String" name="To">AS4BUYER</Metadata>
<Metadata type="string" name="SignalType">PullRequest</Metadata>
<Metadata type="string" name="AS4.ResponseProcessingExchangePoint">AS4 Buyer
Pickup</Metadata>
<Metadata type="string"
name="MessagePartitionChannel">http://sender.example.com/mpc123</Metadata>
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.
Message Participation Channel options

For a detailed description of Message Participation Channel selection, see Message Partition
Channels (MPC) on page 515.
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.
Reliable Messaging options

Interchange supports the use of reliable messaging multiple retry features for AS4 message
exchanges.
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.
Message Splitting options

For detailed information on setting up message splitting, see Large message splitting and joining on
page 521.
AS4 use case: One-way push (MMD

initiated)
About this use case

This use case describes a message exchange scenario in which Interchange pushes an AS4 message
to a remote trading partner and a receipt is returned from the receiving partner to the sending
(push) partner. In this case, message delivery (push) is initiated by the consumption of an ebMS v3
MMD from a back-end file directory.

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.
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.
Configure the sending (push) participant

To configure the MMD-initiated push of an AS4 message to a remote partner (with return receipts
activated), complete the following sequence of tasks. For additional information on completing
each task, follow the links:
1. Create an MMD to use to initiate the AS4 push.
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.
Configure the push receiving participant

To configure the receiving participant of an AS4 push, and activate return receipts, complete the
following sequence of tasks. For additional information on completing each task, follow the links:
1. Add a Community to specify characteristics of Interchange as the receiving AS4 exchange
participant.
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.
AS4 use case: One-way pull (MMD initiated)
About this use case

This use case describes a message exchange scenario in which Interchange pulls an AS4 message
from a remote trading partner and returns a receipt to sending partner. In this case, the message pull
request is initiated by the consumption of an ebMS v3 MMD from a back-end file directory.

Assumptions
l The receiving (pulling) and sending p artners have agreed on a common configuration for
message partition channel, security and receipts.
Note on queued message life

Messages placed in AS4 Interchange polling queues stay in the queues until they are either
consumed by a client or until the backup purge setting threshold is reached (default = 45 days).
When the backup purge threshold is reached, queued messages are deleted.
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.
Phase one: populating the queue

The following figure illustrates the population of an AS4 message queue from an MMD consumed
from the back-end file system.

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.
Phase two: pulling the queued message

The following figure illustrates an AS4 message pull between an Interchange instance configured as
a server and an Interchange instance configured as a pulling client.
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.
Configure Interchange as an AS4 pull server

To configure Interchange in the server role of an AS4 pull message transfer (with "expect receipts"
activated), complete the following sequence of tasks. For additional information on completing
each task, follow the links:
1. Create an MMD to use to generate an AS4 user message on the server in the client's pull queue.
2. Add a Community to specify characteristics of Interchange as the AS4 pull server.
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.
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.
8. Configure Validation Rules to control how Interchange consumes the AS4 polling request.
Configure Interchange as an AS4 pull client

To configure Interchange in the client role of an AS4 message pull, and activate return receipts,
complete the following sequence of tasks. For additional information on completing each task,
follow the links:
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.
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.
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.
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 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
Add an AS4 trading delivery

To configure a new AS4 delivery:
1. From the menu bar select Partners > Manage partners to open the Partners page.

2. Click the name of a partner to which you want to add the delivery.
3. In map graphic, click the Partner delivery icon to open the Partner deliveries page.
4. Click Add a delivery to open the exchange wizard.
5. In the Choose message protocol page, select AS4 (HTTP) and click Next.
6. Configure the HTTP settings for AS4 exchanges:
l URL – The URL for connecting to the trading partner's server. 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 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.
l This server requires a user name and password – If necessary for your connection,

select this option, and then type a user name and password to connect to the server.
7. Click Next.
8. On the Exchange name page, enter a meaningful name for the delivery.
9. Click Finish.
After you add an AS4 trading delivery

When you add an AS4 trading delivery, the delivery is displayed in the list of pickups in the Partner's
Trading deliveries page. When you add the delivery, the product automatically assigns a set of
default values. You can open the delivery and modify these values to optimize trading
characteristics.
See Modify an AS4 trading delivery on page 534.
Modify an AS4 trading delivery

When you add a pickup or delivery, the wizard prompts you to provide a basic set of parameters.
After you create the pickup or delivery you can open the maintenance page to view and manage a
comprehensive set of parameters. Some of these parameters were automatically set when you added

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.
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.
AS4 partner delivery exchange maintenance fields
HTTP settings tab

l URL – URL to use for the connection to the trading partner's server.
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.
This value is used both for a final push configuration option and for secondary pull authorization
checks.
In this field, you can specify the MPC to use for AS4 message deliveries to this partner.
If you do not specify an MPC in this field, the default-implicit (empty) MPC is automatically
selected.
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.
l This server requires a user name and password – If necessary for your connection, select
this option, and then type a user name and password to connect to the server.

Advanced tab
to Transfer CFT via PeSIT, the value in this field must be less than the CFTTCP setting in Transfer
integration.
l Retries – This is the number of times Interchange tries to connect to the partner’s transport if
for triggering retries:
o The connection attempt failed immediately for a specific reason such as host not found.
Note: In the last case above, the 200 OK response also includes the receipt if

l Response timeout (seconds) – How long, in seconds, that Interchange waits for the delivery

l Enable HTTP chunking – If you are sending files larger than 2 gigabytes, select this option 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.
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.
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
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.
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.
Add an AS4 embedded server pickup

Use this procedure to add a trading pickup to a community for receiving AS4 messages from
partners through the HTTP embedded server.
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.
After you add an AS4 embedded server pickup

When you add an AS4 pickup, the pickup is displayed in the list of pickups in the Community's
Trading pickups page. When you add the pickup, the product automatically assigns a set of default
values. You can open the pickup and modify these values to optimize trading characteristics.
See Modify an AS4 embedded server pickup on page 539.
Modify an AS4 embedded server pickup

When you add a trading pickup, the wizard prompts you to provide a basic set of parameters. After
you create the pickup, you can open the maintenance page for the pickup to view and manage a
Procedure
configuration.
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.
6. After making any modifications, click Save changes.
AS4 trading pickup (embedded) maintenance fields
HTTP (embedded) settings tab

Click the Global HTTP server link to view the HTTP server configuration.

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.
The URL used by partners field displays the URL that your partners use to send AS4 messages to

this exchange.
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.
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.

Body / Attachments section:

l Process SOAP body – Select this option to process the contents of the SOAP body of the
consumed message.
l Process attachments – Select this option to process the attachments of the consumed SOAP
message.
Processing section:
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.

files that this transport can handle. If the trading engine receives a file larger than the maximum,
the file is rejected and a message is written to the events log.
Add an AS4 polling client pickup

Use this procedure to add a trading pickup to a community for polling a partner for AS4 messages.
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.

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 Define a new AS4 polling client and click
Next.
7. Click Choose partner delivery... and select an AS4 partner delivery. Then click OK. The
parameters of the selected delivery are used to populate the fields
8. On the AS4 polling client page, complete the fields:
l Partner name – This field is automatically populated based on the partner delivery
exchange selection.
l Delivery URL – This field is automatically populated based on the partner delivery
exchange selection.
l Message partition channel (MPC): – This field is automatically populated based on the
partner delivery exchange selection.
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.
MPCs also allow for merging flows from several sending participants, into a unique flow that
will be treated as such by a receiver.
l Override message partition channel (MPC) – Enter an alternative MPC identifier to
override the value specified in the "Message partition channel (MPC)" field. The same value
must be configured for the polled queue on your partner's machine.
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.
After you create an AS4 polling client pickup

When you add an AS4 pickup, the pickup is displayed in the list of pickups in the Community's
"Trading pickups" page. When you add the pickup, the product automatically assigns a set of
default values. You can open the pickup and modify these values to optimize trading characteristics.
See Modify an AS4 polling client pickup on page 543.

Modify an AS4 polling client pickup

you create the pickup, you can open the maintenance page for the pickup. This enables you to view
and manage a comprehensive set of parameters. Some of these parameters were automatically set
when you added the object, and can only be modified after you add the object.
Procedure
configuration.
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.
AS4 trading pickup (polling) maintenance fields
AS4 polling settings tab

l Partner name – You cannot directly modify this field. This field is automatically populated
based on partner delivery exchange selection.
l Delivery exchange – This field displays the delivery exchange that is selected to send the pull
request message to the partner server. To modify parameters of this exchange, click the name
that is displayed, and in the Change this delivery page, modify settings as required.
l Delivery URL – You cannot directly modify this field. This field is automatically populated
based on partner delivery exchange selection.
l Message partition channel (MPC) – You cannot directly modify this field. This field is
automatically populated based on partner delivery exchange selection.
l Override message partition channel (MPC) – Optionally enter an alternative MPC identifier
to override the value specified in the previous field. If you enter a value in this field, the same
value must be configured for the polled queue on your partner's machine.
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.
Advanced tab
User message processing
Header section:
l Parse SOAP headers into message metadata – Select this option if you want to 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.
Body / Attachments section:
l Process SOAP body – Select this option to process the contents of the SOAP body of the
pulled message.
l Process attachments – Select this option to process the attachments of the pulled SOAP
message.
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.
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.

Manage AS4 polling queues

Messages placed in AS4 Interchange polling queues stay in the queues until they are either
consumed by a client or until the backup purge setting threshold is reached (default = 45 days).
When the backup purge threshold is reached, queued messages are deleted.
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.
Can you use ebXML?

You can use ebXML if your software license enables this functionality. To check license
enablements, select Help > License information on the toolbar in the user interface.
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.

ebXML message lifecycle

The following topics summarize inbound and outbound processing of ebXML messages by
Interchange.
Outbound ebXML processing

The following summarizes Interchange processing steps for an outbound ebXML message There are
variations to this description, but the following is a typical case of a simplified view of ebXML
outbound processing.
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.
Inbound ebXML processing

The following summarizes Interchange processing steps for an inbound ebXML. There are variations
to this description, but the following is a typical case of a simplified view of ebXML inbound
processing.
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.

ebXML message metadata

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 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.
ebXML metadata descriptions

The following describes the metadata elements for ebXML.
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.
Required, optional metadata for back-end application

integration
The following table lists required and optional metadata elements for all back-end application
methods. The metadata elements are defined in ebXML metadata descriptions on page 548.
Element Name Usage
AckRequested Optional
AckSignatureRequested Optional
Action Optional
ConversationId Optional
CPAId Optional
DuplicateElimination Optional
FromRole Required

Element Name Usage
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
ebXML message metadata documents

(MMDs)
When exchanging messages with a file system located in the back end Interchange supports ebXML
business processes using message metadata documents (MMDs) as the interface between it and the
back-end. The MMDs are XML documents that point to an ebXML document on a file system and
contain information that Interchange uses to process documents.
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.

Example of ebXML MMD for outbound message

<MessageMetadataDocoment documentID="Test_B2" protocol="ebXML" protocolVersion="2.0">
<Metadata name="From" type="string">remery-ebxml</Metadata>
<Metadata name="FromRole"
type="http://www.starstandard.org/processes/3A4.xml#Initiator">interop</Metadata>
<Metadata name="To" type="string">esx6-ebxml</Metadata>
<Metadata name="ToRole"
type="http://www.starstandard.org/processes/3A4.xml#Responder">interop</Metadata>
<Metadata name="Service" type="string">FileTransfer</Metadata>
<Metadata name="Action" type="string">B1</Metadata>
<Metadata name="CPAID">remery-esx6</Metadata>
<MessagePayloads>
<Payload id="0784247">
<RemovePayloadAfterProcessing>true</RemovePayloadAfterProcessing>
<MimeContentId>smallXmlPo</MimeContentId>
<MimeContentType>application/xml</MimeContentType>
<Location typle="filePath">
/Users/remery/Source/MiscHaboobStuff/ebXMlInterop4Q2004/CpasAndMmds/smallxmlPO_delete.xml</Location>
</Payload>
</MessagePayloads>
Using an MMD to ping a partner

Ping is an optional service that lets one message service handler determine whether another MSH is
operating.
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.
Example of ping MMD

The following is an example of a ping MMD. Replace the placeholder values in this example with
your sender and receiver information. Copy the MMD to a community file system integration pickup
directory.

<MessageMetadataDocument documentId="PingMMD" protocol="ebXML"
protocolVersion="2.0">
<Metadata name="From" type="string">PartnerA</Metadata>
<Metadata name="To" type="string">PartnerB</Metadata>
<Metadata name="Service">urn:oasis:names:tc:ebxml-msg:service</Metadata>
<Metadata name="Action" type="string">Ping</Metadata>
<Metadata name="CPAId">PartnerA-PartnerB-cpa-1</Metadata>

Example of ping-pong messages

The following are examples of a ping message from one party and the pong response from the other
party. These examples are packaged in SOAP envelopes.
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-
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.
POST http://PartnerA:4080/exchange/PartnerA HTTP/1.1

Content-Type: text/xml
SOAPAction: "ebXML"
User-Agent: haboob/5.3.3.0.6 build-1552
Host: coronation:4080
Connection: close
<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-
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>

Use an MMD for a status request

You can use an MMD to ask a partner about the status of a previously sent message using the
StatusRequest action. For instance, you could use this after reliable messaging retries in the CPA
have been exhausted, but you want to check whether the partner received the payload.
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.
<MessageMetadataDocument documentID="Test_G3" protocol="ebXML"

<Metadata name="StatusRequest">M1109715442335.631@partnerA-
osx5001680093774348165</Metadata>
<Metadata name="From" type="string">partnerA-ebxml</Metadata>
<Metadata name="FromRole"
type="http://www.starstandard.org/processes/3A4.xml#Initiator">interop</Metadata>
<Metadata name="To" type="string">partnerB-ebxml</Metadata>
<Metadata name="ToRole"
type="http://www.starstandard.org/processes/3A4.xml#Responder">interop</Metadata>
<Metadata name="Service" type="string">urn:oasis:names:tc:ebxml-
msg:service</Metadata>
<Metadata name="Action" type="string">StatusRequest</Metadata>
<Metadata name="CPAId" type="string">partnerAB-esx6</Metadata>
Schema location and description

Interchange supports elements in MMDs of outbound messages for identifying locations of related
schemas and describing payloads. The following MMD snippet shows an example of how the
Schema and Description elements can be used as child elements of Payload:
<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
Supported ebXML trading transports

The supported transports for exchanging ebXML messages over the Internet are HTTP and e-mail
(SMTP). When you configure a community to use one of these transports for receiving messages
from partners, choose the ebXML message protocol in Delivery exchange wizard. Then select HTTP
or SMTP as the transport. Follow the prompts to set up a transport.
For general information about creating adding trading pickups and deliveries see:
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.
Supported ebXML application transports

A community can use any of the available transports for picking up and delivering ebXML messages
to back-end applications.
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:
Application pickup options

The following are the application pickup options and metadata sources for documents that are
routed to trading partners.
The back-end or middleware generates metadata

A back-end system or middleware can generate metadata and forward the data to Interchange.
Middleware must understand metadata and payloads. Metadata picked up with ebXML payloads
specifies, among other things, the CPAs to use for processing outbound messages to partners. The
listed application pickup transports must forward certain metadata elements, as described in
Required, optional metadata for back-end application integration on page 551.
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.
Using fixed metadata

The simplest way to avoid having a back-end system produce metadata for payloads is to specify the
“from” and “to” address in the application pickup and let Interchange determine the other
information it needs based on the community CPA. For file system integration, this method
eliminates the need to use MMDs.
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.

Select Always use the following address and click Pick party to select the sending party. Use

the To address tab to make the same selections for the receiving party.
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.
Application delivery options

You can use any of the available application delivery transports to send messages received from
partners to a back-end system. If, however, you want to attach message metadata to payloads, there
are three transport options.
l File system with message metadata – This integration delivery transport works just like the

file system transport, but triggers Interchange to produce an MMD and forward it with the
inbound message to the back-end file system. The MMD contains all metadata associated with
the document received from the partner. See ebXML message metadata documents (MMDs) on
page 552.

l Web services API client – A client routes messages received from partners to a back-end

server. Interchange produces message metadata to the back-end via the AsynchSend Java
interface. The client sets a MetadataItem object on the API Message object for each metadata
item associated with the document received from the partner.
l JMS – The message metadata is attached to the BytesMessages containing the payload that is
placed on the queue. The JMS exchange sets a JMS property on the BytesMessage for each
metadata item associated with the document received from the partner.
ebXML message compression

Interchange supports GZIP compression of ebXML messages. To use it, your trading partner must
support the same compression scheme.
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.
<tp:SimplePart tp:id="GzipSimplePart" tp:mimetype="application/gzip"/>

<tp:Packing tp:id="BogusPackage">
<tp:ProcessingCapabilities tp:parse="true" tp:generate="true"/>
<tp:CompositeList>
<tp:Composite tp:id="BogusComposite"
tp:mimetype="multipart/related" tp:mimeparameters="type=text/xml">
<tp:Constituent tp:idref="BogusSimplePart"/>
</tp:Composite>
</tp:CompositeList>
</tp:Packaging>
Set up a community for ebXML trading

Configuring a community for ebXML trading is like setting up any community, with some notable
differences. Primarily, the community must be associated with a community- and partner-specific
CPA for trading to occur. The CPA determines options for message packaging, requests for
acknowledgments and compression, not the collaboration settings in the user interface. In addition,
the community routing ID must have a specific format.
See Communities on page 134 and Add a community on page 136 for details not specific to ebXML
about setting up a community.


or
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
The community and CPAs

The user interface lets you import complete CPAs as well as CPA templates and associate them with a
community. Other than importing or deleting, however, tasks for managing CPAs are handled
outside of this application. The exception is when you import a CPA template and have partners use
the partner registration wizard. See ebXML partner self-registration on page 576.
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.
Send ebXML via an intermediary

Interchange has an optional message protocol for sending ebXML messages from a true sender to a
true receiver via a third party. The intermediary’s role is to receive the message from the true sender
and forward it to the true receiver. The intermediary does not use a CPA. However, if both the true
sender and true receiver use Interchange or Activator, the end points must use CPAs, as though the
message was or sent directly.

Overview of intermediary re-routing

Re-routing is performed by configuring Interchange in the intermediary role to receive and send
messages via the ebXML intermediary message protocol. The protocol is available only if your user
license enables it. If the protocol is not listed in the delivery exchange wizard, your license does not
support it. For information about the wizard, see:
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.
Intermediary message-handling notes

The following information relates to how the intermediary re-routes ebXML messages:
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.
Configuration of end points

True senders and true receivers who use Interchange must use CPAs as though the parties are
directly exchanging messages without an intermediary.
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.

Intermediary trading with SMTP

When setting up an ebXML intermediary with SMTP, an embedded SMTP server must be used for the
receiver. If the external SMTP server is used, the trading to the receiver fails.
Intermediary trading with HTTPS

If messages are sent via HTTPs, the partners’ HTTPS server certificates must be trusted by the
intermediary community.
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>

<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:TransportProtocol tp:version="1.1">HTTP</tp:TransportProtocol>
<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>
Extract KeyInfo element for a CPA

A tool is available for exporting public key information from a certificate. The KeyInfo element
information then can be copied to a CPA.
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:
keyInfoWriter <path of certificate file> <path of XML output

file>
The following is an example use of the tool:
keyInfoWriter c:\certificates\worldwide.p7b c:\certificates\

worldwide_keyinfo.xml
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.
Import a CPA template

Before you can import a CPA template, it must be properly configured. Building a CPA template
requires knowledge of ebXML standards. The reason for importing templates is so partners can use a
registration wizard to enter their trading information. The system then completes the CPA using the
information the partner provided and information extracted from your community.
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.
Tools for CPAs

Command-line tools are available to help manage CPAs. All are found in <install
directory>\tools and must be run from the tools directory. The following topics describe each
tool.
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:
ebxmlCpaSchematronValidator <parameter> <path to CPA file>
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
l Remove last signature
ebxmlCpaSecurityGuard -z -c file:///C:/cpaTest/tempCpaSigned.xml -d
C:/cpaTest/output -f oneSigCpa.xml
The following describes the parameters.
Parameter Description
(long)
--cpa URL referencing the CPA. For example: file:///C:/ebxml/cpa.xml.
--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.

(long)
--party-name Name of the party signing the CPA. Must match the partyName attribute of the

PartyInfo element of the CPA.
--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:
ebxmlCpaValidator [-offline -online] -cpa [cpa1 file] [cpa2

file] ...
The following describes the parameters.

-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:
2. On the Settings tab, click Select CPA File to choose a CPA to use to generate MMDs.

3. Click Select Output Folder to choose the directory to write the generated MMDs.
4. On the Advanced tab, you can specify MMD settings for:
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.
STAR BODs with ebXML

Use this procedure to set up inline processing of outbound STAR BODs sent via the ebXML message
protocol.
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.

1. On the community summary page, click Message handler in the navigation graphic at the top

of the page.
2. Click Add a message processing action at the bottom of the page.
3. For the Attribute field, select Content MIME type and click Next.
4. On the operator and value page, the form should read “Process the message when Content
MIME type Equals.” In the field after the word “Equals,” type application/xml and click Next.
5. Select Perform inline processing via a Java class and type the following in the Class
name field:
com.cyclonecommerce.webservices.protocols.ebxml.inlineprocessing.StarBO
DProcessor
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.
HL7 payloads with ebXML

Use this procedure to set up inline processing for Health Level 7 version 2 and 3 payloads in
conjunction with ebXML messaging. This functionality, which supports the HL7 Draft Standard for
Trial Use, has been tested for interoperability. See http://www.drummondgroup.com.
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.
1. On the community summary page, click Message handler in the navigation graphic at the top

of the page.
2. Click Add a message processing action at the bottom of the page.
3. For the Attribute field, select Content MIME type and click Next.
4. On the operator and value page, the form should read “Process the message when Content
MIME type Equals.” In the field after the word “Equals,” type application/xml and click Next.
5. Select Perform inline processing via a Java class and type the following in the Class
name field:
com.cyclonecommerce.webservices.protocols.ebxml.inlineprocessing.Hl7Pro
cessor
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.
ebXML partner self-registration

The partner registration wizard provides a way for one community (a hub) to get many partners
configured to trade messages with it. The registration wizard employs a CPA template to build a
complete CPA for the hub and each partner. Both the hub and each partner use the CPA tailored for
their trading relationship to engage in ebXML trading.
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.
ebXML hub procedure

Use this procedure if you are an ebXML hub and want partners to use the registration wizard to build
CPAs. These steps must be completed before partners can use the 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.
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
l Template name – The name of the CPA template the partner should select when using the
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.

ebXML partner procedure

Use this procedure if you are a spoke partner and want to use the hub’s registration wizard to build a
CPA that you can use to engage in ebXML trading with the hub partner.
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
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:
1. Open for editing: <install directory>\conf\log4j.properties

2. Under the section of the file titled “you can change levels of categories below this line,” find the
following line:
log4j.category.com.cyclonecommerce.webservices=info
3. Change the info value to debug.
Common ebXML issues and possible solutions:
l No binary collaboration found message – Add an ebXML delivery exchange

l Receiver routing ID is missing message – The receiver can be your community or a
partner. This message indicates the routing ID for one or the other is unknown to Interchange.
This could be because a routing ID for one or the other has not been defined.
l CPA not found for CPA ID message – Make sure the CPA ID is specified in the metadata
(MMD, JMS property or message attribute for the delivery exchange).
l CanSend cannot be found for action message – CanSend Action is not defined in the CPA
for the community.
l CPA-related issues – Trading may fail because of errors or omissions in a CPA. Check a CPA
thoroughly to make sure the document is accurate and complete.
Email client partners

Interchange can exchange business documents with partners who use an email client application
like Microsoft Outlook. Setting up such a trading relationship requires configuration by users of
Interchange and the email client.
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
Trade without certificates

An email client partner can send messages to an Interchange partner without using a certificate to
encrypt attached documents. This method is for users who prefer to send or receive plain text
attachments to email messages.
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:
a. On the community summary page, click Message validation on the navigation graphic

at the top of the page.
b. Click the Signing tab. If Reject messages that are not signed is selected, click Add
an exception for a partner, select the email partner and click Add.
c. Click the Encryption tab. If Reject messages that are not encrypted is selected, click
Add an exception for a partner, select the email partner and click Add.
6. Make sure message signing and encryption for outbound messages to this partner are turned
off. Do the following:
a. On the community summary page, click Collaboration settings on the navigation

graphic at the top of the page.
b. Click Default settings at the top left of the page titled “Configure community-specific
collaboration settings.”
c. Click the generic email tab.
d. By default, all settings should be off for request receipts, encrypt messages and sign
messages. If not, clear the options and click Save changes.
Configure email client partner

Use this procedure to configure an email client partner to trade documents with a partner who uses
Interchange.
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.

Trade with certificates

An email client partner can send messages to an Interchange partner using a certificate to encrypt
attached documents. This method is for users who prefer to send or receive encrypted attachments
to email messages.
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.

Configure email client partner

Use this procedure to configure an email client partner to trade documents with a partner who uses
Interchange.
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.
Send from email partner

After the email client application and Interchange have been configured properly, use the following
guidelines for sending email messages with attachments from the email client to Interchange.
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.
HTTP outbound proxy

Interchange enables you define an HTTP proxy for routing all outbound HTTP traffic. The proxy
applies to a single community. Each community must set up its own.
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.

HTTP proxy fields

The following describes the proxy fields on the Configure HTTP proxy page.
l Route all outbound HTTP traffic through a proxy – Select this check box to use an HTTP
proxy for a community. Clear this check box if you do not want to use a proxy.
l Host – The fully qualified domain name or IP address of the HTTP proxy.
l Port – The port through which outbound HTTP traffic is routed.
l This proxy requires a user name and password – Select this check box to supply a user

name and password for basic authentication. Clear this check box if your proxy does not require
basic authentication.
o User name – The user name to connect to the server.
o Password – The password to connect to the server.
o Confirm password – The password entered again for confirmation.
Selecting a proxy when testing an HTTP transport

When testing an HTTP transport for sending messages to a partner, you are prompted to select the
community whose proxy settings are to be used for the test. You are prompted to select a
community regardless whether an outbound proxy has not been set up within the community.
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.
1. Click Partner delivery on the navigation graphic at the top of a partner summary page.

2. Click Test in the right column for the HTTP transport you want to test. This action starts the

test.
3. Select a community to proceed with the test.
HTTP security solutions

When using HTTP-based message protocols – AS2, secure file, ebXML, web services, Rosettanet –
security considerations are similar to hosting a web server. There are industry-standard solutions to
make this type of communication secure. Solutions recommended for Interchange are described in
the following topics.
l HTTP (embedded) server on page 586
l External staged HTTP server on page 588
HTTP (embedded) server

You can configure Interchange to accept incoming HTTP connections directly from trading partners
by adding an inbound delivery exchange that uses the embedded HTTP server. The following is a list
of safety options to use in conjunction with the embedded server. The options are numbered from
lowest to highest security.
Option 1. Message-level security

It is safe to allow inbound connections directly to the embedded HTTP server if your message
validation rules require messages (payloads) to be signed and encrypted (the default). This is true
even if Interchange is running on a machine within your protected network, because the embedded
server rejects any message that was not signed with the partner’s private key.
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.
Option 2. Firewall filtering

An additional level of security can be achieved by configuring rules on your firewall to allow only
inbound connections from known-partner IP addresses. You also can allow connections only to
designated ports (for example, 4080 and 1443).
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.
Option 4. Client-authenticated SSL

With SSL, an additional level of security called client authentication can be configured. This option
is selected by default when you define an SSL embedded server in Interchange. Client
authentication requires your partner to present a certificate before the inbound connection can be
accepted. This is similar to the concept of requiring payloads to be signed.
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.
Option 5. Hardware SSL

Options 3 and 4 describe SSL and client-authenticated SSL in terms of the embedded HTTPS server.
But the best performance and highest security can be achieved with a hardware device in the DMZ to
terminate SSL connections.
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.
External staged HTTP server

A staged HTTP server usually resides in your DMZ, accepts incoming connections and stages
incoming messages to disk. A servlet installed on the external HTTP server allows Interchange to poll
for inbound files that have been dropped off by partners. Functionally, the interaction of
Interchange with a staged HTTP server is similar to the way it interacts with an FTP server.
Commonly used HTTP servers include Tomcat, WebLogic and WebSphere.
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.
HTTP connection troubleshooting

The following flow charts illustrate an outbound HTTP connection, what can go wrong, and how
you can resolve connection issues. In addition, if your community is on the receiving end of a
partner’s outbound connection, the charts can help you resolve issues on your side of the
connection.
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.
MLLP server configuration

To configure Interchange as an MLLP server, you add an MLLP type pickup to a community and use
the functionality of an embedded MLLP server to consume and respond to messages sent by
MLLP clients. You can configure the MLLP server to respond synchronously or asynchronously.
This MLLP server can consume requests from clients either in the back end (applications) or over the
internet (trading partners).
MLLP client configuration

To configure Interchange as an MLLP client, you create either an MLLP partner trading delivery (to
send messages to an MLLP server hosted by a partner), or an MLLP community application delivery
(to send messages to an MLLP server application located in the back end).
MLLP use cases

There are two principal use cases for MLLP configuration in Interchange:
l Asynchronous transfers
l Synchronous transfers
Use case 1: Asynchronous MLLP exchanges

In an asynchronous MLLP exchange, the recipient of the message responds to the request with a
protocol acknowledgement, but the handling of the message in the back end is handled
asynchronously. The following paragraph describes a use case in which this exchange pattern is
used.
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.

Asynchronous MLLP client configuration

To configure the MLLP client for an asynchronous exchange:
1. Create a community to represent the doctor's organization.
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.
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.
Asynchronous MLLP server configuration

To configure the MLLP server for asynchronous responses to a client:
1. Create a community to represent the health organization.
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.
Use case 2: Synchronous MLLP exchanges

In a synchronous MLLP exchange, the recipient of the message keeps the connection open until a
functional acknowledgement (HL7 message) has been returned from the back end. The following
paragraph describes a use case in which this exchange pattern is used.
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.
Synchronous MLLP client configuration

To configure the MLLP client for an synchronous exchange:
1. Create a community to represent the doctor's organization.
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).

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.
Synchronous MLLP server configuration

To configure the MLLP server for asynchronous responses to a client:
1. Create a community to represent the MLLP server.
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.
Add or modify an MLLP application delivery
About application deliveries for MLLP

An application delivery is an object that specifies how you want your local community to send
messages to a back-end application. This topic describes how to create an application delivery for
sending client requests to a back-end MLLP server application.

Add an MLLP application delivery
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
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.
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.
Modify an MLLP application delivery

After you create an MLLP application delivery, you can view and modify the fields that define the
delivery.

File system settings tab

Interchange routes messages. If the directory does not exist, Interchange creates it for you. Use
a unique directory name.
Filenames tab

system generates.
Example with the original file extension: dabeed45_4cb.edi
Example without the original file extension: z47e4120_4ce

o Automatically generate unique filenames – (default) . If Interchange detects a
file.



Schedule tab
Advanced tab
available.
triggering retries.

plus the interval.
commands.
Add or modify an MLLP application pickup
About application pickups for MLLP

A community application pickup is an object that specifies how you want your local community
to consume messages from a back-end application. In this case, Interchange is in a server role,
consuming an MLLP client application request.
Add an MLLP application pickup
Prerequisite

Procedure
configuration.
that community.
3. Click Application pickup in the navigation graphic to open the Application pickups page.
4. Click Add an application pickup.
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.
11. Click Finish.
Modify an MLLP application pickup

After you create an MLLP application pickup, you can view and modify fields that define the pickup.

server.



server.
From address tab

To address tab

EDI Splitter tab


Schedule tab

Advanced tab
l Polling interval (seconds) – The interval, in seconds, Interchange waits before polling for
Add or modify an MLLP trading delivery
Add an MLLP trading delivery
About partner deliveries for MLLP

partner delivery for sending client requests to an MLLP server.
Prerequisites
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.
4. On the Delivery exchanges page, click Add a delivery.
5. On the Choose message protocol page, select No packaging and click Next.

8. On the Exchange name page, enter a name for the partner delivery.
9. Click Finish.
Modify an MLLP trading delivery

After you create an MLLP trading partner delivery, you can view and modify fields that define the
delivery.
MLLP settings tab

l MLLP server – Network address of the MLLP server.
l Port – Access port of the MLLP server.

Schedule tab
Advanced tab
available.

triggering retries.
plus the interval.
l Start block character – The decimal byte value to use for the start block character. Start and
(hexadecimal B). The default value is the customary MLLP value. You must use the same values

l End block character – The decimal byte value to use for the end block character. Start and

l Acknowledgement expected from the target MLLP server – Select this option to keep
the connection with the MLLP server open while waiting for acknowledgement.
commands.
Add or modify an MLLP trading pickup
About trading pickups for MLLP

consume messages from a remote partner. In this case, Interchange is in a server role, consuming an
MLLP client request.
Add an MLLP trading pickup
Prerequisite
You must have a community defined. See Add a community on page 136.
Procedure
configuration.
that community.


8. In the Choose transport protocol page, select MLLP and click Next.
authentication certificate trusted by the server when connecting –
11. Click Finish.
Modify an MLLP trading pickup

After you create an MLLP trading pickup, you can view and modify fields that define the pickup.




From address tab

To address tab

EDI Splitter tab


Schedule tab
Advanced tab

MLLP (embedded) fields

An embedded MLLP server is available after you add an application pickup or a trading pickup that
uses an embedded MLLP server. You can change the server’s settings and advanced options.
To change settings:
1. Select System management > Manage embedded servers.

Alternatively, you can click Trading configuration on the toolbar, click on the Communities
page, and then click the link near the bottom of the page named Change an embedded
transport server.
2. From the list of embedded servers, click the name of an MLLP server to open the modification
page.
3. Click Save changes when you are done.
The following are the maintenance fields for an embedded MLLP transport server.
Settings tab (without TLS)

l Server name – The name for the embedded MLLP server. This can be any name you want.
l Port – The TCP port on which the embedded server listens for connection requests.
Settings tab (with TLS)

l Server name – The name for the embedded MLLP server. This can be any name you want.
l Port – The TCP port on which the embedded server listens for connection requests.
l Add a TLS server certificate or TLS server certificate – For optional TLS, the server
requires a TLS certificate. If the server has a certificate, the name of the certificate is displayed. If
the server does not have a certificate, you are prompted to provide one.
If you use a self-signed certificate, it displays on the trusted root certificates tab. A self-signed
certificate is a root certificate. For a server certificate issued by a certificate authority, you may
also have to use the trusted root certificates tab to import a CA-issued root certificate for the
server certificate.

DMZ ports tab

DMZ nodes. The tab only applies to servers used for trading and not back-end application
connections.
l Enable DMZ port forwarding – Select this option if you want the external firewall or load

l Enable security termination in DMZ – Select this option to have various security functions
performed in the DMZ. If connections are via SSL, the secure connection is terminated at the
router agent in the DMZ. For delivery exchanges that require a user name and password to
l Enable IP address checking in DMZ – Select this option to have Interchange check partner
IP addresses against a whitelist of authorized IP addresses. Connections from unknown IP
addresses are not allowed.

select this option to have the router agent check whether the partner is registered to the IP
Advanced tab
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

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.
listed.
digest algorithm.

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 Configuration outline for X.25 on page 634
l Add or edit an X.25/B-ISDN router on page 635
Pages and fields

l OFTP V1 server or polling fields on page 617
l OFTP V2 server or polling fields on page 621
l OFTP V1 client fields on page 622
l OFTP V2 client fields on page 626
l Modify an OFTP pickup or delivery on page 637
l X.25/B-ISDN router fields 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.
Work-around for OFTP file name length limit

OFTP can handle files with names no longer than 26 characters. This is a limitation of the protocol
and not of Interchange.
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:
transport.oftp=info
In addition, 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.
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.
TSL support for OFTP2

Interchange supports communities that use Trust-service Status Lists (TSLs) for trading via OFTP2.
The following topics describe TSLs and how they are used.
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.
How a community uses TSL

Interchange treats a TSL simply as a source of trusted certificates for a community. These are the
certificates that are seen in the Trusted root certificates and Trusted SSL root certificates tabs of a
community's Certificates page.
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.
Configure TSL for a community

Use this procedure to configure a community to use TSL.
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.
Verify TSL download

5. Do the following to verify the TSL has been downloaded:
a. Click Certificates in the navigation graphic at the top of the page.
b. Select the Trusted root certificates tab or the Trusted SSL root certificates tab to display
lists of certificates in the TSL. Notice the user interface does not provide the option to
untrust any of the certificates.
You also can examine TSL certificates by selecting System management > Manage
certificates. This opens a page that allows searching for, and viewing details of, all X.509
certificates in the certificate store.

Stop updating TSL certificates

6. To unlink a community from a TSL, click the task Stop getting this community's trusted
certificates from a TSL on the Manage use of Trust-service Status List (TSL) page. Click OK
to confirm.
When the TSL is turned off, the trusted root certificates for the community remain the same,
but are no longer updated automatically. Additionally, when you go to the Trusted root
certificates tab and Trusted SSL root certificates tab on the Certificates page for the community,
the certificates can be untrusted.
Configure TSL retrieval

Use this procedure to configure Interchange to download TSL files through an HTTP proxy. Only
one proxy can be configured. Interchange downloads all TSLs through the proxy. (This proxy does
not apply to viewing of downloaded TSLs in a browser.)
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.

2. Click the task Configure TSL retrieval to open the Configure Trust-service Status List (TSL)
retrieval page.
3. Select an option:
l None – Retrieval through a proxy is turned off.
l Local – Retrieval is through the proxy configured on this page. Go to step 4.
l DMZ – Retrieval is through a Secure Relay DMZ node. This option displays only if your user
license supports Secure Relay. Go to step 5.
4. If you select Local, complete the following fields.
l Host – The name or IP address of the proxy server to use when retrieving TSLs via HTTP.
l Port – The port number of the proxy server to use when retrieving TSLs via HTTP.
l This proxy requires a user name and password – Select 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.
5. 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.

OFTP transport configuration

A community can use an OFTP transport to trade messages with partners. The following paragraphs
describe the fields in the exchange wizard for adding OFTP trading pickups and trading deliveries.

Transport type

and send messages to the community. Go to Network type on page 617.
Network type
or add one to use.

Interchange uses a name in the following format: Router on [host name or IP].


more about X.25 over ISDN see Use X.25 over ISDN on page 632.
2662.
name or IP>.

See the following figure: OFTP V1 embedded server in delivery exchange wizard.
OFTP V1 server fields (TCP)

The following are the server fields, unless you selected X.25 or X.25 over ISDN. See OFTP V1 server
fields (X.25 or X.25 over ISDN) on page 620.
session setup.
l Port – If TCP, the port on which the server listens for connections.
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
o This server requires client authentication – If you selected TLS, select this check box


community.
partner.
OFTP V1 server fields (X.25 or X.25 over ISDN)

session setup.
l Server network user address – The NUA to wait for an incoming call via OFTP V1 X.25.
number.

community.
partner.


Transport type

and send messages to the community. Go to OFTP V2 server fields on page 621.
See the following figure: add OFTP V2 embedded server in delivery exchange wizard.
OFTP V2 server fields

session setup.


exchange.
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
community.
partner.

the fields for adding an OFTP V1 delivery for a partner.
OFTP transport type

external server to send messages to a remote partner. See Network type on page 623.


on page 623.

Network type

or add one to use.



more about X.25 over ISDN see OFTP on page 611.
2662.
name or IP>.

See the following figure: add OFTP V1 (TCP) client in delivery exchange wizard.

OFTP settings

session setup.
l Remote network user address – The NUA of the remote partner’s server to connect to (OFTP V1
X.25 only).


o Set OFTP session password – Enter a password only when required. The password can
be no longer than eight alphanumeric characters and is case sensitive.
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.
nodes on page 474.

the fields for adding an OFTP V2 delivery exchange for a partner.
OFTP transport type

external server to send messages to a remote partner. See OFTP settings on page 627.
on page 626.


See the following figure: add OFTP V2 client in delivery exchange wizard.
OFTP settings
session setup.

exchange.
Interchange server.
community.
partner.
nodes on page 474.
Use X.25 with OFTP

Interchange supports OFTP V1 over X.25 as an alternative to OFTP V1 over TCP/IP. X.25 is an ITU-T
standard protocol suite for packet-switched wide area network (WAN) communications. The
following topics describe use of X.25 for outbound and inbound messages.

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.
Control and data connection

A control and data connection is established on the router on TCP port 146. This connection has
two roles:
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).
Use X.25 over ISDN

Using OFTP over X.25 over ISDN is much like using OFTP over X.25. The ISDN calls act as the
physical link to transport the X.25 network frames. Instead of using a point-to-multipoint network as
the X.25 network usually is, two different modes can be used:
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.
X.25 over ISDN terminology

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.
X.25 firewall requirements

The following table lists required firewall exceptions for X.25.
Description Source Destination
Control All Interchange hosts, All routers, TCP port 146.

connection random port.
Monitoring All Interchange hosts, All routers, UDP port 161 (unless changed).

connection random port.
Inbound data All routers. All trading engine hosts, one port per

connection embedded server using X.25.
ISDN firewall requirements

All instances of Interchange must be able to connect to every ISDN router on its remote CAPI port
(2662 by default). No reverse or call-back connection is made, as with X.25.
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)
Configuration outline for X.25

High-level steps for configuring an Odette File Transfer Protocol V1 delivery exchange over X.25 or
over X.25 over ISDN:
1. Add an OFTP V1 over X.25 delivery exchange in a community and a partner. See OFTP transport

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.
Add or edit an X.25/B-ISDN router

To add or edit a router configuration for use by OFTP over X.25 or OFTP over X.25 over ISDN:

2. Select the X.25/ISDN routers tab.
3. Do one of the following:
l Click Add a X.25/B-ISDN router to add a router configuration.
l Click a router name to edit its configuration.
4. Complete or edit the fields (see X.25/B-ISDN router fields on page 635).
When adding a router configuration, all fields display on the same page. When editing a router,
the fields display across two tabs.
5. Click Add to add a router or Modify to save changes for an existing router.
X.25/B-ISDN router fields

The topic describes the tabs and fields for configuring the X.25/B-ISDN router router.

General tab
l X.25 enabled – Select this check box for the router to access an X.25 network. Complete or
edit the associated fields.
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
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.
l SNMP UDP port – The UDP port of the SNMP service on the router. If set to 0 (or blank), the

default port of 161 is used.
l SNMP Syslog table ID – The SNMP table ID for the log messages table. If blank, the default
ID of 1.3.6.1.4.1.272.4.1.12.1.4 is used.
Modify an OFTP pickup or delivery

The following topics document the fields on the maintenance pages for Odette File Transfer
Protocol V1 and V2.
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:
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

Embedded OFTP and OFTP TLS settings tab (community)

l View settings for this embedded server – Click this link to manage the embedded server.
For details, see the embedded transport servers chapter.
l Local connection string – The port and path of the embedded server. You cannot edit this
field.
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.
session setup.
exchange.
community.

partner.
Embedded OFTP X.25 and embedded OFTP X.25 over ISDN settings
tab (community)
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.
session setup.
community.
partner.
OFTP and OFTP TLS settings tab (partner)



session setup.
exchange.
Note: If the sub-field is selected, you cannot clear the check box.
Interchange server.
community.

partner.
OFTP X.25 settings tab (partner)

l Remote network user address – The NUA of the remote partner’s server to connect to (OFTP
V1 X.25 only).
l Protocol identifier – Custom data to send to the partner along with the call establishment
request. The data is only meaningful for the remote party. It is usually used to distinguish
between calls that are addressed to the same NUA. You must enter a hexadecimal value.
l Call user data – Custom data to send to the partner along with the call establishment request.
The data is only meaningful for the remote party. It is usually used to distinguish between calls
that are addressed to the same NUA. You must enter a hexadecimal value.
l X.25 router – The name of the X.25 router specified for the delivery exchange.
session setup.

community.
partner.

OFTP X.25 over ISDN settings tab (partner)

l ISDN controller – The ISDN controller, selected from a drop-down list, to use for the outgoing
call.
l Remote X.25 network user address – The X.121 address of the partner if the call is to be
routed over X.25. If the call is established directly to the partner’s ISDN number, this number
may be optional depending on its access control configuration.
l X.25 call user data – This value is passed to the X.25 connection request. Depending on the
configuration on the partner’s side, this may be used to select the software responsible for
answering the call. You must enter a hexadecimal value.
session setup.
community.
partner.
OFTP shared settings tab (partner)

This tab applies only to an OFTP delivery exchange that was set up by one partner but also is used
by, or shared with, another partner. It displays only for the partner sharing the exchange and not
the partner with the original delivery exchange.
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.
Sharing partners tab (partner)

This tab applies only to an OFTP delivery exchange that was set up by one partner but also is used
by, or shared with, another partner. It displays only for the partner who owns 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.

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 Backend will generate receipts (EERPs and NERPs) – Select this option if Interchange
should pause before generating and sending EERPs (signed end-to-end responses) and NERPs
(signed negative end responses). Interchange waits for a back-end system to submit messages
containing the correct metadata for generating EERPs and NERPs. If not selected, Interchange
synchronously generates and sends EERPs and NERPs without waiting for the back-end system
to respond.

specify otherwise.

Note This tab does not apply to OFTP X.25 or OFTP X.25 over ISDN. See Advanced tab for X.25
(partner) on page 646 or Advanced tab for X.25 over ISDN (partner) on page 647.

available.
integration.
o An OFTP protocol error occurred. For example, the partner returned a negative response to a
query on whether to start the file transfer.

minutes. The interval plateaus at 60 minutes.
plus the interval.
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 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.
specify otherwise.

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.
Advanced tab for X.25 (partner)

available.
integration.
plus the interval.
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.

exchange.
specify otherwise.
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.
Advanced tab for X.25 over ISDN (partner)

available.

integration.
plus the interval.
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 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.

l Highest incoming channel – The highest value for the incoming channels identifier counter.

l Lowest outgoing channel – The starting value for the outgoing channels identifier counter.
l Highest outgoing channel – The highest value for the outgoing channels identifier’s
l Lowest two-way channel – The starting value for the two-way channels identifier’s counter.
l Highest two-way channel – The highest value for the two-way channels identifier’s counter.
l Local X.25 network user address – The X.25 address identifying the caller (the instance of
Interchange). Complete this field if the call is routed over an X.25 network that requires it or if
the remote partner uses X.25 access control based on the originating address.
l X.25 window size – The number of X.25 packets that can be sent without acknowledgment.
If the value is blank the network’s default value is used.
l X.25 packet size – The size of the X.25 packets to be sent over the network. If the value is
blank the network’s default value is used.
exchange.

specify otherwise.
OFTP polling settings tab (community)

l OFTP partner to poll – The name of the partner whose server the community polls for
inbound messages.
l URL to poll – The URL of the server being polled for messages.
Advanced tab (OFTP polling)

specify otherwise.
messages.
transport servers.

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.
Using PeSIT with Axway Transfer CFT

A typical use of the PeSIT protocol is for exchanges with the Axway Transfer CFT product. Transfer
CFT is a high-performance, multi-platform managed file-transfer controller. It is a non-intrusive,
high-volume component that ensures the same quality of service and a uniform interface to users
and applications throughout the enterprise, regardless of the underlying platforms. It provides
essential features to manage the automation, monitoring and governance of file transfers.
PeSIT limitations and special usages

l PeSIT store-and-forward is not supported in Interchange.
l For PeSIT exchanges, Interchange routing IDs are used as PeSIT protocol IDs:
o PI3 = caller's protocol identity
o PI4 = server’s protocol identity
l In the PeSIT standards, the PI99 parameter is a free text block. Axway Transfer CFT and Axway
MFT use this parameter to transfer information that is supplementary to information contained in
the other message fields defined for the protocol. This supplementary information is often
referred to in Axway documentation as "Transfer CFT PeSIT extensions". Interchange does not
handle this PI99 usage, although it is possible to implement.

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.
About your PeSIT license

You can use the PeSIT message protocol features of Interchange if your license enables these
features. To check your licensed features see Help > License information. The PeSIT license is
listed under Trading engine features as "Axway Transfer", and should have the value "Enabled".
PeSIT configuration overview

Generally, you can separate the configuration of PeSIT exchange endpoints into application
configuration and trading partner configuration. This topic provides an overview of these
configuration types.
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.
Trading partner configuration

To configure Interchange for PeSIT exchanges with trading partners, 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 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.

Role of configuration objects in exchanges
Outbound example: basic configuration

An application sends a message to Interchange.
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.
Inbound example: basic configuration

A remote trading partner defined in Interchange sends a message to an application through
Interchange, using any protocol supported by Interchange. Interchange identifies the remote
partner using the Partner object, and then directs the message to the application over PeSIT E,
using information specified in the community and application delivery objects.
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.

Pickups and deliveries for PeSIT

In Interchange, you configure PeSIT exchanges with applications and trading partners principally
through the creation and management of PeSIT pickups and deliveries.
Types of PeSIT exchanges

In Interchange you can configure three types of exchanges for PeSIT message trading:
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.
PeSIT functions for partner trading and back-end

integration
The following table summarizes the PeSIT protocol functions for exchanges for exchanging with
applications and with partners:
Interchange PeSIT function Back-end application Trading partner

exchange exchanges exchanges
type
Delivery Send
Fetch
–
Pickup Polling
Multi-community
Respond to fetch

Interchange PeSIT function Back-end application Trading partner

exchange exchanges exchanges
type
Common Restarts
Metadata
attachments
TLS handling
Ack handling
Pickup exchange Protocol IDs (PI3 and PI4)
identifier
PeSIT delivery exchanges

A PeSIT delivery exchange acts as a PeSIT caller (client).
l For application deliveries, you add the delivery exchange to a community. You configure

the exchange to call a back-end PeSIT server.
See Add or modify a PeSIT application delivery on page 659.
l For trading partner deliveries, you add the delivery exchange to a trading partner. You

configure the exchange to call a PeSIT server residing on the partner's computer.
See Add or modify a PeSIT partner delivery on page 675.
A PeSIT delivery exchange operates in one of two roles:
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.
PeSIT pickup exchanges

A PeSIT pickup exchange acts as a PeSIT server.
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:
For details about how to configure, view and modify all PeSIT exchanges, refer to Manage PeSIT
pickups and deliveries on page 659.
PeSIT polling pickups

The polling pickup is available:
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:
For details about how to configure and modify all PeSIT exchanges, refer to Manage PeSIT pickups
and deliveries on page 659.
Special note for community backups
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.
Manage PeSIT pickups and deliveries

Working in the Interchange user interface, you can perform the following management tasks:
l Add or modify a PeSIT partner delivery on page 675
Add or modify a PeSIT application delivery
Add a PeSIT application delivery
Prerequisite
You must have a community. If you need to add a community, see Add a community on page 136.
Procedure
configuration.

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.
Modify a PeSIT application delivery

When you add an application delivery, the wizard prompts you to provide a basic set of parameters.
After you create the delivery you can open the maintenance page to view and manage a
Procedure
configuration.
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.
PeSIT application delivery maintenance fields
PeSIT settings tab

l Hostname – Enter the fully qualified domain name or IP address of the back-end PeSIT server
your community connects to for sending files.
l Port – The port on which the back-end PeSIT server listens for connection requests.
l Hold all outbound messages for pickup by the remote client:
o Selected: The messages sent to this delivery stop in HeldForPickup state, and are available
for the remote client to fetch.
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. The trading
automatically adds the root certificate to the linked communities' trusted SSL root
certificates.
If you don’t 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).
l Community settings (caller) – This section controls the caller’s protocol identity (PI3).
o Use the community routing ID from the message – Select this option to use the

message’s ReceiverRoutingID as community (caller) identifier.
o Use a specific community routing ID –Select this option and choose one of the
available Community’s routing IDs to identify the community (caller) identifier to use.
o Use Password (This is the password the server expects) – Select this option and
choose one of the available Community routing IDs to specify the community (caller)
identifier to use.
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 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 server. This is the password you expect from the
back-end server).
PeSIT parameters tab

This tab is identical for PeSIT application and trading d elivery exchanges.
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 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
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.
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.

client can make to a partner. If you are operating in a cluster environment, this is the total

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
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.
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.
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 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).
listed.
digest algorithm.

needed to resubmit messages to applications or resend messages to partners.
Add or modify a PeSIT application pickup

(embedded server)
Add a PeSIT application pickup (embedded server)
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.

4. Select the From address and To address that match your needs.

5. Select Define a new embedded PeSIT server and click Next.
6. Complete the fields of the Configure the PeSIT server page.
l Server name – Enter a name for the new embedded PeSIT server. This is the name that
appears in the embedded servers list.
l Port – Enter the port on which the server will listen. This must be a free port on the
machines of the cluster.
l Access to this server requires a password – If you want the back-end application to
provide a password to connect to your server, choose this option, and then enter the
required password.
l Clients must use SSL to connect to this server – Select this option if you want to
secure the connections to your server over SSL/TLS. You will need to add a server certificate
and private key for this server.
o This server requires client authentication – Select this option if you require the
client to authenticate itself with its own certificate when connecting (mutual
authentication). This means you must import the client’s certificate to the community’s
personal certificate list. If you want to use the pickup for multiple communities, you
must import the same certificate to each community
7. 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.
8. Click Finish.
Modify a PeSIT application pickup (embedded server)

When you add an exchange, the exchange wizard prompts you to provide a basic set of parameters.
After you create the exchange you can open the maintenance page for the exchange to view and
manage a comprehensive set of parameters for the exchange. Some of these parameters were
automatically set when you added the object, and can only be modified after you add the object.
Procedure
configuration.
that community.
3. Click Trading pickup in the navigation graphic to open the Delivery exchanges page.

PeSIT application pickup maintenance fields

(embedded server)
PeSIT server settings tab

l Click the View setting for this embedded server link to view the server configuration. This
link describes the server whose address and port is displayed in the Local connection string
field.
l Access to this server requires a password – Select this option if you want the back-end
client to provide a password in order to connect to this server. Enter and confirm the required
password.
l Send acknowledgments for messages received by this exchange – Select this option if
any application expects an acknowledgment.
For each application that expects an acknowledgment:
o In the Inbound sender field, enter the caller identity (PI3) used by the application to
connect. If you do not enter a caller identity, no acknowledgements are sent on this
exchange.
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
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 Maximum file size – Enter the maximum file size in bytes. Do not use commas.

Add or modify a PeSIT application pickup

(polling client)
Add a PeSIT application pickup (polling client)

Use this procedure to add an application pickup for polling a back-end P eSIT server.
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
Procedure
configuration.
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.
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.
10. Click Finish.
Modify a PeSIT application pickup (polling client)

When you add an application pickup, the wizard prompts you to provide a basic set of parameters.
After you create the pickup you can open the maintenance page to view and manage a
comprehensive set of parameters for the pickup. Some of these parameters were automatically set
when you added the object, and can only be modified after you add the object.
Because the polling pickup must expose its identity to the polled server, it must be linked to a
community.

configuration.
that community.
3. Click Application pickup in the navigation graphic to open the Application pickup exchanges
page.
4. From the list of available exchanges, click the name of a PeSIT exchange to open the
maintenance page for that exchange.

PeSIT application pickup maintenance fields
PeSIT settings tab

l Hostname –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 Clients must use SSL to connect to this server – Select this option 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.
import the server certificate chain in the community'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 community's trusted SSL root
certificates.
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).

PeSIT polling parameters tab

Use this tab to set the parameters for the PeSIT SELECT polling command.
This tab is identical for PeSIT application and trading polling pickup exchanges.
l File name (PI12) – Mask of the files to poll. For example, enter "test" to poll only the files

named “test”. You can use the wildcard character at the end of any character string. For
example, enter "test*" to poll all files that begin with the string "test", including "test1', test_
myTest", and so on.
l File type (PI11) – Leave this value to 0, except if it has a special meaning for the remote
server. Check this setting with the remote PeSIT server administrator.
l Compression (PI21) – This compression option applies to the polled file, not on the request.
are compressed.
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.
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.

l Synchronization option (PI7):

o Intervals between sync points (Kbytes): Each time an amount of data equal to this
of the last successful check point. The default value is 1024 kilobytes (1 megabyte). Do not
change this value unless advised by the administrator of the PeSIT component. This
corresponds to pacing 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. Do not change this value unless advised by the administrator of the PeSIT
component. This corresponds to chkw in Axway Transfer CFT.
l Read timeout (seconds) – Time in seconds Interchange waits to read data from the pickup
before terminating the connection.
l Connection timeout (seconds) – Time in seconds Interchange waits for a connection to the
l Transfer timeout - caller mode (seconds) – Time in seconds a transfer times out.
l Network timeout (seconds) – Time in seconds the network times out.
l Protocol timeout (seconds) – Time in seconds the protocol times out.
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


l Polling interval – The interval, in seconds, Interchange waits before polling for messages to
retrieve.
In general, you should not use this setting. It is generally best to let Interchange automatically
transport servers.
Add or modify a PeSIT partner delivery
Add a PeSIT partner delivery

Use this procedure to add a delivery for sending messages to a specific trading partner using PeSIT.
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.
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.
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.
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.
Modify a PeSIT partner delivery

When you add a pickup or delivery, the wizard prompts you to provide a basic set of parameters.
After you create the pickup or delivery you can open the maintenance page to view and manage a
Procedure
1. In the Interchange user interface, select Partners > Manage partners.
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.
6. If you make any changes, click Save Changes.
PeSIT partner delivery exchange maintenance fields
PeSIT settings tab

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.
o Selected: The messages sent to this delivery stop in HeldForPickup state, available for
the remote client to fetch them.

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.
certificate sent by the server during the TLS handshake is the same as one registered on the
trading partner. You must have imported the server certificate chain in the partner’s personal
certificates and selected 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.
If you do not select this option, Interchange only verifies that the server certificate is signed
by a certificate that is included in the community’s trusted SSL root certificates. This means
that you must have imported the root certificate of the remote server in the community’s
trusted SSL root certificates.
o Enable CFT compatibility – When you select this option, the trading engine aligns the
PeSIT record size on TLS packets. This is the only method handled by Axway Transfer CFT
until version 3.0, and the default method for the Axway products Gateway and Interpel.
Attention: If you are using Secure Relay, this is not compatible with SSL security termination
in DMZ.
as it does for non TLS communications. This is the default behavior and the recommended
setting (when the remote partner handles it, and when it is compatible with Secure Relay’s
security termination in DMZ).
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 then 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.
o Change password – If you need to change the password for connection to the remote
partner server, enter and confirm the new password.
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 ReciverRoutingId from the message is different from 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 force to not expect a password from the
partner’s server, or set a specific password that is expected from the partner’s server.
PeSIT parameters tab

This tab is identical for PeSIT application and trading d elivery exchanges.
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 « 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 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
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
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.
pesit.recordLength.out.
l Compression (PI21) – Controls the compression of the file during the transfer (compression on
the fly). Select a compression method:
are compressed.

the compression setting, a lower type of compression or no compression is applied.
l Priority (PI17) – Select an option:
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.

client can make to a partner. If you are operating in a cluster environment, this is the total
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
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.
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
are trading with.
l Synchronization option (PI7) –
so on.
data received.
The default value is 3. In most situation this is the correct value.


listed.
digest algorithm.

Add or modify a PeSIT trading pickup

(polling client)
Add a PeSIT trading pickup (polling client)

Use this procedure to add a trading pickup to a community for polling a partner's P eSIT server.
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
configuration.
that community.
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.
9. Click Finish.

Modify a PeSIT trading pickup (polling client)

you create the pickup, you can open the maintenance page for the pickup to view and manage a
Procedure
configuration.
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.
PeSIT trading pickup (polling) maintenance fields
PeSIT settings tab

The trading side polling pickup configuration relies on a partner’s delivery exchange.
To change these settings, do one of the following:
Click on the Matching delivery exchange link to open the corresponding delivery exchange

maintenance page.
Click on Pick polling URL to select another partner delivery exchange.
l Community settings (Server)

o PeSIT Identifier (PI3) – Taken from the selected partner’s delivery exchange. You cannot
modify this field.
l Remote partner settings (server)
o Remote partner – Taken from the selected partner’s delivery exchange. You cannot modify
this field.
o Remote partner URL – The URL of the remote PeSIT server.
o PeSIT identifier – The PI14 value used as the remote partner identity in the
PeSIT message.

l Matching Delivery exchange – The delivery exchange (defined on the partner object) that

corresponds to this pickup exchange. Click the hyperlink to open the maintenance screen for the
partner delivery exchange.
l Acknowledge each fetched file – Select this option if the polled server expects an
acknowledgment for each fetched file.
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.
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.
PeSIT polling parameters tab

Use this tab to set the parameters for the PeSIT SELECT polling command.
This tab is identical for PeSIT application and trading polling pickup exchanges.
l File name (PI12) – Mask of the files to poll. For example, enter "test" to poll only the files

named “test”. You can use the wildcard character at the end of any character string. For
example, enter "test*" to poll all files that begin with the string "test", including "test1', test_
myTest", and so on.
l File type (PI11) – Leave this value to 0, except if it has a special meaning for the remote
server. Check this setting with the remote PeSIT server administrator.
l Compression (PI21) – This compression option applies to the polled file, not on the request.
are compressed.

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.
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.

l Max data unit size in bytes (PI25): – The largest of chunk of data, in bytes, to be
are trading with.
l Synchronization option (PI7):

so on.
data received.
The default value is 3. In most situations this is the correct value.

in process cannot be recovered if the server or a processing node stops or restarts.
l Polling interval – The interval, in seconds, Interchange waits before polling for messages to
retrieve.
In general, you should not use this setting. It is usually preferable 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.
Add or modify a PeSIT trading pickup

(embedded server)
Add a PeSIT trading pickup (embedded server)
Prerequisite
Procedure
configuration.
that community.
3. Click Trading pickup in the navigation graphic to open the Deliveries page.
4. Click Add a delivery exchange to open the exchange wizard (this represents a pickup from

the community point of view).
5. Choose the message protocol PeSIT and click Next.
6. Select Define a new embedded PeSIT server and click Next.
7. Complete the fields of the Configure the PeSIT server page.
l Server name – Enter a name for this embedded PeSIT server. This name appears in the
Embedded servers list.
l Port – Enter the Port on which the server listens. This must be a free port on the machines
of the cluster.
l Community settings (Server) – Set the default identity exposed by the server to the
partners.
o Allow any valid community routing ID – If you select this option, the client
connecting to this server can use any community routing ID as server ID (PI4).
o Restrict to specific community routing ID – If you select this option, the client
connecting to this server can only use the community routing ID you specify as server
ID (PI4).
o Use Password – Select this option if you must provide a password for connections to
the partner. Then enter the required password.

l Remote partner settings (caller)

o Use Password – Select this option if the partner must provide a p assword for
connections this embedded server. Then enter the required password.
l Clients must use SSL to connect to this server – Check this if you want to secure the
connections to your server over SSL/TLS. You must add a server certificate and private key
for this server.
o This server requires client authentication – Select this option if you require the
client to authenticate itself with its own certificate when connecting (mutual
authentication). This means you need to import the client’s certificate in the partners’
personal certificate list and check the option Trust this for SSL server and/or
client authentication. Interchange automatically adds the root certificate to the
linked community trusted SSL root certificates.
9. Click Finish.
Modify a PeSIT trading pickup (embedded server)

When you add an exchange, the exchange wizard prompts you to provide a basic set of parameters.
After you create the exchange you can open the maintenance page for the exchange to view and
manage a comprehensive set of parameters for the exchange. Some of these parameters were
automatically set when you added the object, and can only be modified after you add the object.

configuration.
that community.
3. Click Trading pickup in the navigation graphic to open the Delivery exchanges page.
PeSIT trading pickup (embedded server)

maintenance fields
PeSIT server settings tab

l Click the View setting for this embedded server link to view the server configuration. The
linked page describes the server whose address and port are displayed in the Local connection
string field.

l Community settings (Server) – Set the default identity exposed by the server to the partners.

You can override or restrict the following settings per partner through the partner PeSIT delivery
exchange(s).
o Allow any valid community routing ID – If you select this option, the client connecting
to this server can use any of the of the community routing IDs as server ID (PI4).
o Restrict to specific community routing ID – If you select this option, the client
connecting to this server can only use the community routing ID you specify as server ID
(PI4).
o Use Password – Select this option if you must provide a password for connections to the
partner. Then enter the required password.
l Remote partner settings (caller) – You can override or restrict the following settings per
partner through the partner PeSIT delivery exchange(s).
o Use Password – Select this option if the partner must provide a p assword for connections
this embedded server. Then enter the required password.
l Send acknowledgments for messages received by this exchange – If you select this
option, the server sends an acknowledgment to the partner when it receives a file successfully.
This occurs when the corresponding message is correctly unpackaged. This is a protocol level
acknowledgement, which indicates only that Interchange has correctly received the file.
Advanced tab
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 Maximum file size – Enter the maximum file size in bytes. Do not use commas.
PeSIT send and fetch using an MMD

You can use an MMD to issue a send or fetch to a trading partner side PeSIT server. To do this you
require two delivery exchange types:
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:

<MessageMetadataDocument protocol="generic" documentId="PeSIT_Select">
<Metadata name="Action">Fetch</Metadata>
<Metadata name="From" type="string">PESITA</Metadata>

<Metadata name="To" type="string">NEWYORK</Metadata>
<Metadata name="pesit.filename">ID*</Metadata>
<Metadata name="pesit.fileType">0</Metadata>
<Metadata
name="pesit.max.xfers.per.polling.interval">2</Metadata>

PGP secure trading

The following topics are about using Interchange to securely trade messages with Pretty Good
Privacy (PGP) certificates.
Can you use PGP?

You can use PGP certificates if your software license enables this functionality. To check, select
Help > License information on the toolbar in the user interface.
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.
Add a PGP pickup or delivery

PGP certificates can be used only with special PGP trading pickups and deliveries for FTP and SFTP.
These are exchanges for sending messages to partners (set up in partner objects) or consuming
messages from partners (set up in communities). The use of PGP for picking up from, or routing
messages to a back-end system is not supported.

Add a PGP trading partner delivery

1. From the Partners page select a partner to open the Summary page for that partner.
2. On the navigation graphic at the top of the page, click Partner delivery.
3. Click Add a delivery to launch the exchange wizard.
4. Select PGP (FTP, SFTP) and click Next. You must select PGP. Do not select AS3 or any other
message protocol that supports FTP and SFTP.
5. Select FTP or SFTP, then click Next and follow the prompts.
The subsequent steps are identical to adding any FTP or SFTP partner delivery. See Exchange links
below for links to details of setting up and maintaining FTP and SFTP exchanges.
Add a PGP trading partner pickup

1. From the Communities page select a community to open the Summary page for that
community.
2. On the navigation graphic at the top of the page, click Trading pickup.
3. On the Trading pickups page, click Add a pickup to launch the exchange wizard.
4. Select PGP (FTP, SFTP) and click Next. You must select PGP. Do not select AS3 or any other
message protocol that supports FTP and SFTP.
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.
Exchange topic links

‘From’ and ‘To’ address settings

For community trading pickups, follow the usual guidelines for “from” and “to” addresses. Use these
so Interchange can identify senders properly.
l If EDI messages are traded, select Always parse for the address and select the option: If

the document is EDI, parse for the address.

l If XML messages are traded, select Always parse for the address and select the option: If

the document is XML, use XPaths to locate the address. Select a document type and its
corresponding XPath. If your type is not listed, click XPath to use a wizard for setting the XPath
using your sample of an XML document.
l To trade binary messages, select Specify the address and select the fixed address.
Manage PGP certificates

PGP certificates must be associated with every community and partner engaged in secure trading via
PGP. The following topics cover PGP certificate management.
Add a PGP certificate for a community

Use this procedure to add a PGP certificate and associate it with a community. A community needs
at least one PGP certificate to exchange messages with partners using PGP for encrypting and
signing messages.
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.
Create or add a PGP

1. Click Certificates on the navigation graphic on the community summary page to display the
certificates page. Click the task Add a PGP certificate near the bottom of the page to launch
the PGP certificate wizard.
2. Select an option and click Next:
l Create a PGP certificate. Select this to have Interchange generate a self-signed PGP
certificate. Go to step 3.
l Import a PGP secret keyring. Select this to have Interchange import a PGP certificate
that has been generated by an external, third-party PGP tool. Go to step 4.
Generate self-signed PGP certificate

3. If you selected Create a PGP certificate in step 2, complete the fields and click Finish. You
can accept the default values or choose your own.
Typing a name for the certificate is optional. It does not matter whether you select RSA or DSA
as the algorithm key type. But DSA keys take longer to generate.
The following are the available encryption key lengths:
512 Normal encryption

1024 Strong encryption. 1024 or higher is recommended for high-value EDI transactions
2048 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.
Import a PGP secret keyring from a file

4. If you selected Import a PGP secret keyring in step 2, complete the fields and click Finish.
Click Browse to select a private keyring file. File extensions of keyring files vary depending on
the external PGP tool used to generate them. Examples for private keyrings are GPG and SKR.
Type the passphrase that protects the private keyring. If there are multiple keys in the keyring,
all must use the same passphrase.
Select default PGP certificate

5. Make sure the community has a default PGP certificate. If a community has only one PGP
certificate, Interchange makes it the default. But if a community has two or more, you can pick
one as the default for signing and encrypting messages. The following are the steps:
a. Click Certificates on the navigation graphic on the community summary page to display
the certificates page.
b. Select the PGP personal certificates tab.
c. Select a PGP certificate from the drop-down list and click Save changes to make it the
default.
Export a community PGP certificate

Use this procedure to export a community PGP certificate and its key to a file. You must do this if
your partner uses an interoperable gateway other than Interchange.
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.

4. Click the task Export this certificate near the bottom of the page.

5. Select one of the following:
l PGP public key. This option is recommended and enables you to provide a secure public
key to your partner.
l Complete PGP key.
Caution: Select this option only if you must export your private key and understand the
security risk. Ensure you provide and confirm a password.
6. If you want to export the certificate in binary format, clear the Export output in an encoded
ASCII format (ASCII-armored) check box.
7. Click Export and select the location where you want to save the file.
8. Give the file to your trading partner. If you send the file by email, use WinZip or another
compression tool to compress the file before sending. This is to protect the file integrity.
Import a PGP certificate for a partner

Use this procedure to import a PGP certificate and its public key for a partner profile. You must do
this if your partner uses an interoperable gateway other than Interchange.
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.

PGP certificate field descriptions

You can open a page to view details of PGP certificates used by communities and partners.
For a community, use the PGP personal certificates tab to view or change the default PGP certificate.
You also can add or delete PGP certificates and view details about the certificates.
For a partner, details about PGP certificates can be viewed on the PGP certificates tab.
You cannot use the certificates page at System management > Manage certificates to search

for PGP certificates. That page only is for X.509 certificates.
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.
PGP collaboration settings

The level of security for packaging outbound PGP messages is controlled by collaboration settings.
PGP messages by default are sent encrypted, signed and with PGP armor engaged. The defaults are
described in PGP default settings on page 923. Overall message packaging is described in
Collaboration settings on page 909.
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.
Can you use RosettaNet?

You can use RosettaNet if your software license enables this functionality. To check, select Help >
License information on the toolbar in the user interface.
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.
RosettaNet configuration outline

The following outlines the steps for configuring a community to trade via the RosettaNet protocol.
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.
Add DTD-based PIP

Use this procedure to use a DTD-based PIP not already supported by Interchange.
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.

Add schema-based PIP

Use this procedure to use a schema-based PIP not already supported by Interchange.
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.
Configure pipdefinitions.xml file

The pipdefinitions.xml file is the key for configuring Interchange for RosettaNet trading,
although other steps are required as well. The file defines the business messages to be traded for
each PIP and the order in which each message is sent or received. Interchange uses the definitions
to validate RosettaNet messages and the trading order.
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.

<PipDefinitions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="pipdefinition.xsd" dtdValidation="off"
guidelineValidation="off">
<Pip code="0C2" name="Asynchronous Request-Confirm" version="R01.02">
<Activity name="Asynchronous Test Request" retryAttempts="3">
<Action name="Asynchronous Test Request Action" dtd="0C2_MS_R01_
02_AsynchronousTestRequest.dtd"

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">
</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">
</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">
</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.
RNIF metadata elements

The following are the available RNIF metadata elements. These elements can be used as message
attributes for delivery exchanges, in inline processes or in MMDs. For MMDs, however, there are
some usage exceptions (see MMD elements on page 710).
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.
Message metadata documents

In file system integration with a back-end system, Interchange supports RNIF using message
metadata documents (MMDs) as the interface between it and the back-end. The MMDs are XML
documents that point to a RosettaNet document on a file system and contain information
Interchange uses to process documents.
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="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>
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.
Special handling of metadata

Because of vagaries in the RNIF standard, Interchange has devised a way to pass the
GlobalUsageCode and PipInstanceId to and from back-end applications. There are two use cases:
with MMDs and without MMDs. You need these so that your back-end system can deal with either
case.
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>
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.
DTD-based service contents

When enabled, the following field is parsed:
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.
Schema-based service contents

If enabled, the following field is parsed:
/*/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.
Trade CIDX messages

To trade Chemical Industry Data Exchange messages, you must complete the usual steps to add
CIDX PIP DTDs to the conf\rosettanet\dtds directory and edit the pipdefinitions.xml to
file to include the PIPs. In addition, you must use the CidxPackaging attribute to flag payloads as
CIDX messages. The attribute must have a value of true. You can use only the RosettaNet 1.1
message protocol to trade CIDX messages.

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.
Web Services roles

Web Services Provider
A Web Services Provider creates and exposes a service and can publish the availability of
the WSDL that describes the service.
Web Services Consumer
A Web Services Consumer discovers a desired service and launches a request to the service
provider.
Web Services Relay
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.
Interchange Web Services support

Interchange supports:
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

Interchange Web Services provider mode

For Web Services provider mode, Interchange supports the following features:
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.
Interchange Web Services consumer mode

For Web Services consumer mode, Interchange supports the following features:
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
Web Services provider configuration

overview
The purpose of a Web Services provider mode configuration is to expose a service to one or more
partner consumers. In this mode, the Web Service provider acts as a server, responding to requests
from partner clients.
Illustrations and descriptions

The following figures illustrates schematically how Interchange processes requests from remote Web
Service consumers.
Example 1: Two way service, synchronous response


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.
Example 2: One way service
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:

l Define the content of the Web Service - This involves specifying the format of both the

request for the service, and the response to the request. The message content of Web Services
exchanges is exchanged in XML formatted files. The format of these files is defined by XML
schemas.
l Define a communications framework – This involves specifying the transport protocol and
access parameters that enable consumers to inject messages into your system, and for you to
respond to those messages. Communications with your Web Service Partners is done over HTTP.
Web Services consumer configuration

The purpose of a Web Service consumer mode configuration is to enable Interchange to connect to
a Web Service that is exposed by a remote provider. You can inject the data that you retrieve in the
form of a Web Service response directly into Interchange processing flows.
In this mode, Interchange behaves as a client requesting a service from a remote server.
Overview of the configuration

To set up Interchange to consume Web Services from a remote Web Service provider, you use the
provider's WSDL in the Interchange user interface to generate information for the exchange.
Illustration and description

The following figure illustrates schematically how Interchange processes requests to remote Web
Service Providers:
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
Task 1: Add a community

Add a Community to represent your organization as a trading endpoint. See Add a community on
page 136.
Task 2: Add a partner

Add a partner to represent the Web Services provider server. See Add a partner to a community on
page 148.
Task 3: Add a Web Service trading delivery and Web

Service connection
About this task

A trading delivery is an object that specifies how you want your local community to send
messages over the Internet to a remote partner. For Interchange Web Services consumer mode,
Interchange uses the Web Services trading delivery in a special way.

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.
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 This server requires a user name and password — Select this option if the partner's
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.

After you complete this procedure

l Interchange adds a trading delivery to the list of available trading deliveries.
l Interchange adds a connection that refers to the delivery. To view the connection's properties,
go to Processing configuration > Manage connections and click the name of the
connection that you just created.
You will use this connection in a later step to link a map type component to the trading delivery
for Web Service request/response calls.
l Interchange adds Web Services collaboration settings that are specific to the trading delivery.
Collaboration settings specify how Interchange packages the messages that a community sends
to its partners. For more formation see Default collaboration fields on page 911.
Web Services collaboration settings

Use community collaboration settings to control how outbound Web Services messages are sent to
partners.
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.
View and modify settings

To view the collaboration settings that control sending of messages to a Web Services partner:

2. Select the community you use for Web Service exchanges.
3. On the community map of the community summary page, click the Collaboration settings
icon.
In the left panel, the interface displays a tree structure that shows a node for each partner that is
linked to the community and a child node for each delivery exchange that is defined between
the partner and the community. For example:

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.
Web Services related settings

Sender routing ID
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
Send handler Name of the file in the <install directory>\conf directory used

config file when packaging a 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.
You can create a customized version of this file for outbound
messages, however, doing so requires the aid of a professional services
consultant, or obtaining the optional Software Development Kit, or
both.
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.
Receipt signing certificate
From the drop-down list of available certificates, select the certificate to use for signing
receipts to this partner.
Partner encryption certificate
From the drop-down list of available certificates, select the certificate to use for encrypting
files sent to this partner.
Specify the delivery to send messages to
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.
Web Services message protocol

Communities can use the Web Services message protocol to trade messages with partners. The Web
Services framework enables you to send and receive SOAP messages with payloads:
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.
Default packaging configuration

Under the default configuration for packaging:

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.
Default unpackaging configuration

Under the default configuration for unpackaging:
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.
Web Services transport user accounts

Web Services exchanges can optionally require user names and passwords in a UsernameToken
element in the SOAP header. Within communities, you can specify different types of Web Services
user accounts:
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:
1. In the user interface, from the Trading configuration menu, select a Community to open the

Summary page for that Community.
2. On the Community map of the community summary page, click the Collaboration settings
icon to open the Configure community-specific collaboration settings page.
3. In the Choose the settings to specialize list, select the Set sending rules for the Web
Services message protocol option.
4. In the Define the settings this community will use to send messages list, select the
Use MTOM to encode messages option, and then select one of the following associated
options:
l Select XPaths to encode — Enter the Namespace prefix of the node, the Namespace
URI of the node, and the Local xpath of the 64-bit encoded content found in the
message. Click Add if you want to add information to optimize any additional nodes.
l ID refs to encode — Enter an attribute within the node, such as the ID of the node, for
example: //@id. Click Add to add additional attributes.
5. Select Save changes.
Lockout settings for Web Services

(HTTP embedded) users
You can set the number of times a Web Services user can attempt to connect to an embedded Web
Services server with an invalid password before Interchange locks out the user. This is a safeguard
against possible efforts by unauthorized users to access the server.
Set lockout rules

Use this procedure to set the lockout rules for an embedded Web Services server. The rules apply to
all Web Services users.

settings page.
3. Select the Global Web Services settings tab.


Use this procedure to unlock a locked out user of an embedded Web Services server before the
lockout interval expires.

Troubleshoot Web Services configurations

Problem: The WS-Addressing standard assumes that the From and To fields are URLs of the Web
Service requester and receiver. However, Web Services trading between two Interchange endpoints
typically use AS2-based routing ID’s (ZZHOME, ZZAWAY). Messages between Interchange and third-
party Web Service providers using WS-addressing may fail.
Solution: WS Addressing expects URL’s, not AS2 style routing ID’s: When Web Service addressing
is expected to identify the sender, select the pickup option Address must be determined by
either message attribute configuration or by protocol address only to determine From
and To parties for each message. Depending on whether the partner's WS-Addressing is expecting a
URL or a routing ID, you may need to add the expected URL as an alternate routing ID in the
community and partner settings and set them as default, or use Collaboration settings to specify the
desired ID to use when replying to that party.

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.
Configuration of the Interchange

environment
conflicts.
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:


WebSphere MQ multiple instances

WebSphere® MQ supports the creation of a multi-instance queue manager. A multi-instance queue
manager restarts a WebSphere MQ (MQSeries) server instance automatically on a standby server
when the active instance goes down.
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.
New pickup or delivery

1. Log on to the Interchange user interface.
2. Create an IBM MQ pickup or delivery (application or trading partner).

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.
How the multi-instance functions

Interchange tries to send or receive every message to the last functional WebSphere MQ (MQSeries)
server. WebSphere MQ has a cache where the status for each exchange point is registered. If the
primary instance crashes, Interchange automatically tries to connect to the standby instance. If the
standby is not running, the message is re-queued. The message is then held for a new retry. This
provides time for the standby instance to become active. If the standby is still not available, the
message goes through additional re-queue and retries. The time between the retries increases for
each queue/retry cycle. When the maximum number of retries is reached (defined in the queue
manager configuration), the message is rejected.
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.
Can you use X.400?

You can use X.400 if your software license enables this functionality. To check, select Help >
License information on the toolbar in the user interface.
Operating system exception

X.400 delivery exchanges can be used on computers running any of the operating systems
supported for Interchange, with the exception of Solaris 10 (x86).
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
Pages and fields

l Modify an x400 pickup or delivery on page 744
l Subsystem settings for X.400 server on page 752
l MSP7 for an X.400 server on page 759
l P7 client polling schedules on page 760
l Remote MTA for an X.400 server on page 761

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.

Do you use HP-UX?

If the X.400 subsystem is to be used in an HP-UX clustered environment, and the NFS server
supporting the cluster is enforcing lock authentication, the HP-UX NFS client may need to be
changed to support lock authentication by setting the LOCKD_AUTHSYS_CRED option. See the HP-
UX lockd(1M) man page for more details.
Valid characters for O/R addresses

Originator/recipient (O/R) addresses identify message senders and receivers. An O/R address
consists of required and optional values organized hierarchically. Only valid characters can be used
in O/R addresses. All alphanumeric characters are valid in addition to the following:
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
X.400 trading configuration

A community can use the X.400 subsystem to exchange messages with partners. The following
related topics describe the fields in the delivery exchange wizard for adding an X.400 delivery
exchange and embedded servers for a community and a partner.
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.
Community X.400 pickup

The following describes the fields in the exchange wizard for adding an X.400 pickup for a
community. The fields are the same for X.420 and X.435.

Enter X.400 settings

l Name – The name for the X.400 subsystem. This can be any name you want.
Subsystem ports
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.

Enter X.400 subsystem settings URL

l External hostname – c omputer 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.
instances of Interchange, the partners will send messages to the port specified in this field.
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
Partner X.400 delivery

The following describes the fields in the exchange wizard for adding an X.400 delivery to a partner.
The fields are the same for X.420 and X.435.
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.
For a list of codes see the International Organization for Standardization (ISO):
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.
Choose remote MTA type

On this wizard page select whether to use an existing remote message transfer agent or to add one.
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.
Enter remote MTA settings

l Name – Name of the remote MTA.
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.
l TCP host – The fully qualified domain name or IP address of the remote message transfer agent.
l TCP port – The port the remote message transfer agent listens for connections.
l TCP address – If a TCP address, the fully qualified domain name or IP address of the host and
the listening port number.
l X25 address – If an X.25 address, the fully qualified domain name or IP address of the host.
l TSAP – The transport services access point.

Modify an x400 pickup or delivery

After using the pickup or delivery wizard to add a transport, you can use maintenance pages to
change, test, activate, deactivate or delete community or partner exchanges. The wizard and
maintenance pages have many of the same fields. But, generally, the wizard only has the most
commonly used fields for a transport. The maintenance pages have all of the fields. After using the
wizard to add a transport, you may have to go the transport’s maintenance page to fine-tune the
configuration.
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.
X.400 and X.435 settings tab (community)

l X.400 subsystem – The name of the X.400 server. This name was set when the exchange was
added in the exchange wizard. You can click the name to open a page for viewing or changing
settings for the embedded server. But you cannot change the server name.
l Alias/Routing ID – Depending on whether the delivery exchange 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 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.
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.
instances of Interchange, the partners will send messages to the port specified in this field.

l Subset address used – If not selected, messages are accepted only when the address

attributes in the message recipient O/R address exactly match the address attributes defined for
the partner.
If selected, messages are accepted when the address attributes in the message recipient O/R
address at least match the address attributes defined for the partner. That is, a message is
accepted even when the received address contains additional address attributes. This is what
makes the defined address for the partner a subset address.
X.400 O/R address
the code of the partner’s country. For a list of codes see the Website for ISO (International
Organization for Standardization): http://www.iso.org/iso/home.html.
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.
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 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.
l Domain-defined attribute value address attribute 1 – DDA value for attribute 1.
l Domain-defined attribute type address attribute 2 – DDA type for attribute 2.


l Surname address attribute – The last name of the originator or the recipient.
l Given name address attribute – The first name of the originator or the recipient.
l Initials address attribute – The middle initial of the originator or the recipient.
l Generation Qualifier address attribute – Last name suffixes such as Sr., Jr., II or III.
l Message transfer system – Select whether this delivery exchange uses a local message
transfer agent or an external message store to receive messages.

available.
integration.

plus the interval.
specify otherwise.
Restrict maximum file size for this transport – Optionally lets you specify the maximum

Maximum messages per connection – This value specifies the maximum number of

configured.
messages.
transport servers.
X.400 and X.435 settings tab (partner)

l Alias/Routing ID – Depending on whether the delivery exchange 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 Community exchange point – The name of the embedded server designated for this delivery
exchange. Click to open the drop-down list to select another server, if available. Click Edit to
view or change server settings.
l Remote MTA – The name of the remote message transfer agent for sending messages.
For a list of codes see the Website for ISO (International Organization for Standardization):
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

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
l Private Domain Name – Identifies a private domain name (PRNM) relative to the
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 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.

l Surname address attribute – The last name of the originator or the recipient.
l Given name address attribute – The first name of the originator or the recipient.
l Initials address attribute – The middle initial of the originator or the recipient.
l Generation Qualifier address attribute – Last name suffixes such as Sr., Jr., II or III.
l Public key (X.435 only) – If specified, this is the key for signing receipts or messages when
collaboration settings specify class 3 or class 4 (see X.435 default settings on page 930). Obtain
the public key file from your trading partner. Your partner also has the corresponding private
key.
If you upload a key, click Save changes.


available.
integration.
plus the interval.

Backup files are stored in <install directory>\common\data\backup, unless you specify
otherwise.
commands. This field is available for partner trading deliveries.
X.400 (embedded) servers

After setting up a delivery exchange that uses an embedded server, you can change the server’s
settings.
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:
l Select System management > Manage embedded servers on the toolbar.

l Click Trading configuration on the toolbar. On the Communities page, click the link near the
bottom named Manage all embedded servers.
l Click System management on the toolbar. On the System management page, click the link
near the bottom named Manage embedded servers.
Another path to perform embedded server maintenance is to open a community summary page and
click the link near the bottom named Change an embedded transport server. This opens a
page that lists all servers used by that community only.
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.
About X.400 over X.25

The X.400 subsystem supports sending and receiving messages over X.25 in addition to TCP. You
can select the X.25 option when editing an X.420 or X.435 embedded server (see Subsystem
settings for X.400 server on page 752, Network protocol type). You cannot elect X.25 in the
delivery exchange wizard when adding an X.420 or X.435 transport.
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.
Subsystem settings for X.400 server

The subsystem settings fields for X.420 and X.435 embedded servers are the same except as noted.
l Name – The name of the server. This was set in the delivery exchange wizard. You cannot
change this name.
l Host – The computer on which the server runs. You cannot change this. When Interchange runs
in a clustered environment, X.400 subsystems are distributed dynamically across the cluster.
This means this host value can change on its own.
l Network protocol type – Select whether the server transports over TCP, X.25 or both. The
fields on the tab adjust according to the option selected. See for About X.400 over X.25 on page
752 more information about X.25.
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.

l Incoming X.121 address – The listening X.121 address, including sub-address, for incoming

X.25 calls. The X.121 address is often referred to as the X.25 network user address (X.25 NUA).)
Your DNIC code should not be defined unless you also define the network prefix.
l Outgoing X.121 address – The X.121 address for outgoing calls.
l Link ID – The name of the X.25 card.
l Call user data – Used for outgoing and incoming connections. call user data (CUD) is
appended to a call request for outgoing connections. If a CUD is specified, this CUD is required
for all incoming connections. For use with X.400, this value must always be set to 03010100.
l Min poll interval (ms) – The minimum time in milliseconds between samplings. This applies
only to AIX computers.
l Max poll interval (ms) – The maximum time in milliseconds between X.25 samplings. This
applies only to AIX computers. If set to a small value, X.25 traffic is handled faster at the cost of
higher CPU load. As long as there is regular X.25 traffic, this time automatically adjusts, so that
only the first package can be delayed by the value of this parameter.
l Poll increment – The number of steps to increment between maximum and minimum polling
intervals. This applies only to AIX computers.
l Log size (bytes) – The maximum size of the log file. When the X.25 log file reaches the
maximum size, logging continues in a new file.A value 0 indicates the size of the log file is
unlimited.
l Clear log on restart – Select whether to clear the log file when the system is restarted.
l Log level – Select the level of events to write to the log file. Options are listed from the least to
most verbose logging levels.
Subsystem internal ports

l System starter port – 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 port – The listening port for the lower layer OSI stack process within the X.400
subsystem.
l User agent port – 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.
Subsystem security (X.435 only)

l Private key – If specified, this is the key for verifying signatures of receipts or messages when
collaboration settings specify class 3 or class 4 (see X.435 default settings on page 930). The
signing is performed by the corresponding public key, which your community must provide to
your trading partner. The public key is specified on the X.435 settings tab of the partner X.435
delivery exchange.

o Private key file – The path of the private key file to upload. If you upload a private key,

click Save changes.
o Private key description – Optionally, a description of the private key.
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.

l Maximum connection response time (ms) – Maximum time in milliseconds the transport

protocol layer waits for a connection accept or reject response from the application after
receiving an incoming connection request and passing the request to the application.
l TS1 time (ms) – The time in milliseconds to wait for an answer to a transport connect request.
If an answer is not received within this time, the network connection is disconnected.
l Buffer size (bytes) – The memory each transport connection can use for transport protocol
data unit (TPDU) buffers.
l Maximum TPDU size (bytes) – The maximum TPDU size proposed on an outbound connect
request.
Local message transfer agent

l MTA name – The name of the message transfer agent.
l TSAP – The transport services access point.
For a list of codes, see ISO (International Organization for Standardization):

l Private domain name – Identifies a private domain name (PRNM) relative to the
l Organization – Identifies an organization relative to the PRNM.
l Organization unit – Identifies units such as divisions and departments within the
organization.
l Delivery period (seconds) – The interval the MTA process checks the inbound queues of UAs.
If the receiving UA does not read an inbound message, the MTA removes the message from the
UA delivery queue and sends a non-delivery message to the sender, if requested.
l Poll period (seconds) – The interval the MTA polls for inbound messages. Messages from UAs
and the MTC process are put in the in-queue. The poll interval is used only when the queue is
empty. If the queue is not empty, all messages are processed before polling restarts.
l Transfer time (seconds) – The maximum time allowed for a message to send from one MTA to
another. If the time is exceeded, the transmission fails and the connection is released.

l Maximum number of connection attempts – The maximum times the MTC process should

try to connect to an MTA. If the connection fails, a non-delivery message is sent to the UA that
had this MTA as the destination for messages. If the value is 0 or 1, only one attempt is made.
l Maximum attempt timer (seconds) – When a connection attempt fails, this value specifies
how long to wait before attempting again to connect.
l Maximum inbound connections – The maximum number of simultaneous incoming
connections the MTC can accept. If reached, any new connection are rejected with a reason
code indicating temporary congestion.
l Maximum outbound connections – The maximum number of simultaneous outgoing
connections the MTC can make.
Note: Maximum inbound connections and Maximum outbound connections distribute
network resources when using X.25. Every X.25 subscription has a limited number of logical
channels available. Logical channels enable multiple simultaneous virtual circuits (connections)
to exist across one physical link. In short, the X.25 supplier limits the number of simultaneous
connections. The fields specify the number of logical channels to use in each direction to:
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.

l Keep delivery reports time (hours) – Instructs the MTC process not to discard delivery

reports when the maximum number of connection attempts has been reached. When the MTC
process fails to connect to a remote MTA after the configured number of attempts:
o All messages, notifications and reports are removed from the message-out queue.
o A non-delivery report is sent for all messages and UA notifications.
o All reports are discarded.
If this parameter is used, all reports are kept in the message-out queue. The MTC process keeps
trying to connect to the remote MTA once an hour.
The value of the hours argument specifies the number of hours during which the MTC process
attempts to re-send delivery reports. The value must be a whole number greater than zero.
l Keep notifications time (hours) – Instructs the MTC process not to remove any X.420 or
X.435 notifications from the message-out queue when the maximum number of connection
attempts is reached. When the MTC process fails to connect to a remote MTA after the
configured number of attempts:
o All messages, notifications and reports are removed from the message-out queue.
o A non-delivery report is sent for all messages and notifications.
o All reports are discarded.
If this option is used, all X.420 or X.435 notifications sent from the local UAs are kept in the
message-out queue, and the MTC process keeps trying to connect to the remote MTA once every
hour. The value of the hours argument specifies the number of hours during which the MTC
process attempts to re-send notifications. The value must be a whole number greater than zero.
l Minimum transfer speed (bytes/second) – Specifies the lowest expected network transfer

speed. The process to calculate maximum transfer times uses this value. A message transfer is
aborted when the maximum transfer time is exceeded. Use this option only when there is a
problem with transfer time-outs and the value should not be increased.
l MTC usage – Indicates whether messages can be sent in one or both directions on the same
connection between two MTAs. Most often used is the monolog (one direction) option. Seldom
used is two way.
MTA logging

MTC logging
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.
l Time to keep sending notifications (hours) – Instructs the MS client task not to remove

any X.420 or X.435 notifications from the message-out queue when the maximum number of
connection attempts is reached. When the MS client task fails to connect to a remote MS after
the configured number of attempts:
o All messages and notifications are removed from the message-out queue.
o An internal non-delivery report is sent for all messages and notifications.
If this option is used, all X.420 or X.435 notifications sent from the local UAs are kept in the
message-out queue. The MS client task keeps trying to connect to the remote MS once an hour.
The value specifies the number of hours during which the MS client task attempts to re-send
notifications.

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.
DMZ ports tab


See Enable port forwarding for an exchange on page 484 for more information.
MSP7 for an X.400 server

The following describes the fields for adding or editing an external message store for retrieving or
delivering messages. The fields are the same for adding an P7 client for an X.420 and X.435 server.
Once you add an external message store, you must add at least one polling schedule. See P7 client
polling schedules on page 760.
l TCP host – The fully qualified domain name or IP address of the computer running the external

message store.
l TCP port – The port the external message store listens for connections.
l Remote MSP7 password – Password the local MSP7 uses to access the remote MSP7.
l Local MSP7 password – Password the remote MSP7 uses to access the local MSP7.

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.
Advanced MSP7 parameters

l Time between submission – Seconds between message submissions. At the interval the UA is
checked for messages to send. If so, a connection is made and all messages are sent. If the field
is set to 0, messages are submitted immediately after the UA has made a submission request.
l Maximum inactivity time – Duration in seconds the P7 client keeps open an inactive MS
connection. If the field is set to 0, a connection is released when all MS operations are done.
l Maximum connection attempts – Maximum times the P7 client attempts to connect to the
MS. If exceeded, all messages waiting for submission are returned to the UA as non-deliverable.
l Time between connection attempts – Time in seconds the P7 client waits before

attempting a connection to the MS following a failed attempt.
l Poll at submission – When selected, the P7 client can poll for messages immediately after
message submission but before the next polling interval.
l Submit at poll – When selected, the P7 client can submit messages immediately after polling a
mailbox but before the connection is released.
l Auto alert – When selected, the P7 client enables MS auto alerting. This tells the MS to inform
the P7 client immediately when a message or report has arrived in the user’s mailbox. Upon
receiving the alert, the P7 client retrieves the message or report.
The alert is only sent on an existing connection initiated by the P7 client. Auto alerting is used
only when Maximum inactivity time (described earlier in this section) is greater than 0.
P7 client polling schedules

A P7 client running within an embedded X.400 server must have at least one polling schedule. You
can set up multiple schedules to start and stop polling at various times or a single schedule that polls
continuously at a regular interval.

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.
Remote MTA for an X.400 server

The following describes the fields for adding or editing a remote message transfer agent for an
X.400 server. The fields are the same for an X.420 and X.435 server.
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.
Connect to an Administration Management Domain

(ADMD)
When selected, the following field displays.

l Private domain name – Identifies a private domain name (PRNM) relative to the
l Organization unit – Identifies units such as divisions and departments within the
organization.
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.

X.400 log events

You can review logs written by Interchange and the X.400 subsystem when troubleshooting X.400
issues.
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:
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:
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

Certificates and keys
12
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 you exchange over the public Internet.
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.
Do you use PGP?

Look for topics with PGP in the title for information about using Pretty Good Privacy certificates.
Start with PGP secure trading on page 693. Unless PGP is mentioned explicitly, the topics in this
documentation concern X.509 certificates. Using PGP depends on whether your user license
supports it. Optional PGP support is in addition to standard X.509 support.
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

12 Certificates and keys
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.
The role of trust in PKI

PKI establishes digital identities that can be trusted. The CA is the party in a PKI responsible for
certifying identities. More than generating a certificate, this entails verifying the identity of a
subscriber according to established policies and procedures. This is the case for in-house and
outsourced PKIs. In an organization that generates and uses its own self-signed certificates, the
trading parties must verify the certificates and establish a direct trust. Once established that an
identity or issuer of an identity can be trusted, the trust anchor’s certificate is stored in a local trust
list.
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.
Why use encryption and digital signatures

Using certificates to encrypt and digitally sign documents provides the following assurances about
document transmissions:
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.
Interchange encryption method

Interchange uses a combination of public-private key encryption, which is also known as
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.
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.
Symmetric key lengths

Interchange supports several key lengths for the symmetric key you choose. You need to be careful
to choose a key length your partner can support.
Public-private (asymmetric) key algorithms

Interchange uses the RSA cryptosystem for asymmetric encryption and the digital signatures
provided by using certificates.
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.

Public-private (asymmetric) key lengths

Interchange supports encryption key lengths of 512, 1024, and 2048 bits for the public-private key.
You must choose one of these key lengths when you generate or obtain your certificate. You do not
need to choose the same key length as your trading partner.
Support for dual keys

Some EDIINT-interoperable software products use two keys: one for encrypting documents and the
other for signing documents. Interchange supports single- and dual-key certificates. You do not
need to do anything different to trade documents with a partner who uses dual keys.
Encryption and signing summary

Described in the simplest terms, Interchange exchanges encrypted and signed documents in
S/MIME format.
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.
Ensure data integrity and trust

When digitally signed, ensuring data has not changed and can be trusted involves two steps:
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.

Certificate path validation

Certificate path validation ensures a public-key certificate has not been tampered with and can be
trusted. All certificates are signed by their issuing certificates. This means each certificate contains a
signature that can be checked through the signature verification process previously described. The
verification ensures the certificate has not been tampered with. For a given end-entity certificate, the
list of certificates from itself through its intermediate certificates to its root certificate is known as the
certificate path or chain. (Self-signed or root certificates are signed by themselves.)
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
A community can be in the client or the server role when trading with a given partner.
l Community in client role – When the community is sending a message to a partner, it acts as

the SSL client. This requires the community to have trusted the partner's SSL server certificate.
l Community in server role – When the partner is sending a message to the community's
embedded SSL server, the community acts as the SSL server. If the embedded SSL server has
been configured to require client authentication, the community must have trusted the partner's
SSL client certificate.
At the time of setting up a trading delivery, you specify that "clients must use SSL to connect to this
server." You can further specify to "enable host name verification." The first control requires use of
SSL protocol during connections. The second optional control makes Interchange compare the
name of the SSL server to the name in the server's certificate to make sure they are the same.
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.
Distribute certificates to partners

Before you can exchange encrypted and signed documents with a trading partner, each of you must
obtain the other's certificate and public key. You do this after you have created your community.
Each of you obtains a certificate with a public-private key pair, either by generating a self-signed
certificate or by obtaining a certificate from a certificate authority.
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.
Certificate exchange with Axway partners

If your trading partner uses any of the Axway endpoint products (B2Bi, Interchange or Activator),
export your community, which includes your certificate and public key, to a file and send that file to
the partner. We recommend doing so by a secure means.
Certificate exchange with other partners

If you exchange encrypted and signed documents with partners who use other interoperable
software, export your certificate and public key to a file and send the file to partners. For initial
distribution of self-signed certificates, we recommend sending the certificate to each partner by a
secure method. Subsequent distribution can be by e-mail. For more information see Export a
certificate to a file on page 799.

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.
When to get certificates

You can generate or obtain new certificates when:
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.
Manage expiring certificates

The use of certificates to ensure the security of your document exchanges is an option that is highly
recommended. When sending a message, Interchange uses the partner's public key (included in a
certificate file) to encrypt the message. If the certificate is expired, Interchange does not encrypt or
send the message. Likewise, an inbound encrypted message cannot be deciphered with an expired
certificate. It is important to make sure the certificates associated with communities and partners are
current and have not passed their expiration dates.

View expiration dates

Expiration dates for certificates are displayed in the user interface. For a community, click
Certificates in the navigation graphic at the top of a community summary page to display a list of
the community’s certificates. The list includes the expiration dates of all certificates. For a partner,
you can view the same type of information by clicking Certificates at the top of a partner summary
page.
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.
Certificate replacement and archiving

Do the following when a certificate is about to expire. The advice about archiving expired
certificates is recommended, but not required.
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.
The Trusted root certificates tab in the user interface displays all of the root certificates that your

community trusts, including those of certificate authorities.
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.

Import root certificates

Importing a trusted root is a task that rarely, if ever, must be performed. You might have to import a
trusted root if, for example, your partner sends you a CA-issued certificate and your system does not
have the trusted root for it. In such a case, document trading would fail. As a solution, you would
need to import the root underlying the certificate and trust it.
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.
Auto import intermediate and root

certificates
This topic is helpful when you want to automatically import intermediate and root certificates not
already available in Interchange. This is an uncommon case most users do not encounter.
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.
The pre-loaded intermediate and root certificates are located in <install directory>\conf\

certs. The following figure shows part of the certs directory hierarchy on a Windows file system.
Certificates are organized by CA. Each CA folder has a Root subdirectory and, if needed, an

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.
Do you use PGP?

If you use Pretty Good Privacy (PGP) start by viewing PGP secure trading on page 693. Unless PGP
is mentioned explicitly, the topics in this documentation concern X.509 certificates.
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
Pages and fields

l Certificates search results page on page 783
l Certificates pages on page 786
l Community certificates page on page 787
l Partner certificates page on page 789
l Certificate field descriptions on page 790

Certificates search results page

Use the certificates search page to view details about certificates used by all communities, partners
and servers for all purposes, including encrypting and signing traded messages and securing
connections (SSL). You can view root certificates, whether they are your own self-signed certificates
or those issued by certificate authorities. You can also view intermediate and end-entity certificates.
Certificates can be deleted from the certificate store and the database.
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.
To open the certificates search page, Select System management > Manage certificates on

the top toolbar. Or, click System management to open the System management page and then
click Manage certificates.
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.
Certificates search panel

By default, the search panel located on the left side of the page is closed. Click the Show/Hide tab
to open the panel.
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.
Results display controls

l Certificates per page – Enter a maximum number of lines for display in search results. Default
= 50 results per page
l Maximum # of search results – Enter the maximum number to limit the total number of
search results. Default = 500
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.
View and work with search results

On the search page, you can view and work with search results.
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.
Community certificates page

The Certificates page for communities has the following tabs:
Personal certificates tab

The personal certificates tab displays:
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.

l Signing – The certificate is used for digitalSignature and not used for

keyEncipherment.
l Encryption and signing – The certificate is used for keyEncipherment and at least one
of nonRepudiation and digitalSignature.

The Trusted roots certificates tab displays the roots of partners certificates that a community trusts.
In the case of a self-signed certificate, the trust is for the certificate itself, as a self-signed certificate
is a root certificate. In the case of a certificate authority certificate, the trust is for the root certificate
in the chain of trust of a partner's certificate. By default, the system trusts root certificates when
end-entity partner certificates are imported.
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.
SSH keys tab

The SSH keys tab displays the public keys within private keys a community has imported. Private key
data are not displayed because that would compromise security. SSH keys are used for public-
private key pair authentication or host-based authentication for Secure FTP (SFTP) delivery
exchanges that support encrypting data over a Secure Shell (SSH).
PGP personal certificates tab

The PGP personal certificates tab displays the default certificate, if any, for signing and encrypting
documents. It also lists all PGP certificates associated with the community. If the community has

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.
Partner certificates page

The partner certificate page displays the default certificate, if any, for encrypting documents. It also
lists all certificates associated with the partner along with state, usage and expiration dates.
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.
View certificate information

You can view information about a certificate for a community or partner. Open the certificates page
by clicking Certificates on the navigation graphic at the top of the community or partner summary
page. Click the name of a certificate to open the information page, which consists of multiple tabs.
If you change anything, click Save changes.
The following topic explains the tabs on the certificate information page.

Certificate field descriptions

The following describes the fields on the certificate tabs.
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
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.
Set up certificates for a community

Use this procedure to create self-signed certificates for a community or to load a third-party
certificate for a community.
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.
Generate self-signed certificates

Use this procedure if you selected to create a self-signed certificate in step 2 of Set up certificates for
a community on page 792.
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.
1. On the first certificate wizard page, select Create a self-signed certificate, and click next.

2. On the request certificate page, select:
l Single key certificate if you want one certificate for both signing and encrypting
documents.
l Dual key certificate if you want two certificates, one for signing documents and another
for encrypting documents.
3. Select one of the following encryption key lengths from the key length drop-down list:
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.
Distribute certificate information

l 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.
l 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.
l 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.
Import Entrust certificate

Use this procedure if you selected acquire Entrust certificates in step 3 of Set up certificates for a

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.
1. On the first certificate wizard page, select Retrieve a certificate from a certificate

authority and click Next to display the certificate authority selection page.
2. Select Entrust V.7.1 (CMP).

3. Click Next to display the certificate wizard Entrust server information page.
4. Complete the host and port fields for importing the certificate. Consult with your organization’s
Entrust administrator to obtain the information.
5. Click Next to display the Entrust reference and authorization page.
6. Complete the reference and authorization fields for importing the certificate. Consult with your
organization’s Entrust administrator to obtain the information.
7. Click Next to display the certificate review request page.
8. Review the information on the page. Click Back to change any information or click Next to
acquire a certificate.
9. If there is a check box for Send certificate exchange messages to partners, see Replace
exchanges.
10. Click Finish. The certificates page reappears, displaying the new certificate.
11. If you are setting up a community for the first time, you must distribute your certificate
page 855.

If you need to distribute your certificate to your trading partners who use other interoperable
Before you attempt to exchange encrypted and signed documents, you should contact each
Import RSA Keon certificate

Use this procedure if you selected acquire an RSA Keon certificate in step 3 of Set up certificates for
a community on page 792.
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.
1. On the first certificate wizard page, select Retrieve a certificate from a certificate

authority and click Next to display the certificate authority selection page.
2. Select RSA Keon (CMP) and click Next to display the RSA Keon host and port page.
3. Complete the host and port fields for importing the certificate. Consult with your organization’s
RSA Keon administrator to obtain the information.
4. Click Next to display the key ID and shared secret page.
5. Using the information provided to you, complete the fields for importing the certificate. Type
this information in the key ID and shared secret fields.
6. Click Next to display the certificate review request page.
7. Review the information on the page. Click Back to change any information or click Next to
import the certificate.
8. If there is a check box for Send certificate exchange messages to partners, see Replace
exchanges.
9. Click Finish. The certificates page reappears, displaying the new certificate.
page 855.

Import key pair in certificate file

Use this procedure if you selected to import a certificate and private key from a file in step 3 o f Set
up certificates for a community on page 792.
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.
1. On the first certificate wizard page, select Import a certificate and private key from a file

and click Next to display the locate the certificate file page.
2. To locate the PKCS#12 file containing your certificate, click Browse to display the Browse
dialog box.
3. Locate and select the certificate file. The file must have an extension of .pfx or .p12. Click
Open and the certificate file location certificate page reappears.
4. Type the same password you used when you exported the certificate file from a browser or mail
client.
5. Click Next to display the certificate details page.
6. If you prefer, type a name for the certificate in the Name field. This name can help you tell one
certificate from another. By default the system uses the CA name as the certificate name.

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
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.
page 855.
Import certificates for partners

Use this procedure to import a trading partner’s certificate and associate it with a partner object in
your configuration.
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.
Export a certificate to a file

Use this procedure to export a community or partner certificate to a file. The procedure for both is
similar, except for a community certificate you have the option of exporting the private key as well
as the public key. This option does not apply to partner certificates, which only contain public keys.
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.

4. Click Export this certificate to open the certificate export page. A partner certificate export

page does not have the option for exporting a private key. (If you are starting from the
certificates search page, the path to the export page is different. See Certificates search results
page on page 783.)
5. Select an export option. If you are exporting a community certificate for use by a partner, note
that the DER and PKCS#7 options are functionally the same. However, the one to select
depends primarily on what your partner’s trading engine supports.
For trading between partners who both use Axway software, we recommend selecting PKCS#7
and the checkbox for including all certificates in the certification path. Although this is the most
all-inclusive choice, you can nevertheless choose DER instead with no adverse effects.
The following explains the options in more detail. If you trade with partners who use
interoperable software, we recommend that you determine whether their software supports
DER, PKCS#7 or both.
l DER encoded binary X.509 (.cer) – Select this option to export a binary file with an
extension of cer. The file contains a single binary certificate containing a public key. If
your partner’s software only supports DER encoded certificates, select this option.
l Cryptographic Message Syntax Standard PKCS #7 (.p7b, .p7c) – Select this
option to export a file with an extension of p7c. The file can contain all the certificates
needed to support trading, if more than one is required. If your partner's software supports
a certificate in a PKCS#7 format, this option is recommended over DER. If you select this,
you also can select Include all certificates in the certification path if possible.
This option includes all certificates in the chain of trust for the certificate. This is the most
all-inclusive method for exporting a certificate. However, be aware that your partner's
software, if not Axway, might not support the entire certificate path in the p7c file.
l Personal Information Exchange PKCS #12 (.p12, .pfx) – Select this option to
export a community certificate containing the private key, then provide and confirm a
password. Caution: You should do this only if you can keep the certificate in a highly
secure place. This option is available only for community certificates and not partner
certificates. Your user role must have permissions to export private keys.
6. Click Export certificate to display a file download dialog box.
7. Click Save to display the Save As dialog box.
8. Review the file name and path for the file you are exporting. If you want to change the path or
name, you can navigate to a new folder or type a new file name.
9. Click Save to export the certificate. The certificate export page reappears.
10. Click Close.
11. If you exported a community certificate for a partner, send the certificate file to the partner by a
secure means.

Globally prohibit exporting private keys

There is a way to prohibit all users (including users with administrator privileges) from exporting
X.509 certificates with private keys. The ban encompasses all private keys of X.509 certificates,
whether used by communities or embedded servers.
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.

Manage certificate revocation lists (CRLs)

You can configure Interchange to c ompare certificates against lists of invalid certificates that are
maintained by the issuing certificate authorities. This checking is done for outbound encrypted
documents and inbound signed documents.
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.

How CRL checking works

CRL checking is potentially performed for every non-root certificate encountered during certificate
path validation. The following steps are taken for each such certificate.
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.

Obtain CRL access information

Before you can download a CRL to Interchange, you must obtain the information required to access
the CA’s CRL.
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.
1. On the system management page, click Manage CRLs to display the CRL list page. The page

lists imported CRLs, if any.
2. Click Add a CRL to launch the CRL wizard.
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.
Manage CRL lists

Once one or more CRLs have been downloaded, you can use the CRL list page to manage them. To
open this page:

1. Click System management on the menu bar to open the System management page.

2. From the list of tasks at the bottom of the page, click Manage CRLs to open the CRLs page.
The CRLs page shows the name of each CRL, the date and time the CRL was last updated, the update
schedule status, and the download status.
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.
To delete a CRL, click Delete to the right of a CRL on the CRL list page or click Delete this CRL on

the manage CRL page. Deleted CRLs no longer appear on the CRL list page and are deleted from
<install directory>\common\conf\crls.
Advanced CRL settings

Use the CRL usage and retrieval configuration page to control how CRLs are used and
updated in Interchange.
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.
To open the CRL usage and retrieval configuration page:


2. From the list of tasks at the bottom of the page, click Manage CRLs to open the CRLs page.
3. Click Configure CRL usage and retrieval to open the CRL usage and retrieval
configuration page.
The fields on the CRL usage and retrieval configuration page are described in the following
section. These values are stored in the database.
4. Click Save changes to save your changes to this page.
CRL usage and retrieval tab

Require CRLs
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.
l Except when certificate does not contain CRL distribution point – If you

select this option, CRL checking does not result in an error when a CRL for a certificate
cannot be found and the certificate does not contain a CRL distribution point.
Use expired CRLs
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.
Automatically retrieve CRLs
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.
Proxy mode for HTTP/HTTPS CRL retrieval
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.
Trusted root certificates tab

The Trusted roots certificates tab displays the roots of partners certificates that a community trusts.
In the case of a self-signed certificate, the trust is for the certificate itself, as a self-signed certificate
is a root certificate. In the case of a certificate authority certificate, the trust is for the root certificate
in the chain of trust of a partner’s certificate. By default, the system trusts root certificates when
end-entity partner certificates are imported.
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
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.
Purge old CRLs

CRL file references are stored in a CRL database table. Over time, the CRLs table accumulates an
excessive number of records, eventually adversely affecting system performance. Use the command
line tool crlPurgeHttpsClient to launch the CrlRemover to remove outdated CRLs from both the
table and the file system. It only removes the records that are not related to the most recent CRLs.
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:
..\tools>crlPurgeHttpsClient http 127.0.0.1 6080 api-user test

connecting to host: 127.0.0.1, using protocol: http port:6080, user:
api-user and non-null password
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:
l usage: not enough parameters: []
expecting protocol host port username and user password
The script was called without any parameters, or with one or more parameters missing.
l response code: 401 authToken=null
Unable to log in user: web-traders, incorrect user name or password
The script was called with an invalid login.
l response code: 200
purge response code=403 and message: Forbidden

Web-trader is not authorized to perform this task
The script was called by a user without the Access APIs permission.
Analyze certificates for errors

An X.509 certificate-scanning command-line tool is available to report issues related to public-key
certificates. The tool is certScan and is found in <install directory>\tools.

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:
certScan <file or directory>
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.
Collect data about certificates

The certStats tool collects data about certificates in the database. It is in <install
directory>\tools and must be run from the tools directory.
You can run certStats with or without parameters. The tool can be invoked as:
certStats [-file <file>] [-export <dir>] [-clean] [-cross]
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.
Replace certificates automatically

The following topics describe automatically exchanging replacement certificates between partners
who trade e-commerce messages via EDIINT or OFTP2 delivery exchanges.
Do you use PGP?

Look for topics with PGP in the title for information about using Pretty Good Privacy certificates.
Start with PGP secure trading on page 693. Unless PGP is mentioned explicitly, the topics in this
documentation concern X.509 certificates. To use P GP, you must have an Interchange license that
supports the functionality. PGP support is an optional addition to standard X.509 support.

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
Pages and fields

l Received certificate exchange requests page on page 821
l Sent certificate exchange trust requests page on page 823
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:
l Certificate Exchange Messaging (CEM) is for EDIINT trading partners.

l Security Certificate Exchange (SCX) is for OFTP2 trading partners.
Each standard is for trading partners to exchange public-key certificates and replace certificates that
are about to expire, have been compromised or need replacing for some other reason.
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

Scope of CEM support

The CEM standard encompasses certificate exchanges between partners who use the AS1, AS2 and
AS3 message protocols. Interchange supports CEM for AS1, AS2, AS3 and also the Secure File
message protocol. The protocols are supported for Interchange c ommunities and partners who use
Interchange or a third-party interoperable trading engine.
Scope of SCX support

Interchange supports SCX between partners who use Odette File Transfer Protocol version 2
(OFTP2) trading delivery exchanges only. This support is for Interchange c ommunities and partners
who use Interchange or a third-party interoperable trading engine.
Overview of exchange process

After a trading relationship has been established, a community may get another certificate and
public-private key pair, either by generating a self-signed certificate or importing a P12 or PFX file.
The certificate can be for use by the community for signing and encrypting messages or use as an
SSL or TLS server certificate. Obtaining a new certificate triggers Interchange to check whether the
community supports CEM by having an active EDIINT delivery exchange or SCX by having an active
OFTP2 delivery exchange. It also checks whether any of the community’s partners have an active
default corresponding delivery exchange. If so, the community has the option of sending certificate
exchange messages containing the new certificate to any or all partners. The UI displays the partners
grouped by CEM and SCX.
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.
Types of certificates in requests

Certificates used for the ordinary purposes of signing, encryption and SSL can be sent in CEM and
SCX requests for acceptance by partners. There are some variations in the way Interchange handles
certificates slated for different uses that you should know about.

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.
Signing and SSL

A community uses a signing certificate to sign outbound messages. SSL certificates are used to
authenticate a client or server.
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
Types of CEM messages

CEM messages exchanged between trading partners are XML documents. There are two kinds of
messages: CEM request and CEM response. When replacing, the old certificates are used to sign CEM
messages. This authenticates the identities of the senders.

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.
Determin certificate usage

SCX request messages, which are XML documents, do not contain explicit indications of how a
certificate is to be used by the receiving partner. The receiver of an SCX message is supposed to find
a matching certificate that is already in use for the trading relationship with the sender of the
message to determine how the new certificate is to be used. A matching certificate is a certificate
with exactly the same issuer name, subject name, key usage and extended key usage. Even if a
matching certificate is found it may not be obvious how exactly to use the new certificate.
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.
Positive and negative responses

The positive or negative receipt (EERP or NERP) to an OFTP SCX message is used to indicate
whether the sent certificate has been accepted or rejected. If Interchange sends SCX messages to a
system not configured to automatically accept received SCX certificates, a user may see OFTP
messages in the “waiting for receipt” state for extended periods in Interchange. This should not be a
problem if the resend time on the sending system is set appropriately to avoid resending the original
message before a user on the receiving system has had time to accept or reject the certificate.

Messages, receipts not signed, encrypted

OFTP SCX messages are never signed or encrypted and their receipts (EERPs and NERPs) are never
signed. Regardless of the collaboration settings, Interchange never signs or encrypts an outgoing
SCX message. It also does not request a signed receipt for such a message. Regardless of the
configured message validation rules, Interchange always accepts SCX messages and receipts that are
not signed or encrypted.
Self-signed and CA certificates

The Odette community prefers CA-issued certificates and discourages self-signed certificates. But
Interchange supports both. When an SCX message is used to send a CA-issued certificate, only the
end-entity certificate is contained in the message. When Interchange receives such a message, the
CA certificates necessary to construct the complete path for the received end-entity certificate must
already be in its certificate store. If not already present, you can copy the required CA certificates to
the conf\certs directory. This is the repository of well-known CA root and intermediate
certificates.
Send a CEM or SCX request

Use this procedure to send a CEM or SCX request to one or more partners.
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.

5. If the request is a SCX request, select the Respond by date and the partners to send the

request. Select the type of SCX message to send. The type must be the same for all partners.
See the View certificate details page for SCX requests below. The types to choose from follow
this page illustration.
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.
Track CEM and SCX requests

The Interchange user interface includes two pages for monitoring CEM and SCX messages.
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.

Received certificate exchange requests page

The Received certificate exchange requests page provides information about the CEM and SCX
requests your community has received from partners. This includes the date the message was
received, the name of the partner who sent the message and the number of public-key certificates in
the message. You can use the page to determine how you want to manage processing of inbound
CEM and SCX requests.
CEM requests
The following are the options for CEM requests.
l Let the system automatically accept all signed CEM requests – Select if you want your

community to accept all replacement certificates from partners. Interchange approves each
certificate upon receipt and sends an acceptance CEM response to the partner who sent the
message. Approval is contingent on whether the CEM request was signed with a certificate
associated with the partner’s profile.
l All CEM requests must be manually accepted or rejected – Select if you want to review
each CEM message and determine whether to accept or reject the certificate. Interchange sends
a CEM response once you have decided.
SCX requests
The following are the options for SCX requests.

l Let the system automatically accept – Select to have your community accept all SCX

requests containing a certificate that has the same issuer, subject and key usage of an existing
certificate.
l All OFTP SCX requests must be manually accepted or rejected – Select if you want to
review each SCX message and determine whether to accept or reject the certificate. Interchange
sends a response once you have decided.
Internal checks
Whether you choose the automatic or manual option, Interchange performs the following internal
checks before accepting a certificate:
1. For CEM and SCX – Does Interchange have the complete certificate chain for the certificate in

the request? If a self-signed certificate, the request should contain the complete certificate
chain.
2. CEM only – Does the request XML document contain the issuer name and serial number of the
certificate in the request? Interchange makes sure the issuer name and serial number are the
same in the XML document and in the certificate within the XML document.
3. CEM only – Does the certificate support the requested usage of signing, encryption or SSL?
For example, if the request says the certificate is to be used for signing, Interchange makes sure
the key usage extension, if any, in the certificate actually supports digital signatures.
Message details pages

On the Received certificate exchange requests page, a Message details link displays for each
message. Click the link to open a message details page in Message Tracker on page 826. Certificate
request messages are sent and received like any other messages exchanged between partners.
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).
Figure 1. Received EDIINT CEM certificate exchange request details page

Figure 2. Received OFTP SCX DELIVER details page
Received request details page

The Received request details page shows details about the CEM or SCX request, including the name
of the partner and the usage for the replacement certificate. The requested respond-by date displays
only for a CEM request. An SCX details page displays the type of request (Request, Deliver, Replace).
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.
Sent certificate exchange trust requests page

The Sent certificate exchange trust requests page (see the following figure) provides information
about the CEM and SCX requests your community has sent to partners. This includes the sent and
respond-by dates, the number of partners to whom the request was sent and the number of public-
key certificates in the message.

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).
Sent request details page

The Sent certificate exchange trust request details page shows details about the CEM or SCX request,
including the number of partners who have accepted or rejected the certificate.
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:
l Install this certificate now – Click to immediately implement the certificate before the

respond-by date or despite rejection by one or more partners.

l Cancel the scheduled installation of this certificate – Click to stop Interchange from

implementing the certificate after the respond-by date has passed. This forestalls implementation
only in the absence of responses from partners. If all partners accept the certificate, Interchange
implements the certificate regardless of the canceled respond-by date.
A Message details link displays for every partner to whom you sent a request. Click the link to
open a message details page in Message Tracker on page 826. CEM and SCX messages are sent and
received like any other messages exchanged between partners.

Message Tracker
13
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. Select Message tracker > Find a message
on the top toolbar to open the search page.
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.
Message Tracker search controls

Use the Custom search panel on the left side of the main Message Tracker page to search for
messages by conditions you specify. Messages that match your search conditions are displayed on
the search results area of the page (see Search results page on page 833). These search tools are
available to administrators and users associated with roles that include search permissions.
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).
Message Tracker page

Only the top portion of the custom search panel on the left side is displayed.
The following figure shows a partial view of the main Message Tracker page as it may appear when
first opened.

13 Message Tracker
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.

13 Message Tracker
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.
Peer Network Tracker

Controls for Peer Network Message Tracker display if your user license supports the peer network.
For information, see Track peer messages on page 91.
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).

13 Message Tracker
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.

13 Message Tracker
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
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

13 Message Tracker
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 default settings for searching by date is the Origination or Delivered date Within the last

[n] days. If you open the Message Tracker search page and perform a search without changing the
date defaults, you may not get the results you expect if many database records are older than the
number of days specified in the Within the last [n] days option.
Administrators can change the default value of the option Within the last [n] days on the

Message Tracker global settings page (see Manage default search settings on page 843).
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).
The Specify the dates option lets you specify a search for records whose dates are within a range

of dates and times of your choosing.

13 Message Tracker
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.
Hint: Persisting custom column displays

If you modify the default column view of your search results, and then open a detailed view of any
search results entry, you will lose your custom column view when you click the back button to
return to the search results page (without running a new search query):
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.

13 Message Tracker
Search with wildcard characters

There are two supported wildcard characters for use in Message Tracker only in the following fields:
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 \*.
Search results page

Once search results are displayed, you can enlarge the results display area by clicking the
Show/Hide tab to the right of the search name field.
The following figure is an example of a search results page with the controls hidden. Click
Show/Hide to toggle the view.

13 Message Tracker
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:
l Add this item to the filter – Select to add this value as a search condition in the trading

information area of the custom search panel and perform a new search. You can select this to
cumulatively add values for search different conditions. The value you select is added to the
search conditions already set up on the custom search panel.

13 Message Tracker
l Filter by only this item – Select to clear any search conditions in the trading information area

of the custom search panel and perform a new search based only on this value. You can select
this to clear all search conditions except one. This also resets the date condition to the default of
Origination and Within the last [n] days.
After executing a search, you can save the search by name and perform it again with the same
conditions. To save a search, type a name in the Search name field and click Save. To execute a
saved search, select the name of the search under Message Tracker > My searches. Searches
are saved on a per-user basis. Searches you have saved are not available to users who log on with a
different user ID. However, administrators can share your searches with other users (see Share saved
searches on page 843).
View details of search results

The search results page has controls for customizing the display of message data (see
Message Tracker search controls on page 826). But there are other options for viewing detailed
information.
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.
Message details tabbed pages

Once search results are displayed, you can view message details on tabbed pages. Click Details to
open the message details page for the selected payload or receipt.
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.

13 Message Tracker
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.
Adding notes to message records
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.
Searching for or displaying 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:
1. Ask an administrator to assign the User annotation attribute as an in-use attribute:

a. Select Message tracker > Select attributes for pop-up windows.
b. On the Common tab, select User annotation and click Assign as in-use attributes.
The attribute now displays on the In-use attributes tab.

13 Message Tracker
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.
Message processing details

This tab graphically shows the processing steps for the message. It also provides details about
signing, encryption, compression and whether there was a receipt for the message. If you back up
copies of messages, the name of the backed up file is given.
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.

13 Message Tracker
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).
Search results attributes in pop-up

windows
When search results are displayed you can place the cursor over a Details link and wait two seconds
for a pop-up window to appear. You can specify message attributes and values to display in the
pop-up. The pop-ups are a quick way to view attributes and values related to messages without
opening the message details tabbed pages.
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.
Select attributes for pop-up windows

You select the attributes you want to display in the pop-ups on a page in the user interface titled,
“Select attributes for pop-up windows.” Attributes are organized by tabs in the available attributes
section of the page.
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.

13 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.
You can disable the pop-up windows by selecting Disable message attribute pop-up window

on the message tracker search results page and clicking Save.
The following figure shows a pop-up window displaying selected attributes for a message on the
Message Tracker search results page.

13 Message Tracker
Attribute controls for administrators

Users associated with roles granting administrator permissions have access to a broader range of
controls on the Select attributes for pop-up windows page. Non-administrative users cannot see
these controls.
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:
l Document types of traded messages – In the course of processing Interchange collects and

lists on this page document types of traded messages. An administrator manually can add
document types not already collected or delete types.
l Document classes of traded messages – In the course of processing Interchange collects
and lists on this page document classes of traded messages. An administrator manually can add
document classes not already collected or delete classes.
l MIME types of traded messages – In the course of processing Interchange collects and lists
on this page MIME types of traded messages. An administrator manually can add MIME types not
already collected or delete types.
l Delete autocomplete attribute values – In the course of processing Interchange collects
and lists on this page message attributes that are available as autocomplete values for the
Attribute field on the Message Tracker search page. An administrator can delete autocomplete
values. This only removes attributes as available autocomplete values for the Attribute field. It
does not remove the attributes from traded messages.

13 Message Tracker
Icons on search results page

Icons might appear next to some messages on the search results page. 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.

13 Message Tracker
Delete, resend, reprocess options

The search results page has three action options that can be applied to the displayed records. These
are: delete, resend and reprocess.
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.

13 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.
Share saved searches

Administrators can share their saved searches with other users. They also can take away searches
that have been given to other users.
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 Share my saved searches tab lets you share your saved searches with other users.

a. Select the saved searches you want to share and click Share.
b. If another user has a saved search with a name identical to one of your saved searches,
the name is listed under the Searches with names duplicating my searches
column. This only means the names are the same; the search conditions could be quite
different. Select the overwrite check box if you want the saved search you share to
replace a saved search of the same name belonging to another user.
l Unshare saved searches tab lets you remove saved searches used by yourself and other users.
Select to unshare by user name or search name, select the searches and click Remove.
Manage default search settings

Administrators can use the Message Tracker global settings page to change:
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.

13 Message Tracker
There are several ways to open the page:
l Select Message tracker > Configure global message tracker settings.

or
l Select System management on the top toolbar to open the System management page. Click
the link named Configure global message tracker settings to open the default settings
page.
The following describes the fields on the Global message tracker settings page. Click Save changes
after making any changes.
Default menu items

The following options control whether system-defined default searches are available to select under
Message tracker > Message searches. If selected, these searches are available for all users.
Although you can choose whether to make these available universally, you cannot change the
search conditions of system-defined default searches.
l All messages – This default search finds all messages. If the database has a large volume of

records, you may want to turn off this search.
l All messages-Last 1 Hour – This default search finds all messages traded in the last hour.
l All messages-Last 2 Hours – This default search finds all messages traded in the last two
hours.
l All messages-Last 6 Hours – This default search finds all messages traded in the last six
hours.
l All messages-Last 24 Hours – This default search finds all messages traded in the last 24
hours.

13 Message Tracker
l Failed messages-last days – This default search finds all messages with a status of failed

within a default number days. The default number of days is the value of the Number of days for
default searches field on this page.
l Negative response-last days – This default search finds all messages that received a negative
response from a partner within a default number days. The default number of days is the value of
the Number of days for default searches field on this page.
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.
Peer Network Tracker query restrictions

This section displays only if your user license supports the peer network, which enables Peer
Network Message Tracker.

13 Message Tracker
l Default number of search results to return – The number in this field is the default value

for the Maximum # of peer search results field under Peer Network Tracker 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 largest
allowed value a user can enter in the Maximum # of peer search results field under Peer
Network Tracker on the custom search panel of the Message Tracker page. Be careful when
changing this value. Setting a large number may slow Peer Tracker performance.
Collect message attributes

l Collect attributes for use in message detail pop-up windows – Select to have
Interchange collect attributes from traded messages. These attributes are available to display in
pop-up windows accessible on the Message Tracker search results page. Enabling attribute
collecting is recommended. However, if you experience slower Message Tracker performance,
you may want to disable attribute collecting to determine whether this has an effect.
l Maximum number of attributes to collect – The maximum number of attributes
Interchange can collect for possible use in the pop-up windows. If the number of collected
attributes is at or near the maximum, you can increase the number in this field or go to the
attribute page and delete some attributes to make room for new ones. To open the page select
Message tracker > Select attributes for pop-up windows.
Configure payload view

Use this procedure to format EDI or XML documents with stylesheets for viewing in Message Tracker.
This is optional, except if you process CSOS documents and need to identify CSOS document types.
Documents by default can be viewed as plain text without stylesheets.
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.

13 Message Tracker
4. Click Add a document type to display the page of that name.
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.

13 Message Tracker
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.
Force a document type for XML

To apply a stylesheet when viewing an XML document, a document type value must be forced in
order to identify the documents for applying the stylesheet. In Message Tracker, the document type
by default is blank for XML documents.
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.
l For outbound documents – For the integration pickup exchange for XML documents, open

the maintenance page for the transport and go to the message attributes tab. Use directory
mapping or a fixed attribute to set up DocumentType=XML. (The value does not have to be
XML. It is used here for simplicity.)
l For inbound documents – For the community delivery exchange for receiving messages from
partners, open the maintenance page for the transport and go to the message attributes tab. Set
up a fixed attribute value of DocumentType=XML.

Data storage, backups,
and purging 14
Interchange copies messages it sends and receives to a backup directory, provided backing up is
turned on. Failed messages also are placed in the backup directory; there is not a separate directory
for them. (Note that a rejected message is considered a failed message.) Records of traded and
failed messages are stored in the database.
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.
Message backup configuration

Interchange can back up messages multiple times: When first consumed, and during processing
when the content and state have been changed.
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.

14 Data storage, backups, and purging
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.
Backup configuration page field

descriptions
To open the global backup configuration page, click Trading configuration > Managing
trading configuration on the toolbar. On the Communities page, click Configure the global
backup settings. The following describes the fields.
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.
States of backed-up files

Because you use Message Tracker to search for, view and resubmit documents, there is no need to
manually examine the backup directory contents. If you open the directory, however, you see the
system appends names of backed up files with labels noting the state of backed-up messages. There
are many possible states. Some common states are:
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.
Backup options and Message Tracker

Message Tracker is most useful when message backups are turned on for all deliveries and the
message handler. Backing up is turned on by default at these points:
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
Backup point State Can resend Can reprocess
Application pickup Off No No
Send to partner Off
Message handler Off

Application pickup On Yes Yes
Send to partner On
Message handler Off

Application pickup Off Yes No
Send to partner Off
Message handler On

Application pickup On Yes Yes
Send to partner On
Message handler On

Inbound messages
Backup point State Can resend Can reprocess
Application delivery Off No No
Receive from partner Off
Message handler Off

Application delivery On Yes Yes
Receive from partner On
Message handler Off

Application delivery Off Yes No
Receive from partner Off
Message handler On

Application delivery On Yes Yes
Receive from partner On
Message handler On
Back up a community and its partners

You can back up (or "export") a community and all of its partners to a single compressed file. The
backed-up file includes all configuration settings specific to the community and all of the partners
associated with the community. This includes public and private keys and configurations for
inbound message validation and HTTP proxies.
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.
1. In the Interchange user interface, from the Trading configuration menu, select Manage

trading configuration to open the Communities page.
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.

Import a backed-up community and its

partners
Use this procedure to import a backed-up XML file containing a community and its associated
partners.
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.
1. Click Trading configuration > Manage trading configuration on the top toolbar to

2. Click Add a community to open the Add a community wizard.
3. Select Import a backed-up Interchange version 5 community and its partners from
a compressed file and click Next.
4. Browse to the directory where the backed-up file is located and type the password used when
the community was backed up.
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.
Back up a community as a partner

Before you back up (or "export") a community configuration to a file as a partner profile, make sure
the community has been completely configured.

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.
Community backup as partner procedure

1. In the Interchange user interface, from the Trading configuration menu, select Manage
trading configuration to open the Communities page.
2. Click on the name of the community you want to back up as a partner profile, to open the
Summary page for that community.
3. At the bottom of the community summary page, click Export this community as a partner
profile.
4. Select Save File and click OK.
Interchange generates a partner profile XML using the community characteristics.
After you back up a community as a

partner
You can send the partner profile to your trading partners, or use the partner profile to add a partner
on an implementation of Interchange. See Import a partner on page 858.

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
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.
maximum concurrent connections, retries, connection, response and read time-outs.
l Transport friendly names.
l The transport’s setting for backing up files.
classes themselves.
If you are upgrading from earlier versions, you can create backup files of partners and import them
as partner profiles in this version.
1. In the Interchange user interface, from the Partners menu, select Manage partners to open

the Partners page.
2. Click on the name of the partner you want to back up, to open the Summary page for that
partner.
3. At the bottom of the partner summary page, click Export this partner’s profile.
4. Select Save File and click OK.

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.
maximum concurrent connections, retries, connection, response and read time-outs.
l Transport friendly names.
l The transport’s setting for backing up files.
classes themselves.
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 single partner profile

1. Make sure the profile XML file is accessible on your file system.
2. From the Partners menu, select Add a partner to open the Partner Wizard.
3. Select Import a partner profile from a file and click Next.
l File name – Use the navigation tool to locate and select the partner profile XML file you
want to import.
l Choose import mode:
Replace if partner exists – Select this option if you want to overwrite any existing
partner with that has the same name.
Rename the new partner – Select this option if you want to create a new name for the
partner you are importing. Then enter the name to use in the Partner name field.

Ignore if partner exists – if an existing partner is encountered, it remains as is and the

new partner is not imported.
Update if partner exists – If an existing partner is detected, Interchange adds backed-
up content to the existing partner definition (incremental update).
l Choose peer network cloning:
Allow the partner to be auto-cloned to peers – If your license supports the peer
5. Click Finish.
Partners page.
Import all partner profiles found in a

directory on the server
1. Make sure one or more partner profile XML files are accessible in a single directory on your file
system.
2. From the Partners menu, select Add a partner to open the Partner Wizard.

3. Select Import all partner profiles found in a directory on the server and click Next.
l Directory name – Use the navigation tool to locate and select the directory where you
have stored one or more partner profile XML files.
l Choose import mode:
Replace existing objects if encountered – Select this option if you want to overwrite
any existing partners with that has the same names as imported partner profiles.
Ignore imported objects if existing objects are encountered. – if an existing
partner is encountered, it remains as is and the new partner profile is not imported.
Update (add objects that don't already exist, replace objects that do exist) – If
an existing partner is detected, Interchange adds backed-up content to the existing partner
definition (incremental update).
l Choose peer network cloning:
Allow the partner to be auto-cloned to peers – If your license supports the peer


5. Click Finish.
Partners page.
After you import a partner profile

If you are expecting an imported profile to include the partner’s certificate and public key, check
whether a partner’s certificate is trusted:
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.
Back up and restore a custom

configuration
If your implementation includes custom configuration, you can use the
externalConfigBackupRestore.cmd tool to back up and restore these customizations. The tool
and the customizable externalConfigBackupRestore.xml file are located in the following
directory:
<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.
Custom component Location
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

Custom component Location
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.
Automatic profile importing

Interchange automatically imports community or partner profiles written to a certain system
directory. These must be profiles that have been exported from B2Bi, or from Interchange or
Activator.
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.
\profiles \autoImport \rejected
\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
Configure automated Interchange purge

You can configure Interchange to delete unwanted database records and files in the backup
directory based on the age of the records and files.
To configure automatic purging:
1. In the Interchange user interface, from the menu bar select Trading configuration >

Manage trading configuration to open the Communities page.
2. From list of tasks, select Configure purge dates for trading engine messages.
3. Select an option:
l Delete messages on their purge dates
By default, Interchange is set to delete database records and backup files after they have
been in the system for 45 days. Use the years / months / days fields to change the age
settings. The system checks every 15 minutes to delete records and documents that have
reached their purge dates.
If you change the purge interval, the new interval affects only messages processed after the
change. The purge dates of messages processed before the change remain the same. But
you can use another tool to change purge dates retroactively, to synchronize with a new
purge interval. See Purge Interchange manually on page 863.
Only database records and messages in a final state are deleted. A final state is when no
more processing action is pending. Final states are reported in Message Tracker as:
Delivered, Failed and Resubmitted.
l Turn off purging, but continue setting purge dates
You can choose to turn off purging of database records and backup files. This is not
recommended unless you have requirements for maintaining database records and backup
files indefinitely.
Notes:
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:
2005/10/31 08:06:08.812 High

Administration.Persistence.MessagesPurgedMessage Deleted(CoreId
(1130771141162.903@HOSTNAME))

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.
Note for CSOS users

If you are licensed for CSOS functionality, CSOS records and message backups are scheduled to be
retained for two years, beginning with version 5.4. The CSOS retention period is configurable, but
only with the help of Axway.
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.
Purge Interchange manually

Use the messagePurgeTool to delete all database records and files in the backup directory at
once. This command-line utility is located in <install directory>\tools, and must be run
from that directory.
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.

Configure event purge

You can configure Interchange to delete unwanted database records for message-related events
based on the age of the records.
1. In the Interchange user interface, from the menu bar select Trading configuration >

Manage trading configuration to open the Communities page.
2. In the list of tasks, click Configure purge dates for events.
3. Select to either enable or disable event purges.
4. If you enable event purges, either accept the displayed interval or specify a new purge interval
(frequency of purges).
The default configuration is to delete database records for message-related events after 45
days. The system checks every 15 minutes to delete events that have reached the age threshold.
We recommend setting the age for deleting message-related events identical to the age for
deleting Interchange messages. For more information, see Configure automated Interchange
purge on page 862.

FTP client scripting
interface 15
The FTP client in Interchange includes a scripting interface to accommodate non-standard
interaction with FTP servers. The default FTP client implementation uses an XML file, called the
command set document. The XML file defines meta-commands comprised of one or more FTP
commands to be sent to an FTP server. The default command set document works with most FTP
servers without any modifications.
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.
1. Edit the command set document. At this level, you edit the default command set document

to change the order of commands sent to the FTP server or remove commands. For example, if

15 FTP client scripting interface
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.
Edit the command set document

The script that specifies commands sent to the host is the XML command set document, named
ftpcommandset.xml in [install directory]\conf. It contains a set of meta-commands, each consisting
of one or more FTP commands to be sent to an FTP server.
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.

FTP tester tool

You can use the ftpTester tool to exercise the FTP client outside of Interchange. The script to start
ftpTester can be found in <install directory>\tools.
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
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 password: cyclone
-> Enter account (leave blank for most servers):
-> 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): ?
? help
ASCII perform ASCII data transfers
BINary perform binary data transfers
PASV perform data transfers in passive mode (the default)
PORT perform data transfers in port mode
QUIT/EXIT/BYE exitNormal FtpTester
Note: Metacommands are scriptable via conf/ftpcommandset.xml

Host pickup directory (used by REC, DEL and LIST): pickup
Local working directory (used by REC and LLIST):
-> Enter CONSUMER command (e.g. ?, LIST, RECeive, DELete, LLIST, ASCII,
BIN, LCD, QUIT):
Producer options
**** Welcome to the Cyclone FTP test program ****
-> Enter password: cyclone
-> Enter account (leave blank for most servers):
-> Enter c for CONSUMER client (list, receive, delete), p for PRODUCER
(send). (Blank assumes c): p

-> Should original filenames be preserved when sending? (Y/N - default

is Y):
-> Should existing files be overwritten? (Y/N - default is Y):
-> 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 inbox directory (used by SEND for uploading, after which files are
moved to pickup): inbox
Host pickup directory (used by SEND and LIST): pickup
Local working directory (used by SEND and LLIST):
-> Enter PRODUCER command (e.g. ?, SEND, LLIST, ASCII, BIN, LCD, QUIT):
?
? help
ASCII perform ASCII data transfers
BINary perform binary data transfers
PASV perform data transfers in passive mode (the default)
PORT perform data transfers in port mode
QUIT/EXIT/BYE exitNormal FtpTester
Note: Metacommands are scriptable via conf/ftpcommandset.xml


Host inbox directory (used by SEND for uploading, after which files are
moved to pickup): inbox
Host pickup directory (used by SEND and LIST): pickup
Local working directory (used by SEND and LLIST):
-> Enter PRODUCER command (e.g. ?, SEND, LLIST, ASCII, BIN, LCD, QUIT):
FtpTester displays a main prompt that allows you to enter meta-commands to perform simple
information.
FTP scripts for Interchange application

exchanges
This chapter describes FTP statements to use in scripts for FTP application pickups and deliveries in
Interchange. Information about the two kinds of supported variables – script and environment – is
provided.
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:
# Remote host is a UNIX machine.

CD "/tmp";
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";
Available in receive or send scripts

The following read-only reserved variables are available in receive or send scripts.
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.
Available in send scripts only

The following read-only reserved variables are available in send scripts only.
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:
# We try to RECV all files in the current directory.

# We ignore any errors for the RECV statement.
# If the file transfer succeeded, we delete the remote file.
# We ignore any errors for the DELETE statement.
#
LIST "." INTO %F {
-RECV %F;
IF(%FTPSTATUS IN "200"-"299") {

-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 Syntax – APPEND localfile TO remotefile;

l Description – The APPEND statement appends a local file localfile to a remote file
remotefile. If the file remotefile does not exist, it is created. The file localfile is not changed
nor deleted.
The localfile parameter must be an absolute path. The format of the path is system
dependent.
The remotefile parameter can be an absolute or relative path. The format of the path is system
dependent.
l FTP commands
PORT <sp> host-port <crlf>
APPE <sp> remotefile <crlf>
l Example:
# Interchange installed on a Unix machine.

# Remote host is a Windows machine.
APPEND "/nfs/home/chpy/data/file.dat" TO "remotedir\\files.dat";
CD
Change the current directory on the FTP server.

l Syntax – CD remotedirectory;

l Description – The CD statement changes the current 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
CWD <sp> directory <crlf>
l Example:
# Remote host is a Unix machine.

CD "/tmp";
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:

DELETE "ftpdata\\file.dat";
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.
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
RETR <sp> remotefile <crlf>
l Example:

# Interchange is installed on a Unix machine.
GET "C:\\ftp\\out\\file.dat" TO "/nfs/home/chpy/files.dat";
IF ELSE
Conditional execution.

l Syntax – IF (expression) { statements } [ELSE { statements } ]

l Description – The IF ELSE statement performs conditional execution of statements. The
expression parameter is one of the following.
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 Syntax – LIST remotedirectory INTO variable { statements }

l Description – The LIST statement reads the contents of a directory on the FTP server. If the
variable does not exist, it is created. For each entry found, variable is set to the file name, and
the statements block is executed.
The remotedirectory parameter can be an absolute or relative path. The format of the path is
system dependent.
If the script is executed locally, you can use wildcard characters in the remotedirectory
parameter.
The wildcard characters are:
o An asterisk, *, matches any substring.
o A question mark, ?, matches any single character.
o […] matches any one of the enclosed characters. For example, specifying [abc] matches a or
b or c, but no other character.
If the script is executed locally, the files are sorted by date, starting with the oldest. If the script
is not executed locally, the sort order is undefined.
FTP servers use different file-name formats. For example, some FTP servers include the directory
prefix in the file name. Your script should not make assumptions about the file-name format.
The directory listing is transferred using the ASCII representation type.
l FTP commands
TYPE <sp> A <crlf>
NLST <sp> directory <crlf>
TYPE <sp> original_type <crlf>
l Example 1
-LIST "." INTO %FILE {

RECV %FILE;
DELETE %FILE;
}
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;
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
!"echo START >> result.dat";
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:
l FILE COPY ARGUMENT(1) TO ARGUMENT

(2);
The program simply copies a file. Compile the program. You can now copy a file using the
following Local Command statement:
! "r4edi filecopy.x4 pathname1 pathname2";
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.
l Syntax – PUT localfile TO remotefile;

l Description – The PUT statement copies a local file localfile to the remote file
remotefile. If the file remotefile exists, it is by default overwritten. The file localfile is not
changed or deleted.
dependent.
dependent.
l FTP commands
If the value of the store-unique setting is off:
STOR <sp> remotefile <crlf>
If value of the store-unique setting is on:
STOU <sp> remotefile <crlf>
For details of the store-unique setting, see SUNIQUE on page 883.
l Example
# Interchange is installed on a Windows machine.

# Remote host is a Unix machine.
PUT "C:\\ftp\\out\\file.dat" TO "remotedir/files.dat";
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
QUOTE "SITE CHMOD 666";
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
RETR <sp> remotefile <crlf>

l Example
TYPE "I";
RECV "file.dat";
RENAME
Rename a file on the FTP server.
l Syntax – RENAME file TO newfile;

l Description – The RENAME statement renames a file on the FTP server. If the source and target
directories are different, the file is moved to the target directory and then renamed.

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.
l Syntax – SEND remotefile [APPEND];

l Description – The SEND statement can be used only in send scripts (that is, scripts in an FTP
send method). Interchange passes a message to the send method. The SEND statement then
sends a file containing this message to the FTP server. If the APPEND keyword is specified and
the file remotefile exists, the file is appended to the file remotefile. If the APPEND keyword
is not specified and the file remotefile exists, by default, the file overwrites the file remotefile.
dependent.
l FTP commands

If the value of the store-unique setting is off:
STOR <sp> file <crlf>
If value of the store-unique setting is on:
STOU <sp> remotefile <crlf>
If the APPEND keyword is specified:
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;
-DELETE %F;
}
%Break = "";
}
}

Test trading
16
After you set up a community, you are ready to add trading partners and begin trading. It is a good
practice to test a trading configuration before using it in a production environment.
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.

16 Test trading
Configure for test trading

Use this procedure to configure Interchange for test trading.
We recommend creating a temporary community and a self-signed certificate for the tests rather
than use the community and certificate that you would use for actual production trading of
documents. You can retire the temporary community and certificate after the tests.
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.

16 Test trading
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.
Start the test

Before you begin testing you need some test files on hand. For efficient testing, each of these
documents should be initially 10 KB or less in size. Once you have traded a number of documents,
you can increase the size of the test documents.
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.

16 Test trading
Troubleshoot email testing

If you are using email to send or receive messages and the transport does not perform correctly
during testing, try to determine the cause of the difficulty by checking the following items:
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?
Complete the testing

After you have completed your testing, document the test. Include details about:
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.

Extend and tune your
flow configuration 17
The topics in this section describe how to use the features of the Interchange user interface to fine
tune your flow configurations.
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 Sequential message delivery on page 947
l Embedded transport servers on page 431
l Test trading on page 885
l Document generator on page 97
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.
Add an application delivery setting

Click Add an application delivery setting to add an application delivery to the list.

17 Extend and tune your flow configuration
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.
Manage application delivery settings

Click in the Criteria and settings column of any entry of the list to open the Change application
delivery settings page.
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.
To open Message Simulator, select Trading configuration > Message simulator.
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:
l Simulate inbound message for – The community to receive the simulated message from a

partner.
l Simulate receiving message via – The message protocol the community pretends to use to
receive the message from the partner. You can select any protocol, regardless of whether it has
been configured in the community profile.
l Application delivery criteria – Optional metadata and values specifying delivery criteria for
an application delivery. Select a metadata element, type a value and click Add. You can add
multiple elements and values.
To run a test and change configuration information:
1. Click Run test to display test results.

2. Click Edit this exchange point below the test results to change delivery criteria or other
configuration.
The messages produced by Message Simulator are not real and are used only for testing. Message
Tracker does not keep records of simulated messages.
Uniqueness in Interchange
In order to process message flows in a coherent and predictable manner, Interchange enforces the
uniqueness of object names.

Unique object names

In order to configure Interchange, you create objects and assign values to attributes of these
objects.
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.
Set up message-processing actions

To set up message-processing actions:
1. From the menu bar click Processing configuration.

2. At the top of the Processing configuration page, in the navigation graphic, click either of the
Message handler icons.
Setting up message actions can be a two-step process:
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.
Define message attributes

Message attributes are name-value pairs whose values are extracted from messages through parsing
or have fixed values. Interchange can parse only XML messages, but attributes with fixed values can
apply to EDI, XML or binary documents.
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.
Any attributes that display after Virtual file user data have been added in addition to the

defaults. One way to add or delete attributes is to select System management > Manage
message attributes.
l Consumption file name – The name of the message picked up from an integration or delivery

transport.
l Production file name – The name of the message sent to integration or a partner.
l Sender routing ID – The routing ID of the sending party.
l Receiver routing ID – The routing ID of the receiving party.
l From – The name of the sending party.
l To – The name of the receiving party.

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.
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:
Sender ID equals Community A

(attribute) (operator) (value)
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.
1. ParsedSenderId not equal Sender routing ID

(attribute) (operator) (attribute)
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.
Define message attributes

Use this procedure to define message attributes. Attributes are used for setting up conditions for
message actions. For information about message actions, see Define message actions on page 897.
There are a number of default attributes. For descriptions of the default attributes see the list under
Define message attributes on page 893.
Note on multiple attribute definitions for a single attribute: If you add multiple message

attribute definitions that have criteria for the same attribute, the definitions are all applied in the
order in which they are listed in the user interface. This means that the last listed definition is the last
one applied, and is the one that provides the value for the attribute.
1. Click the Processing icon on the navigation graphic at the top of the community summary
page to open the Processing Configuration page.

2. Click the Message Handler icon at the top of the page to open the Message Handler page.

3. Click Add a new message attribute definition with criteria.
4. Select an attribute from the drop-down list and click Next.
If the attribute you want to add is not listed, click Add attribute, select an attribute and click
Next or Add followed by Next.
Alternately, you can type the name of your own custom attribute. Click Add attribute, select
the name field, type the name and click Add and Next.
If adding 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).
Another suggestion is 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).
5. On the Source tab, the presumption is the attribute value is attached to the message (for
example contained in a message header or added via an in-line processing action). That is the
meaning of The value comes from an external source radio button.
Alternately, you can define a value for the attribute, whether by parsing an XML document or
setting a constant (fixed) value.
Note: If you select The value comes from an external source, you must add at least one
condition. Otherwise, Interchange does not add the definition. It does, however, add the
attribute to the list at System management > Manage message attributes.
The Change attribute name option lets you make an on-the-fly decision to define a different
attribute. For example, on the first wizard page you select the SenderRoutingId attribute and
click Next. However, then you decide you want to instead define the ReceiverRoutingId
attribute. Rather than click Cancel and start over, select Change attribute name and select
the ReceiverRoutingId attribute. Click Save changes to see Interchange has saved a
definition for ReceiverRoutingId and not SenderRoutingId.
You also can use Change attribute name to change the attribute in a previously added
definition:
a. Under Message attribute definitions on the main message handler page, find the
attribute to change.
b. Click the link below Conditions for using this definition.
c. Select Change attribute name, select another attribute, change settings on the Source
and Conditions tabs as applicable.
d. Click Save changes.
6. On the Conditions tab, set up one or more conditions for the attribute. Although optional,
without at least one condition Interchange tries to parse all messages or apply the fixed value.
See Define conditions on page 894.
7. Click Save changes to keep your change.

Define message actions

Use this procedure to define a message handler message action. You may use the default attributes
or set up attributes for message actions. See Define message attributes on page 895.
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.
1. Click Message handler on the navigation graphic at the top of the community summary page

to open the message actions page.
2. Click Processing configuration on the main menu bar to open the Processing configuration
page. Then click Message handler in the Processing configuration graphic to open the
Message handler page.
3. In the list of tasks at the bottom of the page, click Add a new message processing action.
4. In the Attribute field, select an attribute from the drop-down list to use as filtering condition
for the action and click Next. For a description of the default attributes that you can select, see
the list under Define message attributes on page 893.
5. Specify an operator and value for triggering the action and click Next. See Define conditions
on page 894 for definitions of operators.
6. Select the action to perform, complete the applicable fields and click Finish.
The following list describes the available actions.
l Send a copy of the message to – Specify one or more parties as recipients of a copy of the

message. A copy can be sent only in the same direction as the original. For example, if a
community sends a message to partner A, a copy can be sent to partner B. However, after
receiving a message from partner A, a community cannot send a copy to partner B.
l Re-route the message to a specific party – Select this option and then select a partner to
receive the re-routed message from the list available partners.
l Re-route the message using an expression – Select this option, and then type an
expression to use to match a party name or routing ID.
You can select additional actions related to the expression matching:
o Reject the message when the expression cannot be matched to a party
o Force the default routing ID to be applied after matching
l Prohibit re-routing of the message – Select this option to prohibit re-routing of messages
that meet the specified conditions.
l Reject the message – Select this option to reject messages that meet the specified conditions.
You can type a text that provides the reason for the rejection.
l Perform inline processing via a Java class – The extensible architecture of Interchange
allows system integrators to apply custom logic to in-process messages as an integral part of the

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 Apply a message attributes template – Select this option if you want to apply a message

attributes template to messages that meet the specified conditions. See Message attributes
templates on page 424 for information about these templates. When you select this option you
must also select one of the following dependent options:
o Select the message attributes template to use – Select a message attributes template
from the list of available templates.
o Provide metadata variable to identify message attributes template to use –
You must also select an action to execute if the template cannot be applied.:
o Fail the message
o Log a warning
l Perform record format transformation – Select this option if you want to transform the
formatting of the file records. You can specify a format for the original (before transformation)
and target (after transformation) file. See Metadata for record file management on page 418 for
descriptions of the file formats in the drop-down lists.
When the transformation is attempted, the message attribute
RecordTransformationAttempted is set to true. If the transformation succeeds:
o The local file record format attributes will have the target format.
o The transformed payload will be associated to the Actioned state (backup file).

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.
Message handler re-routing

You can configure Message handler to re-route received messages when specified conditions are
met.
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.
Message header re-routing

You can use message headers that specify senders and receivers or routing IDs in documents for re-
routing.
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:
1. Click Trading partners on the navigation graphic at the top of the community summary page.

2. Select Allow messages to be re-routed.
Spoke partners must configure their trading engines to send messages to the hub.
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.
Configure record transformation in

message handler
About record transformation in message handler

Use the Interchange message handler to configure transformations of the records that you exchange
in 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.

3. From the task list at the bottom of the page, click Add a new message processing action

to open the wizard.
4. Select an attribute as a condition for applying the message attributes template, and click Next.
5. In the Select a message processing action page, select the option Perform record
format transformation.
6. Complete the fields. Enter values for the expected input format (original format) and the
desired output format (target format) resulting from the transformation:
Original format – These parameters specify the format of the source record, before
transformation. Any parameter that is not set in these fields is taken from the local file format
metadata attributes. See Metadata for record file management on page 418.
l File format – From the drop-down list, select a file format option:
o Use protocol value
o Binary, fixed record length
o Binary, variable record length
o Text, fixed record length
o Text, variable record length
l Record length – Enter a required record length, or leave this field blank to use the
protocol value
l Record padding character – Enter the character used for line padding (if any).
l Character set – Enter the character set used in the original file (Example: ASCII,
EBCDIC,...).
Target format – These parameters specify the format of the transformed record.
l File format – From the drop-down list select a file format option:
o Use protocol value
o Binary, fixed record length
o Binary, variable record length
o Text, fixed record length
o Text, variable record length
l Record length – Enter a required record length, or leave this field blank to use the
protocol value
l Record padding character – Enter the character to be used for line padding.
l Character set – Enter the character set to use (Example: ASCII, EBDC, ...)
7. Click Finish.
Disabling record transformation

To disable record transformations, do one of the following:

l In message handler, to turn off file transformation, clear the Perform record format

transformation option.
l Set the local or virtual FileFormat attribute to to OCTET_STREAM.
l Set the local and virtual file record attributes to exactly match.
Configure error processing

Use the Configure error processor page to configure the way Interchange handles messages when it
rejects them for any reason. This page enables you to react to message rejection by specifying the
inline processing rule(s) or the script to apply to the rejected message.
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.
About error processing

When Interchange rejects a message, it triggers error processing on the message at the moment of
rejection.
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.
Configure error processing

1. From the menu bar, select Manage trading configuration, to open the Communities page.
2. From the task list at the bottom of the page, select Configure error processing.
l Enable this error processor – Select to enable the processor on message rejection.
l Perform inline processing – Select this option if you want to apply inline processing
rules to a rejected message, then specify one or more inline processors:
o Description – Optionally enter a description of this inline processing rule.
o Class name – Enter the name of the Java class for implementing message error
processing.

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

Post-processing message metadata

The default message metadata for post-processing are described in the following table. These match
the default post-processing metadata elements in the shellscriptmetadata.xml file in
<install directory>\conf. Interchange checks this file to determine valid metadata for post-
processing. The parameter numbers are shown for Windows and UNIX.
Windows UNIX Message metadata Description
%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 post-processing elements

You can use other post-processing elements than those listed in the table in Post-processing
message metadata on page 906. Other metadata elements are documented in Message metadata
and attributes on page 412.
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.
Methods for writing scripts

You can use the following methods for writing post-processing scripts:
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.
Script example for Windows

The following is an example of a post-processing script for Windows. This script re-directs an
inbound file to a local directory and writes activity to an external log file. This example is provided
solely to illustrate the correct format for such scripts.
@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 set destdir=\\win03.cyclonesoftware.com\haboob\binary\%2\%1

set destdir=c:\dest\binary\%2\%1
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
rem if '%7' == 'application/EDI-X12' set destdir=c:\dest\x12

if '%7' == 'X12' set destdir=c:\dest\x12

if '%7' == 'application/EDIFACT' set destdir=c:\dest\edifact
rem if '%7' == 'application/xml' set destdir=c:\dest\xml

if '%7' == 'XML' set destdir=c:\dest\xml
echo Moving %3\%4 to %destdir%

move %3\%4 %destdir%
Script example for UNIX

The following is an example of a post-processing script for UNIX. This script re-directs an inbound
file to a local directory and writes activity to an external log file. This example is shown solely to
illustrate the correct format for such scripts.
#!/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" >>
echo The Production Filename is "$4" >>
echo The Consumption Filename is "$5" >>
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).
Post-processing points to consider

Consider the following points when performing post processing:
l There is no feedback from the post-processing script. The standard and error output streams of
the process are silently discarded.
l The return code is not checked.
l Errors are not published and the document is not rejected if any problems occur within the
script.
l Post processing is not reliable. The script is not retried in case of failure.
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.
Search and display collaboration settings

Use the Show collaboration settings command to search and display the currently active
collaboration settings between your communities and partners.
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).
Manage default collaboration settings

Default collaboration settings apply to all communities, unless overridden one of the more
specialized collaboration settings. To override default collaboration settings, see:
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
View and modify default collaboration settings

To view and modify global default collaboration settings for outbound messages:
1. From the Trading configuration menu, select Change default collaboration settings.

The Collaboration defaults for sending messages page is displayed.
The page is organized by tabs for outbound message protocols. There also is a reliable
messaging tab, which controls processes for resending messages.
2. To view or modify settings, click the tab for a protocol or service.
3. If you modify any settings, click Save changes.
For descriptions of the fields on each tab, see Default collaboration fields on page 911.
Default collaboration fields

The following sections describe the default collaboration settings. These settings control how
messages are sent for each message protocol. There also are settings for reliable messaging, which
control message resending.
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.
AS1 default settings

The AS1 tab shows default outbound message settings for the AS1 message protocol. The settings
affect all outbound documents for all communities, unless superseded by community-, category- or
partner-level settings. You can change these as you need.
l Request receipts from partners – Select this option to have your partners send receipts to

you upon receiving your messages. The receipts are signed or unsigned, depending on your
selection in the request signed receipts check box.
l Request receipts to be redirected – Select this option to request that receipts sent by
partners use the address in the Receipt-Delivery-Option line in the MIME header of outbound AS1
messages. You must type the alternate address in the return email address field.
l Request signed receipts – Select this option to have your partners sign the receipts they
send you.

l 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 to 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.
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 elements 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

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


o Request receipts be sent over a synchronous connection – Select this option if you
want synchronous receipts in accord with the AS2 standard. A synchronous receipt is
returned to the sender during the same HTTP session as the sender's original message. If you
trade messages larger than 10 megabytes, we recommend sending receipts over an
asynchronous connection to avoid tying up system resources. If you have a partner who
uses a version of Interchange earlier than 5.0, the default setting is asynchronous.
Coordinate with your partner to make sure both of you have the same setting.
o Request receipts be sent over an asynchronous connection – Select this option if
you want asynchronous receipts. If you select this, you must complete the next field. An
asynchronous receipt is returned to the sender on a different communication session than

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.
uncompressing.
o EDIINT/ZLIB – Select to trade with partners who use version 4.2 or later of Interchange or
o MIME/GZIP – Select to trade with partners who use versions of Interchange earlier than
o Message encryption algorithm – If you select encrypt messages, select an algorithm.

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.
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
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.
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,
changes when done.

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.


send you.
altered.
uncompressing.
o EDIINT/ZLIB – Select for trading 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 for trading with partners who use versions of Interchange earlier than

list on this tab.
changes when done.
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.


l Expect receipts from partners – Select this option to have your partners send receipts to you

upon receiving your messages. The receipts are signed or unsigned, depending on the user
message for which receipt is generated.
l Payload location – The payload transferred in a SOAP message can be in the SOAP body or
packaged as a MIME attachment. By default outbound payloads are placed in the SOAP body of
the packaged message. The payload also can be packaged as an attachment by changing this
field value. Setting the payload location to None has the effect of neither attaching the payload
as an attachment nor in the SOAP body. In the None case, a SOAP handler must be configured
to attach the payload where desired. To use the default configuration, set the payload location
to SOAP body.
l Message compression – Select this option to compress the messages you send. messages are
compressed using MIME/GZIP algorithm. 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.
l Split messages – Select this option to enable sending of large messages split into smaller units
o Mime envelope compression (None, MIME/GZIP)
two are identical, it ensures the contents have not been altered. Supported encryption
algorithms are Triple DES (default) and AES.
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.

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)
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.
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.

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.
l Pull response retry attempts – The maximum number of times Interchange can try to deliver

a user message in response to a pull request, when the delivery fails (if it shares the reliable
messaging resend interval for timeout processing).
Secure file default settings

The secure file tab shows default outbound message settings for the secure file message protocol.
The settings affect all outbound documents for all communities, unless superseded by community-,
category- or partner-level settings. You can change these as you need.

send you.
altered.
uncompressing.
o EDIINT/ZLIB is for trading with partners who use version 4.2 or later of Interchange or

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
list on this tab.
changes when done.
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.

o Inline processing. If you are a licensed SDK user, you can build a Java class and use it to
messages.
Generic email default settings

The generic email tab shows default outbound message settings for the Generic email message
protocol. The settings affect all outbound documents for all communities, unless superseded by
community-, category- or partner-level settings. You can change these as you need.

you upon receiving your messages. The receipts are unsigned.
Odette FTP V2 default settings

The OFTP V2 tab shows default outbound message settings for ODETTE File Transfer Protocol 2.x.
The settings affect all outbound documents for all communities, unless superseded by community-,
l Request signed receipts – Select this option to have your partners sign the receipts they

send you.
altered.

uncompressing.
o None. Select this if you do not want compression. Also, you must select this to exchange
o EDIINT/ZLIB is for trading with partners who use version 4.2 or later of Interchange or
PGP default settings

The PGP tab shows default outbound message settings for the PGP message protocol. The settings
affect all outbound documents for all communities, unless superseded by community-level,
category-level, partner-level or partner delivery-level settings. You can change these settings as you
need.
with your partner about compressing and decompressing as pre- and post-processing steps. You
decompressing.
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 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.
list on this tab.
changes when done.
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.
o Inline processing. If you are a licensed SDK user, you can build a Java class and use it to

messages.
RNIF 1.1 default settings

The RNIF 1.1 tab shows default outbound message settings for the RosettaNet 1.1 message
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 Base-64 Encode HTTP Messages – Convert outbound messages to base 64. If not selected,

messages are sent in binary format.
RNIF 2.0 default settings

The RNIF 2.0 tab shows default outbound message settings for the RosettaNet 2.0 message
o Encrypt service content and attachments – If encrypt messages is also selected, the
payload is encrypted (service-content and attachments).

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.
Web Services default settings

The Web Services tab shows default outbound message settings for the Web Services message
community-, category- or partner-level settings.
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.
l Send handler config file – Name of the file in <install directory>\conf used when

packaging a message. Interchange provides two versions of this file:
o axis2.xml – (Default) 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.
o axis2NoWSAddressing.xml – This file disables WS-Addressing. If you do not want to use
WS-addressing, select this file.
You can optionally create a customized version of this file, and select it for use with outbound
messages. However, doing so requires engaging a professional services consultant, obtaining
the optional Software Development Kit, or both.
l Payload location – The payload transferred in a SOAP message can be in the SOAP body or
packaged as a MIME attachment. By default outbound payloads are placed in the SOAP body of
the packaged message. The payload also can be packaged as an attachment by changing this
field value. 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, a SOAP handler must be configured to
attach the payload where desired. To use the default configuration, set the payload location to
SOAP body.
l 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. To use
the default configuration, use the default value of handleMessage.
l SOAP version – Specifies whether Interchange, acting as a web service client, uses SOAP 1.1
(default) or SOAP 1.2 to trade with a remote trading partner. You can override this setting by
using the SOAPVersion metadata attribute.
l Encrypt messages – Select this option to encrypt outbound messages. To use the default
configuration, make sure this check box is selected and do not change values of any of the
related fields.

o Message encryption algorithm – Supported encryption algorithms are Triple DES

(default) and AES.
o Encrypt attachments – Sets whether attachments are encrypted (on by default).
o Encrypt SOAP body – Sets whether the SOAP body is encrypted (on by default).
o XPaths to encrypt – You can add specific SOAP envelope elements and sub-elements to be
encrypted. For each you add, specify the namespace prefix, namespace URI and local
XPath.
XPath example:
Namespace prefix: soapenv
Namespace URI: http://schemas.xmlsoap.org/soap/envelope/
Local XPath: /soapenv:Envelope/soapenv:Body
o ID refs to encrypt – You can add specific SOAP envelope elements and sub-elements to be
encrypted.
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:
Local XPath: /soapenv:Envelope/soapenv:Header
Local XPath: /soapenv:Envelope/soapenv:Body
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.
cXML default settings

The cXML tab shows default outbound message settings for the cXML message protocol. The
settings affect all outbound documents for all communities, unless superseded by community-,
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.
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
list on this tab.

changes when done.
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.
X.420 default settings

The X.420 tab shows default outbound message settings for the X.420 message protocol. The
category- or partner-level settings.
l Number of minutes to wait for response from remote MTA – The interval the X.400

subsystem waits for replies from the partner’s message transfer agent.
l Request receipt notifications – Select whether to request the remote application to
acknowledge receiving messages. There are two types of notifications. A receipt notification is a
positive response that a message has been received. A non-receipt notification is a negative
response indicating the remote application has rejected the message. Requesting receipt
notifications is optional.
l Request non-delivery notifications only – A non-delivery notification means a message
failed to deliver or was rejected by the remote system.
l Request both delivery and non-delivery notifications – A delivery notification means a
message has been delivered to the remote system, but has not been accepted. A non-delivery
notification means a message failed to deliver or was rejected by the remote system.

X.435 default settings

The X.435 tab shows default outbound message settings for the X.435 message protocol. The
category- or partner-level settings.
l Number of minutes to wait for response from remote MTA – The interval the X.400

subsystem waits for replies from the partner’s message transfer agent.
l Notification and signing options (security class) – Defines the notification and security
class for communicating with the remote partner. The following defines the classes.
o Class 0 – Only MTS non-delivery reports are requested. A non-delivery report is returned if
the message cannot be delivered to the remote UA.
o Class 1 – In addition to class 0, negative EDINs are requested. The recipient UA sends a
negative EDIN if it rejects responsibility for the received EDIM.
Note: If class 0 or 1 is selected and no errors are reported, the transfers are considered
successful when the internal sent event is received.
o Class 2 – In addition to class 1, positive EDINs are requested. The recipient UA sends a
positive EDIN if it accepts responsibility for the received EDIM.
o Class 3 – In addition to class 2, proof of end-to-end delivery is requested by virtue of signed
EDINs. The signature shows the message from the originator to the recipient was received.
This is similar to a signed return receipt.
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
Reliable messaging default settings

The Reliable messaging tab shows default outbound settings for message resend attempts. The
tab applies only to messages for which receipts are expected. The settings affect all outbound
documents for all communities, unless superseded by community-, category-, partner- or partner
delivery-level settings. You can change these as you need.
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.
Manage community-specific collaboration

settings
You can specify a subset of collaboration settings that apply specifically to one community.
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.
View and modify collaboration settings for a

community
To view or modify the collaboration settings specific to a community:
1. Open a community summary page.
2. On the community navigation graphic, click Collaboration settings to open the Configure
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.
Select a category for specialized collaboration

settings with a community
Before you can set specific collaboration settings between a specific community and a specific
category, you must select the category for specialized collaborations. To do this you must have:
l At least one community
l At least one partner
l At least one category
To specialize collaboration between a community and a category:
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.
Specialize community-to-category collaboration

settings
2. Click Collaboration settings on the navigation graphic at the top of the page to open the
3. In the left pane, in the community/partner tree, click the name of a category to open the
Configure community to category specific collaboration settings page.
4. Select the settings to specialize and modify settings as required.
See Community and category collaboration fields on page 933 for descriptions of the options.
Community and category collaboration

fields
The following describes the community and category collaboration override options.
l Pick the sender routing ID – If a community has multiple routing IDs, you can pick one as

the ID that is included in packaged messages.
l Set sending rules for the AS1 message protocol – Override the AS1 global defaults. For
field descriptions see AS1 default settings on page 911.
l Set sending rules for the AS2 message protocol – Overrides the AS2 global defaults. For
l Set sending rules for the Secure file message protocol – Overrides the secure file global
defaults. For field descriptions see Secure file default settings on page 920.
l Set sending rules for the Generic email message protocol – Overrides the secure email
global defaults. For field descriptions see Generic email default settings on page 922.
l Set sending rules for the Odette FTP V2 message protocol – Overrides the OFTP 2.x
global defaults. For field descriptions see Odette FTP V2 default settings on page 922.
l Set sending rules for the PGP message protocol – Overrides the PGP global defaults. For
field descriptions see PGP default settings on page 923.

l Set sending rules for the cXML message protocol – Overrides the cXML golbal defaults.

For field descriptions see cXML default settings on page 928.
l Set sending rules for the RosettaNet (RNIF) 1.1 message protocol – Overrides the
RosettaNet 1.1 global defaults. For field descriptions see RNIF 1.1 default settings on page 925.
RosettaNet 2.0 global defaults. For field descriptions see RNIF 2.0 default settings on page 925.
l Set sending rules for the Web services message protocol – Overrides the web services
global defaults. For field descriptions see Web Services default settings on page 926.
l Set sending rules for the X.420 message protocol – Overrides the X.420 global defaults.
For field descriptions see X.420 default settings on page 929.
l Set sending rules for the X.435 message protocol – Overrides the X.435 global defaults.
For field descriptions see X.435 default settings on page 930.
l Set resend attempts and interval for reliable messaging – Overrides the defaults for
resending messages. For field descriptions see Reliable messaging default settings on page 930.
l Specify the signing certificate to use – Lets you specify the certificate to use for signing
messages, if it is different than the community default signing certificate.
l Specify the receipt signing certificate to use – Lets you specify the certificate for signing
receipts sent to partners acknowledging messages have been received. You can specify the
receipt signing receipt if different than the community default certificate.
l Specify whether to encrypt or sign messages and choose algorithms – Overrides the
global defaults for encrypting and signing messages. This option overrides not only the default
collaboration settings for your installation, but the protocol-specific signing and encrypting
settings you might have set up for this community.
When selected the following fields display.
o Encrypt messages – Select this check box to encrypt the messages you send.
o Sign messages. Partners use your certificate to verify you as the sender – Select
this check box to digitally sign the messages you send.
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.
Manage community-to-partner specific

You can specify collaboration settings that apply between one specific community and one specific
partner.

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.
Select a partner for specialized collaboration settings

with a community
partner, you must select the partner for specialized collaborations. To do this you must have:
l At least one community.
l At least one partner.
To specialize collaboration between a community and a partner:
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.
Specialize community-to-partner collaboration

settings
3. In the left pane, in the community/partner tree, click the name of a partner to open the
Configure community to partner specific collaboration settings page.

The following list describes the override options:
l Pick the sender routing ID – If a community has multiple routing IDs, you can pick one

as the ID that is included in packaged messages.
l Pick the receiver routing ID – If a partner has multiple routing IDs, you can pick one as
l Set sending rules for the AS1 message protocol – Overrides the AS1 global defaults.
For field descriptions see AS1 default settings on page 911.
l Set sending rules for the Secure file message protocol – Overrides the secure file
global defaults. For field descriptions see Secure file default settings on page 920.
l Set sending rules for the Generic email message protocol – Overrides the secure
email global defaults. For field descriptions see Generic email default settings on page 922.
l Set sending rules for the Odette FTP V2 message protocol – Overrides the OFTP
2.x global defaults. For field descriptions see Odette FTP V2 default settings on page 922.
l Set sending rules for the PGP message protocol – Overrides the PGP global defaults.
For field descriptions see PGP default settings on page 923.
l Set sending rules for the cXML message protocol – Overrides the cXML golbal
defaults. For field descriptions see cXML default settings on page 928.
RosettaNet 1.1 global defaults. For field descriptions see RNIF 1.1 default settings on page
925.
RosettaNet 2.0 global defaults. For field descriptions see RNIF 2.0 default settings on page
925.
l Set sending rules for the Web services message protocol – Overrides the web
services global defaults. For field descriptions see Web Services default settings on page
926.
l Set sending rules for the X.420 message protocol – Overrides the X.420 global
defaults. For field descriptions see X.420 default settings on page 929.
l Set sending rules for the X.435 message protocol – Overrides the X.435 global
defaults. For field descriptions see X.435 default settings on page 930.
l Set resend attempts and interval for reliable messaging – Overrides the defaults
for resending messages. For field descriptions see Reliable messaging default settings on
page 930.

l Specify the signing certificate to use – Lets you specify the certificate to use for

signing messages, if it is different than the community default signing certificate.
l Specify the partner's encryption certificate to use – Select this option to choose
which of the partner’s certificates to use to encrypt messages.
l Specify the receipt signing certificate to use – Select this option to choose which of
the partner’s certificates to use to sign message receipts.
l Specify whether to encrypt or sign messages and choose algorithms– Overrides
the global and community-level defaults for encrypting and signing messages. This option
overrides not only the default collaboration settings for your installation, but the protocol-
specific signing and encrypting settings you might have set up for this partner.
When selected the following fields display.
o Encrypt messages – Select this check box to encrypt the messages you send.
o Message encryption algorithm – If you select encrypt messages, select an
algorithm.
o Sign messages. Partners use your certificate to verify you as the sender –
Select this checkbox 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 Specify the delivery exchange to send messages to – Lets you choose the

transport for sending messages to this partner.
Manage community-to-partner delivery

specific collaboration settings
You can specify collaboration settings to apply between one specific community and one specific
partner delivery.
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

Select a partner delivery for specialized

collaborations settings with a community
partner delivery, you must select the partner delivery for specialized collaborations. To do this you
must have:
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:
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.
Specialize community-to-partner delivery

3. In the left pane, in the community/partner tree, click the name of a partner delivery to open the
Configure community to delivery-specific collaboration settings page.
The following list describes the override options.
l Pick the sender routing ID – If a community has multiple routing IDs, you can pick one as
l Pick the receiver routing ID – If a partner has multiple routing IDs, you can pick one as the
ID that is included in packaged messages.
l Set sending rules for the Web services message protocol – Overrides the Web services
global defaults. For field descriptions see Web Services default settings on page 926.

l Set resend attempts and interval for reliable messaging – Overrides the defaults for

resending messages. For field descriptions see Reliable messaging default settings on page 930.
l Specify the signing certificate to use – Select the signing certificate from a list of available
certificates.
l Specify the receipt signing certificate to use – Select the receipt signing certificate from a
list of available certificates.
l Specify the partner's encryption certificate to use – Select the partner's encryption
certificate from a list of available certificates.
l Specify whether to encrypt or sign messages and choose algorithms – Set message
encryption and signing requirements on this delivery, and choose algorithms for selected
signing requirements.
Inbound message validation rules

Use the Configure message validation rules page to specify whether a community accepts or rejects
messages and documents from partners. You can specify whether a community accepts or rejects:
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.

Configure message validation rules

To set the conditions for accepting or rejecting messages and documents from partners:
1. In the user interface, from the Trading configuration menu select a community that

receives messages from one or more partners.
2. On the community graphic at the top of the page, click the Message Validation icon.
3. The interface displays the Configure message validation rules page.
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
Validation rules: Duplicate messages tab

Use the Duplicate messages tab of the Configure message validation rules page to control
whether a community accepts or rejects duplicate EDI documents .
Select an option:
l Reject duplicate EDI document IDs – Select this if you want Interchange to check if an

inbound message duplicates a previously received message in the following ways:
o Duplicate control number
o Duplicate sender name
o Duplicate sender routing ID
o Duplicate receiver name
o Duplicate receiver routing ID
If all of these values are the same as those in a previously received message, the message is
rejected and given a failed status. You can search for failed messages in Message Tracker on
page 826.
Interchange only checks for duplicates of EDI documents. Specifically, this means documents
with the following MIME types:
o application/EDI-X12 (X12 document)
o application/EDIFACT (EDIFACT document)
o application/EDI-consent (TRADACOMS document)

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:
l Click Add an exception for a partner to create a partner-specific exception.

l Click Add an exception for a category to create an exception for a partner collaboration
category. A collaboration category is a group of partners who have common collaboration
settings.
l Click Add an exception for a trading pickup to create an exception for messages received
by the community through a specific community trading pickup.
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.
Validation rules: Signing tab

Use the Signing tab of the Configure message validation rules page to control whether a
community accepts or rejects unsigned messages .
Select an option:
l Reject messages that are not signed (DEFAULT) – Select this option if you want the

community to only accept messages that are signed with your partner’s private encryption key.
Your community verifies the signature with the public key in the digital certificate associated
with the partner. To receive signed messages, the partner’s certificate and public key must be
included in the partner information.
l Accept messages that are not signed – Select this option if you want the community to
accept both unsigned messages and signed messages (if the partner’s certificate is included in
the partner information).
Whether you choose to reject or accept messages that are not signed, the choice applies to all
exceptions to the message signing option:

settings.

Validation rules: Encryption tab

Use the Encryption tab of the Configure message validation rules page to control whether a
community accepts or rejects unencrypted (plain text) messages.
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
exceptions to these options:

settings.
You can add multiple partners, c ategories or exchange points to the exceptions lists. Interchange
Validation rules: CSOS duplicate orders tab

If your user license enables the CSOS functionality, the CSOS duplicate orders tab is displayed.
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:

l Reject duplicate CSOS purchase orders (default) – Select this option if you want

Interchange to check whether an order duplicates a previously received order in the following
ways:
o Duplicate order number
o Duplicate DEA registration number
o Duplicate sender name
o 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.
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.
l Allow duplicate CSOS purchase orders – Select this option to let Interchange accept
duplicate orders.
Whether you choose to reject or accept d uplicate CSOS purchase orders, the choice applies to all
exceptions to the message signing option:

settings.
Validation rules: Web Services tab

Use the Web Services tab of the Configure message validation rules page to control how the
community handles inbound Web Services and AS4 message authentication.
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>
l Reject messages when password is in plain text (not digest)

You can only select this option if you first select the "Reject messages" option above. When you
select this option, the partner must send the password in digest form, as in the following
example:
<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 without UsernameToken in SOAP header (default) – Enables the

community to consume Web Services or AS4 messages that do not include UserName tokens.
l Reject messages that are not authorized using X509 digital signature defined
within SOAP header – When you select this option, Interchange checks for an X509 token in
the signature SOAP Header of an AS4 or Web Services inbound message. X509 tokens are also
available for encryption security headers, but they are not subject to this validation. If the X509
token is absent or refers to an invalid certificate, the message is rejected.

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:
l Web Services UsernameTokens

l X509 Digital Signature Authentication
To apply exceptions, locate one of the above categories on the validation rules page and:

settings.
Validation rules: AS4 tab

Use the AS4 tab of the Configure message validation rules page to control how Interchange
handles the AS4 messages that it consumes from remote partners.
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:
l Ignore duplicate AS4 message IDs – Select this option if you want Interchange to check if

an inbound AS4 message duplicates a previously received message.
l Allow duplicate AS4 message IDs – Select this option to let Interchange accept duplicate
AS4 messages.
Whether you choose to ignore or allow duplicate AS4 message IDs, the option applies to all AS4
messages received by the community, unless you define exceptions. You can set up the following
exceptions to these options:


settings.
l Click Add an exception for a partner's web services or AS4 delivery to create an
exception for messages received synchronously through a partner web service or AS4 delivery.
You can add multiple partners, c ategories or exchange points to the exceptions lists. Interchange
Validation rules: cXML tab

Use the cXML tab of the Configure message validation rules page to control whether a community
accepts cXML messages with a shared secret.
Interchange cXML delivery exchanges optionally can require passwords in a SharedSecret element in
the cXML document header.
Select an option:
l Reject messages without a shared secret – Select this option if you want the community

to only accept cXML messages that have shared secret elements.
l Accept messages that are not signed (DEFAULT) – Select this option if you want the
community to accept cXML messages with and without shared secret elements.
Whether you choose to reject or accept cXML messages without shared secrets, the choice applies to
all messages received for the community, unless you define exceptions. You can set up the
following exceptions to the message signing option:

settings.

Sequential message delivery

In Interchange message-handling, sequential delivery is the ability to deliver messages in the
order they were originally consumed on a specific pickup, and also filtered for delivery by the
resolved destination application or partner delivery. This is sometimes referred to as first-in-first-out
(FIFO) behavior.
How Interchange manages sequential

delivery
An Interchange internal sequence manager ensures that messages are delivered in the order in which
they are consumed, per pickup and per resolved destination partner or application pickup delivery.
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
Sequential delivery behavior
Message consumption (as client)

l Each pickup with the sequential message delivery option activated has a single consumer per
cluster (no multiple parallel message consumption).
l For MQ and POP3, messages are presented in a FIFO manner. Interchange assigns the order
(generating sequential IDs) based on this FIFO order.

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.
Message consumption (as server)

For FTP and SFTP embedded servers:
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).
Message production (as client)

In general, sequential delivery can only work if one and only one output message is generated for
each input message.
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.
Message production (as server)

For the FTP and SFTP embedded servers:
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.
Previous message sequence saved as

metadata
When Interchange assigns a new sequence ID and number (derived from consummation order and
destination delivery exchange) it adds the previous SequenceId and SequenceCount to the
metadata (PreviousSequenceId and PreviousSequenceNumber respectively). You can then
use this metadata in Message Tracker searches to track messages in their previous sequence.
Empty message handling

In the case where Interchange allocates a sequence ID/Number but fails to produce the message to
the integration engine, it produces an empty message. This can occur when Interchange starts to
consume a payload, assigns the sequence ID/Number, but then payload transfer fails. In this case,
the allocated sequence ID/Number is canceled in Interchange and an empty message is sent to the
integration engine indicating that no message will be received for that ID/Number.
Examples
Normal sequence:
Sequence ID Sequence
number
1 1
1 2
1 3
1 4
Sequence with failed message number 3.
number
1 1
1 2

number
1 3 (failed)
1 4
Sequence with dummy message replacing failed message number 3.
number
1 1
1 2
1 3 (dummy/empty)
1 4
Out of sequence behavior

In the case of multiple out of sequence instances, the sequence is not guaranteed.
For example:
Message number Status Timeout status (seconds)
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.
Recovery on shut down

Interchange sequential delivery behavior is identical for clean shutdowns and forced shutdowns. In
both cases, Interchange stops processes abruptly. There is no concept of a graceful shutdown.
When Interchange starts up again up, the fail-over coordinator analyzes all work that was in-process
at the moment of the shutdown. The fail-over coordinator re-introduces the work in the system,
resetting timers to the original configured value of XX seconds. Reintroduction of the “old remaining
workload” consumes 50% of the system capacity.
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:
Message Status Timeout status

number (seconds)
1 In transfer –
2 Available 5
3 Available 10
After restart:

number (seconds)
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.


number (seconds)
1 Not available –
2 Available 60
3 Available 60
Existing workload vs new workload

After a shut down, the new messages that Interchange picks up from either the application side or
the trading side, end up back in the list of to-do work. As reload tasks are limited to 50% of the
capacity, it can take a while achieve full recovery.
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.
Manual resubmission and sequential

delivery
When Interchange rejects messages because the processing failed, it is the responsibility of the
sending user to resubmit messages in the proper sequenced order.
If sequencing is activated on the corresponding pickup, Interchange guarantees that the order in
which messages are re-submitted is kept.
Unique identities in metadata for

sequenced messages
The following metadata attributes are now added to messages that are handled in Interchange:

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.
Sequential delivery limitations

l Sequential delivery is only provided for the transport protocols listed. See Supported protocols
on page 947.
l When using sequential delivery with a Metadata Profile, you cannot change the format type in
the associated Metadata Service. The new format type is not recognized and the document is
routed based on the original format type.
Use generic MMDs

In file system integration with a back-end system, Interchange supports use of message metadata
documents (MMDs) as the interface between it and the back-end. MMDs are XML documents that
point to documents on a file system and contain information Interchange or a back-end system uses
for processing.
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
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 ebXML on page 545
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:
<?xml version="1.0" encoding="UTF-8" ?>

<MessageMetadataDocument documentId="TestMMD" protocol="generic"
<Metadata name="From">community2</Metadata>
<Metadata name="To">community1</Metadata>
<MessagePayloads>
<MimeContentID>smallXmlPo</MimeContentId>
<MimeContentType>application/EDI-X12</MimeContentType>
<Location type="filePath">C:/payload/community2_TO_community1_
1.edi</Location>
</Payload>
</MessagePayloads>

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:
<?xml version="1.0" encoding="UTF-8" ?>

<MessageMetadataDocument id=ID161019851226531680367remery-imac"
protocol="generic" protocol version="1.0">
<Metadata name="From">esx6-as2</Metadata>
<Metadata name="IsDuplicate">false</Metadata>
<Metadata name="To">remery-as2</Metadata>
<Metadata name="BusinessProtocol">AS2</Metadata>
<Metadata name="PayloadCount">1</Metadata>
<Metadata name="CoreId">ci1226531678390.799@remery-imac_te</Metadata>
<Metadata name="ExpirationTime">1230419678390</Metadata>
<MessagePayloads>
<Payload id="ID92717771226531680365remery-imac">
<Location
type="filePath">/Users/remery/Source/CI5/Trunk/myCommon/data/in/esx6-
as2_TO_rememry-as2_1242.edi</Location>
</Payload>
</MessagePayloads>

Staged HTTP
18
The staged HTTP transport provides a secure way for communities to receive messages from
partners without having to change firewall configurations.
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
Overview of staged HTTP

The staged HTTP transport provides a secure way to receive messages from partners without having
to change firewall configurations. You can use this transport after deploying the staged HTTP servlet
on a web server in your DMZ. You also must add staged HTTP as an inbound transport in your
community.

18 Staged HTTP
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.

18 Staged HTTP
Staged HTTP configuration outline

To configure staged HTTP in Interchange:
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.
Staged HTTP files to deploy

The files that you must deploy on the web server for the staged HTTP servlet are located in
<install directory>\util\stagedhttp. Archive files in TAR and WAR formats are provided.
A TAR file must be unpackaged and the files manually copied to the web server. A WAR file deploys
automatically once copied to the web server.
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:
http://<web server host>:<port>/stagedhttp/config
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.

18 Staged HTTP
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.
1. Click New Mailbox at the top of the staged HTTP configuration manager page to display the

mailbox maintenance page.
2. In the URL field, type a directory name where inbound files are written. As you type the name, it
is appended to the URL in the URL field.
The partner connects with this URL to POST documents to the servlet directory. Interchange
connects with the same URL to pick up documents.
When you give the URL to the partner or Interchange administrator, you must add the domain
and port of the web server. For example, the mailbox maintenance page displays a URL like this:
http://webserver/webmailbox/partner
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
3. In the Company Name field type the name of the partner using this mailbox.

18 Staged HTTP
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.
Partner connection to staged HTTP

A default remote user is included with the deployment, or you can add a user to the web server and
have one or more partners connect using it. Partners should not use the ecengine user to connect.
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>

</auth-constraint>
...
</security-constraint>
....
</web-app>

18 Staged HTTP
Edit, delete, view mailboxes

To edit, delete or view contents of mailboxes, select a mailbox on the staged HTTP configuration
manager page and click the action you want on the top toolbar.
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.
Staged HTTP UI fields

The following fields are used in the delivery exchange wizard in Interchange user interface for
configuring this transport. See Message protocols for staged HTTP on page 964 for information
about using staged HTTP with the AS2, ebXML, RosettaNet 1.1, RosettaNet 2.0 and secure file
message protocols.
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

18 Staged HTTP
l Clients must use SSL to connect to this server –Select this to have Secure Sockets Layer

a certificate in a community or partner must be designated as the SSL certificate. The server must
support SSL. If this is not selected, connections are not encrypted.
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.
Message protocols for staged HTTP

The staged HTTP transport is supported for the AS2, ebXML, RosettaNet 1.1, RosettaNet 2.0 and
secure file message protocols. The following topics provide notes about using each protocol with
staged HTTP. Extra configuration steps are required only with the secure file message protocol.
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.
RosettaNet 1.1 and 2.0

Using staged HTTP to trade RosettaNet 1.1 and 2.0 messages does not require any special
configuration of the staged HTTP servlet. However, Interchange does not support synchronous
RosettaNet 2.0 responses of any type (single or dual action). Consequently, synchronous
RosettaNet 2.0 responses over staged HTTP are not supported.
Secure file
Supporting the secure file message protocol requires special configuration of the staged HTTP
servlet.

18 Staged HTTP
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>

18 Staged HTTP
File forwarding to bypass polling

The default way to receive messages via the staged HTTP transport is Interchange polling of the web
server for inbound messages sent by partners. You can set up another way, where the web server
forwards messages to Interchange upon receipt. This bypasses polling and increases throughput,
but opens a port into your trusted network.
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.

18 Staged HTTP
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.
High availability staged HTTP

The following figure shows the staged HTTP servlet in a high availability configuration to handle
inbound traffic. This involves setting up servlets on multiple web servers. A load balancer is used to
direct traffic to each web server. The partner uses the virtual IP address of the load balancer in
sending messages.
In this clustered example, each instance of Interchange needs a staged HTTP delivery exchange for

18 Staged HTTP
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.
Deploy the web servlet

Use this procedure to deploy the staged HTTP servlet on a supported web server application. See
Staged HTTP files to deploy on page 960 to find the servlet files in Interchange directory tree. The
servlet has been validated against the following web servers:
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.
Directory type Default path File that defines path
Message Windows: conf\

processing C:\opt\cyclone\data\stagedhttp configurationrules.
Unix: xml
/opt/cyclone/data/stagedhttp
Message Windows: conf\

temporary C:\opt\cyclone\tmp\mailbox-data webmailboxconfig.
Unix: xml
/opt/cyclone/tmp/mailbox-data

18 Staged HTTP
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.
Deploy on Apache Tomcat

Use the following steps to deploy the staged HTTP servlet on an Apache Tomcat web server. These
steps are provided as guidelines. See the web server user documentation for specifics about
deploying servlets.
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.
Map the user... ...to the role
mailboxadmin mailboxadmin_role
ecengine ecengine_role
remoteuser remoteuser_role
communityadmin communityadmin_role
3. Logon to the Tomcat UI. Access the “Manager App”.

18 Staged HTTP
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:
Map the user... ...to the role
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 19
Secure file message protocol is an Axway-proprietary protocol that provides EDIINT packaging over
transport protocols not supported by EDIINT AS1 / AS2 / AS3.
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
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 and receiver determination

The following outlines the order in which Interchange determines sender and receiver. This
information is provided for users who may want to post messages to Interchange with their own
tools.

19 Secure file message protocol
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.
Minimal MIME headers

An inbound, clear text payload must contain the Content-Type: and Content-Length: headers at an
absolute minimum.
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.
Frequently asked questions

l What MIME headers are used?
Secure file is EDIINT based (actually EDIINT AS2). Secure file uses most of the same headers as
AS2. Secure file does not use as2-to and as2-from. See Sender determination on page 972.
l Are multiple attachments supported?
No.
l Is it possible to add custom MIME headers to the packaged outbound message?
No.
l Which encryption algorithms and signing algorithms are supported?
The same as AS1, AS2 and AS3.
l What about multi-part MIME? Are MultiPartForm data POSTs supported?
See the EDIINT and AS2 specifications.
l Does Secure file support subject line parsing for true-sender and true-receiver?
Secure file shares code with the other EDIINT business protocols. All the EDIINT business
protocols support Interchange Subject Line parsing.
l What is the effect of security and signing vs. clear text?

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.
l Post an X12 file – For the following command to work, configure the ep1 exchange point to

parse EDI documents.
curl --header content-type:application/EDI-X12 --data @myfile.edi
http://hostname:port/exchange/ep1
l Post an EDIFACT file – For the following command to work, configure the ep1 exchange

point to parse EDI documents.
curl --header content-type:application/EDIFACT --data @myfile.edi
Optionally, the following can be included to avoid document parsing:
--header X-Cyclone-To:senderroutingid --header X-Cyclone-
From:receiverroutingid
l Post a XML file – For the following command to work, configure the ep1 exchange point to

parse XML documents. Also, configure the XPath of sender and receiver in myfile.
curl --header content-type:application/xml --data @myfile.xml
Optionally, the following can be included to avoid document parsing:
--header X-Cyclone-To:senderroutingid --header X-Cyclone-
From:receiverroutingid

l Post a binary file – In the following example, receiverroutingid is a routing ID of a configured

partner.
curl --header from:receiverroutingid --header content-
type:application/octet-stream --data @myfile.bin
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.
Secure file signed encrypted request signed

ack
Message-ID: <name-T40H_te1093984405402.238@name-T40H>
Date: Tue, 31 Aug 2004 20:33:26 GMT
From: sender
Subject: namelinux2;haboob
Mime-Version: 1.0
Content-Type: application/pkcs7-mime; smime-type=enveloped-data;
name=smime.p7m
Content-Transfer-Encoding: binary
Content-Disposition: attachment; filename=smime.p7m
Disposition-Notification-To: sender
Disposition-Notification-Options: signed-receipt-protocol=optional,
pkcs7-signature;
signed-receipt-micalg=optional, sha1
X-Cyclone-To: namelinux2
X-Cyclone-From: sender
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 Çâÿ¸†Ôàú'/ã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îúú`D%«pÜÊ§Šü–«£[u´8Ã€èfc®%+dd – ò`dmœPðªm…=´
{8b¢ƒDf=¤*w rè/ëâa5@¥#‰¢‘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˝Çá¹×ì¿!*)
Secure file no security

Message-ID: <REmery-T40H_te1093984862754.266@REmery-T40H>
Date: Tue, 31 Aug 2004 20:41:02 GMT
From: haboob
Subject: remerylinux2;haboob
Mime-Version: 1.0
Content-Type: application/EDI-X12;
name=haboob_TO_remerylinux2_10734.edi
Content-Transfer-Encoding: binary
Content-Disposition: attachment;
filename=haboob_TO_remerylinux2_10734.edi
X-Cyclone-To: remerylinux2
X-Cyclone-From: haboob
ISA*00* *01*XXXXXX *ha*boob *re*merylinux2 *961106*2106*U*00302

*000010734*0*P*>&GS*DX*2162523233*2102468507*961106*2106*666*X
*003020UCS&ST*894*6300001&G82*D*4046252*007924756*0185*004180022
*001180*961111&LS*100&G83*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*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*000010734&
Secure file from curl

POST /exchange/haboob HTTP/1.1
User-Agent: curl/7.10.6 (i386-redhat-linux-gnu) libcurl/7.10.6
OpenSSL/0.9.7a ipv6 zlib/1.1.4
Host: name-t40h:4080
Pragma: no-cache
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
Content-Type: application/EDI-X12
ISA*00* *01*XXXXXX *re*merylinux2 *ha*boob2

*961106*2106*U*00302*000002749*0*P*>&GS*DX*2162523233
*2102468507*961106*2106*666*X*003020UCS&ST*894*6300001&G82
*D*4046252*007924756*0185*004180022*001180*961111&LS*100&G83
*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
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
PHOTO&G83*15*12.000*&SE*2591*6300001&GE*1*666&IEA*01*000002749&

WebTrader
20
WebTrader enables anyone with a computer, a web browser, and an Internet connection to engage
in B2B commerce with other WebTraders, as well as with partners with sophisticated e-commerce
trading systems.
Can you use WebTrader?

You can use WebTrader if your software license.xml file enables the webtrader key. To check,
select Help > License information on the toolbar in the Interchange user interface. Additional
license keys enable more levels of WebTrader functionality. The other keys are listed in the
applicable WebTrader topics.
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:

20 WebTrader
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.
l Between a WebTrader partner and the sponsor

A WebTrader partner and sponsor can exchange documents.
l Between WebTrader partners
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.
Manage WebTrader partners and users

The procedures in this section describe how to create and mange WebTrader end users for the
exchange of documents with sponsors or other partners.
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

20 WebTrader
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
After you create a WebTrader partner

After you create a WebTrader partner or user, the partner can log onto the Interchange user
interface and use a limited set of functions to send, receive and manage WebTrader documents.
Add a WebTrader partner

Use this procedure to set up a WebTrader profile on the sponsor's Interchange server.
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
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>

20 WebTrader
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:
o Allow trading with all members of subscribed communities

o Allow trading with sponsor and any sponsor representatives
o Allow trading with all members of subscribed communities and also assume
the role of sponsor representative
l Choose the roles this user should have - From the list of available roles, select the
roles that you want to give to this WebTrader. After installing Interchange, there is a single
default role available by default: WebTrader user. This role grants all privileges to the
WebTrader user.
4. Click Finish to create the WebTrader partner.
The WebTrader partner is added to the list of WebTrader users, and is enabled to trade
documents with the sponsor and, optionally, with other WebTrader partners in the sponsor
community.

20 WebTrader
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.
Manage sponsor and trading relationships

After you add a WebTrader partner, you can change the sponsor community, provided that you
have more than one community. You can also specify with whom a WebTrader partner can trade.
1. From the WebTrader manager menu, select an existing WebTrader partner to open the

summary page for that WebTrader partner.
2. Go to the bottom of the summary page and select the command Manage memberships and
trading restrictions for this partner. Then from the export options screen select Save file
to save the WebTrader partner information to a file.
The Choose communities and a sponsor for this WebTrader is displayed. The page has
three tabs: Communities, Sponsor and Trading restrictions. The Sponsor tab is selected
by default.
3. Use the tabs to change the WebTrader sponsor and trading partner:
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.

20 WebTrader
Manage trading restrictions

When you set up a WebTrader user account, you assign one of the following restrictions to the
account:
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
Allow trading with all members of subscribed communities

A WebTrader with this trading restriction can:
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
Allow trading with sponsor and any sponsor representatives

Note A sponsor representative is a WebTrader that is assigned restriction #3.
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

20 WebTrader
l The recipient list comprises members (community sponsor or sponsor representatives) that are in
their sponsor community
Allow trading with all members of subscribed communities and also

assume the role of sponsor representative
A WebTrader with this trading restriction is a sponsor representative. This WebTrader can:
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
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

20 WebTrader
Use case:
l WT2 is assigned restriction #2: "Allow trading with sponsor and any of that sponsor's
representatives"
Result:
WT2 can trade with:
l SPA
l WT3
Use case:
l WT3 is assigned restriction #3: "Allow trading with all members of subscribed communities and
also assume the role of sponsor representative"

20 WebTrader
Result:
WT3 can trade with:
l WT1 l SPA
l WT2 l P1
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"
Result:
WT2 can trade with:
l WT3
l SPA

20 WebTrader
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"
Result:
WT4 can trade with:
l WT1 l P1
l WT2 l P2
l WT3 l SPA
l WT5 l SPB
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"

20 WebTrader
Result:
WT5 can trade with:
l WT1 l P1
l WT2 l P2
l WT3 l SPA
l WT4 l SPB
Add a WebTrader user to a partner

When you create a WebTrader partner, you specify a single user for the partner. After the initial
creation, you can create additional users that also have permission to log on to the WebTrader user
interface using the same WebTrader partner account.
To add additional users to a WebTrader partner:

2. On the navigation graphic at the top of the summary page click the Users icon.
The WebTrader users screen is displayed. This screen lists the users who are authorized to log
on to WebTrader as representatives of the currently selected partner.
3. Click Add a WebTrader user.
4. In the Add a WebTrader user screen complete the fields:
l User ID – Enter an account name for the user. The WebTrader user uses this ID to log on
to the UI.
l Password – Enter a password for the WebTrader user. The WebTrader user must use this
password to log on to the UI.
This field does not appear if you have implemented single sign on.
l Confirm password – Re-enter the password to confirm.

20 WebTrader
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.
Delete a WebTrader user from a partner

on to WebTrader as representatives of that partner.
3. Locate the user you want to delete in the displayed list of users.
4. On the line that lists the user, in the right column, click Delete.

20 WebTrader
Add WebTrader user roles

Roles are sets of predefined permissions that you can create for WebTrader users. After you create
roles you can apply different roles to different users, or the same role to multiple users.
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.
Add a new role

To create a new role:
1. Select WebTrader manager > Manage WebTrader user roles.

2. In the Roles page, click Add a role.
3. In the Add a role page, complete the fields:
l Role name (mandatory) – Enter a name this role.
l Description – Optionally enter a text description. This description appears in the Roles
screen to remind you of the characteristics of the role.
4. From the list of permissions in the Add a role screen, select the permissions to associate with
this role.
5. Click Add this role.
The new role appears in the list of roles on the Roles page.
Change the role of a WebTrader user


20 WebTrader
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.
Set WebTrader password policy

Use the following procedure to control the password and identification characteristics of your
WebTrader partners. These settings effect all WebTrader partners and users.
1. Select WebTrader manager > Configure WebTrader password policy.

The Change WebTrader password policy settings screen is displayed.
l Minimum user ID length – Default = 2
l Minimum password length – Default = 3
l Minimum change count before password can be reused – Default = 3. Enter the
value 0 to disable.
l Elapsed days before password can be reused – Default = 180. Enter the value 0 to
disable.
l Days password remains valid before it must be reset – Default = 0. Enter the value
0 to disable.
l Elapsed days before disabling an inactive user – Default = 30. Enter the value 0 to
disable.
l Force new users to reset their password upon initial login – Selected by default.
l Passwords must not contain the user ID – Selected by default.
l Passwords must have at least one upper-case and one lower-case letter
l Passwords must have at least one number (0 to 9)
l Passwords must have at least one special character from the set – If you select
this option, complete the following field.
l Special characters allowed – If you activated the previous option, list the set of special
characters that the user can use in a password.
3. If you modified any fields, click Save changes.

20 WebTrader
Additional WebTrader user management

options
As an administrative user, you can manage various characteristics of WebTrader users from the UI.

on to WebTrader as representatives of that partner.
3. Click the name of a user from the list, to view and modify the characteristics of that user.
4. The Change WebTrader user screen is displayed. Use the options in the following tabs to
view and modify the user:
l General tab - Use this tab to modify:
o User full name
o User email
o User phone number
o User descriptive text
o Email notification of document reception (on or off)
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.
Group WebTrader partners by category

You can create categories and use them to group WebTrader partners, just as you can with other
Interchange partner types. Categories are useful to limit search results to specific groups of users
that share common characteristics, such as physicians, technical labs or pharmaceutical companies.
For a review of how to create and manage partner categories, see Group partners by categories on
page 158.

20 WebTrader
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.
Add a WebTrader to a category

1. Select WebTrader manager > Manage WebTraders.
2. From the WebTrader partners screen, click a WebTrader partner in the list to open the
WebTrader summary page for that WebTrader partner.
3. From the WebTrader Summary screen, click the Categories icon on the summary graphic.
4. Select the category you would like to use to classify this WebTrader partner .
After you add a WebTrader partner to a category

When a WebTrader partner belongs to a category, you can use the category filter in the search tool
of the WebTrader users page. This enables you to limit the display of WebTrader partners to those
partners that belong to a specific category.
Enable trading with non-WebTrader

partners
To enable the WebTrader partner to trade with non-WebTrader partners in the community:

2. Go to the bottom of the summary page and select the command Export this partner as a
non-sponsored partner profile. Then from the export options screen select Save file to
save the WebTrader information to a file.
3. Give copies of the exported profile file to non-WebTrader partners in the community who want
to trade with the WebTrader partner. The partners must import the file into their Interchange
systems. The exported file contains contact information and a routing ID for the WebTrader
partner. It also contains the sponsor’s certificate and public key for securely moving documents
between non-WebTrader partners and the sponsor’s community.

20 WebTrader
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.
Use the WebTrader partner search tool

When you have a large number of partners to manage it is useful to use the search tool in the
WebTrader Partners page to find specific partners.
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
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.
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
Activate self-registration for WebTrader

partners
As a WebTrader sponsor you can activate the WebTrader registration wizard. This wizard lets
WebTraders set up their own trading profiles without help from you as sponsor. This provides a way
to get many WebTraders configured to trade messages.

20 WebTrader
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.
1. If you have not done so, on the Getting Started page the user interface, select Set a

password for the WebTrader self-registration user.
A page displays, prompting you to set a password for the user WebTrader registrant.
2. Type a password for the user and click Save changes.
This action adds the WebTrader registrant user and displays the change user page. The user ID
is webtrader and the password is the one you specified.
3. You can manage WebTrader partner details on the WebTrader partners page (WebTrader
manager > Mange WebTrader partners).
4. Communicate the following information to partners who will use the WebTrader registration
wizard:
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
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>.
Manage WebTrader partner and

community attributes templates
As a WebTrader administrator you can create partner and community attributes templates to link
custom metadata to you WebTrader users.

20 WebTrader
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.
Create a partner or community attributes

template
1. From the Interchange tool bar select WebTrader manager > Manage WebTrader
partners.
2. From the Related tasks list at the bottom of the page, click Manage partner and
community attributes template.
3. From the Related tasks list at the bottom of the page, click Add new attribute field.
4. In the Add an attribute field page complete the fields:
l Name – Enter a name for the attribute. This is the name that will be displayed to document
traders.
l Make this a required attribute – Select this option if all WebTrader partners must have
this attribute valued in their configuration.
l Make available for searching – Select this option if you want the WebTrader end user's
search tool to include this attribute name and value as a search filter option.
l Make available for message processing – Select this option if you want document
processing to depend on the detection (or non-detection) of this attribute or attribute
value. For example, you may want to configure a service to run only if a specific partner
attribute/value is detected.
l This property is a list of values – Select this option if you want to create a list of 1-n
values from which the user selects a single value.
l Selection style – Indicate if the user can select from a single value or from a multiple-
value list.
l Possible values – Enter the possible values that you want to appear in the user's selection
list.
5. Click Add.

20 WebTrader
Modify a partner or community attributes

template
After you create either a partner or community attribute, you can change it in the Manage partner
or community attributes template:
1. Select WebTrader manager > Manage WebTrader partners.

2. From the Related tasks list at the bottom of the page, click Manage partner attributes
template.
3. From the list of templates, click the name of the template you want to modify, to open the
Change an attribute field page.
4. Change the displayed fields as required. For field descriptions see the previous procedure.
5. Click Save.
Change attribute display order
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:

2. Click Manage partner and community attributes template.
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.
Fill in required WebTrader partner

attributes
If you have already created WebTrader partners and then you add a partner template with one or
more required attributes, you must update the WebTrader partners order to configure them for the
new required values.
1. In the user interface, select WebTrader manage >Manage WebTrader partners.

Any WebTrader partners that are currently incomplete (missing configuration steps) are marked
with an exclamation mark icon.
2. From the list of WebTrader partners, click the name of an incompletely configured partner to
display the Summary page for that partner.
3. Under the section You must complete the following tasks before this partner is
complete, click Fill in the required attributes.
4. Enter attribute values where required to complete the attributes configuration.

20 WebTrader
Change the attributes template display

order
After you create two or more attributes templates, you can change the display order of the template
attribute list on the Manage partner and community attributes template page. This has the effect of
changing the order of the display of attributes in the partner search and configuration displays.

2. In the related tasks list, click Manage partner and community attributes template.
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.
4. Click Save.
Delete partner or community attributes

template
After you create a partner or community attribute, you can delete it using the following procedure:

2. In the related tasks list, click Manage partner and community attributes template.
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.
Manage WebTrader document attributes

templates
As a WebTrader administrator you can create document attributes templates to link specific
metadata to the documents that your WebTrader users exchange.
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.

20 WebTrader
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.
Create a document attributes template

partners.
2. From the Related tasks list at the bottom of the page, click Manage document attributes
template.
3. From the Related tasks list at the bottom of the page, click Add new attribute field.
4. In the Add an attribute field page complete the fields:
l Name – Enter a name for the document attribute. This is the name that displays in the
WebTrader user interface.
l Make this a required attribute – Select this option if the user must choose or enter a
value each time a document is sent.
l Make available for searching – Select this option if you want the WebTrader end user's

search tool to include an attribute name and value filter.
l Make available for message processing – Select this option if you want document
processing to depend on the detection (or non-detection) of this attribute or attribute
value. For example, you may want to configure a service to run only if a specific
attribute/value is detected.
l This property is a list of values – Select this option if you want to create a list of
possible values from which the user can select.
l Selection style – Indicate if the user can select a single value or multiple values from the
list of possible values.
l Possible values – Enter the possible values that you want to appear in the user's selection
list.
5. Click Add.
Modify a document attributes template

partners.

20 WebTrader
2. From the Related tasks list at the bottom of the page, click Manage document attributes

template.
3. From the list of templates, click the name of the template you want to modify, to open the
Change an attribute field page.
4. Change the displayed fields as required. For field descriptions see the previous procedure.
5. Click Save.
Change document attribute display order

After you create two or more document attributes templates, you can change the display order of
the template attribute list on the Manage document attributes template page. This has the
effect of changing the order of the display of attributes in the WebTrader user interface.

2. In the related tasks list, click Manage document attributes template.
3. On the Manage document attributes template page, select either the up or the down arrow of
any attribute to change its position in the list.
4. Click Save.
Delete a document template

2. In the related tasks list, click Manage document attributes template.
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 template or Cancel if you decide not to delete.
Activate large message handling

By default, a WebTrader sponsor community in Interchange can send or receive documents of up to
50 MB. If your WebTrader users will be sending larger documents you should activate large message
handling on the WebTrader community configuration.
To do this you:
l Provide WebTrader users with licenses in which the webtraderAppletForLargeFiles key is
enabled.

20 WebTrader
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
pickup.
To enable a Secure file trading pickup, see Secure file message protocol on page 971.
Activate large message sending for

WebTrader partners
2. Select Trading configuration menu > Manage trading configuration.
3. From the list of communities, click the community that represents you as a WebTrader sponsor.
4. From the list of tasks, select Add a secure file HTTP or HTTPS partner exchange to use
the WebTrader large file applet, then click Next.
The Choose a message protocol screen is displayed.
5. Select the option Secure file (HTTP, FTP, SFTP. file system, JMS, IBM MQSeries,
WebDav), then click Next.
6. On the Choose transport protocol screen, select HTTP.
7. On the Choose HTTP transport type screen, select an option:
l Use the system's global embedded HTTP server
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.
UI behavior for WebTrader users
Large message trading not enabled

When large message trading is not enabled (Secure file not configured for the sponsor community),
WebTrader partners can send messages of up to 10 MB. Attempts to send larger messages will fail.
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:

20 WebTrader
A configuration error prevents uploading large files. Ask your sponsor

to enable a secure file HTTP of HTTPS exchange for receiving messages
from partners. Try again to upload after the sponsor tells you this has
been done.
When this message is displayed, the WebTrader partner can continue to send documents of less
than 10 MB.
Large message trading enabled

On first connection to the sponsor server via the WebTrader UI, the WebTrader user's browser
displays a Java applet status information message and it downloads the large file handling applet.
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:
\Documents and Settings\<user directory>\.cyclone
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.

20 WebTrader
Reset standard upload limit

The standard limit for file uploads of 50 MB applies generally to all Interchange HTTP uploads. It is
possible to reset this limit. To do this:
1. Go to <install directory>/webapps/ui/WEB-INF/.

2. Open the file web.xml in a text editor.
3. Modify the value of the following lines, resetting the value as required:

<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.
Monitor WebTrader exchanges

Once a WebTrader partner is active, an administrative user can use Message Tracker to monitor
trading between WebTrader partners and other partners.
For details of how to use Message Tracker, see Message Tracker on page 826.
WebTrader end user browser issues

Chrome 42 (released April 2015) and later versions do not allow Java plugins in the way plugins
have been traditionally enabled in browsers. Special configuration is now required. The use of these
browsers may cause particular issues or difficulties for your WebTrader end users.
For more information, refer to the Java website under the topic of "How do I enable Java in my web
browser?"

20 WebTrader
Manage unlimited strength JCE policy

download issues
The client system used by a WebTrader end user is configured with JRE 8. The client machine
automatically downloads unlimited strength JCE policy files from the Interchange server to which it
connects (if the files do not exist already exist on the client machine).
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.
Analyze the issue

In normal use, there is no specific indication to the end user that the policy file download has failed
to copy to the directory. However the standard message that the applet has not loaded yet persists
with the mention to contact the administrator.
To view the progress of the policy down load you can open a Java console.
1. From the Windows Start Menu select Programs>Java>Configure Java to open the Java

Control Panel.
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.
Correct the issue

There are two options for avoiding this 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 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.

20 WebTrader
3. Select Run as Administrator.

4. Open a WebTrader session.
Confirm the resolution

With a Java console, open you should now be able to confirm the success of the policy download.
The end user can proceed with trading activities.

Axway CSOS
21
For licensed users, Interchange supports digital signing and verification of controlled substance
orders in compliance with the Controlled Substance Ordering System of the U.S. Drug Enforcement
Administration (http://www.deaecom.gov/). The documents being handled are purchase orders
that conform to CSOS standards. These can be EDI X12 or XML documents.
Can you use CSOS?

This mortar and pestle icon on the user interface toolbar indicates that your user
license supports CSOS functionality. If this icon is absent, you are not licensed for

CSOS processing. If you have purchased a CSOS license and experience any
display issues, contact Support services on page 23.
Another way to check whether your license supports this functionality is to select
Help > License information.
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.
User validation with PassPort

If your organization uses PassPort, you can use it in conjunction with Axway CSOS to validate CSOS
user(s) credentials.
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

21 Axway CSOS
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
Overview of CSOS functionality

With digital certificates issued by DEA, a user can sign controlled substance orders before
Interchange sends the orders to partners. Orders more than one day in the future from today’s date
are rejected and can be found in Tracker in a Failed state. Orders are signed with the user's private
key corresponding to the user's public-private key pair in the certificate. Once signed, the user’s
certificate, containing the public key only, is transmitted with the order.
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

21 Axway CSOS
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.

21 Axway CSOS
CSOS configuration for sending

Follow this outline to configure Interchange to sign and send CSOS purchase orders. A system
administrator performs the steps, except as noted when a CSOS signing user should perform a task.
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
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.
Click Add this user to create the user.

Repeat this step if you need to add another CSOS signing user.
6. Have the CSOS user you added in step 5 log on to the user interface.
7. Have the CSOS user select Change my user account on the toolbar. Depending on the
permissions for the role assigned to the user, this link is on the User settings menu or the
Users and roles menu.
8. Have the CSOS user select the Personal certificates tab and click Add a certificate to open
the certificate wizard.
The certificate to add is the user’s signing certificate from DEA. A signing certificate is needed to
send signed orders to a partner.
Import the signing certificate to Interchange. See Import CSOS signing certificate on page
1021.
The required DEA-issued intermediate and root certificates are pre-loaded in Interchange. These
are required to complete the chain of trust upon importing the DEA-issued signing certificate
(also known as an end-entity certificate).
9. If not already complete, configure an external SMTP server. (See the Interchange
Installation Guide.) Then, have the CSOS user select the CSOS daily e-mail tab and specify
the following:

21 Axway CSOS
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
l If your license includes Transaction Director features, use Transaction configuration >

Add a document type.
l If your license does not include Transaction Director features, use Message tracker >
Configure payload view.
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.
CSOS configuration for receiving

Follow this outline to configure Interchange to receive signed CSOS purchase orders from partners.
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
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:

21 Axway CSOS
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.
l Select Message tracker > Configure payload view.

l Enter the following values:
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.
About CSOS roles

A system administrator completes CSOS configuration, which includes role and user administration.
After you create a role that includes Approve CSOS orders privileges, you can assign this role to
one or more users who have DEA certificates. These users can view, approve, or reject all orders
containing their individual DEA certificates. They can also add/edit the Notes, Quantity Received,
and Date Received on their processed orders.
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:

21 Axway CSOS
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.

21 Axway CSOS
Use the CSOS applet on your web page

A Java applet is used for signing CSOS documents on the browser user’s machine and uploading to
an Interchange host. Instructions for incorporating the applet on your web page are in the
README.html file in <install directory>\webapps\wtapplet\csos. In the same directory is
a sample file, testCsosApplet.html, that demonstrates the applet. To try out the test page, start
Interchange server and point a browser to the following URL:
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.

download issues
The client system used by a CSOS WebTrader end user is configured with JRE 8. This system
automatically downloads unlimited strength JCE policy files from the Interchange server to which it
connects (if the files do not exist already exist on the client machine).
files exist in the following folder of the CSOS licensed Interchange server:
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.
Analyze the issue


Control Panel.

21 Axway CSOS
4. Click OK.
Correct the issue

l The CSOS/WebTrader end user can start the web browser in administrator mode. To do this:
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

21 Axway CSOS
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.
WebTrader partner requirements

The WebTrader p artner needs a valid DEA-issued certificate with which to sign CSOS purchase
orders. The signature is evidence of the WebTrader p artner’s approval of such orders. The
Interchange sponsor, upon receiving signed orders, verifies the signature against DEA-issued root
certificates. The WebTrader p artner's browser must haveJava Runtime Environment (JRE) 1.6. The
WebTrader p artner also must deploy Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction Policy Files 5.0 or 6.0.
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.
l Internet Explorer – Select Tools > Internet Options to open the Internet Options window.

Select the Advanced tab. Scroll down the list of settings and look for a category named Java
(Sun). Under this might be a setting that is the same or similar to the following line:
Use JRE 1.5.0_05 for <applet> (requires restart)
If present, select the check box for this entry if not already selected. Click OK to close the
window and save your change and restart Internet Explorer.
l Mozilla Firefox – Type about:plugins in the address field and press Enter. Scroll down the
installed plug-ins page and check the version of the latest Java plug-in.
If you need JRE 1.5.0_05 or later, go to the following URL and download and install the JRE:
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.

21 Axway CSOS
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.
Approve CSOS documents in WebTrader

Use this procedure if you are a WebTrader partner and want to check WebTrader for CSOS
documents awaiting signing.
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.

21 Axway CSOS
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.

21 Axway CSOS
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.
Turning on HTTP chunking

The CSOS order signing applet can chunk large messages before sending.
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.
1. Applet parameter – This first option is a server-side change. You can edit the web page

containing the applet to pass a value for httpChunkingAlwaysOn as an applet parameter.
For example:
<applet ...
<param name="httpChunkingAlwaysOn" value="true"/>
</applet>
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.

21 Axway CSOS
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.
Import CSOS signing certificate

Use this procedure to import the DEA-issued signing certificate to Interchange. This certificate is
assigned to a user who uses it to sign CSOS orders before Interchange sends the orders to partners.
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.
1. Select Change my user account on the toolbar. Depending on the permissions for the role

assigned to the user, this link is on the User settings menu or the Users and roles menu.
2. Select the Personal certificates tab and click Add a certificate to open the certificate
wizard.
3. Type the path to the certificate file or click Browse to locate the file.
4. In the Password field under the Certificate file field, type the password the DEA provided.
This is the password that protects the certificate file.
5. In the Certificate password field, type the password you want to use. This password
supersedes the password provided by the DEA. This is the password you use to sign a CSOS
order. Also type the new password in the Confirm password field.
6. In the DEA Number field, enter the DEA number associated with the certificate.

The format for this number is two capital letters followed by seven digits. This information is
used to determine which orders you can view and sign.
7. Click Next. A name for the certificate is displayed. You can use this name or type a different
name.
8. Click Finish to complete importing the certificate.
To verify the certificate has been imported, click the Personal certificates tab and look for
the name of the certificate you just imported.
CSOS certificate revocation lists

DEA maintains certificate revocation lists of CSOS certificates it has issued and revoked for one
reason or another. Revoked certificates are not valid for CSOS order signing. Interchange fails a
CSOS order signed with a revoked user certificate.
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.

21 Axway CSOS
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 .
Identify CSOS purchase orders

Use the Identify CSOS purchase orders page to configure how Axway CSOS identifies and handles
EDI X12 850 documents or XML purchase order documents.
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.
Order identification tab

If you send or receive CSOS orders, you must configure EDI X12 850 documents or XML purchase
order documents as valid CSOS documents.
To configure EDI document identification for CSOS

Note Performing this configuration requires some familiarity with XML Path Language (XPath).
Before you begin, ensure you have a sample 850 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. The wizard cannot verify whether a document
is an 850 or another transaction type, so be sure to use a properly formatted 850.
1. Choose one of the following methods:

21 Axway CSOS
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.
Example for Identity XPath:

/envelope/functionalgroup/transactionset[@code='855']/table/loop
[@code='N1']/segment[@code='N1' and element[@code='98' and value='ST']]
/element[@code='67']/value
Example for DEA Number XPath:
Example for Order Number XPath:
/envelope/functionalgroup/transactionset[@code="855"]/table/segment
[@code="REF"]/element[@code="127"]/value
l To specify that all 850s are handled as CSOS documents, click Accept all EDI 850s as CSOS

purchase orders. For the DEA Number and Order Number fields, 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.
2. Under Document type, select the CSOS 850 you previously added to the central list of

document types.
If this does not appear in the list, follow the instructions in one of the following:
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.
To configure XML document identification for CSOS

Note Performing this configuration requires some familiarity with XML Path Language (XPath).
Before you begin, ensure you have a sample XML 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 select each segment.
1. Click Add an XML 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 XML file.
2. Under Document type, select the CSOS Purchase Order you previously added to the central
list of document types.
If this does not appear in the list, follow the instructions in one of the following:

21 Axway CSOS
3. Click Test and follow the instructions in the wizard to select your sample XML file. Use the test
4. Click Save.
Order sources tab

The Order sources tab enables you to set filtering conditions in addition to those on the Order
identification 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 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:
1. Click Add an order source at the bottom of the page. The page displays an available default

source of any exchange from any party to any party.
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.
Purchase orders picked up from sent from sent to
file system integration Your community Partner A
file system integration Your community Any partner
Trading transport for receiving Partner A Your community

messages from partners
Trading transport for receiving Any partner Your community

messages from partners

21 Axway CSOS
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.
Related documents tab

By default, Interchange is configured to retain documents identified as CSOS orders for two years.
This tab lets you identify documents such as invoices and shipment notices that must be retained
along with the related CSOS orders. One use for this tab is to associate 855 purchase order
acknowledgements. See Link EDI 855 PO Acknowledgement to 850 PO on page 1026 for more
information.
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.
CSOS duplicate orders tab

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 application pickup 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.

21 Axway CSOS
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.
To add a partner-specific exception to the selected behavior, click Add an exception for a

partner. A wizard displays to help you locate and select the partner or partners you want to add.
You can add multiple partners to the exception list at one time using the wizard. Interchange applies
the opposite of the selected behavior to any partners that display in the exception list.
Link EDI 855 PO Acknowledgement to 850

PO
In addition to configuring Axway CSOS to handle 850 purchase orders, you can configure it to
associate each 855 purchase order acknowledgment your system receives back from a supplier with
the original PO. This enables you to see that the order was authenticated and processed
successfully.
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.

21 Axway CSOS
2. On the Related documents tab, click Add an EDI document identifier.

A new configuration row appears.
3. For each field, enter the appropriate XPath segment or c lick the ellipse (...) button to use the
wizard to select the XPath segment from your sample 855 file.
Example for Identity XPath:

Example for DEA Number XPath:
Example for Order Number XPath:
/envelope/functionalgroup/transactionset[@code="855"]/table/segment
[@code="REF"]/element[@code="127"]/value
4. Under Document type, select 855.

If 855 does not appear in the list, see the "Add the following document type(s) to configure the
display of CSOS purchase orders" step of CSOS configuration for sending on page 1011.
5. Click Save.
6. Click Test and follow the instructions in the wizard to select your sample 855 file. Use the test
Once one or more CSOS purchase orders and acknowledgements have traded, you can view the
purchase order(s) to see that the quantity was confirmed.
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.

21 Axway CSOS
Sign pending orders

Use this procedure to digitally sign CSOS orders and release them so Interchange can package and
send them to a partner. This procedure presumes all CSOS configuration steps have been completed
correctly.
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.

21 Axway CSOS
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.

21 Axway CSOS
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.
Configure PKCS#7-encrypted XML trading

Axway CSOS includes a feature to facilitate trading with partners that send orders using a specific
PKCS#7-encrypted XML packaging. Walmart Stores is the only known originator of this packaging
at this time.
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:

21 Axway CSOS
Field Value
Identify XPath /CSOSSignableOrder
DEA Number /CSOSSignableOrder/Header/PurchaserDEANumber
Order Number /CSOSSignableOrder/Header/CSOSOrderID
Document type [Document type you created in Step 2.]
4. For the partner, create a new trading pickup. For more information, see Add a trading pickup on

page 261.
5. Modify the trading pickup as follows:
a. On the Message attributes tab, in the Attribute name field, select csos.pkcs7.
b. In the Value field, enter true.
c. Click Add.
The csos.pkcs7 attribute now appears in the Fixed message attributes list.
Once this configuration is complete, you can begin testing trading with Walmart.

eSubmissions
22
The following topics provide information for using the eSubmissions functionality within
Interchange to send large messages to the U.S. Food and Drug Administration.
Can you use eSubmissions?

A license.xml file that supports eSubmissions is required to use the functionality. The license also
must enable the license key allowCustomMetadataInMessageHeaders. Check Help > License
information.
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.

22 eSubmissions
A key component of eSubmissions is a custom application pickup named Directory file system

consumer. This transport handles only messages outbound to the FDA. In addition, eSubmissions
adds two metadata elements — FdaCenter and FdaSubmissionType — to the AS2 MIME headers of
outbound messages. Values of these elements identify the messages’ intended destinations and
categories.
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.
Getting started with eSubmissions

Use this procedure to apply for an electronic submissions account and gather information to provide
to the FDA about your community.

22 eSubmissions
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.
Add an application pickup

Use this procedure to configure an application pickup needed for eSubmissions. This is a pluggable
transport named Directory file system consumer.
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

22 eSubmissions
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:
<TransportDefinition name="Directory file system consumer"

description="Pluggable transport which consumes directory
messages from the file system." available="true">
<Class>com.cyclonecommerce.custom.fda.
PluggableArchiveSubmissionClient</Class>
<Usages>
<Consume>
<Integration/>
<Consume>
</Usages>
<SettingDefinitions>
<SettingDefinition name="Directory" description="Directory from
which
directories/files will be consumed." type="string" required="true"
encrypt="false" mask="false"/>
</SettingDefinitions>
</TransportDefinition>
3. In the user interface, click Application pickup in the navigation graphic at the top of the

community summary page.
4. Click the Add an application pickup task at the bottom of the page to open the wizard.
5. On the From address page, select one of these options:

protocol address only.
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.

22 eSubmissions
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.
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.
Address parsing rule options:
o If the document is EDI, parse for the address – If an EDI document is picked up,

use the “to” and “from” addresses specified within it. Properly formatted EDI documents
contain this information.
o Perform enhanced EDI parsing to match partner messaging IDs – This

setting applies to X12, EDIFACT, and TRADACOMS. If selected, Interchange
performs additional parsing of the header information to create routing IDs with a
colon separator between values. For example, information from an EDIFACT file
would be parsed in the following format:

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
o If the document is XML, use XPaths to locate the address – If an XML

document is picked up, use the “to” and “from” addresses specified by the XPaths
within it. XML Path Language or XPath is a language for addressing parts of an XML
document.

22 eSubmissions
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.
Add partner-specific collaboration settings

Use this procedure to add partner-specific AS2 collaboration settings for your community and the
FDA. These rules affect how your community sends messages to the FDA.
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.

22 eSubmissions
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 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.
8. For message compression select MIME/GZIP.
9. Select 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.
10. Use the Add new and Add buttons to add the following as selected attributes:
l FdaCenter
l FdaSubmissionType
Complete the FDA partner

Use this procedure to complete the partner for the FDA. You can do this after the FDA approves your
electronic submission account and sends you information including:
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.

22 eSubmissions
e. Select This server requires a user name and password only if the FDA sent a user

name and password to use.
f. Click Next to optionally name the delivery. Otherwise, click Finish.
6. Complete the delivery configuration.
a. On the partner summary page, click Partner delivery on the navigation graphic at the
top of the page. Then click the transport added in step 5 to open its maintenance page.
b. Click the Advanced tab.
c. Make sure each of the following fields has a value of 300 seconds (5 minutes). These
intervals are needed to accommodate the FDA’s busy network.
l Connect timeout
l Read timeout
l Response timeout
d. Select Enable HTTP chunking.
e. Click Save changes.
Import root certificate for SSL

Use this procedure to add a trusted root certificate to your community after the FDA has sent you a
root certificate for SSL.
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.
Send messages to the FDA

Once all configuration has been completed, you can send messages to the FDA by writing files to the
integration pickup directory set up in Step 8 of Add an application pickup on page 1034. You can
send a single file or a directory containing many subdirectories and files.
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.
l If a single file: SenderId-ReceiverId-FDACenter-FDASubmissionType-FileName.extension

l If a directory: SenderId-ReceiverId-FDACenter-FDASubmissionType-DirectoryName
This format applies to the root directory, but not to any subdirectories.
SenderId and ReceiverId are the routing IDs of your community and the FDA partner, respectively.

22 eSubmissions
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.
FDA WebTrader end user browser issues

Chrome 42 (released April 2015) and later versions do not allow Java plugins in the way plugins
have been traditionally enabled in browsers. Special configuration is now required. The use of these
browsers may cause particular issues or difficulties for FDA WebTrader end users.
For more information, refer to the Java website under the topic of "How do I enable Java in my web
browser?"

download issues
The client system used by an eSubmissions WebTrader end user is configured with JRE 8. This
system automatically downloads unlimited strength JCE policy files from the Interchange server to
which it connects (if the files do not exist already exist on the client machine).
files exist in the following folder of the CSOS licensed Interchange server:

22 eSubmissions
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.
Analyze the issue


Control Panel.
4. Click OK.
Correct the issue

l The eSubmissions/WebTrader end user can start the web browser in administrator mode. To do
this:
4. Open a CSOS/WebTrader session.


Interoperability with
other Axway products 23
The follow topics describe how to integrate Interchange with other Axway products and
components.
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.
Integrate with Axway Sentinel

After you install Interchange and Sentinel, you can use the Integrate the trading engine with
Sentinel page to control how Interchange interoperates with Sentinel. From this page, you can
enable and disable the Interchange / Sentinel interface, and control the types of metadata that are
sent to Sentinel for events that are tracked in Interchange.
Open the Integrate the trading engine with

Sentinel page
To open this page:
1. Click Trading configuration on the toolbar to open the Communities page.
2. Click Configure Sentinel integration to open the Integrate the trading engine with Sentinel
page.

23 Interoperability with other Axway products
Organization of the page

The Integrate the trading engine with Sentinel page has three tabs:
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:
1. On the Sentinel tab, select Enable Sentinel interface to display the configuration fields.

2. Complete the fields.
l Primary host – The fully-qualified domain name or IP address of the computer running
Sentinel. If Interchange and Sentinel are running on the same computer, you can use the
short computer name instead of the fully-qualified domain name.
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:
Interchange event level Sentinel event level
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
Custom objects tab

The use of this tab is rarely required.
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.
Related tasks list

At the bottom of the Integrate the trading engine with Sentinel page, two tasks are displayed:
l Add an integration filter – Click this link to open the Add an integration filter page.

l Manage trading configuration – Click this link to return to the Communities page.
About Sentinel filters

Use the Filters tab to set conditions for sending message 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.
Add or modify Sentinel filters

The Filters tab of the Integrate the trading engine with Sentinel page lists available filters. If you
add custom filters, the default filter always is listed last. This is to illustrate that the default filter runs
last, after custom filters. The page also shows the filter expressions for custom filters.

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:
Default filter fields

l Name – The name of the filter. You cannot change the name of the default filter.
l Description – A description of the filter.
l Tracked object name – Unless you have a custom tracked object, select ALL or

XFB Transfer. The default tracked object in use by Interchange is XFB Transfer. If you have a
custom tracked object, selecting ALL engages all TOs, including XFB Transfer.
l Don’t send any events – Select this option to block all events unless overridden by custom
filters. This places the default filter in do-not-send mode and all custom filters in send mode.
l Send all events – Select this option to send all events unless overridden by custom filters. This
places the default filter in send mode and all custom filters in do-not-send mode.
Custom filter fields

l Name – The name of the filter to add or change. After adding it, you can change the name of a
custom filter.
l Description – A description of the filter.
l Tracked object name – Unless you have a custom tracked object, select ALL or
XFB Transfer. The default tracked object in use by Interchange is XFB Transfer. If you have a
custom tracked object, selecting ALL engages all TOs, including XFB Transfer.
l Filter expression – Click the link to add or change a filter expression for tuning the operation
of the filter. A custom filter must have at least one filter expression. For more information, see
Filter expressions on page 1048.

l External class for metadata processing – Enter the java class to be used for processing the

event metadata.
l Enable this integration filter – Select to turn on the filter.
l Disable this integration filter – Select to turn off the filter.
When adding a filter, the filter expression link displays only after you type a filter name and click
Add. The link says Click here to define a filter expression.
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.
A single expression consists of a metadata attribute, an operator (equals or not equals) and a

value.
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.
Integrate with Axway Integrator

Interchange can send messages to and pick up messages from the Axway Integrator message
translator via a JMS queue. This topic describes how to configure Interchange to integrate with
Integrator, but does not include the Integrator tasks for integrating with Interchange. Integrator
users are advised to review the Integrator documentation.
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.
Field Recommended Value
JMS type Listener (integration pickup only)
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.

Message picked up from Integrator
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.
Integrator metadata Interchange changes to
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.

Message sent to Integrator
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.
Interchange changes To Integrator-friendly

metadata
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.
Integrate with Axway Gateway

Use this integration to have a community in Interchange poll and retrieve files from Axway Gateway.
Clear-text files are retrieved via HTTP. Upon receipt, Interchange delivers the files to back-end
integration, just as it does for any message received from a partner.
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.
Axway Gateway configuration

Use this procedure to enable Axway Gateway to integrate with Interchange.
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.
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.
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.
Integrate with Axway PassPort

The following topics describe integrating Interchange with Axway PassPort 4.6:
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.
Functional limitations for PassPort AM

The following function of Interchange is not compatible with PassPort AM:
l Using Axway ePedigree.
Database and installation requirements

You must use a new database for Interchange to integrate with PassPort. You cannot upgrade from
a previous version of Interchange and use the same database as before.

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.
Verify PassPort host name

Make sure the PassPort server host name is correct before starting the Interchange server for the first
time. If incorrect, the server fails to connect to PassPort and the incorrect value is written to
Interchange database and cannot be changed.
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.
About PassPort AM component instances

Review this topic if you plan to integrate Interchange with PassPort AM.
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.
Steps after installation

Use this procedure to complete the initial configuration for integrating Interchange with PassPort.
The steps to perform vary depending on the level of integration selected during the Interchange
installation.
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."

24 Track activities and events
Track activities and

events 24
To track a message or file exchange and monitor status and results, you can use the following
Interchange tools:
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 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.
How Sentinel works

During runtime operations, Interchange sends data to the Sentinel Server each time pre-determined
events occur. Administration users can add to this data by creating maps that generate monitoring
data, and then add the maps to Interchange processing steps.
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.

Interchange Tracked Objects for Sentinel

Sentinel uses Tracked Objects to store the data it receives from tracked applications. Each Tracked
Object defines a specific set of data and receives data for specific types of application events. For
Interchange, Sentinel uses the following Tracked Objects:
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.
HeartBeat Tracked Object
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.
Secure Relay monitoring

The Secure Relay (DMZ) reporting of heartbeat life cycles is independent from Interchange
heartbeat node monitoring. The Secure Relay heartbeat has its own cycleId/timestamp.
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.
Heartbeat attributes
The following table lists the attributes that Heartbeat sends to Sentinel.
Attribute Description Value
CycleId Based on the node startup time. This ID is Example value:

used for the constant heartbeat when the 1406620945548
singleton fails over to another node in the
cluster.
EventDate Current date on the running node. Example value:

2014-06-14
EventId The unique event identification number Example value:

generated by Interchange. 1163521349929
EventTime Current time on the running node, in format Example value: 14:26:51

hh:mm:ss.
GMTDiff The number of minutes between local time Example value:

and GMT. -420
IsAlert Indicates whether the event is in an alert state. 0= no

1= yes

Attribute Description Value
IsEnd Indicates whether the event is completed. 0 = event not end

1 = event completed
IsException Indicates whether the event is in an exception 0= no

state. 1= yes
ObjectId The type of Sentinel Tracked Object that 899942214

generated the data. This is the same ID for all
Sentinel heartbeat reporting.
ProductIPAddr Hostname of the machine on which the node Host of the node

where the cluster singleton that is reporting (Interchange or Secure Relay
the heartbeats is running. node) that is reporting the
status
ProductName Product name of Interchange. Interchange
ProductOS Name of the operating system on the Example value:

computer running Interchange. "Windows XP"
ReturnMessage Node name + reason for an alert or exception Example value: "TE(my_

status. trading_engine) IE(my_
integraton_engine
(unknown))"
State Event state (Alert, Warn Active) reported to l Alert – ISALERT=1,

Sentinel by Interchange. ISEXCEPTION=0
l Warn – ISALERT=0,
ISEXCEPTION=1
l Active – ISALERT=0,
ISEXCEPTION=0
l RETURNMESSAGE – if
anything is specified
about the reason for
isAlert or isException.
ProductId The name of the node where the cluster ID of the node (Interchange

singleton that is reporting the heartbeats is or Secure Relay node) that is
running. reporting the status.
Delay Time in seconds between heartbeat events. Default = 60. This value can

be modified in the
Interchange user interface.
See Integrate with Axway
Sentinel on page 1042.

XFBTransfer Tracked Object

XFBTransfer is a Sentinel Tracked Object that stores and describes events related to file or message
transfers. Interchange generates XFBTransfer data for each step of the transfer p rocess. The
collected data of the entire processing cycle d escribe the transfer of a file or a message between two
endpoints.
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
Identify the steps in the transfer process

For each step of each transfer, the Interchange generates an "event" (tracking data message) that it
sends to Sentinel. The State attribute of the event identifies the relevant step of the transfer process.
The following table lists and describes the typical values of the State attribute for most message
exchanges.
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.
Additional state attributes for embedded FTP/SFTP server events
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:
Sentinel state Details
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.
Additional state attributes for embedded WebTrader server events
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:
Sentinel state Details
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)
Identify the relationship to other events

The sequence of events that describe a single complete Interchange message or file exchange are
referred to as a Processing Cycle. To identify the individual processing events that belong to the
same Processing Cycle, use the CycleId attribute.
Identify the roles of transfer partners

Each endpoint in a transfer has one of two roles:
1. Sender o r Receiver

2. Requester o r Server
The State attribute details table describes these roles. Notice that transfer partners are referred to as
Requesters, Senders, and Receivers.
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.
Attribute Data Type Value
Direction String One of the following:

l E: The Sender g enerated the Tracked Instance.
l R: The Receiver generated the Tracked Instance.
IsServer String One of the following:
l 1: The Sender or, alternatively the Receiver is a
Server.
l 0: The Sender or, alternatively the Receiver is a
Requester.
Example 1: When a transfer occurs between a Sender/Requester and a Receiver/Server, Sentinel
receives the following data for the event.
State Direction IsServer
Created E (Sender) 0 (Requester)

To_Execute E (Sender) 0 (Requester)
Sending E (Sender) 0 (Requester)
Receiving R (Receiver) 1 (Server)
Sent E (Sender) 0 (Requester)
Received R (Receiver) 1 (Server)
Example 2: When a transfer occurs between a Receiver/Requester and a Sender/Server,
Sentinel receives the following data for the event.
Created R (Receiver) 0 (Requester)

To_Execute R (Receiver) 0 (Requester)
Sending E (Sender) 1 (Server)
Receiving R (Receiver) 0 (Requester)
Sent E (Sender) 1 (Server)

Received R (Receiver) 0 (Requester)
Identify Senders and Receivers

Together, the Direction and IsServer attributes identify the role of a transfer partner in the transfer
process. However, they do not explicitly identify partners. To explicitly identify transfer partners, use
the following attributes.
Attribute Data Value

Type
Site String Partner alias that the local partner uses to identify the parameter settings

for the remote partner. When the value of the Direction attribute is:
l R (Receiver), the Receiver is the local partner. The Receiver used
the value of this attribute to identify the parameter settings for the
Sender.
l E (Sender), the Sender is the local partner. The Sender used the
value of this attribute to identify the parameter settings for the
Receiver.
ReceiverId String Network identifier of the Receiver
SenderId String Network identifier of the Sender
RAppl String Network identifier of the Receiver application
SAppl String Network identifier of the Sender application
FinalReceiverId String If the Processing Cycle:
l describes a stored and forwarded transfer, the value of this attribute
is the Network Identifier of the final Receiver of the transfer
l does not describe a stored and forwarded transfer, the value of this
attribute is empty
OriginalSenderId String If the Processing Cycle:
l describes a stored and forwarded transfer, the value of this attribute
is the Network Identifier of the initial Sender of the transfer
l does not describe a stored and forwarded transfer, the value of this
attribute is empty
Identify transfer users

Although Senders and Receivers perform all actions in the transfer process, they do not initiate these
actions. Transfer users initiate transfer actions. Transfer users include both people and software
applications. To monitor d etails about transfer users, use the following attributes.


Type
UserId String Local identifier of the user who owns the transferred file or message

GroupId String Local identifier of the group to which the transfer owner belongs
RequestUserId String Local identifier of the user who requested the transfer. If the user is:
l also the transfer owner, the values of UserId and RequestUserId
match
l not the transfer owner, the values of UserId and RequestUserId do
not match
RequestGroupId String Local identifier of the group to which the requesting user belongs
Trustee String If User Access Control is:
l activated for the transfer, the value of this attribute is the local
identifier of the transfer owner ( UserId )
l not activated for the transfer, the value of this attribute is the
network identifier of the user who requested the transfer
( RequestUserId )
RUser String Local identifier of the user who received the transfer
SUser String Local identifier of the user who sent the transfer
Identify transfers
To identify a transfer, use the following attributes.

Type
IdAppl String If the value of the IsServer attribute is:

l 0, the value of this attribute is the local identifier of the Requester
l 1, the value of this attribute is empty
Application String Local data identifier. If the value of the Monitor attribute is:
l CFT, the value of this attribute is an IDF (Model File Identifier)
l PEL or Gateway, the value of this attribute is an object name


Type
FileName String If the value of the CommandType attribute is:

l Message, this attribute is empty
l File and the value of the Direction attribute is E (Sender), this
attribute identifies the file from which the Sender retrieved the
transfer d ata
l File and the value of the Direction attribute is R (Receiver), this
attribute identifies the file in which the Receiver recorded the
transfer d ata
LocalId String If the value of the Direction attribute is:
l E (Sender), the value of this attribute is the local transfer identifier
for the Sender
l R (Receiver), the value of this attribute is the local transfer
identifier for the Receiver
Senders and Receivers use local transfer identifiers to manage transfers
(cancel, d elete, and so on).
ProtocolFileName String Network transfer identifier. The Sender sent this identifier to the
Receiver.
ProtocolFileLabel String Network transfer name. The Sender sent this name to the Receiver. The
Receiver can use this name to locally name the transfer.
ProtocolId String Network transfer identifier. The Sender generated this identifier. The
Receiver acknowledged this identifier.
ProtocolMessage String If the value of the CommandType attribute is:
(Gateway o nly) l Message, the value of this attribute is the content of the
transferred message
l File, this attribute is empty
PositionNumber Integer Catalog transfer identifier. If the value of the Direction attribute is:
l E (Sender), the value of this attribute identifies the transfer in the
Sender's transfer catalog or transfer mailbox
l R (Receiver), the value of this attribute identifies the transfer in
the Receiver's transfer catalog or transfer mailbox
ProtocolParameter String Network transfer description. The Sender sent this description to the
Receiver.
UserParameter String Local transfer description. When the Requester recorded the transfer in
the transfer catalog o r transfer mailbox, the Requester generated this
description.
The value of this attribute includes two parts:
l the first part contains the first forty characters of the description
l the second part contains the remaining characters of the
description

Identify transfer validity periods

Senders and Receivers can perform specific transfers o nly during the specified validity periods. To
monitor the validity periods for transfers, use the following attributes.
Attribute Data Type Value
EarliestDate Date Date on which the validity period begins

EarliestTime String Time at which the validity period begins
LatestDate Date Date on which the validity period ends
LatestTime String Time at which the validity period ends
Identifying transfer dates and times

During the transfer process, Senders and Receivers record the time and date of certain actions that
they perform. To monitor these details, use the following attributes.
Attribute Date Value

Type
CreationDate Date By default, the system date on which the Sender sent the transfer.

The Sender can set this date. The Receiver can filter transfers based
on this date.
CreationTime String By default, the system time at which the Sender sent the transfer.
The Sender can set this time. The Receiver can filter transfers based
on this time.
SendDate Date If the value of the Direction attribute is:
l E (Sender), the value of this attribute is the date on which the
Sender recorded the transfer in the transfer c atalog or transfer
mailbox.
l R (Receiver), the value of this attribute is the date on which
the Receiver recorded the transfer in the transfer c atalog or
transfer mailbox
The Sender and the Receiver record each transfer o nly once.
SendTime String If the value of the Direction attribute is:
l E (Sender), the value of this attribute is the local time at which
the Sender recorded the transfer in the transfer c atalog or
transfer mailbox.
l R Receiver), the value of this attribute is the local time at
which the Receiver recorded the transfer in the transfer c atalog
or transfer mailbox
The Sender and the Receiver record each transfer o nly once.

Attribute Date Value

Type
AckDate Date Date on which the Receiver acknowledged the transfer. If the

Receiver did not acknowledge the transfer, this attribute is empty.
AckTime String Time at which the Receiver acknowledged the transfer. If the
Receiver did not acknowledge the transfer, this attribute is empty.
StartDate Date If the value of the State attribute is:
l SENT, the value of this attribute is the date on which the
Sender began sending the transfer
l RECEIVED, the value of this attribute is the date on which the
Receiver began receiving the transfer
These dates are expressed in dd.mm.yyyy format.
StartTime String If the value of the State attribute is:
l SENT, the value of this attribute is the local time at which the
Sender began sending the transfer
l RECEIVED, the value of this attribute is the local time at
which the Receiver began receiving the transfer
These times are expressed in hh:mn:ss format.
EndDate Date If the value of the State attribute is:
l SENT, the value of this attribute is the date on which the
Sender stopped sending the transfer
l RECEIVED, the value of this attribute is the date on which the
Receiver stopped receiving the transfer
These dates are expressed in dd.mm.yyyy format.
EndTime String If the value of the State attribute is:
l SENT, the value of this attribute is the local time at which the
Sender stopped sending the transfer
l RECEIVED, the value of this attribute is the local time at
which the Receiver stopped receiving the transfer
These times are expressed in hh:mn:ss format.
TransmissionDuration String If the value of the State attribute is:
l SENT, the value of this attribute is the time that was required
to send the transfer
l RECEIVED, the value of this attribute is the time that was
required to receive the transfer
These times are expressed in seconds.
Identify transfer protocols

Most transfers are associated with three protocol layers:

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

Type
Protocol String Name of the protocol that operates at the Protocol Layer o f the transfer. The

possible values of this attribute are:
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
IsSSL String One of the following:

l 1: SSL/TLS protected the transfer.
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
Identify transfer options

To monitor transfer options, use the following attributes.


Type
Compression String One of the following compression options:

l 0: Undefined
l 1: Horizontal
l 2: Vertical
l 3: Both horizontal and vertical
l 4: Not compressed
EOTProcedure String When the value of the State attribute is:
l SENT, the value of this attribute is the name of the EOT (End of
Transfer Procedure) that the Sender executed
l RECEIVED, the value of this attribute is the name of the EOT (End
of Transfer Procedure) that the Receiver executed
Priority Integer Transfer p riority. Receivers process transfers in the order of their priority.
The range of possible values for this attribute is zero to 255. The lowest
priority is zero. The highest priority is 255.
RetryMaxNumber Integer Maximum number of times that the Sender can attempt to send transfers
RetryNumber Integer Number of times that the Sender attempted to send the transfer. Each
time the Sender established a connection with the Receiver, the Sender
counted one attempt.
RequestType String One of the following:
l S: The Sender sent a single transfer to a single Receiver.
l G: The Sender sent a group o f transfers to a single Receiver. For
each transfer in the group, Axway Managed File Transfer generated
one Processing Cycle.
l D: The Sender sent a single transfer to a group of Receivers
( diffusion). For each Receiver in the group, Axway Managed File
Transfer generated o ne Processing Cycle.
TransferType String One of the following:
l G: The transfer belongs to a group o f transfers that the Sender sent
to a single Receiver. For each transfer in the group, Axway Managed
File Transfer generated one Processing Cycle.
l D: The Receiver belongs to a group of Receivers to whom the
Sender sent the transfer ( diffusion). For each Receiver in the group,
Axway Managed File Transfer generated o ne Processing Cycle.
Identify the size of transfers

To monitor the size of transferred files and messages, use the following attributes.


Type
FileSize Integer Size of the transferred file or message on the Sender's monitor, before

compression. This size is expressed in bytes.
TransmittedBytes Integer Size of the transferred file or message on the Receiver's monitor, after
decompression. This size is expressed in b ytes.
Identify the structure and content of transfers

To monitor the structure and content of transfers, use the following attributes.

Type
CommandType String One of the following:

l Message: The transferred data is a message.
l File: The transferred data is a file.
BlockSize Integer If the value of the CommandType attribute is:
l File and the Receiver's monitor is a main frame, the value of this
attribute identifies where the Receiver stores the transferred data
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.
FileType String If the value of the CommandType attribute is:

l File, the value of this attribute is one of the following:
l fixed: The transferred data contains fixed-length records.
l variable: The transferred data contains variable-length records.
l undefined: The structure of the transferred d ata is unknown.


Type
RecordNumber Integer If the value of the CommandType attribute is:

l File, the value of this attribute is the number of records in the
transferred file
RecordSize Integer If the value of the CommandType attribute is:
l File and the value of the FileType attribute is fixed, the value of
this attribute is the size of all records in the transferred file,
expressed in bytes
l File and the value of the FileType attribute is variable or
undefined, the value of this attribute is the size of the largest
record in the transferred file, expressed in bytes
Transcoding String Character code of the transferred data. The possible values of this
attribute are:
l A: ASCII
l B: Binary
l E: EBCDIC
l T: A transcoding table modified the c haracter code of the transfer.
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.
Metadata for most messages

In the following table, the value column shows an actual or sample value for an element, when
applicable. Sample values are noted as such.
Element Description Value
Application File name. Sample value:

pc1_To_pc3_1002.edi
CommunityPickup The name of the trading ––
pickup that consumed a
message.

CycleId When Interchange reports Sample value:

its XFBTransfer Tracked XR1QTJr3uCYG
Object on page 1065 to 71KWdqJN113R
Sentinel, Sentinel hashes
SSx1sX
the value to produce the
CycleId.
The sample value is an
example of a CycleId as
generated by Sentinel.
Interchange does not
generate the CycleId.
DeliveryExchange The name of the trading ––
delivery used to send the
message.
Direction The direction of the S = Sender

message related to the R= Receiver
event.
Sender (S) is a message
picked up from integration
for sending to a trading
partner.
Receiver (R) is a message
received from a partner and
sent to integration.
DocumentType The type of document Sample value:

(within a document format 810
and version category) that
is being exchanged.
EndDate End date of transaction Sample value:

(when known). 2014-11-14
EndTime End time of transaction Sample value: 14:26:51:268

(when known).
EventDate The date that Interchange Sample value:

generated the event, in 2014-11-14
yyyy-mm-dd format.
EventId The event identification Sample value:

number generated by 1163521349929
Interchange.

EventTime The time Interchange Sample value: 14:26:51

generated the event, in
hh:mm:ss format.
FileName The original name of the Sample value:

file Interchange received pc3_To_pc1_1001.edi
from integration or from a
partner.
FileSize The size of the file in bytes. Sample value:

1636
GmtDiff The number of minutes Sample value:

between local time and -420
GMT.
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.
IsAlert Indicates whether the 0 = not alert

transaction is in an alert 1 = alert, not resolved
state. 2 = alert, resolved
IsEnd Indicates whether the 0 = transaction not end

transaction is completed. 1 = transaction completed
IsException Indicates whether the 0 = not exception

transaction is in an 1 = exception
exception state.
IsServer Indicates whether 0 = not server

Interchange is acting as a 1 = server
server.
IsSsl Indicates when an SSL 0 = not SSL

connection is in use. 1 = SSL
Location Name of the location of Sample value:

Interchange node sending hostname_te
the event.

Machine Name of the computer Sample value:

running Interchange. hostname-t41

Monitor Indicates Interchange is the Sample value:

transaction monitor. INTR = Interchange
MonitorVersion The version and build Sample value:

number of Interchange. 5.10.1.0.11.6825
ProductName Product name of Interchange

Interchange.
ProductOs Name of the operating Sample value:

system on the computer Windows XP
Protocol The transport protocol for Sample value:

the traded messages. HTTP
ProtocolId Name of the EDIINT Sample value:

message protocol. AS2
Rappl URL Interchange uses to Sample value:

send a message to a http://hostname-
partner. t41:4085/exchange/partner
ReceiverId Routing ID of the message Sample value:

receiver. partner
RequestType The type of message S = single transfer

processing request the G = split documents
transaction represents.
RetryMaxNumber Maximum number of times Sample value:

Interchange tries to send a 3
message.
RetryNumber Number of times Sample value:

Interchange tried to send a 1
message.

ReturnCode Message type. 0 = unknown

1 = request
2 = receipt
3 = request and receipt
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.
Sappl URL a partner uses to send Sample value:

a message to Interchange. http://hostname-
t41:4085/exchange/community
SendDate Populated by Interchange Sample value:

when the production date 2014-11-14
is assigned.
SenderId Routing ID of the sending Sample value:

community in Interchange. community
SendTime Populated by Interchange Sample value:

when production time is 10:05:17:977
assigned.
SentinelCycleId The raw unhashed CycleId Sample value:

on page 1078 generated by SUIV1163523917554.1909@tsuliga-
Interchange. t41_te … E
This is the key element for
linking together the various
pieces of a transaction.
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.
Site Sending (outbound) or Community name

receiving (inbound) party
name, based on direction.
StartDate Date that Interchange Sample value:

originated a message, in 2014-11-14
yyyy-mm-dd format.
StartTime Time that Interchange Sample value:

originated a message, in 10:05:17:977
hh:mm:ss:sss format
State Event state reported to Sample value:

Sentinel by Interchange. To_Ack
For a list of states, see
XFBTransfer Tracked Object
on page 1065.
TradeDestination For an outbound message, ––
the routing ID of the
receiving partner.
For an inbound message,
receiving community.
TradeDestinationAlias For an outbound message, ––
the name of the receiving
partner.
the name of the receiving
community.
TradeFormat The message protocol used Sample value:

to send the message. AS2
TradeMessageId The ID Interchange Sample value:

assigned to the message. <1179782810657.1423@a_te>

TradeOriginator For an outbound message, ––
sending community.
sending partner.
TradeOriginatorAlias For an outbound message, ––
the name of the sending
community.
the name of the sending
partner.
TradeSigningAlgo The algorithm used to sign Sample value:

the message. SHA1
TradeState The state of the original Sample value:

message. Delivered
TransmissionDuration Elapsed time of Sample value:

transmission in seconds. 7
UserObjectId Cycle ID with message state Sample value:

added as suffix. SUIV1163523917554.1909@hostname_
te … E.To_Ack
XFBLOG Tracked Object
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 .
Activate the Tracked Object

To activate and use the XFBLOG Tracked Object in the Interchange implementation:

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
ApplicationName Application name Variable string 40
CodeMsg Message code Variable string 10
IdentMsg Message identifier Variable string 10
Monitor Hardcoded value Variable string 10
Product Product name: Interchange Variable string 10
RecDate Recorded date in local log file Date
RecTime Recorded time in local log file Time
SeverityClass Severity class: Variable string 10

ES – System Error
EC – Component Error
EM – Message Error
AV – Error and Warning
IG – General Information
IP – Program Information
SessionTag Session tag Variable string 20
TransferTag Transfer tag Variable string 20

Activity tracking and logs

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 intended for software developers or advanced users.
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 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
User interface home page

The Interchange user interface home page is a configurable dashboard of system-wide activity. It
warns of alerts requiring user attention, reports summary information about trading activities,
reports system status, and lets you perform quick searches of messages.
Click the Home icon on the toolbar to open the home page.
Click Change home page layout at the bottom of the page to change the display of your home

page using drag-and-drop objects representing information categories.
Monitor file system health

You can have Interchange continuously monitor the directories a community uses for file system
delivery exchanges. This is a good way to make sure directories linked to file system integration
pickups and deliveries are working properly.

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.

Alert activity report

The alert activity report can display categories of information regarding processing error, fatal,
rejected and notification events. Select Reports > Alert activity report.
Select Reports > Alert activity report to open a page that lets you generate a report instantly.
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.
External monitoring of server status

A servlet that runs on Interchange can return a default server status message or custom page when a
client performs an HTTP GET. Network routing devices such as load balancers, content switches
and system monitors can hit the servlet periodically. The response indicates Interchange server and
all network components in between are operational.
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:
<File name="serverstatus.html"path="conf/serverstatus.html" />

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.

Create audit files of UI object changes
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.

Logged audit data

For each object type, audit log files collect the following information:
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.
Activate object change auditing

To activate object-change auditing:
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.
Activate logging to XML file

By default, when object change auditing is activated, Interchange logs user change events to
<install_directory>\logs\<machine_name>_cn_audit.csv. To additionally activate
logging to <install_directory>\logs\<machine_name>_cn_audit.csv:

1. Go to <install_directory>/conf.
2. Open audit_config.xml in a text editor.
3. Remove the comment from the line:

4. Save the file.
Tune object change audit outputs

Axway recommends that the default settings only be modified by an administrator or with the aid of
an Axway services resource. Changes made to the audit configuration can have an impact on the
type of objects being logged, and can possibly cause the auditing process to not work properly.
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:


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.
Log file tracking

The system writes many kinds of log files to its logs and other directories. For the most part, these
logs are troubleshooting tools for software developers and not intended for end users. Experienced
users, however, might gain insights into processing activity by examining certain of these files. Log
files contain a complex array of data that takes practice to interpret.
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.
System statistics logs

All logs file appended with stats.log are Java Management Extensions (JMX) monitoring and
statistics logs. There can be many of these files, depending on how many processing nodes are
active.
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.
User interface logs

These logs are created by the user interface. Like system logs, they do not contain information
useful to the typical end user. These logs are written to <install directory>\logs\ui.

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.
HTTP server logs

These logs are written by the embedded HTTP server when a control node or service node is started
with the -Ddebug startup option.
Class path logs

Log files appended with classpath contain information about all JARs in class paths.
Console logs
Log files appended with console contain standard output (stdout) and standard error (stderr)
output streams from embedded third-party software.
Real-time viewing of log files

Use this procedure to use a utility that lets you view activity as the system writes it to any log file.
This procedure explains how to use it in a Windows environment. Usage on UNIX is similar.
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

Set up tail as a Windows option

Use this procedure to set up the tail.exe utility in a way that lets you view real-time logging
activity in Windows when you right-click a log file name and select a tail option.
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.
Troubleshooting with the log4j file

The properties in the log4j.properties file control the level of messages written to Interchange
system log files. By changing levels, you control the volume of messages written to the logs.
Changing levels can be useful in troubleshooting.
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
SFTP client messages

To troubleshoot issues for trading with partners using external SFTP servers, change the levels of all
of the following properties to debug.
l log4j.category.com.cyclonecommerce.collaboration.transport.sftp=info
l log4j.category.com.cyclonecommerce.tradingengine.transport.sftp=info
l log4j.category.com.sshtools=info
SFTP server messages

To troubleshoot issues for trading with partners using embedded SFTP servers, change the levels of
all of the following properties to debug.
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
PeSIT server messages

To troubleshoot issues for trading with partners using embedded PeSIT servers, change the level of
the following property to debug.
l log4j.category.com.cyclonecommerce.tradingengine.transport.pesit=info
OFTP server messages

To troubleshoot issues for trading with partners using embedded OFTP servers, change the level of
the following property to debug.
l log4j.category.com.cyclonecommerce.tradingengine.transport.oftp=info
DMZ nodes messages

To troubleshoot DMZ nodes issues, change the level of the following property to debug.
l log4j.category.com.axway.dmznode=info
SSH nodes messages

To troubleshoot SSH nodes issues, change the level of the following property to debug.

l log4j.category.com.maverick=info
Secure Relay messages

To troubleshoot Secure Relay (XSR) issues, change the level of the following properties to debug.
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
Send log files to technical support

Interchange has an option in the user interface for bundling the application’s log files in one
compressed file and sending the packaged files to technical support. When working with users to
resolve issues, technical support often asks for log files to help in troubleshooting. This option
makes it easy to supply the latest log files.
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.
To send logs to technical support through the user interface, select Help > Send logs.

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
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.
The events.xml file

The events.xml file in <install directory>\conf manages publishing events to log files and
JMS routers. You must understand this file if you want to customize event configurations.
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.
EventRouters section of events.xml

The top portion of the events.xml file is for event routers. The following is an example of the
default EventRouters section of the file.
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"

System events
autoFlush="true" maxFileSize="2M" maxBackupFiles="5"/>

<MetadataProcessorListRef ref="Messaging"/>
<EventFilterRef ref="Important"/>
</EventRouter>
<EventRouter id="Message Detail to Log File"
class="com.cycloneommerce.events2.router.LogFileRouter" active="false">
<Parameters file="../logs%nodeName%_message_detail.log"
rollOnStart="true" autoFlush="true" maxFileSize="2M"
maxBackupFiles="5"/>
<EventFilterRef ref="Message Detail"/>
</EventRouter>
<EventRouter id="Message Summaries to Log File"
class="com.cyclonecommerce.collaboration.events.MessageSummaryLogFileRou
ter" active="false">
<Parameters file="../logs%nodeName%_message_summary.log"
rollOnStart="true" autoFlush="true" maxFileSize="2M"
maxBackupFiles="5"/>
<EventFilterRef ref="Message Summary"/>
</EventRouter>



<l!---->
</EventRouters>
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.

l Parameters element – An EventRouter element can have a Parameters element that defines

parameters specific to the particular event router class. The Parameters element can contain
attributes or sub-elements.
l EventFilterRef element – An EventRouter element can contain an EventFilterRef element that
identifies the event filter to be applied to the event router. Only events that pass through the
filter are passed to the event router. The EventFilterRef element, if present, must contain a ref
attribute with the same value as an id attribute in an EventFilter element. If a EventFilterRef
element is not defined, all events are passed to the event router.
l MetadataProcessorListRef element – An EventRouter element can have a
MetadataProcessorListRef element that identifies what list of metadata event content processors
should be used to determine what metadata processor to use for each event. The ref attribute
must refer to a MetadataProcessorList element.
In the default configuration of events.xml, use MetadataProcessorListRef only when you want to
publish events at the Messaging level. This element is not needed in other event router
configurations.
MetadataProcessors section of events.xml

The MetadataProcesssors section follows the EventRouter section of the events.xml file. The
following is an example of the default MetadataProcessors section.
<MetadataProcessors>

<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.

System events
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.
EventFilters section of events.xml

The EventFilters section follows the MetadataProcessors section of the events.xml file. The
following code is a partial example of the default EventFilters section.
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>


</NotFilter>

System events
A filter that passes all events that do not pass the simple or complex event filter defined
within.
l <AndFilter>

</AndFilter>
A filter that passes all events that pass all the event filters defined within.
l <OrFilter>

</OrFilter>
A filter that passes all events that pass any of the event filters defined within.
Log file event router

The event system comes with a standard event router in events.xml that sends events to log files in
the logs directory ( Log file tracking on page 1092). This outbound event router is implemented by
the following Java class:
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.
<EventRouter id="Unique identifier of router"

class="com.cyclonecommerce.events2.router.LogFileRouter" active="false">
<Parameters
file="fileName"
rollOnStart="boolean"
autoFlush="boolean"
gmt="boolean"
maxFileSize="long"
maxBackupFiles="integer"
maxContentDepth="integer"
rollTimes="hh:mm,hh:mm,hh:mm,…"
/>
<MetadataProcessorListRef ref="Messaging" />
<EventFilterRef ref="Important" />
</EventRouter>
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

System events
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.
JMS event router

With the help of Axway technical consultants, you can configure a router in events.xml to publish
events to a JMS queue. To do so, you must have Java Message Service experience and a working
JMS system.
Instructions for configuring a JMS event router are in the events.xml file.
Oracle AQ event router

With the help of Axway technical consultants, you can configure a router in events.xml to publish
events to an Oracle Advanced Queuing facility (Oracle AQ) queue. To do so, you must have Java
Message Service experience and a working Oracle AQ system.
Instructions for configuring an Oracle AQ event router are in the events.xml file.
XML for JMS and AQ event routers

Each event is serialized in XML form before being written to the JMS or AQ queue. Each event type
can contain different data that is specific to the event type. The following is an example of such XML
content:

<CycloneEvent>
<id>1132766968963.226929@node1</id>
<type>Messaging.Packaging.SignatureCompleted</type>
<level>Low</level>
<created>2005-11-23T12:29:28</created>
<dispatched>2005-11-23T12:29:28</dispatched>
<nodeId>node1_te</nodeId>
<extendedContent/>
<metaData>
<MessageSnapshot>
<CoreId>1132766968539.226918@bdhp6040</CoreId>
<SenderRoutingId>testsender</SenderRoutingId>
<ReceiverRoutingId>testreceiver</ReceiverRoutingId>
<DocumentId>000028161</DocumentId>
<ContentMimeType>application/EDI-X12</ContentMimeType>
<MessageState>Actioned</MessageState>
<MessageContentSize>272</MessageContentSize>
<BusinessProtocolType>RAW</BusinessProtocolType>
<BusinessProtocolVersion>1.0</BusinessProtocolVersion>

<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>
Data common to all events

The following data are common to all events written to the JMS or AQ queue.
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.
Data specific to message-related events

The following data are specific to message-related events written to the JMS or AQ queue.
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.

System events
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.
Persistence event router

Up until version 5.4.2, the router to persist events to the database was active in the events.xml
file. Effective with version 5.4.2, the event persistence router is inactive by default. A change in the
way the system reports events makes it possible to no longer have to store events in the database,
freeing database space and reducing data traffic.
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.



</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.

System events
6. Uncomment the second block of commented-out elements for the default “to” and “from”
addresses. Configuring this is required.
l For Parameter name="FromEmailAddress" value, enter a default “from” address for

events.
l For Parameter name="AlertEmailAddresses" value, enter one or more “to” email
addresses. These are where the events are delivered. To enter two or more addresses,
separate each address with a comma. For example, name1@domain.com,
name2@domain.com.
7. Optionally, uncomment the first block of commented-out elements for a community-specific
“from” address and one or more “to addresses.
Use a community routing ID as the value of Community id.
l For Parameter name="AlertEmailAddresses" value, enter one or more “to” email

addresses. These are where the events are delivered. To enter two or more addresses,
separate each address with a comma. For example,
name1@domain.com,name2@domain.com.
Interchange uses the address of the secure email delivery exchange for the community as the
“from” address. If such an address is not available, Interchange uses the contact email in the
community as the “from” address.
8. Save and close alerts.xml.
9. Restart Interchange server.
When an event defined in alerts.xml is triggered, email messages about the event are
delivered to the specified “to” addresses.
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 for email events

The following metadata are available to all events in alerts.xml.
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.

System events
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.

System events
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.
Event Lvl Description
ActionTreeExecuted Low Action tree executed
Collaboration.ErrorBuildingCollaboration Error Error building a binary

collaboration
Collaboration.ErrorExecutingActionTree Error Error executing a binary

collaboration
DecompressionFailure Error Message could not be

decompressed
DecryptionFailure Error Message could not be decrypted
Duplicate Warn Received a duplicate message
Duplicate.Message Warn Received a duplicate message
Duplicate.Payload Error Received a duplicate document
InlineProcessing.Error Error Inline processing was performed

on a message that resulted in an
exception being thrown

InlineProcessing.Initiated Low This event generates before an

inline process is called by a
message processing action or a
delivery exchange
InlineProcessing.Performed Low Inline processing was applied to

a message and returned
successfully
InvalidCertificate Error No valid certificate
InvalidCertificate.InvalidEncryptionCertificate Error No valid encryption certificate
InvalidCertificate.InvalidSigningCertificate Error No valid signing certificate
InvalidPartner Error Partner ID invalid or unknown
InvalidPayload Error Payload cannot be recognized
InvalidPayload.XmlParsingFailure Error Error parsing XML payload
InvalidResponseRequest Error Message contains an invalid

receipt request
InvalidResponseRequest.UnsupportedFormat Error Requested protocol format is not

supported
InvalidResponseRequest.UnsupportedMicAlgorithms Error Requested MIC algorithms are

not supported
InvalidSignature Error Signature cannot be verified or

validated
InvalidSignature.InvalidHash Error Signature has invalid hash value
InvalidSignature.UnassociatedCertificate Error Signature certificate is not

associated with the message
sender
InvalidSignature.UntrustedCertificate Error Signature certificate is untrusted
MessageIgnored High

System events
MessageJoined High For messages with multiple

payloads (typically ebXML and
RosettaNet), child messages of
the original have been joined
into the single message sent
MessagePackaged Low Message packaged
MessagePackaged.Error Error An error was encountered while

packaging a message
MessagePackaged.Request Low A request was packaged
MessagePackaged.Response Low A receipt was packaged
MessageReceived High Message received from transport
MessageRejected Error Message rejected
MessageSent High Message sent via transport
MessageUnpackaged Low Message unpackaged
MessageUnpackaged.Error Error An error was encountered while

unpackaging a message
MessageUnpackaged.Request Low A document was unpackaged
MessageUnpackaged.Response Low A receipt was unpackaged
PayloadDelivered High Payload delivered to integration

point
PayloadReceived High Payload received from

integration point
PayloadSplit High A batch EDI document has been

split into individual documents
PayloadSplit.Error Error An unrecoverable error occurred

when splitting an EDI document.
No children were produced and
the original document failed.
RequiredHeaderNotFound Error Message did not contain the

required header

ResendCancelled Low Resend cancelled
ResendInitiated High Resend initiated
ResendsExhausted Error Message resent maximum times
ResponseDelivered High An inbound receipt has been

reconciled with the outbound
message that requested it, or an
outbound receipt has been
successfully transmitted to the
requesting party.
ResponseSent High Receipt sent via transport
Resubmit High Message resubmitted
Resubmit.Failed Error Message failed to resubmit
Resubmit.Initiated High Message resubmission initiated
UnexpectedProcessingError Error Cannot process a received

message due to an unexpected
error
UnexpectedResponse Error Receipt message is unexpected

or contain
UnexpectedResponse.AuthenticationFailed Error Receipt indicates authentication

of original message failed
UnexpectedResponse.DecompressionFailed Error Receipt indicates decompression

UnexpectedResponse.DecryptionFailed Error Receipt indicates decryption of

original message failed
UnexpectedResponse.DuplicateRequest Warn Receipt indicates the original

message was a duplicate
UnexpectedResponse.DuplicateResponse Warn Received a duplicate receipt
UnexpectedResponse.InsufficientMessageSecurity Error Receipt indicates original

message had insufficient security
UnexpectedResponse.IntegrityCheckFailed Error Receipt indicates integrity check


System events
UnexpectedResponse.MicMismatch Error MIC in receipt does not match

MIC in original message
UnexpectedResponse.NoPartner Error Receipt indicates there was no

partner configured for the
original message
UnexpectedResponse.SenderEqualsReceiver Error Receipt indicates the sender and

receiver of the original message
were identical
UnexpectedResponse.UnexpectedProcessingError Error Receipt indicates there was an

unexpected error processing the
original message
UnexpectedResponse.UnknownError Error Received a receipt with an

unknown error
UnexpectedResponse.UnknownFailure Error Received a receipt with an

unknown failure
UnexpectedResponse.UnknownWarning Warn Received a receipt with an

unknown warning
UnexpectedResponse.UnmatchedResponse Error Receipt does not match original

message
UnexpectedResponse.UnsupportedFormat Error Receipt indicates the original

message requested a receipt
using an unsupported protocol
format
UnexpectedResponse.UnsupportedMicAlgorithms Error Receipt indicates the original

message requested a receipt with
an unsupported MIC algorithm
UnknownReceiver Error Received message from unknown

receiver
UnknownSender Error Received message from unknown

sender
ValidationFailure Error An error validating an ebXML

message. For instance, a
message could not be validated
against a CPA.

ValidationFailure.NotEncrypted Error An inbound message failed

because it was not encrypted
ValidationFailure.NotSigned Error An inbound message failed

because it was not signed
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.
ConnectionClosed Low Input or output connected closed
ConnectionEstablished Low Outbound or inbound connection established
ConnectionInitiated Low Outbound or inbound connection initiated
InputTransferCompleted Low Input transfer has completed
InputTransferInitiated Low Input transfer initiated on new connection
OutputTransferCompleted Low Output transfer completed
OutputTransferInitiated Low Output transfer initiated
PostProcessing Low Post processing
PostProcessing.Completed High Post processing completed
PostProcessing.Failure Error Post processing failed
PostProcessing.Initiated High Post processing started
ReceiveFailure Error A receive (input) fails for any reason
ReceiveFailure.InputConnectionFailure Error Input connection cannot be set up
ReceiveFailure.InputConnectionLost Error Input connection lost
ReceiveFailure.InputTermination Error Input abnormally terminated

System events
RetryCompleted Low Retry finished
RetryFailure Error A retry fails for any reason
RetryFailure.RetriesExhausted Error All retries have been attempted
RetryFailure.RetryCancelled Error Retry operation cancelled
RetryScheduled Low A message that failed to send due to a transport

error has been scheduled for another attempt
at sending
SendFailure Error A send (output) fails for any reason
SendFailure.OutputConnectionFailure Error A connection cannot be established
SendFailure.OutputConnectionLost Error Established connection lost
SendFailure.OutputTermination Error Output abnormally terminated
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.
CertificateValidationFailure Error Certificate validation failed
CompressionCompleted Low Compression completed
CompressionInitiated Low Compression started
DecompressionCompleted Low Decompression completed
DecompressionFailure Error Decompression failed
DecompressionInitiated Low Decompression started
DecryptionCompleted Low Decryption completed
DecryptionFailure Error Decryption failed

DecryptionInitiated Low Decryption started
EncryptionCompleted Low Encryption completed
EncryptionInitiated Low Encryption started
PackageCompleted Low Packaging completed
PackageInitiated Low Packaging started
PayloadUnpackaged Low A payload has been unpackaged
SignatureCompleted Low A signing operation has completed
SignatureInitiated Low A signing operation has started
SignatureVerificationCompleted Low A signature verification and validation has completed
SignatureVerificationFailure Error Signature verification failed
SignatureVerificationInitiated Low A signature verification and validation has started
UnpackageCompleted Low Unpackaging completed
UnpackageInitiated Low Unpackaging started
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.
NotPeer Error Either the sender or receiver of a peer message is not a peer.
ReceiveFailed Error An error occurred while processing a peer message from another peer.
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.

System events
Administration.Alert High An alert generated
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.
CertificateManagement.CertificateMetadataModified High The metadata on a

certificate has been created,
update or deleted.
CertificateManagement.PersonalCertificateAboutToExpire High A certificate is about to pass

its expiration date
CertificateManagement.PersonalCertificateAdded High A certificate has been added
CertificateManagement.PersonalCertificateExpired High A certificate has expired
CertificateManagement.PersonalCertificateNotOperational High A certificate is not in active

status
CertificateManagement.PersonalCertificateNotYetValid High A certificate precedes its

validation date
CertificateManagement.PersonalCertificateRemoved High A certificate has been

removed
CertificateManagement.PersonalCertificateRevoked High A certificate is no longer

valid
CertificateManagement.PsePolicyUpdated High A default signing or

encryption certificate has
been changed
CertificateManagement.SslCertificateAboutToExpire High An SSL certificate is about to

pass its expiration date

CertificateManagement.SslCertificateExpired High An SSL certificate has

expired
CertificateManagement.SslCertificateNotOperational High An SSL certificate is not in

active status
CertificateManagement.SslCertificateNotYetValid High An SSL certificate precedes

its validation date
CertificateManagement.SslCertificateRevoked High An SSL certificate is no

longer valid
CertificateManagement.TrustedCertificateAboutToExpire High A trusted certificate is about

to pass its expiration date
CertificateManagement.TrustedCertificateAdded High A certificate has been

trusted
CertificateManagement.TrustedCertificateExpired High A trusted certificate has

expired
CertificateManagement.TrustedCertificateNotOperational High A trusted certificate is not in

active status
CertificateManagement.TrustedCertificateNotYetValid High A trusted certificate

precedes its validation date
CertificateManagement.TrustedCertificateRemoved High A certificate has been

untrusted
CertificateManagement.TrustedCertificateRevoked High A trusted certificate is no

longer valid
CertificateManagement.UserCertificateAboutToExpire High A user’s certificate is about

to expire
CertificateManagement.UserCertificateExpired High A user’s certificate has

expired
CertificateManagement.UserCertificateNotOperational High A user’s certificate is not in

active status
CertificateManagement.UserCertificateNotYetValid High A user’s certificate precedes

its validation date
CertificateManagement.UserCertificateRevoked High A user’s certificate is no

longer valid

System events
Collaboration.AllBuildingBlocksRemoved High A message handler

condition has been removed
Collaboration.BuildingBlockAdded High A message handler

condition has been added
Collaboration.BuildingBlockRemoved High A message handler

condition has been removed
CpaManagement.CpaExpired High A community has a CPA that

expire in two weeks or less.
CrlManagement.UpdateCompleted High An update of a certificate

revocation list has been
completed
CrlManagement.UpdateFailed Error An update of a certificate

revocation list has failed
CrlManagement.UpdateInitiated Low An update has been initiated

for a certificate revocation
list
DMZNode.Add High A DMZ (Secure Relay) node

has been added.
DMZNode.Delete High A DMZ (Secure Relay) node

has been deleted.
EmbeddedServer.Added High An embedded server has

been added
EmbeddedServer.Removed High An embedded server has

been deleted
EmbeddedServer.Updated High An embedded server has

been updated
ExchangePoint.Added High An exchange point has been

added
ExchangePoint.Removed High An exchange point has been

deleted
ExchangePoint.Updated High An exchange point has been

updated

Node.Added High A node has been added
Node.Removed High A node has been deleted
Party.CommunityAdded High A community has been

added
Party.CommunityImported High A community profile has

been imported
Party.CommunityRemoved High A community has been

deleted
Party.CommunityUpdated High A community has been

updated
Party.ImportFailed Error A community or partner

profile failed to import
Party.PartnerAdded High A partner has been added
Party.PartnerImported High A partner profile has been

imported
Party.PartnerRemoved High A partner has been deleted
Party.PartnerUpdated High A partner has been updated
Trust-server Status Lists (TSLs)

The following are events related to TSLs.
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
TslManagement.Update Low A TSL update was aborted because a newer TSL is not

Aborted available.
TslManagement.Update High A TSL update completed successfully.

Completed

System events
TslManagement.Update Error A TSL update ended in failure because of an unexpected error.

Failed
TslManagement.Update Low A TSL update was initiated.

Initiated
DMZ
The following events are related to messages processed via Secure Relay.
DMZNode.Connection High Master agent connects to router agent.
DMZNode.Disconnection High Connection drops between master agent and router agent.
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.

CSOS.Messaging.Approval Low A user has signed and approved an outbound

message
CSOS.Messaging.Approval.Rejected High A message awaiting signing was rejected
CSOS.Messaging.QueuedForApproval Low A document is waiting for user signing
CSOS.Messaging.Verification Low This event has been deprecated.

The user signature of an inbound message has
been verified
CSOS.Messaging.Verification 2 Low The user signature of an inbound message has

been verified
CSOS.Messaging.Verification.Failed Error The user signature of an inbound message has

failed verification
Certificate exchange messages

The following certificate exchange events related to messages for exchanging replacement
certificates between trading partners.
CertExchange.CertificateInstall.Failure Error Installation of community certificate through

CEM or SCX failed
CertExchange.Certificate Low Installation of community certificate through

Install.Success CEM or SCX succeeded
CertExchange.Message.Failed Error Processing of received EDIINT CEM or OFTP2

SCX message failed
CertExchange.Message.Invalid Error Received EDIINT CEM or OFTP2 SCX message

was invalid
CertExchange.Request. Low Received EDIINT CEM or OFTP2 SCX trust

Accepted request was accepted
CertExchange.Request. Error Failed to accept received EDIINT CEM or OFTP2

Accepted.Failed SCX trust request
CertExchange.Request.Failed Error Processing of EDIINT CEM or OFTP2 SCX

request failed

System events
CertExchange.Request.Invalid Error Received EDIINT CEM or OFTP2 SCX request

was invalid
CertExchange.Request. Low EDIINT CEM or OFTP2 SCX request was

Received received
CertExchange.Request.Rejected High Received EDIINT CEM or OFTP2 SCX trust

request was rejected
CertExchange.Request.Rejected.Failed Error Failed to reject received EDIINT CEM or OFTP2

SCX trust request
CertExchange.Request.Sent Low EDIINT CEM or OFTP2 SCX request was sent
CertExchange.Response.Accepted Low Received EDIINT CEM or OFTP2 SCX trust

response accepted previously sent trust request
CertExchange.Response.Failed Error Processing of received EDIINT CEM or OFTP2

SCX trust response failed
CertExchange.Response. Low Received EDIINT CEM or OFTP2 SCX trust

Ignored response was ignored
CertExchange.Response. Low EDIINT CEM or OFTP2 SCX response was

Received received
CertExchange.Response. High Received EDIINT CEM or OFTP2 SCX trust

Rejected response rejected previously sent trust request
CertExchange.Response.Sent Low EDIINT CEM or OFTP2 SCX response was sent
WebTrader.Document.Downloaded Low A WebTrader p artner has clicked a

document link to download it to his local
hard drive.
WebTrader.Document.Downloaded.Viewed Low A WebTrader p artner has clicked a

document link to view a document in the
browser.
WebTrader.Document.Purged Low A WebTrader p artner has deleted a

document from the trash.
WebTrader.Document.Removed Low A WebTrader p artner has moved a

document to the trash.

WebTrader_Document_Delivered Low A message has arrived in the WebTrader

partner’s inbox.
WebTrader_Document_Supplied Low A WebTrader p artner has submitted a

document.
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.

System events
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.
ClusterBus.ErrorEvent Error A node communication error has occurred
ClusterBus.FatalEvent Error A node communication fatal error has occurred
ClusterBus.WarningEvent Warn A node communication warning has occurred
Node.ShutdownCompleted High Node has shut down
Node.ShutdownInitiated High Node begins to shut down
Node.StartupCompleted High Node has started
Node.StartupFailure Error Node fails to start
Node.StartupInitiated High Node begins to start up
StartupCompleted High Server has started
StartupInitiated High Server begins to start up
SystemLoadExceeded Warn The system has exceeded the processing threshold and

has throttled back
Administration licensing
The following table shows the administration licensing event.

Administration.Licensing.ResourceUnlicensed Warn License.XML file does not allow access

to a resource
Administration persistence
The following table shows the administration persistence event.
Administration.Persistence.MessagesPurged High Messages have been purged from the

backup directory and the database
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.
Authentication.AuthenticationFailure High A user cannot be authenticated
Authentication.AuthenticationSuccess High A user has been authenticated
Authentication.LockedOutUserAttempt High A user retries logging on
Authentication.UserLoggedOut High A user has logged out
Authentication.MaxAttemptsExceeded High A user has exhausted the number of allowed

log-on attempts
Authorization.AuthorizationDenied High A user has been denied use of a resource
Authorization.AuthorizationGranted Low A user has been authorized to use a resource
Configuration.Failure Error Error due to missing or corrupted data in the

database or a missing license.xml file
Configuration.ItemChanged High A security configuration has been changed
Configuration.PasswordCreationFailure Error A password could not be encrypted

System events
Group.GroupAdded High A role has been added
Group.GroupRemoved High A role has been deleted
Group.GroupUpdated High A role has been updated
Group.UserAddedToGroup High A user has been added to a role
Group.UserRemovedFromGroup High User removed from a role
User.LockedOut High A user’s authority to log on has been

suspended
User.LockOutRemoved High A user can log on again
User.PasswordUpdated High A user’s password has been changed
User.UserAdded High A user has been added
User.UserRemoved High A user has been deleted
User.UserUpdated High A user has been updated

Troubleshooting
25
The chapter Track activities and events on page 1060 can be useful for troubleshooting problems in
Interchange. Additional troubleshooting topics in this document are listed below.
Troubleshoot online help

If you experience display problems while using the online help, clearing the browser's cache is
recommended. Display issues may include the wrong page or no page displays for context-sensitive
help or the table of contents links do not match pages.
Use the log4j file for troubleshooting

By changing the level of messages written to the Interchange system log files, you can control the
amount of messages written to the logs. Changing the levels can be helpful in troubleshooting
problems. See Troubleshooting with the log4j file on page 1095.
Troubleshoot test trading

Test trading is used for testing the Interchange configuration before using it in a production
environment. For troubleshooting during test trading, see Troubleshoot email testing on page 888.
Troubleshoot protocols and standards

Troubleshooting information is available in this document for the following protocols and
standards.
ebXML
See ebXML troubleshooting on page 579.
HTTP
See HTTP connection troubleshooting on page 589.

25 Troubleshooting
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.
Troubleshoot unexpected Interchange

restarts
Unexpected Interchange restarts

Unexpected Interchange restarts may be due to:
l Operating system issues
l Product issues
l Configuration issues
Analyze restart problems
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.

25 Troubleshooting
Activate Interchange debug

1. Go to <install directory>\conf\.
2. Open log4j.properties in a text editor.
3. Add the following lines:
l log4j.category. b2bx.pluggabletransport=debug
l log4j.category.
b2bx.pluggabletransport.IntegratorPluggableServer=debug
l log4j.category.
b2bx.pluggabletransport.PluggableIntegratorClient=debug
4. Save the file.
To view Interchange debug logs, go to <install director>\logs and open the file <machine
name>_cn_console.log.
Generate and analyze dump files

Memory dump files record useful information that may help identify why a server has stopped
unexpectedly.
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

25 Troubleshooting
Slow and problematic cluster startups with NFS

If an Interchange cluster takes more time than expected to start correctly or restarts several times
before successfully starting, and uses an NFS shared file system, this can be due to various causes
on the client and the server side.
Thread limitation on NFS server

Increase the number of kernel threads ("processes") that the nfsd daemon can use on the NFS share
machine ("the server" in this context). The nfsd daemon runs on the server and handles client
requests for file system operations. Each daemon handles one request at a time. Assign the
maximum number of threads based on the load you expect the server to handle.
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.
Caching behavior of Interchange nodes

Node startup problems may be due to caching behavior. It may be useful to disable the NFS cache.
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

25 Troubleshooting
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):
# Only root can start the service
[ $uid -ne 0 ] && exit 4
# Hotfix for the read-leases problem
echo 0 > /proc/sys/fs/leases-enable

Glossary
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
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.
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.

Glossary
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.

Glossary
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

Glossary
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
Changing search default settings.
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.
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.

Glossary
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.
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

Glossary
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.

The trusted roots certificates tab displays the roots of partners’ certificates that a community
trusts. In the case of a self-signed certificate, the trust is for the certificate itself, as a self-signed
certificate is a root certificate. In the case of a certificate authority certificate, the trust is for the
root certificate in the chain of trust of a partner’s certificate. The system by default trusts root
certificates when end-entity partner certificates are imported.
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.

Interchange 5.12.0 AdministratorsGuide AllOS en

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Interchange 5.12.0 AdministratorsGuide AllOS en

Caricato da

Copyright:

Formati disponibili

What's new in Interchange 5.12 28

Interchange 5.12 Administrator Guide 3

3 Network and server administration 52

Interchange 5.12 Administrator Guide 4

5 Tools and options 93

6 User interface 110

Interchange 5.12 Administrator Guide 5

7 Interchange user administration 114

8 Trading configuration 132

Interchange 5.12 Administrator Guide 6

Interchange 5.12 Administrator Guide 7

9 Embedded transport servers 431

Interchange 5.12 Administrator Guide 8

Interchange 5.12 Administrator Guide 9

10 Secure Relay DMZ nodes 474

11 Work with protocols, formats, and standards 494

Interchange 5.12 Administrator Guide 10

Interchange 5.12 Administrator Guide 11

Interchange 5.12 Administrator Guide 12

Interchange 5.12 Administrator Guide 13

12 Certificates and keys 767

Interchange 5.12 Administrator Guide 14

13 Message Tracker 826

Interchange 5.12 Administrator Guide 15

14 Data storage, backups, and purging 849

15 FTP client scripting interface 866

Interchange 5.12 Administrator Guide 16

16 Test trading 885

17 Extend and tune your flow configuration 889

Interchange 5.12 Administrator Guide 17

18 Staged HTTP 958

Interchange 5.12 Administrator Guide 18

19 Secure file message protocol 971

Interchange 5.12 Administrator Guide 19

21 Axway CSOS 1008

Interchange 5.12 Administrator Guide 20

23 Interoperability with other Axway products 1042

24 Track activities and events 1060

Interchange 5.12 Administrator Guide 21

Interchange 5.12 Administrator Guide 22

Who should read this guide

Interchange 5.12 Administrator Guide 23

About this guide

Network and server administration — Describes processing nodes and configuration

Tools and options — Describes the tools available for use with Interchange. See Tools and options

Interchange user interface — Describes the various component of the UI. See User interface on

Interchange user administration — Describes how to manage users, passwords, roles, and

Embedded transport servers — Describes the embedded servers provided for use with

Secure Relay DMZ nodes — Describes Secure Relay and DMZ nodes and zones. See Secure Relay

Work with specific protocols and standards — Describes several of the different protocols and

Certificates and keys — Describes how Interchange offers true security by providing

Backup and restore — Explains and lists the steps for data storage, backing up the data, and

Interchange 5.12 Administrator Guide 24

Extend and tune a flow configuration — Describes how to use the features of the Interchange

Integration with Sentinel, Integrator, Gateway, and PassPort — Learn about the

Activity and event tracking — Describes the activity reports and system events. See Track

Interchange 5.12 Administrator Guide 25

Accessibility features of Interchange

Interchange 5.12 Administrator Guide 26

Screen reader support

Accessibility features of the

Screen reader support

Interchange 5.12 Administrator Guide 27