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:

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:

{
    "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.