REST API - Attacher des documents à un ticket
Sommaire
POST /requests/{rfc_number}/documents
- Cette méthode permet d'attacher des documents à un ticket déterminé (un ticket englobe un incident, demande de service / changement / investissement, problème et événement).
exemple /requests/I161026_000005/documents
- Les fichiers peuvent être au format .pdf, .docx, .jpg, .svg, .pptx, .txt, .png, etc.
- Plusieurs fichiers peuvent être attachés simultanément.
Remarques
voir Conventions de l'API REST Service Manager
- En cas de succès, un code de statut HTTP 201 est retourné et un lien URL (HREF) vers la ressource créée est fourni.
- Vous devez passer le contenu des fichiers dans un objet de type form-data (Key = documents) dans le corps de la requête HTTP. Pour cela, vous devez utiliser une fonctionnalité de votre application ou un outil / développement tiers permettant de :
- télécharger et attacher les fichiers souhaités ;
- encoder les fichiers en Base64.
Liste des paramètres / champs
Paramètres obligatoires
Dans l'URL, vous devez utiliser le paramètre ci-dessous.
| Paramètre | Type | Description / Exemple |
|---|---|---|
| rfc_number | string | Identifiant du ticket |
Paramètres optionnels
Dans le corps de la requête HTTP, vous pouvez utiliser les objets JSON détaillés ci-dessous.
| Paramètre | Type | Description / Exemple |
|---|---|---|
| description | string | Description des documents joints |
| documents | file | Contenu des documents joints encodés en Base64. Note : Ce paramètre comprend 2 variables : filedata et filename - voir Exemple |
Description des actions effectuées
1. Les documents sont téléchargés.
- Titre du document = Nom du fichier
2. Ils sont attachés au ticket et deviennent accessibles via l'onglet Documents de la fiche Ticket.
Codes de statut HTTP de la méthode
StatusHeader
Note : Un code erreur Timeout est renvoyé et la méthode échoue si le serveur ne répond pas à la requête du web service REST au bout d'un certain temps (par défaut, 60 secondes).
| Code | Erreur | Description |
|---|
Status201
| 201 | Created (Créé) | Requête traitée avec succès et création d’un élément. |
Status401
| 401 | Unauthorized (Non autorisé) | Processus d'authentification pour accéder à la ressource incorrect : Login/Mot de passe incorrect, Session non valide, Compte Service Manager incorrect.
exemple { "error": "Invalid Login / Password" } |
Status403
| 403 | Forbidden (Interdit) | Refus d'exécution de la requête par le serveur. À la différence de l'erreur 401, l'authentification est acceptée, mais les droits ne permettent pas au client d'accéder à la ressource : Utilisateur n’ayant pas le paramètre REST API activé dans son profil. |
Exemples
Exemple de corps de requête HTTP
{
"documents": [{
"filedata": "SmUgc3VpcyB1biBkb2N1bWVudA==",
"filename": "document.docx"
}]
}
"documents": [{
"filedata": "SmUgc3VpcyB1biBkb2N1bWVudA==",
"filename": "document.docx"
}]
}
Résultat avec un code de statut retourné 201
{
"HREF": "https://{your_server}/api/v1/{your_account}/requests/I161026_000005"
}
"HREF": "https://{your_server}/api/v1/{your_account}/requests/I161026_000005"
}
ConventionsAPI
Conventions de l'API REST
| Convention | Signification | |
|---|---|---|
| Orange | Paramètres utilisés dans la chaîne d’une requête HTTP et qui ne correspondent pas à des champs de la base Service Manager.
exemple Méthode Voir une liste de biens https://{your_server}/api/v1/{your_account}/assets?max_rows=3&fields=asset_tag |
|
| Noir et Gras | Paramètres utilisés dans l’URL d’une requête HTTP et qui correspondent à des champs de la base Service Manager.
exemple Méthode Voir un bien https://{your_server}/api/v1/{your_account}/assets/{asset_id} |
|
| Vert | Paramètres utilisés dans le corps d’une requête HTTP et qui représentent des noms d’objets JSON correspondant à des champs de la base Service Manager ; ils permettent d’affecter ou de modifier une valeur de champ dans la base.
exemple Méthode Terminer un ticket { "closed": { "end_date": "11/20/2016 12:12:12", } } |
|
| Paramètres utilisés dans le corps d’une requête HTTP et qui représentent des noms d’objets JSON ne correspondant pas à des champs de la base Service Manager.
exemple Méthode Reprendre un ticket { "restarted": { "comment": "string (required)" } } |
||