Work Order Import

Read work orders from the body of an email with an email parser

9 min read Work Order Import

An email parser reads the body of the email that arrives. You open a sample email from the sender, tell the parser which label holds the order number, which holds the address and so on, and the import reads the same labels in the emails that follow. It can also hand a PDF attached to the email, or a PDF linked from it, to a PDF parser. This page only exists for a parser whose Document type is Email, and the parser has to be saved on Properties first.

The page has four tabs: Reference documents, Field rules, Guard rules and Test. The Test tab only shows once the parser is saved.

Reference documents

A reference document is a sample email saved as a .eml file. A parser needs at least one, and each one keeps its own rules and its own guard rules.

  1. Save a sample email from your mail program as a .eml file.
  2. Open Reference documents and drop the file on Add a reference email. The drop zone takes .eml files only.
  3. The page moves to Field rules with the email shown beside the rules.
  4. Add the rules (below), then click Save. Saving stores the email and its rules.

Click a saved document to open it again. Delete appears under each document once there is more than one, and the last one can't be deleted. A delete is immediate and doesn't wait for Save.

Add a second document when the same sender writes its emails in more than one layout. A parser imported from an export file carries its rules without the email they were built from, so its document shows as Imported rules, greyed out. Add an email to build on.

Leaving the page, reloading it, or opening another reference document with unsaved rules brings up "Unsaved changes".

Field rules

The left side lists what the parser can read from the open email, and the right side shows the email.

Text rules

A text rule reads one field from the body of the email. Click Add rule, choose the Field, and choose How to find the value.

By label looks for a label in the email wherever it sits.

Option What it does
Label in the email For example Order No. Capitals, doubled spaces, a * and a colon, dash or # after the label don't matter.
Other labels it might have Other labels the sender uses. They are tried when the label above isn't in the email.
The value runs over several lines Takes the lines after the label too, up to the next line that looks like a label, or 40 lines.
Stop before a line that starts with With several lines only. Stops before the first line that starts with this text.

The value is read from the cell beside the label in a table, from the text after it in "Label: value", or from the line under it. A label that is in the email with no value gives an empty value, and another label's value isn't used in its place.

Between two pieces of text reads whatever sits between two strings.

Option What it does
Field value starts with: The text just before the value.
Field value ends with: The text just after it. Both are needed.
Number of end values to skip Skips that many occurrences of the end text before stopping, and keeps the text in between.

Every rule also has Remove spaces, Remove numbers, Remove non-numbers and Text to remove, which clean the value before it is used.

Data found in email

When the email has labels with values, such as the rows of a table or lines like "Order No: 25511", they are listed under Data found in email with their Label, Value in this email and Use as. Choose a field in Use as and a rule for that label is made for you. Clear the field and the rule is deleted. A description or a list of people is set to run over several lines.

Fields you can read

Field Notes
Order number, Project name, Project description
Date issued, Due date, Due time, Response time Simpro only. A Fergus parser isn't offered them.
Site name, Site address
Site contact: name, phone, mobile, email, position A single contact.
Customer contact: name, phone, mobile, email A single contact.
Site contacts (a list of people), Customer contacts (a list of people) A block of text with several people, each added as a contact. See PDF parser rules for how people are read.

An email has no field for project notes. To fill the notes, use a template.

Subject

On a Simpro parser the subject line is listed above the body. Click ... and choose Response Time to use the whole subject as the response time. The subject can't be read for anything else, and a Fergus parser doesn't show it.

Each attachment, and each link in the email body that starts with http, is listed with a ... button. Choose PDF Parser and pick one of your PDF parsers from Please select a PDF parser. The list only holds PDF parsers of the same platform. Click the chip to remove it.

At import time:

  • An attachment is read when it is the same file type as the reference attachment. Every attachment of that type is read.
  • A link is downloaded when it starts with http and is on the same host as the reference link. Every such link is downloaded. Formpiece fetches it without signing in, so a link that needs a login gives no PDF.
  • The PDF parser's rules run on the PDF. They fill any field the subject rule hasn't, and a text rule on the email replaces a value the PDF supplied.
  • If the PDF parser has guard rules and the PDF fails them, the PDF supplies no fields.

