close

Guides

Sections

Family Processor

Using Family Processor

Family Processor is a tool which allows you to define one or multiple changes to one or more Revit® family files. This software can be used to make the following kinds of changes to Revit family files:

This software also provides the following functions:

The ability to automate these tasks with accuracy and consistency can provide enormous time and cost savings, as well as reduce the likelihood of human errors inducing mistakes in the families.

Starting Family Processor

To launch Family Processor, you must have a family open in the Revit editor. This is necessary because a starting family is used as a baseline for default values that may apply to other families. This also makes it easy if you only want to automate changes to that single family. Once you have a family file open, click on the “CTC Software” tab in the ribbon and then click on the “Family Processor” button.

Family Processor Interface

Once the button is clicked, Family Processor will open:

Family Processor Interface

Tool Bar

Across the top of the Family Processor dialog are the following tool buttons:

The New Settings button clears out all of the current definitions of changes to one or more families that should be made. Essentially, it simply clears out the settings to apply to each family.

The Open Settings button lets you load previously-saved settings from a file you select.

The Save Settings button lets you save your current settings to a file you select.

The Options button brings up the following dialog that lets you control how Family Processor works. These options should be fairly self-explanatory:

Family Processor Interface

The Help button launches this user guide.

The Videos button opens a list of videos which can be viewed to learn more about using this tool.

The About button will bring up a dialog which provides information about this application.

Processing

As we’ll see shortly, the information in the bottom half of most tabs defines the actual actions to take on one or more families.

The top half of those tabs is used to select or specify what should go in the bottom half. For example, the “Only names containing” field above the list of choices allows you to quickly filter down the list by typing in a part of the name. Only those items that include what you type will remain on the list for selection.

IMPORTANT: Unless you make changes on the “Processing Order” tab, the order in which changes will be applied to the families matches the order that Family Processor presents the settings to you.

Family-Level Processing Tab

The first tab is the Family-Level Processing tab. This tab contains settings that apply to the entire family and not, for example, just to a parameter or a material.

Family Processor Interface

This tab contains settings that allow you to apply a value to the OmniClass property of the family. You can select to make no change, to set a specific value, or to get the value to apply from an existing Text parameter in the family being processed.

For example, the families to be processed may have been created with an older version of Revit which did not have the OmniClass property on families. If a Text parameter called OmniClass Value exists in each family and contains the value to be stored in the OmniClass property of families that now exists in Revit, you can specify that parameter name as the one from which to get the value:

Family Processor Interface

You can also have Family Processor delete the parameter once the value has been successfully applied.

Below this section are controls for changing the category of the family as well as the checkbox-based “Family Parameters” from the “Family Category and Parameters” dialog in Revit:

Family Processor Interface

The category of the family being processed can be changed by selecting something other than “No Change” from the list:

Family Processor Interface

The “3D” and “Annotation” options are simply filters which change which category choices are in the list, to simplify the list of choices.

IMPORTANT: Be careful when changing the category of a family! When the category of a family is changed, subcategories will be lost and some category-specific parameters may be lost as well. Use this feature at your own risk.

The “checkbox” values below the category list can be set to ‘No Change,’ ‘Set Checked,’ or ‘Set Unchecked.’

Below this section is the section for defining the Keynotes file this family will use:

Family Processor Interface

This works like the equivalent dialog that is natively in Revit. To not set a Keynotes file, simply leave the “Set the keynotes file” checkbox unchecked.

Below this section is a control for opening family files with Auditing turned on. This can be used to help clean up family files which may have some corruption-type issues in them, to which Revit 2015 and later are particularly sensitive.

Below this option is a setting for importing the units of measure to apply to the families being processed. For example:

Family Processor Interface

With this option enabled, all the settings for units of measure from the “Metric Family Template.rfa” family file will be applied to all the families being processed.

This option will NOT convert values to nominal values in the new units of measure. For example, if a value starts out as 33mm in a family but the units of measure for length in the family being used for units of measure are inches, the value in the family being updated will NOT change to a nice, round 1.25 inches but instead will be something like 1.29921 inches. So this process simply changes the working units of measure within the family in the same manner as if that’s all that were to be changed in Revit manually.

