Automate job creation in BigChange from emailed work orders

This article builds one agent that turns work order emails into BigChange jobs. Each time a work order lands in the folder you choose, the agent reads it, whether the details are in a PDF or in the email itself. It finds the contact and site in BigChange and checks for an open job at that site. A person on the service desk approves it, and the agent creates the job unscheduled, with the fault and the client PO in a note. The desk allocates the visit in BigChange as normal.

BigChange stays the record. The agent reads and writes there through the BigChange REST step, and nothing is raised without your desk. Why emailed work orders stall, and how the same agent works in Joblogic and Simpro, is in the guide How emailed work orders become jobs.

Before you start, have these ready:

• Edit access to an agent in Agent Builder.
• Your BigChange Customer ID, Client ID and Client Secret, from Admin, then API Web Services in BigChange. See Connect the step.
• An Outlook or Gmail mailbox that can sign in for itself, with a folder or label the work orders land in. A Microsoft 365 shared mailbox cannot be watched, so forward its work orders to one that can.
• One real work order from each client, to test with.

The agent has seven steps, built left to right on the canvas. The names are suggestions; the step types and settings are what matter.

1. 1Work orders: an Email received trigger on the folder, such as Inbox/Work orders, with the client's domain in From contains.
2. 2Download the work order: an Outlook (or Gmail) step with Download attachments turned on.
3. 3Read the work order: a File Parser step with PDF ticked and a field for each detail the job needs.
4. 4Find the site: an Intelligence step with a BigChange REST step attached as a tool, offering Search contacts and Search jobs by address.
5. 5Desk approves: an Approval step, by email reply to the person on the desk.
6. 6Raise the job: a second Intelligence step with a BigChange REST tool offering Create job and Create note.
7. 7File the email: an Outlook step with Move email to folder, such as Inbox/Work orders/Done.

Work orders written in the email itself, with no PDF, need a small change to steps 2 and 3, set out under Plain-text work orders.

In the Nodes panel, open Trigger and click Email received. Under Mailbox, choose the Provider and enter the Folder (Outlook) or Label (Gmail). For a folder inside the inbox, give the path from the top: Inbox/Work orders, not Work orders. Save the agent, then click Connect under Connection and sign in as the mailbox you want watched.

Open How do we decide this is the right email? and keep the filters tight, because every email that passes starts a run that uses credits. Put the client's domain in From contains, such as @haldenhousing.co.uk, and set Has attachments to Yes for a client that always sends a PDF. Emails that miss the filters cost nothing. Every setting is in Start an agent when an email arrives.

Email received cannot use Per-user integration mode, and BigChange REST only works with the agent's own connection. Keep the agent on Agent-level in Settings.

Add an Outlook step with Download attachments turned on. It fetches every file on the email and passes each one on separately. Then add a File Parser step. Under File types to parse, tick PDF only, and turn on Stop the branch when the file is missing or not a selected type, so a signature logo or a spreadsheet does not carry on.

Under What to extract, say in plain words what to pull out, for example: the client's work order number, the site name and address, the fault, the priority and the client PO. Add a Structured field for each, such as work_order, site, fault, priority and client_po, so later steps can use them by name.

Each file goes through the rest of the agent on its own, so an email with two PDF work orders makes two jobs, each with its own approval.

Add an Intelligence step. Attach a BigChange REST step to its Tools side and, under Actions, choose Search contacts and Search jobs by address. These actions only read, so leave Pause for approval off. Connect BigChange on the step with the three values from BigChange, as described in Connect the step.

Tell the step what to do in plain words, for example: Find the BigChange contact and site for this work order. Then look for an open job at that site with the same client reference. Write the contact, the site, the fault, the priority and the client PO, and say whether an open job already exists and its reference. If the site cannot be matched, say so.

Search contacts finds contacts and sites by name, address, postcode or reference, so the work order does not need to use your own site name. The AI fills in each action's fields itself, which matters because many BigChange ID fields only take numbers and cannot hold a reference to an earlier step.

