Connect Orders

Placing an Order:

To place an order, a post request must be made to the order.create endpoint.

Pre-requisites#

1. Location Search (optional)#

If you don't already know the location ID of the address that you want to connect a service, you will need to perform a location search. This will allow you to find the correct location ID for the location you want to place the order at.

If you already have the location ID, this step won't be required.

2. AVC ID (only for transfers)#

For NBN transfers (where an existing service is already active at the location and needs to be transferred) you must obtain the AVC ID from your customer of the service requiring transfer.

The AVC ID should be sent in the Service Qualification (see below) and a transfer will only be accepted for the relevant location + infrastructure combination, where the SQ has indicated that the provided AVC matched the service on the same infrastructure.

3. Service Qualification (required)#

An order cannot be submitted without a valid and current service qualification (SQ).

Perform a service qualification for the location ID. The results of the service qualification will significantly determine what the ordering requirements are for that location, as it will assess what products and infrastructure are currently available at the location and what options exist for ordering those products and potentially installing additional or replacement infrastructure.

You will be required to pass the ID of the relevant SQ result when submitting the connect order.

Service Qualification results expire and once expired, cannot be used in an order. If you attempt to submit an order with an expired SQ, it will fail validation. You should perform a new SQ and attach that instead. Currently SQ results expire 2 hours after creation, but this may be subjec to change. Other factors also affect the expiry time of SQ results (e.g. if an order is submitted/completed for the same location ID etc.)

See the Service Qualification section for information on how to interpret the SQ result.

Appointment Management#

Where a professional installation is required to complete the order (e.g. new infrastructure, subsequent install, upgrade NTD etc.) an appointment of the correct demand type is required in order to place an order with the upstream provider.

Nitrogen provides 2 options for managing appointments for a new order:

Auto Appointment Booking#

You may opt to have your Nitrogen partner account enabled for auto appointment booking.

If this is enabled, you are not required to pre-reserve or attach an appointment to your connect orders. Upon receiving an order that requires an appointment, Nitrogen will automatically determine the correct type of appointment, request available timeslots and reserve the first available timeslot as an appointment. This appointment will then be automatically attached to the order when it is submitted to the upstream provider. Once the provider validates and accepts the order, the appointment will be confirmed (status: Booked) and Nitrogen will send the relevant appointment callbacks to your subscribed endpoints if applicable.

Auto booked appointments are only automated during the initial order submission. Management of the appointment such as reschedule, cancel etc. is then handled via the appointments API.

Tenants with auto appointment booking enabled can still pre-reserve their own appointment and attach it to the order if desired. The auto appointment booking will only occur when the tenant hasn't reserved and attached the appointment.

Manual Appointment Booking#

If your account does not have auto appointment booking enabled, you will need to identify scenarios requiring an appointment and manage reserving your own appointments via the Appointments API before submitting an order.

In this case, orders without a valid, reserved appointment attached to them which require an appointment will not have any automated appointments completed for them.

Appointments In Connect Payload#

If you are passing an appointment in with your order payload, you should pass the uuid of the appointment in the bookedAppointmentId field.

   {
      "bookedAppointmentId": "019a7f60-5189-7ac2-91e4-e63c497efaeb",
   } 

If the appointment is not in the correct status or the correct type of appointment, the order will be rejected, or you will be sent a notification requesting a new appointment be attached to the order.

Fibre Connect Upgrades#

For NBN locations currently on a copper technology, many of them are eligible for a free upgrade to full fibre under NBN's Fibre Connect upgrade program.

Eligible locations will show alternativeTechnology as Fibre when you preform a Standard service qualification and receive a copper service class in response.

To commence the ordering process for a Fibre Connect upgrade, you should perform another SQ with the same location, but the sq type of NFAS. If the location is eligible for Fibre Connect, this SQ will show a Fibre service class with no infrastructures, and you can submit the order using the NFAS SQ to commence the Fibre Connect ordering process at that location.

If your tenancy has auto managed appointments (see above), Nitrogen will book an appropriate appointment automatically. If you manage your own appointments, you will be required to reserve an appointment and attach it to the order.

Order Create Payload#

Order Types#

1. New Service#

If you specify an infrastructure id (and port if required) that does not currently have an active service on it or request for the service to be placed on new infrastructure (e.g. subsequent install or service class without infrastructure installed yet), your order will be considered a new service order.

This is used when you want to create a new service, not attempting to transfer an existing service.

2. Transferring An Existing Service#

If ordering a service on a line or infrastructure port that has a current active service then Service Transfer details will be required on the order.

