Summary
"Get" is a type of step you can use when configuring Custom Automations
You use Get steps to retrieve data from a record related to the record in the Automation trigger or another step - so, for example, an End User could trigger an Automation, and then a Get step could retrieve its related Company
You use replacement codes to specify where the mapping reference is (e.g. the "companyId" field on the trigger record)
It's possible for a Get step to retrieve multiple records rather than a single record, but the associated Automations are typically more complex
You can use the data gathered from Get steps in subsequent Automation steps
Who is this article for?
Planhat Users who are building Custom Automations for their organization (e.g. Tech/Ops)
Article contents
This is a technical deep-dive article
Read on if you'd like to learn about Get steps - a type of step you can use when configuring Custom Automations. Ensure you read our article on Custom Automations before this one, so you are familiar with the context of where these Get steps can be used.
If you would simply like a general introduction to Automations, check out our overview article here.
What are Get steps?
A "Get" step is a type of action step that you can include when configuring a Custom Automation. (Get steps may be running "behind the scenes" in Templated Automations too, but they wouldn't be visible in the UI or configurable by you in that case.)
Click the image to view it enlarged
In a Get step you can retrieve either a single record (the most common setup you'll use) or multiple records:
You have the option to retrieve records from whichever model you like (see the model dropdown in the screenshot below) - as long as it's referenced in the trigger model/record of a previous step. So, for instance, in the example Automation screenshot at the top of this article, the trigger involves the Opportunity model, which has the system (default/custom) field "companyId", so when a specific Opportunity triggers the Automation, we can look at this field on this Opportunity record to identify the Company it's connected to, and retrieve the data of that Company. We discuss this topic in further detail in the "How" section below.
📌 Definitions
Model - Planhat data models are Company, End User, License, Opportunity, and so on. You can think of them as like containers for data
Record - data within those models - e.g. if Company is the model, then BMW, Microsoft and Nike could be records; and if End User is the model, then Katie Chambers, Jason Bendefy and Sally Peters could be records
Why use Get steps?
Get steps are used to retrieve related records (from related models) - they are how you can gather data in addition to the trigger record, to use in subsequent steps.
This is a bit easier to understand when we go through practical examples, so let's use the one in the example Automaton we saw earlier - here it is again (with the Get step showing in the configuration panel on the left-hand side):
Click the image to view it enlarged
What this Automation is configured to do is:
When an Opportunity record is updated with specific properties (e.g. the Opportunity to sell Module A to Company "Radleys" is marked as "lost")
Get the Company referenced in that Opportunity (in this case: Radleys)
And create a specific Task for that Company (i.e. an "Opportunity Review" Task associated with Radleys), and make the Owner of the Task the Owner of that Company (using data you retrieved from the Get step)
As you can see from the example, Get steps follow references between models/records - so in this case, because the Opportunity model/record contains a reference to the Company model/record, we can get the data for the linked Company record, and then use the data from that Company in subsequent steps.
Let's look at another example - this one has multiple Get steps:
Click the image to view it enlarged
In this example, what's happening in the Automation is:
When an End User record is added to a filter (e.g. the End User "Carolyn Booth" is assigned the Role "Champion" and so moves into the "Champions" folder
Get the Company record referenced in that End User record (e.g. the Company "Zoom")
Get the User record (user of Planhat - i.e. you and your teammates) that's referenced in the Owner field on that Company record (e.g. Louis Monet)
Get the User record (of Planhat - i.e. you and your teammates) that's referenced in the Co-Owner field on that Company record (e.g. Antonio Califano)
Post a message in a Slack channel, using all the information you have gathered (e.g. "Carolyn Booth from Zoom is now a Champion. The Company Owner is Louis Monet and the Co-Owner is Antonio Califano.")
Later in this article we also go through an example of an Automation where the Get step is for multiple records:
When the Co-Owner field on a Company record is populated or updated
Get all the Workflow records associated with that Company
Update all these Workflows with the Co-Owner
The Automation in that case is actually more complicated than it may seem in this summary - it involves a JavaScript function execution step and a Webhook step - so in general, if you can achieve what you want by a "Get a single" step rather than a "Get multiple" step, that would be preferred. We discuss this in more detail later in this article.
How to set up Get steps
When you are configuring (creating or editing) a Custom Automation (see here for general information on how to do this), you can select "Get" in any step after the trigger:
Click the image to view it enlarged
Once you've selected "Get", you choose whether you want the step to retrieve a single record or multiple records, and select which model you'd like to retrieve records from.
📌 Important to note
Remember that you should select a model that's referenced by the model in your trigger. For example, in the screenshot above, the model in the trigger - End User - has a field "companyId" that references the Company record that the End User record is linked to, so you can use this to "Get" the Company, as we describe below.
Getting a single record
📌 Important to note
"Get" steps work by:
Looking at a record that's been retrieved (in the trigger or a previous step, e.g. an End User)
Looking at a field on that record that refers to a different record (e.g. a field on the End User referring to its Company)
Retrieving that referenced record (getting the Company referenced by the End User)
As the Company model is central/top of the hierarchy in Planhat, with most other models relating to Company, you will most commonly find Get steps that reference Companies like this.
If you want to follow a link between models that don't have a built-in reference like this (e.g. if an Asset triggers the Automation and you want to "Get" its related Project), you will need to use a custom field (e.g. in this example, you'll need a custom field on the Asset model/record containing the associated Project ID).
📌 Important to note
You use a replacement code to specify which record you want to "Get" - how that record is identified. The code specifies whether your starting point is the model/record in the trigger or one retrieved in another step, and then which field on that model/record contains the reference to the other model/record you're getting.
For example, <<object.companyId>> is a very common replacement code used when getting a single Company - it says to look at the "companyId" field on the trigger model/record (which could be e.g. the End User that triggered the Automation) to identify which Company record is connected to that trigger record (e.g. that End User).
If you "Get" a record referenced in an action step (rather than a trigger), your replacement code will reference the specific step name, such as <<Step 1.owner>>.
Firstly, we're going to take the example of retrieving a single record (e.g. a single Company in the screenshot example above).
In the configuration panel, next to "id" (grayed out because it's mandatory - see the screenshot below), you should specify the ID of the record you want to retrieve, which is referenced on the trigger record, using the relevant replacement code.
In the example shown below, we use the replacement code <<object.companyId>>, which means the Automation will look at the record in the trigger (in this case, the End User that was added to the specified filter, e.g. Kerry Smith), and look specifically at the "companyId" system (default/standard) field on that record (which will contain a Planhat ID for a Company), and then "Get" the data for that Company record (e.g. Mars), including all its fields.
As this Automation's trigger is "added to a filter", you can actually see the whole trigger record in the "event details" in the Logs tab, including the field we are referring to in this replacement code:
As with other dynamic replacement codes, you need to refer to the field exactly (i.e. with correct spelling, capitalization and spacing), using the API name rather than the label name if it's a system (default/standard) field. As well as the logs event details shown above, you can check the field names in our API documentation and (in some cases) in the "Fields" tab of the "Data" Global Tool.
In the step example above, the replacement code starts with "object" because it's referring to the record in the trigger, but you can also refer to other steps in Get steps, meaning you can even get from a Get step! We can see this in the next step example:
Click the image to view it enlarged
In this Automation, we want the last step to be a Slack message that includes the name of the Owner of the Company. The Company retrieved in Step 1 (a Get step) has an "owner" field, but instead the the name, this field contains the Planhat ID of the User record ("User" being the model that represents users of Planhat - i.e. you and your colleagues), as shown in the screenshot below of Step 1 in the Automation logs - so that's not suitable for including in our Slack message. However, we can use the Company "owner" field to retrieve the User record in another Get step, including its system (default/standard) fields "firstName" and "lastName".
Because we are referring to the record retrieved in Step 1 (the Company) rather than the trigger record (the End User), we include "Step 1" in the replacement code rather than "object". We want to retrieve the User record whose ID is in the "owner" field of the Company record in Step 1, so our full replacement code that we use for the ID, as shown in the screenshot below, is <<Step 1.owner>>. Note that you have to state the name of your step exactly - so if your step is called s-Ujk, for instance, your replacement code would be <<s-Ujk.owner>>.
Looking at the logs for Step 2 - our User Get step - we can see that the system (default/standard) fields "firstName" and "lastName" have been retrieved for that User, as shown below.
You can view the rest of this Automation in our worked examples article - next, we do another very similar User Get step to retrieve the name of the Company Co-Owner, and then include all the gathered information in our Slack message that's the final step.
Getting multiple records
The examples above covered getting a single record per step. This is the simplest and most common type of Get step.
It is also possible to Get multiple records per step, like so:
However, these "multiple" Get steps are often substantially more complicated than "single" Get steps, involving JavaScript functions and webhooks. Let's take a look at an example.
Let's say you create a custom field on the Workflow model: "Co-Owner". You want an Automation:
that is triggered by the system (standard/default) Co-Owner field on a Company record being populated or updated,
and the desired outcome is that this new Company Co-Owner value is applied to all Workflows associated with that Company
For example, if my Company "Innova Biosciences" is assigned the Co-Owner "Bob" (a Planhat User), and this Company has the Workflows "Expansion" and "Customer Reference" in progress, then those two Workflows for Innova Biosciences will also be assigned the Co-Owner Bob.
So if we make this happen using a Workflow with a "multiple" Get step, what does it look like?
📌 Important to note
We show an example below, but as this is quite complex, we are not going to deep-dive into every detail. Please speak to your Technical Account Manager (TAM) if you would like to create an Automation like this.
You can click all these images to view them enlarged
The Automation trigger is when the Company Co-Owner field is populated/updated
Next we have the Get step
We have selected "Get multiple Workflows"
You can see that the next part (in "Search") is slightly different for "multiple" Get steps rather than "single" Get steps - here it's a "query" rather than an "id". We use the query
companyId=<<object._id>>in this case
The next step is executing a JavaScript function
The function is:
const workflows = <<Step 1>>
const company = <<object>>;
let workflowsWithCoOwners = workflows
.filter(workflow => workflow.percentDone != 100 && !workflow.isArchived) // Filter open workflows of type Project
.map(workflow => {
if (company.coOwner) {
return {
_id: workflow._id,
custom: {
"Co-Owner": company.coOwner
}
};
} else {
return {
_id: workflow._id,
custom: {
"Co-Owner": null
}
};
}
});
return workflowsWithCoOwners;Note that this refers to the specific Workflow custom field created ("Co-Owner") as well as the specific Get step name ("Step 1"); if your field or step was named differently, you would need to adapt the function
The final step is calling a webhook, using Planhat's API
Note that although the URL shown below is
https://api.planhatdemo.com/workflows, this is because this Automation has been built in a Planhat tenant on a demo cluster (ws.planhatdemo.com); the standard URL for a tenant onws.planhat.comwould behttps://api.planhat.com/workflows
Sometimes it may be preferable to use a similar Automation that Gets a single record as a simpler alternative to a more complex Automation that Gets multiple records. For example, we could potentially build the following Automation as an alternative to the "multiple" Get step example above:
Trigger: when a Workflow enters a filter
Using a Global Filter with the rule: Workflow associated with a Company where the Co-Owner field is populated (see screenshot below)
Notes:
This will only include Workflows associated with Companies that go from having no Co-Owner to having one assigned, rather than also including Workflows associated with Companies where the Co-Owner is changed from one User to another (so this is a difference from the previous example)
Filters don't typically immediately update/process, so you may find this Automation is not triggered immediately when the Company Co-Owner is assigned. (You can cause a Global Filter to process by going to edit it and resaving it)
You configure/manage Global Filters within the "Data" ("Data Model") Global Tool. You can learn about filter logic here
Next we have the "Get a single Company" step
We use the replacement code
<<object.companyId>>to say that we want to retrieve the data of Company referenced in the "companyId" field in the Workflow that triggered the Automation by entering the filter
The next step updates the Workflow by adding the Co-Owner from the retrieved Company into the custom "Co-Owner" field on the Workflow
Because we haven't renamed the first step in this example - it retains the automatically generated name of "s-jCj" in this case (as shown in the screenshot below) - we reference this step name in
<<s-jCj.coOwner>>
Therefore, if you are considering building an Automation with a "multiple" Get step, you should consider whether you could create something similar - and simpler - using a "single" Get step instead.