Diagnostic

Available diagnostic units

The following units can be available depending on the configuration of the service on which the diagnostic is launched.

Copper

Unit Diag Name	Unit code	Unit Diag Category	Part of STANDARD DIAG
Technical information	technicalinfo	Access	Yes
Synchro test	synchro	Access	Yes
CPE MAC	cpemac	Access	Yes
SELT	selt	Access	No
MELT	melt	Access	No
Enable access	enable	Access	No
Disable access	disable	Access	No
Reset access	reset	Access	No
Access traffic	traffic	Access	No
Test dslam	test_dslam	Access	Yes
Test dlm	test_dlm	Access	Yes
Test rtc	test_rtc	Access	Yes
Collective disturbance	derco	Access	Yes

Fiber

Unit Diag Name	Unit code	Unit Diag Category	Part of STANDARD DIAG
Fiber state	fiber_state	Access	Yes
Service informations	service_info	Access	No
Collective disturbance	derco	Access	Yes

Note

Diagnostics on ENNI services are not supported at this time.

In the event of a collective disruption, the response will contain the “impacted_services” key listing all service references impacted by this disruption.

Diagnostic unit categories

There are two types of diagnostic units categories : access and network.

access units run on the access side of the service such as line synchronization, DSLAM ports technical informations, etc.

network units run on the network side of the service (Covage network) such as DSLAM status, core routers or delivery gate.

Getting available diagnostic units

To get the diagnostic units available specifically for a service, you must call the url /api/diagnostic/units/ and provide the following query parameters:

Query parameter	Mandatory	Description
service_uuid	Yes	UUID of the service on which you want to run diagnostic
category	Yes	Category of the units you want to run (access or network)

Example:

GET /api/diagnostic/units/?service_uuid=54u93i&category=access HTTP/1.1
Host: extranet.kosc-telecom.fr

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

[
  {
    "name": "technicalinfo",
    "label": "Technical information",
    "category": "access",
    "description": "TODO",
    "standard": true
  },
  {
    "name": "synchro",
    "label": "Synchro test",
    "category": "access",
    "description": "TODO",
    "standard": true
  },
  {
    "name": "cpemac",
    "label": "CPE MAC",
    "category": "access",
    "description": "TODO",
    "standard": true
  },
  {
    "name": "selt",
    "label": "SELT",
    "category": "access",
    "description": "TODO",
    "standard": false
  },
  {
    "name": "melt",
    "label": "MELT",
    "category": "access",
    "description": "TODO",
    "standard": false
  },
  {
    "name": "port-reset",
    "label": "Port reset",
    "category": "access",
    "description": "TODO",
    "standard": false
  },
  {
    "name": "enable",
    "label": "Enable access",
    "category": "access",
    "description": "TODO",
    "standard": false
  },
  {
    "name": "disable",
    "label": "Disable access",
    "category": "access",
    "description": "TODO",
    "standard": false
  }
]

Units fields are the following ones:

Field name	Type	Description
name	string	Name of the unit, this field is used for the diagnostic custom creation
category	string	Category of the unit (access or network)
label	string	Localized string containing the unit name (useful when displaying results on your backoffice)
description	string	Localized string containing the unit description (useful when displaying results on your backoffice)
standard	boolean	Tells if the unit is part of a standard diagnostic

Creating a diagnostic run

To run a diagnostic on a service, a new diagnostic run must be created by doing a POST on url /api/diagnostic/runs/.

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

{
    "service_uuid": "3acf5ab1-4062-4199-ba98-c3f94681b3de",
    "type": "standard"
}

You can ask for a custom series of diagnostic units by setting type field to custom and by providing a units field containing all units you want to run.

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

{
    "service_uuid": "3acf5ab1-4062-4199-ba98-c3f94681b3de",
    "type": "custom",
    "units": ["selt", "enable", "synchro"]
}

By default, units are ran on all endpoints of the service. You can specify which endpoint(s) you want the unit to be ran on by providing the endpoints field on request. You will find these endpoints on the service itself.

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

{
    "service_uuid": "3acf5ab1-4062-4199-ba98-c3f94681b3de",
    "type": "custom",
    "units": ["selt", "enable", "synchro"],
    "endpoints": [{
        "endpoint_ref": "0123456789",
        "endpoint_ref_type": "line_number"
    }]
}

Constraints:

• You may only execute units part of the same category if you ask for a custom diagnotic.

• You must own the service you are creating the diagnostic run on.

• If a diagnostic run is already attached to the given service and its status is (created, submitted or running), you cannot create a new diagnostic run. You have to wait until it’s completed, cancelled or error).

• On a Bitstream service (copper) you cannot reset an endpoint(e), and run other diagnostic(s) at the same time.

Note

Only standard diagnostic runs will allow to create a support ticket.

Fetching a diagnostic run

To fetch a diagnostic run you will have to GET url /api/diagnostic/runs/{alias}/.

Note

This request is possible using the alias or the id of the diagnostic run.

GET /api/diagnostic/runs/D170803_11001/ HTTP/1.1
Host: extranet.kosc-telecom.fr

When a diagnostic run is created or fetched, the API returns a dictionary with complete information about the run, the units and their status.

GET /api/diagnostic/runs/D170803_11001/ HTTP/1.1
Host: extranet.kosc-telecom.fr

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

