11 Steps to Create your First Dynamo Script

This post is an excerpt from our MANAGE learning package for Revit.

Dynamo is a visual programming platform for Revit. Typically, programming is done with text. Visual programming replaces code with nodes and wires instead. In the end, you can achieve the same result by building a custom add-in than a Dynamo script. In the image below, the Visual and Textual programs both accomplish the same thing.

In this chapter, we will focus on modifying parameters and information. Dynamo can be used to generate geometry, but these features are usually more complex. We’ll focus on the simple stuff first.

Dynamo Terminology

Open Dynamo. You will find the tool on the ribbon, in the Manage tab.

Here is the basic terminology of Dynamo. Nodes are the little boxes you keep seeing all around. We’ll use that word a lot.

Connecting Nodes

The core idea of Dynamo is to connect nodes using wires. That’s what we do in the image below.

Renaming Nodes

Double-click on a node to rename it. Renamed nodes will have a yellow “Renamed” tag alongside the name.

Nodes Library

On the left of the interface, you’ll see the node library. They are divided into multiple categories. The nodes that interact with Revit are part of the Revit category. The search bar is essential to find your way around the huge number of nodes.

Custom Community Packages

A strength of Dynamo is the active community which keeps providing additional nodes for free. Go to the Package menu and select Search for a package. Some packages are essential for a great Dynamo experience. More on that later.

Input Nodes

Input nodes are essential to get your script started. They are used to define specific numbers, text, file path, yes/no and much more. Here are some input nodes you’ll encounter:

Creating a Note

Some scripts can become an insane spaghetti festival. Adding notes to the script helps other users understand what’s going on. Go to Edit and click on Create Note.

Then, type in whatever you want and click Accept.

Creating a Group

Notes are okay, but groups are better. Select multiple nodes and notes. Then, right-click and select Create Group.

Check out this awesome group:

You can show a group color by right-clicking it. Multiple colors will be available. When creating big scripts, use a strong color code to keep things easy to manage.

Manual Mode vs Automatic Mode

The Automatic/Manual option is located at the bottom right of the interface.

Automatic mode will run and rerun the script each time you modify it. This feature is the default mode in Dynamo but is probably not convenient for you. Automatic mode often executes scripts before users are ready to do so. You can potentially cause problems to your model if you aren’t careful.

Instead of Automatic, switch to Manual instead. When you want to activate the script, click on Run. Regardless of which mode you are using, create a test model before using your script on an important Revit model.

Dynamo Player

Some users are terrified of opening Dynamo. That’s ok, they can use the Dynamo Player to run the script, and they’ll never face the spaghetti. You will learn more about the Dynamo Player in the coming pages.

Creating a Sequence

That’s enough with the interface; let’s create something.

Add a sequence node. Use the right-click menu and type in Sequence.

Hover your cursor over one of the input ports. You will see a pop-up that explains what that input does and what input type the node expects—hovering your cursor above the entire node will explain how to use the node.

Adding Input Nodes

Let’s explore a few ways to create input. The universal Dynamo node is called Code Block and can be used for multiple things. You can indeed type in code but also type in values. To create a code block, double-click anywhere on the screen.

In the example below, we type numbers. Press Enter to create multiple lines on the same Code Block. Plug the wires.

Code Block has some limitations. One of them is that the values entered here can’t be customized in the Dynamo Player.

Number vs Integer

The Code Block alternative is to use a Number or Integer node. If you remember your math class, an integer is a number that is not a fraction.

Using a Slider

When creating numbers or integer input, you can use sliders. Click on the arrow symbol to adjust min, max and step.

Let’s plug that slider into the sequence!

Executing the Sequence

Execute the script. The sequence is generated. Hover your cursor on the node, and you’ll see a List pop-up. Go to the list and click the Pin icon to see all items on the list permanently.

Using a “String”

Time for some programming jargon: string means text.

Create a string node.

Type in a letter. As you can see below, the script now creates an alphabetical list instead of a number sequence.

This specific type of entry only accepts a single letter, but other nodes will allow you to use as many words and letters as you want.

Ok, we've created a sequence, but that doesn't amount to much. It's time to get serious and create a script that will allow you to modify the parameters of specific elements.

11 Steps to Create Your First Dynamo Script

1- Understand the Difference Between Category, Family, Type and Instances

You are ready to interact with a Revit model. First, take a look at this chart and make sure you understand it. Else, you'll get confused with nodes.

2- Define All Elements of a Category

Let’s say you want to pick all doors in your project. You’ll need to bring two nodes: Categories and All Elements of Category. Use the search bar to find the nodes.

In the Categories node, use the dropdown menu to pick a category. In this example, we use Doors.

A quick note here: if you try to type Doors in a String or Code Block node, you will get a warning. Revit expects the Category input type. A string isn’t a category. That’s why you need to use the Categories node.

3- Add "Element.SetParameterByName" Node

Search for the Element.SetParameterByName node. Set the doors to the element input port. Use a string value for the parameterName and a number for the value.

