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 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 sub type¶
Whether a connection is going to be newly constructed or migrated depends on the order sub type 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 ISRA 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 there are no copper connections availables and there aren’t any ISRA points either, choose CREATE with nlsType 3.
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.
Warning
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 down time for an unrelated end user.
Note
Check 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.
Note
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.
Note
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 ISRA 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
|
Note
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 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.
Warning
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.
Note
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.