Chorus B2B User manual

Chorus B2B Gateway
User Guide
22 May 2009
Version 0.4.3

Chorus B2B User Guide
22 May 2009 Page 2
Version 0.4.3 © Copyright Telecom 2009
Document Control
Document Authorities
Document Details Name Title
Document Owner Jacqui Barclay Implementation Manager
Customer Service, Chorus
Author(s) Dane Moodie Integration Specialist
Approval to publish Date Name Approval By
Approver Email
Version History
This table shows a record of significant changes to the document.
Version Date Author Description
0.1 10 February
2009 Dane Moodie First draft for review by Chorus.
0.2 23 February
2009 Dane Moodie Updated based on feedback from Jacqui Barclay. Updated CPA example based on IBM feedback.
0.3 4 March 2009 Dane Moodie Updated based on feedback from Karen Ellis.
0.4 7 April 2009 Dane Moodie Updated information on timeframes and connectivity testing.
0.4.1 16 April 2009 Dane Moodie Updated based on feedback from Stephen Thomson
0.4.2 19 May 2009 Dane Moodie Updated section on message correlation to incorporate
changes in the B2B
0.4.3 22 May Dane Moodie Changes to reflect the new template. Inclusion of glossary
and intended audience
Document
Review This document will be subject to periodic review. It is the responsibility of the Document Owner to initiate and control the review process.
Copyright
Copyright © 2009 Telecom New Zealand Limited
All rights reserved
No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or
by any means, electronic, mechanical, photocopying, recording or otherwise without the prior written
permission of Telecom New Zealand Limited.
This document is the property of Telecom New Zealand Limited and may not be disclosed to a third party,
other than to any wholly owned subsidiary of Telecom Corporation of New Zealand Limited, or copied
without consent.

Chorus B2B User Guide
22 May 2009 Page 3
Version 0.4.3 © Copyright Telecom 2009
Table of Contents
1. INTRODUCTION.............................................................................................................4
1.1.1. Objectives of Manual..................................................................................................4
1.1.2. Contractual Reference................................................................................................4
1.1.3. Use Of The Name Telecom..........................................................................................4
1.1.4. Limitations ...............................................................................................................4
1.1.5. Intended Audience ....................................................................................................4
1.2. RELATED REFERENCE MATERIAL ..............................................................................................4
1.3. GLOSSARY OF TERMS USED ...................................................................................................4
1.4. WHAT IS THE CHORUS B2B GATEWAY? .....................................................................................6
1.4.1. Message Service Protocol ...........................................................................................6
1.4.2. Relationship Definition ...............................................................................................6
1.5. ASSUMPTIONS ..................................................................................................................7
1.6. SUPPORT ........................................................................................................................7
2. GETTING STARTED ........................................................................................................8
2.1. OVERVIEW ......................................................................................................................9
2.2. INFORMATION REQUIRED BY CHORUS ...................................................................................... 10
2.3. COLLABORATION PROTOCOL AGREEMENT DOCUMENT..................................................................... 11
2.4. CUSTOMER CERTIFICATE..................................................................................................... 20
2.4.1. Production Keys ...................................................................................................... 20
2.4.2. Test Keys.............................................................................................................. 21
2.5. CHORUS CERTIFICATE ....................................................................................................... 21
3. TESTING YOUR IMPLEMENTATION.................................................................................. 21
3.1. TESTING INTERNALLY ........................................................................................................ 21
3.1.1. Sending Messages................................................................................................... 21
3.1.2. Receiving Acknowledgements from Chorus.................................................................. 24
3.1.3. Receiving Messages from Chorus............................................................................... 25
3.2. CHORUS CONNECTIVITY TEST............................................................................................... 26
3.3. TESTING AGAINST THE CHORUS TEST GATEWAY .......................................................................... 26
4. MOVING TO PRODUCTION ............................................................................................ 27
5. PAYLOAD DATA ........................................................................................................... 27
6. TROUBLE SHOOTING ................................................................................................... 28
7. SECURITY................................................................................................................... 28
7.1. MESSAGE ENCRYPTION ...................................................................................................... 28
7.2. NON-REPUDIATION .......................................................................................................... 29

Chorus B2B User Guide
22 May 2009 Page 4
Version 0.4.3 © Copyright Telecom 2009
1. Introduction
1.1.1. Objectives of Manual
The Chorus B2B Gateway is intended to allow Chorus’ customers to access our
products and services utilising a business to business document exchange
mechanism. This User Guide will define the technical steps that should be
followed to allow your business to begin trading with us through our B2B
Gateway.
1.1.2. Contractual Reference
This document is provided to Telecom Partners, Service Companies, Access
Seekers and 3rd party service providers for use alongside the relevant contracts
for service or the relevant Standard Terms Determination.
1.1.3. Use Of The Name Telecom
Throughout this document, Telecom New Zealand is referred to as Telecom.
1.1.4. Limitations
This document does not, in any way, vary the terms of the main contract between
Telecom and the service provider. If there is any conflict between the relevant
contract and statements made in this document, the terms of the relevant
contract shall prevail.
1.1.5. Intended Audience
This document is primarily intended as a technical reference. The intended
audience is:
•Software Architects
•Infrastructure Designers
•Network Engineers
•Security Engineers
•Software Developers
1.2. Related Reference Material
Although the following documents provide related reference material, they may or may
not be referenced directly in this document:
Location Document Title
http://www.chorus.co.nz/industry-
reports Telecom B2B Assure Example XML Messages
http://www.chorus.co.nz/industry-
reports Chorus B2B Fulfill Example XML Messages
1.3. Glossary of Terms Used
The following list describes some of the terms used in this document:

