SubTransactions and TransactionGroups

Sometimes we need to commit Transaction before we can go to the next step, and using regular Transaction would cause too many items in Undo menu. So let's learn how to combine them into single Action in Undo menu.

Back to Lessons

M5-02

Sub-Transactions and Transaction Groups

Back to Lessons

M5-02

SubTransactions and TransactionGroups

Resources

Docs: SubTransaction

Docs: TransactionGroup

Summary

SubTransaction and GroupTransaction

I would recommend you to use regular Transaction all the time. But sometimes we would need to commit multiple steps for our script to work.

For example in Revit 2021, we couldn't create Floor with an openings in a single Transaction. We would need to create a Floor and then create an opening. Luckily they changed that in future Revit versions.

So we would have to create multiple transactions and then Group them together so we only have 1 change in Revit undo menu. Theoretically, SubTransactions should also work for that, but in my experience TransactionGroup works much better.

Let's' see how to use them

SubTransaction

Let's start with SubTransaction. Sub-transactions are objects that provide control over a subset of changes in a document.

💡 A Sub-transaction can only be active as a part of an open transaction. They can't exist on their own!

Here is a syntax of how to create them.

#🔷 Start Transaction
t = Transaction(doc, 'Transaction')
t.Start()


st1 = SubTransaction(doc)
st1.Start()
# Change A
st1.Commit()


st2 = SubTransaction(doc)
st2.Start()
# Change B
st2.Commit()

#🔶 Commit/Rollback Transaction
t.Commit()
# t.RollBack()

TransactionGroup

TransationGroup can be used to combine multiple transaction into one. It also provides you controls over all transactions.

If you have 5 Transaction for whatever reason, and on the last one something happened and you want to cancel them, TransactionGroup will be able to give you that control.

If the group is committed, all the transactions remain committed, but if the transaction group is rolled back instead, all the inner, already committed transactions will be undone (and removed).

It also gives you an ability to combine all Transactions into single one, so you only have 1 thing in the Undo menu.

Here is a Syntax on how to use them. It's just abstract example.


#🔷TransactionGroup - Start 🔓
tg = TransactionGroup(doc, "Transaction Group")
tg.Start()


t1 = Transaction(doc, 'Change A')
t1.Start()
# Changes here
t1.Commit()

t2 = Transaction(doc, 'Change B')
t2.Start()
# Changes here
t2.Commit()

for i in range(5):
    t = Transaction(doc, 'Change in Loop')
    t.Start()
    # Changes here
    t.Commit()

#🔶 TransactionGroup Assimilate/Commit/Rollback 🔒
tg.Assimilate()
# tg.Commit()
# tg.RollBack()

💡 Assimilate method combines all Transations into single one and it also Commits all Transactions.

💡 You still need to commit all Transactions inside of TransactionGroup.

Complete Lesson

Questions:

When should I use them?

Discuss the lesson:

P.S. Sometimes this chat might experience connection issues.
Please be patient or join via Discord app so you can get the most out of this community and get access to even more chats.