New line order

Swagger-UI: order-v1 | OpenAPI file: order-v1.yml

Table of contents

New line order

The purpose of a new line order is to order a new connection with a telco, or migrate an existing connection. Both new lines and migrations are managed with an order of type NewLine. This chapter documents the contents and process of a new line order.

Order contents

A new line order contains the following information:

  • customerOrderId: Your order id
  • orderType: NewLine
  • orderSubType: CREATE or MIGRATE (default CREATE if unspecified)
  • wishDate: the wish date to deliver the connection on, or execution date in case of a migration
  • address: the address information of the connection
  • contact: contact information if deviating from the default reseller contact information
  • package: the package code
  • slaProduct: optional SLA product code
  • parameters: order parameters
  • evcs: one or more EVC (Ethernet Virtual Circuit. May as well be a PVC on an ATM connection.) instances to order on a connection

Customer order ID

The customer order ID is a mandatory parameter which should contain a unique order ID generated by you (or your system). When an order already exists with the given order ID, the order will be rejected.

Choosing the right order subtype

Whether a connection is going to be newly constructed or migrated depends on the order subtype specified in the order message. Choosing the right order type for the connection depends on the situation at the location.

The following rules apply:

  • If your end user has a connection at another telco and would like to become your customer with the same specifications as the existing connection, choose MIGRATE.

  • If you’re ordering a DSL line, the following rules apply:

    • if all copper connections in the IS/RA point at the location are taken, and there aren’t any NLS 2 lines available, choose to migrate an existing one.
    • if there are no copper connections available, but there are NLS 2 lines available, choose CREATE with nlsType 2 as an order parameter.
  • If you’re ordering an FttH line and an FttH line is already at the end user location, chose MIGRATE.
  • If there are enough copper connections or fiber connections available at the end user location and your end user wants a new line, chose CREATE.

Before ordering a migration, verify with your end user that an existing connection needs to be migrated. Otherwise, the connection may be unfairly “stolen” from another end user, possibly resulting in downtime for an unrelated end user.

Check the parameters for information about the various nlsType values.

Wish date

The wish date of a new connection can be either empty or may be set to a date in the near future. The wish date is optional in the order and when omitted, the telco will determine the appropriate date by its own business rules.

When choosing your own wish date, adhere to the following business rules:

  • The wish date for new lines needs to be at least 5 working days in the future
  • For migration orders, the wish date needs to be at least 10 working days in the future.

New connections delivered either by Reggefiber or KPN will most likely be delivered before the wish date. This should ensure that you’re able to properly connect the end user at the requested end user.

When migrating a line, the wish date is actually the date on which the connection will be migrated.

Parameters

Order parameters are a generic way of specifying parameters specific to the location and situation for the end user connections It is basically a key/value map with a predefined set of parameter types.

Parameters can for example specify a service ID, your own unique line reference and the NLS type. It is possible to specify multiple order parameters in one order.

The following table shows the available parameters and its purposes.

Parameter Read only Description
accessProtocol yes DHCP or PPP
configurableEvc yes Whether or not the EVC can be configured with custom VPI/VCI or Vlan ID
ipAllocation yes Whether or not an IP address or prefix can requested with the EVC. If so, a list of allowed prefix sizes will be supplied in the availability checker in subnetSize
subnetSize yes Available subnet size for an IPv4 subnet
technology yes ADSL2, VDSL2 or Fiber
testAndLabel no Whether or not a KPN engineer should test label a new DSL connection
wcd no Whether or not a KPN engineer should install a new outlet for a DSL connection
serviceId no The service ID of the line to migrate
israPoint no The IS/RA point to deliver a new connection on
lineNumber no Line number in case of DSL line sharing
lineSharing no Set to true to order a DSL line on a connection on which analogue telephony is already configured
nlsType no New line type for a DSL connection. See DSL specifics.
custLineRef no Your optional line reference. This will appear on the invoice

Read only parameters are informational parameters about the possible connection. They cannot be changed nor specified in the order. You can use those parameters to determine which parameters to fill in.

EVCs

An EVC (Ethernet Virtual Circuit. May as well be a PVC on an ATM connection.) is actually a circuit on a line. In case of an ADSL2 connection, this is the ATM circuit. In case of a Fiber or VDSL2 connection, this is the ethernet VLAN.

It is currently possible to order exactly one EVC with a connection. If the configurableEvc parameter is set to true in the package information in the available check result, you may configure the VPI/VCI or VLAN id in the EVC with the order request.

When the package information contains the ipAllocation parameter along with the subnetSize parameter, it is possible to request an IPv4 with one of the sizes as specified in the subnetSize parameter.

By default, an IPv4 prefix size of /32 is requested, meaning one IP address per EVC. When requesting a larger subnet, additional charges may apply. The tariff for the allocated prefix is the tariff of the product of type IPADDRESS multiplied by the amount of IP addresses in the prefix size.

If available in the network, an IPv6 prefix with size /48 is ordered automatically with no additional charge.

Contact information

When the telco needs to make an appointment with the end user customer for delivery and setup of the new connection, the contact information needs to be given in the order message. Alternatively, when most of your connections share the same contact information, it is possible to register default contact information via the Contact API.

So when a new connection has specific contact information, supply it in the order. Otherwise, omit the contact section completely if you’ve registered default contact information.