> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acelabusa.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Sync Material Hub Fields into Revit as Shared Parameters
> Enable Material Hub fields, load them into your Revit model as Shared Parameters, and schedule or tag their values.
This article walks through enabling Material Hub fields and loading them into your Revit model.
Your Material Hub data — product names, manufacturers, MasterFormat sections, project-specific fields and more — can now be written directly onto the elements and materials in your Revit model. Once a field is synced, it behaves like any other Revit parameter: it shows up in Properties, in schedules, and in tags.
## **How it works (the short version)**
Revit stores custom data on elements using **Shared Parameters**. A Shared Parameter is a custom field defined once in a `.txt` file on your computer or network, then loaded into a Revit project so its values can be filled in and scheduled.
When you enable a Material Hub field for sync, the plugin does three things for you:
1. **Registers the field** in your Shared Parameters `.txt` file, named `MH_[FieldName]` — for example, "Submittal Status" becomes `MH_Submittal_Status`.
2. **Loads it into your current Revit project** and makes it available on all element categories and all material categories.
3. **Writes the value** from Material Hub onto your linked elements and materials every time you sync.
You never have to create parameters, manage GUIDs, or map fields by hand. Steps 1 and 2 happen once per project — after that, syncing is all you do.
> **Note:** Because Revit treats elements and materials differently, each field is registered twice behind the scenes — once for elements and once for materials. You'll only ever see one field and one parameter name in the plugin.
***
## **Before you start**
* The Acelab Revit plugin is installed and you're signed in
* Your Revit project is linked to an Acelab project
* You're on a **PRO** plan or the MH Fields tab in you setting panel is read-only on other plans
* You know where your firm's Shared Parameters `.txt` file lives, and you can save to it
**If your Shared Parameters file is managed by your BIM team** and you don't have permission to write to it, you can still sync — you'll just need your BIM manager to add the parameters once. See [Troubleshooting](#troubleshooting) below.
***
## **Step 1 - Open the MH Fields tab**
1. Open the Acelab panel in Revit.
2. Click **Settings**.
3. Select the **MH Fields** tab.
The **Revit Fields** tab is unchanged — everything you configured there still works exactly the same way.
> **On a non-PRO plan?** You'll see a **PRO** badge next to the tab. You can look at everything, but toggles and Save are disabled.
***
## **Step 2 - Confirm your Shared Parameters file location**
At the top of the tab you'll see **Shared Custom Parameters File Location**.
* If Revit already has a Shared Parameters file set, the path appears here automatically.
* To point to a different file, click **Browse** and select a `.txt` file.
This is the file Acelab will add parameter definitions to. It's the same file Revit uses under **Manage → Shared Parameters**.
***
## **Step 3 - Choose which fields to sync**
Under **Choose fields to sync from Material Hub**, your fields are organized into four groups:
Click a group row to expand it, then:
* **Turn on a whole group** with the group toggle - every field inside turns on.
* **Turn on individual fields** with the toggle on each field row.
As you enable fields, each row shows the Revit parameter name it will use, plus a status:
| Status | Meaning |
| :-------------- | :------------------------------------------------------------------------- |
| **Not enabled** | Field won't sync |
| **New** | First time you've enabled this field — it will be registered when you save |
| **Active** | Already registered in a previous session |
> Toggles update instantly in the panel, but nothing is written to Revit until you click **Save**.
***
## **Step 4 - Save and load the parameters into your project**
Click **Save**.
**If you enabled any new fields,** the **Load New MH Parameters** dialog appears. It tells you exactly what's about to happen, in up to two lists:
* **New Fields will be added to your Shared Parameters file**: fields that don't exist in your `.txt` file yet
* **Already in file — will be loaded into this project**: fields that exist in the file but haven't been used in this project yet
Click **Append & Load** to write the parameters and load them into your project.
**This is a one-time step per project.** The next time you save or sync, already-loaded fields are skipped automatically.
***
## **Step 5 - Run a sync and find your Material Hub values in Revit**
Sync as you normally would. Material Hub field values are written after your standard sync finishes.
### **On elements:**
1. select an element and look in the Edit Type Properties, or
2. add the `MH_[FieldName]` parameter as a column in any schedule.
### **On materials:**
1. open the **Materials Browser**, select a material, and look for its custom parameters. Depending on your Revit version these appear either on the Identity tab or in a separate custom-parameters dialog opened from the bottom-left of the Materials Browser.
2. The most reliable place to confirm the values is a **Material Takeoff** schedule — add `MH_M[FieldName]` as a column.
> **Tip:** Parameter names always start with `MH_M`, but you can rename the column header in any schedule via the schedule's **Formatting** tab → **Heading**. That lets you present a clean label like "Submittal Status" without changing the underlying parameter.
***
## **Turning a field off**
Flip its toggle off and click **Save**. From then on, syncs stop writing to that field.
What *doesn't* happen when you disable a field:
* The parameter definition is **not** removed from your `.txt` file
* The parameter is **not** unbound from your Revit project
* Values already written to your model are **not** erased
If you re-enable the field later, it picks up the same parameter it used before and your schedules keep working.
***
## **Good to know**
* **Material Hub is the source of truth.** Every sync overwrites Revit with whatever Material Hub currently holds. If you edit a value directly in Revit, the next sync will replace it.
* **Clearing a value in Material Hub clears it in Revit.** The parameter is blanked rather than left with a stale value.
* **Elements without an Acelab link are left alone.** Their `MH_` parameters aren't touched or blanked.
* **Parameters are available on every category.** Binding isn't limited to Acelab-linked elements, so the parameters show up in your category lists whether or not a given element has data.
* **Settings are saved per project.** Enabling fields in one project doesn't change another.
***
## **Troubleshooting**
**"Invalid Path: Browse to select where your Shared Parameters file should be saved."** No valid file is set. Click **Browse** and select your `.txt` Shared Parameters file, then click Save again.
**"File In Use: Close this file in any other open programs, then try again."** The `.txt` file is open somewhere else — often a text editor. Close it everywhere and click Save again.
**The dialog says the file can't be written to** Your Shared Parameters file is read-only, which usually means your BIM team controls it. Two options:
1. Ask your BIM manager to add the `MH_` parameters to the firm's file. Once they're in the file, come back and save — Acelab will find them and load them without needing to write anything.
2. Point the plugin at a file you can write to via **Browse**, or change the file in Revit under **Manage → Shared Parameters**.
**A field shows "Skipped" after sync** Either the field is toggled off, or you clicked **Cancel** on the Load New MH Parameters dialog so the parameters were never loaded into this project. Open Settings → MH Fields, confirm the toggle is on, click **Save**, and complete **Append & Load**.
**A field shows "Failed" after sync** The most common cause is a data type mismatch — for example, text in a field Revit expects to be numeric. If the field looks correct and it still fails, contact Acelab support with the sync result screen.
**Parameters didn't appear in my project after saving** Check that your model isn't in a state that blocks parameter changes (for example, a workset or permission restriction), then save again. If the save reported that the file was updated but the project load failed, the parameter definitions are already in your `.txt` file — saving again will load them without duplicating anything.
***