What Properties can you use in PropertyWizard formulas?

Or, ‘How to use RevitLookup to find the right Property’.

You can access two kinds of property in your PropertyWizard formulas:

• Standard Parameter properties.
• API properties.

This post explains how to explore both these kinds of property using RevitLookup.

Getting Started

So, selecting a Door in Revit and choosing ‘Snoop Current Selection’ from the RevitLookup menu, I get this dialog:

The left pane of the dialog lists the elements you selected. In the Revit API, a door is a ‘FamilyInstance’, and RevitLookup identifies the door by its Name and ElementID.

The right pane lists the element’s API Properties and Methods. I’ll go into more detail on which API Properties you can access later in the post, but first let’s look at standard Parameter properties in RevitLookup.

Parameter properties in RevitLookup

Parameters are the standard properties shown in the Revit Properties window:

And you can see them in RevitLookup by clicking on the ‘Parameters / <ParameterSet>’ property under Element:

This will open another RevitLookup window showing the door’s parameters in the left pane:

All of the properties visible in the Revit Properties window are visible in this Parameters list. If you add extra instance parameters in Revit, you will see them here too.

There are a few extra parameters in the RevitLookup list, and a few duplicates. It should be possible to access the extra parameters straightforwardly, but currently it is not possible to tell PropertyWizard which of the duplicates to use.

Getting Values from Parameters

So, to access the value of a parameter in a formula, you just type the name of the parameter as shown in RevitLookup’s left pane. Enclose the name in square brackets if it contains spaces or other special characters.

For best results, I would check a few things about your parameter before using it in a formula.

StorageType

The first thing to check is the parameter’s StorageType. It will be one of these five values:

If the StorageType is ‘ElementId’, PropertyWizard will return the referenced element. You can use dot notation to access sub-properties of the element, for example, Type will return the door’s Type, and so Type.[Type Mark] will return the door type’s Type Mark parameter.

Parameters with ‘Integer’, ‘Double’ and ‘String’ StorageTypes will return those values directly. Strings are straightforward, but Integers and Doubles will need some interpretation.

Definition.ParameterType

Each parameter has a Definition, and the Definition contains the parameter’s ParameterType. The ParameterType tells you how PropertyWizard will interpret Integer and Double parameter values.

In this example, the Door’s ‘Head Height’ parameter has a StorageType of Double and a ParameterType of Length, so you know that the value you get back will be a Length value.

PropertyWizard automatically converts the returned value into the relevant units, so this Length value will be interpreted directly as a length.

ParameterType.YesNo values will be returned as boolean (true / false) values, that you can use directly in PropertyWizard’s logical functions. They have StorageType Integer: Yes / true is stored as 1, and No / false is stored as 0. 

It is important to match the unit types in your formulas, otherwise you will receive the equivalent of Revit’s ‘inconsistent units’ error.

I’m aware that I have more work to do to expand the range of ParameterTypes that PropertyWizard handles.

HasValue

The last thing to check before using the parameter is ‘HasValue’. This tells you whether the current element’s parameter has a value.

Frequently, a parameter will have a value for some elements, but not for others, so your formula will work for some elements but not for others.

For example, this door’s ‘Finish’ parameter does not have a value, so accessing it will return an error:

For other doors, where the Finish has been set, the formula will complete without error. 

You can catch the error with the try function and supply a default value of your choice, like this: try(Finish, "NO FINISH SET"):

API Properties

API Properties are all the Properties in the right-hand pane of the element’s RevitLookup window:

If you scroll down in the right pane, you’ll see that below the Properties section there is a Methods section. These are the API Methods, which you currently cannot access from PropertyWizard. If you try to access a Method, you will get a ‘Property name not recognised’ error:

However, if you scroll further down in the right pane, you’ll see that the door element has three sets of Properties and Methods, separated by blue bars: ‘Element’, ‘Instance’ and ‘FamilyInstance’. Element and Instance are the base classes of FamilyInstance in the RevitAPI, as shown in this screenshot from ‘RevitAPI.chm’:

This means that from a door formula, in principle you can access API Properties from each of the classes Element, Instance and FamilyInstance.

Most API Properties are simple, but there are a few that are parameterized, and you cannot access these from PropertyWizard formulas (yet). For example, on the FamilyInstance, there are parameterized versions of FromRoom, ToRoom, Room and Space, which RevitLookup fails to read and which you cannot access in PropertyWizard.

Getting values from API Properties

Just as with standard Parameters, to access the value of an API property in a formula you just type the name of the property. You will not need to use square brackets round an API Property name, because they never use special characters.

When PropertyWizard is matching your typing with a property name, it always looks for a Parameter before it looks for an API property, so a Parameter will mask an identically-named API property.

API Property Types

The key thing to find out before using an API Property is ‘what kind of value does it return?’

Often, you can work this out from RevitLookup. But the definitive guide is always the Revit API documentation, either the RevitAPI.chm (which you can download from Autodesk as part of the Revit SDK), or Gui Talarico’s excellent revitapidocs or his newly-launched apidocs.co. 

These are the first few API properties of the Element class as shown in RevitAPI.chm:

 Looking at the first property, AssemblyInstanceId, you can check the return type in RevitAPI.chm:

And in RevitAPIDocs:

Both show the same listing, and API property listings are fairly easy to interpret. The return type is the word before the property name (in this case ‘ElementId’). 

As with Parameter properties, if an API property returns an ElementId, PropertyWizard will automatically return the referenced element. This will behave exactly like an Element returned from a Parameter property, so you can access its parameters and API properties using dot notation.

Other common return types include string, integer and double, all of which are returned as values that you can use directly in formulas.

API ‘bool’ values are returned as booleans, which you can use in PropertyWizard’s logical functions or assigned direct to Yes/No parameters.

Other return types will generally be Revit API or .Net class types. You can use dot notation to access the API properties of these classes, in exactly the same way as you can with Elements.

You can ‘drill down’ through the API documentation to explore the RevitAPI classes, and follow the links out to the .Net documentation for .Net classes. For example, this is the .Net page that’s linked from a bool:

The documentation does start to get complex, but the subtitle tells you most of what you need to know: ‘Represents a Boolean (true or false) value.’

Conclusion

So that is a quick guide to using RevitLookup (and the Revit API documentation) to explore the properties you can use in your PropertyWizard formulas. If anything is unclear or doesn’t work as you expect, please let me know.