Transcript
TIBCO BusinessConnect™ cXML Protocol User’s Guide Software Release 6.0 July 2013
Two-Second Advantage®
Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIBCO, Two-Second Advantage, TIBCO ActiveMatrix BusinessWorks, TIBCO Administrator, TIBCO BusinessConnect, TIBCO Designer, TIBCO Enterprise Message Service, TIBCO Hawk, TIBCO IntegrationManager, TIBCO Rendezvous, and TIBCO Runtime Agent are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation in the U.S. and other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM. THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. Copyright © 2012-2013 TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information
| iii
Contents
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x TIBCO BusinessConnect cXML Protocol Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x Third-Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv How to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 The cXML Protocol and TIBCO BusinessConnect cXML Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 The cXML Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 TIBCO BusinessConnect cXML Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Features of TIBCO BusinessConnect cXML Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 New Features in This Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Supported cXML Versions and Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Chapter 2 TIBCO BusinessConnect cXML Protocol Process Flows and Functionality . . . . . . .7 The cXML Operations and TIBCO BusinessConnect cXML Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 cXML Operation Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Synchronous Request-Response Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 One-way Notify Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Process Flow for Outbound and Inbound Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Processing Outbound Request and Notify Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Processing Inbound Request and Notify Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Delayed Response to OrderRequest Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 TIBCO BusinessConnect cXML Protocol and PunchOut. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 PunchOutSetupRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 PunchOutOrderMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Configurable Reply to PunchOutOrderMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 TIBCO BusinessConnect cXML Protocol and Marketplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
TIBCO BusinessConnect cXML Protocol User’s Guide
iv
| Contents Document Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Shared Secrets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Digital Signatures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Multiple Credentials. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Validating Credentials in Inbound Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Controlling Credentials in Outbound Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Chapter 3 Preparing to Use TIBCO BusinessConnect cXML Protocol . . . . . . . . . . . . . . . . . . . 23 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Exchanging Information with Your Trading Partner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Configuring TIBCO BusinessConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Managing cXML Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Importing cXML Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding cXML Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exporting Versions and Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27 27 27 31
Setting Up Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Configuring HTTP, HTTPS, and HTTPSCA Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Configuring Message Attachment Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Configuring Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Chapter 4 Setting Up Trading Hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Setting Up Trading Hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Setting Up cXML Protocol for Trading Hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Adding Domain Identities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Chapter 5 Setting Up Trading Partners. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Setting Up Trading Partners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Setting Up cXML Protocol for Trading Partners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Adding Domain Identities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Configuring Transports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Chapter 6 Configuring Business Agreements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Configuring Business Agreements with cXML Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Operational Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Document Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Transports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
52 52 53 53
Overriding Participant Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Chapter 7 Private Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Configuring Private Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
TIBCO BusinessConnect cXML Protocol User’s Guide
Contents v
|
Standalone Private Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 TIBCO ActiveMatrix BusinessWorks Processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Setting Credentials from Private Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Private Process Message Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Outbound Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Inbound Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Outbound Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Inbound Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Error Message Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Complex Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Request and Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Configuring Private Processes with TIBCO ActiveMatrix BusinessWorks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Configuring BCServerConfig Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Configuring Send and Receive Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Using TIBCO BusinessConnect cXML Protocol with Marketplaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Using BusinessConnect as cXML Marketplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Receiving Messages from BusinessConnect Marketplace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Chapter 8 Viewing Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Viewing Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Audit Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Summary View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Transaction Details View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 State Details View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Non-Repudiation Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Resend Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 State Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Chapter 9 Tutorial — Standalone Private Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Participant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Setting Up Buyer on Machine 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Setting Up Seller on Machine 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Running the Tutorial Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Configuring Buyer’s Private Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Configuring Seller’s Private Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Running Private Process Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Viewing Audit Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
TIBCO BusinessConnect cXML Protocol User’s Guide
vi
| Contents Chapter 10 Tutorial — TIBCO ActiveMatrix BusinessWorks Private Processes . . . . . . . . . . 115 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Using the Example Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Opening the Example Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up the Example Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Project Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
117 117 118 119
Setting Up PunchOutSetupRequest Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Setting Up Buyer on Machine 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Setting Up Seller on Machine 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Running PunchOutSetupRequest Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running Seller on Machine 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running Buyer on Machine 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Expected Behavior. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
124 124 124 125
Appendix A Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Appendix B Property Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Appendix C Handling Different cXML Document Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Outbound Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Inbound Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Appendix D Outbound Message Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
TIBCO BusinessConnect cXML Protocol User’s Guide
| vii
Tables
Table 1
General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Table 2
Syntax Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Table 3
Operations Supported in cXML 1.2.016 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Table 4
Notify Operation Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Table 5
Notify Request Action Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Table 6
Request-Response Operation Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Table 7
Request Action Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Table 8
Response Action Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Table 9
Trading Host cXML General Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Table 10
Trading Partner cXML General Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Table 11
ae/cXML/InitiatorRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Table 12
ae/cXML/ResponderRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Table 13
ae/cXML/ResponderResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Table 14
ae/cXML/InitiatorResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Table 15
ae/cXML/ErrorNotify Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Table 16
ae/BC/Attachment Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Table 17
ae/BC/TradingPartner Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Table 18
Audit Log Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Table 19
Transaction Detail Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Table 20
State Details View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Table 21
Non-Repudiation Log Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Table 22
Resend Log Columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Table 23
Audit Log States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Table 24
Error States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Table 25
Participant Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Table 26
Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Table 27
cXML Configurable Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Table 28
Siglepart MIME Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 TIBCO BusinessConnect cXML Protocol User’s Guide
viii
| Tables Table 29
Multipart MIME Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
TIBCO BusinessConnect cXML Protocol User’s Guide
| ix
Preface
This software may be available on multiple operating systems. However, not all operating system platforms for a specific software version are released at the same time. Please see the readme file for the availability of this software version on a specific operating system platform. TIBCO BusinessConnect cXML Protocol is a cXML plug-in for TIBCO BusinessConnect, enabling users of TIBCO BusinessConnect to connect trading partners with cXML protocol in their business transactions. Based on an agreed-upon process flow and common document format, you and your trading partners can conduct secure and verifiable business transactions online using TIBCO BusinessConnect cXML Protocol.
Topics •
Related Documentation, page x
•
Typographical Conventions, page xii
•
Connecting with TIBCO Resources, page xv
TIBCO BusinessConnect cXML Protocol User’s Guide
x
| Related Documentation Related Documentation This section lists documentation resources you may find useful.
TIBCO BusinessConnect cXML Protocol Documentation The following documents form the TIBCO BusinessConnect cXML Protocol documentation set: •
TIBCO BusinessConnect cXML Protocol Installation Read this manual for instructions on site preparation and installation.
•
TIBCO BusinessConnect cXML Protocol User’s Guide Read this manual for instructions on using the product.
•
TIBCO BusinessConnect cXML Protocol Release Notes Read the release notes for a list of new and changed features. This document also contains lists of known issues and closed issues for this release.
Other TIBCO Product Documentation You may find it useful to read the documentation for the following TIBCO products: •
TIBCO ActiveMatrix BusinessWorks™ software: This product provides an integration platform that enables companies to rapidly integrate systems and automate business processes.
•
TIBCO Administrator™ software: This product provides capabilities for managing users, monitoring machines, and deploying and managing applications that use TIBCO products.
•
TIBCO BusinessConnect™ software: This product is a B2B (business-to-business) gateway that allows your company to engage in electronic commerce with your business partners.
•
TIBCO Designer™ software: This product provides a graphical user interface to create TIBCO ActiveMatrix BusinessWorks process definitions, or create or modify TIBCO Adapter configurations.
•
TIBCO Enterprise Message Service™ software: This product sends messages from your applications in a format that conforms to the Java Messaging Service (JMS) specification.
•
TIBCO Hawk® software: This product is for monitoring and managing distributed applications and systems throughout the enterprise.
TIBCO BusinessConnect cXML Protocol User’s Guide
Preface xi
|
•
TIBCO Rendezvous® software: This product uses messages to enable distributed application programs to communicate across a wide variety of hardware platforms and programming languages.
•
TIBCO Runtime Agent™ software: This product is a bundle of TIBCO software and third-party software that is required to run many TIBCO applications such as TIBCO ActiveMatrix BusinessWorks, TIBCO Adapters, and so on.
Third-Party Documentation The cXML protocol specification can be found at the following site: http://www.cxml.org
TIBCO BusinessConnect cXML Protocol User’s Guide
xii
| Typographical Conventions Typographical Conventions The following typographical conventions are used in this manual. Table 1 General Typographical Conventions Convention
Use
ENV_NAME
TIBCO products are installed into an installation environment. A product installed into an installation environment does not access components in other installation environments. Incompatible products and multiple instances of the same product must be installed into different installation environments.
TIBCO_HOME
An installation environment consists of the following properties: •
Name Identifies the installation environment. This name is referenced in documentation as ENV_NAME. On Microsoft Windows, the name is
appended to the name of Windows services created by the installer and is a component of the path to the product shortcut in the Windows Start > All Programs menu. •
BCCXML_HOME
code font
Path The folder into which the product is installed. This folder is referenced in documentation as TIBCO_HOME.
TIBCO BusinessConnect cXML Protocol installs into a directory within a TIBCO_HOME. This directory is referenced in documentation as BCCXML_HOME. The default value of BCCXML_HOME depends on the operating system. For example on Windows systems, the default value is C:\tibco\bc\version_number\protocols\cxml. Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example: Use MyCommand to start the foo process.
bold code font
Bold code font is used in the following ways: •
In procedures, to indicate what a user types. For example: Type admin.
•
In large code samples, to indicate the parts of the sample that are of particular interest.
•
In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable | disable]
TIBCO BusinessConnect cXML Protocol User’s Guide
Preface xiii
|
Table 1 General Typographical Conventions (Cont’d) Convention
Use
italic font
Italic font is used in the following ways:
Key combinations
•
To indicate a document title. For example: See TIBCO ActiveMatrix BusinessWorks Concepts.
•
To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal.
•
To indicate a variable in a command or code syntax that you must replace. For example: MyCommand PathName
Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C. Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q. The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances. The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result. The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.
Table 2 Syntax Typographical Conventions Convention
Use
[ ]
An optional item in a command or code syntax. For example: MyCommand [optional_parameter] required_parameter
|
A logical OR that separates multiple items of which only one may be chosen. For example, you can select only one of the following parameters: MyCommand param1 | param2 | param3
TIBCO BusinessConnect cXML Protocol User’s Guide
xiv
| Typographical Conventions Table 2 Syntax Typographical Conventions (Cont’d) Convention
Use
{ }
A logical group of items in a command. Other syntax notations may appear within each logical group. For example, the following command requires two parameters, which can be either the pair param1 and param2, or the pair param3 and param4. MyCommand {param1 param2} | {param3 param4}
In the next example, the command requires two parameters. The first parameter can be either param1 or param2 and the second can be either param3 or param4: MyCommand {param1 | param2} {param3 | param4}
In the next example, the command can accept either two or three parameters. The first parameter must be param1. You can optionally include param2 as the second parameter. And the last parameter is either param3 or param4. MyCommand param1 [param2] {param3 | param4}
TIBCO BusinessConnect cXML Protocol User’s Guide
Preface xv
|
Connecting with TIBCO Resources
How to Join TIBCOmmunity TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to http://www.tibcommunity.com.
How to Access TIBCO Documentation You can access TIBCO documentation here: http://docs.tibco.com
How to Contact TIBCO Support For comments or problems with this manual or the software it addresses, contact TIBCO Support as follows: •
For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site: http://www.tibco.com/services/support
•
If you already have a valid maintenance or support contract, visit this site: https://support.tibco.com Entry to this site requires a user name and password. If you do not have a user name, you can request one.
TIBCO BusinessConnect cXML Protocol User’s Guide
xvi
| Connecting with TIBCO Resources
TIBCO BusinessConnect cXML Protocol User’s Guide
|1 Chapter 1
Introduction
This chapter gives an introduction to TIBCO BusinessConnect cXML Protocol and describes its features.
Topics •
The cXML Protocol and TIBCO BusinessConnect cXML Protocol, page 2
•
Features of TIBCO BusinessConnect cXML Protocol, page 3
•
Supported cXML Versions and Operations, page 4
TIBCO BusinessConnect cXML Protocol User’s Guide
2
| Chapter 1
Introduction
The cXML Protocol and TIBCO BusinessConnect cXML Protocol This section gives an introduction of the cXML protocol and TIBCO BusinessConnect cXML Protocol.
The cXML Protocol Commerce eXtensible Markup Language (cXML), which is based on Extensible Markup Language (XML), is a business protocol for documents used in e-commerce. cXML allows buyers, sellers, aggregators, and intermediaries to connect to a marketplace and to each other over the Internet. cXML was written for the transaction needs of electronic product catalogs, procurement applications, and buying communities. cXML transactions involve the exchange of documents, most of which are analogous to hardcopy documents traditionally used in business. These documents are simple text files, but they have a well-defined structure and contents.
TIBCO BusinessConnect cXML Protocol TIBCO BusinessConnect cXML Protocol is the TIBCO implementation of cXML. It acts as a cXML plug-in to TIBCO BusinessConnect, enabling TIBCO BusinessConnect to connect trading partners that want to use the cXML protocol in their business transactions. Based on an agreed-upon process flow and common document format, you and your trading partners can conduct secure and verifiable business transactions online using TIBCO BusinessConnect cXML Protocol. TIBCO BusinessConnect cXML Protocol no longer supports TIBCO BusinessPartner.
TIBCO BusinessConnect cXML Protocol User’s Guide
Features of TIBCO BusinessConnect cXML Protocol 3
|
Features of TIBCO BusinessConnect cXML Protocol The following are major features in TIBCO BusinessConnect cXML Protocol: •
Support for cXML up to version 1.2.016.
•
Synchronous request-response and one-way notify operation types.
•
HTTP, HTTPS transport protocols, as well as HTTPS with client authentication (HTTPSCA).
•
Support for Ariba Commerce Services Network (ACSN).
•
Support for Ariba Marketplace Network Edition (AMNE).
•
Authentication of documents through shared secret, digital signatures and Message Authentication Code (MAC).
•
Support for optional ProfileResponse elements.
•
Smart routing.
•
The ability to send and receive attachments for all transactions except ProfileRequest and PunchOutOrderMessage.
•
Validation using DTD (Document Type Definitions) files for all documents exchanged.
•
The ability of TIBCO BusinessConnect to act as a marketplace.
•
Configurable wait time private process response.
•
Audit logs, non-repudiation logs, and resend logs.
•
Support for non-default trading participant domain identities for outbound documents.
New Features in This Release It is noteworthy that TIBCO BusinessConnect cXML Protocol 6.x is built on the architecture of TIBCO BusinessConnect 6.x, which is now incorporated into TIBCO Administrator. It utilizes many features inherent in TIBCO BusinessConnect 6.x, for example, user authentication for external users from trading partners, IP filter, unified gateway server in the DMZ zone, and added platform supports. For a list of the features available in TIBCO BusinessConnect 6.0 or later, see TIBCO BusinessConnect Trading Partner Administration Guide.
TIBCO BusinessConnect cXML Protocol User’s Guide
4
| Chapter 1
Introduction
Supported cXML Versions and Operations TIBCO BusinessConnect cXML Protocol supports the following cXML versions: •
1.1.009
•
1.1.010
•
1.2.000~1.2.016
Table 3 is a list of operations supported in cXML 1.2.016 and the DTDs that define them. For information on the version changes in newer versions, go to http://www.cXML.org/spec/release_notes.cfm. Table 3 Operations Supported in cXML 1.2.016 Transaction (Request Action) Name
Response Action Name
Type
Validation DTD
Since
GetPendingRequest
GetPendingResponse
Sync RR
cXML.dtd
1.1.009
OrderRequest
DefaultResponse
Sync RR
cXML.dtd
1.1.009
ProfileRequest
ProfileResponse
Sync RR
cXML.dtd
1.1.009
PunchOutOrder Message
N/A
Notify
cXML.dtd
1.1.009
PunchOutSetup Request
PunchOutSetup Response
Sync RR
cXML.dtd
1.1.009
Subscription ChangeMessage
N/A
Notify
cXML.dtd
1.1.009
Subscription ContentRequest
Subscription ContentResponse
Sync RR
cXML.dtd
1.1.009
SubscriptionList Request
SubscriptionList Response
Sync RR
cXML.dtd
1.1.009
SupplierChange Message
N/A
Notify
cXML.dtd
1.1.009
SupplierData Request
SupplierData Response
Sync RR
cXML.dtd
1.1.009
SupplierList Request
SupplierList Response
Sync RR
cXML.dtd
1.1.009
StatusUpdate Request
DefaultResponse
Sync RR
cXML.dtd
1.1.009
TIBCO BusinessConnect cXML Protocol User’s Guide
Supported cXML Versions and Operations 5
|
Table 3 Operations Supported in cXML 1.2.016 (Cont’d) Transaction (Request Action) Name
Response Action Name
Type
Validation DTD
Since
ConfirmationRequest
DefaultResponse
Sync RR
Fulfill.dtd
1.2.000
ShipNoticeRequest
DefaultResponse
Sync RR
Fulfill.dtd
1.2.000
CopyRequest
DefaultResponse
Sync RR
Fulfill.dtd
1.2.001
ProviderSetup Request
ProviderSetup Response
Sync RR
cXML.dtd
1.2.001
ProviderDoneMessage
N/A
Notify
cXML.dtd
1.2.001
CatalogUpload Request
DefaultResponse
Sync RR
cXML.dtd
1.2.002
MasterAgreement Request
DefaultResponse
Sync RR
cXML.dtd
1.2.005
InvoiceDetail Request
DefaultResponse
Sync RR
Invoice Detail.dtd
1.2.006
AuthRequest
AuthResponse
Sync RR
cXML.dtd
1.2.009
PaymentRemittance Request
DefaultResponse
Sync RR
Payment Remittance.dtd
1.2.011
PaymentRemittance StatusUpdateRequest
DefaultResponse
Sync RR
Payment Remittance.dtd
1.2.011
TimeCardInfoRequest
DefaultResponse
Sync RR
Fulfill.dtd
1.2.011
TimeCardRequest
DefaultResponse
Sync RR
Fulfill.dtd
1.2.011
DataAvailable Message
N/A
Notify
cXML.dtd
1.2.013
DataRequest
DataResponse
Sync RR
cXML.dtd
1.2.013
PaymentProposal Request
DefaultResponse
Sync RR
Payment Remittance.dtd
1.2.014
TIBCO BusinessConnect cXML Protocol User’s Guide
6
| Chapter 1
Introduction
TIBCO BusinessConnect cXML Protocol User’s Guide
|7 Chapter 2
TIBCO BusinessConnect cXML Protocol Process Flows and Functionality
This chapter describes process flows and relevant functionality when using TIBCO BusinessConnect cXML Protocol for cXML transactions.
Topics •
The cXML Operations and TIBCO BusinessConnect cXML Protocol, page 8
•
Process Flow for Outbound and Inbound Requests, page 11
•
TIBCO BusinessConnect cXML Protocol and PunchOut, page 15
•
TIBCO BusinessConnect cXML Protocol and Marketplace, page 18
•
Document Authentication, page 19
•
Multiple Credentials, page 21
TIBCO BusinessConnect cXML Protocol User’s Guide
8
| Chapter 2
TIBCO BusinessConnect cXML Protocol Process Flows and Functionality
The cXML Operations and TIBCO BusinessConnect cXML Protocol TIBCO BusinessConnect cXML Protocol is a plug-in for TIBCO BusinessConnect, which acts as a gateway between a private process of an organization and trading partners on the Internet. TIBCO BusinessConnect cXML Protocol enforces that outbound and inbound documents conform to cXML specifications and automates and simplifies many tasks for the organization’s private processes, including: •
Maintaining host and partner information.
•
Applying credentials and document security.
•
Constructing and validating documents.
•
Applying MIME formatting based on cXML specifications.
•
Maintaining transport connections.
In this way, private process designers can focus on more useful tasks such as, how to use the transacted data in their business processes. This section describes how cXML operations are carried out with TIBCO BusinessConnect cXML Protocol. For a more detailed process flow in TIBCO BusinessConnect cXML Protocol, see Process Flow for Outbound and Inbound Requests on page 11.
cXML Operation Types In a cXML operation, two partners exchange business documents over the Internet based on the pre-defined rules of cXML. cXML specifies the message formats and transport protocols the partners must utilize in order to conduct business-to-business (B2B) operations. The process flow for a typical cXML PunchOut purchase order proceeds as follows: 1. A buyer sends a cXML PunchOutSetupRequest to a seller. 2. The seller sends a cXML PunchOutSetupResponse to the buyer. This message contains the URL to the seller’s catalog page. 3. The buyer uses a browser to access the catalog page, selects an item, and checks out. 4. The seller sends a cXML PunchOutOrderMessage to the buyer, containing a price quote. 5. The buyer sends a cXML OrderRequest to the seller.
TIBCO BusinessConnect cXML Protocol User’s Guide
The cXML Operations and TIBCO BusinessConnect cXML Protocol 9
|
6. The seller sends a cXML DefaultResponse to the buyer to finalize the order. Depending on the process flow, different operation types are used. There are two operation types in cXML. In the example above, the following operations are synchronous request-response operations: •
PunchOutSetupRequest / PunchOutSetupResponse
•
OrderRequest / DefaultResponse
PunchOutOrderMessage in the example above is a one-way notify operation.
Synchronous Request-Response Operations When both partners are using TIBCO BusinessConnect cXML Protocol, a synchronous request-response operation occurs in the following sequence: 1. A private process inside the initiating company sends a request message to its BusinessConnect server. 2. The initiator’s BusinessConnect server sends the request message to the responder. 3. The responder’s BusinessConnect server forwards the authenticated and validated business request to the local private process and waits for a response. 4. The responder private process responds to its BusinessConnect server. 5. The responder’s BusinessConnect server forwards the response to the initiator over the same channel. 6. The initiating company’s BusinessConnect server forwards the business response to the initiator private process. For a more detailed process flow in TIBCO BusinessConnect cXML Protocol, see Process Flow for Outbound and Inbound Requests on page 11.
One-way Notify Operations When both partners are using TIBCO BusinessConnect cXML Protocol, a one-way notify operation occurs in the following sequence: 1. A private process inside the initiating company sends a notify message to its BusinessConnect server. 2. The initiator’s BusinessConnect server sends the notify message to the responder. 3. The responder’s BusinessConnect server acknowledges receipt of the notify message and forwards the message to its local private process. TIBCO BusinessConnect cXML Protocol User’s Guide
10
| Chapter 2
TIBCO BusinessConnect cXML Protocol Process Flows and Functionality
For a more detailed process flow in TIBCO BusinessConnect cXML Protocol, see Process Flow for Outbound and Inbound Requests on page 11.
TIBCO BusinessConnect cXML Protocol User’s Guide
Process Flow for Outbound and Inbound Requests 11
|
Process Flow for Outbound and Inbound Requests This section describes in detail how TIBCO BusinessConnect cXML Protocol processes request or notify messages initiated by private processes as well as external trading partners.
Processing Outbound Request and Notify Messages The following steps occur when BusinessConnect sends an outbound cXML document to a public process over the Internet: 1. A private process publishes a message of class ae/cXML/InitiatorRequest on TIBCO Rendezvous or on an implementation of Java Message Service (JMS), such as TIBCO Enterprise Message Service. The message contains all fields specified in Outbound Request Format on page 61, including a cXML
or element in the request field. 2. TIBCO BusinessConnect cXML Protocol performs the following functions: — Retrieves the message from TIBCO Rendezvous or JMS. — Validates the cXML document using the operation ID and trading partner elements specified in the document. — Constructs a cXML document using information provided by the private process or from its local configuration store, including the host and partner’s credentials, document security information, and so on. — Wrap the cXML document along with any attachments into a MIME-formatted envelop. For information on MIME formatting for outbound documents, see Outbound Message Formats on page 135. — Establishes a connection at the trading partner’s URL (which can be ACSN’s URL) with the appropriate transport protocol based on the trading partner settings and business agreement settings, and posts the cXML document. 3. BusinessConnect waits for a response or an acknowledgement from the trading partner.
TIBCO BusinessConnect cXML Protocol User’s Guide
12
| Chapter 2
TIBCO BusinessConnect cXML Protocol Process Flows and Functionality
4. In a request-response transaction, TIBCO BusinessConnect cXML Protocol performs the following functions upon receiving the response from the trading partner: — Validates the response document. — Formats the response into a message of class ae/cXML/InitiatorResponse and publishes the message on TIBCO Rendezvous or JMS. See Inbound Response Format on page 69 for the message format. In a one-way notify transaction, TIBCO BusinessConnect cXML Protocol considers the transaction complete when it receives an acknowledgement of receipt from the trading partner, and simply forwards the acknowledgement to the private process through TIBCO Rendezvous or JMS. 5. The private process retrieves the message from TIBCO Rendezvous or JMS and processes it.
Processing Inbound Request and Notify Messages The following steps occur when TIBCO BusinessConnect cXML Protocol receives an inbound request or notify message at its cXML URL over a previously enabled transport protocol: 1. TIBCO BusinessConnect cXML Protocol performs the following tasks: — Inspects the MIME header to determine whether there are attachments. — Determines the version of the cXML document. See Handling Different cXML Document Versions on page 133 for information on how TIBCO BusinessConnect cXML Protocol handles different cXML document versions. — Validates the document using the appropriate cXML DTD in its configuration store. — Authenticates the document using the document’s credentials based on the pre-configured document security options. — Determines whether the cXML operation is allowed in its business agreement settings.
TIBCO BusinessConnect cXML Protocol User’s Guide
Process Flow for Outbound and Inbound Requests 13
|
2. If all the tasks in the previous step complete without errors, TIBCO BusinessConnect cXML Protocol processes the cXML document depending on what the document is: — ProfileRequest TIBCO BusinessConnect cXML Protocol sends a cXML response over the same transport connection with all operations that it supports. The transaction then ends here. — Notify Messages TIBCO BusinessConnect cXML Protocol formats the notify message into a message of class ae/cXML/ResponderRequest and publishes the message along with attachments on TIBCO Rendezvous or JMS (see Inbound Request Format on page 65 for formatting information). The transaction then ends here. TIBCO BusinessConnect cXML Protocol also sends an HTTP 200 OK acknowledgement to the sender by default. To change the default response for a PunchOutOrderMessage, see Configurable Reply to PunchOutOrderMessage on page 16. — All Other Request Messages TIBCO BusinessConnect cXML Protocol formats the request into an ae/cXML/ResponderRequest message and publishes the message along with attachments on TIBCO Rendezvous or JMS. It then waits for a response from the local private process. 3. A private process retrieves the ae/cXML/ResponderRequest message and processes it. If the request field contains a cXML request, it must respond by publishing an ae/cXML/ResponderResponse message on TIBCO Rendezvous or JMS with a cXML response in the request field. 4. When TIBCO BusinessConnect cXML Protocol retrieves the response from TIBCO Rendezvous or JMS, it performs the following functions: — Validates the cXML response and verifies that the response is appropriate for the current transaction. — Wrap the cXML document into a single-part MIME message. — Sends the MIME-formatted cXML response back to the trading partner over the same transport connection.
Delayed Response to OrderRequest Messages Because requests and responses travel through the same connection channel, a true synchronous response (OrderResponse) for an OrderRequest message may not be possible at times. If TIBCO BusinessConnect cXML Protocol does not receive a response from the local private process within a configurable time
TIBCO BusinessConnect cXML Protocol User’s Guide
14
| Chapter 2
TIBCO BusinessConnect cXML Protocol Process Flows and Functionality
period (see Table 8, Response Action Tab, on page 30), it responds with a DefaultResponse message that contains a status code of 201 and a status text of Accepted. This tells the trading partner that it will send a StatusUpdateRequest message at a later time. When the responder private process is ready to update the order status, it sends a StatusUpdateRequest message. The responder private process can continue to send StatusUpdateRequest messages until it sends one StatusUpdateRequest with a status of 200.
TIBCO BusinessConnect cXML Protocol User’s Guide
TIBCO BusinessConnect cXML Protocol and PunchOut 15
|
TIBCO BusinessConnect cXML Protocol and PunchOut The PunchOut transaction is one of the main features of the cXML protocol. It affords the way for suppliers in a commerce network (ACSN for example) to allow per-transaction access to the catalogs on their web servers. It also enables buyers on the commerce network to access the most up-to-date pricing and availability information on products by going to the suppliers’ catalogs directly. This section describes how TIBCO BusinessConnect cXML Protocol works with cXML PunchOut. For more information on PunchOut transactions, see the cXML protocol specification.
PunchOutSetupRequest When BusinessConnect receives an ae/cXML/InitiatorRequest message from a private process via TIBCO Rendezvous or JMS, and the request field is a element, TIBCO BusinessConnect cXML Protocol performs some supplemental tasks in addition to those described in Processing Outbound Request and Notify Messages on page 11. A cXML PunchOutSetupRequest contains two critical elements: and . •
BrowserFormPost URL If the PunchOutSetupRequest in the request field
does not contain a element, or the element is empty or does not exist, TIBCO BusinessConnect cXML Protocol inserts the URL of the local BusinessConnect instance into the PunchOutSetupRequest as the value of . If more than one transport protocol is enabled in the local BusinessConnect instance, the order of precedence in URL selection is HTTPSCA first, then HTTPS, then HTTP. When a network commerce hub (ACSN for example) receives a PunchOutSetupRequest message, it first uses its own pre-configured SupplierSetup URL for the trading partner if one is available. Otherwise, it uses the SupplierSetup URL in the PunchOutSetupRequst to forward the request to the trading partner. •
SupplierSetup URL If the PunchOutSetupRequest in the request field does
not contain a element, or the element is empty or does not exist, TIBCO BusinessConnect cXML Protocol uses the value of Supplier Setup URL in the trading partner’s cXML protocol configuration (see Setting Up cXML Protocol for Trading Partners on page 46 for more information). TIBCO BusinessConnect cXML Protocol User’s Guide
16
| Chapter 2
TIBCO BusinessConnect cXML Protocol Process Flows and Functionality
If no SupplierSetup URL is configured there, then TIBCO BusinessConnect cXML Protocol sends the PunchOutSetupRequest message without a SupplierSetup URL.
PunchOutOrderMessage When the buyer is done shopping and clicks the check-out button in a cXML PunchOut transaction, the seller must send a PunchOutOrderMessage to the buyer. Two possible implementations are described below: •
The supplier’s shopping site can embed the encoded PunchOutOrderMessage in the shopping cart page as a hidden HTML Form field. When the user clicks the check-out button, the browser posts the encoded PunchOutOrderMessage to the BrowserFormPost URL originally supplied by the buyer in the PunchOutSetupRequest. When the buyer is using TIBCO BusinessConnect, this BrowserFormPost URL usually points back to the buyer’s own BusinessConnect instance. In effect, the supplier sends PunchOutOrderMessage to the buyer through the buyer’s own web browser. For more information on this method, see the cXML protocol specification.
•
The supplier’s web server can act as a private process to BusinessConnect and publish an ae/cXML/InitiatorRequest message along with its PunchOutOrderMessage to its BusinessConnect instance through TIBCO Rendezvous or JMS. In this case, it should use the BrowserFormPost URL in the original PunchOutSetupRequest from the buyer in the postURL field of the ae/cXML/InitiatorRequest message. See Table 11 on page 61 for information on using the postURL field.
Configurable Reply to PunchOutOrderMessage If the supplier is configured to send PunchOutOrderMessages via HTML Form Posts, by default the user will only see the text "OK" after the page is refreshed, since TIBCO BusinessConnect cXML Protocol acknowledges all notify messages with an HTTP 200 OK message. You can change this default reply for PunchOutOrderMessages to a more elaborate webpage that tells the user that a price quote has been received, for example. This is done by supplying the URL of an HTML page or a script such as ASP (Active Server Page) in the PunchOutOrderMessage Reply URL field in the trading host’s cXML configuration panel (see Table 9, Trading Host cXML General Properties, on page 40).
TIBCO BusinessConnect cXML Protocol User’s Guide
TIBCO BusinessConnect cXML Protocol and PunchOut 17
|
After you specify a URL in the PunchOutOrderMessage Reply URL field, TIBCO BusinessConnect cXML Protocol will redirect the Web browser to that URL. TIBCO BusinessConnect cXML Protocol also passes the following parameters to the URL in case of a script: •
statuscode=status_code
•
statusmessage=status_message
•
statusbody=detailed_message
•
tpname=trading_partner_name
•
tpdomain=trading_partner_domain
•
toid=trading_partner_identity
You can use these parameters to customize your webpage.
TIBCO BusinessConnect cXML Protocol User’s Guide
18
| Chapter 2
TIBCO BusinessConnect cXML Protocol Process Flows and Functionality
TIBCO BusinessConnect cXML Protocol and Marketplace Because TIBCO BusinessConnect has authentication capabilities and TIBCO BusinessConnect cXML Protocol can support all operations in the cXML specification, you can use BusinessConnect as a cXML marketplace to trading partners. When private processes send messages, they can instruct TIBCO BusinessConnect cXML Protocol to send them as a marketplace. The private process designers then can implement the marketplace-specific trade logic. For more information on using TIBCO BusinessConnect cXML Protocol as a marketplace, see Using TIBCO BusinessConnect cXML Protocol with Marketplaces on page 78.
TIBCO BusinessConnect cXML Protocol User’s Guide
Document Authentication 19
|
Document Authentication There are three ways that a document can be authenticated in TIBCO BusinessConnect cXML Protocol: •
Shared secrets
•
Shared secrets with MAC encryption
•
Digital signatures
The most common way is using shared secrets. This is like using a password. In shared secrets, the physical transport can be HTTP, HTTPS, or HTTPSCA. For instructions on using document authentication with TIBCO BusinessConnect cXML Protocol, see Setting Up cXML Protocol for Trading Partners on page 46.
Shared Secrets Trading participants can use shared secrets to authenticate cXML documents from each other. To use shared secrets, trading participants make their secret keys known to each other. When one of the participants initiates a transaction, it embeds its own secret key in the outbound cXML message. The receiver then uses its partner’s secret key verify the validity of the embedded secret key in the inbound document. ACSN authenticates cXML documents by comparing the shared secret in the document to the one that it knows. ACSN then removes the sender's shared secret and replaces it with the recipient's shared secret in any cXML documents that it sends, so the trading partner can authenticate ACSN as the sender in return. You should use the HTTPS protocol or employ MAC encryption of shared secrets in order to maintain confidentiality of you and your partner’s secret keys when transmitting them over the Internet.
Digital Signatures Digital signatures use public-key cryptography for authentication. To use digital signatures with TIBCO BusinessConnect cXML Protocol, both trading participants must obtain a public certificate-private key pair. They then must make their public certificates known to each other. When Participant A initiates a transaction, it must sign the cXML document with its private key. Participant B
TIBCO BusinessConnect cXML Protocol User’s Guide
20
| Chapter 2
TIBCO BusinessConnect cXML Protocol Process Flows and Functionality
then uses Participant A’s public certificate to verify the signature in the cXML document. Participant B must likewise sign the response document with its own private key so that Participant A can verify the signature with its public certificate. To use digital signatures for document authentication, you must install both the host participant’s private key and the partner participant’s public certificate in their respective trading participant configuration panels in the BusinessConnect console. See TIBCO BusinessConnect Trading Partner Administration Guide for instructions on configuring digital signatures for trading participants. Note that digital signatures is not the same as configuring HTTPSCA. If you wish to use HTTPSCA for your BusinessConnect server, you must also add your server’s public certificate in the Certificate Store configuration panel. For more information, see TIBCO BusinessConnect Trading Partner Administration Guide. TIBCO BusinessConnect cXML Protocol utilizes digital signatures for authentication only and not for encryption. If you wish to conduct confidential transactions over the internet, you must use the HTTPS or HTTPSCA protocol.
TIBCO BusinessConnect cXML Protocol User’s Guide
Multiple Credentials 21
|
Multiple Credentials The To and From credentials appear in the header of cXML messages. They are used to identify the initiator and the responder of a transaction. Multiple credentials can be used to identify the same trading partner using more than one domain-identity pairs.
Validating Credentials in Inbound Messages When TIBCO BusinessConnect cXML Protocol validates a request or notify message, it evaluates the inbound message's To and From credentials against the local configuration. The credentials are checked against the Domain - Identity pools for the trading partner and trading host in the Configuration GUI. If the required credentials do not exist, TIBCO BusinessConnect cXML Protocol terminates the transaction by responding with an error message. You can determine how strictly the credentials are validated by configuring the following two properties, which are found in TIBCO Administrator by clicking BusinessConnect > System Settings > Activated Protocol Plug-ins and Properties > cXML: •
cxml.credentialcheck.from
•
cxml.credentialcheck.to — Specifies how many of the To credentials must match configured partner identities. By default, all sent credentials must match.
— Specifies how many of the From credentials must match configured partner identities. By default, all sent credentials must match for the message to be processed.
See Appendix B, Property Reference, on page 129 for more information on configuring these two properties.
Controlling Credentials in Outbound Messages When a private process initiates a request or notify message, TIBCO BusinessConnect cXML Protocol adds the message header along credentials taken from the locally configured Domain - Identity pools. By default, TIBCO BusinessConnect cXML Protocol sends only the default credential for a given host or partner. The default From credential is the default domain-identity pair for the trading host. The default To credential is the default domain identity for the respective trading partner. However, you can configure TIBCO BusinessConnect cXML Protocol to send multiple credentials in outbound request or notify messages. The following two options are found in the cXML protocol configuration for a trading partner: TIBCO BusinessConnect cXML Protocol User’s Guide
22
| Chapter 2
TIBCO BusinessConnect cXML Protocol Process Flows and Functionality
•
Send Messages with Multiple From Credentials — All messages sent to the trading partner will include all the domain identities listed in the trading host Domain - Identity pool.
•
Send Message with Multiple To Credentials — All messages sent will include the full list of domain identities from the trading partner Domain - Identities pool in the To credential.
See Table 10, Trading Partner cXML General Properties, on page 47 for more information on these options. Sending multiple To or From credentials sends the full list of domain identities in the trading partner Domain Identity pool. This includes domain identities that were created for any enabled protocol other than cXML. When a trading host is acting as a marketplace, the multiple credentials feature is disabled. See Using TIBCO BusinessConnect cXML Protocol with Marketplaces on page 78 for more information. The following code is the cXML header of an example outbound request message if you select the Send Messages with Multiple From Credentials checkbox. Notice that the element contains three elements. These are all the credentials configured in the Domain - Identity pool of the trading host. 123456789 id777 AN01000010452-T AN01000010452-T AN01000010452-T shared secret TIB/BusinessConnect cXML
TIBCO BusinessConnect cXML Protocol User’s Guide
| 23 Chapter 3
Preparing to Use TIBCO BusinessConnect cXML Protocol
This chapter explains the four necessary tasks you must perform before configuring trading participants with TIBCO BusinessConnect cXML Protocol: exchanging information with your trading partner, managing cXML versions and operations, configuring message transports, and configuring domains.
Topics •
Overview, page 24
•
Managing cXML Operations, page 27
•
Setting Up Transports, page 32
•
Configuring Domains, page 35
TIBCO BusinessConnect cXML Protocol User’s Guide
24
| Chapter 3
Preparing to Use TIBCO BusinessConnect cXML Protocol
Overview This chapter describes the preliminary information you need in order to configure your BusinessConnect server for your cXML transactions. It also gives the instructions for configuring some of this information in your BusinessConnect server. You must perform all the tasks in this chapter prior to configuring trading participants with TIBCO BusinessConnect cXML Protocol.
Exchanging Information with Your Trading Partner Before you start conducting e-commerce with a trading partner, you must work out the following information with your trading partner: •
Agree on the cXML version. Partners that use cXML to conduct e-commerce must agree on the default cXML version for their documents. Trading partners can exchange this information via email, the web, or any other method.
•
Agree on whether to use document authentication as well as the authentication method. Supported methods are shared secrets, MAC-encrypted shared secrets, and digital signatures.
•
Exchange the following information: — Domain Identity The identity domain and the unique ID for you and your trading partner. If you are both members of a commerce network, you must use the identifiers assigned by the network hub, such as NetworkID for ACSN. — Server URLs You need to use your trading partner’s server URL to conduct e-commerce transactions, and visa versa. If you agree upon multiple protocols (HTTP, HTTPS, and HTTPSCA for example), you must exchange server URLs for each of the agreed protocols. This can be done via email, the web, or any other method. Server URLs for TIBCO BusinessConnect cXML Protocol follow the formats below: protocol://hostName:portNumber/cXML
For example: http://www.myhost.com:6700/cXML https://www.myhost.com:6705/cXML
— Shared Secrets If you wish to use shared secrets for document security, you must exchange secret keys with your trading partner, along with a creation date and an expiration date. — Public certificates In order to use HTTPS or HTTPSCA for your cXML
TIBCO BusinessConnect cXML Protocol User’s Guide
Overview 25
|
transactions, as well as utilize digital signatures for document authentication, you must also exchange public certificates.
Configuring TIBCO BusinessConnect You must perform three tasks in the BusinessConnect console in TIBCO Administrator before complete configuration of all trading participants with TIBCO BusinessConnect cXML Protocol: operations, transports, and domains. Operations Before configuring your trading participants to use cXML operations, install each operation in the BusinessConnect console in TIBCO Administrator. You can add them in two ways: •
Importing cXML Versions The TIBCO BusinessConnect cXML Protocol
installation directory contains configuration data files for each version of cXML. You can import one or more versions directly into the Operations Editor and use them without further configuration. •
Manually Adding Operations If you wish to use operations in cXML versions
for which there are no existing configuration data files (such as, cXML versions later than 1.2.016), you must add the versions and operations one by one in the Operations Editor. Only the operations installed in the Operations Editor can be used to validate inbound cXML requests from trading partners. See Handling Different cXML Document Versions on page 133 for more information. See Managing cXML Operations on page 27 for instructions on adding cXML operations. Transports Before you can configure each trading participant’s transport protocol, you must enable them in BusinessConnect. Three types of transports are supported in TIBCO BusinessConnect cXML Protocol: HTTP, HTTPS, HTTPSCA. If you want to use HTTPS or HTTPSCA, you must also install valid certificates in the Server Identities & Certificates tab of the Certificate Store configuration panel, which is accessible at BusinessConnect > System Settings > Certificate Store. For more information, see TIBCO BusinessConnect Trading Partner Administration Guide. See Setting Up Transports on page 32 for instructions on enabling transports.
TIBCO BusinessConnect cXML Protocol User’s Guide
26
| Chapter 3
Preparing to Use TIBCO BusinessConnect cXML Protocol
Attachment Directory TIBCO BusinessConnect cXML Protocol stores all attachments from incoming messages as files on BusinessConnect server. You must also configure the directory for TIBCO BusinessConnect cXML Protocol to use to store these files. See Configuring Message Attachment Directory on page 34 for instructions on configuring the attachment directory. Domains In order to create domain identities for your trading participants, their respective identity domains must exist in BusinessConnect’s list of domains. See Configuring Domains on page 35 for instructions on adding your domains.
TIBCO BusinessConnect cXML Protocol User’s Guide
Managing cXML Operations 27
|
Managing cXML Operations This section describes two methods adding operations in order to use them in TIBCO BusinessConnect cXML Protocol: •
Importing cXML Operations, page 27
•
Adding cXML Operations, page 27
This section also includes instructions for exporting your operation configuration to a configuration data file. See Exporting Versions and Operations on page 31. Only the operations installed in the Operations Editor can be used to validate inbound cXML requests from trading partners. See Handling Different cXML Document Versions on page 133 for more information.
Importing cXML Operations Perform the following steps to import operations of a specific cXML protocol version: 1. In TIBCO Administrator, click BusinessConnect > Operations Editor in the left panel. 2. In the right panel, click the Import button. The Import Operations panel is displayed. 3. Click the Change link. The Change File panel is displayed. 4. Click the Browse button, and select a cXML version, which is located in the TIBCO_HOME/bc/version/protocols/cxml/samples/Transactions
directory. 5. Click the OK button to upload the file. The uploaded file is displayed in the Imported Operations panel. 6. Set the password in the Password field if the CSX file is saved with one and then click the Done button. The cXML operation is imported in BusinessConnect.
Adding cXML Operations If you want to use operations in a cXML version later than 1.2.016, you must add them manually into the BusinessConnect Operations Editor in TIBCO Administrator. Adding cXML operations into BusinessConnect consists of two major tasks:
TIBCO BusinessConnect cXML Protocol User’s Guide
28
| Chapter 3
Preparing to Use TIBCO BusinessConnect cXML Protocol
•
Adding a cXML version.
•
Adding cXML operations one-by-one.
Adding cXML Versions Perform the following steps to add a cXML version: 1. In TIBCO Administrator, click BusinessConnect > Operations Editor in the left panel. 2. Click the cXML link from the Protocol list in the right panel. The Edit Operations: cXML panel is displayed. 3. Click the New Version button. The New Version panel is displayed. 4. In the General tab, enter a version number in the Name field. 5. Click the Change link next to the Validation cXML.dtd field. The Change File panel is displayed. 6. Select the Uploaded File item in the Type drop-down list and then the Upload File field is displayed. 7. Click the Browse button next to the Upload File field to locate and upload your DTD file. 8. Click the OK button in the Change File panel. 9. Follow step 5 to step 8 to specify the Validation Fulfill.dtd, Validation InvoiceDetail.dtd, and Validation Payment Remittance.dtd fields that you want to add. 10. Click the Save button in the New Version to save the version changes. Adding cXML Operations Perform the following steps to add a cXML operation: 1. In TIBCO Administrator, click BusinessConnect > Operations Editor in the left panel. 2. Click the cXML link in the Protocol column in the right panel. The Edit Operations: cXML panel is displayed. 3. From the Version list, select the radio button next to a cXML version you want to add. 4. Click the New Operation button. The New Operation panel is displayed. 5. Select either the Notify or Request-Response item from the Operation Type drop-down list and then click the OK button.
TIBCO BusinessConnect cXML Protocol User’s Guide
Managing cXML Operations 29
|
6. Configure the operation in each tab. For the descriptions of the properties, see Notify Operation Properties on page 29 and Request-Response Operation Properties on page 30. 7. Click the Save button. If you want to save your configuration in case of reinstallation, you can export it to a file. If your trading partner is also using BusinessConnect, you can also share the exported file with your partner to expedite its configuration. For instructions on exporting your configuration, see Exporting Versions and Operations on page 31. Notify Operation Properties Table 4 and Table 5 contain the descriptions to the properties found in a notify operation’s configuration panel. Table 4 Notify Operation Tab Field
Description
Name
The displayed name of the operation.
Description
(Optional) A short description of the operation.
DTD used for validation
The DTD used to validate the documents sent and received in this operation. These DTDs are specified when you define your cXML version in Adding cXML Versions on page 28.
Table 5 Notify Request Action Tab Field
Description
Name
The displayed name of the action.
Description
(Optional) A short description of the action.
Direction
The direction of the notify action:
Root XML Element Name
The name of the root XML element for the action, as defined by the validation DTD which is specified in the Notify Operation tab.
Initiator to Responder.
TIBCO BusinessConnect cXML Protocol User’s Guide
30
| Chapter 3
Preparing to Use TIBCO BusinessConnect cXML Protocol
Request-Response Operation Properties Table 6, Table 7, and Table 8 contain the descriptions to the properties found in a request-response operation’s configuration panel. Table 6 Request-Response Operation Tab Field
Description
Name
The displayed name of the operation.
Description
(Optional) A short description of the operation.
DTD used for validation
The DTD used to validate the documents sent and received in this operation. These DTDs are specified when you define your cXML version in Adding cXML Versions on page 28.
Table 7 Request Action Tab Field
Description
Name
The displayed name of the action.
Description
(Optional) A short description of the action.
Direction
The direction of the request action:
Root XML Element Name
The name of the root XML element for the action, as defined by the validation DTD which is specified in the Request-Response Operation tab.
Initiator to Responder.
Table 8 Response Action Tab Field
Description
Name
The displayed name of the action.
Description
(Optional) A short description of the action.
Direction
The direction of the response action:
Root XML Element Name
The name of the root XML element for the action, as defined by the validation DTD which is specified in the Request-Response Operation tab.
Maximum Wait Time for Private Process (seconds)
The time in seconds that the BusinessConnect server should wait for the private process to respond to a request.
TIBCO BusinessConnect cXML Protocol User’s Guide
Responder to Initiator.
Managing cXML Operations 31
|
When configuring a synchronous request-response operation that is not defined with a response action, you must specify DefaultResponse as the response document in the Name field of the Response Action tab.
Exporting Versions and Operations Perform the following steps to export a cXML version or operation: 1. In TIBCO Administrator, click BusinessConnect > Operations Editor in the left panel. 2. Click the cXML link in the Protocol column in the right panel. The Edit Operation: cXML panel is displayed. 3. Select the radio button next to a version or operation you want to export. 4. If a version radio button is selected, click the Export Version button. If a operation radio button is selected, click the Export Operation button. 5. Click the Set button next to the Password field to set a password in the Export Operations panel. 6. Click the Export Data button. The Save As dialog is displayed with operations.csx as the suggested file name. Change the file name, and click the Save button to save the version or operation.
TIBCO BusinessConnect cXML Protocol User’s Guide
32
| Chapter 3
Preparing to Use TIBCO BusinessConnect cXML Protocol
Setting Up Transports This section describes how to configure three types of transports supported by TIBCO BusinessConnect cXML Protocol, as well as how to configure the directory path for receiving message attachments from the BusinessConnect server.
Configuring HTTP, HTTPS, and HTTPSCA Transport Perform the following steps to set up HTTP transport for your B2B transactions: Task A Enable Transports 1. In TIBCO Administrator, click BusinessConnect > System Settings in the left panel. 2. Click the Inbound Public Transport Types link on the right panel. The Inbound Public Transport Types panel is displayed. 3. Check the HTTP, HTTPS, and HTTPSCA checkboxes from the Transport Type list and then click the Enable button. 4. Click the Done button to save the changes. Task B Configure Transport Services 1. In TIBCO Administrator, click BusinessConnect > Gateway in the left panel. 2. Click the Gateway Services link in the right panel. The Gateway Services panel is displayed. 3. Click the New button and then the New Gateway Service panel is displayed. 4. In the Name field, enter a name for the new service. 5. Select the HTTP item from the Type drop-down list and then click the OK button to save the changes. 6. In the General tab, check the Active checkbox to active the HTTP transport.
TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up Transports 33
|
7. In the Credentials tab, specify a private key. a. Click the New Private Key button in the All Credentials panel. The New Private Key panel is displayed. b. In the Alias field, enter a name for the new private key. c. Upload a new private key from your machine. Click the Change link, and upload the private key. d. Click the Set link next to the Password field. In the Enter Password and Enter Password Again fields, add the password to protect the key. e. Click the OK button and then click the Save button. The new Private Key is listed in the Credential Name column. 8. In the Transport tab, specify the Gateway Service settings, such as, port numbers. For more information about Gateway Service setting, see "Chapter 4 Gateway Services" in TIBCO BusinessConnect Gateway Server Administration.
TIBCO BusinessConnect cXML Protocol User’s Guide
34
| Chapter 3
Preparing to Use TIBCO BusinessConnect cXML Protocol
Configuring Message Attachment Directory When a message contains an attachment, TIBCO BusinessConnect cXML Protocol stores the attachment in a file and sends the file reference to the private process. Perform the following steps to configure BusinessConnect to send attachments to a specific directory: 1. In TIBCO Administrator, click Application Management > BusinessConnect > Configuration in the left panel. 2. Click the BusinessConnect link in the right panel. 3. In the BusinessConnect tab, click the Component Settings sub-tab. 4. Click the Intercomponent Advanced link. 5. Specify a valid directory path in Shared Temporary Directory field. See Configuring Directories for Large and Shared Files in TIBCO BusinessConnect Server Administration Guide for more information on this field. See Attachment Type on page 72 for information on specifying and obtaining the file references for message attachments.
TIBCO BusinessConnect cXML Protocol User’s Guide
Configuring Domains 35
|
Configuring Domains Perform the following steps to add a domain for your trading participants: 1. In TIBCO Administrator, click BusinessConnect > System Settings in the left panel. 2. Click the Metadata Type Configuration link in the right panel. The Metadata Type Configuration panel is displayed. 3. Click the Domains link in the Metadata Type list. The Edit: Domains panel is displayed. 4. Click the New button. 5. In the New Domain panel, type a name of the domain in the Domain Name field and then click the Save button. 6. In the Edit: Domains panel, click the Done button. The Metadata Type Configuration panel is displayed. 7. Click the Done button to save the changes.
TIBCO BusinessConnect cXML Protocol User’s Guide
36
| Chapter 3
Preparing to Use TIBCO BusinessConnect cXML Protocol
TIBCO BusinessConnect cXML Protocol User’s Guide
| 37 Chapter 4
Setting Up Trading Hosts
This chapter describes setting up trading hosts to use TIBCO BusinessConnect cXML Protocol.
Topics •
Setting Up Trading Hosts, page 38
•
Setting Up cXML Protocol for Trading Hosts, page 40
TIBCO BusinessConnect cXML Protocol User’s Guide
38
| Chapter 4
Setting Up Trading Hosts
Setting Up Trading Hosts Perform the following steps to set up a trading host to use the cXML protocol: 1. In TIBCO Administrator, click BusinessConnect > Participants in the left panel. 2. Click the New button in the right panel. The New Participant panel is displayed. 3. Specify a name in the Participant Name field. 4. Select the Host item in the Type drop-down list and then click the OK button. 5. In the Edit Host Participant panel, check the Active checkbox in the General tab. 6. In the Business Locations tab, click the Headquarters link. You must specify the following information in the Headquarters panel: Phone, Fax, Email, Primary Legal Contact, and Primary Support Contact in order to use TIBCO BusinessConnect cXML Protocol. 7. Specify the following fields: — Phone — Fax — Email 8. Assign a legal contact to the business location. a. In the Contacts panel, click the New button in the Contacts panel. The New Contact panel is displayed. b. Specify the name of the participant in the First Name and Last Name fields. c. Select the Legal item from the Contact Type drop-down list. d. Click the Save button to save the contact information. The Edit Business Location panel is displayed. e. Select the contact in the Primary Legal Contact drop-down list.
TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up Trading Hosts 39
|
9. Assign a support contact to the business location. a. In the Contacts panel, click the New button in the Contacts panel. b. Specify the name of the participant in the First Name and Last Name fields. c. Select the Support item from the Contact Type drop-down list. d. Click the Save button to save the contact information. The Edit Business Location panel is displayed. e. Select the contact in the Primary Support Contact drop-down list. 10. Click the Save button. 11. Continue with step 3 in Setting Up cXML Protocol for Trading Hosts on page 40. If you want to use digital signatures for document authentication, see TIBCO BusinessConnect Trading Partner Administration Guide for instructions on adding a private key for your trading host.
TIBCO BusinessConnect cXML Protocol User’s Guide
40
| Chapter 4
Setting Up Trading Hosts
Setting Up cXML Protocol for Trading Hosts Perform the following steps to setup cXML protocol for a trading host: 1. In TIBCO Administrator, click BusinessConnect > Participants in the left panel. 2. Click the name of a trading host in the right panel. 3. Click the Protocols tab. 4. Click the cXML link. The Edit Enabled Protocol panel is displayed. 5. If the cXML protocol is not enabled, perform the following steps to enable it: a. Click the Enable button in the Protocol tab. The Enable panel is displayed. b. Check the cXML checkbox and then click the OK button. The cXML protocol is displayed in the Protocol Name list of the Protocol tab. 6. In the General tab, set general properties. See Table 9 for a description of each property. 7. Click the Save button to save the changes. Table 9 Trading Host cXML General Properties Field
Description
Default Domain Identity
The default domain-identity credential to use for this host if your trading partner accepts only one credential. Select from the list of domain-identity pairs you created in the Domain Identities dialog. Go to Adding Domain Identities on page 42 to add or edit a domain identity.
Valid Email Address List
The identifier to use in the From header field of the SMTP MIME message. This email address list can be a list of email addresses. For an outbound document sent to the trading partner through SMTP transport, the first email address is used in the From header. For incoming email from the mail server, the To email address from the email is matched to one of the email addresses in this list.
URL
The complete URL by which this trading host is reachable. You must change its default value (CHANGE_ME) to the URL that you want to use for your trading host.
TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up cXML Protocol for Trading Hosts 41
|
Table 9 Trading Host cXML General Properties (Cont’d) Field
Description
Default cXML Version
The cXML version to use when a version is not specified by the private process. This version must have been installed in the Operations Editor (see Managing cXML Operations on page 27). Also, if the inbound request from a trading partner does not use a fully-qualified URL for its validation DTD, the version specified here is used.
PunchOutOrderMessage Reply URL
The URL that BusinessConnect uses to redirect the Web browser after receiving a PunchOutOrderMessage from the browser. See Configurable Reply to PunchOutOrderMessage on page 16 for more information.
ProfileResponse Settings Enable Accepting Attachments in OrderRequest
Indicates whether the trading host accepts attachments in OrderRequest documents. If selected, this option is included in a ProfileResponse.
Enable Accepting Change in OrderRequest
Indicates whether the trading host allows for changes or deletions of OrderRequests. If selected, this option is included in a ProfileResponse.
Enable Direct PunchOut
Indicates whether this host supports direct PunchOut operations, which are PunchOut operations in which clients are authenticated by the PunchOut-enabled sites directly instead of by a network commerce hub (such as ACSN). If selected, this option is included in a ProfileResponse.
Authentication Mode for Direct PunchOut
Specifies the method of authentication for direct PunchOut operations. This option is included in a ProfileResponse if the Enable Direct PunchOut checkbox is selected.
Direct PunchOut URL
The URL by which trading partners can connect to this host for direct PunchOut operations. This option is included in a ProfileResponse if the Enable Direct PunchOut checkbox is selected.
TIBCO BusinessConnect cXML Protocol User’s Guide
42
| Chapter 4
Setting Up Trading Hosts
Adding Domain Identities You can configure more than one domain-identity credential for your host participant. If you configure multiple credentials here, TIBCO BusinessConnect cXML Protocol will elect to send all credentials or only the default credential, based on how you configure your trading partner’s cXML protocol. For more information on sending multiple credentials to your trading partner, see Setting Up cXML Protocol for Trading Partners on page 46. Perform the following steps to add a domain-identity pair for the cXML protocol: 1. In TIBCO Administrator, click BusinessConnect > Participants in the left panel. 2. Click the name of a trading host in the right panel. The Edit Host Participant panel is displayed. 3. Click the Protocols tab and then click the cXML link. The Edit Enabled Protocol: cXML panel is displayed. 4. Click the Add New link next to the Default Domain Identity field. The Domain Identity List panel is displayed. 5. Click the Add New button. The New panel is displayed. 6. Select a domain from the Domain drop-down list. This is mapped to the identity domain in the host’s domain-identity pair. If the domain you wish to use does not exist, see Configuring Domains on page 35 for instructions on adding domains. 7. Type the identity for the local host in the Identity field. This is mapped to the identity in the host’s domain-identity pair. 8. Click the Save button in the New panel. 9. Click the OK button in the Domain Identity List panel. The Edit Enabled Protocol: cXML panel is displayed. 10. Select the domain identity you just created in the Default Domain Identity drop-down list. 11. Click the Save button to save the changes.
TIBCO BusinessConnect cXML Protocol User’s Guide
| 43 Chapter 5
Setting Up Trading Partners
This chapter describes setting up trading partners to use TIBCO BusinessConnect cXML Protocol.
Topics •
Setting Up Trading Partners, page 44
•
Setting Up cXML Protocol for Trading Partners, page 46
TIBCO BusinessConnect cXML Protocol User’s Guide
44
| Chapter 5
Setting Up Trading Partners
Setting Up Trading Partners Perform the following steps to set up a trading partner: 1. In TIBCO Administrator, click BusinessConnect > Participants in the left panel. 2. Click the New button in the right panel. The New Participant panel is displayed. 3. Specify a name in the Participant Name field. 4. Select the Partner item in the Participant Type drop-down list and then click the OK button to save the definition. The New Partner Participant panel is displayed. 5. Check the Active checkbox. 6. In the Business Locations tab, click the Headquarters link. You must specify the following information in the Headquarters panel in order to use TIBCO BusinessConnect cXML Protocol: Phone, Fax, Email, Primary Legal Contact, and Primary Support Contact. 7. Specify the following fields: — Phone — Fax — Email 8. Assign a legal contact to the business location. a. In the Contacts panel, click the New button in the Contacts panel. The New Contact panel is displayed. b. Specify the name of the participant in the First Name and Last Name fields. c. Select the Legal item from the Contact Type drop-down list. d. Click the Save button to save the contact information. The Edit Business Location panel is displayed. e. Select the contact in the Primary Legal Contact drop-down list.
TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up Trading Partners 45
|
9. Assign a support contact to the business location. a. In the Contacts panel, click the New button in the Contacts panel. b. Specify the name of the participant in the First Name and Last Name fields. c. Select the Support item from the Contact Type drop-down list. d. Click the Save button to save the contact information. The Edit Business Location panel is displayed. e. Select the contact in the Primary Support Contact drop-down list. 10. Click the Save button. 11. Continue with the instructions in Setting Up cXML Protocol for Trading Partners on page 46. If you want to use digital signatures for document authentication, see TIBCO BusinessConnect Trading Partner Administration Guide for instructions on adding a public certificate for your trading partner.
TIBCO BusinessConnect cXML Protocol User’s Guide
46
| Chapter 5
Setting Up Trading Partners
Setting Up cXML Protocol for Trading Partners TIBCO BusinessConnect cXML Protocol 6.0 no longer supports transactions with ACSN trading partners using the _ACSN configuration. You must manually configure each trading partner with ACSN parameters in order to carry out transactions with ACSN. Perform the following steps to setup cXML protocol for a trading partner: 1. In TIBCO Administrator, click BusinessConnect > Participants in the left panel. 2. Click the name of a trading partner in the right panel. The Edit Partner Participant panel is displayed. 3. Click the Protocols tab. 4. Click the cXML link. The Edit Enabled Protocol panel is displayed. 5. If the cXML protocol is not enabled, perform the following steps to enable it: a. Click the Enable button in the Protocol tab. The Enable panel is displayed. b. Check the cXML checkbox and then click the OK button. The cXML protocol is displayed in the Protocol Name list of the Protocol tab. 6. Select the trading partner’s domain identity in the Default Domain Identity drop-down list. If the list is empty, you must add a domain identity to the list by following the instructions in Adding Domain Identities on page 49. 7. Configure the remaining properties in the General tab. See Table 10 on page 47 for a description of each of the properties. If you want to carry out transactions with ACSN, use ACSN settings for the following information: — Domain identities — Authentication mode (including shared secret information)
TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up cXML Protocol for Trading Partners 47
|
8. Follow the instructions in Configuring Transports on page 50 to configure default transports for the trading partner. Table 10 Trading Partner cXML General Properties (Sheet 1 of 3) Field
Description
Default Domain Identity
The default domain identity to use for this partner. Select from the list of domain identities created in the Domain dialog. If you are using ACSN, choose ACSN’s domain identity. See Adding Domain Identities on page 49 to add or edit a domain identity.
Valid Email Address List
The identifier to use in the From header field of the SMTP MIME message. This email address list can be a list of email addresses. For an outbound document sent to the trading partner through SMTP transport, the first email address is used in the From header. For incoming email from the mail server, the To email address from the email is matched to one of the email addresses in this list.
Send Message with Multiple From Credentials
Indicates whether the partner server allows for incoming messages to contain multiple credentials in the From field.
Send Message with Multiple To Credentials
Indicates whether the partner server allows for incoming messages to contain multiple credentials in the To field.
Supplier Setup URL
Indicates the URL of the partner’s PunchOut website, if the partner is PunchOut-enabled.
URL-encoded PunchOutOrderMessage (Default is Base-64)
Indicates whether the partner’s encoding scheme for its PunchOutOrderMessage is URL-encoded. If this radio button is not selected, the partner’s encoding scheme is set to Base64 by default.
TIBCO BusinessConnect cXML Protocol User’s Guide
48
| Chapter 5
Setting Up Trading Partners
Table 10 Trading Partner cXML General Properties (Sheet 2 of 3) Field
Description
Authentication Mode
The method by which the host and the partner authenticate the documents sent by each other. If you are using ACSN, use ACSN’s document security settings. There are three available options: •
SharedSecret
•
MAC — This option allows the host and the partner to conceal shared secrets during document trasmission. For information on how MAC values are computed, see the cXML protocol specification. You must also specify the Secret Key value in the Partner Shared Secret Setting section and all properties in the Host Shared Secret Setting section.
•
DigitalSignature — The host and partner ensure document authentication by signing the documents and verifying the signatures in the documents.
— The host and partner authenticate documents by verifying the secret key included in the documents. You must also specify the rest of the properties in both the Partner Shared Secret Setting and the Host Shared Secret Setting sections.
Partner Shared Secret Setting Secret Key
The secret key of the partner. If you are using ACSN, specify ACSN’s secret key. If authentication mode is set to SharedSecret, upon receiving a document, the host verifies the shared secret in the document against the value here. If authentication mode is set to MAC, the host uses the value here when computing the MAC value for documents that it receives.
Creation Date
The creation date of the trading partner’s secret key. When the host computes MAC value of the partner, it does not use the creation date specified here. Instead, the host uses the value of CredentialMac.creationDate in the received document.
Expiration Date
The date of expiration of the trading partner’s secret key. When the host computes MAC value of the partner, it does not use the expiration date specified here. Instead, the host uses the value of CredentialMac.expirationDate in the received document.
TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up cXML Protocol for Trading Partners 49
|
Table 10 Trading Partner cXML General Properties (Sheet 3 of 3) Field
Description
Host Shared Secret Setting Secret Key
The secret key of the host that communicates with this trading partner. If you are using ACSN, specify the secret key that you registered with ACSN. If authentication mode is set to SharedSecret, the host uses the value here as the shared secret when sending documents to the partner. If authentication mode is set to MAC, the host uses the value here when computing the MAC value for documents that it sends.
Creation Date
The creation date of the host’s secret key. If authentication mode is set to MAC, the host uses the date here when computing the MAC value for documents that it sends to the partner.
Expiration Date
The date of expiration of the host’s secret key. If authentication mode is set to MAC, the host uses the date here when computing the MAC value for documents that it sends to the partner.
Adding Domain Identities Perform the following steps to add an identity domain and identifier for the trading partner’s cXML protocol: 1. In TIBCO Administrator, click BusinessConnect > Participants in the left panel. 2. Click the name of a trading partner in the right panel. The Edit Partner Participant panel is displayed. 3. In the Protocols tab, click the cXML link. The Edit Enabled Protocol: cXML panel is displayed. 4. In the General tab, click the Add New link next to the Default Domain Identity field. The Domain Identity List panel is displayed. 5. Click the Add New button. The New panel is displayed. 6. Select the Identity Domain from the Domain drop-down list. If you are using ACSN, select the NetworkId item.
TIBCO BusinessConnect cXML Protocol User’s Guide
50
| Chapter 5
Setting Up Trading Partners
7. Type the identifier of the trading partner in the Identity field. If you are using ACSN, enter AN-1000000001. 8. Click the Save button.
Configuring Transports To configure transport settings for the trading partner: 1. Perform the first three steps in Adding Domain Identities. 2. Click the Transport tab. 3. Click the Add button. The New Transport panel is displayed. 4. Specify a name for the transport in the Transport Name field. 5. Select a transport type in the Transport Type drop-down list. If you are using ACSN, select the HTTPS item. 6. Click the OK button. A more detailed configuration is displayed. 7. Specify the trading partner’s URL in the URL field. If you are using ACSN, type: certservice.ariba.com/service/transaction/cxml.asp.
8. (HTTPS only) Select a certificate in the Server Certificate drop-down list. 9. Configure the remaining properties based on your particular setup. For more information on these properties, see the chapter on HTTP, HTTPS, and HTTPSCA transports in TIBCO BusinessConnect Trading Partner Administration Guide. 10. Click the Save button to save the definition. If you configure multiple transports for a trading partner, you will be asked to select a transport setting when configuring a business agreement with this trading partner. See Configuring Transports on page 53.
TIBCO BusinessConnect cXML Protocol User’s Guide
| 51 Chapter 6
Configuring Business Agreements
This chapter describes setting up business agreements to use TIBCO BusinessConnect cXML Protocol.
Topics •
Configuring Business Agreements with cXML Protocol, page 52
•
Overriding Participant Settings, page 55
TIBCO BusinessConnect cXML Protocol User’s Guide
52
| Chapter 6
Configuring Business Agreements
Configuring Business Agreements with cXML Protocol Perform the following steps to configure a business agreement: 1. In TIBCO Administrator, click BusinessConnect > Business Agreements in the left panel. 2. Click the New button in the right panel. The New Agreement panel is displayed. 3. Select a host in the Host Party panel and a partner from the Partner Party panel. Make sure that both the host and the partner are configured with the cXML protocol. 4. Click the OK button. The New Agreement panel is displayed. 5. Check the Valid checkbox in the New Agreement panel. Optionally, specify a date range for which the agreement is valid. 6. Click the Add Protocol Bindings button. The Select Protocol panel is displayed. 7. Check the cXML checkbox and then click the OK button. The New Agreement panel is displayed. 8. Click the cXML link in the Protocol Bindings panel. 9. Configure the following three tabs in the Edit Protocol Binding: cXML panel: — Operational Bindings (see Adding Operational Bindings) — Document Security (see Configuring Document Security on page 53) — Transports (see Configuring Transports on page 53) 10. Click the Save button. The Edit Agreement panel is displayed. 11. Click the Save button to save the changes.
Adding Operational Bindings In the Operational Bindings tab of the Edit Protocol Binding: cXML panel, you can add operational bindings in two ways: •
Include all operations that are installed in the Operations Editor by simply checking the Allow All Operations checkbox.
•
Select individual operations that the host or the partner can initiate.
TIBCO BusinessConnect cXML Protocol User’s Guide
Configuring Business Agreements with cXML Protocol 53
|
Perform the following steps to add individual operation bindings to the host or the partner: 1. Click the Add Operation Bindings button in either the Host Name Can Initiate or the Partner Name Can Initiate panel, where Name is the name of your host or partner. The Select Operation panel is displayed. 2. Expand the cXML versions you want to use. 3. Select the operations you want to allow the host or the partner to initiate, respectively. 4. Click the OK button to save the changes.
Configuring Document Security If you use digital signatures for document security: 1. Click the Document Security tab in the Edit Protocol Binding: cXML panel. 2. Select a private key for the selected host in this business agreement in the Signing Key drop-down list. You must have already installed a private key for this host during trading host configuration. See TIBCO BusinessConnect Trading Partner Administration Guide for more information. 3. Make sure that the SHA1 item is selected in the Digest Algorithm drop-down list. TIBCO BusinessConnect cXML Protocol does not support the MD5 digest algorithm. 4. Select a public key for the selected partner in this business agreement in the Verification Certificate drop-down list. You must have already installed a certificate for this partner during trading partner configuration. TIBCO BusinessConnect cXML Protocol does not make use of the Encryption Info Setting sections because the cXML protocol does not specify document-level encryption. Use HTTPS if you want your transaction to be encrypted, since HTTPS provides transport-level encryption.
Configuring Transports Perform the following steps to configure the transport protocols for this business agreement: 1. Click the Transports tab in the Edit Protocol Binding: cXML panel.
TIBCO BusinessConnect cXML Protocol User’s Guide
54
| Chapter 6
Configuring Business Agreements
The Primary Transport drop-down list in the Outbound Transports for Host Name section includes all transports configured for the selected partner during trading partner configuration (see Configuring Transports on page 50), while the Allowed Inbound Transports for Partner Name section includes all transports configured for the BusinessConnect server of the selected host (see Setting Up Transports on page 32). The Name is the name of your host or partner. 2. Select an available transport for the select host in the Primary Transport drop-down list. 3. (HTTPSCA only) Select a private key to use for the selected host. In the Allowed Inbound Transports for Partner Name panel, select the transport protocols for the partner to use. The Name is the name of your host or partner. 4. (HTTPSCA only) Click the Edit Settings link next to the HTTPSCA checkbox to select a certificate for authenticating the selected partner.
TIBCO BusinessConnect cXML Protocol User’s Guide
Overriding Participant Settings 55
|
Overriding Participant Settings You can override all default participant settings when configuring business agreements with the cXML protocol: 1. In the Edit Protocol Binding: cXML panel, click the Show Advanced button in the upper-right-hand corner. To show the Edit Protocol Binding: cXML panel, follow the steps from step 1 to step 8 in Configuring Business Agreements with cXML Protocol on page 52. The configuration panel now contains two more tabs: HOST’s Configuration and PARTNER’s Configuration, where HOST and PARTNER are the names of the selected host and partner respectively. 2. Click the HOST’s Configuration tab. You can now see all the cXML protocol settings that you configured during trading host configuration (See Setting Up cXML Protocol for Trading Hosts on page 40). 3. Check the Override Settings checkbox. 4. Make the changes to the host’s cXML settings in the provided fields. See Table 9, Trading Host cXML General Properties, on page 40 for a description of each property. 5. Click the PARTNER’s Configuration tab. You can now see all the cXML protocol settings that you configured during trading partner configuration (See Setting Up cXML Protocol for Trading Partners on page 46). 6. Check the Override Settings checkbox. 7. Make the changes to the host’s cXML settings in the provided fields. See Table 10, Trading Partner cXML General Properties, on page 47 for a description of each property.
TIBCO BusinessConnect cXML Protocol User’s Guide
56
| Chapter 6
Configuring Business Agreements
TIBCO BusinessConnect cXML Protocol User’s Guide
| 57 Chapter 7
Private Processes
This chapter describes the interaction between TIBCO BusinessConnect cXML Protocol and its private processes and gives specifications for private process messages.
Topics •
Configuring Private Processes, page 58
•
Private Process Message Formats, page 60
•
Configuring Private Processes with TIBCO ActiveMatrix BusinessWorks, page 75
•
Using TIBCO BusinessConnect cXML Protocol with Marketplaces, page 78
TIBCO BusinessConnect cXML Protocol User’s Guide
58
| Chapter 7
Private Processes
Configuring Private Processes You can use the following two types of private processes to use TIBCO BusinessConnect cXML Protocol: •
Standalone Standalone private processes must use TIBCO Rendezvous or JMS to communicate with BusinessConnect.
•
TIBCO ActiveMatrix BusinessWorks TIBCO ActiveMatrix BusinessWorks processes can either send requests to a BusinessConnect server, or receive replies from a BusinessConnect server. For an example, see Chapter 10, Tutorial — TIBCO ActiveMatrix BusinessWorks Private Processes, on page 115.
Standalone Private Processes If you wish to design standalone private processes for use with TIBCO BusinessConnect cXML Protocol, you must use TIBCO Rendezvous or JMS for message exchange. TIBCO BusinessConnect cXML Protocol uses TIBCO ActiveExchange™ messages (aeRvMsg) to exchange cXML messages with private processes. See Private Process Message Formats, page 60 for formatting information of cXML messages.
TIBCO ActiveMatrix BusinessWorks Processes TIBCO BusinessConnect comes with TIBCO Designer palette for BusinessWorks processes, which encapsulates most of the message exchange configurations. The variety of BusinessWorks palettes also enables you to define elaborate private processes to suit the needs of your business transactions.
Setting Credentials from Private Processes The private process can specify credentials other than the default in its message by including the following fields:
ae/cXML/InitiatorRequest
•
hostId — When used with the hostDomain field, specifies the domain identity in the From credential. This field is ignored when used without the hostDomain field, and the default domain identity of the default host is used instead.
•
hostDomain — When used with the hostId field, specifies the trading host domain identity in the From credential. This domain must already be in the
TIBCO BusinessConnect cXML Protocol User’s Guide
Configuring Private Processes 59
|
configured trading host Domain - Identity pool. This field is ignored when used without the hostId field, and the default domain identity of the default host is used instead. •
tpDomain — Specifies which configured domain identity for the trading partner to use in the To credential. The domain given for tpDomain must already be in the configured trading partner Domian - Identity pool. If tpDomain does not exist in the Domain - Identity pool, it is ignored and the default domain identity is used.
See Outbound Request Format on page 61 for more information on messages and message fields.
InitiatorRequest
TIBCO BusinessConnect cXML Protocol User’s Guide
60
| Chapter 7
Private Processes
Private Process Message Formats TIBCO BusinessConnect cXML Protocol uses aeRvMsg messages to exchange cXML messages with private processes on TIBCO Rendezvous or JMS. This section describes the cXML-specific data classes that are used in the ^data^ field of aeRvMsg messages. You must format outbound messages and include all required information as prescribed by the respective data classes. For more information on the format of aeRvMsg messages, see TIBCO Adapter SDK Concepts. See one of the sections below for formatting details of each cXML message type: •
Outbound Request Format, page 61
•
Inbound Request Format, page 65
•
Outbound Response Format, page 68
•
Inbound Response Format, page 69
•
Error Message Format, page 70
Data Types and Data Fields This section also describes some specific data types and fields in detail: •
Complex Types, page 71
•
Request and Response Fields, page 73
TIBCO BusinessConnect cXML Protocol User’s Guide
Private Process Message Formats 61
|
Outbound Request Format The initiator private process uses this class to handle outbound requests. Initiator Request
Initiator Private Process
Responder Private Process
Internet BC Initiator
BC Responder
The message has the following subject name and message field elements: Class Subject name
ae/cXML/InitiatorRequest
prefix.installation.cXML.INITIATOR.REQUEST
Example: Message fields
AX.BC.ACME.cXML.INITIATOR.REQUEST
See Table 11.
Table 11 ae/cXML/InitiatorRequest Fields (Sheet 1 of 4) Message Field
Type
Required
Description
standardID
String
Yes
The string "cXML".
transaction ID
String
Yes
A unique ID for the transaction. TIBCO BusinessConnect cXML Protocol does not enforce nor verify the uniqueness of transactionID.
operationID
String
Yes
The cXML version and the operation name in the following format: version/operationName. For example: 1.2.016/ProfileRequest. If version is not specified, TIBCO BusinessConnect cXML Protocol uses the default cXML version specified in the trading host’s cXML protocol configuration panel (see Setting Up cXML Protocol for Trading Hosts on page 40).
TIBCO BusinessConnect cXML Protocol User’s Guide
62
| Chapter 7
Private Processes
Table 11 ae/cXML/InitiatorRequest Fields (Sheet 2 of 4) Message Field
Type
Required
Description
tpName
String
No
The name by which the trading partner identifies itself and as configured in TIBCO BusinessConnect cXML Protocol. This field takes precedence over the field when both fields are used.
tpNameList
tpDomain
Sequence of Trading Partner
No
String
No
tpNameList
A list of trading partner names. This field is not fully utilized in TIBCO BusinessConnect cXML Protocol. If multiple names are found in tpNameList, only the first name in the list is used. Also, tpName takes precedence over this field. The identity domain you wish to use for the trading partner. Specify if you do not wish to use the default domain-identity pair configured in the Domain Identity pool of the trading partner. If a domain is specified here, BusinessConnect uses the credential with a matching domain in the trading partner’s Domain - Identity pool. If BusinessConnect cannot find a credential with a matching domain, it uses the partner’s default domain-identity pair. This field is disregarded if TIBCO BusinessConnect cXML Protocol is using multiple credentials in the cXML element, since all credentials in the trading partner’s Domain - Identity pool are sent.
TIBCO BusinessConnect cXML Protocol User’s Guide
Private Process Message Formats 63
|
Table 11 ae/cXML/InitiatorRequest Fields (Sheet 3 of 4) Message Field
Type
Required
Description
hostDomain
String
No
The identity domain you wish to use for the trading host. Specify hostDomain and hostId in the following situations: •
You wish to use a different trading host credential instead of the default domain-identity pair configured in the Domain - Identity pool.
•
There are multiple business agreements with the intended trading partner from several (different) trading hosts.
•
The marketplace field is set to description for martketplace).
true
(see the
If both hostDomain and hostId are specified, BusinessConnect searches for a matching credential in the trading hosts’s Domain - Identity pool. If TIBCO BusinessConnect cXML Protocol cannot find a matching credential, it terminates the operation with an error message. If only one of hostDomain and hostId is specified, TIBCO BusinessConnect cXML Protocol uses the default domain-identity pair of the default host. This field is disregarded if TIBCO BusinessConnect cXML Protocol is using multiple credentials in the cXML element, since all credentials in the trading partner’s Domain - Identity pool are sent. hostId
String
No
The ID you wish to use for the trading host. See the description for hostDomain.
TIBCO BusinessConnect cXML Protocol User’s Guide
64
| Chapter 7
Private Processes
Table 11 ae/cXML/InitiatorRequest Fields (Sheet 4 of 4) Message Field
Type
Required
Description
marketplace
String
No
Specifies whether to use BusinessConnect as a marketplace (true or false). If it is set to true, BusinessConnect sends the default host’s credential with the type="marketplace" attribute. See Using TIBCO BusinessConnect cXML Protocol with Marketplaces on page 78 for more information. You must specify both hostId and hostDomain when setting the value here to true. Otherwise, TIBCO BusinessConnect cXML Protocol sends an error to the private process.
request
String
No
A cXML or element, depending on whether the message is a request or notify message. For information on how they are formatted, see Request and Response Fields on page 73.
closure
String
Yes
A unique identifier used between the private process and BusinessConnect to match up the request and response documents in a transaction. The response to this request or notify message from BusinessConnect will contain the same ID in the closure field. Note that TIBCO BusinessConnect cXML Protocol does not enforce nor verify the uniqueness of message closures.
postURL
String
No
The URL you wish to use to post this request. Specify if you do not wish to use the trading partner’s default cXML URL.
attachment
Sequence of Attachments
No
A sequence of attachments. The class definition name for this date type is ae/BC/Attachment. See Attachment Type on page 72.
TIBCO BusinessConnect cXML Protocol User’s Guide
Private Process Message Formats 65
|
Inbound Request Format The responder private process uses this class to handle inbound requests. Initiator Private Process
Responder request
Internet
BC Initiator
Responder Private Process
BC Responder
The message has the following subject name and message field elements: Class Subject name
ae/cXML/ResponderRequest
prefix.installation.cXML.RESPONDER.REQUEST
Example: AX.BC.ACME.cXML.RESPONDER.REQUEST Message fields
See Table 12.
Table 12 ae/cXML/ResponderRequest Fields (Sheet 1 of 3) Message Field
Type
Required
Description
standardID
String
Yes
The string "cXML".
sourceTP
Trading Partner
Yes
The sender credential information that is contained in the element of the inbound cXML request or notify message. See TradingPartner Type on page 73.
destination TP
Sequence of Trading Partner
Yes
The credential information that is contained in the element of the inbound cXML request or notify message. There may be one or more credentials.
fromTP
Sequence of Trading Partner
Yes
The credential information in the element of the inbound cXML request or notify message. There may be one or more credentials.
TIBCO BusinessConnect cXML Protocol User’s Guide
66
| Chapter 7
Private Processes
Table 12 ae/cXML/ResponderRequest Fields (Sheet 2 of 3) Message Field
Type
Required
Description
header
String
No
A well-formed XML document that contains the cXML header of the inbound request. It is formatted as follows:
Which header elements are included depends on which of the following properties are selected in BusinessConnect > System Settings > Activated Protocol Plug-ins and Properties > cXML: cXML.Header.* — all credentials in the inbound request are included. cXML.Header.From — The entire element in the inbound request is included. cXML.Header.To — The entire element in the inbound request is included.
— The entire element in the inbound request is included. cXML.Header.Sender
marketplace
Sequence of Trading Partner
No
The credential in the element of the inbound cXML request or notify message which contains the type="marketplace" attribute.
operationID
String
Yes
The cXML version and the operation name in the following format: version/operationName. For example: 1.2.016/ProfileRequest.
operation Name
String
Yes
cXML transaction name (OrderRequest for example).
operation Type
String
Yes
The string "notify" or "syncRequestResponse".
transaction ID
String
Yes
The unique ID of this transaction.
TIBCO BusinessConnect cXML Protocol User’s Guide
Private Process Message Formats 67
|
Table 12 ae/cXML/ResponderRequest Fields (Sheet 3 of 3) Message Field
Type
Required
Description
request
String
No
The or element of the inbound cXML document, depending on whether the message is a request or notify message. For information on how they are formatted, see Request and Response Fields on page 73.
duplicate
String
Yes
Indicates a possible duplicate message. If BusinessConnect detects an incoming message with a payloadID that appeared in the public message, the value here is set to "true".
closure
String
Yes
A unique identifier used between the private process and BusinessConnect to match up the request and response documents in a transaction. The private process must include the value provided here in the closure field of the ae/cXML/ResponderResponse message when sending a response to BusinessConnect.
attachment
Sequence of Attachments
No
A sequence of attachments. The class definition name for this date type is ae/BC/Attachment. See Attachment Type on page 72.
TIBCO BusinessConnect cXML Protocol User’s Guide
68
| Chapter 7
Private Processes
Outbound Response Format The responder private process uses this class to handle outbound responses.
Initiator Private Process
Internet
BC Initiator
Responder response
Responder Private Process
BC Responder
The message has the following subject name and message field elements: Class Subject name
ae/cXML/ResponderResponse
prefix.installation.cXML.RESPONDER.RESPONSE
Example: AX.BC.ACME.cXML.RESPONDER.RESPONSE Message fields
See Table 13
Table 13 ae/cXML/ResponderResponse Fields Message Field
Type
Required
Description
standardID
String
Yes
The string "cXML".
statusCode
Integer
Yes
A code to indicate the status of the transaction. It must be 200 for success or a private process-defined error code ranging from 1000 to 1999. See Status Codes on page 127.
statusMsg
String
Yes
A description of the statusCode. The standard success message is OK. If statusCode is a private process-defined error code, then include a description of the error here.
response
String
No
A cXML element. See Request and Response Fields on page 73 for formatting information.
TIBCO BusinessConnect cXML Protocol User’s Guide
Private Process Message Formats 69
|
Table 13 ae/cXML/ResponderResponse Fields (Cont’d) Message Field
Type
Required
Description
closure
String
Yes
A unique identifier used between the private process and BusinessConnect to match up the request and response documents in a transaction. The private process must copy the value from the closure field of the inbound ae/cXML/ResponderRequest message that it received from BusinessConnect.
payloadID
String
No
The payload ID that BusinessConnect uses to send the response. If payloadID is not specified, BusinessConnect generates one automatically.
Inbound Response Format The initiator private process uses this class to handle inbound responses. Initiator Private Process
Responder Private Process
Internet Initiator Response
BC Initiator
BC Responder
The message has the following subject name and message field elements: Class Subject name
ae/cXML/InitiatorResponse
prefix.installation.cXML.INITIATOR.RESPONSE
Example: AX.BC.ACME.cXML.INITIATOR.RESPONSE Message fields
See Table 14
Table 14 ae/cXML/InitiatorResponse Fields Message Field
Type
Required
Description
standardID
String
Yes
The string "cXML".
TIBCO BusinessConnect cXML Protocol User’s Guide
70
| Chapter 7
Private Processes
Table 14 ae/cXML/InitiatorResponse Fields (Cont’d) Message Field
Type
Required
Description
statusCode
Integer
Yes
A code to indicate the status of the transaction beginning with the numeral 2 (2XX). See Status Codes on page 127.
statusMsg
String
Yes
A description of
operationID
String
Yes
The cXML version and the name of the request or notify operation for which the response is sent, in the following format: version/operationName. For example: 1.2.016/ProfileRequest.
operationName
String
Yes
The name of the request or notify operation for which the response is sent.
transactionID
String
Yes
The ID of the transaction. transactionID is unique for the entire transaction.
response
String
No
The cXML element. See Request and Response Fields on page 73 for formatting information.
closure
String
Yes
A unique identifier used between the private process and BusinessConnect to match up the request and response documents in a transaction. The value here is the same value provided in the closure field of the outbound ae/cXML/InitiatorRequest message.
duplicate
String
No
Specify "true" if BusinessConnect detects that the response document from the trading partner contains a payloadID identical to that of a previously received response.
statusCode.
Error Message Format An error message has the following subject name and message fields elements: Class Subject name
ae/cXML/ErrorNotify
prefix.installation.cXML.ERROR
Example: AX.BC.ACME.cXML.ERROR
TIBCO BusinessConnect cXML Protocol User’s Guide
Private Process Message Formats 71
|
Message fields
See Table 15
Table 15 ae/cXML/ErrorNotify Fields Message Field
Type
Required
Description
standardID
String
Yes
The string "cXML".
statusCode
Integer
Yes
An error code. Error codes can be 4XX, 1XXX. See Status Codes on page 127.
statusMsg
String
Yes
The description of the error code in
details
String
No
A detailed description of the error. This can be an analysis of the problem.
operationID
String
No
The cXML version and the name of the request or notify operation to which the error relates, in the following format: version/operationName. For example: 1.2.016/ProfileRequest.
transactionID
String
No
The ID of the transaction from which the error originates.
trading Partner
Trading Partner
No
The trading partner’s participant information.
host
Trading Partner
No
The trading host’s participant information.
closure
String
No
The value here depends on the situation:
extrainfo
Any
No
5XX,
or
statusCode.
•
If the error message is related to an outbound request, the value is identical to that of the ae/cXML/InitiatorRequest message.
•
If the error message is related to an outbound response, the value is identical to that of the ae/cXML/ResponderResponse message. It may be null.
N/A
Complex Types This section explains the two complex types used in the private process message fields.
TIBCO BusinessConnect cXML Protocol User’s Guide
72
| Chapter 7
Private Processes
Attachment Type and ae/cXML/ResponderRequest both contain an field, which can contain a list of attachments. This section describes the data structure of each attachment.
ae/cXML/InitiatorRequest attachments
Class Message fields
ae/BC/Attachment
See Table 16.
Table 16 ae/BC/Attachment Fields Message Field
Type
Required
Description
content-type
String
Yes
The content type of this attachment. (image/jpeg and image/gif for example).
content-id
String
Yes
The identifier for this attachment.
content
Binary
No
The entire attachment data. If you wish to send a file as the attachment, you may wish to use the fileReference field instead. fileReference takes precedence over this field when both fields hold values. Furthermore, fileReference is always used instead of this field in an ae/cXML/ResponderRequest.
name
String
No
The name of the attachment. If a name is not provided here, TIBCO BusinessConnect cXML Protocol automatically generates to be attachmentindex.content-type, where index is the enumeration of the attachment and content-type is the value of the content-type field. For example: attachment2.jpeg.
fileReference
String
No
The absolute path to the file you wish to send as the attachment. This field takes precedence over the content field when both fields hold values. Also, This field is always used in an ae/cXML/ResponderRequest from BusinessConnect. See Configuring Message Attachment Directory on page 34 for more information on how to configure the directory path for TIBCO BusinessConnect cXML Protocol to store message attachments.
TIBCO BusinessConnect cXML Protocol User’s Guide
Private Process Message Formats 73
|
TradingPartner Type TIBCO BusinessConnect cXML Protocol uses this data type to encapsulate trading participant information wherever applicable. Class Message fields
ae/BC/TradinPartner
See Table 17.
Table 17 ae/BC/TradingPartner Fields Message Field
Type
Required
Description
name
String
No
The name of the trading participant.
domain
String
No
The identity domain of the trading participant.
id
String
No
The identity of the trading participant.
locationID
String
No
N/A
type
String
No
N/A
Request and Response Fields This section describes and illustrates how the request and response fields are formatted in TIBCO Rendezvous or JMS messages. Note that the content of these fields is actually a well-formed XML document. TIBCO BusinessConnect cXML Protocol is able to handle messages that are missing the XML header in the request and response fields. Request Document Format In a request-response operation, the ae/cXML/InitiatorRequest or ae/cXML/ResponderRequest message contains a cXML element in the request field. For example: 1CX3L4843PPZO 610 https://aribaorms:26000/punchout.asp http://www.workchairs.com/punchout.asp
TIBCO BusinessConnect cXML Protocol User’s Guide
74
| Chapter 7
Private Processes
…
Response Document Format In a request-response operation, the ae/cXML/ResponderResponse or ae/cXML/InitiatorResponse message contains a cXML element in the response field. In a response message such as ProfileResponse, the response field of the Initiator Response and Responder Response messages should contain something like: http://workchairs.com/cgi/orders.cgi …
Notify Document Format In a notify operation, the
ae/cXML/InitiatorRequest
message contains a cXML field. For example:
ae/cXML/ResponderRequest
the
request
or
1CX3L4843PPZO 763.20 5555 E000028901 …
TIBCO BusinessConnect cXML Protocol User’s Guide
element in
Configuring Private Processes with TIBCO ActiveMatrix BusinessWorks 75
|
Configuring Private Processes with TIBCO ActiveMatrix BusinessWorks To define a BusinessWorks private process to interact with BusinessConnect requires the following resources: •
BusinessConnect Connection (BCServerConfig) — a shared resource that connects to the BusinessConnect configuration store for message exchange.
•
Activities to handle outbound and inbound BusinessConnect messages.
Configuring BCServerConfig Resource To set communications between private processes and the BusinessConnect server, you must include BCServerConfig resource in the root project. Perform the following steps to configure a BCServerConfig resource: 1. In TIBCO Designer, open a BusinessWorks project. 2. Select Palettes > Browse.... in the menu. The Palette Browser dialog is displayed. 3. Check the BusinessConnect checkbox under the BusinessConnect folder to make the BusinessConnect palette available. 4. Click the Close button. 5. In the Project panel, click the root project directory of your BusinessWorks project. 6. Drag the BusinessConnect Connection icon from the Palettes panel to the Design panel. The resource with the name, BCServerConfig, is displayed in the Design panel. You can change its name in the configuration panel. 7. Click the BusinessConnect Server Access tab in the Configuration panel. 8. Select a type of JDBC driver you use to communicate with the BusinessConnect configuration store in the JDBC Driver Type drop-down list. The settings in step 8, step 9, and step 10 should be the same as the settings in your BusinessConnect installation. To see the JDBC settings in your BusinessConnect installation, log into TIBCO Administrator and go to BusinessConnect > System Settings > Audit, Non-Repudiation and Runtime Database Configuration and then select the bc-db link.
TIBCO BusinessConnect cXML Protocol User’s Guide
76
| Chapter 7
Private Processes
9. Type the URL for the BusinessConnect configuration store in the JDBC URL field. 10. Type the configuration store user name and password in the DB User and DB Password fields. 11. Click the Apply button. 12. Click the Configuration tab. Make sure the Update Transport Settings checkbox is checked. By default, the resource synchronizes its TIBCO Rendezvous or JMS settings with the settings in the BusinessConnect configuration store. 13. Click the Update from Configuration Store button. 14. Select the cXML item from the Protocol Name drop-down list. 15. Click the Import Selected Business Protocol button. TIBCO Designer now retrieves all installed operations in the BusinessConnect configuration store and places them in the BCSchemas project folder in the form of schemas. Do not move, modify, nor delete the BCSchemas folder or the contents therein.
16. Click the Apply button. For more information on the BusinessConnect Connection (BCServerConfig) resource, see TIBCO BusinessConnect Palette Reference.
Configuring Send and Receive Activities There are three BusinessConnect Send activities for sending requests (or notifications), responses and miscellaneous messages. There are also three BusinessConnect three receive activities for receiving requests (or notifications), responses, and miscellaneous messages. When configuring a Send activity, you must ensure that all required fields must be supplied to the activity before the Send activity can be executed. When a Send activity is executed, the resource sends a request of the selected operation to BusinessConnect. Unlike Send activities, Receive activities are process starters. Therefore there can be only one Receive activity in a process definition and the Receive activity acts to start the process. A process definition with a Receive start activity is started when BusinessConnect receives a message from a trading partner and sends it to BusinessWorks. You can configure the process definition to use the output of the Receive activity to perform different tasks, such as formulating a response message and invoke a Send activity. TIBCO BusinessConnect cXML Protocol User’s Guide
Configuring Private Processes with TIBCO ActiveMatrix BusinessWorks 77
|
For more information on configuring each of the Send and Receive activities, see TIBCO BusinessConnect Palette Reference. You may also step through the tutorial in Chapter 10, Tutorial — TIBCO ActiveMatrix BusinessWorks Private Processes, on page 115 to learn how to configure a BusinessWorks project to send and receive cXML messages. The following sub-sections give you a quick glance at the resources you need to configure different kinds of private processes. Configuring Initiators In order for your BusinessWorks processes to initiate request-response or notify operations (send request or notify messages), you need the following resources: •
BCServerConfig—for connecting to your BusinessConnect server.
•
Send Request/Notification—for sending request or notify messages to BusinessConnect.
•
Receive Response (request-response only)—for receiving responses from BusinessConnect.
•
Receive Misc. Msg—for receiving any error messages from BusinessConnect.
Configuring Responders In order for your BusinessWorks processes to receive request messages, you need the following resources: •
BCServerConfig—for connecting to your BusinessConnect server.
•
Receive Request/Notification—for receiving request or notify messages from BusinessConnect.
•
Send Response—for sending responses to BusinessConnect.
•
Send Misc. Msg—for sending any error messages to BusinessConnect.
•
Receive Misc. Msg—for receiving any error messages from BusinessConnect.
Configuring Notification Receivers In order for your BusinessWorks processes to receive request messages, you need the following resources: •
BCServerConfig—for connecting to your BusinessConnect server.
•
Receive Request/Notification—for receiving request or notify messages from BusinessConnect.
•
Send Misc. Msg—for sending any error messages to BusinessConnect.
TIBCO BusinessConnect cXML Protocol User’s Guide
78
| Chapter 7
Private Processes
Using TIBCO BusinessConnect cXML Protocol with Marketplaces This section describes how to use BusinessConnect as a cXML marketplace. It also describes how TIBCO BusinessConnect cXML Protocol processes messages from a cXML marketplace. There are some differences between communicating with ACSN and with a marketplace (AMNE for example). The major difference is in how they deal with their own credentials in the cXML header. When ACSN forwards a message, it does so without affecting the and credentials. However, when a marketplace forwards a message, it adds its own credential to the credentials. Likewise, when a trading participant sends a message via a marketplace, it must include the credential of the marketplace in the credentials. For example, the element in a message sent from an AMNE marketplace request looks as follows:
111111111 AN01000010452-T
The type="marketplace" attribute in the second credential indicates that the credential belongs to a marketplace.
Using BusinessConnect as cXML Marketplace A private process can specify in its ae/cXML/InitiatorRequest message that it wishes to use BusinessConnect as a marketplace. The private process must specify the following fields: •
marketplace — set the value to true. BusinessConnect will insert the default domain-identity credential of the default host into the credential of the cXML header, along with the type="marketplace" attribute. It will also insert the same credential into the credential along with document security information.
•
hostDomain
— specify the identity domain of the trading host in the credential of the cXML header.
TIBCO BusinessConnect cXML Protocol User’s Guide
Using TIBCO BusinessConnect cXML Protocol with Marketplaces 79
|
•
hostId — specify the the identity of the trading host in the
credential
of the cXML header. If either the hostDomain or hostId is missing with the marketplace field set to true, BusinessConnect returns an error to the private process. Thus the final cXML header in BusinessConnect’s outbound message is generated in the following format: PrivateProcess hostID Default-Host ID partnerID Default-Host hostID
Receiving Messages from BusinessConnect Marketplace If a trading partner is sending a request or notification to your BusinessConnect server as to a marketplace, it places your default host’s credential in the credentials. For example: 111111111 AN01000010452-T
When setting up BusinessConnect as a marketplace, make sure that the BusinessConnect server authenticates the marketplace credential regardless of the other credentials (NetworkID-AN01000010452-T in the example above). In other words, set the cxml.credentialcheck.to property to any. See Appendix B, Property Reference, on page 129 for more information on this property.
TIBCO BusinessConnect cXML Protocol User’s Guide
80
| Chapter 7
Private Processes
TIBCO BusinessConnect cXML Protocol User’s Guide
| 81 Chapter 8
Viewing Logs
This chapter discusses how to view audit, non-repudiation, and resend logs after conducting business transactions.
Topics •
Overview, page 82
•
Audit Log, page 83
•
Non-Repudiation Log, page 86
•
Resend Log, page 87
•
State Field Values, page 88
TIBCO BusinessConnect cXML Protocol User’s Guide
82
| Chapter 8
Viewing Logs
Overview TIBCO BusinessConnect provides three logs that track which messages have been processed: •
Audit log
•
Non-repudiation log
•
Resend log
The audit log is used to store information about the cXML transactions and documents processed by BusinessConnect. Using the audit log, one can follow the processing states of inbound or outbound documents. See Audit Log on page 83 for more information. The non-repudiation log is used to provide proof of the delivery of messages and message content. It is a persistent record of all successfully-completed cXML transactions. Non-repudiation depends on authentication using digital signatures. Transactions that involve digitally-signed messages are stored in the non-repudiation database. This protects against any attempts by a party to subsequently revoke the occurrence or the content of the transaction. See Non-Repudiation Log on page 86 for more information. The resend log displays the audit log transactions that are eligible to be resent. See Resend Log on page 87 for more information.
Viewing Logs Perform the following steps to access the log viewer: 1. In TIBCO Administrator, click BusinessConnect > Log Viewer in the left panel. 2. Click a link in the right panel to select which log to view: — Audit Logs to display the audit log search options. — Non-Repudiation Logs to display the non-repudiation log search options. — Resend Logs to display the resend log search options. 3. Select the cXML radio button in the Protocol drop-down list. For information on searching the logs, see TIBCO BusinessConnect Trading Partner Administration Guide.
TIBCO BusinessConnect cXML Protocol User’s Guide
Audit Log 83
|
Audit Log The audit log for cXML protocol is used to store information about the messages and documents processed by TIBCO BusinessConnect cXML Protocol. You can use the audit log to follow the processing states of inbound or outbound documents. This section describes the metadata in the audit log.
Summary View Table 18 lists the columns that appear in the audit log. Table 18 Audit Log Columns Column Name
Definition
Time Stamp
The time when the message was processed.
Start Time
The time when the transaction was initiated.
Operation ID
The version/operation name of the cXML operation.
Payload Id
The value of the payloadID attribute in the cXML document. This is a unique number with respect to space and time.
Host Initiates
Whether the host initiated the operation.
Trading Partner
The name of the trading partner.
TIBCO BusinessConnect cXML Protocol User’s Guide
84
| Chapter 8
Viewing Logs
Transaction Details View To view the details of a transaction, click the document icon column of an audit log entry.
in the left-most
The Log Viewer displays the general information for the transaction at the top and a table with information for each event at the bottom. The table columns are listed in Table 19. Table 19 Transaction Detail Columns Column
Definition
Time Stamp
Time that the transaction passed through the state displayed in the State column.
Status
Indicates whether the transaction is completed. Possible values are and ERROR.
PENDING, COMPLETED
State
The state code that represents the current state.
Description
A description of the state code.
Responder Response Payload Id
The value of the payloadID attribute in the cXML response.
Protocol Version
The cXML version used in this operation.
State Details View To view the details of a specific state, click the document icon in the left-most column of a state detail entry. See Table 20 for a description of each metadata in the state details view. Table 20 State Details View Column
Definition
Time Stamp
Time that the transaction passed through the state displayed in the State column.
Operation ID
The version/operation name of the cXML operation.
Payload Id
The value of the payloadID attribute in the cXML document. This is a unique number with respect to space and time.
Status
Indicates whether the transaction is completed. Possible values are and COMPLETED.
PENDING
TIBCO BusinessConnect cXML Protocol User’s Guide
Audit Log 85
|
Table 20 State Details View (Cont’d) Column
Definition
State
The state code that represents the current state.
Description
A description of the state code.
Host Initiates
Whether the host initiated the operation.
Trading Partner
The name of the trading partner.
Responder Response Payload Id
The value of the payloadID attribute in the cXML response.
Protocol Version
The cXML version used in this operation.
TIBCO BusinessConnect cXML Protocol User’s Guide
86
| Chapter 8
Viewing Logs
Non-Repudiation Log Transactions involving digitally-signed messages are stored in the non-repudiation database. The non-repudiation log displays some of the information stored in the non-repudiation database. Note that not all information is displayed. For example, digital signatures are stored but not displayed. In contrast to the audit information, non-repudiation information is intended for long-term storage. Therefore there is only one entry per transaction to minimize storage space. Table 21 gives a description of each column in the non-repudiation log. Table 21 Non-Repudiation Log Columns Field
Definition
Time Stamp
Time this non-repudiation log entry was entered.
Request Payload ID
A payload identifier generated by BusinessConnect.
Operation ID
The version/operation name of the cXML operation.
Trading Partner
The trading partner name.
Protocol Name
The string "cXML".
TIBCO BusinessConnect cXML Protocol User’s Guide
Resend Log 87
|
Resend Log Table 22 gives a description of each column in the resend log. Table 22 Resend Log Columns Column
Definition
Time Stamp
The time when the message was processed.
Start Time
The time when the transaction was initiated.
Trading Partner
The trading partner name.
Operation ID
The version/operation name of the cXML operation.
Host Initiates
Indicates whether the host participant initiated the transaction.
State
The state of the operation. See State Field Values on page 88 for all possible states.
Description
A more verbose description of the state listed in the State column.
Payload ID Protocol Version Status
TIBCO BusinessConnect cXML Protocol User’s Guide
88
| Chapter 8
Viewing Logs
State Field Values The following is a list of the state field values: Table 23 Audit Log States State
Description
RECEIVED-PP-REQUEST
Received request from private process
RECEIVED-PP-RESPONSE
Received response from private process
RECEIVED-TP-REQUEST
Received request from trading partner.
RECEIVED-TP-RESPONSE
Received response from trading partner.
RECEIVED-TP-EXCEPTION
Received error message from trading partner.
PKGD-PP-REQUEST
Packaged request to private process.
PKGD-PP-RESPONSE
Packaged response to private process.
PKGD-TP-REQUEST
Packaged request to trading partner.
PKGD-TP-RESPONSE
Packaged response to trading partner.
PKGD-TP-EXCEPTION
Packaged error response to trading partner.
SENT-PP-REQUEST
Send request to private process
SENT-PP-RESPONSE
Sent response to private process.
SENT-TP-REQUEST
Sent request to trading partner.
SENT-TP-RESPONSE
Sent response to trading partner.
SENT-TP-EXCEPTION
Sent error message to trading partner.
TRANSACTION-COMPLETE
Transaction completed successfully.
TIBCO BusinessConnect cXML Protocol User’s Guide
State Field Values 89
|
If an error occurred, one of the following states is shown: Table 24 Error States State
Description
MESSAGE-ERROR
Error in incoming message service header.
TRANSACTION-TERMINATED
The transaction is terminated with an error code.
TIBCO BusinessConnect cXML Protocol User’s Guide
90
| Chapter 8
Viewing Logs
TIBCO BusinessConnect cXML Protocol User’s Guide
| 91 Chapter 9
Tutorial — Standalone Private Processes
This tutorial guides you through the steps necessary for performing a TIBCO BusinessConnect cXML Protocol operation. The example in this chapter uses standalone private processes that can be executed directly from the command prompt.
Topics •
Overview, page 92
•
Setting Up Buyer on Machine 1, page 95
•
Setting Up Seller on Machine 2, page 103
•
Running the Tutorial Example, page 111
TIBCO BusinessConnect cXML Protocol User’s Guide
92
| Chapter 9
Tutorial — Standalone Private Processes
Overview This tutorial demonstrates the entire process of configuring TIBCO BusinessConnect cXML Protocol to perform cXML operations, as well as sending and receiving cXML documents with private processes. In this tutorial you will use two machines, each acts as a BusinessConnect server. You are going to simulate a PunchOutSetupRequest operation between a buyer and a seller: the buyer sends PunchOutSetupRequest to the seller; the seller responds to the buyer with PunchOutSetupResponse. The following figure describes the flow of events. 2. TIBCO BusinessConnect
TIBCO BusinessConnect
Request
5. Response 1.
6. Request
Response
4.
3.
Response
Request
Initiator Private Process
Responder Private Process
Machine 1
Machine 2
1. A private process on Machine 1 (the initiator) sends a PunchOutSetupRequest document to its BusinessConnect server. 2. The initiator BusinessConnect server packages and sends the PunchOutSetupRequest document to the responder, which is configured as a trading partner. 3. The responder’s BusinessConnect server receives the inbound PunchOutSetupRequest, repackages it and forwards it to its private process.
TIBCO BusinessConnect cXML Protocol User’s Guide
Overview 93
|
4. The responder private process receives the PunchOutSetupRequest document, then responds by sending a PunchOutSetupResponse document to its BusinessConnect server. 5. The responder’s BusinessConnect server packages the PunchOutSetupResponse document and sends it to the initiator over the same transport channel. 6. The initiator’s BusinessConnect server forwards the PunchOutSetupResponse document to the private process. The tutorial does not simulate the actual punch-out shopping experience. In the real-life scenario, the seller will eventually send PunchOutOrderMessage to the buyer. The buyer will then initiate an OrderRequest operation to perform an actual purchase, followed by the seller’s DefaultResponse back to the buyer.
Prerequisites Before starting the tutorial, make sure you have performed the following tasks on both of the machines you will use: •
Installed TIBCO BusinessConnect
•
Installed TIBCO BusinessConnect cXML Protocol
•
Created deployment configuration for BusinessConnect. See TIBCO BusinessConnect Installation, Migration, and Deployment Guide for instructions.
•
Obtain access to the following directories: TIBCO_HOME/BC/version/protocols/cxml/samples/src TIBCO_HOME/BC/version/protocols/cxml/samples/Transactions
Participant Information This tutorial is based on a buyer and a seller. Table 25 Participant Information Buyer
Seller
Trading Partner Name
company1
company2
Key identity file
company1_key.p12
company2_key.p12
(HTTPS only)
(HTTPS only)
TIBCO BusinessConnect cXML Protocol User’s Guide
94
| Chapter 9
Tutorial — Standalone Private Processes
Table 25 Participant Information (Cont’d) Buyer Certificates file
Seller
company1_cert.p7b
company2_cert.p7b
(HTTPS only)
(HTTPS only)
Private process executables
ppinitiator.exe
ppresponder.exe
Message
PunchOutSetupRequest
ppinitiator
TIBCO BusinessConnect cXML Protocol User’s Guide
(UNIX)
ppresponder
(UNIX)
PunchOutSetupResponse
Setting Up Buyer on Machine 1 95
|
Setting Up Buyer on Machine 1 This section gives the instructions for setting up a trading participant on Machine 1, which will act as the buyer in the transaction. The following is a general sketch of the tasks: •
Task A, Installing cXML Operations, page 95
•
Task B, Configuring Server Transport, page 95
•
Task C, Configuring a New Domain, page 96
•
Task D, Configuring Trading Host (Buyer), page 97
•
Task E, Setting Up Seller as Trading Partner, page 99
•
Task F, Configuring Business Agreement, page 101
Task A Installing cXML Operations Perform the following steps to install cXML operations on Machine 1: 1. Log into TIBCO Administrator. 2. Click BusinessConnect > Operations Editor in the left panel. 3. Click the Import button in the right panel. The Import Operations panel is displayed. 4. Click the Change link next to the Upload Configuration Data File field. The Change File panel is displayed. 5. Click the Browse button, and navigate to the TIBCO_HOME/BC/version/protocols/cxml/samples/Transactions
directory. 6. Select the 1.2.005.csx file, and click the Open button to upload the file. 7. Set the password in the Password Field. 8. Click the Done button. Task B Configuring Server Transport Perform the following steps to configure the BusinessConnect server on Machine 1:
TIBCO BusinessConnect cXML Protocol User’s Guide
96
| Chapter 9
Tutorial — Standalone Private Processes
1. Enable the HTTP transport. a. In TIBCO Administrator, click BusinessConnect > System Settings in the left panel. b. Click the Inbound Public Transport Types link in the right panel. The Inbound Public Transport Types panel is displayed. c. Check the HTTP, HTTPS, and HTTPSCA checkboxes from the Transport Type list and then click the Enable button. d. Click the Done button to save the changes. 2. Click BusinessConnect > Gateway in the left panel. 3. Click the Gateway Services link in the right panel. The Gateway Services panel is displayed. 4. Click the New button and then the New Gateway Service panel is displayed. 5. In the Name field, enter HTTP. 6. Select the HTTP item from the Type drop-down list and then click the OK button to save the changes. 7. In the Credentials tab, specify a private key. a. Click the New Private Key button in the All Credentials panel. The New Private Key panel is displayed. b. In the Alias field, enter Buyer
Key.
c. Click the Change link, and navigate to the TIBCO_HOME/BC/version/samples/keys directory. Select the bcpartner1_key.p12 file and then click the OK button. d. Click the Set link next to the Password field. In the Enter Password and Enter Password Again fields, enter Password1. e. Click the OK button and then click the Save button. The new Private Key is listed in the Credential Name column. 8. In the Transport tab, select the Buyer Key item in the Private Key Credential for Secure Ports drop-down list. The BusinessConnect server on Machine 1 is now configured with an HTTP transport. Task C Configuring a New Domain Perform the following steps to configure a new domain in TIBCO Administrator: 1. Click BusinessConnect > System Settings in the left panel. TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up Buyer on Machine 1 97
|
2. Click the Metadata Type Configuration link in the right panel. 3. Click the Domains link in the Metadata Type Configuration panel. The Edit: Domains panel is displayed. 4. Click the New button. The New Domain panel is displayed. 5. In the Domain Name field, type cXML-Example. 6. Click the Save button. 7. Click the Done button in the Edit: Domains panel and then click the Done button in the Metadata Type Configuration panel to save the changes. Task D Configuring Trading Host (Buyer) In this section, you will set up the buyer as a trading host on Machine 1 by performing the following tasks: •
Setting Up Trading Host Properties, page 97
•
Setting Up cXML Protocol, page 98
Setting Up Trading Host Properties 1. Click the BusinessConnect > Participants link in the left panel. 2. Click the New button in the right panel. The New Participant panel is displayed. 3. Type Company1 in the Name field. 4. Select the Host item in the Type drop-down list and then click the OK button. The New Host Participant: Company1 panel is displayed. 5. Check the Active checkbox. 6. In the Business Locations tab, click the Headquarters link. 7. Specify the following fields: — Phone: 111-111-1111 — Fax: 111-111-1111 — Email: [email protected]
TIBCO BusinessConnect cXML Protocol User’s Guide
98
| Chapter 9
Tutorial — Standalone Private Processes
8. Assign a legal contact to the business location. a. In the Contacts panel, click the New button in the Contacts panel. The New Contact panel is displayed. b. In the First Name field, enter Legal. c. In the Last Name field, enter 1. d. Select the Legal item from the Contact Type drop-down list. e. Click the Save button to save the contact information. The Edit Business Location panel is displayed. f.
Select the Legal
1
item in the Primary Legal Contact drop-down list.
9. Assign a support contact to the business location. a. In the Contacts panel, click the New button in the Contacts panel. The New Contact panel is displayed. b. In the First Name field, enter Support. c. In the Last Name field, enter 1. d. Select the Support item from the Contact Type drop-down list. e. Click the Save button to save the contact information. The Edit Business Location panel is displayed. f.
Select the Support
1
item in the Primary Legal Contact drop-down list.
10. Click the Save button. Setting Up cXML Protocol Perform the following steps to set up a cXML protocol: 1. In the Protocols tab, click the cXML link. The Edit Enabled Protocol: cXML panel is displayed. 2. In the General tab, click the Add New link next to the Default Domain Identity field. The Domain Identity List panel is displayed. 3. Click the Add New button. The New panel is displayed. 4. Select the cXML-Example item from the Domain drop-down list. 5. In the Identity field, enter id1111. 6. Click the Save button and then click the OK button. 7. Select the cXML-Example-id1111 item from the Default Domain Identity drop-down list.
TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up Buyer on Machine 1 99
|
8. In the URL field, enter http://www.company1.com:6700/cXML, where 6700 is the HTTP port number of company1. 9. Click the Save button in the Edit Enabled Protocol: cXML panel. 10. Click the Save button in the Edit Host Participant: Company1 panel. Checking Your Work 1. Click BusinessConnect > System Settings in the left panel. 2. Click the General link in the right panel. 3. Select the Company1 item in the Default Host drop-down list. 4. Click the Save button. Task E Setting Up Seller as Trading Partner Next, you will set up a trading partner configuration on Machine 1 for the seller by performing the following tasks: 1. Setting Up Seller’s Trading Partner Properties, page 99 2. Setting Up the cXML Protocol, page 100 Setting Up Seller’s Trading Partner Properties Perform the following steps to set up properties for a seller’s trading partner: 1. Click the BusinessConnect > Participants link in the left panel. 2. Click the New button in the right panel. The New Participant panel is displayed. 3. Type Company2 in the Name field. 4. Select the Partner item in the Type drop-down list and then click the OK button. The New Partner Participant: Company2 panel is displayed. 5. Check the Active checkbox. 6. In the Business Locations tab, click the Headquarters link. 7. Specify the following fields: — Phone: 222-222-2222 — Fax: 222-222-2222 — Email: [email protected]
TIBCO BusinessConnect cXML Protocol User’s Guide
100
| Chapter 9
Tutorial — Standalone Private Processes
8. Assign a legal contact to the business location. a. In the Contacts panel, click the New button in the Contacts panel. The New Contact panel is displayed. b. In the First Name field, enter Legal. c. In the Last Name field, enter 2. d. Select the Legal item from the Contact Type drop-down list. e. Click the Save button to save the contact information. The Edit Business Location panel is displayed. f.
Select the Legal
2
item in the Primary Legal Contact drop-down list.
9. Assign a support contact to the business location. a. In the Contacts panel, click the New button in the Contacts panel. The New Contact panel is displayed. b. In the First Name field, enter Support. c. In the Last Name field, enter 2. d. Select the Support item from the Contact Type drop-down list. e. Click the Save button to save the contact information. The Edit Business Location panel is displayed. f.
Select the Support
2
item in the Primary Legal Contact drop-down list.
10. Click the Save button. Setting Up the cXML Protocol Perform the following steps to set up a cXML protocol: 1. In the Protocols tab, click the cXML link. The Edit Enabled Protocol: cXML panel is displayed. 2. If the cXML item is not displayed in the Protocol list: a. Click the Enable button. b. Check the cXML checkbox and then click the OK button.
TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up Buyer on Machine 1 101
|
3. Configure the General tab. a. Click the Add New link next to the Default Domain Identity field. The Domain Identity List panel is displayed. b. Click the Add New button. The New panel is displayed. c. Select the cXML-Example item from the Domain drop-down list. d. In the Identity field, enter id2222. e. Click the Save button and then click the OK button. f.
Select the cXML-Example-id2222 item from the Default Domain Identity drop-down list.
4. Configure the Transports tab. a. Click the Add button. The New Transport panel is displayed. b. In the Name field, enter HTTP. c. Select the HTTP item from the Type drop-down list. d. Click the OK button. The New HTTP Transport panel is displayed. e. In the URL field, type hostname:6700/cXML, where hostname is the host name of Machine 2, which configures the seller as its trading host, and 6700 is the HTTP port set in the deployment configuration on the seller’s server. See Configuring Server Transport on page 103 for more information. f.
Click the Save button in the New HTTP Transport panel.
5. Click the Save button in the Edit Enabled Protocol: cXML panel. 6. Click the Save button in the Edit Partner Participant: Company2 panel. Task F Configuring Business Agreement Perform the following steps to configure business agreement: 1. In TIBCO Administrator, click BusinessConnect > Business Agreements in the left panel. 2. Click the New button in the right panel. The New Agreement panel is displayed. 3. Select the Company1 radio button in the Host Party panel and the Company2 radio button in the Partner Party panel. 4. Click the OK button. The New Agreement panel is displayed. 5. Click the Add Protocol Bindings button. The Select Protocol panel is displayed. TIBCO BusinessConnect cXML Protocol User’s Guide
102
| Chapter 9
Tutorial — Standalone Private Processes
6. Check the cXML checkbox and then click the OK button. The New Agreement panel is displayed. 7. Click the cXML link in the Protocol Binding panel. 8. In the Operation Bindings tab, check the Allow All Operations checkbox. This checkbox enables both the host and the partner in this agreement to initiate all operations installed in the Operations Editor. In this tutorial only the host acts as the initiator. 9. Click the Transports tab. 10. In the Outbound Transports for Host 'Company1' panel, select the HTTP item from the Primary Transport drop-down list. 11. In the Allowed Inbound Transports for Partner 'Company2' panel, check the HTTP checkbox. 12. Click the Save button in the Edit Protocol Binding: cXML panel. 13. Click the Save button in the Edit Agreement: Company 1 - Company 2 panel.
TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up Seller on Machine 2 103
|
Setting Up Seller on Machine 2 This section gives the instructions for setting up a trading participant on Machine 2, which acts as the seller in the transaction. The following is a general sketch of the tasks: •
Task A, Importing cXML Operations, page 103
•
Task B, Configuring Server Transport, page 103
•
Task C, Configuring Domain, page 104
•
Task D, Configuring Trading Host (Seller), page 105
•
Task E, Setting Up Buyer as Trading Partner, page 107
•
Task F, Configuring Business Agreement, page 109
Task A Importing cXML Operations Perform the following steps to install cXML operations on Machine 2: 1. Log into TIBCO Administrator. 2. Click BusinessConnect > Operations Editor in the left panel. 3. Click the Import button in the right panel. The Import Operations panel is displayed. 4. Click the Change link next to the Upload Configuration Data File field. The Change File panel is displayed. 5. Click the Browse button, and navigate to the TIBCO_HOME/BC/version/protocols/cxml/samples/Transactions
directory. 6. Select the 1.2.005.csx file, and click the Open button to upload the file. 7. Set the password in the Password Field. 8. Click the Done button. Task B Configuring Server Transport Perform the following steps to configure transport for the BusinessConnect server on Machine 2:
TIBCO BusinessConnect cXML Protocol User’s Guide
104
| Chapter 9
Tutorial — Standalone Private Processes
1. Enable the HTTP transport. a. In TIBCO Administrator, click BusinessConnect > System Settings in the left panel. b. Click the Inbound Public Transport Types link in the right panel. The Inbound Public Transport Types panel is displayed. c. Check the HTTP, HTTPS, and HTTPSCA checkboxes in the Transport Type list and then click the Enable button. d. Click the Done button to save the changes. 2. Click BusinessConnect > Gateway in the left panel. 3. Click the Gateway Services link in the right panel. The Gateway Services panel is displayed. 4. Click the New button and then the New Gateway Service panel is displayed. 5. In the Name field, enter HTTP. 6. Select the HTTP item from the Type drop-down list and then click the OK button to save the changes. 7. In the General tab, check the Active checkbox to active the HTTP transport. 8. In the Credentials tab, specify a private key. a. Click the New Private Key button in the All Credentials panel. The New Private Key panel is displayed. b. In the Alias field, enter Seller
Key.
c. Click the Change link, and navigate to the TIBCO_HOME/BC/version/samples/keys directory. Select the bcpartner2_key.p12 file and then click the OK button. d. Click the Set link next to the Password field. In the Enter Password and Enter Password Again fields, enter Password1. e. Click the OK button and then click the Save button. The new Private Key is listed under the Credential Name column. 9. In the Transport tab, select the Seller Key item in the Private Key Credential for Secure Ports drop-down list. The BusinessConnect server on Machine 2 is now configured with an HTTP transport. Task C Configuring Domain Perform the following steps to configure a new domain in TIBCO Administrator: TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up Seller on Machine 2 105
|
1. Click BusinessConnect > System Settings in the left panel. 2. Click the Metadata Type Configuration link in the right panel. 3. Click the Domains link in the Metadata Type Configuration panel. The Edit: Domains panel is displayed. 4. Click the New button. The New Domain panel is displayed. 5. In the Domain Name field, type cXML-Example. 6. Click the Save button. 7. Click Done button in the Edit: Domains panel and then click the Done button in the Metadata Type Configuration panel to save the changes. Task D Configuring Trading Host (Seller) This section describes how to set up a seller as a trading host on Machine 2 by performing the following tasks: •
Setting Up Seller’s Trading Host Properties, page 105
•
Setting Up cXML Protocol, page 106
Setting Up Seller’s Trading Host Properties Perform the following steps to set up host properties: 1. Click the BusinessConnect > Participants link in the left panel. 2. Click the New button in the right panel. The New Participant panel is displayed. 3. Type Company2 in the Name field. 4. Select the Host item in the Type drop-down list and then click the OK button. The New Host Participant: Company2 panel is displayed. 5. Check the Active checkbox. 6. In the Business Locations tab, click the Headquarters link. 7. Specify the following fields: — Phone: 222-222-2222 — Fax: 222-222-2222 — Email: [email protected]
TIBCO BusinessConnect cXML Protocol User’s Guide
106
| Chapter 9
Tutorial — Standalone Private Processes
8. Assign a legal contact to the business location. a. In the Contacts panel, click the New button in the Contacts panel. The New Contact panel is displayed. b. In the First Name field, enter Legal. c. In the Last Name field, enter 2. d. Select the Legal item from the Contact Type drop-down list. e. Click the Save button to save the contact information. The Edit Business Location panel is displayed. f.
Select the Legal
2
item in the Primary Legal Contact drop-down list.
9. Assign a legal contact to the business location. a. In the Contacts panel, click the New button in the Contacts panel. The New Contact panel is displayed. b. In the First Name field, enter Support. c. In the Last Name field, enter 2. d. Select the Support item from the Contact Type drop-down list. e. Click the Save button to save the contact information. The Edit Business Location panel is displayed. f.
Select the Support
2
item in the Primary Legal Contact drop-down list.
10. Click the Save button. Setting Up cXML Protocol Perform the following steps to set up a cXML Protocol: 1. In the Protocols tab, click the cXML link. The Edit Enabled Protocol: cXML panel is displayed. 2. If the cXML item is not display in the Protocol list: a. Click the Enable button. b. Check the cXML checkbox and then click the OK button.
TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up Seller on Machine 2 107
|
3. Configure the General tab. a. Click the Add New link next to the Default Domain Identity field. The Domain Identity List panel is displayed. b. Click the Add New button. The New panel is displayed. c. Select the cXML-Example item from the Domain drop-down list. d. In the Identity field, enter id2222. e. Click the Save button and then click the OK button. f.
Select the cXML-Example-id2222 item from the Default Domain Identity drop-down list.
4. In the URL field, enter http://www.company2.com:6700/cXML, where 6700 is the HTTP port number of company2. 5. Click the Save button in the Edit Enabled Protocol: cXML panel. 6. Click the Save button in the Edit Host Participant: Company1 panel. Checking Your Work Perform the following steps to check the host name: 1. Click BusinessConnect > System Settings in the left panel. 2. Click the General link in the right panel. 3. Select the Company2 item in the Default Host drop-down list. 4. Click the Save button. Task E Setting Up Buyer as Trading Partner Next, you need to set up a trading partner configuration on Machine 2 for the buyer by performing the following tasks: 1. Setting Up Buyer’s Trading Partner Properties, page 107 2. Setting Up cXML Protocol, page 108 Setting Up Buyer’s Trading Partner Properties Perform the following steps to set up the properties of the buyer’s trading partner: 1. Click the BusinessConnect > Participants link in the left panel. 2. Click the New button in the right panel. The New Participant panel is displayed.
TIBCO BusinessConnect cXML Protocol User’s Guide
108
| Chapter 9
Tutorial — Standalone Private Processes
3. Type Company1 in the Name field. 4. Select the Partner item in the Type drop-down list and then click the OK button. The New Partner Participant: Company1 panel is displayed. 5. Check the Active checkbox. 6. In the Business Locations tab, click the Headquarters link. 7. Specify the following fields: — Phone: 111-111-1111 — Fax: 111-111-1111 — Email: [email protected] 8. Assign a legal contact to the business location. a. In the Contacts panel, click the New button in the Contacts panel. The New Contact panel is displayed. b. In the First Name field, enter Legal. c. In the Last Name field, enter 1. d. Select the Legal item from the Contact Type drop-down list. e. Click the Save button to save the contact information. The Edit Business Location panel is displayed. f.
Select the Legal
1
item in the Primary Legal Contact drop-down list.
9. Assign a legal contact to the business location. a. In the Contacts panel, click the New button in the Contacts panel. The New Contact panel is displayed. b. In the First Name field, enter Support. c. In the Last Name field, enter 1. d. Select the Support item from the Contact Type drop-down list. e. Click the Save button to save the contact information. The Edit Business Location panel is displayed. f.
Select the Support
1
item in the Primary Legal Contact drop-down list.
10. Click the Save button. Setting Up cXML Protocol Perform the following steps to set up a cXML Protocol:
TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up Seller on Machine 2 109
|
1. In the Protocols tab, click the cXML link. The Edit Enabled Protocol: cXML panel is displayed. 2. If the cXML item does not display in the Protocol list: a. Click the Enable button. b. Check the cXML checkbox and then click the OK button. 3. In the General tab, follow the steps below to configure this tab: a. Click the Add New link next to the Default Domain Identity field. The Domain Identity List panel is displayed. b. Click the Add New button. The New panel is displayed. c. Select the cXML-Example item from the Domain drop-down list. d. In the Identity field, enter id1111. e. Click the Save button and then click the OK button. f.
Select the cXML-Example-id1111 item from the Default Domain Identity drop-down list.
4. In the Transports tab, follow the steps below to configure this tab: a. Click the Add button. The New Transport panel is displayed. b. In the Name field, enter HTTP. c. Select the HTTP item from the Type drop-down list. d. Click the OK button. The New HTTP Transport panel is displayed. e. In the URL field, type hostname:6700/cXML, where hostname is the host name of Machine 1, which is configured with the initiator (Company1) as its trading host, and 6700 is the HTTP port set in the deployment configuration on the buyer’s server. See Configuring Server Transport on page 95 for more information. f.
Click the Save button in the New HTTP Transport panel.
5. Click the Save button in the Edit Enabled Protocol: cXML panel. 6. Click the Save button in the Edit Partner Participant: Company1 panel. Task F Configuring Business Agreement Perform the following steps to configure business agreements: 1. In TIBCO Administrator, click BusinessConnect > Business Agreements in the left panel.
TIBCO BusinessConnect cXML Protocol User’s Guide
110
| Chapter 9
Tutorial — Standalone Private Processes
2. Click the New button in the right panel. The New Agreement panel is displayed. 3. Select the Company2 radio button in the Host Party panel and the Company1 radio button in the Partner Party panel. 4. Click the OK button. The New Agreement panel is displayed. 5. Click the Add Protocol Bindings button. The Select Protocol panel is displayed. 6. Check the cXML checkbox and then click the OK button. The New Agreement panel is displayed. 7. Click the cXML link in the Protocol Binding panel. 8. In the Operation Bindings tab, check the Allow All Operations checkbox. This checkbox enables both the host and the partner in this agreement to initiate all operations installed in the Operations Editor. In this tutorial, only the host acts as the initiator. 9. Click the Transports tab. 10. In the Outbound Transports for Host 'Company2' panel, select the HTTP item from the Primary Transport drop-down list. 11. In the Allowed Inbound Transports for Partner 'Company1' panel, check the HTTP checkbox. 12. Click the Save button in the Edit Protocol Binding: cXML panel. 13. Click the Save button in the Edit Agreement: Company 2 - Company 1 panel.
TIBCO BusinessConnect cXML Protocol User’s Guide
Running the Tutorial Example 111
|
Running the Tutorial Example This section describes how to run the private processes to simulate cXML operations using the buyer and seller you configured. Running the simulation consists of the following tasks: 1. Configuring Buyer’s Private Process, page 111 2. Configuring Seller’s Private Process, page 112 3. Running Private Process Files, page 113 The instructions described in this section apply to both Windows and UNIX platforms, except that only the files used for Windows platforms (ppinitiator.exe and ppresponder.exe) are mentioned. For UNIX platforms, simply use the corresponding UNIX files in place of the Windows files (ppinitiator and ppresponder) as you step through the instructions.
Configuring Buyer’s Private Process You need the ppinitiator.exe executable file on Machine 1 to simulate a standalone initiator private process. This file executes a Java program that sends a sample Rendezvous message to BusinessConnect, then prints the response in the command prompt. You must edit the ppinitiator.tra file to correspond to the settings in your BusinessConnect installation: 1. In Administrator, set the java.property.serverName parameter to the installation name. Follow the steps below to find the installation name: a. Click the BusinessConnect > System Settings link in the left panel. b. Click the General link in the right panel. The General panel is displayed. c. In the Installation Name field, enter java.property.serverName. d. Select the Company1 item in the Default Host drop-down list. e. Click the Save button.
TIBCO BusinessConnect cXML Protocol User’s Guide
112
| Chapter 9
Tutorial — Standalone Private Processes
2. Configure the ppinitiator.tra file. a. On Machine 1, open the ppinitiator.tra file in the TIBCO_HOME/BC/version/protocols/cxml/samples/src directory in a
text editor. b. Set the value of the java.property.tpName parameter to company2. c. Remove the number sign (#) from the start of the following line: #java.property.operationId=PunchOutSetupRequest
d. Add the number sign (#) to the start of the following line: java.property.operationId=ProfileRequest The ppinitiator.tra file is configured by default to send a ProfileRequest to BusinessConnect. Performing ProfileRequest operations is a good way to determine whether the partners’ servers are connected and configured properly.
e. Save the file.
Configuring Seller’s Private Process You will use the ppresponder.exe executable file on Machine 2 to simulate a standalone responder private process. This file executes a Java program that does the following: •
Waits for an inbound cXML request from BusinessConnect.
•
Outputs the inbound request in the command prompt.
•
Outputs the response in the command prompt.
•
Sends the response to its BusinessConnect server via Rendezvous.
You must edit the ppresponder.tra file to correspond to the settings in your BusinessConnect installation: 1. On Machine 2, open the ppresponder.tra file in the TIBCO_HOME/BC/version/protocols/cxml/samples/src directory in a text
editor. 2. Set the value of the java.property.serverName parameter to the installation name. To get the installation name, see step 1 in Configuring Buyer’s Private Process on page 111. 3. Save the file.
TIBCO BusinessConnect cXML Protocol User’s Guide
Running the Tutorial Example 113
|
Running Private Process Files Perform the following steps to run the private process files in TIBCO Administrator: 1. On Machine 2 (the seller side), click Application Management > BusinessConnect > Service Instances in the left panel. Verify that the service instance is in the Running state. If not, deploy and start the instance. If you are using BusinessConnect in DMZ mode, verify that both the DMZ instance and the BusinessConnect server instance are running. 2. Create the ppresponder.exe file manually: a. Copy the wrap.exe file from the TIBCO_HOME/tools/wrapper directory to the TIBCO_HOME/bc/version/protocols/cxml/samples/src directory. b. Rename the copied file to ppresponder.exe. 3. Execute ppresponder.exe in a command prompt on Machine 2. 4. On Machine 1 (the buyer side), click Application Management > BusinessConnect > Service Instances in the left panel of TIBCO Administrator. Verify that the service instance is in the Running state. If not, deploy and start BusinessConnect. 5. Create the ppinitiator.exe file manually: a. Copy the wrap.exe file from the TIBCO_HOME/tools/wrapper directory to the TIBCO_HOME/bc/version/protocols/cxml/samples/src directory. b. Rename the copied file to ppinitiator.exe. 6. Execute ppinitiator.exe in a command prompt on Machine 1. 7. Watch the command prompt outputs to see messages being exchanged between the two machines.
Viewing Audit Log You can view logs of the interaction on both the initiator and the responder side. Perform the following steps to view the audit logs: 1. In TIBCO Administrator, click BusinessConnect > Log Viewer in the left panel. 2. Select the cXML radio button in the Protocol list and then click the Audit button. The Audit Logs: cXML > Connection: bc-db panel is displayed.
TIBCO BusinessConnect cXML Protocol User’s Guide
114
| Chapter 9
Tutorial — Standalone Private Processes
3. If transaction processing proceeds normally, select the COMPLETED item in the Status drop-down list. If an error occurs during transaction processing, select the ERROR item in the Status drop-down list. 4. Select the One Day item in the Date Range drop-down list. 5. Click the Search button. You should see a log entry for the PunchOutSetupRequest operation. 6. Click the icon in the left-most column of the Search Results panel to view the details of the transaction.
TIBCO BusinessConnect cXML Protocol User’s Guide
| 115 Chapter 10
Tutorial — TIBCO ActiveMatrix BusinessWorks Private Processes
This chapter demonstrates how to design TIBCO ActiveMatrix BusinessWorks private process for TIBCO BusinessConnect cXML Protocol.
Topics •
Overview, page 116
•
Using the Example Project Files, page 117
•
Setting Up PunchOutSetupRequest Operation, page 121
•
Running PunchOutSetupRequest Operation, page 124
TIBCO BusinessConnect cXML Protocol User’s Guide
116
| Chapter 10
Tutorial — TIBCO ActiveMatrix BusinessWorks Private Processes
Overview The TIBCO BusinessConnect palette in TIBCO Designer enables business process designers to integrate the processes in TIBCO ActiveMatrix BusinessWorks with BusinessConnect. Configuring Private Processes with TIBCO ActiveMatrix BusinessWorks on page 75 includes some instructions on how to set up the palette resources in TIBCO Designer. For more information on each resource in the BusinessConnect palette, see TIBCO BusinessConnect Palette Reference. This tutorial demonstrates the configuration of TIBCO ActiveMatrix BusinessWorks private processes using the BusinessConnect palette in TIBCO Designer. An understanding of TIBCO ActiveMatrix BusinessWorks and TIBCO Designer is necessary to run and understand this tutorial.
Prerequisites In order to use this tutorial, you must have done the following: •
Installed TIBCO ActiveMatrix BusinessWorks before installing TIBCO BusinessConnect on the two machines used in Chapter 9, Tutorial — Standalone Private Processes, on page 91. Doing so ensures that the BusinessConnect palette is installed properly into TIBCO Designer when BusinessConnect is installed.
•
Completed the tutorial in Chapter 9, Tutorial — Standalone Private Processes, on page 91. You will use the same setup on the two machines to run the tutorial in this chapter.
TIBCO BusinessConnect cXML Protocol User’s Guide
Using the Example Project Files 117
|
Using the Example Project Files The BusinessWorks project files used in this tutorial can be found in the TIBCO_HOME/bc/version/protocols/cxml/samples/bw directory. This example project demonstrates how to send and receive messages from TIBCO BusinessConnect cXML Protocol in a BusinessWorks project.
Opening the Example Project You must set up and run the example project on both the initiator and the responder machines. Follow in instructions below to set up the example project on both machines: 1. Start TIBCO Designer. 2. Click the New Empty Project button in the TIBCO Designer Startup panel. The Save Project dialog is displayed. 3. In the Project Directory field of the Multi-File Project tab, specify a directory for this new project or click the button to browse to an empty directory. 4. Click the OK button. The TIBCO Designer window is displayed. 5. Select Project > Import Full Project in TIBCO Designer menu. The Import Full Project dialog is displayed. 6. In the ZIP Archive tab, click the
button, and browse to the
TIBCO_HOME/bc/version/protocols/cxml/samples/bw directory.
7. Select the cXMLbwSample.zip archive file, and click the OK button. The Import - Options dialog is displayed. 8. In the Import - Options dialog, select the following radio buttons: — Replace Existing Global Variables With Those In Import — Overwrite On Name Conflict 9. Click the Apply button. After the project finishes loading, the main project is displayed, as shown in Figure 1.
TIBCO BusinessConnect cXML Protocol User’s Guide
118
| Chapter 10
Tutorial — TIBCO ActiveMatrix BusinessWorks Private Processes
Figure 1 TIBCO ActiveMatrix BusinessWorks Project
Setting Up the Example Project Perform the following steps to set up the example project. 1. After opening the example project, click the Global Variables tab in the TIBCO Designer project window. 2. Set the value of the BC_CXML_HOME variable to TIBCO_HOME/bc/version/protocols/cxml and then click the OK button to save the changes. 3. Click the Project tab in the TIBCO Designer project window to view the project panel. 4. Click the root folder in the project palette. In this example, the root folder is called Untitled3, as shown in Figure 1.
TIBCO BusinessConnect cXML Protocol User’s Guide
Using the Example Project Files 119
|
5. Configure the BusinessConnect Connection shared resource. a. In the design panel, click the BC-cXML icon, . This is the BusinessConnect Connection shared resource used to connect to your BusinessConnect server and configuration store. b. Click the BusinessConnect Server Access tab in the Configuration panel. c. Specify the JDBC Driver, JDBC URL, DB User, and DB Password fields. JDBC settings should be the same as the settings in your BusinessConnect installation. To see the JDBC settings in your BusinessConnect installation, log into TIBCO Administrator, and click BusinessConnect > System Settings > Audit, Non-Repudiation and Runtime Database Configuration and then select the bc-db link. d. Click the Apply button. e. In the Configuration tab, check the Update Transport Settings checkbox. f.
Click the Update From Configuration Store button.
g. Select the cXML item from the Protocol Name drop-down list. h. Click the Import Selected Business Protocol button. You should now see all installed operations in the BusinessConnect configuration store. i.
Click the Apply button.
6. Save the project.
Project Components After you have set up the example project, the design panel of the root project folder should look like the following figure.
Four folders in the root project directory contain process definitions for various operations:
TIBCO BusinessConnect cXML Protocol User’s Guide
120
| Chapter 10
Tutorial — TIBCO ActiveMatrix BusinessWorks Private Processes
•
cXML Requests contains process definitions for initiating three operations: ProfileRequest, PunchOutSetupRequest and OrderRequest.
•
cXML Responses contains process definitions for responding to two cXML
operations: PunchOutSetupRequest and PunchOutOrderMessage. •
cXML Messages contains process definitions for initiating two different cXML notify operations: PuncOutOrderMessage and SubscriptionChangeMessage.
•
Misc Messages contains a process definition for receiving error messages.
The cXML DTDs and Utilities folders contain some helper resources used by the process definitions in the four folders above. The Utilities folder contains a process that is used to acquire sample cXML documents. The BCSchemas folder is maintained and used by the BC-cXML (BusinessConnect Connection) shared resource. It contains schemas for all operations imported from your BusinessConnect configuration store Do not move, modify, nor delete the BCSchemas folder or the contents therein.
The Main process definition is set up to kick-start a cXML operation of your choice. This chapter gives instructions on how to set up and perform a PunchOutSetupRequest operation. You can also try some other operations using the process definitions.
TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up PunchOutSetupRequest Operation 121
|
Setting Up PunchOutSetupRequest Operation This section describes how to set up the PunchOutSetupRequest process definition on Machine 1 and the PunchOutSetupResponse process definition on Machine 2.
Setting Up Buyer on Machine 1 Perform the following steps to set up the buyer on Machine 1, which acts as the initiator: 1. In the project browser of the opened TIBCO Designer project on Machine 1, click the root project folder. 2. In the design panel, double-click the cXML Requests folder and then double-click the cXML PunchOutSetupRequest item to see its details, as shown below.
The Load and Validate Payload process definition is a helper resource taken from the Utilities folder. This resource supplies a sample PunchOutSetupRequest document to the BusinessConnect resource (PunchOutSetupRequest). 3. Click the PunchOutSetupRequest icon in the design panel to see its details in the configuration panel. 4. Click the Input tab.
TIBCO BusinessConnect cXML Protocol User’s Guide
122
| Chapter 10
Tutorial — TIBCO ActiveMatrix BusinessWorks Private Processes
5. Expand the process data in the Process Data panel to see how the data is mapped as input, as shown below.
6. Click the button in the Activity Input panel to correct any mapping errors. Repeat until no errors are found. 7. Click the Apply button.
Setting Up Seller on Machine 2 Perform the following steps to set up the buyer on Machine 2, which acts as the responder: 1. In the project browser of the opened TIBCO Designer project on Machine 2, click the root project folder. 2. In the design panel, double-click the cXML Responses folder. 3. Double-click the PunchOutSetupRequest Responder icon to see its details, as shown below.
The Load and Validate Payload process definition is a helper resource taken from the Utilities folder. This resource supplies a sample PunchOutSetupResponse document to the BusinessConnect resource (PunchOutSetupResponse).
TIBCO BusinessConnect cXML Protocol User’s Guide
Setting Up PunchOutSetupRequest Operation 123
|
4. Click the PunchOutSetupResponse icon in the design panel to see its details in the configuration panel. 5. Click the Input tab. 6. Expand the process data in the Process panel to see how the data is mapped as input, as shown below.
7. Click the button in the Activity Input panel to correct any mapping errors. Repeat until no errors are found. 8. Click the Apply button.
TIBCO BusinessConnect cXML Protocol User’s Guide
124
| Chapter 10
Tutorial — TIBCO ActiveMatrix BusinessWorks Private Processes
Running PunchOutSetupRequest Operation To run the PunchOutSetupRequest operation that you have set up, you must run the following processes using the TIBCO Designer tester tool: •
PunchOutSetupRequest Responder on Machine 2
•
cXML Error Message on both machines
•
cXML PunchOutSetupRequest on Machine 1
Running Seller on Machine 2 Perform the following steps to start the responder processes on Machine 2: 1. In the opened TIBCO Designer project on Machine 2, click the Tester tab in the project panel. 1. Click the
button. The Select Processes To Load dialog is displayed.
2. Check the PunchOutSetupRequest Responder checkbox in the cXML Responses folder. 3. Check the Error Message checkbox in the Misc
Messages
folder.
4. Click the Load Selected button. 5. Move on to Running Buyer on Machine 1 after TIBCO Designer finishes loading the processes.
Running Buyer on Machine 1 You must finish starting the responder processes on Machine 2 before proceeding with this section. Perform the following steps to start the initiator processes on Machine 1: 1. In the opened TIBCO Designer project on Machine 1, click the Tester tab in the project panel. 1. Click the
button.
2. Check the cXML PunchOutSetupRequest checkbox in the cXML folder. 3. Check the Error Message checkbox in the Misc
Messages
Responses
folder.
4. Click the Load Selected button. 5. In the Jobs list, click the cXML Requests/cXML PunchOutSetupRequest job.
TIBCO BusinessConnect cXML Protocol User’s Guide
Running PunchOutSetupRequest Operation 125
|
6. Click the
button to initiate the PunchOutSetupRequest operation.
7. Set the text content of the operationName element to PunchOutSetupRequest. You can set the text content by double-clicking the column on the right of the operationName column. 8. Set the text content of the tpName element to company2. You can set the text content by double-clicking the column on the right of the tpName column. 9. Follow the process flow in the TIBCO Designer tester on both machines.
Expected Behavior You should see that the tester on Machine 1 (buyer side) pauses at its BusinessConnect resource (PunchOutSetupRequest) while the tester on Machine 2 (seller side) steps through the transitions. After the tester on Machine 2 transitions to its BusinessConnect resource (PunchOutSetupRequest Responder), the tester on Machine 1 resumes processing. You can step through the process flow or set breakpoints in a particular job to view how information is exchanged between the buyer and the seller. Also, you can inspect the audit log in BusinessConnect for more information on how messages are exchanged between BusinessWorks and the BusinessConnect server.
TIBCO BusinessConnect cXML Protocol User’s Guide
126
| Chapter 10
Tutorial — TIBCO ActiveMatrix BusinessWorks Private Processes
TIBCO BusinessConnect cXML Protocol User’s Guide
| 127 Appendix A
Status Codes
This section describes the status codes generated by TIBCO BusinessConnect cXML Protocol and their descriptions. Status codes are numbered according to the following categories: •
2xx — Success
•
4xx — Permanent error. The client should not retry. The error is such that the request cannot be accepted as it is. Error code 409 is the only exception to this.
•
5xx — Transient error. This is usually a transport error. The client should retry.
•
1xxx — Private process-defined error codes.
Table 26 contains all status codes sent by TIBCO BusinessConnect cXML Protocol for outbound and inbound messages. Table 26 Status Codes Code
Description
200
OK
201
Accepted
400
Bad request
401
Unauthorized (authentication failed)
403
Forbidden (operation not allowed)
406
Not acceptable (document parsing error)
417
Expectation failed (configuration error)
476
Signature verification failed
500
Internal server error
551
Unable to forward request
TIBCO BusinessConnect cXML Protocol User’s Guide
128
| Appendix A
Status Codes
TIBCO BusinessConnect cXML Protocol User’s Guide
| 129 Appendix B
Property Reference
Table 27 contains the explanations to the configurable cXML properties, which can be found in TIBCO Administrator by clicking BusinessConnect > System Settings > Activated Protocol Plug-ins and Properties > cXML. Table 27 cXML Configurable Properties (Sheet 1 of 3) Property
Default
Comments
cXML.credentialcheck. to
all
Relaxes security for the To credential checking for incoming documents. The following are the possible values: all — The first To credential that matches one of the configured host credentials is used to identify the host. However, all credentials in the element in the cXML header must match the credentials of a configured host. Otherwise, BusinessConnect sends a 400 error. any — The first To credential that matches a configured host credential is used to identify the host, and TIBCO BusinessConnect cXML Protocol processes the inbound document without checking any remaining To credentials. If not one credential in the element produces a match, BusinessConnect sends a 400 error. first — The first credential in the element is used to identify the host. If it does not match a host credential, BusinessConnect sends a 400 error.
TIBCO BusinessConnect cXML Protocol User’s Guide
130
| Appendix B
Property Reference
Table 27 cXML Configurable Properties (Sheet 2 of 3) Property
Default
Comments
cXML.credentialcheck. from
all
Relaxes security for the From credential for incoming documents. The following are the possible values: — The first From credential that matches one of the configured partner credentials is used to identify the partner. However, all credentials in the element in the cXML header must match the credentials of a configured partner. Otherwise, BusinessConnect sends a 400 error. all
any — The first From credential that matches a configured partner credential is used to identify the partner, and TIBCO BusinessConnect cXML Protocol processes the inbound document without checking any remaining From credentials. If not one credential in the element produces a match, BusinessConnect sends a 400 error. first — The first credential in the element is used to identify the partner. If it does not match a partner credential, BusinessConnect sends a 400 error. cXML.doctype.systemid .punchoutordermessage
long
Specifies the format of the System identifier in an outgoing message: long
— the complete URL. For example:
http://xml.cXML.org/schemas/cXML/1.2.016 /cXML.dtd short
— only the name of the DTD. For example:
cXML.dtd. cXML.Header.*
False
Specifies whether to forward the entire cXML header to the private process along with the inbound cXML request or notification. This setting overrides the setting for cXML.Header.From, cXML.Header.To, and cXML.Header.Sender properties described below.
cXML.Header.From
False
Specifies whether to forward the From credentials to the private process along with the inbound cXML request or notification.
cXML.Header.To
False
Specifies whether to forward the To credentials to the private process along with the inbound cXML request or notification.
TIBCO BusinessConnect cXML Protocol User’s Guide
Property Reference 131
|
Table 27 cXML Configurable Properties (Sheet 3 of 3) Property
Default
Comments
cXML.Header.Sender
False
Specifies whether to forward the Sender credential to the private process along with the inbound cXML request or notification.
TIBCO BusinessConnect cXML Protocol User’s Guide
132
| Appendix B
Property Reference
TIBCO BusinessConnect cXML Protocol User’s Guide
| 133 Appendix C
Handling Different cXML Document Versions
Because there are different versions of cXML, TIBCO BusinessConnect cXML Protocol processes documents in various cXML versions differently.
Outbound Requests When a private process initiates an outbound cXML request, TIBCO BusinessConnect cXML Protocol first tries to resolve the cXML version and then verifies the version/operation pair against the configured host-to-partner operation bindings. The outbound request is processed only if there is a matching host-to-partner operation binding in the business agreement. When the outbound cXML request does not specify a cXML version, TIBCO BusinessConnect cXML Protocol uses the default host’s cXML version to validate and forward the outbound message.
Inbound Requests When TIBCO BusinessConnect cXML Protocol receives an inbound cXML request, it first tries to resolve the cXML version and then verifies the version/operation pair against the configured partner-to-host operation bindings. The inbound request is accepted only if there is a matching partner-to-host operation binding in the business agreement. However, one of the following situations may occur when BusinessConnect receives an inbound cXML request from a trading partner: •
An inbound cXML document has a DOCTYPE that does not specify a fully-qualified DTD URL. For example:
TIBCO BusinessConnect cXML Protocol uses the default version for the authenticated host for DTD validation. It then sends a response using the same version. You can specify the default cXML version for a trading host in
TIBCO BusinessConnect cXML Protocol User’s Guide
134
| Appendix C
Handling Different cXML Document Versions
the host’s cXML configuration panel. See Setting Up cXML Protocol for Trading Hosts on page 40 for more information. If an inbound cXML request does not specify a fully-qualified DTD URL, it will be accepted only when there is a partner-to-host operation binding for defaultVersion/Operation in BusinessConnect’s business agreement configuration. Otherwise, BusinessConnect responds with a 403 (Forbidden) error code. •
An inbound cXML document has a DOCTYPE that specifies a version that is not in the BusinessConnect Operations Editor (See Managing cXML Operations on page 27). For example, a BusinessConnect server that is only installed with cXML versions 1.2.000 and 1.2.016 receives an inbound request with the following DOCTYPE System identifier:
In this case, TIBCO BusinessConnect cXML Protocol uses the highest installed cXML version in its configuration store to validate the request and sends a response using the same version. For example, if the same BusinessConnect server is installed with cXML versions 1.2.000 and 1.2.016, then TIBCO BusinessConnect cXML Protocol uses 1.2.016 for DTD validation. If an inbound cXML request specifies a cXML version, it will be accepted only when there is a partner-to-host operation binding for highestInstalledVersion/Operation in BusinessConnect’s business agreement configuration. Otherwise, BusinessConnect responds with a 403 (Forbidden) error code.
TIBCO BusinessConnect cXML Protocol User’s Guide
| 135 Appendix D
Outbound Message Formats
In accordance with the cXML specification, TIBCO BusinessConnect cXML Protocol uses the MIME wrapper layer for message transmission over the internet. cXML requests can be either singlepart or multipart MIME messages, whereas cXML responses can only be singlepart MIME messages. See Table 28 and Table 29 for formatting information. Table 28 Siglepart MIME Message Message Part
Content
HTTP
POST /cXML HTTP/1.0 Content-type: text/xml; charset="UTF-8" Content-length: 1862 User-Agent: Java1.1 Host: localhost:8083 Connection: Keep-Alive
Content
cXML document
Table 29 Multipart MIME Message
MIME Header
POST /cXML HTTP/1.0 Content-type: multipart/mixed; boundary=something unique User-Agent: Java1.1 Host: localhost:8083
part 1
--something unique content-type: text/xml; charset="UTF-8" cXML document
part 2
--something unique content-type: image/jpeg; [email protected] image --something unique--
TIBCO BusinessConnect cXML Protocol User’s Guide
136
| Appendix D
Outbound Message Formats
TIBCO BusinessConnect cXML Protocol User’s Guide
| 137
Glossary
A
identity domain and an identity string that is usually assigned by the domain administrator.
ActiveExchange™ One of the three product lines in TIBCO’s e-business space that focuses on B2B integration. The other two are ActivePortal™ and ActiveEnterprise™ (see www.tibco.com for details).
DUNS Data Universal Numbering System is a popular identity domain that is maintained by Dun & Bradstreet (D&B). Most business entities and government or non-government organizations worldwide are registered with and identified by this identity domain.
C certificate
I
A document the contains an entity’s identity information and its public key, which are attested to by a certificate authority.
identity domain
credential A domain-identity pair that identifies a trading participant in cXML transactions. A trading participant can possess multiple credentials (one for each identity domain for which it belongs).
A domain that is typically maintained by a public identity service, in which business entities are assigned unique identifiers and can use the identifiers to identify each other when carrying out B2B transactions.
M D
marketplace
An identity domain that is part of a domain-identity pair. See domain identity and identity domain.
An e-commerce network hub for small to medium businesses. In terms of cXML, a marketplace possesses the ability to manage trading participant information and perform all cXML operations.
domain identity
MD5
An identifier for trading participants in e-commerce, which consists of a well-known
An algorithm that can be used to verify message integrity through the creation of a 128-bit message digest from a message of any length.
domain
TIBCO BusinessConnect cXML Protocol User’s Guide
138
| Glossary MD5 is commonly used in digital signature applications.
O operation A cXML request-response or notify action. It denotes the nature and content of the action. For example: a PunchOutSetupRequest operation.
S SHA1 Secure Hash Algorithm 1 is an algorithm that can be used to verify message integrity through the creation of a 160-bit message digest from a message of any length (less than 264 bits). SHA1 is commonly used in digital signature applications.
T transaction A cXML request-reponse or notify action. It denotes the action as a countable unit instead of what happened in the action. For example: the transaction is successful.
TIBCO BusinessConnect cXML Protocol User’s Guide
| 139
Index
A ACSN 3, 78 shared secrets 19 ACSN configuration domain identities 49 ActiveExchange messages 58 ActiveExchange, defined 137 AMNE 3, 78 attachment directory 72 for incoming messages 26, 34 attachment field format 72 attachments 3 audit log 83 state details view 84 summary view 83 transaction details view 84
B BCCXML_HOME xii BrowserFormPost URL 15, 16 business agreements 52, 101, 109 document security 53 operational bindings 52 overriding participant settings 55 transport 53 BusinessConnect configuration operations 25 overview 25 BusinessConnect Connection 75 BusinessConnect palette 116 BusinessPartner 2 BusinessWorks 116 BusinessWorks Private processes notification receivers 77
BusinessWorks private processes 75 activities 76 initiators 77 responders 77 BusinessWorks tutorial example project 117
C certificate,defined 137 configurable reply to PunchOutOrderMessage 16 controlling credentials in outbound messages 21 credentials 21, 42, 49, 78 security relaxation 129 credentials, defined 137 customer support xv cXML 2 cXML operations 8 cXML process flow 8 cXML versions 133 cXML.credentialcheck.from 21, 129 cXML.credentialcheck.to 21, 129 cXML.doctype.systemid.punchoutordermessage 129 cXML.Header.* 129 cXML.Header.From 129 cXML.Header.Sender 129 cXML.Header.To 129
D default cXML version 40 delayed response to OrderRequest messages 13 digital signatures 19, 86 DOCTYPE System identifier 133 document authentication 19, 47 TIBCO BusinessConnect cXML Protocol User’s Guide
140
| Index domain identities 21, 40, 47 adding 42, 49 domain identity 24 domain identity, defined 137 domain, defined 137 domains 26 configuring 35, 96, 104 DUNS, defined 137
E ENV_NAME xii error codes 127 error message format 70, 71 error states 89 exchanging information with your trading partners 24
I identity domain, defined 137 identity domains 26, 42, 49
L logs audit 83 overview 82 resend 87 state values 88, 89 state values for logs 88 viewing 82, 82
M F features 3 fileReference 72 forwarding credentials to private processes 129
H handling different cXML document versions 133 hostDomain field 78 hostId field 78 HTTP 32 HTTPS transport HTTPS 32 HTTPSCA 3, 32
TIBCO BusinessConnect cXML Protocol User’s Guide
marketplace 3, 18 credentials 21 receiving messages from 79 marketplace field 78 marketplace, defined 137 marketplaces 78 MD5 53 MD5, defined 137 message formats 60, 72 attachment field 72 complex types 71 error 70, 71 inbound requests to private processes 65 inbound responses to private processes 69 messages to trading partners 135 notify documents 74 outbound requests from private processes 61 outbound responses from private processes 68 private processes 65, 73 inbound response format 69
Index 141
|
outbound response format 68 processes 61 request and response fields 73 request documents 73 response documents 74 TradingPartner field type 73 MIME message format 135 multiple credentials 21, 47 multiple credentials, sending 21
N new in this release 3 non-repudiation log 86 Notify Action tab 29 notify operation properties 29 Notify Operation tab 29 notify operations 8
O one-way notify operations 8, 9 operation configuration 25 notify 29, 29 Request Action tab 30 request-response 30 Request-Response Operation tab 30 operation, defined 138 operational binding 133 operational bindings 52 operations 8, 9, 27 adding 25 adding manually 27, 28 business agreement bindings 52 exporting 31 importing 25, 27, 95, 103 supported in cXML 1.2.016 4 usage 133 versions, adding 28 OrderRequest 13 OrderResponse 13
overriding participant settings 55
P postURL field 16 preparing to use BusinessConnect cXML Protocol 24 private keys 19 private process simulators, configuring 111, 112 private process configuration 58, 77 BusinessWorks 75, 77 private process messages 78 credentials 58 hostDomain 78 hostId 78 notify document format 74 overview 60 request and response fields 73 request documents 73 response documents 74 private processes 72 attachment field format 72 BusinessWorks 58 complex types 71 error message format 70, 71 inbound request format 65 inbound response format 69 outbound request format 61 outbound response format 68 TradingPartner field type 73 wait time 13 process flow inbound messages 12 outbound messages 11 ProfileRequest 3 properties 129 public certificates 19, 24 PunchOut 15 PunchOut, direct 40 PunchOutOrderMessage 3, 16 configurable reply to 16 URL-encoded 47 PunchOutOrderMessage Reply URL 40 TIBCO BusinessConnect cXML Protocol User’s Guide
142
| Index PunchOutSetupRequest 15
R Rendezvous messages 58 request-response operation properties 30 request-response operations 8 resend log 87 Response Action Tab 30
S server transport 25, 32, 95, 103 server URLs 24 setting credentials from private processes 58 SHA1 53 SHA1, defined 138 shared secrets 19, 24, 47 standalone private processes 58 state details view, audit log 84 state values for logs 89 status codes 127 StatusUpdateRequest 13 summary view, audit log 83 SupplierSetup URL 15, 47 support, contacting xv supported cXML versions and operations 4 synchronous request-response operations 8, 9 System identifier 133 System identifier format 129
trading host configuration 97, 105 trading hosts 38 cXML general 40, 40, 98, 106 trading parters cXML transport 50 trading partners 44 cXML general 46, 47, 100, 108 TradingPartner field type 73 transaction details view, audit log 84 transactions 138 transport HTTP 32 HTTPSCA 32 transports business agreements 53 server 25, 32 tutorial 117 BusinessWorks example project 117 BusinessWorks prerequisites 116 overview 92 participant information 93 prerequisites 93 running BusinessWorks processes 124 running simulated private processes 111 setting up BusinessConnect 95, 103 setting up BusinessWorks private processes 121 setting up example project 118 viewing audit log 113
U URL 40
T
V
technical support xv TIBCO ActiveExchange, defined 137 TIBCO BusinessConnect cXML Protocol 2, 8, 15, 18, 78, 78 TIBCO Designer 58, 116 TIBCO_HOME xii
validating credentials in inbound messages 21 validation 21, 133 validation DTD 29 versions 133
TIBCO BusinessConnect cXML Protocol User’s Guide
Index 143
|
W wait time, private processes 13
TIBCO BusinessConnect cXML Protocol User’s Guide
