Diagnostics

Liste des unités de tests disponibles

Les unités suivantes peuvent être disponibles selon la configuration du service sur lequel vous voulez exécuter le diagnostic.

Cuivre

Nom de l'unité	Code de l'unité	Unit Diag Category	Part of STANDARD DIAG
Informations techniques	technicalinfo	Access	Yes
Test de synchro	synchro	Access	Yes
CPE MAC	cpemac	Access	Yes
SELT	selt	Access	No
MELT	melt	Access	No
Activation de l'accès	enable	Access	No
Désactivation de l'accès	disable	Access	No
Redémarrage de l'accès	reset	Access	No
Traffic de l'accès	traffic	Access	No
Test de dslam	test_dslam	Access	Yes
Test de dlm	test_dlm	Access	Yes
Test RTC	test_rtc	Access	Yes
Dérangement Collectif	derco	Access	Yes

Fibre

Nom de l'unité	Code de l'unité	Unit Diag Category	Part of STANDARD DIAG
État de la ligne fibre	fiber_state	Access	Yes
Informations liées au service	service_info	Access	No
Dérangement Collectif	derco	Access	Yes

Note

Les diagnostics sur les services ENNI ne sont pas supportés pour le moment.

En cas de dérangement collectif, la réponse contiendra la clef "impacted_services" listant toutes les références de services impactées par ce dérangement.

Catégories des unités de diagnostic

Deux types d'unités de diagnostic existent : access et network.

Les unités de type access s'exécutent du coté accès du service, comme la synchronisation, les informations techniques du port des DSLAMs, etc.

Les unités de type network s'exécutent du coté réseau du service (réseau de Covage) comme le statut du DSLAM, les routeurs et les portes de livraisons.

Récupération des unités de diagnostic disponibles

Pour récupérer les unités de diagnostic disponibles pour un service donné, vous devez faire un GET sur l'url /api/diagnostic/units/ en fournissant les paramètres suivants :

Parameter query	Obligatoire	Description
service_uuid	Oui	UUID du service sur lequel vous voulez exécuter le diagnostic
category	Oui	Catégories des unités de tests que vous voulez exécuter (access ou network)

Requête :

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

Réponse :

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

[
  {
    "name": "cpemac",
    "label": "CPE MAC",
    "category": "access",
    "description": "",
    "standard": true,
    "available": true,
    "sort_value": "cD1jcGVtYWM="
  },
  {
    "name": "disable",
    "label": "Disable endpoint(s)",
    "category": "access",
    "description": "",
    "standard": false,
    "available": true,
    "sort_value": "cD1kaXNhYmxl"
  },
  {
    "name": "enable",
    "label": "Enable endpoint(s)",
    "category": "access",
    "description": "",
    "standard": false,
    "available": true,
    "sort_value": "cD1lbmFibGU="
  },
  {
    "name": "melt",
    "label": "MELT",
    "category": "access",
    "description": "",
    "standard": false,
    "available": true,
    "sort_value": "cD1tZWx0"
  },
  {
    "name": "reset",
    "label": "Reset endpoint(s)",
    "category": "access",
    "description": "",
    "standard": false,
    "available": true,
    "sort_value": "cD1yZXNldA=="
  },
  {
    "name": "selt",
    "label": "SELT",
    "category": "access",
    "description": "",
    "standard": false,
    "available": true,
    "sort_value": "cD1zZWx0"
  },
  {
    "name": "synchro",
    "label": "Synchro test",
    "category": "access",
    "description": "",
    "standard": true,
    "available": true,
    "sort_value": "cD1zeW5jaHJv"
  },
  {
    "name": "technicalinfo",
    "label": "Technical information",
    "category": "access",
    "description": "",
    "standard": true,
    "available": true,
    "sort_value": "cD10ZWNobmljYWxpbmZv"
  },
  {
    "name": "traffic",
    "label": "Access traffic",
    "category": "access",
    "description": "",
    "standard": false,
    "available": true,
    "sort_value": "cD10cmFmZmlj"
  }
]

Les champs d'une unité de test sont les suivants :

Nom du champ	Type	Description
name	string	Nom de l'unité, ce champ est à fournir lors de la création d'un diagnostic custom
category	string	Categorie de l'unité (access ou network)
label	string	Version localisée du nom de l'unité (utile pour l'affichage des résultats sur votre backoffice)
description	string	Version localisée de la description de l'unité (utile pour l'affichage des résultats sur votre backoffice)
standard	boolean	Précise si l'unité fait partie d'un diagnostic standard

Création d'un diagnostic run

Pour effectuer un diagnostic sur un service, un nouveau diagnostic run doit être créé en effectuant un POST sur l'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"
}

Vous pouvez demander une série particulière d'unités de diagnostic en précisant le champ type à custom et en fournissant un champ units contenant la liste des unités que vous voulez exécuter.

Requête :

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"]
}

Par défaut, les unités sont exécutées sur tous les endpoints du service. Dans le cas d'un service multipaires, vous pouvez spécifier sur quels endpoints vous voulez que les unités soit exécutées en fournissant le champ endpoint dans la requête.

Requête :

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"
    }]
}