A reference email links to one PDF parser. Choosing PDF Parser on another attachment or link replaces the first.

Suggest rules

Suggest rules reads the labels in the open email and shows the text rules it would add. It looks for Order number, Project name, Site address, Date issued, Due date, Project description, Site contacts and Customer contacts, using the labels work orders commonly use, such as Job number, Quote number, Property address, Details, Tenant and Agent. A plain "Date" label is ignored because it is usually the date of a forwarded message.

Each suggestion shows Field, Value found, How it will be found and Existing rule. Tick the ones to keep and click Apply N rules. A suggestion for a field that already has a rule starts unticked and shows Replaces. A value with line breaks in it shows Check. Applied suggestions are on screen until you click Save.

Guard rules

Guard rules say which emails the parser is for. An email is only processed when its subject, sender and body together contain all the guard text, so an email that looks the same but belongs to another business or inbox is skipped. They belong to the open reference email. With none, every email is processed.

  1. Open Guard rules with a reference email open.
  2. Type text under Add text and click Add, or search under Or pick text from the reference email and click Use as guard. Text from the Subject, From and Body is listed.
  3. Choose Contains or Is exactly for each rule.
  4. Click Save.

Case and spacing are ignored. Contains looks for the text anywhere in the subject, the sender and the body. Is exactly needs the subject, the sender, a line of the body or a table cell to be that text and nothing else. An email passes when it meets every rule of at least one reference email that has guard rules.

An email that fails is skipped and recorded with "Skipped: The email did not match the parser's guard rules" and the missing text. If the inbox has recipients under When a work order was not processed, they get an email headed "Work order skipped". See Inbox rules.

Test

Test runs the saved rules on any .eml file and shows what they extract, without creating anything in Simpro or Fergus.

  1. Open Test and drop an .eml file on the drop zone.
  2. Read Extracted fields.
  3. If the parser has guard rules, a Matches the guard rules or Does not match the guard rules badge shows. An email that fails is still read.

The test uses what is saved. Rules you haven't saved aren't in it. A PDF parser linked from the email runs, and the PDF it reads isn't shown.

What this page doesn't cover

Field filters and Field mapping don't change the values of an email parser's text rules. Use the clean-up options on the rule itself. See Field filters.

How it maps to Simpro and Fergus

The fields an email parser reads go to the same places as a PDF parser's. See the mapping tables in PDF parser rules for Simpro and Destination fields for Fergus.

When it goes wrong

A rule finds nothing in some emails

The sender may label the value differently, or send the value in a different place. Add the other labels under Other labels it might have, and run Test on a recent email.

A Between two pieces of text rule finds nothing

The import reads the plain text of the email with every line that contains "From:", "Date:" or "To:" taken out first. A line such as "Due Date: 12/03/2026" is gone before the rule runs. Use By label for those, which reads the whole body.

Both Field value starts with: and Field value ends with: have to be in the email, and a rule with only one of them reads nothing.

A table value is read from the wrong cell

By label takes the next cell to the right of the label in the same row. When the labels sit in a header row and the values in the row under it, the next label in the header is taken as the value. A table with each label and its value side by side reads correctly.

The PDF in the email isn't read

The attachment has to be the same file type as the reference attachment, so a PDF sent with a different content type isn't matched. For a link, the host has to be the same as the reference link, and the page has to return the PDF to anyone who opens it.

More than one PDF is read

Every attachment of the matching type is read, and the first value found for a field is kept. If an email carries the work order and a separate invoice PDF, the PDF parser's rules run on both. Add guard rules to the PDF parser so it skips the one that isn't a work order.

"No fields were extracted from this email. Check the parser settings."

None of the rules found a value. Check the labels in a recent email.

Site details not mapped

The badge by the parser name shows when no text rule reads a Site name or Site address and no PDF parser is linked. A linked PDF parser counts as having them.