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

Date and time values use the xsd:dateTime format: YYYY-MM-DDTHH:MM:SS+[UTC offset, e.g. 12:00].

If an error occurs during the processing of the Message Diagnostic Header the Web Service will return an HTTP 500 error to the user and a SOAP fault message containing:

The following tables contain the common exception messages, refer to standard SOAP specifications for a full set.

The order elements contain Order header information. The following table describes the Order elements.

The following table provides details of the SiteVisit elements.

Order - SiteVisit - type

The following table describes the values provided by the type element.

The following table describes the AppointmentSlot elements.

Order - SiteVisit - AppointmentSlot - dateTime

The following table describes the values provided by the dateTime element.

Date and time values use the xsd:dateTime format: YYYY-MM-DDTHH:MM:SS+[UTC offset, e.g. 12:00].

Service Name

ReserveAppointmentRequest

Service Inputs

The following criteria is mandatory for requesting this service.

Message Handling Specifications

Service Name

ReserveAppointmentResponse

Service Outputs

If valid Order and Site Visit ids were provided, the response will contain the values used in the request and the following SiteVisit elements:

• AppointmentSlot id type
• startDateTime
• endDateTime.

Message Handling Specifications

The order elements contain Order header information. The following table describes the Order elements.

The following table describes the SiteVisit elements.

Order - SiteVisit - type

The following table describes the values provided by the type element.

The following table describes the AppointmentSlot elements.

Order - SiteVisit - AppointmentSlot - dateTime

The following table describes the values provided by the dateTime element.

Date and time values use the xsd:dateTime format: YYYY-MM-DDTHH:MM:SS+[UTC offset, e.g. 12:00].

The following table describes the Filter - FilterParameter elements.

Order - SiteVisit - AppointmentSlot - Filter - FilterParameter - TimeSlot

The following table describes the values provided by the TimeSlot element.

Note: at least one TimeSlot value must be selected to enact this filter.

Date and time values use the xsd:dateTime format: YYYY-MM-DDTHH:MM:SS+[UTC offset, e.g. 12:00].

Order-SiteVisit-AppointmentSlot-Filter-FilterParameterVALIDATE_INTER_APPOINTMENT_LEADTIME

The following table describes the values provided by the VALIDATE_INTER_APPOINTMENT_LEADTIME element.

If this filter is not included in the request, the service will ignore the Inter-Appointment Leadtime rules and return all available appointments (this is the equivalent of selecting 'No').

Service Name

QueryAppointmentRequest

Service Inputs

The following criteria is mandatory for requesting this:

You may restrict the search criteria to a date range using the following the FilterParameter elements:

• TimeSlot
• VALIDATE_INTER_APPOINTMENT_LEADTIME (for SiteVisit appointments only).

Note: if the filter is not selected the maximum range of available appointment slots will be returned using current date plus Default Advance Schedule Duration number of days.

Message Handling Specifications

Service Name

QueryAppointmentResponse

Service Outputs

If valid Order and SiteVisit details were provided, the response will contain the values used in the request and the range of available time slots using the SiteVisit elements:

• startDateTime

• endDateTime.

Appointments are either dates and times a site visit can be performed, e.g. Scope, Install, Install/CSE or CSE or as available RFS dates.

Site visit appointments are returned as morning slots from 08:00 - 12:00 and afternoon slots from 13:00 - 17:00, RFS dates are returned on the hour.

The following tables provide examples of the values.

Morning Site Visit:

Afternoon Site Visit:

RFS dates:

Message Handling Specifications

The following table describes the BillingInformation elements.

The following table describes the values provided by the Charge element.

-- Order - BillingInformation - Charge - category

The following table describes the values provided by the category element.

-- Order - BillingInformation - Charge - ChargeType

The following table describes the values provided by the ChargeType element.

The following table describes the EscalateOrder elements.

-- Order - EscalateOrder - EscalationReason

The following table describes the values provided by the escalationReason element.

-- Order - Reason

The following table describes the values provided by the Reason element.

The following table provides the mapping for the new code and description values released on the 15th of August 2016.

In addition to the current Order - OrderItem elements and values the inform and amend order notifications will include the following OrderItem elements where appropriate.

The following table describes the Timing elements.

-- Order - OrderItem - Timing - name

The following table describes the values provided by the name element.

The following table describes the SiteVisit elements.

-- Order - OrderItem - SiteVisit - type

The following table describes the values provided by the type element.

> Order - OrderItem - SiteVisit - AppointmentSlot Elements

-- Order - OrderItem - SiteVisit - AppointmentSlot - dateTime

The following table describes the values provided by the dateTime element.

-- Order - OrderItem - Question

The following table describes the values provided by the Question element.

-- Order - OrderItem - Question - questionValue

The following table describes the values provided by the questionValue element.

-- Order - OrderItem - Quote Elements

The following table describes the values provided by the Quote element.

The following table provides details of the Notification elements.

-- Notification - type

The following table describes the values provided by the type element in InformOrderNotification messages.

The following table describes the values provided by the type element inAmendOrderNotification messages.

-- Notification - NotificationItem