Service Transfer#

When transferring an existing service, send the transferType field as SERVICE_TRANSFER and ensure you include the AVC ID of the service you are transferring in the avcId field:

   {
      "infrastructureId": "NTD111111111111",
      "portId": 1,
      "transferType": "SERVICE_TRANSFER",
      "avcId": "AVC0000009999999"
   }

The above payload will be for a transfer of the service on port 1 of NTD with id NTD111111111111 where that service has a matching AVC ID AVC0000009999999.

The AVC ID provided in the order payload must match the AVC ID that was sent in the linked service qualification and the service qualification result must have indicated a match on the the avc id for the exact infastructure that you are placing the order on. The order will be rejected if this is not the case.

Connect Outstanding#

IMPORTANT

Connect Outstanding must be used sparingly and only in cases where you have genuinely collected evidence to ascertain that the end customer is the resident at the location on which you are attempting the transfer and they are unable to obtain the AVC ID. ABB/NBN will require this evidence to be provided upon request at any time, to verify that the use of connect outstanding was legitimate.

In cases where the customer is unable to provide the AVC ID of an active service, usually because they are a new resident and the previous resident has not yet disconnected their service the transferType field should instead be set as CONNECT_OUTSTANDING in order to allow the new service to 'take over' the existing active service on the infrastructure instance that contains an active service.

   {
      "infrastructureId": "NTD111111111111",
      "portId": 1,
      "transferType": "CONNECT_OUTSTANDING",
      "avcId": null
   }

The above payload will be for a new service on port 1 of NTD with id NTD111111111111 where an existing service already exists and is to be replaced by the new service.

Product Offer Object#

In the service qualification result a list of available product offer IDs will be present in the availableProducts section of the SQ response. This list of product offers are products that should be available to order at the location, subject to further validation during the ordering process.

For NBN/broadband product types (currently the only type of product available), there is a different product offer for each relevant download/upload speed combination. Furthermore, each product has a defined set of components that are available by default, and in some cases, as additional component options that can also be selected. (e.g. upstream provider restoration SLAs, different types of IP addresses etc)

To retrieve information about your tenancy's currently available product offers, including all supported component types and default/available options per component type, use the product catalog endpoint to retrieve a list. This will provide you with the information required to submit a valid order for the product offer and its components.

A product offer definition is made up of a primary component (e.g. NBN broadband) and zero or more secondary components. The secondary compoments may be required or optional, and this will be specified in the product catalog response for the product offer.

To specify which product offer you would like to order and which options for each component, you include a produtOffer object in your order payload.

The product offer object in an order does not need to have the primary component specified (in fact, it will fail validation if it is) since it is the standard component that comes with the product offer. The secondary components are to be specified in the payload.

The components marked as required: true in the product catalog response MUST be specified in the product offer components array, even if you are requesting the default option. The components marked as required: false can be optionally included - leaving them out will result in that component not being applied to the order at all.

Example Product Offer Object#

   {
      "productOffer": {
          "id": "019a77da-9d15-740e-ba98-a6d814c85eff",
          "components": [
              {
                  "type": "restoration_sla",
                  "option": "standard"
              },
              {
                  "type": "ip_address_v4",
                  "option": "static"
              }
          ]
      }
   }

In the above example, we're requesting to order product offer id "019a77da-9d15-740e-ba98-a6d814c85eff" with a standard restoration SLA and a static ipv4 address.

Infrastructure#

Details of infrastructure available at a location will be found in the Service Qualification results.

Each available infrastructure element (i.e. Network Termination Device (NTD) or Copper Pair (CPI)) will be listed in the service qualification's infrastructures array and will contain information about the status of the infrastructure and capacity, type etc.)

If there is no Infrastructure ID provided the order will proceed as a subsequent install, if available at that location, otherwise the order will be rejected.

When requesting a subsequent install, the installation type specified must be listed in the SQ.

Infrastructure Replacement & High Speed Capacity#

In some cases, where NTD technology is present at the location it may be possible to request an NTD to be upgraded to a different NTD type (additional costs may apply).

The types that are available as upgrade options for a particular infrastructure (if any) will be listed in the infrastructureUpgradeOptions array within the infrastructure object.

Sometimes a product offer's bandwidth may exceed the available capacity on an existing NTD. In that case, the product offer will be present in the productsRequiringInfrastructureUpgrade arrays under the infrastructure object. If the product offer you are ordering is present in this array, your order payload MUST include a valid NTD upgrade type.

Ordering an infrastructure upgrade#

