Use the following steps to install OpenSSL on your local machine.

Use the following steps to generate your certificate and private key.

Use the following steps to verify that your certificate has been created successfully.

Send the certificate to your Implementation Manager for uploading into the Chorus B2B.

To enable messages to be exchanged between our network and yours, the external firewalls on both networks have to be configured to allow incoming and outgoing messages between our B2B gateways.

You need to provide us with all the static public IP address(es) and port number(s), which you will use to initiate and receive messages, and the URL endpoints of your B2B, so that we can allow them on our network.

Our public IP addresses, port, and URL endpoints, which you need to allow, are shown in the following tables.

We use X.509/TLS 1.2 to encrypt the message over HTTP (HTTPS), to set this up in your B2B you need to access our certificates from our URL endpoints. This needs to be done for both emulation and production.

We will retrieve your TLS certificates from your URL endpoints.

The web services validate the SOAP header elements to ensure that messages are signed using security encryption (WS-Security) and that the message diagnostic header elements (MDH) identify the sender. 

Message encryption works as follows:

• Messages you send to us must be signed using your X.509 private key. We will use your public key certificate to verify them.
• Messages we send to you will be signed using our X.509 private key. You will use our public key certificate to verify them.

To set this up we will send you our public key certificates for both production and emulation. And you need to send us your public key certificates.

The certificates must meet x509 standards and we request that you provide them in the PEM file format. You may use Certificate Authority (CA) issued, or self-signed certificates. If you use:

• CA Issued certificates, you need to provide us with the chain certificates (root and intermediate) in addition to your owner certificate.
• Self-signed certificates, and require help generating them, see Generate Self Signed Certificates. This page provides instructions for creating the certificates and the mandatory fields. 

To securely deliver your public key certificates to us, we recommend they are exchanged on physical media like a USB flash drive or by email in a password protected zip file.

The Web Services Security - Message Diagnostic Header page describes the values required in the MDH elements.

To validate the messaging is secure and encrypted, submit a request to one of our web services (e.g. Query Location) and you should receive a response back from us.

Our design allows for messages to be resent automatically during an HTTP network failure. The following diagram provides an overview of the HTTP Application layer retry process

The retry function is set to:

• Delay = 10000 ms
• Max delivery attempts = 3.

If your system responds with a 5xx error rather than an acknowledgement we will only attempt to deliver the message once during each retry scenario. “Note that the retry time, in this case, can be less than 15 minutes if we receive another trigger into our datastore (a response to a request from you).

If your system is unresponsive and provides no response we will time out waiting for your response after 10 seconds and we will attempt to deliver the message 3 times during each retry scenario. The first message that is successfully acknowledged changes the status of your endpoint to available and we will attempt to retry the remaining messages.

Unsent messages are persisted using a data store, this guarantees that they are saved even if a server is restarted.

If you send an acknowledgement with 'LFC001' in the soap error code field we will remove the message from the queue (either response to sequential).

CreateOrderResponse, AmendOrderNotification, InformOrderNotification, CreateOrderNotification are the messages on Sequential Queue.

If the Max delivery attempt count is exhausted, the message will be placed at the head of the queue. The maximum time will be a 15-minute delay before the message delivery retry is restarted. Whether the maximum delay occurs will depend on what the failure was that caused the delivery attempts to fail – see above for details.

This cycle continues until the message is delivered. It ensures that messages are sent in the sequence they are generated. 

QueryPlaceResponse, QueryProductOfferInformationResponse, QuerySiteInformationResponse, QueryOrderFeasibilityResponse, QueryAppointmentResponse, ReserveAppointmentResponse, QueryOrderResponse, AmendOrderResponse, CancelOrderResponse are the messages on Response Queue. 

This queue is for messages where the most recent is considered the most important when the timer retries it will attempt any new messages first before retrying the message that did not receive a valid acknowledgement.

The following order is observed when we place messages on to the Response queue: 

1. State of message i..e, received is sent before an error
2. Priority level where 1 is lowest and 9 is highest
3. Timestamp where latest or fresher messages first

e.g., A received state priority 1 message should be selected prior to an errored state priority 2 message, where 2 has a higher priority than 1. 

Any QueryPlaceResponse, QueryProductOfferInformationResponse, QuerySiteInformationResponse, QueryOrderFeasibilityResponse, QueryAppointmentResponse, ReserveAppointmentResponse, QueryOrderResponse message that fails to be acknowledged after 3 sets of retries will be marked as failed and not retried again.

This queue has 5 concurrent threads per RSP, so messages can be sent in parallel as the order of message delivery is not critical.

Where all attempts are failing the queue is marked as down and will only make reattempts of the message [refer above] until a successful acknowledgement – it will then resume normal processing of messages.

The customer retry strategy is provided to give insight into resending of messages automatically in the case of a network failure on our side. The following diagram provides an overview of a customer HTTP Application layer retry process.

This is an indicative representation of a retry process at the transport level. The way you implement your retry process will not affect us and is solely your responsibility. We recommend that you consult your HTTP library implementations for the default behaviour to understand its configuration capabilities for use when communicating over HTTP.

Our checklist helps to ensure security implementation is made simple.  To improve our customer experience please provide any feedback on our checklist to our Customer Implementation Manager or Service Delivery Manager.

Our B2B Web Services have been built towards industry standards defined by New Zealand's Telecommunications Carrier Forum (TCF), see Background section below for links to the TCF documentation.

Our B2B Web Services uses well established industry standards. The technologies and their current supported versions are described in the following table.

Our B2B Web Services infrastructure will consist of two environments as described in the following table. Each environment is configured separately from one another.

> WSDL and XSD

The WSDL file Chorus-WSDL_version_21.8 replaced by Chorus-WSDL_R23.8 in February 2023.

Customers using B2B and EMMA will need to load the new version of WSDL and XSD.

Download our available WSDL zipfile from here:

Chorus-WSDL_R23.8

> Chorus EMMA Portal Extract

The Chorus EMMA Portal Extract contains the full list of addresses stored in EMMA Portal, in CSV format.

Please see further information described under our emulation environment section.

• Chorus EMMA Portal Extract [CSV, 340.9MB]

> Chorus Product Catalogue EMMA extract

The EMMA product catalogue contains both the EMMA product offer ID and the product specifications and characteristic of all on boarded products and CSEs. 

Please ask your Implementation Manager for your latest EMMA product catalogue file.

Also see further information described under our emulation environment section.

The following table describes the products currently supported by our B2B Web Services.

The basis of our B2B operations is an asynchronous model.  The transport pattern is Request – Acknowledgement (Synchronous) and Response – Acknowledgment (Synchronous).

When you submit a request to a web service (1) we will provide a synchronous acknowledgement of your request (2) at the transport layer.  We will then respond to the message in your request asynchronously. 

When we initiate the response to your request (3) we expect a synchronous acknowledgement from your business at the transport layer (4). 

The following diagram provides a visual aid of our asynchronous model. 

Synchronous versus Asynchronous

TCF Ultra-Fast Broadband BSS/OSS Web Service Design Specification

The following documents and links provide a reference to the industry standards we utilised in the development of our B2B Web Services infrastructure. The documents include the standards and / or the proof of concept for:

• Function points
• On- and off-boarding
• WS-I
• Business Process
• Management
• Interoperability
• Metadata
• Reliability
• Security
• Transactions
• Resources
• Messaging
• XML