Applies to: SureFile Enterprise DMS Administrator

Rules define how to match emails and what to do with them when a match is found. Each rule can target incoming emails, outgoing emails, or both, and store matching emails in a specified location. If you want to stop a rule from being evaluated but don't want to delete it, you can disable the rule.

1. Refresh button
2. Create button
3. Export button
4. Import button
5. Edit button
6. Copy button
7. Move up button
8. Move down button
9. Rules list
10. Selected rule

SureFile evaluates rules in the order displayed in the list. You can reorder the rules in case the order in which they’re processed is important for you. Each rule uses a pattern to match emails which can be simple or complex. A simple pattern specifies a set of words to match, targeting all, any, or none of them, while a complex pattern is defined using a regular expression (regex).

When evaluating rules, emails matching a rule’s pattern are stored in the associated SharePoint location, which may include variable parts derived from text matched in the email’s data or metadata. For example, say you store emails for each customer in a separate folder, and when you send an email you include the customer’s name in the subject. SureFile can be configured to recognise this, automatically extracting the customer’s name from the subject, and using this as part of the SharePoint location where the email is stored.

If you’re already using the Managed Filing add-on for DMS, you can migrate your existing XML-based rules to the JSON format required by SureFile and then import them via the administration portal. Once you have rules in SureFile, whether imported or created from scratch, you can export them in SureFile's JSON file format, say, to store them as part of a business continuity plan. Exporting and importing rules is also a convenient way to duplicate rules with minor changes. Simply export the rules, copy the ones you want to tweak, then import them back into SureFile.

Create a rule

1. Complete
2. Incomplete/Error
3. To do

Creating a rule is a multi-step process, defining how to match emails and how to construct the save location path from static text and dynamic data. A progress indicator on the left of the New SureFile rule dialog helps you understand where you are in the process and lets you jump to a specific step where appropriate.

To create a SureFile rule, follow these steps.

1. Go to the Rules page and click Create.

   The New SureFile rule page is displayed.

   At any time, you can click Cancel to discard this rule.

2. Define the rule's Name and Scope.

   Give the rule a unique and descriptive name and select which emails it targets (incoming, outgoing, or both).

   For help with this step, see Name and Scope.

   Click Next to go to Named Groups.

3. Optional: Define Named Groups.

   Named groups are patterns used to match values in various parts of an email. These values are used in later steps to match emails to this rule and determine the save location.

   For help with this step, see Named Groups.

   Click Next to go to Conditions, or click Back to go back to Name and Scope.

4. Define Conditions.

   Conditions are the criteria that match emails to this rule. Each condition specifies a part of the email to check and what to check for (either a regular expression or specific text).

   For help with this step, see Conditions.

   Click Next to go to Unique Identifier, or click Back to go back to Named Groups.

5. Optional: Define a Unique Identifier.

   The unique identifier is the value stored in a nominated property of each SharePoint location and is used to determine the save location. Defining a unique identifier can help to improve SureFile performance.

   For help with this step, see Unique Identifier.

   Click Next to go to Save Location, or click Back to go back to Conditions.

6. Define the rule's Save Location.

   This is the SharePoint location where emails matching this rule's conditions will be saved. The Save Location is constructed from static and dynamic parts, possibly including values from named groups and the unique identifier.

   For help with this step, see Save Location.

   Click Next to go to Review, or click Back to go back to Unique Identifier.

7. Review your rule's definition.

   If you need to adjust any part of the rule, click the corresponding item in the progress indicator and make changes as required, then return here to review again.

8. Click Create.

   The New SureFile rule page closes, returning to the Rules page.

Steps 2-6 are described in detail below.

Name and Scope

Every rule needs a unique and easily identifiable name and a scope that identifies which emails it targets (incoming, outgoing, or both).

To define a rule's name and scope, follow these steps.

1. In the Rule name field, enter a name for the rule.

2. In the Scope field, select an item from the list corresponding to the emails you want this rule to target.

   Choose from Incoming, Outgoing, or Both.