Chorus B2B User Guide
22 May 2009 Page 5
Version 0.4.3 © Copyright Telecom 2009
Term Description
B2B Business-to-Business: electronic communications between two or
more businesses
DSA An algorithm for creating digital signatures
ebMS ebXML Message Service: one of the ebXML protocols utilised by
the Chorus B2B Gateway
ebXML The suite of protocols implemented on the Chorus B2B Gateway
HTTP Hypertext Transfer Protocol: The application layer protocol used
for communicating with the Chorus B2B Gateway
HTTPS Hypertext Transfer Protocol Secure: The combination of SSL/TLS
and HTTP
MSH ebXML Message Service Handler: the Chorus B2B Gateway is an
implementation of a MSH
OSS Operational Support System; computer systems used by
telecommunications service providers
RSA An algorithm for public key cryptography
SHA-1 A digital hashing algorithm
SOAP A protocol for exchanging XML documents via Web Services
SSL Secure Socket Layer (also known as Transport Layer Security):
cryptographic protocol allowing secure communication over the
Internet
XML eXtensible Mark-up Language: the mark-up language utilised by
documents exchanged via the B2B Gateway
XSD XML Schema Definition: expresses the rules to which an XML
document must conform

Chorus B2B User Guide
22 May 2009 Page 6
Version 0.4.3 © Copyright Telecom 2009
1.4. What is the Chorus B2B Gateway?
The Chorus B2B Gateway is a secure and reliable document exchange mechanism that
can be used by your business to exchange business documents with us. The business
documents exchanged will typically be in the form of XML documents.
The Chorus B2B Gateway is based on the ebXML suite of specifications1. The following
ebXML Specifications are utilised by the Chorus B2B Gateway:
•Message Service Protocol: An XML based protocol and envelope structure used for
sending and receiving messages
•Collaboration Protocol Agreement: A format for defining a relationship between
trading partners (e.g. between Chorus and your business) in an XML document
The sections below offer a brief introduction to these specifications, while subsequent
sections will provide specific details on how these specifications are used by Chorus.
1.4.1. Message Service Protocol
The Chorus B2B Gateway is based on the ebMS 2.02message service protocol. This
specification defines the manner in which two or more ebXML based Message Service
Handlers3(MSH) can exchange business documents with the following key features4:
Guaranteed Delivery: Once messages are sent they are guaranteed to be delivered
once and only once.
Non-Repudiation: The identity of the sending party, and the fact that the message has
not been tampered with, can be proven via digital signatures.
Encryption:5Data can be protected to ensure it cannot be viewed by third parties.
You may utilise any ebMS 2.0 compliant ebXML Message Service Handler product when
interacting with the Chorus B2B Gateway. The Chorus B2B Gateway does not utilise any
bespoke features, and is intended to be interoperable across ebMS 2.0 implementations.
This User Guide will provide sample ebXML messages that allow you to verify your
Message Service Handler implementation against the Chorus B2B Gateway
implementation.
1.4.2. Relationship Definition
Before two parties can begin exchanging business documents with each via the ebMS
protocol, they must agree a variety of information that allows their respective Message
Service Handlers to communicate with each other.
1The ebXML specifications are broader than the details presented here. This document will focus solely on the ebXML features
utilised by Chorus.
2The ebMS 2.0 specification, which also provides additional background information, can be found at http://www.oasis-
open.org/committees/ebxml-msg/documents/ebMS_v2_0.pdf
3Message Service Handler (MSH) is the generic term used in this document for a Service capable of sending and receiving
ebXML Messages. The Chorus B2B Gateway is the Chorus Message Service Handler.
4These features are expressed as an extension to the SOAP with Attachments specification. The SOAP envelope contains all the
header information necessary to support these services, while the actual business document being exchanged is added as an
attachment.
5Encryption will be achieved via the use of HTTPS with the Chorus B2B Gateway rather than XML Encryption. Essentially this
moves encryption outside the realmof the ebXML layer, and into the communication layer.

Chorus B2B User Guide
22 May 2009 Page 7
Version 0.4.3 © Copyright Telecom 2009
The ebXML specifications define a manner for capturing this information in a document
called a Collaboration Protocol Agreement (CPA)6. CPA documents are XML documents
conforming to a specified schema.
This User Guide will describe the process to follow in order to obtain a CPA document
from Chorus, and how to understand the contents within the CPA document.
1.5. Assumptions
This guide assumes that
•your business has been accepted to trade via the Chorus B2B Gateway. This guide
will not provide information on legal agreements that must be signed, or accounts
that must be established.
•you have selected a Message Handler System, and implemented it within your
company.
•your business has some background knowledge of the relevant ebXML specifications.
1.6. Support
Any questions relating to the material contained in this User Guide should be emailed to
[email protected].
6The CPA specification is defined at: http://www.oasis-open.org/committees/ebxml-cppa/documents/ebcpp-2.0.pdf

