Ostara in Agent Builder

The Ostara step lets an agent read and change work orders in your Ostara account as part of a run. It can fetch a work order by its number, accept it, give an ETA, add a note or set the client reference. It can also record an engineer's travel, start, pause and stop, attach documents and certificates, create a work order, and authorise, refuse or cancel one. Each step does one thing, picked from 16 actions, and hands what Ostara sends back to the next step. The same connection also drives the Ostara webhook trigger, which starts an agent when Ostara reports one of the events you tick, such as a work order being assigned.

app.centrus.ai/app/agents/workflow-builder

Agents

Build modular AI workflows with reusable nodes

New work order, new job

1,240 / 10,000 creditsValidateResetRunsSettingsUpdate & Publish

New Ostara work order

Assigned

Fetch the work order

Get work order

2

Raise the job

Create job

Accept the work order

Accept job

AI builderMap

1. 1Ostara in the Integration group of the Nodes panel.
2. 2The step on the canvas. Its summary shows the action, Get work order.
3. 3Connection: whether this agent has an Ostara connection. It shows the name Ostara, not the account.
4. 4Endpoint: the action the step performs, chosen from the full list.
5. 5The action's field. Here the work order number comes from the alert that started the run.

Centrus works alongside Ostara. Work orders stay in Ostara, and the agent reads and updates them there through Ostara's API. A new work order can raise a job in BigChange, described in BigChange REST in Agent Builder. To look up and update work orders in a conversation rather than in an agent, see Ostara in chat. How every integration fits together is in Integrations overview.

Open the agent in Agent Builder and find Ostara in the Integration group of the Nodes panel. It sits after Xero and before Freshdesk. Drag it onto the canvas and connect the step before it to its left-hand side. Until you choose an action, its summary on the canvas reads No endpoint selected.

New Ostara work order

Assigned

Ostara

No endpoint selected

2

1. 1Ostara in the Integration group. Drag it onto the canvas.
2. 2The new step. It reads No endpoint selected until you choose an action in its Details panel.

On a phone, Agent Builder shows the canvas only. The Nodes panel is hidden on screens narrower than 768 pixels and the Details panel on screens narrower than 1,024 pixels, so you can follow an agent's steps on a phone but need a tablet or computer to add an Ostara step or change its settings.

09:41

Centrus

Agents

Build modular AI workflows with reusable nodes

Chase overdue invoices

Save and Publish

New Ostara work order

Assigned

Fetch the work order

Get work order

Raise the job

Create job

Accept the work order

Accept job

The Ostara connection belongs to this agent alone. It is separate from the organisation's Ostara connection in chat, so connecting one does not connect the other. One connection covers every Ostara step in the agent and its Ostara webhook trigger, so you only connect once per agent.

You need three values from Ostara: the Username of your Ostara inbound API account, the API key Ostara emailed you, and the Client host name. The host name is the short name at the start of your Ostara API address, such as meridian, not the full address. Anyone who can edit the agent can enter them. They are stored on this agent only. Ostara decides what the username and key may read and change.

1. 1Save the agent with Save draft. Until it has been saved once, the Connection section reads Save this workflow as a draft first, then connect the account. and Connect is greyed out.
2. 2Select the Ostara step. In the Details panel, open Connection and click Connect.
3. 3In the Connect Ostara window, enter the Username, API key and Client host name, then click Connect.
4. 4Centrus checks the values with Ostara, by reading your account's list of action names, before it saves them. Connection then reads Connected · Ostara. It does not show the host name or the username.

If a field is empty, Centrus stops in the window with Username is required, API key is required or Client host name is required. If Ostara refuses the username or key, nothing is saved and the message is Ostara rejected the username or API key. A host name with anything other than letters, numbers and hyphens, such as a space or a dot, is refused with a message that starts Ostara client host name is invalid. Enter the short name only, such as meridian: Centrus builds the rest of the address itself.

Two sets of credentials. The username and API key you enter here are for calls Centrus makes to Ostara. When Ostara calls Centrus with an alert, it signs in with a different pair, the webhook username and password, which Centrus generates when you connect. They appear on the Ostara webhook trigger, described under Start an agent from Ostara alerts. Do not swap one pair for the other.