3. Click Next, moving to the next rule step, Named Groups.

Named Groups

Named groups define patterns that SureFile can use to match and extract values from the email subject. Once defined, you can use named groups in the Conditions, Unique Identifier, or Save Location as a placeholder for a dynamic value obtained from each matched email. Named groups can even be used as building blocks to simplify the definition of more complex named groups.

Add a named group for each value you want SureFile to extract from the email subject.

Add a named group

To create a named group, follow these steps.

1. On the Named Groups page, click Add named group.

   The page changes, adding an empty named group item.

   

   1. Named Group item
   2. Group name field
   3. Group regular expression field
   4. Clear button
   5. Regex Builder button
   6. Delete Named Group button
   7. Add named group button

2. In the Group name field, enter a name for the named group.

   This name will be used in subsequent steps as a placeholder for this named group, later replaced by the extracted value, so choose a brief but meaningful name that accurately reflects the value.

3. Enter the regular expression for the named group.

   There are two ways to do this. Select the one you want to use below and follow the corresponding steps.

   Type the regex

   In the Group regular expression field, type the regular expression.

   You can nest named groups to build up more complex named groups using simpler ones.

   There are two ways to insert another named group into a named group's regular expression:

   • Type its name enclosed in angled brackets (<...>).
   • Click the named group badge and select a named group from a list.

   Use the regex builder

   The regex builder provides a guided experience to help you create regular expressions.

   To learn about the regex builder, see Regular expressions in SureFile Enterprise.

   1. Click Regex Builder.

      The Regex Segments flyout appears showing a single empty regex segment.

      

      1. Regex segment
      2. Add (regex segment) button
      3. Resulting Regex field
      4. Testing field
      5. Ok button
      6. Cancel button

      A regular expression is composed of regex segments that each match a specific part of the target text.

   2. Add as many regex segments as you need.

      As you add segments, the Resulting Regex field updates to show you what your regular expression looks like.

   3. Enter text in the Testing field to check if your regex works the way you want it to.

      This can help to guide you as you add segments, as you can see immediately whether the segments you've added match the way you expect them to.

      Test your regex with text that should match and text that shouldn't match. For example, if you have a segment that can be optional, it's a good idea to test that your regex works with and without matching text. Similarly, if you have a case-sensitive segment, make sure it only matches the correct case.

   4. Once you've finished constructing your regex, click Ok to save it.

4. The named group item is now displayed with a coloured background. This colour is used elsewhere to help you identify this particular named group and to distinguish it from others.

   

5. Repeat steps 1-3, creating all the named groups you need.
6. Click Next, moving to the next rule step, Conditions.

   Alternativley, you can click Back to go back to the Name and Scope step.

Edit a named group

To edit a named group, modify the relevant fields.

• Group name: Type in the Group name field.
• Group regular expression: There are two ways to edit a regular expression:
  • If you're familiar with regex and know which part you need to change, type in the Group regular expression field.
  • If you're less confident with regex, click Regex Builder to use the regex builder.

Delete a named group

To delete a named group, click Delete Named Group for the named group you want to delete.

The named group is deleted without confirmation.

Named groups in input fields

Once you've added some named groups, you can use them in subsequent steps when defining conditions, a unique identifier, or the save location. A named group appears in an input field as a rounded badge containing the named group's name and using the colour assigned to the name group as the badge's background colour.

Insert a named group

There are two ways to insert a named group:

• Type: In a field that can accept a named group, type the name of a named group enclosed in angle brackets (<...>). When you type the closing >, the named group text changes to a rounded badge.
• Select: When a field can accept a named group, a small round badge appears next to the input cursor. Click the badge to display a list of named groups. Select an item from the list to insert that named group into the field at the input cursor's position.

Remove a named group

To remove a named group from an input field, click the named group in the input field, then click the named group's Dismiss badge.

The named group is removed without confirmation.

Conditions

Conditions are the criteria that SureFile uses to match emails to rules. A condition specifies which part of the email to check (such as the subject, body, or recipients) and what to check for (either a regular expression or specific words). A named group matched in an email's subject becomes a filing tag.

