Integrations

An integration hands work to an external tool. Whenever a task of your project moves from one status to another, Mabato sends a web request to an address you choose. A typical use is to give a task to an automation tool, a chat service or a build system as soon as it moves to In progress.

Integrations belong to one project, and only the owner of the project sees and manages them. Members who are not the owner do not see the section. In a closed project the section is read-only.

Configuring an integration

You manage integrations in the settings of the project.

Select Projects in the top bar.
On your project, select Edit project. The dialog Edit project opens.
Scroll to Integrations. Existing integrations are listed with their name, the status change and the method.

The Integrations section of the Edit project dialog with one saved integration and the Add integration button — The Integrations section of a project with one integration.

Select Add integration. The form New integration opens.
Enter a Name of up to 100 characters. The name appears in the list and in failure notifications.
Under Runs when a task moves, choose the status change that triggers the request, for example To do → In progress. The statuses are Backlog, To do, In progress and Done, and every pair of two different statuses is available. The integration runs only when a task really changes its status, whether it moved on the board, in the backlog or in the task details. Creating a task triggers nothing.
Choose the HTTP method: POST, PUT or PATCH.
Enter the URL. It must start with https:// and point to a public address. You can insert placeholders after the host name, for example https://builds.example.com/hooks/{{task.id}}.

The New integration form, upper part: name, the status change that triggers it, HTTP method, URL with a placeholder inserted and a header with a hidden value — The upper part of the New integration form with name, status change, method and URL.

If the receiving tool needs a key, select Add header and fill Header name and Header value, for example Authorization and the key. You can add several headers.
Choose the Body format, Text or JSON, and optionally write a Body (optional) that is sent with every call. Use the placeholder buttons below the field to insert task values. Leave the body empty to send no body.
Set the Timeout in seconds (1-60). The default is 10.
Select Save integration. The integration appears in the list.

The New integration form, middle part: the Headers group with one header name and its value field, and the Add header button — The Headers group of the form. The header value is hidden while you type.

The New integration form, lower part: body format JSON, the body with placeholders, the placeholder buttons and the timeout — The lower part of the form with body, placeholder buttons and timeout.

Mabato sets some headers itself, so you cannot use these names: Host, Content-Length, Content-Type, Transfer-Encoding, Connection, User-Agent, Upgrade, TE, Trailer and anything starting with Proxy-. Each header name can be used once per integration. Mabato sends a Content-Type header that matches the body format you chose.

Changing or deleting an integration

In the Integrations section, select Edit next to the integration, change what you need and select Save integration. To leave the form without saving, select Cancel.
To remove an integration, select Delete and confirm with Delete permanently. The integration and its saved header values are gone and cannot be restored.

There is no switch to pause an integration. Delete it, or change its status change, if you do not want it to run.

What happens at a status change

After Mabato has saved the status change, it sends the request in the background. Your change is never delayed or blocked by the receiving tool. A request counts as successful when the tool answers with a status from 200 to 299. Success is silent: nothing is shown or stored.

Placeholders

Placeholders are replaced by values of the task at the moment the request is sent. Write them in double curly braces, or select a button below the URL or Body (optional) field to insert one. Mabato refuses to save an integration that contains an unknown placeholder, or one that is not allowed in that field, and shows Unknown placeholder with its name.

Placeholder	In the URL	In the body	Replaced by
`{{project.id}}`	yes	yes	the id of the project
`{{task.id}}`	yes	yes	the id of the task
`{{transition.from}}`	yes	yes	the old status: `backlog`, `todo`, `in_progress` or `done`
`{{transition.to}}`	yes	yes	the new status, written the same way
`{{project.name}}`	no	yes	the name of the project
`{{task.name}}`	no	yes	the name of the task
`{{task.description}}`	no	yes	the description of the task, empty if it has none
`{{task.acceptanceCriteria}}`	no	yes	the acceptance criteria, one per line in their order, empty if there are none

In the URL, a value is made safe for an address automatically. Placeholders are allowed only after the host name, never inside it.
In a Text body, a value is inserted unchanged.
In a JSON body, a value is escaped so that quotes and line breaks in a task name cannot break the JSON. You write the surrounding quotes yourself, for example {"task": "{{task.name}}", "to": "{{transition.to}}"}.
To write the characters {{ literally, put a backslash in front of them: \{{.
Text that a placeholder inserts is never searched for placeholders again.

Limits

What	Limit
Integrations per project	5. At the limit, Add integration is disabled and the section says A project can have at most 5 integrations. Delete one to add another.
Headers per integration	10
Length of the URL	2,000 characters
Length of a header value	4,096 characters
Size of the body	64 KB
Timeout	1 to 60 seconds, counted for the whole request

Where Mabato may send requests

Only https:// addresses, without a user name or password in the address.
Only public addresses. Local and internal targets such as localhost, addresses of private networks and host names without a dot are refused when you save and again when the request is sent.
Host names with special characters must be entered in their ASCII form (starting with xn--).
Mabato never follows a redirect. Enter the final address.

What is not included

No retries: every status change sends one request.
No test button: to try an integration, move a task through the status change.
No history: Mabato keeps no log of successful or failed requests, only the notification for a failure.

When a call fails

When a request fails, the owner of the project gets a notification in the bell, see Integration failure notifications. The entry names the integration and the task, and gives the reason in plain words:

A failed integration in the notification list: which integration, which task, when, and why it failed — A failure notification with the reason The target could not be reached.

Message	What to check
The target did not answer in time.	The tool is slow or down. Check it, or raise the Timeout (up to 60 seconds).
The target could not be reached.	The host name is misspelled or the tool is offline. Check the URL.
The secure connection to the target failed.	The tool's certificate is invalid or expired. Fix it on the tool's side.
The target answered with status code.	The tool refused the request. A 401 or 403 usually means a wrong key in the header; 404 means a wrong path; 400 may mean the body is not what the tool expects.
The target answered with a redirect (status code), which is not followed.	Enter the address the redirect points to.
The address is not allowed (it is not a public address).	Use a public `https://` address.
The rendered body is not valid.	Check the braces of the body and, for a JSON body, the JSON syntax.
A saved header value could not be read. Please enter it again.	Edit the integration and enter the header value again.
The task no longer exists.	The task was deleted before the request was sent. Nothing to fix.
Too many calls were waiting; this call was dropped.	Many status changes happened at once. Move the task again later.

Select the bell, then the text of the failure entry. The settings of the project open at Integrations.
Select Edit next to the integration named in the entry and correct what the reason points to.
Select Save integration.
Move a task through the same status change to send a new request. Mabato does not retry on its own.