Orders¶

An order is a dictionary containing some fields representing an order.

Order Type¶

There is 2 types of orders:

The activate order is used to create a new service. It’s an activation order. It’s defined with a product chosen in the Covage catalog.
The terminate order is used to end a service from an active service on the Covage platform. It’s a terminate order.

Service type¶

The platform handle two service types depending on the product range used to order a service:

collect service defined by a product in the family ADSL (A), SDSL (S) or SDSL Max (M).
enni service defined by a product in the family ENNI (N).

Collect Order type¶

Depending on the order collect is one of a neighbour or not, there is 4 types of collect activation orders:

activate when the line used belong to the final client.
create when the final client wants to create a new line from another one he already activated on the local loop.
create_nearby wen the final client wants to create a new line in a building from the activated line of a neigbour in the same neighbour.
create_neighbour when the final client want to create a new line from the activated line living in a different address but on the same pavement.

The initial state of an order is draft. It’s a draft order.

service activation order of collect type needind a line building create, create_nearby and create_neighbour) require an appointment with the final client and local loop operator.
Every service order of type collect needs a contact name from the operator.

Note

The terminate order of a enni service is not permitted on the platform.
The activation order of an enni service must be ordered with Covage. They are created and managed by Covage. You can access them through order and service api.

`order` composition¶

Order attributes contains required informations to indentify, define and follow an order. Some fields are only used for specific services (collect or enni) and the activation type (with or without line building).

Identify an order¶

Field name	Type	Description
model	string	`order`
operator_uuid	string	Operator identifier (you)
order_uuid	string	Technical order identifier
alias	string	Legible Covage order reference, in the format OYYMMDD_XXXXX , to be provided to Delivery service
operator_order_ref	string	Order reference in your information system
operator_order_name	string	Order name as displayed on the extranet

Define an order¶

Field name	Type	Description
type	string	`order` type. can be `activate` or `terminate`
product	dict	Informations about the chosen product. Define the service type, technology flow rate and available options.
service_uuid	string	Service technical identifier: If the order ends with success when a terminate order is created
service_alias	string	Covage commercial reference of the service: (To send along with all exchange with Covage). If the order ends with success when a terminate order is created
batch_alias	string	Commercial Covage reference of a batch. Set by the Covage delivery team. formated as BYYMMDD_XXXXX. used when the order is part of a mass migration batch.

`type` field¶

There are several types of orders:

Order Type	Description
`activate`	New service creation
`terminate`	Existing service termination

`product` field¶

The product dictionary contains the information required for activation, as well as information about the product line and the product family (see product catalog).

{
    "name": "ADSL-Max-FULL-KOSC",
    "code": "AM01",
    "description": "ADSL * FULL unbundling  * KOSC",
    "line": {
        "name": "ADSL-Max",
        "code": "AM",
        "description": "ADSL-MAX * Best of ADSL, VDSL products",
        "family": {
            "name": "ADSL",
            "code": "A",
            "description": "ADSL * technology : ADSL, VDSL, READSL"
        }
    }
}

When creating an order, only the product code field has to be filled in. The other fields are automatically added by KOSC to grant you an easy access to the information.

Example:

{
    "code": "AM01",
}

Follow the order status¶

Field name	Type	Description
status	string	Order state: `draft`, `processing`, …
creation_date	ISO datetime	Order creation date
modification_date	ISO datetime	Date of last order modification
processing_date	ISO datetime	Actual order processing start date
submission_date	ISO datetime	Order submission date
acknowledged_date	ISO datetime	Date of order acknowledgment by the Covage system
held_date	ISO datetime	Last date when order changed to `held` state
completion_date	ISO datetime	Date when order changed to `completed` state
cancellation_date	ISO datetime	Date when the order changed to `cancelled` state
rejection_date	ISO datetime	Date when order changed to `rejected` state

`status` field¶

Order state	Description
`draft`	The order was created but not submitted.
`submitted`	The order was successfully submitted by the operator.
`acknowledged`	The order was acknowledged by Covage.
`processing`	The order was acknowledged by the provider, and is being processed
`pending`	The order is waiting for an action by the operator. Example : xDSL order confirmation on a sensitive access
`held`	The order is waiting for an action by Covage (or by the PROVIDER). Example : copper local loop desaturation process
`rejected`	The order was rejected. The rejection may happen in different stages of the access production process: initial controls or later stages). A rejected order of the `activate` type did not generate any new services, rejected order of the `modify` type did not modify any services, a rejected terminate order din not terminate any services, etc.
`cancelled`	The order was canceled by the operator (`cancel` action)
`completed`	The order was successfully completed. An order of the `activate` type did activate a new link, an oder of the `terminate` type did terminate a service, etc.

Order Characteristics for a `collect` service¶

Field name	Type	Description
owner	dictionary	End customer contact information
contacts	dictionnaire	Informations de contact pour l’`order`

`owner` field¶

The owner field is a dictionary containing the end customer identification information.

See documentation here.

`contacts` field¶

The contacts field is a dictionary containing information about the people to contact in order to process the order.

Field name	Type	Description
operator	dictionary	Operator (you) contact information
owner	dictionary	End customer contact information