Reusing a connection. If you have already connected Ostara on another agent you created, choose that agent under Copy from existing agent. Centrus fills in the three fields from it, and you click Connect to save them on this agent. The webhook username and password are not copied: this agent gets its own. The list only shows agents you created that are not archived and have an Ostara connection, so an agent someone else shared with you never appears. When there are none, the box reads No other agents with this connection. If the copy itself fails, the message is Could not copy credentials from that agent.

Sharing and copying the agent. When you share an agent, its Ostara connection stays with it, and everyone who runs it uses that connection rather than their own. When you duplicate an agent, the steps are copied but the connection is not, so connect Ostara again on the copy. Copy from existing agent makes that quick. For the details, see Share an agent.

Disconnecting. Disconnect removes the credentials from this agent only, including the webhook username and password. Its Ostara steps and trigger stop working until someone connects it again, and other agents keep their own connections. A successful connect shows Ostara connected to this agent.

Select the step and open Endpoint in the Details panel. Its first line reads: Choose the Ostara action. Writes change the live work order. There is no work-order list. Chat only has lookup, accept, ETA, notes, and client reference. Endpoint tool type holds all 16 actions in one list that starts with List action mapping. The list has no search box and no headings, so the tables at the end of this guide are the quickest way to find the exact name you need. The line under the list is the action's own description.

Keep Set endpoint fields here. Let AI populate endpoint fields hides the fields so that an AI can fill them, but on a step in the agent's main flow nothing fills them in when the step runs. To have an AI choose the values, attach the step to an AI step as a tool instead, as described below.

The descriptions of most changes end with After the user confirms. This changes the live work order. There is no undo from Centrus. That wording is shared with chat. On a step in the main flow nobody is asked: the change is made as soon as the run reaches the step. To have someone check first, put an Approval step in front of it.

Each action then shows its own fields in a box named after the action. The box starts closed: open it to fill the fields. Each field's label is the first sentence of its description, and a required field is marked with an asterisk. Get work order has one field, Ostara work order number, which takes the number Ostara gives the work order, such as 48213. Some fields on the engineer, document and decision actions have no description, so their labels are Centrus's internal names: Externalreference, Externaldatetime and Externaluser. They are optional.

To use a value from an earlier step, open Step data references at the top of the Details panel. The Ostara trigger and Ostara steps list no fields there, so type the reference yourself. The work order number from the alert is {{ trigger.json.id }}, as in the overview agent.

Dates and times are text in ISO 8601. The ETA fields ask for a time in UTC or with an offset, such as 2026-10-12T08:00:00+01:00 for 08:00 on 12/10/2026 in British Summer Time. The work order number is text too, so a reference can be pasted into it, but it must hold digits only when the step runs. Documents on Add document, Certificates on Add certificate, and the contact, tasks and locations on Create work order each take a JSON array or object typed into one box. Optional system reason type on Pause job is a number field, so it takes a fixed number and not a reference.

What the step passes on. When the step runs, it passes on the item it received with Ostara's reply added, so the alert's fields are still there for later steps. After Get work order, the work order's fields sit alongside them. A change acts on the first item it receives only. To change several work orders, put the step inside a Loop with a batch size of 1, described in Conditions, loops and approvals.

As a tool for an AI step. Connect an Ostara step to the Tools side of an Intelligence step and its Details panel changes. Instead of one endpoint, Actions lets you choose several, with a search box, and the AI decides when to call each one and fills in the fields itself. On the canvas, the summary names up to three of the chosen actions, then shows the first name and a count.

New Ostara work order

Assigned

Decide the ETA

GPT-5.6 Terra

Work order actions

Get work order, Accept job, Provide ETA

1

1. 1The Ostara step attached to the Intelligence step as a tool. The canvas names the actions it may call.
2. 2Actions: the Ostara actions the AI may call.
3. 3Pause for approval: each call the AI makes waits for someone to approve it in the Runs panel.

Pause for approval appears on every Ostara step but only applies to calls an AI makes, so it has no effect on a step in the main flow. To ask someone before a main-flow step changes Ostara, put an Approval step in front of it. A change also claims the action before it calls Ostara, so a repeated run of the same change reuses the first result instead of sending it twice.

The Ostara webhook trigger, in the Trigger group of the Nodes panel just below Freshdesk webhook, starts the agent when Ostara reports an event you have ticked, such as Assigned for a work order assigned to you. It uses the agent's Ostara connection, so if an Ostara step is already connected, the trigger is too. Setting up, testing and costs for every system are covered in Start an agent from a system alert. This section covers what is particular to Ostara.

