Assurance API

1.9.x
(0 reviews)

How to use the API

This page describes how different parts of the Assurance API operate, and how each part can be used.

For more information, refer to the RAML in Anypoint.

Overview

The Assurance API provides end-to-end fault diagnosis and problem management. This API calls all available details of your product instance up front to drive the workflow including service validation, fault diagnostics, outage correlation, and a process for booking appointments and submitting and updating problem reports.

The sections below describe how to use the API to manage a fault end-to-end.

Subscriptions and Notifications

The Assurance API includes the ability to set up subscriptions to be notified with updates to problem reports and events. A subscription URL is provided, or you can specify a target URL for delivery of notifications.

Subscriptions can be updated, deactivated and deleted.

Because of the asynchronous nature of problem report updates and status changes it may be helpful to subscribe to a notification instead of polling for updates.

For the following:

  • Submit a subscription request - call POST /subscribers with a secret key and a webhook url, which will be used to POST notifications to.
  • Validate the webhook URL endpoint - provide a GET endpoint at the webhook url to receive a challenge querystring value, which must be echoed in the GET response.

Get Products

The Get Product API call enables the initiation of a troubleshooting session for a Chorus service.

The Get Product API call queries Chorus inventories including the Chorus address database, product inventories, and problem reports to retrieve all available information for the Product Identifier supplied. The response will depend on the type of product, and whether we hold full inventory. Information about our different product types are held in the Product Details section below.

Step Role Action Description
1. API Consumer Get Product Call Assurance API GET /products/{productid} method using a Chorus product identifier.
2. Assurance API Validate Service The API will validate the service including that the service is active and that the service is owned by the initiating RSP (or sub-entity).

If the service is inactive
Then an API error response is returned.

If the requestor is not authorised to access the information
Then an API error response is returned.

If the API consumer has entered an invalid identifier
Then an API error response is returned.
3. Assurance API Query inventory The API queries inventory for Product Service Details.

If the product is validated
Then where we hold full details of your product instance in our inventory, all information is returned.

If the product is partially validated
Then where we hold partial details of your product instance in our inventory, the information we have available is returned.

If the product is unvalidated
Then where the product type is unavailable in our inventory and we are unable to validate the product, the Product Types Possible list is also returned.
Details include:
  • A message describing the unvalidated product
  • Available Product Types for the supplied Product Id which can be used for subsequent diagnostics and problem report submission
  • Product Category Type – Generalised product categorisation used for grouping
4. Assurance API Query inventory The API will return details applicable to the type of service.

If the product is Copper
Then the API will also return:
  • DSLAM information
  • Port information
If the product is Fibre
Then the API will also return:
  • OLT and ONT objects
  • Fibre voice services
  • Plan objects
If the product is Complex
Then the API will also return:
  • Access type
  • Exchange ID
  • Glass mode
  • Wire Mode
If the product is an RGW
Then the API will also return:
  • Wi-Fi service details
5. Assurance API Query address / orders / problem reports The API queries other inventories to return additional information available for the product instance to support fault diagnosis and resolution.
  • Address details
  • Supported test types
  • Open orders
  • Problem Reports (the last 3 months’ worth)

Updating WAN Configuration

When updating WAN configuration, please note the following regarding the optional ipMode parameter:

  • GET /products/{productid}/wan response may or may not include the optional ipMode parameter
  • If the parameter is included, and the value is 1, then the IP mode is IPV4 only and the IPV4 attributes will be returned.
  • If the parameter is included, and the value is 3, then the IP mode includes IPV4 and IPV6. Attributes will be returned for both.
  • If the parameter is NOT included, the device is assumed to be IPV4 and IPV4 attributes will be returned.

When updating the WAN configuration using PUT /products/{productid}/wan, please note the following:

  • If the ipMode parameter was NOT present in the GET call then it MUST NOT be included in the PUT call. As ipV4 mode is assumed the ipV4 object MUST be present in the PUT call.
  • If the ipMode parameter was present in the GET call, then ipMode parameter MUST be present in the PUT call. If new value is 1 or 3 , then the ipV4 object MUST be included, If the new value is 3, then the ipV6 object MUST also be included.

Diagnostics

The POST sessions API call enables the initiation of a diagnostic session. Where available, the Assurance API will run the default test(s) and return results applicable to the product type submitted.

Where a product is unvalidated, the product type must be specified when posting a diagnostic.

Where no default test exists for the product type, then other factors such as any open problems are used to diagnose the fault.

