Tickets aus anderen Systemen mit der Todomator-API erstellen

Todomator · todomator@1.7 todomatorapitokenticketsintegration

Todomator stellt seine Aktionen über einen API-Endpunkt bereit: POST /api/ mit einem JSON-Body { "schema": "<name>", "data": { ... } } (die API-Routen von Total.js; siehe das Rezept API-Routen). Die Adresse /api/ stammt aus der Zeile $api der Datei config.

Mit dem Token authentifizieren

Neben der Sitzung einer angemeldeten Person akzeptiert die API ein Token: Senden Sie es im Header x-token oder im Query-Parameter token. Entspricht es der Einstellung token (siehe Einstellungen), läuft die Anfrage als eingebauter Benutzer namens Bot, ein Administrator mit der Berechtigung bot; jedes andere Token wird abgewiesen. Verwenden Sie ein langes zufälliges Token, behalten Sie es auf Ihrem Server und senden Sie es nur über HTTPS.

Ein Ticket erstellen

Der Aufruf heißt tickets_create. Nur name ist Pflicht; der Rest ist optional:

Feld	Hinweise
`name`	der Titel
`folder` oder `folderid`	der Ordner, per Name (Todomator sucht ihn) oder per Id; das Ticket übernimmt das Abrechenbar-Flag des Ordners
`users`	die zuzuweisenden Personen, per Name oder E-Mail; eine unbekannte Person ist ein Fehler (`User "..." not found`)
`watcherid`	die Personen, die es verfolgen, per Id (anders als `users` nimmt das Schema dieser Version sie nicht per Name an)
`statusid`	`pending` (Standard), `open`, `review`, `postponed`, `note` oder `closed`
`markdown`, `html`	der Inhalt
`tags`, `ispriority`, `isbillable`, `ispublic`	Tags und Flags
`date`, `deadline`, `worked`	der Tag, eine Frist und bereits gearbeitete Minuten
`attachments`	eine Liste von `{ name, data }`, wobei `data` die Datei in Base64 ist
`reference`, `source`, `attrs`	freie Felder, um das Ticket mit Ihrem System zu verknüpfen
`callback`	eine Adresse, die das Ticket erhält

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

Die Antwort ist die Id des neuen Tickets. Die zugewiesenen Personen werden benachrichtigt, und die offenen Sitzungen der Personen, die es sehen dürfen, werden aktualisiert.

Der Callback

Ist callback gesetzt, sendet Todomator ein POST mit den Ticketdaten an diese Adresse, wenn das Ticket erstellt, aktualisiert oder geklont wird und wenn ein Kommentar hinzugefügt wird (beim Erstellen und Aktualisieren sendet es zusätzlich die Liste der angegebenen Felder, keys). Ihr System kann ihn nutzen, um den Status eines Tickets zu spiegeln.

Weitere Aufrufe

Derselbe Endpunkt bedient die übrigen Aktionen, mit den Namen aus controllers/api.js: tickets (Liste), tickets_detail/{id}, tickets_update/{id}, tickets_clone/{id}, tickets_remove/{id}, logwork_create, folders, tags und mehr. Die offizielle API-Dokumentation finden Sie unter docs.totaljs.com/todomator.