Below this option is a setting to change the casing of all text-based parameter values. For example:

Family Processor Interface

Text-based parameter values do not include a unit of measure, and include such parameter types as Text, Multi-line Text and URL. This setting allows changing the values to all uppercase, all lowercase, or to use title casing. Title casing uses capital letters as seen in the titles of most things, such as: My Awesome Parameter

A common use case for this option is to ensure all text values are all in uppercase letters, so schedules will appear in a uniform manner.

NOTE: URL parameters will not have their casing changed, because many web sites have case-sensitive addresses.

Below this is a setting to sort parameters within groups, as seen in the Family Types dialog when editing a family. This image shows the before and after results of turning on this setting:

Family Processor Interface

Lookup Tables Tab

The second tab in Family Processor is the Lookup Tables tab:

Family Processor Interface

This tab allows deleting lookup tables from the family being processed, or importing lookup tables from CSV files into the family being processed. This tab contains 2 subtabs:

Delete Lookup Tables Sub Tab

This tab allows you to define, by name, which lookup tables should be deleted from the families to be processed:

Family Processor Interface

As with the other tabs, information from the currently open family is used to provide starter choices in the top half of this tab, and the bottom half of this tab is where the changes to actually apply to the families are listed. As items are added to the bottom half, they are removed from the list in the top half.

In this example, the lookup table shown in the top half (“Fitting Sizes”) is in the currently open family. To add a single item from that list to the actual list of lookup tables to delete from families you can:

To select multiple lookup tables from the current family, you can use the Shift and Ctrl keys to select the lookup tables to delete from families, and then click the “Add Selected Tables” button.

We may also want to delete a lookup table in multiple families to process that doesn’t happen to exist in the current family. We can do this by specifying the name in the “Type a lookup table name” field and clicking the “Add Lookup Table” button.

This was done in the above example, where a “Test Lookup Table” value was entered and the “Add Lookup Table” button was clicked.

Import Lookup Tables Sub Tab

This tab allows you to define, by file name, which lookup table files should be imported into the families to be processed:

Family Processor Interface

Click the “Browse for Files to Add…” button to select which CSV files to import as lookup tables into each family to be processed.

In the example above, the lookup table file D:\Temp\Fitting Sizes.csv was selected. During the processing of the family files, this lookup table file will be imported into each family.

Change Materials Tab

The next tab in Family Processor is the Change Materials tab:

Family Processor Interface

This tab contains 3 subtabs:

Delete Materials Sub Tab

This tab allows you to define, by name, which materials should be deleted from the families to be processed:

As with the other tabs, information from the currently open family is used to provide starter choices in the top half of this tab, and the bottom half of this tab is where the changes to actually apply to the families are listed. As items are added to the bottom half, they are removed from the top half.

Currently no changes to apply are listed in the example above. In this example, the materials that appear in the top half are those in the currently open family. To add a single item from that list to the actual materials to delete from families you can:

Family Processor Interface

As with the other tabs, information from the currently open family is used to provide starter choices in the top half of this tab, and the bottom half of this tab is where the changes to actually apply to the families are listed. As items are added to the bottom half, they are removed from the top half.

Currently no changes to apply are listed in the example above.

In this example, the materials that appear in the top half are those in the currently open family. To add a single item from that list to the actual materials to delete from families you can:

To select multiple materials from the current family, you can use the Shift and Ctrl keys to select the materials to delete from families, and then click the “Add Selected Materials” button.

In the above example you can see that there are more materials after Default Wall. We can filter out all the other materials by putting the word “default” in the Only names containing field, which will turn yellow when information has been typed into it:

Family Processor Interface

In this example we’ll select Default Light Source and Default Wall and click the “Add Selected Materials” button:

Family Processor Interface

We may also want to delete a material in multiple families to process that doesn’t happen to exist in the current family. We can do this by specifying the name in the “Type a material name” field and clicking the “Add Material” button:

Family Processor Interface

Further, we can use one or more family files other than the currently open one to get material definitions from as well. This can be useful in case you don’t know all of the material names that exist in other family files to be processed:

Family Processor Interface

When the “Select Files” dialog appears (shown below), the “Browse…” button can be used to find a folder in which family files exist.

