Skip to main content

Auto-Expand Linked Objects

MSPintegrations makes it easy to access related entities from Autotask without explicitly querying Autotask for those related and nested objects.

How the Autotask API Works Natively​

When you retrieve an entity from the Autotask API, Autotask returns only that single entity. It does not include the entity's parent or any of its child entities. You get that one record and its own properties, including the ID properties that hold integers pointing at related records.

To gather all the information about an entity and the records it relates to, the Autotask API requires a separate request for each related record. For example, to get a ticket, its account, its contact, and its notes, you make one request for the ticket, then read the IDs on the ticket and make another request for the account, another for the contact, and another for the notes. Each related record you want is one more API call.

How the MSPintegrations System Handles This​

Building that same result yourself would mean adding a separate query action for each related record: one to fetch the ticket, another to fetch its account, another for its contact, and so on. You would wire each query to the IDs returned by the previous one.

The MSPintegrations system removes that work. Instead of building a query action for each related record, you reference the related entity's property by name, and the system retrieves the entity it needs at runtime. It fetches related entities automatically, opportunistically, and only when a property you reference actually requires them.

This does not change what the Autotask API returns. You still receive that single entity. What changes is how you interact with the returned object inside the workflow builder: by following an ID property, you read the properties of a related entity without building a separate query action to fetch it.

Two Behaviors: Reading the Stored ID vs. Following It​

An ID property behaves in two different ways depending on whether you stop at the ID or keep going.

Reading the stored ID returns the integer that is already on the object. This does not contact Autotask. The value is the literal integer stored on the entity you already have.

{{custom.ticket_note.TicketID}}      <!-- The parent ticket's ID (integer on the note; no API call) -->
{{custom.ticket_note.TicketID.id}}   <!-- Also the parent ticket's ID (no API call) -->

Following the ID retrieves the related entity. When you add a property after the ID, the system retrieves the related entity from Autotask and then resolves that property.

{{custom.ticket_note.TicketID.TicketNumber}}  <!-- Retrieves the parent ticket, returns its TicketNumber -->
{{custom.ticket_note.TicketID.Title}}         <!-- Retrieves the parent ticket, returns its Title -->
Rule of thumb

A bare ID property (TicketID or TicketID.id) is free: it renders a value the object already holds. Adding a property after it (TicketID.Title) retrieves the related entity from Autotask on demand.

In these examples, custom.ticket_note is just an example variable name. It assumes the ticket note was stored in the custom.ticket_note property earlier in the workflow. Use whatever variable name holds your object.

Autotask links a child entity to its parent by storing the parent's ID on the child. A ticket note holds its parent ticket's ID in TicketID. You reach the parent ticket by following that property.

{{custom.ticket_note.TicketID}}               <!-- The parent ticket's ID (no API call) -->
{{custom.ticket_note.TicketID.TicketNumber}}  <!-- The parent ticket's number -->
{{custom.ticket_note.TicketID.Title}}         <!-- The parent ticket's title -->
{{custom.ticket_note.TicketID.Status.Name}}   <!-- The parent ticket's status label -->

For more on why the child holds the parent's ID, see Understanding the Autotask Data Structure.

Following References on Any Entity​

This works for any property that holds the ID of a related entity. For example, starting from a ticket:

{{custom.ticket.ContactID}}              <!-- The contact ID (no API call) -->
{{custom.ticket.ContactID.FirstName}}    <!-- The contact's first name -->
{{custom.ticket.ContactID.LastName}}     <!-- The contact's last name -->
{{custom.ticket.ContactID.EMailAddress}} <!-- The contact's email -->

{{custom.ticket.AccountID}}              <!-- The account ID (no API call) -->
{{custom.ticket.AccountID.AccountName}}  <!-- The account name -->

{{custom.ticket.AssignedResourceID.FirstName}}  <!-- The assigned resource's first name -->

This makes it simple to answer questions like "Is the resource who completed this task still active?" without writing extra query steps.

Deep Navigation Across Multiple Entities​

You can chain ID properties to walk across several related entities in a single expression. Each step follows the ID property on the entity before it.

{{custom.ticket_note.TicketID.AccountID.OwnerResourceID.FirstName}}

This expression walks from the ticket note, to its parent ticket, to that ticket's account, to that account's owner resource, and then resolves the owner's FirstName.

There is no limit on how deep you can navigate. The builder's autocomplete only suggests two levels at a time, so you can type deeper paths manually.

Each step into a related entity retrieves that entity from Autotask on demand, so a deep path can retrieve several entities. To keep this efficient, the system caches these retrievals for a short time. If you access the same related entity more than once in a workflow, it is retrieved from Autotask only once.

Picklist Values Resolve to Their Label​

Some properties hold a picklist value rather than the ID of a related entity. A picklist value is one of a fixed set of options on the field; it is not a separate entity, and nothing is retrieved from Autotask when you resolve it.

The builder still resolves the display label for you:

{{custom.ticket.Status}}       <!-- The status value (for example, 5) -->
{{custom.ticket.Status.Name}}  <!-- The status label (for example, Complete) -->

To understand the difference between a property that references a related entity and a property that holds a picklist value, see Understanding the Autotask Data Structure.