Datasets

A dataset is a two-column list of keys and values, such as client domains and client names, or matter numbers and folder IDs. Custom variables look values up in a dataset to decide folder names, and policies built on those variables can, for example, exclude every sender on a list. This page explains how to create a dataset, fill it by hand or from a CSV file, keep it in sync with a cloud storage folder, and monitor that sync.

Before you begin

• Plan the key and the value. The key is what a variable will look up (for example partner.example); the value is what it returns (for example Partner Inc).
• To fill a dataset from storage, connect an individual Box, Egnyte, OneDrive or Google Drive account in Settings › Integrations. Dropbox and organization-level accounts can't be used for sync.

How datasets are used

• In a variable, with the conditions is equal to the key of the dataset or contains the key of the dataset, or with the action and map with. The variable returns the matching row's value. See Custom Variables.
• Lookups ignore case and outer spaces. Partner.Example finds the key partner.example. If two keys differ only by case, the first one wins.

The Datasets page

Open Auto Filling › Datasets. Each dataset shows its name, when it was last updated, Edit and Delete. Click the arrow to expand it and page through its rows. Datasets that sync from storage also show their sync status.

Create a dataset by hand

1. In Auto Filling › Datasets, click Create.
2. Enter a Dataset name.
3. On the Dataset Items tab, click + Add item and enter a Key and a Value. Repeat for each row.
4. Click Save Dataset.

A key can't be blank or start with a space, and a value can't be blank.

Import rows from a CSV file

1. Prepare a .csv file with one row per line: the key, a comma, then the value. Don't include a header row unless you want it as a row. For example:

   partner.example,Partner Inc
   supplier.example,Supplier Ltd

2. On the Dataset Items tab, next to Import:, click one of:

   • Update existing: adds new keys and updates the value of keys that already exist. Other rows are kept.
   • Replace All: deletes all current rows and keeps only the rows in the file.

3. Choose the file. The dashboard shows how many rows were added, updated or skipped.

4. Click Save Dataset.

File rules:

• Maximum file size: 2 MB.
• Exactly two columns per row. Rows with more than two columns aren't allowed.
• Lines with an empty key or only one value are ignored.

Warning: Replace All removes every row that isn't in the file, including rows you added by hand.

Fill a dataset from cloud storage (Dataset Sync)

Dataset Sync reads a storage folder and adds one row per file or subfolder, using its ID and name. Use it to map names to folder IDs, for example so a rule can file email into an existing client folder by the client's name.

1. In Auto Filling › Datasets, click Create and enter a Dataset name.

2. Open the Fill with cloud storage tab ("Sync your cloud storage information into this dataset").

3. In Cloud storage account, choose the account.

   

4. Complete the sync settings that appear:

   Setting	Options	Default
   Files or folders	Read the files or the folders in the folder	Files
   Folder path	Root, or pick a folder from storage	Root
   Use as key / Use as value	The ID or The name of each file or folder	Key = ID, value = name
   Action	Replace: each run replaces all rows. Merge: each run adds and updates rows and keeps the others.	Replace
   Repeat	No repeat, every 6 hours, every 12 hours, every 24 hours	No repeat

5. Click Save and sync. The first sync starts.

To look up a folder ID by name, set Use as key to the name and Use as value to the ID.

Important: With Replace, the first sync removes rows you entered by hand, and each later run removes rows added through the API. Use Merge if you also add rows another way.

To stop scheduled syncs, edit the dataset and use the option to stop repeating on its synchronization tab.

Sync status

The dataset list shows the state of each synced dataset:

When you edit a synced dataset, its synchronization tab is highlighted if the last run failed.

The run history lists each run with its start and end times, the account and folder, the reason for a failure, and Show details for the full error.

Failure notifications

When a scheduled sync fails, mxHERO:

• sends an email notification, and
• adds a dataset-sync-failure notification in Reports › Notifications. Expand it to see the dataset, the storage account and the cause, with Go to dataset and Go to accounts.

These notifications are in the Platform warnings category of Settings › Notifications. See Notification Settings and Notification Error Codes.

Update a dataset through the API

You can read a dataset, replace all its rows, or add, change and delete single rows with the mxHERO V3 API. The dataset must exist in the dashboard first. See Datasets API.

Limits

Delete a dataset

Click Delete on the dataset. If a variable uses it, the dashboard lists the variables with links. Remove the dataset from those variables first.

Verify

1. Expand the dataset in the list and check a few rows.
2. Open a variable that uses the dataset, click Test variable, and enter a value that should match a key. The test should return that row's value.
3. For a synced dataset, check that the status is Synced after the first run.

Troubleshooting

Related pages

• Custom Variables
• Regular Expressions
• Datasets API
• Notification Error Codes