Créer des tickets depuis d’autres systèmes avec l’API de Todomator

Todomator · todomator@1.7 todomatorapitokenticketsintegration

Todomator expose ses actions par un seul point d’accès API : POST /api/ avec un corps JSON { "schema": "<name>", "data": { ... } } (les routes API de Total.js ; voir la recette routes API). L’adresse /api/ vient de la ligne $api du fichier config.

S’authentifier avec le jeton

En plus de la session d’une personne connectée, l’API accepte un jeton : envoyez-le dans l’en-tête x-token ou dans le paramètre de requête token. S’il est égal au réglage token (voir réglages), la requête s’exécute comme un utilisateur intégré appelé Bot, un administrateur avec la permission bot ; tout autre jeton est refusé. Utilisez un long jeton aléatoire, gardez-le sur votre serveur et envoyez-le uniquement en HTTPS.

Créer un ticket

L’appel s’appelle tickets_create. Seul name est obligatoire ; le reste est facultatif :

Champ	Remarques
`name`	le titre
`folder` ou `folderid`	le dossier, par nom (Todomator le cherche) ou par id ; le ticket prend l’indicateur facturable du dossier
`users`	les personnes à assigner, par nom ou e-mail ; une personne inconnue est une erreur (`User "..." not found`)
`watcherid`	les personnes qui le suivent, par id (contrairement à `users`, le schéma de cette version ne les accepte pas par nom)
`statusid`	`pending` (par défaut), `open`, `review`, `postponed`, `note` ou `closed`
`markdown`, `html`	le contenu
`tags`, `ispriority`, `isbillable`, `ispublic`	étiquettes et indicateurs
`date`, `deadline`, `worked`	le jour, une échéance et les minutes déjà travaillées
`attachments`	une liste de `{ name, data }` où `data` est le fichier en Base64
`reference`, `source`, `attrs`	champs libres pour relier le ticket à votre système
`callback`	une adresse qui reçoit le ticket

{
	"schema": "tickets_create",
	"data": {
		"name": "The invoice page fails with a 500",
		"folder": "Customer support",
		"users": ["jane@example.com"],
		"markdown": "Reported by the contact form.\n\nSteps: open the invoice and click *Print*.",
		"tags": ["bug"],
		"source": "website",
		"reference": "form-2041"
	}
}

La réponse est l’id du nouveau ticket. Les personnes assignées sont notifiées et les sessions ouvertes des personnes qui peuvent le voir sont rafraîchies.

Le callback

Quand callback est défini, Todomator envoie un POST à cette adresse avec les données du ticket lorsque le ticket est créé, mis à jour ou cloné, et lorsqu’un commentaire est ajouté (à la création et à la mise à jour, il envoie aussi la liste des champs fournis, keys). Votre système peut l’utiliser pour refléter l’état d’un ticket.

Autres appels

Le même point d’accès sert le reste des actions, avec les noms de controllers/api.js : tickets (liste), tickets_detail/{id}, tickets_update/{id}, tickets_clone/{id}, tickets_remove/{id}, logwork_create, folders, tags et d’autres. La documentation officielle de l’API se trouve sur docs.totaljs.com/todomator.