Because of the asynchronous nature of the diagnostics, the time it takes to run a diagnostic depends on two factors:

  1. Time for the Diagnostic API to respond. The Diagnostic API should respond within 4-10 seconds.

  2. Time for the actual test to complete running. This time depends on the type of test. Indicative average times for each test are listed below:

    • ONT Status, 10 seconds or less
    • Single Line Test, 32 seconds or less
    • Line State Diagnosis, takes 15 seconds or less
    • Electrical Test, 50 seconds or less
    • Wi-Fi information, 30 seconds or less

Based on these average response times, polling for a result should be set at a frequency of no less than 10 second intervals or alternatively subscribe to be notified when the diagnostic results are ready.

  • Diagnostics sessions timeout after one hour of update inactivity on the session.
  • It is possible to cancel a diagnostic using the Cancel Diagnosis API call. This call should only be used if incorrect information such as an incorrect product type has been submitted when posting the diagnostic.
  • A diagnostic session concludes with the return of a fault type and associated next steps that can be used in the submission of a problem report.

The table below describes the diagnostic process.

Step Role Action Description
1. API Consumer Submit a diagnostic request / Post Diagnosis (Initiate Diagnostics Session) The Post Diagnosis API call / request initiates default diagnosis action for the product type.

For unvalidated services, the product type is required in the request.
2. Assurance API Return diagnostic The Assurance API will return:
  • Diagnostic session identifier
  • Product Service details
  • Actions
  • Fault Types
  • Questions
3. Assurance API Run diagnostic The Assurance API will run the default test applicable to the product type submitted and query open problem reports, to assist with fault diagnosis.

Note:
Diagnostics sessions will timeout after one hour of update inactivity on the session.
4. API Consumer Retrieve a diagnostic Use the diagnostic session identifier to retrieve the results of a diagnostic.
5. API Consumer Determine next step The API consumer determines and decides the next step.

If diagnostics has identified a fault
Then use the fault type to begin problem report submission.

If a problem is already open for the product instance
Manage the open problem report.

Log a Problem Report

The Post Problem Report API call enables an API consumer to submit a problem report into the Chorus ITSM tool.

Diagnostics must have been completed prior to submitting a problem report and submitting a problem report will trigger the completion of the diagnostic session.

Problem report submission includes completing appointment details where required and answering mandatory questions. Non mandatory questions should to be supplied in a problem report submission to ensure Chorus has all supporting information to aid the resolution process.

The table below describes the problem report logging process.

Step Role Action Description
1. API consumer Post Fault Type Problem report submission starts with the API consumer posting a fault type.
2. Assurance API Return Problem Submission details Depending on the product and fault types posted, the Assurance API returns all the details required for submission of a problem report including the applicable question sets.
3. API consumer Book Appointment If an appointment is required, then the API consumer follows the Book Appointment flow.
4. API consumer POST Problem Report The POST Problem Report API call enables the API consumer to submit a problem report.

This results in the submission of a problem report into the Chorus ITSM tool and completion of the diagnostic session.
5. Assurance API Return Problem Report Details The Assurance API returns problem report details.
6. API Consumer Get Problem Report The Get Problem Report API call enables an API consumer to retrieve a full problem report.

Provides details of a specific problem report and any updates that have been made during its lifecycle.

Book Appointment

The Query Schedule call queries the Chorus workforce management source to return details of available appointments for products / fault types that require a booking with a service company technician.

Appointment availability is based on the SLAs associated with the product and fault type, and the availability of technicians with the required skill set.

The three booking types are described in the table below.

Type Description
1. ASAP ASAP (earliest available appointment) is available for all products.
Note:
  • If no appointment type is specified, the ASAP slot is automatically assigned.
  • If using non-UCLL products, then ASAP is the only option available.
  • For layer 1 ASAP appointments, use the enumeration BY.
  • For layer 2 ASAP appointments, use the enumeration ASAP.
2. Request an appointment Use the request an appointment option for all layer 2 products.
Note: It is not available for layer 1 products.

Appointment requests use the enumeration BET.
3. Confirmed appointment (look and book) The look and book confirmed appointments are only available for layer 1 UCLL products including SLES, SLU MPF and UCLL MPF.

Confirmed appointments use the enumeration BET

The table below describes the process for booking an appointment.

Step Role Action Description
1. API Consumer Get Schedule Use the Get Schedule API call to retrieve a schedule.