Chorus B2B User Guide
22 May 2009 Page 8
Version 0.4.3 © Copyright Telecom 2009
2. Getting Started
In order to begin communicating with us via the Chorus B2B Gateway, you must
implement an ebMS 2.0 compliant Message Service Handler (MSH). This MSH will
typically be exposed to other applications within your company allowing these
applications to send business documents through it to Chorus, and receive business
documents from Chorus.
The diagram below shows a typical usage pattern for the Chorus B2B Gateway:
1. A user performs an activity in your Operational Support System (OSS). This
activity requires information to be exchanged with Chorus (e.g. Submit Sales
Order).

Chorus B2B User Guide
22 May 2009 Page 9
Version 0.4.3 © Copyright Telecom 2009
2. Your OSS sends a message to your Message Service Handler detailing the
information that needs to be exchanged.
3. Your Message Service Handler sends a message over the Internet to Chorus B2B
Gateway.
4. Our B2B Gateway sends an acknowledgment confirming that the message has
been received.
5. The Chorus B2B Gateway delivers the message to its OSS where the activity
requested is performed.
Messages are returned to your OSS using this pattern in reverse.
All business documents exchanged via the Chorus B2B Gateway will be asynchronous in
nature. Even in cases where a response is required to a submitted document (e.g. Sales
Order Confirmation for a Sales Order Request); this will be sent via a separate
connection. In such cases, we will provide information that allows business responses to
be correlated with business requests.
2.1. Overview
In order to begin using the Chorus B2B Gateway, the following steps need to be followed.
These will be defined in detail in the remainder of this document:
1. Implement and test your MSH internally
2. Provide Chorus with required technical information
3. Provide your security certificates to Chorus
4. Receive CPA documents from Chorus
5. Receive security certificates from Chorus
6. Perform a connectivity test with Chorus
7. Test your MSH against the Chorus Test B2B Gateway
8. Begin using the Production Chorus B2B Gateway
This process is referred to as the on-ramping process. The following timeframes should
be adhered to within this process:
Time Frame Description
2 weeks prior to testing Provide Chorus required information regarding your test MSH.
Provide Chorus with your test security certificate
1 week prior to testing Chorus will provide you a CPA document for use against the Chorus
Test B2B Gateway.
Chorus will provide you their test security certificate for use against
the Chorus Test B2B Gateway.
1 week prior to testing Perform connectivity testing between your test MSH and the Chorus
Test B2B Gateway
4 weeks prior to production Begin testing against the Chorus Test B2B Gateway. This is based on
the assumption that it will take approximately 2 weeks to pass the
tests required to begin using the production B2B Gateway.
2 weeks prior to production Provide Chorus required information regarding your production MSH.
Provide Chorus with your production security certificate
1 week prior to production Chorus will provide you a CPA document for use against the Chorus
B2B Gateway.
Chorus will provide you their production security certificate for use

Chorus B2B User Guide
22 May 2009 Page 10
Version 0.4.3 © Copyright Telecom 2009
against the Chorus B2B Gateway.
1 week prior to production Perform connectivity testing between your production MSH7and
Chorus
2.2. Information Required by Chorus
We require information from you that will be used to create the CPA documents (for both
test and production) defining your relationship with us. The following information is
required:
Information Required Description
Contact Details Contact information for the following resources:
Primary Technical Resource: the person responsible
for all technical issues relating to your MSH and its
integration with the Chorus B2B Gateway
Primary Commercial Resource: the person
responsible for all commercial/contractual issues
The email address for alerts generated from the
B2B Any alerts generated by the Chorus B2B Gateway will be sent to this email address. If this is not
included, alerts will not be sent via email. The list
of alerts that will be sent is described in section 6.
Your preferred testing date The date when you would like to start testing your
Message Service Handler against the Chorus Test
B2B Gateway.
Your preferred production date The date when you would like to start using the
Chorus Production B2B Gateway.
The URL of your B2B Gateway This is the URL that Chorus should utilise for
sending messages to your gateway. A separate
URL can be use during the test phase.
The URL provided must utilised HTTPS rather than
HTTP, since HTTPS is the mechanism that will be
used to implement encryption of messages.
The IP addresses (or addresses) from which your
MSH will send and receive traffic The IP address that will be used for connecting to the Chorus B2B Gateway.
You may provide multiple IP addresses if
necessary. Separate IP addresses may also be
provided for the Test Phase.
This is not necessarily the IP address of the server
hosting your MSH if you are using Network Address
Translation internally; it is the public IP address
Chorus will see when receiving messages from you.
The Algorithm you will use for Signing Messages8Messages must be signed using one of the
following:
DSA with SHA1
RSA with SHA1
Chorus will assume customers will utilise RSA with
SHA1 if no preference is provided.
7This step is only necessary if you are using a separate MSH for your test and production gateways