Define one or more conditions to be evaluated against each target email. You can test whether your conditions work as expected by defining some test email data.

Add a condition

To add a condition, follow these steps.

1. On the Rule conditions page, click Add condition.

   The page changes, adding an empty condition item that matches the email subject against a regular expression by default.

   

   1. Email part list
   2. Match type list
   3. Expression field
   4. Delete (condition) button
   5. Regex builder button
   6. Case Sensitive switch

2. From the Email part list, select which part of the email you want to match against.

   Choose from Subject, Body, From, ToRecipients, CcRecipients, BccRecipients, or InternetMessageHeaders.

3. From the Match type list, select how you want to match against the selected email part.

   Choose from the following options.

   • All: The email part contains all of the specified keywords.
   • Any: The email part contains at least one of the specified keywords.
   • None: The email part doesn't contain any of the specified keywords.
   • Regex: The email part matches the specified regular expression.

   If you choose All, Any, or None, the condition item changes, displaying different fields.

4. Fill in the condition details.

   The required details differ depending on the Match type. Select the one you chose below and follow the corresponding steps.

   All, Any, None

   

   1. Email part list
   2. Match type list
   3. Keywords field
   4. Add (keyword) button
   5. Delete (condition) button
   6. Case Sensitive switch
   7. Word match list

   1. In the Keywords field, enter a word to match.
   2. If you want to match more words, click Add (keyword).

      A new row appears in the Keyword field where you can enter another word to match.

      Repeat this step until you have added all the words you want to match against the selected email part.

   3. From the Word match list, select one of the following options.
      • Partial word match: Word boundaries are ignored. Any instance of specified keywords in the selected email part's content are counted as a match. For example, the keyword part matches both email part and wild party.
      • Full word match: To be counted as a match, the relevant keywords must match content in the selected email part exactly, starting and ending at either the input boundary or a word boundary. For example, the keyword part matches email part but not wild party.
   4. If you want keyword matches for this rule to be case-sensitive, turn on the Case Sensitive switch.
   5. If you want to add more conditions (for example, to match against different email parts), click Add condition and repeat the steps above to fill in the condition.

   Regex

   • If you're familiar with regular expressions and know what you need to enter, type the required regex in the Expression field.

     The regex can include named groups. To learn about inserting and removing named groups in input fields, see Named groups in input fields.

   • If you're less confident with regex, use the regex builder which provides a guided experience for creating regular expressions. To learn about the regex builder, see Building regular expressions in SureFile Enterprise.

     1. Click Regex Builder.

        The Regex Segments flyout appears showing a single empty regex segment.

        

        1. Regex segment
        2. Add (regex segment) button
        3. Resulting Regex field
        4. Testing field
        5. Ok button
        6. Cancel button

        A regular expression is composed of regex segments that each match a specific part of the target text.

     2. Add as many regex segments as you need.

        As you add segments, the Resulting Regex field updates to show you what your regular expression looks like.

     3. Enter text in the Testing field to check if your regex works the way you want it to.

        This can help to guide you as you add segments, as you can see immediately whether the segments you've added match the way you expect them to.

        Test your regex with text that should match and text that shouldn't match. For example, if you have a segment that can be optional, it's a good idea to test that your regex works with and without matching text. Similarly, if you have a case-sensitive segment, make sure it only matches the correct case.

     4. Once you've finished constructing your regex, click Ok to save it.

5. Test the condition.

   You can define test data that simulates an email you might expect to be matched by the condition. When test email data is defined, a status indicator on each condition shows whether or not the condition matches the test email. To learn about testing conditions, see Test rule conditions.

Edit a condition

To edit a condition, modify the relevant fields.

• Email part: Select an item from the Email part list.
• Match type: Select an item from the Match type list.
• If Match type is All/Any/None:
  • Keywords:
    • To add a keyword, click Add (keyword) and type in the new keyword field.
    • To modify a keyword, click in the relevant keyword field and type the required changes.
    • To delete a keyword, click Delete (keyword) for the relevant keyword field.
  • Word match: Select a value from the Word match list.