If you would like to replace an existing NTD with a valid upgrade version, you should specify the infrastructureId AND the infrastructureUpgradeType together in the payload:

Example Payload With Upgrade#

   {
      "infrastructureId": "NTD111111111111",
      "infrastructureUpgradeType": "FTTP_4_PORT_V4"
   }

The above example payload will trigger an upgrade to be initiated as part of the order, to replace existing NTD with id NTD111111111111 with a new FTTP 4 port V4 NTD.

Example Payload With No Upgrade#

   {
      "infrastructureId": "NTD111111111111",
      "infrastructureUpgradeType": null,
      "portId": 2
   }

The above example payload will NOT trigger any NTD upgrade. It will attempt to place the service on port 2 of the existing NTD with id NTD111111111111.

Install and Dispatch#

Installation Options#

Use the ntdInstallation field to indicate what type of installation you would like to have for the service to be installed.

You should default this field to no-action when you are installing the service on existing infrastructure.

Where new infrastructure is required (e.g. subsequent installation or location doesn't yet have infrastructure) or an infrastructure upgrade is being requested, the available installation types will be listed in the service qualification. You will not be able to choose an install option that is not listed.

Pass tech for a technician to install the required infrastructure, this will require a valid appointment.

If a self install kit is available to be installed, you can instead pass dispatch as the installation type and a self install device will be delivered to the user instead of a technician appointment. This is not available at all locations.

Dispatch Options#

Where your selected ntdInstallation option is dispatch, you must also send the dispatchOptions in the payload, with valid delivery details for the device to be shipped to.

If the delivery address is the same as the location of the service then sameAddressAsLocation can be set to true and the other address will not be required.

If sameAddressAsLocation is not present or false, then the address object will be required.

The contact name and phone number field is always required to ensure the delivery provider can contact the end user if required.

Authority to leave the parcel can be provided and will result in the s well as any additional instructions for delivery.

Service Configuration Object#

Configuration of the service is achieved via the serviceConfiguration object. You pass the initial values in the connect order and can later modify the service's configuration using a similar data structure in the modify order.

Unlike the product offer object, the service configuration does not have to have all its items explicitly provided in the connect payload. Any parameters that are not provided, will be set to their defaults.

The service configuration is made up of the following parameters (The layer 3 options object contains options that are applicable only to layer 3 broadband product types):

DSL Stability Profile#

Possible Values: standard or stable

Default: standard

For copper line services, applying a stability profile can sometimes help with troubleshooting issues.

Most services would have the standard profile applied, and this is the default for all services.

In order to apply a stable profile, this would be passed as stable instead.

It would not be recommended to apply a stable profile for a connect order, as it is usually meant for troubleshooting after a service has problems.

Layer 3: Auth Method#

Possible Values: ipoe or pppoe

Default: ipoe

The method that a layer 3 service will use to connect.

IPoE (Internet Protocol over Ethernet) is the default and preferred method and uses DHCP, therefore not requiring the end user to input a username and password into their CPE.

PPPoE (Point-to-Point Protocol over Ethernet) is an option that can be supported by the network, but requires the users to add a username and password into their CPE.

Layer 3: Apply Shaping Restriction#

Possible Values: Boolean true or false

Default: false

Allows the tenant to adjust the shaping on a service from its provisioned speed to a much lower speed. Would generally be used for applying a restriction due to end user non payment suspension etc.

When set to true, the service will be shapped to 1mbps down and 1mbps upload.

Layer 3: Unblock Ports#

Possible Values: Boolean true or false

Default: false

For security reasons, some standard ports are blocked by default, to prevent user traffic on known ports that shouldn't generally be expected from a regular user service.

When port blocking is enabled (default) the following ports are blocked:

OUT:

• SMTP (except to ABB SMTP servers)
• RFC1918
• tcp/11211
• udp/11211

IN:

• SMTP
• udp/135
• netbios
• tcp/80
• tcp/443
• tcp/11211
• udp/11211
• RFC1918

Where an end user requires the use of these ports and understands the risk of unblocking, tenants can set unblockPorts to true on the service configuration and Nitrogen will reconfigure the network to unblock all of the ports.

Example Service Configuration Payload#

   {
      "serviceConfiguration": {
         "dslStabilityProfile": "standard",
         "layer3Options": {
            "authMethod": "ipoe",
            "applyShapingRestriction": false,
            "unblockPorts": false
         }
      }
   }

Other Payload Parameters#

POTS (PLain Old Telephone Service)#

When a copper line has an legacy telephone connection on it, the service qualification will indicate this.

In this case, the following fields may be required to be submitted for an order to be accepted: