OCR Text Extraction

OCR (optical character recognition) reads text from images, scanned PDFs and pictures inside Word documents, so your rules can file or protect email based on what those files say. This page explains how to get OCR, the four OCR variables, and how they differ from the regular attachment text that mxHERO already reads.

Before you begin

• OCR is enabled by mxHERO on request. It is off by default. Ask your mxHERO representative or support@mxhero.com to enable it for your organization.
• Until OCR is enabled, the OCR variables don't appear in the variable lists.
• Know how to build variables. See Custom Variables.

Text mxHERO reads without OCR

Most attachments already have text that mxHERO reads directly, without OCR. This text is in the Attachments Text variable (attachments_text), available to every organization:

• Plain text, HTML and RTF
• Word (.doc, .docx), Excel (.xls, .xlsx) and PowerPoint (.ppt, .pptx)
• PDF files that have a text layer (created digitally, not scanned)
• AutoCAD drawings (.dwg): text, multiline text, block attributes and attribute definitions in the drawing

Note: DWG text extraction is not OCR. It reads the text objects stored in the drawing file and needs no activation. Only .dwg is supported; other CAD formats (for example .dxf) are not read, and text that exists only as lines or a raster image in the drawing can't be read.

Use OCR when the text you need is in a picture: scanned documents, photos, screenshots, or image-only PDFs.

OCR variables

When OCR is enabled, four variables are added:

Use them like any other text variable: in conditions (contains, matches regex, dataset matching), in convert values, in file paths and names, and in policies. See Regular Expressions.

How OCR runs

• Only when needed. OCR runs only when a rule actually uses one of the OCR variables, and only for that file type. Rules that don't use them aren't slowed down.
• One attachment at a time. When a rule names or files each attachment separately, only the variable that matches that file's type returns text.
• Results are reused for 14 days. If the same file (identical content) arrives again in your organization within 14 days, the saved result is used. Results are never shared between organizations.
• Large documents take longer. If reading a file takes too long, mxHERO keeps the partial result and the email is processed again later to finish. This can delay filing for that email.

Limits

OCR accuracy depends on scan quality. Handwriting, low resolution, skewed pages and unusual fonts reduce accuracy. Allow for small errors in your patterns, for example by matching a number rather than a name.

Example: file scanned forms by employee ID

A scanner emails each scanned HR form as a PDF. The form has the line Employee ID: 48213.

1. Create a variable:
   • Source: attachments_pdf_text
   • Condition: matches regex with Employee\s*ID\s*:?\s*(\d{5})
   • Convert value: the group 1 placeholder
2. Use the variable in the rule's storage file path, for example HR Forms/{Employee ID}/.
3. Test the variable with a sample .eml of a scanned form.

Verify

1. After mxHERO confirms OCR is on, open Auto Filling › Variables and create a variable. The OCR variables are listed among the Application fields.
2. Click Test variable, then Upload an email, and upload a sample email with a scanned attachment. The OCR text should appear in the result.
3. Send a test email through the rule and check the result in Email Flow Logs.

Troubleshooting

Related pages

• Variables Reference
• Custom Variables
• Regular Expressions
• Mail2Cloud Advanced Overview