{
  "id": 225146,
  "alias": "D190913_80926",
  "service_uuid": "3acf5ab1-4062-4199-ba98-c3f94681b3de",
  "status": "error",
  "units": [
    "synchro"
  ],
  "results": {
    "synchro": {
      "status": "error",
      "label": "Synchro test",
      "category": "access",
      "description": "",
      "data": [],
      "error_code": null,
      "error_description": ""
    }
  },
  "creation_date": "2019-09-13T14:03:32.713524Z",
  "modification_date": "2019-09-16T15:27:06.151004Z",
  "end_customer": "Untel",
  "type": "custom",
  "service_alias": "S190913_75475",
  "endpoints": [
    {
      "endpoint_ref": "0492271978",
      "endpoint_ref_type": "line_number"
    }
  ],
  "product": {
    "code": "AM01",
    "name": "ADSL-Max_FULL_BE_KOSC"
  },
  "ticket_id": null,
  "ticket_alias": null
}

Field name	Type	Description
id	integer	Id of the diagnostic run
alias	string	Alias of the diagnostic run
service_uuid	string	Diagnosed service uuid
service_alias	string	Diagnosed service alias
status	string	diagnostic current status (created, submitted, running, completed, cancelled, error, completed_with_error)
units	array	Array units name
results	dict	units results (see below for description)
creation_date	string	diagnostic creation date
modification_date	string	diagnostic last update
end_customer	string	Information about service end customer
type	string	diagnostic type (standard or custom)
endpoints	array	Service endpoints array
product	dictionary	Dictionary containing the code and name of product enabled on the service

Diagnostic run results

Fetching a diagnostic run returns a dictionary containing a field named results. This field contains the results of all units of the diagnostic run.

Example:

{
    "results" : {
        "selt": {
            "status": "submitted",
            "label" "SELT",
            "category": "access",
            "description": "Description of the SELT diagnostic unit",
        },
        "enable": {
            "status": "completed",
            "label" : "Enable access",
            "category": "access",
            "description": "Description of the 'enable' diagnostic unit",
            "data": [ {} ]
        },
        "synchro": {
            "status": "error",
            "label" "Synchro test",
            "category": "access",
            "description": "Description of the Synchro test diagnostic unit",
            "error_code": "DSLAM_UNREACHABLE",
            "error_description": "DSLAM can not be reached",
        }
    }
}

Each unit listed on the units field have an entry on the results dictionary with the following fields:

Name	Type	Description
status	string	Status of the unit, can be (created, submitted, running, completed, cancelled, error or completed_with_error)
category	string	Category of the unit (access or network).
label	string	Localized string containing the unit name (useful when displaying results on your backoffice).
description	string	Localized string containing the unit description (useful when displaying results on your backoffice).
error_code	string	This fields contains the error code of the unit when status its status is error.
error_description	string	Human readable localized string describing the unit error.
data	list of dictionnaries	Results of unit for each of the endpoints of the service

Note

When a unit is erroneous on a specific endpoint, the unit status is set to completed_with_error. The data dictionary corresponding to that endpoint will contain a field named error that will contain the reason why the unit failed on endpoint.

Cancelling a diagnostic

To cancel a diagnostic run you will have to do a PUT on url /api/diagnostic/runs/{alias}/.

Example:

PUT /api/diagnostic/runs/D170803_11001/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
    "status": "cancelled"
}

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

{
    "id": 1,
    "alias": "D170803_11001",
    "type": "custom",
    "creation_date": "2017-06-16T16:20:19.824993",
    "modification_date": "2017-06-19T07:31:19.372438",
    "service_uuid": "yn4b0yf6",
    "service_alias": "S170418_21000",
    "endpoints": [{
        "endpoint_ref": "0123456789",
        "endpoint_ref_type": "line_number",
    }],
    "endcustomer": "John Doe",
    "product": {
        "code": "AM01",
        "name": "ADSL-Max",
    },
    "status": "cancelled",
    "units": ["selt", "enable", "synchro"],
    "results": {
        "selt": {
            "status": "cancelled",
            "label" "SELT",
            "category": "access",
            "description": "Description of the SELT diagnostic unit",
            "data": [{ }],
        },
        "enable": {
            "status": "cancelled",
            "label" "Enable access",
            "category": "access",
            "description": "Description of the 'enable' diagnostic unit",
            "data": [{ }],
        },
        "synchro": {
            "status": "cancelled",
            "label" "Synchro test",
            "category": "access",
            "description": "Description of the Synchro test diagnostic unit",
            "data": [{ }],
        }
    }
}

Note

The diagnostic run status must be created, submitted or running to be cancelled.

This request is possible using the alias or the id of the diagnostic run.

Deleting a diagnostic run

Diagnostic runs can be deleted by doing a DELETE on url /api/diagnostic/runs/{alias}/.

DELETE /api/diagnostic/runs/D170420-56732/ HTTP/1.1
Host: extranet.kosc-telecom.fr

Note

The diagnostic status must be completed, cancelled or error to be deleted.

This request is possible using the alias or the id of the diagnostic run.

Listing diagnostic runs

A list of diagnostic runs can be retrieved by doing a GET on url /api/diagnostic/runs/.

The following filters can be added as query params to url.

Filter name	Description
service_alias	Alias of the service diagnostics are running on
diagnostic_run_alias	Alias of the service diagnostics are running on
product_line_code	Product line code of service diagnostics are running on
end_customer	Search for diagnostics on service belonging to end customer

The API will return a list of dictionnaries representing the runs.

Note

Diagnostic runs are asynchronous. That means that after having created a run, you will have to call it regularly until its status is either completed or failed.