Add an Approval step after Find the site. Set How approval is granted to By email reply and enter the address of the person on the desk, such as Megan Ellis. She replies APPROVE or REJECT and does not need a Centrus login. Centrus does not tell anyone that a run is waiting in the Runs panel, so email approval suits a busy desk better.

The subject and Message to the approver take expressions, so include the site, the fault, the priority, the PO and whether an open job was found. Set How long to wait for approval to 8 hours or less, because a run lasts 8 hours at most. Set If the timeout elapses to Treat as rejected and continue, so nothing is raised that nobody saw.

Connect the Rejected exit to whatever should happen instead, such as an email to the desk. While a run waits, the next work order for that agent waits too, so approvals need answering through the day. Once the jobs have matched the desk's for a few weeks, you can keep the approval for the unsure ones only, behind a Condition. See Conditions, loops and approvals.

From the Approved exit, add a second Intelligence step and attach a BigChange REST tool with Create job and Create note. Tell it: Create one job on the contact and site found, then add a note to it with the fault, the client PO and the client's work order number. If an open job already exists for this work order, add the email as a note on that job instead and create nothing.

Leave Schedule job off the list, so the job is created unscheduled and the desk allocates the visit. Leave Pause for approval off on this tool too. The Approval step has already asked the desk, and a run paused by a tool cannot be approved from the Runs panel today.

To tell the account manager, add an Outlook step that emails them the job reference. To answer the client in the same thread, use Reply to email. Finish with Move email to folder, because the trigger does not mark emails as read or move them, and the desk can then see which work orders have been dealt with.

Some clients write the work order in the email, with no file. For those, leave out Download the work order and Read the work order, set Has attachments to Any, and add an Outlook step with Get conversation after the trigger. Find the site then reads the email itself, which reaches it as {{ trigger.json.bodyText }}, and the thread shows whether it is a reply about a job that already exists.

If one client sends PDFs and another writes plain text, build two agents, each watching its own folder, and have an Outlook rule or a Gmail filter file each client's emails into the right one.

Every email starts its own run, replies included. A reply such as Re: WO-55821 goes through the same steps: Find the site sees the open job, and the approved run adds the reply as a note rather than raising a second job. The agent's own replies sit in Sent Items and start nothing. A resent copy is a new email, so the check runs again.

Send a real work order into the folder, then open Runs, click Run now and choose Dry run (no actions performed). The run uses the latest email in the folder. BigChange searches run for real, so you see the contact and site it found. Create job and Create note are skipped, and their summary says what they would have done. A dry run costs 1 credit.

Put each dry run next to the job the desk raised by hand, and publish once a week of them match. Emails already in the folder before you publish are never picked up, so the first live run is the next work order to arrive. On a live agent, test with Dry run only: Run for real uses the latest email even if the agent has already dealt with it, and raises a second job. More in Test an agent before it goes live.

Waiting costs nothing, and so does an email that misses the filters. A PDF work order that becomes a new job uses at least 13 credits:

Plans start at £299.99 a month for up to 5 users, with 10,000 automation credits a month, so 200 work orders at about 15 credits each use 3,000. See Automation credits and usage limits.

• No run starts. Check that the agent is published, the folder path is right (Inbox/Work orders, not Work orders) and the email passes every filter. Emails that arrived before you published are never picked up.
• BigChange REST token request failed (HTTP 401). BigChange rejected the Client ID or Client Secret. Disconnect and connect again with the right values.
• The site is not found. Read what Find the site wrote in the run. If the client names the site differently from BigChange, tell the step which detail to search on, such as the postcode or the client's site reference.
• Two jobs from one email. The File Parser read two files. Tick PDF only, and turn on Stop the branch when the file is missing or not a selected type.
• Work orders queue up. A run waiting for approval holds the emails behind it. Answer approvals promptly, or keep the approval for the work orders the agent is unsure about.
• The run failed after a long wait. The decision came more than 8 hours after the run started. Set How long to wait for approval to 8 hours or less.