Once family files are found, they are displayed in the top list. One or many can be selected in the top list, and the “Add Selected Files” button can be clicked to copy the selected items to the lower list.

Note that files can be added from very different folders, as selected items from multiple searches can all be consolidated into one list using this dialog (search, add some, search elsewhere, add some, etc.).

Family Processor Interface

Once the “OK” button is clicked, the family files in the lower list will be scanned and the list of unique materials found in all the families will be shown on the previous screen:

Family Processor Interface

One or many of these can be selected. Clicking the “OK” button will return the selected items to the list in the lower section of the main Family Processor screen:

Family Processor Interface

Items can be removed from the list in the bottom half of the screen by either double-clicking on them or by using the “Remove Selected Items” and “Remove All Items” buttons at the bottom of the screen (highlighted).

To use the “Remove Selected Items” button, you must first select the name(s) of the materials to remove from the list by clicking on them. You can use the Ctrl and Shift buttons while clicking to help select multiple items.

Add Materials Sub Tab

This tab allows you to define new materials to be added to a family. The following values can be specified:

If a material with the same name already exists on a family being processed it will not be modified with the values you specify for adding materials. If a material with the same name already exists, this addition definition will simply be ignored.

This tab works just like the Delete Materials tab, with the ability to set these additional values. For example:

Family Processor Interface

To select items to be removed from the bottom list, you click on their row headers. You can use the Ctrl and Shift buttons while clicking to help select multiple items:

Family Processor Interface

Materials to Change Sub Tab

This tab allows you to define new values for materials that already exist in families to be processed.

The following properties can be changed on materials to be edited:

This tab works in the same way as the Add Materials tab. For example:

Family Processor Interface

Here you can see that we changed the Default material to be a lighter gray, and we changed the name of “Glass” to be “Bulletproof Glass” and made it a lighter shade of blue with less transparency than regular glass.

Change Parameters Tab

This tab contains tools for allowing you to change many aspects of the parameters to be found in the family files to be processed:

Family Processor Interface

An important thing to note regarding changing parameters is only ONE shared parameters file can be used when adding shared parameters or replacing parameters with shared parameters. If you need to work with more than one shared parameters file, you'll have to process the families once for each shared parameters file.

The shared parameters file to use is specified at the top of this tab. The first time you visit this tab, the empty area in which to specify the shared parameters file to use will blink yellow 3 times.

Family Processor Interface

You only need to specify a shared parameters file if you will be adding shared parameters or replacing a parameter with a shared parameter.

Delete Parameters Sub Tab

This tab allows you to define, by name, which parameters should be deleted from the families to be processed:

Family Processor Interface

Remember that in Revit, parameter names are case-sensitive, so the correct use of upper- and lower-case letters matters.

This dialog works the same as the Delete Materials dialog, except for the additional “Show all shared parameters” checkbox. When unchecked it will show only those parameters that were found in the currently open family. When checked it will also include in the list all the parameters defined in the shared parameters file specified as well, if any.

Also as with the Delete Materials dialog, the “Select from Family File(s)…” button allows selecting parameter definitions from one or more family files other than the one currently open.

Family Processor Interface

Add Shared Parameters Sub Tab

This tab allows you to add shared parameters to the families being processed:

Family Processor Interface

The definitions for the shared parameters can only come from the shared parameters file specified, so those are the only ones presented as choices. Family Processor uses the names of the parameters listed in this dialog and the name of the shared parameters file to tell Revit how to correctly add the shared parameters to the families being processed.

As with other parameter-oriented tabs, this tab has special features that are worth noting:

Family Processor Interface

Selecting one of the choices and clicking the “OK” button will apply that unit symbol to the value in the grid.

IMPORTANT: Because one new parameter to add may require a formula that references another new parameter to add, the order of the parameters being added can be very important. Just like when using the Revit user interface, the parameter being used in the formula must be added first.

You can control the order of the parameters to add by using the up and down arrow buttons to the right of the list of parameters to add:

Family Processor Interface

These buttons are enabled when you select one or more rows to move up and down the list by clicking on their row header buttons.

In the example above, we may want to have the Supply Fan Apparent Load parameter added before the others. To make that happen, we click on the row header for it, and then the up-arrow button twice:

