Tickets aanmaken vanuit andere systemen met de Todomator-API

Todomator · todomator@1.7 todomatorapitokenticketsintegration

Todomator stelt zijn acties beschikbaar via één API-endpoint: POST /api/ met een JSON-body { "schema": "<name>", "data": { ... } } (de API-routes van Total.js; zie het recept API-routes). Het adres /api/ komt uit de regel $api van het bestand config.

Authenticeren met het token

Naast de sessie van een aangemelde persoon accepteert de API een token: stuur het in de header x-token of in de queryparameter token. Als het gelijk is aan de instelling token (zie instellingen), draait het verzoek als een ingebouwde gebruiker genaamd Bot, een beheerder met het recht bot; elk ander token wordt geweigerd. Gebruik een lang willekeurig token, bewaar het op je server en stuur het alleen via HTTPS.

Een ticket maken

De aanroep heet tickets_create. Alleen name is verplicht; de rest is optioneel:

Veld	Opmerkingen
`name`	de titel
`folder` of `folderid`	de map, op naam (Todomator zoekt hem op) of op id; het ticket neemt de factureerbaar-vlag van de map over
`users`	de toe te wijzen personen, op naam of e-mail; een onbekende persoon is een fout (`User "..." not found`)
`watcherid`	de personen die het volgen, op id (anders dan `users` neemt het schema van deze versie ze niet op naam aan)
`statusid`	`pending` (standaard), `open`, `review`, `postponed`, `note` of `closed`
`markdown`, `html`	de inhoud
`tags`, `ispriority`, `isbillable`, `ispublic`	labels en vlaggen
`date`, `deadline`, `worked`	de dag, een deadline en al gewerkte minuten
`attachments`	een lijst van `{ name, data }` waarbij `data` het bestand in Base64 is
`reference`, `source`, `attrs`	vrije velden om het ticket met je systeem te verbinden
`callback`	een adres dat het ticket ontvangt

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

Het antwoord is de id van het nieuwe ticket. De toegewezen personen krijgen een melding en de open sessies van de personen die het mogen zien worden ververst.

De callback

Wanneer callback is ingesteld, stuurt Todomator een POST naar dat adres met de ticketgegevens wanneer het ticket wordt aangemaakt, bijgewerkt of gekloond, en wanneer er een opmerking wordt toegevoegd (bij aanmaken en bijwerken stuurt het ook de lijst van de opgegeven velden, keys). Je systeem kan hem gebruiken om de status van een ticket te spiegelen.

Andere aanroepen

Hetzelfde endpoint bedient de overige acties, met de namen uit controllers/api.js: tickets (lijst), tickets_detail/{id}, tickets_update/{id}, tickets_clone/{id}, tickets_remove/{id}, logwork_create, folders, tags en meer. De officiële API-documentatie staat op docs.totaljs.com/todomator.