Contraintes :

• Vous ne pouvez éxecuter que des unités appartenant à la même catégorie lorsque vous demandez un diagnostic custom,

• Vous ne pouvez pas demander un diagnostic sur un service si un diagnostic est déjà en cours sur celui-ci.

• Sur un service Bitstream (cuivre), vous ne pouvez pas lancer la réinitialisation de(s) port(s) en même temps que d'autres diagnostics .

Note

Seuls les diagnostics de type standard permettent de créer un ticket de support.

Récupérer un diagnostic run

Pour récupérer un diagnostic run, vous devez effectuer un GET sur l'url /api/diagnostic/runs/{alias}/.

Note

Cette requête est possible en utilisant l'alias ou l'id du diagnostic run.

Requête :

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

Quand un diagnostic run est créé ou récupéré, l'API retourne un dictionnaire contenant toutes les informations du diagnostic, des unités et leurs statuts.

Requête :

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

Réponse :

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
}

Liste des champs

Nom du champ	Type	Description
id	integer	Identifiant du diagnostic run
alias	string	Alias du diagnostic run
service_uuid	string	UUID du service sur lequel le diagnostic est effectué
service_alias	string	Référence Covage du service sur lequel le diagnostic est effectué
status	string	Statut actuel du diagnostic run (created, submitted, running, completed, cancelled, error, completed_with_error)
units	array	Liste des unités
results	dict	Résultats des unités
creation_date	string	Date de création du diagnostic run
modification_date	string	Date de dernière modification du diagnostic run
end_customer	string	Information concernant le client final sur le service
type	string	Type de diagnostic run (standard ou custom)
endpoints	array	Liste des endpoints du service
product	dictionary	Dictionnaire contenant les champs code et name du produit du service

Résultats d'un diagnostic run

La récupération d'un diagnostic unit renvoie un dictionnaire contenant un champ results. Ce champ contient les résultats de toutes les unités du diagnostic run.

Avertissement

Le format du champ results n'est pas garanti, n'est pas constant entre les services même pour un produit identique, et peut changer à tout moment en fonction des contraintes opérationnelles de Covage. Son utilisation en API doit se faire avec précaution.

Exemple:

{
    "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",
        }
    }
}

Chaque unité listée dans le champ unit a une entrée correspondante dans le dictionnaire du champ results, dont le contenu est le suivant :

Name	Type	Description
status	string	Statut de l'unité, peut être created, submitted, running, completed, cancelled, error ou completed_with_error.
category	string	Catégorie de l'unité (access ou network).
label	string	Chaîne de caractères localisée contenant le nom de l'unité.
description	string	Chaîne de caractères localisée contenant la description de l'unité.
error_code	string	Ce champ contient le code erreur de l'unité lorsque son statut est error.
error_description	string	Version lisible de l'erreur rencontrée par l'unité.
data	list of dictionnaries	Résultats de l'unité pour chacun des endpoints du service. Le format de ce champ n'est pas garanti. Les résultats sont composés d'une première liste correspondant à chaque endpoint (un seul dans le cas de la fibre), puis d'une deuxième liste comprenant un ou plusieurs objets avec les résultats du diagnostic, selon les cas.

Note

Quand une unité est en erreur sur un endpoint particulier, le statut de l'unité est completed_with_error. Le dictionnaire présent dans le champ data contiendra une clef error correspondant à la description de l'erreur rencontrée.

Annulation d'un diagnostic run

Pour annuler un diagnostic run en cours, vous pouvez faire un PUT sur l'url /api/diagnostic/runs/{alias}/.

Note

Le statut du diagnostic run doit être created, submitted ou running pour être annulé.

Cette requête est possible en utilisant l'alias ou l'id du diagnostic run.

Requête :

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

{
    "status": "cancelled"
}

Réponse :

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": [{ }],
        }
    }
}

Supprimer un diagnostic run

Un diagnostic run peut être supprimé en effectuant un DELETE sur l'url /api/diagnostic/runs/{alias}/.

Note

Cette requête est possible en utilisant l'alias ou l'id du diagnostic run.

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

Note

Le statut du diagnostic run doit être completed, cancelled ou error pour être supprimé.

Lister les diagnostic runs

Une liste des diagnostic runs peut être récupérée en faisant un GET sur l'url /api/diagnostic/runs/.

Les filtres suivants peuvent être ajoutés en paramètre à l'URL :

Nom du filtre	Description
service_alias	Alias du service sur lequel les diagnostics sont ou été éxecutés
diagnostic_run_alias	Alias du service sur lequel les diagnostics sont ou été éxecutés
product_line_code	Code de la ligne de produit du service sur lequel les diagnostics sont ou été éxecutés
end_customer	Recherche de diagnostics sur le nom du client final

L'API renverra une liste de dictionnaires représentant les diagnostic runs.

Note

Les diagnostic runs sont asynchrones. Après avoir créé un diagnostic run, vous devrez régulièrement les récupérer jusqu'à ce que leur statut soit completed, failed, error ou cancelled. Au-delà de 300 secondes (5 minutes), un diagnostic non terminé passe automatiquement en erreur.