Family Processor Interface

Add Family Parameters Sub Tab

This tab allows you to add family parameters to the families being processed.

Family Processor Interface

It works exactly the same way as the “Add Shared Parameters” tab, except the list of source parameters are the parameters in the currently open family, plus you have the ability to add your own custom parameter definitions, or get definitions from one or more other family files.

Replace with Shared Parameters Sub Tab

This tab allows you to replace an existing family or shared parameter in the families being processed with a specific shared parameter from the selected shared parameters file.

Family Processor Interface

On this tab you define the parameter name and type to replace with a specific shared parameter. As with other tabs, the list in the top section is built from the parameters in the currently open family, plus you have the option to show or hide all the shared parameters from the currently selected shared parameters file as well.

Also as with other tabs, you have the ability to manually define your own parameter name and type to replace with a shared parameter, or get parameter definitions from another family file.

Once a parameter to replace is in the lower section, you assign a parameter from the currently selected shared parameters file to replace it with.

As can be seen in the next image, when you choose which shared parameter to use to replace the existing parameter, you only get to choose from those shared parameters defined as the same parameter type as the one to replace:

Family Processor Interface

This ensures that you can only choose a replacement parameter that Revit will allow to work.

If a shared parameter exists with the exact same name and parameter type as the parameter to be replaced, it will automatically be selected by default from the list as soon as the parameter to be replaced is added to the list.

An option exists at the bottom of the list which can be used to automatically find all parameters in the family being processed whose name and parameter type matches the name and parameter type of parameters that exist in the shared parameters file and automatically replace them with those shared parameters:

Family Processor Interface

For example, if the family contains a Length parameter called Overall Length and the shared parameters file also contains a Length parameter called Overall Length, the one in the family will be automatically replaced by the one in the shared parameters file because they are both of the same parameter type and have exactly the same (case sensitive) name.

If the parameter in the family is either a family parameter or a different shared parameter than the one in the shared parameters file, it will be swapped out with the one from the shared parameters file. This would automatically occur for all parameters in the family with matching definitions in the shared parameters file.

Parameters to Change Sub Tab

This tab allows you to make changes to the properties of existing family and shared parameters.

Family Processor Interface

As can be seen in the above image, you can change the name (for family parameters), whether or not the parameter is instance or type (or leave that setting alone), the value, the formula and the group in which the parameter should be listed.

If no characters have been typed in for a value or formula (the cell in the grid is empty), the current value or formula will NOT be changed.

To clear out a parameter's formula or a TEXT parameter's value, set the formula or value to one or more space characters.

Just as in Revit, you may only change the value or formula for a built-in parameter. So you can’t, for example, change the Model parameter to be an instance parameter.

When adding a FamilyType parameter (has a combo box allowing you to "swap out" one nested family for another) to the list of parameters to change while a family is open with that parameter in it, by default a number will appear in the Value field representing the ID of the currently selected choice in this family. You MUST change that value to be blank (not even spaces, to leave its value alone) or to the name of the type to apply, exactly as it appears in the list of choices in the combo box list when changing the value manually in the family editor for the family being processed. This is because ID values are likely to vary between families. Also, as normally seen in Revit, you cannot set the formula for a FamilyType parameter.

Handling Special Parameter Workflows

When adding parameters, the entire add will fail if a parameter with the same case-sensitive name already exists in the family. If a parameter already exists with the same name, it will remain untouched by the add process.

However, it may be desirable to “add the parameter with my value if the parameter doesn’t exist in the family, or set my value on the parameter if it already exists in the family.” Family Processor does NOT assume everyone wants to do this at all times: add means only to add, not to change existing. This ensures there is no confusion.

IMPORTANT: But this workflow can still be achieved by defining the parameter in the “Add” list, and defining it AGAIN in the “Parameters to Change” list.

The Add process will create it and set the value if it doesn’t exist. Whether or not it was just added, the Change process will set the value because the parameter will now exist.

Another workflow might be “I’m adding dozens of parameters by selecting them from a complex mechanical family, and the formulas for many parameters reference other parameters, but determining the order they need to be added in so all the formulas work during the add would be difficult, time-consuming or error-prone.”