New Ostara work order

Assigned

Fetch the work order

Get work order

Raise the job

Create job

Accept the work order

Accept job

1. 1Connection, shared with the agent's Ostara steps. Connected, it reads Connected with no account name.
2. 2Events: the events that start a run. Only Assigned is ticked.
3. 3Set this up in Ostara: the steps to follow in the Ostara portal, the endpoint URL, and the webhook username and password.
4. 4Simulate webhook: runs the agent once with a sample work order.

Every event it can listen for. There are 25 events in one list, with no headings and no codes. Tick only the ones the agent needs, because each event that matches starts a run and each run uses credits. The agent cannot be published until at least one is ticked: Centrus says Ostara webhook needs at least one event selected before it can be published. The canvas summary names every ticked event, separated by commas, and reads No events selected until you tick one.

Assigned suits an agent that raises a job for each new work order. Job Stopped also fires when a job is paused, so an agent on Job Stopped should not assume the work is finished. The node does not explain the other events, and Ostara decides when it sends each one. If an agent changes a work order, avoid ticking the event its own change could cause, such as Notes Added on an agent that adds notes, so that it does not start itself again.

Who sets it up, and where. The Centrus side is done by anyone who can edit the agent. Centrus does not register the endpoint with Ostara: someone with access to the Ostara portal adds it, and Ostara Support has to whitelist the address. Set this up in Ostara starts: Ostara does not call Centrus until this endpoint exists in their portal and they have whitelisted the URL. Its steps, with the Centrus side first:

1. 1Connect Ostara on the trigger and save the agent. Webhook username and Webhook password appear under the endpoint URL. They stay the same if you connect again without disconnecting.
2. 2In the Ostara portal, open your avatar, then API Integration.
3. 3Add an endpoint and choose Webhook, not Email.
4. 4Paste the endpoint URL from the node. Copy beside it copies the URL and shows Endpoint URL copied. The address is the same for every organisation. Centrus tells the agents apart by the webhook username.
5. 5Choose basic authentication, with the webhook username and password from the node. Do not use the API key you entered to connect.
6. 6Tick the same events as the node.
7. 7Ask Ostara Support to whitelist the URL, then set the endpoint to Active.

Pointing at Have you set this endpoint up?, under the steps, shows the same steps again. Under the URL, the node says: Paste these into the Ostara endpoint. They are not the inbound API key. Until the trigger is connected, it reads Connect Ostara to generate the webhook username and password. instead.

Centrus checks the webhook username and password on every alert, and an alert with the wrong pair is turned away without starting anything. Disconnect deletes the pair. Connecting again creates a new one, so after a disconnect, update the endpoint in Ostara. A second agent has its own pair, so it needs its own endpoint in the portal. The password is shown in full on the node, with no copy button, to anyone who can open the agent.

What the trigger hands on. Ostara sends the work order as it stands after the action. Each alert becomes one item for the next step, with id, the work order number; status; clientreference; etadatetime; attendance, holding workstartdatetime and workenddatetime for the visit; event, holding actiondescription, the name of what happened, and datetime, when it happened; eventType, such as job_stopped; and triggerType, which is ostara. Reach them with references such as {{ trigger.json.id }} or {{ trigger.json.attendance.workenddatetime }}. Ostara decides which of these it fills in for each event, so for anything more, follow the trigger with Get work order.

An alert whose event Centrus does not recognise is ignored. If Ostara sends the same event twice with the same time, the agent runs once.

Simulating an alert. Once the agent is saved, Simulate webhook runs it once for the Event and Work order id you enter. Event starts on Job Started, and any of the 25 events can be chosen, ticked or not. The sample carries the work order number and the event. It has no status, client reference or ETA, and only a visit start for Job Started or a visit end for Job Stopped, set to the moment you click. Use the number of a real work order so that Get work order after it finds something. A simulated alert is a real run rather than a dry run: write actions change Ostara, and the run uses credits. The sample does not call Ostara for the event itself. Simulate webhook stays greyed out until Work order id has something in it. A successful start shows Simulated webhook started. See the Runs panel.

New Ostara work order

Assigned

Fetch the work order

Get work order

Raise the job

Create job

Accept the work order

Accept job

