Revit-API-08

revit-api/08-chnages-in-revit-api

How make changes with Revit API?

You can't make changes with Revit API unless you use Transaction. And it's a great feature. Let me explain what is it and how to use it.

Revit-API-08

courses

basics

revit-api/08-chnages-in-revit-api

How make changes with Revit API?

You can't make changes with Revit API unless you use Transaction. And it's a great feature. Let me explain what is it and how to use it.

Resources

API: Transaction Class

Summary

What is a Transaction in Revit API?

In this lesson you will learn how to make changes using Revit API.

Also, I also want to reassure you that it's very safe to explore Revit API because you can not make any changes by accident. You literally have to Start and Commit Transaction to make any changes.

This is great news for beginners, because you can explore Revit API without the fear of breaking anything. And if you try to make a change, you will get a warning saying "Attempt to modify outside of Transaction." And it will not change anything.

Transaction in Revit API is like a guardian of Revit projects. It makes sure that you can't make any changes in Revit projects by accident and you can't break anything. It's there to protect projects from unwanted changes and beginner coders.

And it's actually easy to use.

How to use Transaction?

Firstly, to use a Transaction in Revit API - you need to create it. SO let's open Revit API Docs and have a look at Transaction - Constructor methods.

You will see the following option with 2 arguments:

Document refers to a Revit project. Usually we define doc variable for the currently open project, that's what we will provide here.

Name refers to the name of the change that will be shown in the undo menu. I like to include py_ or ef_ prefix to indicate that it's from my tools, but you can write anything you want.

# 🔑 Create Transaction for Project
t = Transaction(doc, 'ChangeName')

Once you have a transaction you need to use its methods - Start and Commit. And it's important that in between you put your piece of code that makes changes.

# 🔑 Create Transaction for Project
t = Transaction(doc, 'ChangeName')

t.Start()  # 🔓

# 👉 Code Changes Here...

t.Commit()  # 🔒

💡Notice that code with changes have to be in between Start/Commit.

Let's break it down.

Change Parameter Value

So, now you know about Transactions let's make some changes.

We are going to continue with the code from previous lesson, and we set new parameter values. Here is the code we will reuse:

# 👉 Pick an Object
ref_pick_object = uidoc.Selection.PickObject(ObjectType.Element)
elem            = doc.GetElement(ref_pick_object)  # Pick Wall Instance 
elem_type       = doc.GetElement(elem.GetTypeId()) # Get  Wall Type

# Get Instance/Type Parameters
p_comments     = elem.get_Parameter(BuiltInParameter.ALL_MODEL_INSTANCE_COMMENTS)
p_typ_comments = elem_type.get_Parameter(BuiltInParameter.ALL_MODEL_TYPE_COMMENTS)
p_area         = elem.get_Parameter(BuiltInParameter.HOST_AREA_COMPUTED)

# Display values:
print('Comments: {}'.format(p_comments.AsString()))
print('Type Comments: {}'.format(p_typ_comments.AsString()))

To change parameter value we need to use .Set method and provide correct data type depending on your parameter.

So let's try to set some values without Transaction and see what happens.

# Set New Parameter Values
p_area.Set(15.69)        
p_comments.Set('EF Comment')
p_typ_comments.Set('EF Type Comment')

First of all you will get Exception: The parameter is read-only.

And it's because the Area parameter is indeed read-only, its value depends on the wall's geometry. (I just wanted to remind you that we can have read-only parameters in Revit).

Now, let's get rid of area, and try it again.

# Set New Parameter Values        
p_comments.Set('EF Comment')
p_typ_comments.Set('EF Type Comment')

This time we get Exception: Attempt to modify the model outside of transaction..

You will see this message quite often in the beginning and don't worry. It's 100% normal to see error messages during coding. It's just part of the journey.

Error messages don't mean that you crashed Revit. It just reports that something went wrong in your code and tries to describe what went wrong.

So in this case it's clear - let's add Transaction.

# 🔑 Create Transaction for Project
t = Transaction(doc, 'ChangeName')

t.Start()  # 🔓

# Set New Parameter Values (Code Changes between Start/Commit)  
p_comments.Set('EF Comment')
p_typ_comments.Set('EF Type Comment')

t.Commit()  # 🔒

Now it should work!

What if you provide wrong DataType?

Alright, now I want you to pay very close attention. It can save you a lot of hours in the future. Well, at least it would save me this much…

Sometimes you will have a large code where you get user input and then you convert the data between integer, float and strings. And then eventually you try to use it as a new parameter value, but you provide wrong DataType.

