Creare ticket da altri sistemi con l’API di Todomator

Todomator · todomator@1.7 todomatorapitokenticketsintegration

Todomator espone le sue azioni tramite un solo endpoint API: POST /api/ con un corpo JSON { "schema": "<name>", "data": { ... } } (le rotte API di Total.js; vedi la ricetta rotte API). L’indirizzo /api/ deriva dalla riga $api del file config.

Autenticarsi con il token

Oltre alla sessione di una persona con accesso, l’API accetta un token: invialo nell’intestazione x-token o nel parametro di query token. Se è uguale all’impostazione token (vedi impostazioni), la richiesta viene eseguita come un utente integrato chiamato Bot, un amministratore con il permesso bot; qualsiasi altro token viene rifiutato. Usa un token lungo e casuale, tienilo sul tuo server e invialo solo via HTTPS.

Creare un ticket

La chiamata si chiama tickets_create. Solo name è obbligatorio; il resto è facoltativo:

Campo	Note
`name`	il titolo
`folder` o `folderid`	la cartella, per nome (Todomator la cerca) o per id; il ticket prende il flag di fatturabilità della cartella
`users`	le persone da assegnare, per nome o e-mail; una persona sconosciuta è un errore (`User "..." not found`)
`watcherid`	le persone che lo seguono, per id (a differenza di `users`, lo schema di questa versione non le accetta per nome)
`statusid`	`pending` (predefinito), `open`, `review`, `postponed`, `note` o `closed`
`markdown`, `html`	il contenuto
`tags`, `ispriority`, `isbillable`, `ispublic`	tag e flag
`date`, `deadline`, `worked`	il giorno, una scadenza e i minuti già lavorati
`attachments`	un elenco di `{ name, data }` dove `data` è il file in Base64
`reference`, `source`, `attrs`	campi liberi per collegare il ticket al tuo sistema
`callback`	un indirizzo che riceve il 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 risposta è l’id del nuovo ticket. Le persone assegnate vengono notificate e le sessioni aperte delle persone che possono vederlo vengono aggiornate.

Il callback

Quando callback è impostato, Todomator invia un POST a quell’indirizzo con i dati del ticket quando il ticket viene creato, aggiornato o clonato, e quando viene aggiunto un commento (alla creazione e all’aggiornamento invia anche l’elenco dei campi forniti, keys). Il tuo sistema può usarlo per rispecchiare lo stato di un ticket.

Altre chiamate

Lo stesso endpoint serve le altre azioni, con i nomi di controllers/api.js: tickets (elenco), tickets_detail/{id}, tickets_update/{id}, tickets_clone/{id}, tickets_remove/{id}, logwork_create, folders, tags e altro. La documentazione ufficiale dell’API è su docs.totaljs.com/todomator.