IMPORTANT: This workflow can also be achieved by selecting the parameters from another family in the “Add” list, in any order, and selecting them from the other family AGAIN in the “Change” list, again in any order.

In this case the parameters will be added to the family even if setting the formula during the Add fails because another parameter needed in the formula hasn’t been added yet.

However, when the Change command is run again later, all the parameters WILL be on the family at that time, so setting the formulas again will always work.

Processing Order Tab

This tab allows you to control the order in which the changes to be made to the family are applied:

Family Processor Interface

By default, the order in which the changes are applied matches the order in which the settings are presented in the tool.

However, there are some workflows which cannot be done with the default order, or that could be done but which would require multiple runs of Family Processor with different settings on the same families.

One example is the desire to replace an existing parameter with a shared parameter if the original parameter is found, but if the original parameter is NOT found, to then add the shared parameter. This ensures the shared parameter exists on the family, but has replaced an existing parameter if it had been there originally.

For example, “I want to replace parameter Volts with shared parameter Voltage, but if parameter Volts doesn’t exist, then add shared parameter Voltage”

Using the default processing order, shared parameter Voltage would get added even if parameter Volts exists, then the replace later would fail because shared parameter Voltage would already exist in the family, and you’d wind up with both parameters on the family.

So in this case you’d want the Replace with Shared Parameters to happen before the Add Shared Parameters.

To change the order of processing, select one or more items in the list and use the green “Move Up” and “Move Down” buttons. To make the example above work, these settings would be made:

Family Processor Interface

You can also disable the settings during processing by unchecking an item. For example, if we want to keep the settings of the family parameters to add, but not apply them for the time being, simply uncheck that item:

Family Processor Interface

IMPORTANT: The processing order is saved with the rest of the settings. If you disable an item by unchecking it and save the settings, the next time those settings are loaded that item will still be disabled. This button: Family Processor Interface can always be used to reset the processing to the default order Family Processor uses.

Select Families & Begin Tab

This tab allows you to control which family or families are processed, and configure any special processing that should be done:

Family Processor Interface

If selecting the current family file, as seen above, the currently open family will have the changes applied to it, but the family will not be saved automatically. You must do that yourself once you have approved of the changes made.

At the bottom of the screen is an option to log only errors. The Last Log tab (discussed next) shows the log of all the processing that was done during the last run of Family Processor. If this option is checked, it reduces the log to only errors that may have occurred, such as trying to add a family parameter when there was already a parameter on the family with that exact name.

If the option is turned on in the Options dialog, another checkbox may appear at the bottom of this screen that allows exporting the parameter information for all types to an XML file.

When multiple families are to be processed, the screen looks like this:

Family Processor Interface

The upper portion of this screen is used to select which families to process. The lower portion of this screen contains some options. One of these options is the “Preview only” option. With this option selected, each family to process is opened and the changes attempted on them, but the families are not saved once the processing on them is complete. The Last Log tab will show both the successful changes that were able to be made to the families processed, as well as the changes that were not able to be made.

The “Save to alternate parent folder” allows you to save the changed versions to a completely different folder structure, while maintaining the same set of subfolders as in the original parent folder. NOTE: Saving to an alternate parent folder always saves family files, even if no changes were detected.

In the example above, when the first family in the list is processed, the updated version would be saved to: D:\Temp\Processed\Samples\rac_advanced_sample_family.rfa

This is because the “Parent folder” specified at the top is “C:\Program Files\Autodesk\Revit 2017” but the family being processed is in the further subfolder “Samples” – so that set of subfolders is appended to the alternate parent folder selected, which was D:\Temp\Processed

There are more options available as well:

Family Processor Interface

The “Override the preview image using the view with this name (select or type the case-sensitive view name)” allows you to specify a view to use to create a new preview image. If this option is unselected (the default) the preview image will be regenerated from the last view used to make it, retaining the same preview image as was originally in the file.

If this option is selected, and a view with the specified name can be found in the family, the preview image will be recreated using the specified view. The list of choices for views to use comes from the currently open family, however you may type in any view name you wish. Just remember that view names are case-sensitive.

The “Create new shared parameters file from all unique shared parameters found in families” option, if checked, will create a new shared parameters file that will consist of all the unique shared parameters found in all the families that are processed.

