How work gets into WorkOrders

Four ways, one board

However a request arrives, it becomes the same kind of job on the board. Someone might email you, another system might send it, or a customer might type it in themselves. Either way you get a job with a customer, an address, and the original request saved with it.

There are four ways in. You don't have to pick just one, and most firms end up using two. It's worth knowing what each one is for before you start telling people where to send their requests.

1. Your own WorkOrders address

Every company gets an address as soon as it's created, something like yourfirm@jobs.workorders.nz. It's there before you've set anything else up, it can't be switched off, and any email sent to it becomes a job on your board.

There's nothing to set up. You don't need a password, mailbox details, or any changes to your domain. You'll find it at the top of Settings → Mailboxes, with a button to copy it.

The catch is that it's a new address, and your customers don't know it yet. That's fine if you're putting it on a website contact form, a maintenance agreement or the side of the van. And if you forward your existing inbox to it, your customers don't need to know it at all. That's what most firms end up doing. See your own WorkOrders address for what to do with it.

2. A mailbox you already have

If your customers already write to an address they've used for years, like the one on your invoices, you can leave it as it is and have WorkOrders read the mailbox instead. This works with any mailbox that supports IMAP with a password, such as Gmail or the mailbox your web host gives you. It doesn't work with Microsoft 365 or Outlook, because Microsoft no longer allows it. See Microsoft 365 and Outlook mailboxes for what to do instead.

WorkOrders checks the mailbox every five minutes. It never deletes mail and never marks it as read. Once a message has become a job, it's moved out of the inbox into a folder called WorkOrders-Processed, so anyone else who reads that inbox can see what's been picked up.

The catch is the password. You need a username and password for the mailbox (on Gmail, an app password rather than your everyday one), and a password can be revoked, expire, or be deleted by someone who didn't know what it was for. When that happens WorkOrders stops reading the mailbox, and you'll need to connect it again by hand. Read connecting a Gmail mailbox for the full steps. It's the fiddliest of the four options, which is why it has its own page.

3. Another system raising jobs over HTTP

The work might start somewhere else, like a building management system, a property manager's software, or a maintenance schedule you already run. That system can create the job directly instead of sending an email about it. It sends the job to /api/v1/integration/work-orders using a key you create under Settings → API keys, and it arrives as an ordinary work order.

This one needs someone who writes software, so it's usually something you set up when the other system's people ask how to connect to you. See raising jobs from another system for creating a key and what to give your developer. The developer reference has the full request format, and how to try it without signing a contract.

4. A customer raising a request in the portal

Your customers can see their own jobs in a portal, which they reach from the link in their status emails. You can also let them start a job there, using a short form that asks what needs doing and where.

This is off until you switch it on in Settings → Your company. Switching it on gives every one of your customers a request form, and plenty of firms would rather every request came through someone who knows the customer.

It isn't open to the public. To use the form, a customer has to sign in to the portal, and they do that by clicking a link emailed to an address you already have on a customer record. The link at the bottom of a status email only shows one job, and it isn't enough to use the form. A request raised in the portal is marked as coming from the portal, with the customer already filled in. WorkOrders takes the customer from their record, not from the form, so nobody can raise a request in someone else's name.

So which one?

For most firms the answer is to use the first two together, without connecting anything. Keep the address your customers know, and set up a rule in that mailbox to forward everything to your WorkOrders address. Your customers don't have to change anything, and you don't have to give anyone a password.

• Starting fresh, or happy to hand out a new address? Use your WorkOrders address on its own. It's the only option with nothing to break.
• Want to keep the address customers know, without sharing a password? Forward that inbox to your WorkOrders address.
• Want processed mail moved into its own folder, or can't set up a forwarding rule? Connect the mailbox over IMAP.
• Work arriving from another system? Use the API, alongside any of the above.

Two ways in doesn't mean two jobs

The same email arriving two ways only ever makes one job. If you forward your inbox to your WorkOrders address and connect that same inbox over IMAP, WorkOrders recognises the second copy and doesn't create a second job for it.

Every email has an ID that the sender's email program gave it, and WorkOrders keeps track of the ones it has seen for your company. Two copies of the same message have the same ID, and two separate emails never do. So you can run both at once, for example while you're changing over, without anyone having to close duplicate jobs.

If something you expected hasn't turned up, or has turned up twice, see an email didn't become a job. It covers the emails that never become jobs, and how long to wait before you worry.