New work order, new job raises a BigChange job when Ostara assigns a work order. New Ostara work order is an Ostara webhook with Assigned ticked. Fetch the work order uses Get work order with {{ trigger.json.id }}, so the agent has the whole work order, such as 48213 for Northgate Housing at Riverside House. Raise the job uses Create job in BigChange and sets the job's reference to the work order number, so a later agent can find the work order again. Accept the work order uses Accept job with the same number, and the new BigChange job number as the optional external reference. Each new work order costs 4 credits. To check each one before it is accepted, put an Approval step in front of Accept the work order.

Weekdays at 17:00

Daily at 17:00 · Mon, Tue, Wed, Thu, Fri

Tomorrow's jobs

List jobs

Ostara jobs only

Keep ALL of 1 rule(s)

Each job

Batch size 1

Set the ETA

Provide ETA

Email the planners

1 action enabled

Tomorrow's ETAs writes an ETA on each Ostara work order booked for the next day, at 17:00 each weekday. Tomorrow's jobs uses List jobs in BigChange for the next day. Ostara jobs only is a Filter that keeps the jobs whose reference holds an Ostara work order number, as New work order, new job sets it. Each job is a Loop with a batch size of 1, because a change acts on the first item it receives. Inside it, Set the ETA uses Provide ETA, with the job's reference as the work order number and its planned start as the ETA, such as 08:00 on 16/10/2026. Provide ETA is for work orders that are already accepted. Email the planners sends Priya Shah the list of ETAs given. The list costs 1 credit, the Filter 0.1, and each Provide ETA inside the Loop another credit.

Job stopped

Job Stopped

Fetch the work order

Get work order

Write the update

GPT-5.6 Terra

Email the office

1 action enabled

Job stopped note tells the office when an engineer stops work on an Ostara job. Job stopped is an Ostara webhook with Job Stopped ticked. Fetch the work order uses Get work order with {{ trigger.json.id }}. Because Job Stopped also fires when a job is paused, Write the update reads the work order and the alert, and its instructions say not to call the job finished unless the work order shows it. Email the office sends Sarah Price two lines, for example that Dylan Hughes stopped work at Riverside House at 16:40 on 09/10/2026, taken from {{ trigger.json.attendance.workenddatetime }}. Nothing in Ostara changes, so the agent is safe to try with Simulate webhook.

A dry run is the safe way to try an Ostara step. Open Runs in the toolbar, click Run now and choose Dry run (no actions performed). Get work order and List action mapping call Ostara for real, so you see real data. The 14 changes are skipped, and the step's summary starts with DRY RUN and says the change was not performed, so nothing in Ostara changes. The summary names the change by its internal name, such as ostara_provide_eta for Provide ETA. Run for real performs every action, including the changes.

{
  "dryRun": true,
  "wouldPerform": {
    "provider": "ostara",
    "tool": "ostara_provide_eta",
    "args": {
      "workOrderId": "48213",
      "etadatetime": "2026-10-16T08:00:00+01:00"
    }
  }
}

A dry run does not check the values a change would send, so a work order number with letters in it only fails in a real run. An agent that starts from Ostara alerts has no alert when you click Run now, so {{ trigger.json.id }} is empty and Get work order fails with Ostara work order id must be a number. To dry-run it, type a real work order number in place of the reference while you test, then put the reference back.

Open a step in the run to see its output. The panel shows the first 50 items of each output, and later steps still receive all of them. A dry run costs 1 credit for the whole run. A simulated Ostara alert is not a dry run, so test changes with Run now first. For Run now, dry runs and the Runs panel in full, see Test an agent before it goes live.

An Ostara step costs 1 automation credit each time it runs successfully, whatever the action. A step that fails costs nothing. When the step is a tool, each call the AI makes costs 1 credit. The Ostara webhook trigger is free, but every run it starts costs 1 credit, like any other run.

Inside a Loop, the step is charged on every pass, so a Loop that gives an ETA on 40 work orders costs 40 credits for that step. Ostara has no list of work orders in Agent Builder, so every work order is fetched or changed one call at a time. Tick only the events an agent needs: an event ticked by mistake starts a run, and costs credits, each time Ostara sends it. For allowances, limits and how to see what each run cost, see Automation credits and usage limits.