The contacts.operator field allows you to specify the person in your team that has to be contacted should Covage encounter any problem with the processing of an order.

Example:

{
     "contact_uuid": "93reo2i3",
}

The Contacts API allows you to list, create, modify and delete your contacts.

The contacts.owner field allows you to specify the information associated with the owner of the line that has to be created.

{
     "first_name": "John",
     "last_name": "Doe",
     "phone_number": "0168425698",
     "cell_phone_number": "0668425698",
     "email": "john@doe.com"
 }

Activation order characteristics for a `collect` service.¶

Field name	Type	Description
activation_type	string	Activation type. Either `activate`, `create`, `create_nearby` or `create_neighbour`
activation_info	dictionary	Activation information
eligibility_ref	string	Eligibility request identifier
address	dict	`endpoint` adress
endpoints	endpoint list	List of initial endpoints. Empty if building line is required
reference_endpoint	dict	Active neighbour endpoint (if building line is required)
enni	dict	informations about the `enni` service to which the trafic is forwarded. Apply for `collect` service with SDSL product (`S` family)
options	dict	Options to be activated (depending on the selected product)
comment	string	Specific information, agreed with Covage, for service activation

`activation_info` field¶

The activation_info field is a dictionary containing the required informations for order when it’s an activate order.

Field name	Type	Description
mandate_id	string	Refers to the unbundling mandate signed with you by the end customer for line activation. This mandate could be claimed from you in case of slamming.

`endpoints` field¶

For line activation, endpoints field is mandatory and express to Covage one or more endpoints to be activated. xDSL for more informations.

`reference_endpoint` field¶

In some cases, during the creation of a line, the final endpoint still does not exist. Eligibility then must be carried out on an endpoint near the endpoint that has to be created.

Once the order is created, the reference_endpoint field will contain information about the reference endpoint.

endpoint example:

{
    "endpoint_ref": "0123456789",
    "endpoint_ref_type": "line_number",
}

Note

Warning: you must provide all the values that were sent to you upon issuing the eligibility request without modification.

`address` field¶

in case of line activation, the address field contains informations about de line address of the line to activate and is pre-filled with informations of the reference_endpoint. Some fields are the modifiable to indicate exact address of the endpoint to be created (stairs, street number and so on).

Note

The address fields to fill depends on the activation type. The address definition infos are in the section xDSL line order.

`enni` field¶

Must be filled with a SDSL family product (S). See documentation here.

`origin` field¶

The origin field is a read-only field whose value (standard, mass_migration, unit_migration) is computed automatically by the platform depending on the order type. This field allows the customer to differentiate well between STANDARD order and MASS_MIGRATION order.

`options` field¶

The option field is a dictionary with the option code as the key and configuration dictionary as value.

For orders that include a portability request, the portability report form the local loop operator (operator awarded the contract and infrastructure operator) is directly transmitted to the operator. Also you should a prefix_code and optionalaly a rio_code. See doc here.

Order characteristics for an `enni` service¶

Field name	Type	Description
pop	dict	Informations about the POP hosting the `enni`.

`pop` field¶

The pop field is a dictionary with characteristics from the API.

Exemple:

{
   "pop": {
        "address": "137 Boulevard Voltaire, 75011 PARIS",
        "code": "P75TH2",
        "housing": "TELEHOUSE 2",
        "interface": "10G_SR"
    }
}

Creating an `order`¶

When an order is being created, its state is draft (the term draft order is used).

This feature allows the operator to fill in the initial information available and to complete it later on.

To create an order, a POST must be executed on the URL /api/orders/.

But only the activation order of a collect service can be created on the extranet.

Example:

POST /api/orders/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
   "type" : "activate",
   "activation_type" : "activate",
   "eligibility_ref": "KOSC_8178cd36-9207-4f86-a932-caaebba14381",
   "product" : {
      "code" : "SD01"
   },
   "options" : {
      "grt" : {
         "value" : "4h_bhbd",
         "enabled" : true
      }
   },
   "contacts" : {
      "operator" : {
         "contact_uuid" : "bp5nkkcx"
      },
      "owner" : {
         "phone_number" : "0123456789",
         "email" : "email@domain.com",
         "first_name" : "Prénom",
         "last_name" : "Nom"
      }
   },
   "operator_order_ref" : "UNTEL02-1",
   "operator_order_name" : "Commande pour client Untel",
   "comment" : "Commentaires",
   "activation_info" : {
       "mandate_id" : "01234567"
   },
   "owner" : {
      "type" : "unregistrated",
      "name" : "Untel"
   },
   "endpoints" : [ {
      "endpoint_ref_type" : "line_number",
      "endpoint_ref" : "0143340043"
   } ],
   "address" : {
      "street_name" : "RUE DU CAPITAINE GUYNEMER",
      "rivoli_code" : "1440",
      "floor" : "03",
      "city" : "COURBEVOIE",
      "insee_code" : "92026",
      "street_number" : "00044"
   },
   "enni": {
       "enni_vlan": "111",
       "enni_service_ref": "S20181102_12001"
   }
}