The API consumer must specify the work division and either the Exchange ID for layer 2 products or the TLC for layer 1 products.
2. Assurance API Return Schedule The Assurance API will return the applicable schedule.
3. API Consumer Post Reservation Post a Reservation.

If ASAP
Then for layer 1, use the enumeration BY.
And For layer 2, use the enumeration ASAP.

If reservation Request
Then use the enumeration BET.

If confirmed Reservation
Then use the enumeration BET.
4. Assurance API Return Reservation The Assurance API will return details based on the type of reservation.

If ASAP


If reservation Request
Then reservation requests are confirmed after problem report submission as a system status update.

If confirmed Reservation Then a confirmation and reservation ID is returned.

Manage Problem Reports

Once a problem report has been logged with Chorus, an API consumer can manage the problem using the Update, Amend, Close and Cancel functions described below.

Note: Problem Report payloads will vary between products.

Assurance API Aspect How it works Exceptions / scenarios and notes
Update Problem Report Enables an API consumer to update a problem report. This call appends progress updates to the problem report. Problem reports with a status of closed can’t be updated.
Amend Problem Report Enables an API consumer to amend the editable details originally submitted in a problem report. This is different to updating a problem report which provides a journal update of activity.

Problem reports with a status of closed can’t be amended.
Close Problem Report Enables an API consumer to close a problem report if the problem status is Service Given. An RSP can only close a problem report when the status is Service Given.

Problem reports will auto-close within 48 hours of Service Given. The close problem report call is optional.
Cancel Problem Report Enables an API consumer to submit a cancellation request for a problem report.

Depending on the status and history of the problem report the report will either be:
  • Cancelled automatically
  • Referred to our Assure team for review and manual cancellation
  • Rejected

Query Problem Reports

The Query Problem Reports API call enables an API consumer to query current and up to 12 months of historical problem reports, and have results returned based on selected input criteria.

The API consumer can specify a sort order, ascending or descending for each field.

Results are paginated with a maximum of 50 records per page.

Assurance API Aspect How it works Exceptions / scenarios and notes
Query Problem Reports Enables an API consumer to query problem reports using the following input criteria:
  • status
  • closureCode
  • serviceProviderProblemNumber
  • updateDate
  • createDate
  • productId
  • notStatus
Query Problem Reports status

Returns all Problem Reports with the Problem Report status or statuses specified (comma delimited).

Displays as ProblemReport Status. 		Status are:
  • Open
  • Accepted
  • Request for information
  • Pending cancel
  • Assigned
  • Scheduled
  • In progress
  • Service Given
  • Completed
  • Closed
Query Problem Reports

closureCode 		closureCode

Returns all Problem Reports with the specified impact value.

Displays as ProblemReport Closure / Status Reason.
Query Problem Reports

serviceProviderProblemNumber 		serviceProviderProblemNumber

Returns all ProblemReports related to the customer reference.

Displays as Customer Reference.
Query Problem Reports

updateDate 		updateDate

Returns all Problem Reports with the specified Last Updated Date.

Expects yyyy-MM-ddTHH-mm-ss format.

Displays as ProblemReport Last Updated Date.
Query Problem Reports

createDate 		createDate

Returns all Problem Reports with the specified Created Date.

Expects yyyy-MM-ddTHH-mm-ss format.

Displays as ProblemReport Created Date.
Query Problem Reports

productId 		productId

Returns all Problem Reports related to the service number / service identifier.
Query Problem Reports

notStatus 		notStatus

Returns all Problem Reports without the Problem Report status or statuses specified (comma delimited).

Displays as ProblemReport Status.
Query Problem Reports

sort 		sort

Sort results by one or multiple named fields and for each field specify ascending or descending order. Use a colon to specify the sort order. 		(ProductId, productTypeId, problemNumber, serviceProviderProblemNumber, status, createDate, updateDate, scheduleDate).

Product Details

The tables below show the characteristics of each product throughout the Assurance API process flow.