Probably you expect an error message, right? Well, Let's test it.

I will just try to set a Float DataType to our String Parameter.

# 🔑 Create Transaction for Project
t = Transaction(doc, 'ChangeName')

t.Start()  # 🔓

# Set New Parameter Values (Code Changes between Start/Commit)  
p_comments.Set(15.69) #❌ Wrong Data Type!

t.Commit()  # 🔒

If you execute this code then nothing would happen. Literally nothing.

Parameters wouldn't change, and you wouldn't get any errors. I've spent a few hours trying to debug my code when it was just a wrong data type. It happens…

⚠️So if you try to change parameter value, and it doesn't change. Double-Check the type of the data you provide, and make sure it matches parameter StorageType.

It's simple, but I remember how I couldn't understand why my code doesn't work. And it was just a wrong data type…

Change Wall Offset

Let's try to change another parameter like Wall's Base Offset.

First of all we need to get the parameter, and since it's a built-in parameter we need to check its internal name in Revit Lookup.

If you think logically it's a numeric parameter with decimal point, so we need to use float value. It also has StorageType.Double.

So let's use this code to set offset to 1.69cm.


# 👉 Pick an Object
from Autodesk.Revit.UI.Selection import ObjectType
ref_pick_object = uidoc.Selection.PickObject(ObjectType.Element)
elem            = doc.GetElement(ref_pick_object)

#🔎 Get Base-Offset Parameter
p_base_offset = elem.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET)

# 🔑 Create Transaction 
t = Transaction(doc, 'ChangeName')
t.Start()   # 🔓 

value_cm = 1.69
p_base_offset.Set(value_cm)

t.Commit()  # 🔒

And it kind of works...
There is one slight issue with the value. We tried to set 1.69cm, but we got 51.51cm.

So firstly, let's investigate with Revit Lookup. Some of you might already know what's the issue, but let me demonstrate it.

Investigate The Unit Difference

You will notice that in Revit Lookup it has the right value - 1.69.
However, it's 1.69 feet, which is 51.51cm.

⚠️Remember, Revit API uses feet as internal units. So we need to convert metric values.

So here is the revised code with value converted to feet (internal units).

# 👉 Pick an Object
from Autodesk.Revit.UI.Selection import ObjectType
ref_pick_object = uidoc.Selection.PickObject(ObjectType.Element)
elem            = doc.GetElement(ref_pick_object)

#🔎 Get Base-Offset Parameter
p_base_offset = elem.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET)

# 🔑 Create Transaction 
t = Transaction(doc, 'ChangeName')
t.Start()   # 🔓 

value_cm = 1.69
value_ft = UnitUtils.ConvertToInternalUnits(value_cm, UnitTypeId.Centimeters)

p_base_offset.Set(value_ft)

t.Commit()  # 🔒

And now it works as expected! Make sure to double check units you use.

Keep Tranasction out of loops.

Lastly, I want to give a very simple advice:

⚠️Keep Transaction outside of loops.

Everytime you Start and Commit a Transaction - you update Revit's Database. And on large projects it can take noticeable time.

Therefore, if you put your Transaciton inside of a loop, you will be making a lot of unnecessary updates, instead of making one single update with all your changes.

HomeWork

As usual, practice to remember it better.

Pick an element and try setting a few parameter values and don't forget to use Transaction.

Also, share in the community your insights and your code snippets. Together you will all learn much more.

⌨️ Happy Coding!

Complete Lesson

Discuss the lesson :

P.S. Sometimes this chat might experience connection issues.

Use Discord App for best experience.

Discuss the lesson :

P.S. Sometimes this chat might experience connection issues.

Use Discord App for best experience.

Discuss the lesson :

P.S. Sometimes this chat might experience connection issues.

Use Discord App for best experience.

Unlock Community

The pyRevit Hackers Community is only available with pyRevit Hackers Bundle.
Upgrade Here to Get Access to the community and all pyRevit Courses.

Use coupon code "upgrade" to get 150EUR Discount as a member.

⌨️ Happy Coding!

Unlock Community

The pyRevit Hackers Community is only available with pyRevit Hackers Bundle.
Upgrade Here to Get Access to the community and all pyRevit Courses.

Use coupon code "upgrade" to get 150EUR Discount as a member.

⌨️ Happy Coding!

Unlock Community

The pyRevit Hackers Community is only available with pyRevit Hackers Bundle.
Upgrade Here to Get Access to the community and all pyRevit Courses.

Use coupon code "upgrade" to get 150EUR Discount as a member.

⌨️ Happy Coding!