For the sake of this exercise, we use the Sill Height parameter to modify doors.

When your script is ready, click on Run if you are in Manual mode. If you are using Automatic mode, the script will be executed automatically. Check out your doors. The Sill Height should be adjusted to 150mm:

4- Switch to the “Select Model Elements” Node

Let’s pause for a moment and celebrate the fact that you’ve created your first useful Dynamo script. Isn’t that amazing? You can easily flip a few nodes to potentially affect all parameters of all categories in your projects.

We’ve used All Elements of Category in this case, but what if you want a specific elements selection instead?

Bring in the Select Model Elements node. Be careful: another node called Select Model Element (singular) only allows you to select a single element.

When you click on Select, go back to Revit and make a window selection.

5- Understand ElementID and Watch Node

When elements are selected, you will see a bunch of numbers populate the node. These represent the ElementID value, which is a unique number for each element. Add a Watch node: it will indicate the category or type of each unique ElementId. Click on the green ElementId to show the element in your Revit model.

6- Create a Selection Filter

Try to execute the script with your selection: you’ll most likely get a warning. That’s because you selected elements from multiple categories, not just doors. Other categories don’t have a Sill Height parameter, resulting in a Dynamo warning. The script is still working, but it is inefficient. This action isn’t good practice: you need to clean your script.

Let’s bring a node called Element.GetCategory and plug it in. The node creates a list with the category for each element.

Let’s bring another friend to the party. This one is called Category.Name. It will convert the categories to strings. Then, bring in the node called ==. This node will compare two values and give you a list containing either the True or False values.

In the x input, have a list with the Category of each selected element. In the y input, we plug in a Doors string input. The == node answers the question: is x = y? If yes, it returns True. If no, it returns False.

Check out the result. You can see that elements 0 and 2 (Walls and Rooms categories) return a False result. Element 1 returns True because it is part of the Doors category.

Let’s bring the final node in our selection filter: Boolean Mask. The node is called List.FilterByBoolMask. This node compares the original elements list to the true/false list and separates the result into two different lists.

To properly use the BoolMask node, you must initially plug in the selected elements to the list input. Plug the result of the == node in the mask input.

In the example below, you can see the Select Model Elements output is connected to two different nodes.

When the script is executed, the in list contains all doors, while the out list contains elements from all other categories.

Now, plug in the list to the Set.ParameterByName node you’ve added earlier. No more yellow warning!

7- Alternative: Use Node From Rhythm Package

Let’s be honest: that was a lot of nodes to filter by category. Let’s introduce John Pierson’s amazing Rhythm package. It contains the perfect node for you. First, search for the Rhythm package as you’ve learned in the previous section. Click on the arrow button to download.

Now, add the node called ElementFilter.ByCategory. If you are confused by the node, hover your cursor on the inputs to get full explanations.

Note: the search tool in Dynamo can be capricious. If you can’t find the node, try typing in “ByCategory”.

This custom node replaces the 4 default nodes we had to use in step #6. Big thanks to John Pierson, the oracle of Dynamo.

8- Replace “SetByParameter” Node

The Element.SetParameterByName is limited to instance properties. The Rhythm package contains another helpful node called Element. SetParameterByNameTypeOrInstance that also works with type parameters. Replace the old node with this custom node.

This image is what the final script looks like.

9- Prepare the Script for the Dynamo Player

The dynamo player is great if you want people in your team to use the script without interacting with the spaghetti interface.

There are a couple of easy steps to take if you want to bring your script to the Dynamo Player. Right-click on nodes and activate “Is Input”. Repeat the process for all input nodes you want to access in the Dynamo Player.

Once the node is set to inputs, you have to Rename them. Double click on a node and put a name that will be easy to understand for all users. In the example below, we rename the String node to CATEGORY.

In this script, we rename 3 nodes for Category, Parameter Name and Value.

10- Bring the Script to the Dynamo Player

Save the script. In this case, we’ll use the name “Assign Parameter to Elements”. Open the Dynamo Player, located in the Manage tab.

You will see the Dynamo Player interface with a bunch of default scripts. Click on the folder icon with an arrow. A windows folder will pop up. Paste your new script in that folder and click the circle refresh arrow.

11- Test Your Script

Your script should now appear in the Dynamo Player. Click on the properties icon before running it:

Users can modify all inputs. We can use this script to modify any number parameter value from any category. In this case, let's try to alter the wall's base offset to 175mm. Watch out: the parameter names are cap-sensitive. Make sure you type them in exactly as they appear, or else you'll get a warning.

Press on the Play button. If all goes well, it should say “Run completed”. If you get a warning, you’ll have to debug your script or ensure the inputs don’t have any mistakes.

To make sure the script worked, verify the walls on the models. The selected walls indeed have a Base Offset value of 175mm.

Download the Pamphlets Collection

Did you enjoy this post? Do you want to get even more tips, including how to a text parameter option inside your script and add further filtering? Download the latest issue of our Pamphlets collection about Dynamo.