The following table provides details of the NotificationItem elements.

Details of the notification items provided by the Inform Order Notifications the are described here.

Note: this type of notification is not used to notify you of an order state or substate change.

-- Notification - NotificationItem

The following table describes the values provided by the STATUS NotificationItem elements.

-- Notification - NotificationItem

The following table describes the values provided by the STATUS_WITH_NOTE NotificationItem elements.

-- Notification - NotificationItem

The following table describes the values provided by the MANUAL_INTERACTION NotificationItem elements.

-- Notification - NotificationItem

The following table describes the values provided by the REJECT_CANCEL NotificationItem elements.

Details of the state and substate changes and the notification items provided byAmendOrder Notifications the are describedhere.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - ACKNOWLEDGED_ACCEPTED.

-- Notification - NotificationItem

The following table describes the values provided by the ACKNOWLEDGED_ACCEPTED NotificationItem elements.

-- Notification - NotificationItem

The following table describes the values provided by the RFS_CONFIRMED NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - CONSENT_REQUIRED.

-- Notification - NotificationItem

The following table describes the values provided by the CONSENT_REQUIRED NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - CONSENT_REQUESTED.

-- Notification - NotificationItem

The following table describes the values provided by the CONSENT_REQUESTED NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - CONSENT_GAINED.

-- Notification - NotificationItem

The following table describes the values provided by the CONSENT_GAINED NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - CONSENT_DECLINED.

-- Notification - NotificationItem

The following table describes the values provided by the CONSENT_DECLINED NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - GENERATE_QUOTATION.

-- Notification - NotificationItem

The following table describes the values provided by the GENERATE_QUOTATION NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - INTENT_TO_CANCEL.

-- Notification - NotificationItem

The following table describes the values provided by the INTENT_TO_CANCEL NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - IN_PROGRESS_INTENT_TO_CANCEL.

The following table describes the values provided by the IN_PROGRESS_INTENT_TO_CANCEL NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - NETWORK_DESIGN.

-- Notification - NotificationItem

The following table describes the values provided by the NETWORK_DESIGN NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - NETWORK_BUILD.

-- Notification - NotificationItem

The following table describes the values provided by the NETWORK_BUILD NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - SCOPING_SCHEDULED.

-- Notification - NotificationItem

The following table describes the values provided by the SCOPING_SCHEDULED NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - SCHEDULED.

-- Notification - NotificationItem

The following table describes the values provided by the SCHEDULED NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - INVESTIGATION_REQUIRED.

-- Notification - NotificationItem

The following table describes the values provided by the INVESTIGATION_REQUIRED NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - QUOTE_ACCEPTANCE.

-- Notification - NotificationItem

The following table describes the values provided by the QUOTE_ACCEPTANCE NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - HELD_SCHEDULE_SCOPING.

-- Notification - NotificationItem

The following table describes the values provided by the HELD_SCHEDULE_SCOPING NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - HELD_SCHEDULE_INSTALL.

-- Notification - NotificationItem

The following table describes the values provided by the HELD_SCHEDULE_INSTALL NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - HELD_PROVIDER_TO_ADVISE.

-- Notification - NotificationItem

The following table describes the values provided by the HELD_PROVIDER_TO_ADVISE NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - HELD_PENDING_DISCONNECT_ACCEPTANCE.

-- Notification - NotificationItem

The following table describes the values provided by the HELD_PENDING_DISCONNECT_ACCEPTANCE NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - SERVICE_GIVEN.

-- Notification - NotificationItem

The following table describes the values provided by the SERVICE_GIVEN NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - COMPLETED_BILLING.

-- Notification - NotificationItem

The following table describes the values provided by the COMPLETED_BILLING NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - CLOSED_CANCELLED.

-- Notification - NotificationItem

The following table describes the values provided by the CLOSED_CANCELLED NotificationItem elements.

The following table provides the OrderItem state and substate associated with the AmendOrderNotification - Notification - type - CLOSED_COMPLETED.

-- Notification - NotificationItem

The following table describes the values provided by the CLOSED_COMPLETED NotificationItem elements.

-- Notification - NotificationItem

The following table describes the values provided by the SVM_EVENT NotificationItem elements.

> SVM Event Description

The following descriptions are used to describe the result of changes to the site visit scoping and/or install appointments.

-- Notification - NotificationItem

The following table describes the values provided by the ESCALATION_ACCEPTED NotificationItem elements.

-- Notification - NotificationItem

The following table describes the values provided by the ESCALATION_COMPLETED NotificationItem elements.

-- Notification - NotificationItem

The following table describes the values provided by the ESCALATION_DECLINED NotificationItem elements.

-- Notification - NotificationItem

The following table describes the values provided by the AMEND_ORDER_COMPLETED NotificationItem elements.

The following codes are used to describe the result of appointments, and are sent using the relevant Notifications message, e.g. SVM_EVENT includes this along with other descriptive information in the NOTIFICATION_TEXT.

Service Name

• InformOrderNotification
• AmendOrderNotification

-- Service Outputs

Notifications contain the current order details and notification values. The following tables lists key information that is included with some notification types.