There are some limitations:

The “Create Type catalog files” option, if checked, will create type catalog files next to the family files being saved.

NOTE: The type catalog files will NOT include built-in parameters, such as Manufacturer, Cost, etc. These are most commonly seen in the Identity Data group.

If type catalog files exist, the new ones being generated will overwrite the old ones.

IMPORTANT: If you choose to “Delete the types in the families” be aware that once the types are removed from the families, they are gone and cannot be used to regenerate type catalogs again in the future. For example, if you generate type catalogs and delete the types from the families, then later add a parameter to the families and want to regenerate the type catalogs, the old type catalogs will get overwritten with new ones that have no types in them.

If you leave the types in the families users can still benefit from this by only loading the desired types into the project using the type selector dialog, thus keeping the project smaller and lighter and simpler to use than if all the types in the family were loaded, which is what happens when not using type catalogs.

IMPORTANT: If you choose to “Delete the types in the families” be sure to test this process on some families with this option turned OFF to ensure the type catalog files generated include all the data necessary. Once the types in the families have been deleted, the only way to get missing data back is to revert to using backup copies of the families from before the types were deleted.

If the option to sort the parameters is selected, the parameters in the type catalog files generated will be sorted alphabetically. If it is not selected, the parameters will appear in the order returned by Revit. In 2015 or later, this is the order seen within each group on the Family Types dialog in Revit, however the order the grouped parameters appear in the type catalog file is determined by Revit. For example, the Identity Data group may be shown last in the Revit user interface, but the parameters from that group may be listed somewhere in the middle.

If the option to sort the types alphabetically is selected, the types listed in the type catalog will be sorted alphabetically, but this is a TEXT sorting. So if, for example, you have types that start with numbers, they may not appear sorted in numerical order. For example, you might see something like this:

1

10

2

3

35

4

Parameter sorting works the same way.

If the option to sort the types alphabetically is NOT selected, the types will be listed in whatever order Revit provides.

The option to save the type catalog files to *.csv files instead of the default *.txt files may be useful if you want to edit the type catalog files manually in spreadsheet software before finally saving them to *.txt files for production use with Revit.

For example, you may want to delete some parameters (columns) from the type catalog file before the final renaming to *.txt files, and the easiest way to do that is likely in spreadsheet software.

The option to exclude parameters by name using wildcards can remove parameters from the type catalog that are not desired.

For example, you may have a naming convention for parameters which are used to control how geometry flexes. Perhaps those parameters have names that start with CTRL:

CTRL_AutoHeight

CTRL_ArrayCount

You may also want to exclude formula-driven calculated parameters whose names have “calculated” in them.

To filter both of these sets of parameters out of the type catalog, you’d type: CTRL*|*calculated*

Note that there should be no spaces around the pipe (|) separator character.

IMPORTANT: Parameter names are case-sensitive, and as such these searches are case-sensitive as well. So searching for parameters that start with CTRL* is different than searching for parameters that start with Ctrl*

Once you click the “Begin Processing” button, the families will be opened and processed. A progress dialog that looks like this will be displayed:

Family Processor Interface

If the “Cancel” button is clicked, you will be asked if you want to stop processing the families. If processing is stopped, any families processed up to this point WILL have been saved with the settings applied.

Last Log Tab

This tab is automatically displayed once processing has completed. It shows a log of all the actions that were attempted, and the success or failure of each action:

Family Processor Interface

Buttons along the top allow you to turn on and off the different types of messages. For example, clicking the “Info” button will not show any Info rows in the log. Only Error, Warning and Successful messages would remain in the list.

NOTE: If the “Log only errors” option is checked then only errors (and a few info messages such as separators) will appear in the log.

The log can also be saved to one of several formats, including a spreadsheet format, comma-delimited text file, a tab-delimited text file and as an XML file.

Logs for each run can be automatically saved as comma-delimited text (CSV) files to a specified folder. This can be controlled by the Options settings.

Family Processor Best Practices

Because of the complexity of the settings that can be applied and because they can be applied to many families, it is recommended that you take great care when using Family Processor:


Videos

Youtube Playlist

Related Tools

Family Exporter

Family Loader

Project Processor


Back to the Manager Tools Index