In this example, Covage adds the fields below:

model
order_uuid
alias
operator_uuid
creation_date
modification_date
status

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "model": "order",
  "order_uuid": "t8jcx8tp",
  "alias": "O170516_21000",
  "operator_uuid": "9lf2g9rt",
  "creation_date": "2017-05-16T21:36:23.945079",
  "modification_date": "2017-05-16T21:36:23.945079",
  "status": "draft",
  "type" : "activate",
  "activation_type" : "activate",
  "eligibility_ref": "KOSC_8178cd36-9207-4f86-a932-caaebba14381",
  "product": {
      "name": "SDSL-4M-PREMIUM-G-1P-KOSC",
      "code": "SD01",
      "description": "SDSL 4Mbit/s  PREMIUM * Guaranteed * 1 pair * KOSC",
      "line": {
          "name": "SDSL-4M",
          "code": "SD",
          "description": "SDSL-4M * Rate : 4 Mbits",
          "family": {
              "name": "SDSL",
              "code": "S",
              "description": "SDSL"
          }
      }
  },
  "options" : {
     "grt" : {
        "value" : "4h_24_7",
        "enabled" : true,
        "default_value" : "4h_bhbd"
     }
  },
  "contacts" : {
     "operator" : {
        "contact_uuid" : "bp5nkkcx"
     },
     "owner" : {
        "phone_number" : "0123456789",
        "email" : "email@domain.com",
        "first_name" : "Prénom",
        "last_name" : "Nom"
     }
  },
  "operator_order_ref" : "UNTEL02-1",
  "operator_order_name" : "Commande pour client Untel",
  "comment" : "Commentaires",
  "activation_info" : {
      "mandate_id" : "01234567"
  },
  "owner" : {
     "type" : "unregistrated",
     "name" : "Untel"
  },
  "endpoints" : [ {
     "endpoint_ref_type" : "line_number",
     "endpoint_ref" : "0143340043"
  } ],
  "address" : {
     "street_name" : "RUE DU CAPITAINE GUYNEMER",
     "rivoli_code" : "1440",
     "floor" : "03",
     "city" : "COURBEVOIE",
     "insee_code" : "92026",
     "street_number" : "00044"
  },
  "enni": {
      "enni_vlan": "111",
      "enni_service_ref": "Gate 1"
  }
}

Retrieve an `order`¶

You can retrieve an order by means of the GET method on the /api/orders/{order_uuid}/ URL.

GET /api/orders/t8jcx8tp/ HTTP/1.1
Host: extranet.kosc-telecom.fr

Update an `order`¶

You can update an order by means of the PUT method on the /api/orders/{order_uuid}/ URL.

Only the modifications on the following fields will be taken into account:

owner
comment
contacts
options
operator_order_ref
operator_order_name
enni
batch_alias

Note

The behavior upon modification of the endpoints field depends on the order type.

Note

An order cannot be modified unless its state (status) is draft.

Note

Every time a PUT is used, the whole document must be sent. The modifiable fields that are no longer present will be deleted from the order.

Note

The batch_alias field is filled when an order is part of a mass migration program managed by Covage.

Delete an `order`¶

You can delete an order in the draft state by means of the DELETE method on the `/api/orders/{order_uuid}/ URL.

DELETE /api/orders/t8jcx8tp/ HTTP/1.1
Host: extranet.kosc-telecom.fr

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

Submit an `order`¶

It’s possible to submit an activation order or terminate order of a collect service with a POST on POST sur l’url /api/orders/{order_uuid}/submit/. The order mst be in the draft state.

POST /api/orders/t8jcx8tp/submit/ HTTP/1.1
Host: extranet.kosc-telecom.fr

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

Confirm or cancel an `activation order`¶

If the order is a service activation of collect type, some event requires an answer from you. At this time the order is in the pending state.

You can send your answer with a POST on /api/orders/{order_uuid}/{action}/.

possible actions are:

confirm
cancel

Orders¶

Order Type¶

Service type¶

Collect Order type¶

order composition¶

Identify an order¶

Define an order¶

type field¶

product field¶

Follow the order status¶

status field¶

Order Characteristics for a collect service¶

owner field¶

contacts field¶

Activation order characteristics for a collect service.¶

activation_info field¶

endpoints field¶

reference_endpoint field¶

address field¶

enni field¶

origin field¶

options field¶

Order characteristics for an enni service¶

pop field¶

Creating an order¶

Retrieve an order¶

Update an order¶

Delete an order¶

Submit an order¶

Confirm or cancel an activation order¶

`order` composition¶

`type` field¶

`product` field¶

`status` field¶

Order Characteristics for a `collect` service¶

`owner` field¶

`contacts` field¶

Activation order characteristics for a `collect` service.¶

`activation_info` field¶

`endpoints` field¶

`reference_endpoint` field¶

`address` field¶

`enni` field¶

`origin` field¶

`options` field¶

Order characteristics for an `enni` service¶

`pop` field¶

Creating an `order`¶

Retrieve an `order`¶

Update an `order`¶

Delete an `order`¶

Submit an `order`¶

Confirm or cancel an `activation order`¶