Working with MDL

Vault Toolbox provides syntax highlighting for .mdl files and tools to extract, deploy, and drop MDL directly from Visual Studio Code. This guide outlines how to use each of these tools, and how to download a Vault Configuration Report.

MDL Syntax Highlighting

Section link for MDL Syntax Highlighting

Vault Toolbox recognizes .mdl files in your project repository, providing syntax highlighting for MDL keywords (such as CREATE, RECREATE, ALTER, RENAME, and DROP), component types, attribute names, strings, and comments. Visual Studio Code applies this highlighting automatically to any .mdl file.

Downloading Vault Configuration Reports

Section link for Downloading Vault Configuration Reports

You can download a Vault Configuration Report using Vault Toolbox instead of doing so through the Vault UI. Vault Configuration Reports are Microsoft Excel reports that contain configuration information and reference data. This is especially useful for evaluating your Vault's configuration prior to modifying components. Learn more about generating Vault Configuration Reports.

To download a Vault Configuration Report:

1. Select the Vault Toolbox icon in the lefthand panel.
2. Select the Actions () tab.
3. Expand Components () and select Download Vault Configuration Report ().
4. Optional: Configure the report parameters described in Configuration Report Options below.
5. Optional: Click () Save as defaults to save your current parameters as the form's starting point for future reports, or () Reset to defaults to discard back to Vault's own defaults.
   
6. Optional: Click Change Location to update the folder the report downloads to. By default, the report downloads to vault-toolbox/config/<vaultId>.
7. Click Download Report.

Note

You must connect an environment before downloading a report. If no environment is connected, this action is disabled and Vault Toolbox prompts you to connect one first. See Managing Environments to learn how to connect an environment.

Once the download completes, Vault Toolbox opens the destination folder in the Explorer panel. Vault also sends an email notification with a link to download the report .zip file.

Configuration Report Options

Section link for Configuration Report Options

The Download Vault Configuration Report form supports the following optional parameters:

• Include Vault Settings: If selected, the report includes Vault settings. Enabled by default.
• Include inactive components: When selected, the report includes inactive components and subcomponents.
• Include document & binder templates: When selected, the report includes document and binder templates. Enabled by default.
• Suppress empty results: When selected, the report excludes tabs with only header rows.
• Components modified since: When selected, the report only includes components modified since the selected date. This operation is not available for subcomponents. Leaving this field blank includes all dates.
• Component types: A list of component types to include (for example, Doclifecycle, Doctype, Workflow). Leaving this field blank includes all component types and adds an Excel object data report to the .zip output.
• Output format: The output format for the report: Excel Macro-Enabled (XLSM) or Excel (XLSX).

Extracting MDL from Vault

Section link for Extracting MDL from Vault

Vault Toolbox can extract component MDL from Vault, allowing you to review the configuration for certain components prior to writing custom MDL.

To extract MDL from Vault:

1. Select the Vault Toolbox icon in the lefthand panel.
2. Select the Actions () tab.
3. Expand Components () and select Extract MDL from Vault ().
4. In the confirmation dialog, click Extract.

Caution

Extracting MDL deletes any local MDL file that no longer exists in Vault, so the folder always mirrors Vault exactly. The confirmation dialog warns you before this happens if local files already exist. Click Change Location in the dialog instead of Extract to choose a different folder first.

Once the operation completes, you can access all component MDL in your Vault from the vault-toolbox/mdl/<vaultId> folder in your project repository, organized into one subfolder per component type.

Deploying MDL to Vault

Section link for Deploying MDL to Vault

Vault Toolbox utilizes the RECREATE MDL command to create or alter selected component types in Vault, using the file's existing contents exactly as written. To deploy MDL to Vault, right-click a .mdl file in the editor or the Explorer panel and select Vault Toolbox > Deploy to Vault.

Vault Toolbox reports whether the deploy succeeded or failed in a notification, including a View API Call button that opens the API History entry for the deploy.

Caution

You cannot deploy MDL directly to a production Vault. We recommend using VPKs to deploy to production. This action targets sandbox environments only.

Dropping MDL from Vault

Section link for Dropping MDL from Vault

Vault Toolbox utilizes the DROP MDL command to delete a component from Vault. To drop MDL from Vault, right-click a .mdl file in the editor or the Explorer panel and select Vault Toolbox > Drop from Vault.

You don't need to write the DROP statement yourself since Vault Toolbox derives the DROP statement automatically from the component type and name in the file's leading CREATE/RECREATE header. A confirmation dialog shows the exact statement and target Vault before anything is sent.

Caution

Dropping a component permanently deletes it from Vault. You cannot drop MDL directly from a production Vault. This action targets sandbox environments only.