• If Match type is Regex:

  There are two ways to edit Expression:

  • If you're familiar with regex and know which part you need to change, type in the Expression field.

  • If you're less confident with regex, click Regex Builder to use the regex builder.

• Case Sensitive: Turn the Case Sensitive switch on or off as required.

Delete a condition

To delete a condition, click Delete (condition) for the condition you want to delete.

The condition is deleted without confirmation.

Example | Condition

This condition matches the email subject against a regular expression that includes named groups for the client number and invoice number. The regex is tested against a sample subject line, showing a match and the values extracted for the two named groups.

Closing the Regex segments flyout and returning to the Conditions page, the regex is now displayed with the two named groups shown using their allocated colours. Notice the small badge floating near the regex field's input cursor. You can click the badge to open a list of all the named groups. Select a named group from the list to insert it in the regex at the input cursor's position.

Test rule conditions

You can test your rule's conditions by defining test data which simulates an email that you might expect to match the rule's conditions.

Create test email data

To create test email data, follow these steps.

1. Click Create test email data.

   The Test Email flyout opens.

   

   1. Create test email data button
   2. Test email data fields
   3. Create button
   4. Cancel button
2. Enter values in the various fields to simulate the email you expect the conditions to match.

3. Click Create.

   The Test Email flyout closes, returning you to the Conditions page.

4. On the Conditions page, each condition now has a status indicator which shows whether or not the condition matches the test email data.

Once you have created test email data, options to edit and delete the test data appear.

1. Edit test data button
2. Delete test data button
3. Matches status indicator
4. Does not match status indicator

Edit test email data

To edit test email data, follow these steps.

1. Click Edit test data.

   The Test Email flyout opens populated with the existing test data.

2. Edit values in the various fields as required.

3. Click OK.

   The Test Email flyout closes, returning you to the Conditions page.

4. On the Conditions page, the status indicator on each condition shows whether or not the condition matches the updated test email data.

Delete test email data

To delete test email data, click Delete test data.

The test email data is deleted without confirmation, and the status indicators are no longer displayed.

Unique Identifier

In a structured SharePoint file store, you might use a key identifier to organise your documents and emails. For example, you may store all emails for a specific customer under a folder named using the customer number, something like this:

If your SharePoint structure is organised in this way, SureFile can recognize a unique identifier in each email's subject and automatically save to an associated location.

1. Object Type list
2. Property Name field
3. Property Value field
4. Clear (Property Value) button
5. Select Named Group badge
6. Remove button

Define a unique identifier

To define a unique identifier, follow these steps.

1. From the Object Type list, select a value.

   This is a SharePoint location type. Available options are Folder, Library, and Site.

2. In the Property Name field, enter the name of the SharePoint property that contains the unique value you want to use.

   In most cases, enter Title unless you know you need to enter a different value.

3. In the Property Value field, enter the value to search for.

   In most cases, this is a named group that you defined earlier. The actual value to search for will be extracted from each email's subject by matching the named group's regex.

   To learn about ways to insert a named group, see Insert a named group.

4. Click Next.

When determining the save location, SureFile will search for a property with the name defined in Property Name and the value defined in Property Value in locations of the type selected in Object Type.

Edit the unique identifier

To edit the unique identifier, simply type the required changes in the Object Type, Property Name, or Property Value fields.

Remove the unique identifier

To remove the unique identifier, click Remove.

The unique identifier is removed without confirmation.

Save Location

Once an email matches a rule's conditions, SureFile needs to know where to save it. Depending on the kind of emails matched by a rule and how you've structured your SharePoint file store, you may want emails saved to a dynamically determined location using information from the email or SharePoint, or you may just want them saved to a static location. SureFile handles both of these scenarios.

1. Save URL field
2. Allow Inserting Tags switch
3. Create test email data button

