Custom Variables

A custom variable turns information in an email into a value you can use in a folder path, a file name or a policy. For example, it can pull a six-digit project number out of the subject, map a sender's domain to a client name, or answer "does this email contain an invoice?". This page explains how to create, test and maintain custom variables in Auto Filling › Variables.

Before you begin

• Know which built-in values you want to start from (subject, body, sender, attachment name, and so on). See Variables Reference.
• If you will look values up in a list, create the dataset first. See Datasets.
• Have a sample email (.eml or .msg, up to 25 MB) for testing.

How a variable works

A variable is one or more condition blocks. Each block reads one or more fields, tests them with a condition, and then either returns a value (then convert to), looks the result up in a dataset (and map with), or adds another condition (and).

• Conditions joined with and must all match.
• Blocks joined with Add OR condition are alternatives: the first block that matches produces the value.
• If nothing matches, the variable is empty, or returns its Default Value if you set one.

How mxHERO evaluates a custom variable: OR blocks are tried in order until one matches.

Filter, Copy, Security and Template Policies use whether the variable matched, not the value it returns. A variable that falls back to its Default Value counts as no match.

The Variables page

Open Auto Filling › Variables. The page has two tabs:

• Variables: your organization's variables, with Edit, Copy and Delete.
• Default Variables: nine built-in variables, with Show and Copy.

Create a variable

1. In Auto Filling › Variables, click Create.

   

2. Enter a Variable Name (required) and, optionally, a Variable Description. The name is what you'll pick from the { list, so make it clear, for example Project Number.

3. In the first select, choose what the condition reads:

   • When Fields: built-in email fields. Then choose one or more in Application fields. Type to filter; each entry shows a description.
   • When Variables: another variable, such as a default variable. Then choose it in Select a variable.

   

4. Choose a Condition and enter a Value. See Conditions.

5. Choose an Action:

   • then convert to: enter the value the variable returns. Type { to insert placeholders, such as a regex group or any built-in variable. The SUGGESTED VALUES box lists the placeholders the condition produces.
   • and map with: look the result up in a dataset. See Look up a dataset.
   • and: add another condition that must also match.

6. To add an alternative, click Add OR condition and fill in the new block.

7. Optionally, turn on Use a default value on no match and enter a Default Value. This avoids empty folder names when nothing matches.

8. Click Save variable.

The variable now appears in the Variables tab and in the { list as a User variable.

Conditions

Date and count fields (for example Received Date / yyyyMMdd or Recipients Address Count) can also be compared with greater-than and less-than conditions.

Matching is not case-sensitive: invoice matches INVOICE.

Values you can return

In then convert to and in path fields, type { to insert:

You can combine placeholders and text, for example PRJ-{Regex group 1}.

Important: Older articles use ${1} for regex groups. That syntax doesn't work here. Insert groups from the { list.

Look up a dataset

Use a dataset to translate a value into another, for example a sender domain into a client folder name.

1. Set the condition to matches regex and enter a pattern that captures the lookup value, for example @(.+)$ on From Address.
2. In Action, choose and map with.
3. In Datasets, choose the dataset.
4. Choose how the key is compared: when the key is equal to or when the key contains, and enter what to look up, for example {Regex group 1}.
5. In the second Action, choose then convert to and insert the dataset value.
6. Save and test.

Dataset keys are compared without regard to case, and spaces at either end of a key are ignored.

Examples

Project number from the subject or body

• When Fields: Subject Normalized, Message Body
• Condition: matches regex \d{6}
• then convert to: {Regex group 0}
• Use in a path: Projects/{Project Number}/Correspondence

Client name from the sender's domain (dataset)

• When Fields: From Address, domain part
• Condition: is equal to the key of the dataset, dataset Client domains (rows such as partner.example → Partner Inc)
• Returns: Partner Inc
• Default Value: Unsorted

Yes/no flag for a policy

• When Fields: Subject
• Condition: contains invoice
• then convert to: true
• Use in a Filter Policy so a rule runs only for invoices. See Filter Policies.

Combine two fields

• Block 1: When Fields Attachment Extension is equal to pdf and Subject contains contract, then convert to Contracts
• Add OR condition, block 2: Subject contains quote, then convert to Quotes
• Default Value: Other

Build on a default variable

• When Variables: Microsoft Confidential Sensitivity Label, then convert to Confidential

AI Question variables

If your organization has connected an OpenAI account, the first select also offers an AI option that asks a yes/no question about each email. See AI Question Conditions.

Test a variable

1. Open the variable and click Test variable. The heading changes to Test variable.
2. In Complete the example, fill in each field the variable reads, or click Upload an email and choose a .eml or .msg file up to 25 MB.
3. Click Test. The result shows whether the variable matched and the value it returns.
4. Click End testing to go back to the form.

Test with emails that should match and with emails that shouldn't.

Copy, edit and delete

• Copy creates a new variable from an existing one, including a default variable. Use it to change a built-in pattern.
• Edit: rules and policies that use the variable use the changed version.
• Delete: if the variable is used by a rule, a policy, a template definition or another variable, the dashboard lists them with links. Remove it from those first.

Verify

1. Test the variable with a sample email.
2. Use it in a test rule's storage file path.
3. Send a test email and check the folder name in storage, or the message in Email Flow Logs.

Troubleshooting

Related pages

• Variables Reference
• Regular Expressions
• Datasets
• Storage File Paths
• Filter Policies