Learn how to dynamically display associated HubSpot object data—like line items on a deal—using DocMergy loops, merge functions, and smart formatting in Word templates.
Using the get_associated_objects function in DocMergy
- To dynamically pull data from associated HubSpot objects, you’ll need to use the get_associated_objects merge function in your template.
Function Syntax (Function syntax is the set of rules that define how to write a function, including its name, parameters, code block, and optional return value.)
- get_associated_objects(from_object_type, from_object_id, to_object_type, order_by)
Argument Breakdown
First argument [from_object_type]
- The source object you're starting from.
- Usually, this is the object type that triggered the workflow (e.g. 'contact' if your workflow is triggered by a contact).
Second argument [from_object_id]
- The HubSpot ID of the object you're pulling associated records from.
- Tip: You can get the current object’s ID using: object.hs_object_id
Third argument [to_object_type]
- The object type you want to retrieve.
- Examples include
- "company'
- "deal"
- "line_items"
Fourth argument [order_by]
- Defines how the results are sorted.
- If not specified, HubSpot will sort by creation date (oldest first).
- To sort manually, use a tuple format: ("createdate", "DESCENDING")
Example – Get the most recently associated company:
{{ get_associated_objects("contact", object.hs_object_id, "deal")[0].dealname }}
Here's what it means step-by-step:
Get the name of the first deal associated with the current contact.
- get_associated_objects("contact", object.hs_object_id, "deal")
This gets a list of deals associated with a contact. - "contact" is the source object type.
- object.hs_object_id is the ID of the current contact in the context.
- "deal" is the target associated object type.
- [0] This takes the first deal from the list of associated deals.
- .dealname This accesses the dealname property of that first associated deal.
Example of table displaying all line items on a deal
In this scenario, we assume that multiple line items are associated with a deal
The above table would be in the Word/Doc/Presentation template
Any row above the {% for ... %} won't be touched by DocMergy and is usually your table header.
The second row is the definition of the loop that will iterate on what the get_associated_objects returns. We define a variable called line_item (this can be anything you want) that will hold the current record in the loop. This row will be removed when the document is rendered, it is usually more readable to merge all columns of this row but it is not required.
The last row represents the current object that we are iterating on. In the same way we access properties on "object." we can now use "line_item." or any name that you have used above in the for loop.
The Loop Row
{% raw %} {% for line_item in get_associated_objects("deal", object.hs_object_id, "line_items") %} {% endraw %}
-
This line starts a loop that fetches all line items associated with the current deal.
-
line_item is just a temporary variable name for each item. You can call it whatever you want.
-
This row will not appear in the final document.
Inside the Loop
{% raw %} {{ line_item.hs_sku }} {% endraw %}
{% raw %} {{ line_item.description }} {% endraw %}
{% raw %} {{ "${:.2f}".format(line_item.price.to_float()) }} {% endraw %}
{% raw %} {{ line_item.quantity }} {% endraw %}
These cells use the line_item variable to display:
-
SKU
-
Description
-
Price (formatted as currency using Python f-string style formatting)
-
Quantity
Ending the loop
{% raw %} {% endfor %} {% endraw %}
- This line tells DocMergy when to stop looping through the line items.