The save location may include named groups corresponding to information such as client, project, or matter identifiers which SureFile can insert into the subject of matched emails as filing tags. A tag consists of the named group's value enclosed in square brackets ([ ... ]). Subsequently, SureFile rules can match these tags in other emails (reply or forwarded emails, for example) when determining the SharePoint save location.

The save location can also include wild card path segments using the format *n where n is an integer. This instructs SureFile to ignore n path segments when searching to determine the save location. The wild card path format * is also supported. This ignores any number of save location path segments. So, for example, .../clients/*/email matches all of these:

On the other hand, .../clients/*2/email matches the second path only.

To define the save location, follow these steps.

1. In the Save URL field, enter a URL on your SharePoint tenant representing the location where you want emails matching this rule to be saved.

   Save URL can be either a static location or a dynamic location that includes named groups and/or wild card path segments. To learn about inserting and removing named groups in input fields, see Named groups in input fields.

   • A Save URL that includes named groups substitutes the named group values from the email subject when determining the actual save location.

   • If you enter a URL that is not on the Microsoft 365 tenant where you installed SureFile, an error message is displayed. However, this error does not prevent you from saving your rule.

     

2. If you want to allow SureFile to insert tags in the subject of saved emails, turn on the Allow Inserting Tags switch.

   If Allow Inserting Tags is on, SureFile inserts a tag for each named group in Save URL.

3. If the Search for matches button is disabled (because Save URL contains named groups), you need to create test email data; otherwise, you can skip to the next step.

   To learn about creating test email data, see Create test email data.

   Once test email data has been created, options to edit and delete the test data appear. To learn about editing and deleting test email data, see Edit test email data and Delete test email data.

   

   • If the test data matches the rule's condition: A summary of the location search criteria is displayed showing how SureFile will search for a matching location including sample values for named groups and ellipsis for wild card path segments, and the Search for matches button is enabled.
   • If the test data doesn't match the rule's condition: A message is displayed advising you to make it match if you want to enable the Search for matches button so that you can test the save location search in your SharePoint tenant.

4. Test the save location works as expected.

   Click Search for matches to search your SharePoint tenant for locations that match the Save URL. Matching locations are displayed showing the location name, its path, and an icon indicating either an exact match or an inexact match.

   with shown in the check that SureFile can find your rule's save location.

Review

Once you've defined your rule, a summary of the selected criteria is presented for your review.

1. Rule name
2. Scope
3. Conditions
4. Unique Identifier
5. Save URL
6. Allow Inserting Tags
7. Enabled switch
8. Back button
9. Create button
10. Cancel button

If you need to change anything, select the relevant section from the progress bar on the left to navigate to that section and make the necessary changes, then return to the Review page.

You can control whether SureFile processes this rule with the Enabled switch. Turn Enabled on and SureFile will attempt to match emails against this rule. Turn Enabled off and SureFile ignores this rule.

Once you're satisfied with the rule's criteria, click Create to save the rule. The New SureFile rule closes, returning you to the Rules page.

Manage rules

Edit a rule

To edit a rule, follow these steps.

1. In the Rules list, select the rule you want to edit.

2. Click Edit.

   The Edit rule page is displayed showing the rule's name and with the Review section selected.

3. Make the necessary changes.

4. Click Save Changes.

   The Edit rule page closes, returning you to the Rules page.

   If you decide you don't want to keep your changes, click Cancel instead. The Edit rule page closes, and any changes you made are discarded.

Copy a rule

To copy a rule, follow these steps.

1. In the Rules list, select the rule you want to copy.

2. Click Copy.

   SureFile creates a copy of the selected rule and opens it in the Edit rule page with the Review section selected. By default, the copied rule's name is the same as the rule you copied prefixed with (Copy) .

3. Make any required changes to the copied rule.

4. Click Save Changes.

   The Edit rule page closes, returning you to the Rules page with the new rule selected.

   If you decide you don't want to keep your changes, click Cancel instead. The Edit rule page closes, and any changes are discarded, but the copied rule is not deleted.

Delete a rule

1. Rule name
2. Rule GUID identifier
3. Remove button

To delete a rule, follow these steps.

1. In the Rules list, select the rule you want to delete.

2. Click Edit.

   The Edit rule page is displayed showing the rule's name and beneath it a GUID identifier with a Remove button beside it.

3. Click Remove.

   The Remove rule? confirmation dialog is displayed.

4. On the Remove rule? dialog, click Yes.

   The Edit rule page closes, returning you to the Rules page with no rule selected.

   If you decide you don't want to delete the rule after all, click No instead. The Edit rule page closes, returning you to the Rules page with the rule still selected.

Reorder rules

The order of SureFile rules allows you to prioritise particular rules over others. This is especially important when the Match single rule option is enabled.

To reorder rules, follow these steps.

1. Select the rule that you want to move.

2. Click Move up or Move down to adjust the rule's position.

   The Rules list refreshes, showing the rule in its new position.

3. Repeat the above steps for each rule you want to reorder.

Export and Import

The administration portal supports export and import of SureFile rules using JSON-format files. These options are useful to keep rules aligned across multiple SureFile instances, to back up your rules as part of a business continuity plan, or to duplicate rules with minor changes (export the rules as a JSON format file, copy the rules you want to tweak, then import the rules).

If you’re already using Surefile Desktop (previously known as the Managed Filing add-on for DMS), you can migrate your existing rules. To learn more, see Configure settings in SureFile Enterprise > Convert Legacy XML Rules to JSON.

Export rules

To export rules in JSON format, follow these steps.

1. On the Rules page, click Export.

   A Save As dialog is displayed with a default file name for the exported file generated using the current date and time in the format YYYYMMDDhhmmssSSS; for example rules-20261023044600548.json.

2. Browse to the location where you want to save the exported rules file and adjust the export file name as required.

3. Click Save.

   The exported rules file is saved to the selected location.

[
  {
    "Id": "7ac7f333-60b3-41f5-8600-ff8f847b5677",
    "SaveUrl": "https://mytenant.sharepoint.com/sites/clients/<clientnumber>",
    "ExpressionGroup": {
      "Expressions": [
        {
          "KeywordMatchType": "Regex",
          "MessagePropertyName": "Subject",
          "Keywords": "Correspondence \\[Invoice # (?<invoicenumber>I\\d{8})-(?<clientnumber>C\\d{4,})\\]",
          "CaseSensitive": false,
          "MatchEntireWord": false
        }
      ],
      "Operator": "And"
    },
    "Name": "Invoice correspondence",
    "RuleEnabled": true,
    "Scope": "Both",
    "AllowInsertingTag": true,
    "SavePathProperty": {
      "ObjectType": "Folder",
      "InternalName": "Title",
      "Value": "<invoicenumber>"
    }
  },
  {
    "Id": "95893144-14d7-4a98-9f95-5fcd7ebd3ee6",
    "SaveUrl": "https://mytenant.sharepoint.com/sites/docsandemails",
    "ExpressionGroup": {
      "Expressions": [
        {
          "KeywordMatchType": "Any",
          "MessagePropertyName": "Subject",
          "Keywords": "aardvark unicorn",
          "CaseSensitive": false,
          "MatchEntireWord": false
        }
      ],
      "Operator": "And"
    },
    "Name": "Demo | Both | Any from (aardvark, unicorn)",
    "RuleEnabled": true,
    "Scope": "Both",
    "AllowInsertingTag": true,
    "SavePathProperty": null
  }
]

Import rules

To import a JSON-format rules file, follow these steps.

1. On the Rules page, click Import.

   An Open dialog is displayed with the JSON File (*.json) file type selected.

2. Browse to the location of your JSON-format rules import file and select it.

3. 

   Click Open.

   The rules in the selected file are imported into your SureFile solution, replacing all existing files.

   If there's a problem with the file you selected to import, an error message is displayed in the bottom-right corner indicating the nature of the problem. For a list of possible error messages, see SureFile rules import error messages.