• No list and no search. There is no action that lists or searches work orders, so every action except List action mapping and Create work order needs the work order number. List action mapping returns Ostara's action names, not work orders. Get the number from an Ostara alert, or from a job in another system where you stored it.
• One request at a time. Ostara allows one request at a time for each username. Centrus queues its own calls for the same host and username, including chat when it uses the same username. If something else is calling Ostara with that username, the step fails with Ostara allows only one request at a time. Retry shortly. Centrus does not retry it for you.
• Pause job needs its tick box touched. Whether a short-term fix is in place is required. A box that has never been ticked sends nothing, so the step fails with Ostara istemporaryfixinplace is required. To send yes, tick it. To send no, tick it and then untick it.
• Clearing a client reference. Update client reference says an empty value clears the reference, but on a step in the main flow an empty Client reference box is left out of the request rather than sent empty. Use the step to set a reference, and clear one in Ostara.
• Documents by web address. Add document and Add certificate attach files by an https address, not by upload. Each document needs a description and a url. Each certificate needs a description, a url, validfromdate, validtodate and isfailcertificate. An address that is not https is refused with Ostara document upload from this tool needs an https URL.
• Changes that cannot be undone. Every change is made on the live work order, and the descriptions say there is no undo from Centrus. Create work order adds a live work order, Cancel job needs a reason in Why the work order is being cancelled, and Refuse job turns the work order down.
• Per-user integration mode. Ostara only works with the agent's own connection. The Connection section says the step uses it even in per-user mode, but in per-user mode the step fails and tells you to switch the agent back to agent-level mode. An agent with the Ostara webhook trigger cannot be published in per-user mode, or switched to it: Centrus says Ostara webhook cannot use per-user credentials. Use the agent Ostara connection.
• Published agents only. Alerts only start runs once the agent is published. Simulate webhook and Run now work on drafts. Which events start a run is read from the agent as last saved, while the steps that run are the published ones, as explained in Start an agent from a system alert.

• Ostara is not connected to this agent. Open the step's Connection section and click Connect. If you have duplicated the agent, the copy needs its own connection.
• Ostara rejected the username or API key. Ostara refused the values. Check that you used the inbound API username and the API key from Ostara's email, not the webhook username and password, then connect again.
• Username is required, API key is required or Client host name is required. A field in the connect window was empty. Fill all three in.
• Ostara client host name is invalid. The host name held something other than letters, numbers and hyphens. Enter the short name only, such as meridian.
• Stored Ostara API key is invalid. Please reconnect. Centrus cannot read the saved key. Disconnect, then connect again.
• Ostara work order id must be a number. The work order number was empty or held something other than digits. Check the reference, and on an agent that starts from alerts, remember that Run now has no alert to read it from.
• Ostara could not find that URL or work order. Ostara has no work order with that number for this account, or the host name points at the wrong account. Check both.
• Ostara rejected the request: followed by Ostara's reason. Ostara turned the request down. Correct what the reason names and run again.
• Ostara allows only one request at a time. Retry shortly. Another request was using the same username. Run the agent again a little later.
• Ostara istemporaryfixinplace is required. Pause job was sent without the tick box. Tick it for yes, or tick and untick it for no.
• Ostara notes is required. or Ostara attendee is required. A required field was empty, such as the reason on Cancel job or the engineer on Start job. The message uses the field's internal name.
• Ostara documents is not valid JSON. or Ostara certificates is not valid JSON. The box held text that looked like JSON but was not. Check the brackets and quotation marks.
• No action selected. The step has no action yet. Choose one under Endpoint tool type.
• An alert never starts the agent. Check that the agent is published and the event is ticked, and that the endpoint in the Ostara portal is a Webhook, not Email. It must be Active and whitelisted by Ostara Support, and use basic authentication with this agent's webhook username and password. After a disconnect, the endpoint needs the new pair.
• Provide a work order id to simulate against. Simulate webhook needs a work order number. Use a real one so Get work order can find it.
• No other agents with this connection. None of the agents you created has an Ostara connection. Enter the three values by hand.
• The step fails in per-user mode. Switch the agent back to agent-level integration mode. Ostara has no per-person connection in Agent Builder.

The Ostara step offers 16 actions: 2 read from Ostara and 14 change it. Every endpoint below is on https://{client}-ostaraapi.ostarasystems.net, where the client is the host name you connected. The 13 changes to an existing work order all post to the same address, with the action's name in the request, such as acceptjob. Fields marked required must be filled in. Most changes also take optional notes and the optional external fields, which Centrus passes to Ostara with the action.