Business Complex
Product Name Validation Product Identifier type Range Example Default Tests
UBA Backhaul Fully Validated Circuit ID 100****** /101******/120****** 100860890 None
UCLL Backhaul 100****** /101******/120****** 100555373
Asynchronous Transfer Mode 16**** / 19**** to 57**** /100******/120****** 100435721
Digital Data Service 100******/120****** 100435721
Frame Relay 48*** to 16**** / 19**** to 57**** / 100****** 100435721
Handover Links 100******/120****** 100435721
HSNS Lite Copper 100******/120****** 120687053
HSNS Lite Fibre 100******/120****** 100559574
HSNS Premium 100******/120****** 100559574
Megalink Service 100******/120****** 100435721
Metro IP Service 100******/120****** 100435721
One Office Service 100******/120****** 100435721
Baseband
Product Name Validation Product Identifier type Range Example Default Tests
Baseband IP Fully Validated ASID 1617******/3*******/4*******/
6*******/7*******/9*******		 1617000092 Electrical Loop Test
Baseband Copper Fully Validated ASID 1625****** 162589456 None
UCLL
Product Name Validation Product Identifier type Range Example Default Tests
SLES Fully Validated ASID 1622******/1692****** 1622200438 None
SLU MPF 1622******/1692****** 1622200438
UCLL MPF 1622******/1692****** 1692200438
DSL
Product Name Validation Product Identifier type Range Example Default Tests
Basic UBA Fully Validated ASID 1624******/1634******/1684******/
1690******/1694******		 1624894562 LSD
Enhanced UBA 1624******/1634******/1684******/
1690******/1694******		 1624894562
VDSL 1624******/1634******/1684******/
1690******/1694******		 1624894562
PSTN and Spark Voice
Product Name Validation Product Identifier type Range Example Default Tests
Business Line Fully Validated POTS number 3*******/4*******/6*******/
7*******/9******* 		31976490, 45678342, 69277563, 72864017, 95248141 Single Line Test
Centrex 3*******/4*******/6*******/
7*******/9******* 		31976490, 45678342, 69277563, 72864017, 95248141 None
Home Line 3*******/4*******/6*******/
7*******/9*******		 31976490, 45678342, 69277563, 72864017, 95248141 Single Line Test
ISDN Basic Rate Access 3*******/4*******/6*******/
7*******/9*******		 31976490, 45678342, 69277563, 72864017, 95248141 None
ISDN Primary Rate 3*******/4*******/6*******/
7*******/9*******		 31976490, 45678342, 69277563, 72864017, 95248141 None
Toll Free Service Not Validated POTS number 800******/508****** 800225598 None
NGA Layer 2
Product Name Validation Product Identifier type Range Example Default Tests
NGA Bitstream 3/3a Partially Validated Product ID 1621******/1636******/1637****** 1621260132 ONT Status
NGA Bitstream 2 Product ID 1621******/1636******/1637****** 1636284947 ONT Status
NGA Business - eDMR ASID 1621******/1636******/1637****** 1621287540 None
NGA Business - Point to Point ASID 1621******/1636******/1637****** 1621200438 None
NGA Small Business Fibre ??? 1621******/1636******/1637****** 1621200438 None
eDMR Backhaul ASID 1621******/1636******/1637****** 1621287540 None
NGA Bitstream 4 Not Validated Product ID 130****** 1306284947 ONT Status
NGA Layer 1
Product Name Validation Product Identifier type Range Example Default Tests
Bandwidth Fibre Access Not Validated Circuit ID / Path ID 17****/18****/**/***/****/10,000 to 47,999/300****** 182150, 345, 2352 None
Chorus Regional Transport 17****/18****/**/***/****/10,000 to 47,999/300****** 182150, 345, 2352
Direct Fibre Access 17****/18****/**/***/****/10,000 to 47,999/300****** 182150, 345, 2352
Intra Candidate Area Backhaul 17****/18****/**/***/****/10,000 to 47,999/300****** 182150, 345, 2352
Co-Location
Product Name Validation Product Identifier type Range Example Default Tests
Commercial Co-Location Not Validated FBN 1633***** 163302602 None
UCLL Co-Location 1633***** 163302602

Events

View event notifications for all planned and unplanned Chorus network events, for all of your Chorus services. The table below describes the objects returned for events and provides context for some of the information returned.

Assurance API Aspect How it works What it can be used for
View Events Queries the network events repository and returns details of future planned, current and recent planned and unplanned Chorus events. Use as a single source for all Chorus future planned, current and recent planned and unplanned event information.
View Event Impacts Queries the network events repository and returns details of future planned, current and recently planned and unplanned Chorus events mapped to Chorus products.

View event impacts and match impacted services to your customers, along with inbound interactions. 		Use this to match events to impacted services to your customers, along with inbound interactions. This allows you to pro-actively manage outages and your customers' expectations more effectively with the goal of reducing unnecessary calls into your operational teams.

Reviews