---
alias: master-data-external-files-tutorial
description: Master data files can reference external files with the mdfile scheme, so values that exceed the Excel cell limit, such as Automation Controller workflows, survive the export and import round trip.
---

# Master Data External File Links

## Overview

A master data file describes each entity as a set of rows and columns, whether the
file is an Excel workbook or its JSON equivalent. This representation has a hard
constraint: a single Excel cell holds at most 32,767 characters. Some values do not
fit in a cell. The most common case is the **Workflow** value of an **Automation
Controller** or of a shared **Automation Workflow**, which is a complete workflow
definition in JSON and easily grows beyond that limit.

**External file links**, available since version 12.0.0, solve this. Instead of
holding the full value, a master data entry can hold a reference to a separate file
that travels next to the master data file:

```text
mdfile://<relative path>
```

During import, the reference is replaced by the content of the file, so the loaded
entity is identical to one whose value was written inline. During export, values that
do not fit in a cell are automatically written as separate files and referenced with
`mdfile://`, so large entities now survive a full export and import round trip.

External file links work the same way in `.xlsx` and in `.json` master data files.

## The mdfile reference

An external file link is a value that starts with the `mdfile://` prefix, followed by
a path relative to the location of the master data file. For example, an
`AutomationControllerWorkflow` entry in a JSON master data file:

```json
{
    "AutomationControllerWorkflow": {
        "1": {
            "AutomationController": "MyController",
            "Name": "Setup",
            "DisplayName": "Setup",
            "Workflow": "mdfile://./Setup.json",
            "Order": "1"
        }
    }
}
```

At import time:

- The referenced file must exist next to the master data file, at the relative path
  written in the value. When importing a master data package, the reference is
  resolved inside the package content.
- The value is replaced by the full content of the referenced file before the entity
  is loaded.
- If the referenced file cannot be found, the import fails with an error identifying
  the missing path.

Always use forward slashes in the relative path.

## Export behavior

The Master Data Export applies the mechanism automatically:

- Any value longer than the Excel cell limit is extracted to its own `.json` file,
  and the cell keeps only the `mdfile://./<file name>` reference.
- When an export produces external files, the download is a `.zip` archive that
  contains the master data file (`masterdata.xlsx` or `masterdata.json`) together
  with the referenced files. Without external files, the download is the plain
  master data file.
- When exporting an **Automation Controller**, each extracted workflow file is named
  after the workflow display name (or name), for example `Setup.json`. If any
  workflow of the controller exceeds the cell limit, all workflows of that controller
  are exported as external files, keeping the export consistent.

The exported `.zip` can be imported back as a master data package without any manual
editing: the references resolve automatically against the files in the archive.

## Use in customization projects

Master data files in a `Data` package can use external file links the same way. Keep
the referenced workflow files inside the content that the package delivers, next to
the master data file that references them.

The `cmf build` command understands the links: an `AutomationControllerWorkflow`
entry whose `Workflow` value starts with `mdfile:` is recognized as a file reference,
exactly as if the deprecated `IsFile` column was set. When such a workflow is called
as a subworkflow by another workflow, the build verifies that the referenced file is
part of the package content and fails when the file is missing. This catches broken
references before the package is ever installed.

### Relation to the IsFile column

Before version 12.0.0, workflows of an Automation Controller or a shared Automation
Workflow could already be kept in separate files through the `IsFile` column: setting
`IsFile` to `Yes` marks the `Workflow` value as a file name, resolved against the
automation workflow files base path of the package. This mechanism is still
supported, but it is deprecated in favor of the `mdfile://` prefix, which is
self-describing, is not limited to workflow columns, and is produced automatically by
the Master Data Export.

## Related

- [[user-guide-master-data-export]]
- [[master-data-packages-admin]]