Integration blocks

An integration on its own does nothing until someone runs it. An integration block is how you put one on a job form, as a button the person doing the work presses when they get to that step. They see the answer where they’re standing, and it’s saved against the job.

You add it in a job type’s form builder, so you need the Tenant Admin or Brand Administrator role. The engineer pressing the button needs only the execute permission for integrations on their brand.

Adding one

1. Open the job type and go to its form builder.
2. Drag an Integration field from the palette onto the form.
3. In the properties panel on the right, open Integration Settings and pick your integration from the list. Only active integrations appear; if the list is empty, create one under Settings > Integrations first.
4. Set the rest of the settings below.
5. Save the job type.

The order matters as much as the settings. Put the block after the fields it reads from, so the engineer has filled them in by the time they press the button.

What the engineer sees

Button Label is the text on the button. The default is Run Integration, which tells nobody anything. Say what it does: “Run line check”, “Verify address”.

Trigger Type is Manual (button click) or Auto (on form load). Manual is the right answer nearly always. Auto fires the moment the form opens, which suits a lookup that pre-fills other fields and suits nothing that costs money or changes something at the other end.

Pending Message is what shows while an async integration is waiting for its answer. “Waiting for the line test result” beats a bare spinner when the wait is minutes.

Show raw response (debug) prints the whole reply under the results. Useful while you’re building the integration, noise once it works.

While a run is in progress the engineer sees Executing or, for async, Awaiting response. A finished run says the integration completed successfully. A failed one shows the error with a Retry button next to it. If the other service never answers an async run, it ends with a message saying the run expired.

Input mapping

Each of the integration’s input parameters gets a row, with a required badge where the integration needs a value. For each one you choose where the value comes from.

• Field takes it from another field on the same form, so whatever the engineer typed is what gets sent.
• Static is a fixed value you type here. Good for an account number or a reference that’s the same on every job.
• Entity takes it from the job or the customer record without anyone typing it. Job fields cover the identifier, the job number, status, priority, notes and the scheduled start and end. Customer fields cover the identifier, name, email, phone, the address lines and postcode, the country, and the CRM reference.
• Default uses the default value set on the integration itself. It’s offered only for optional parameters that have one.

Entity is the one that saves the most typing. A line test that needs the customer’s postcode should read it from the customer record, not ask an engineer standing in the rain to type it.

Output mapping

Each output parameter can be pointed at a field on the form, and the result is written into it when the run finishes. Tick Read only so the engineer can’t edit a value the integration produced.

Only map what the person on site needs to act on. A test that returns thirty fields still only wants two on the screen.

Blocking completion

Turn on Required for completion and the job can’t be completed until the integration has run successfully. That’s what you want for a mandatory check: a line test that has to pass before the job can close.

With that on, Auto-complete job appears. Switch it on and the job moves to completed by itself once every blocking integration on the form has resolved. Leave it off if you want the engineer to make that call.

Which form it goes on

Integration blocks go on either form. On the Operator Form the office runs them while booking or editing a job, which suits checks like “is this account on stop”. On the Resource Form the engineer runs them on site.

A run made while booking counts for the job once it is saved, including for Required for completion. Inputs that read job values are empty until the job exists, so a block that needs them waits until the job has been saved.

Where the results end up

Every run is saved against the job, so the answer is still there when someone opens it next week. You can also see it in the integration’s own execution history, and read it back through the API.

What’s next

• The form builder: the rest of the field types
• Custom integrations: the integration behind the button
• Execution and history: what happened when it ran