Summary
Create a Custom Automation: to create a custom automation you will need to head over to the "Operations" module > "Automate" page, then click on the "+" icon in the top left-hand corner and select "Create Custom".
Automation Triggers: automations are incredibly powerful and they can be built to trigger off of any event that's related to any object in Planhat.
Automation Actions: when an automation is triggered, there are many actions that the automations can do, for example: creating and updating records, notifying users, sending a Slack message, calling a webhook, executing a function and more!
Custom automations are incredibly powerful, this article should provide you with a good understanding of what our automation capabilities are.
Who is this article for?
All Planhat users.
Any user that wants to create a custom automation.
Series
Custom Automations ⬅️ You are here
Article contents
Introduction
Automations in Planhat can be incredibly simple, or incredibly complicated; it all depends on what you need them to do for you. But, at the highest level, they're all the same; they perform specific actions instantly when specific firing criteria are met.
Custom Automations are much more versatile and flexible than Templated Automations, but they're still accessed just as easily from the Operations module. They allow you to unlock an unbelievable amount of power, ranging from building highly custom multi-step automations, all the way to custom JavaScript function executions, and even completely bespoke integrations using Planhat's Custom Integrations. But remember, this article is a starting overview of the custom editor, rather than a comprehensive guide: when it comes to your specific use case, your Technical Account Manager knows best.
🚀 Tip
Since these automations can be so flexible, a custom build process should always begin with a consultation with your Technical Account Manager, to ensure that the objective is clear and a Custom Automation is the best route.
How to Create a Custom Automation
To create a custom automation you will need to head over to the "Operations" module > "Automate" page, then click on the "+" icon in the top left-hand corner and select "Create Custom".
Custom Automations allow you to build sequential automations that can move and transform data in a thousand different ways. Furthermore, our automations are not just limited to moving data in Planhat, but also provide tools to move data to different systems and even execute complex functions outside Planhat!
📌 Important to note
Our Support and Technical Account Manager teams are always happy to help you define and troubleshoot Custom Automations. 🤓
Automation Triggers
Automations are incredibly powerful and they can be built to trigger off of any event that's related to any object in Planhat.
Events: events related to any Planhat object e.g. Company, End User, Workflow. Select whether the object should trigger the automation when:
Created
Updated
Deleted
Created or updated
Added to / removed from a filter
Apply a filter-style criteria, or apply an actual filter, to determine what should happen to the object for the automation to fire. The automation will fire on any object which transitions from not meeting to meeting the criteria, to meeting the criteria, while the automation is enabled.
🚀 Tip
There's no difference between implementing these criteria directly in the automation, or referencing an existing filter.
🚀 Tip
The "Has value" and "Has no value" operators allow you to trigger your automation to fire whenever an object property changes from:
Having no value to having a value (Has value).
Having one value to having any another value (Has value).
Having a value to not having a value (Has no value).
Incoming Webhook: a specific incoming webhook, simply copy the webhook URL and push events to it.
Scheduled: select days and times for the automation to fire on.
Automation Actions
When an automation is triggered, there are many actions that the automations can do, for example:
An object-related event:
Select how the automation should affect an object:
Create a new one.
Update an existing one.
Notify user:
Select whether to notify a user related to:
The object (team member field).
The related company (team member field).
Get: use Get steps to map from one object to another, this is discussed in more detail here.
Call a webhook:
Select the webhook URL to interact with. Then decide whether to:
GET (obtain) data from the URL.
POST (create) data to the URL.
PUT (update) the entire data on the URL.
PATCH (update) targeted pieces of data on the URL.
DELETE (erase) data on the URL.
Decide what data format to use for the URL interaction:
JSON
JavaScript
XML
x-www-form-URL-encoded
.csv
HTML
Plain Text
Use an integration: if you would like to set up a custom integration, please discuss this with your Technical Account Manager and Customer Success Manager.
Sending Slack message:
Select the Channel to send the message to.
Specify the message to send.
Execute function:
Write your expression within our JavaScript editor, to return a specific value.
Additionally, they can apply more advanced intermediate steps which...
Get a related object or set of objects (enabling cross-object automations, if the Project status is updated, update all Project-related Assets)
Select whether to obtain a single object or multiple objects.
Select the related object to GET.
📌 Important to note
Always speak to your Technical Account Manager or Customer Success Manager if you're interested in setting up a Custom Integration in Planhat for an Automation.
Key Components
There are three commonly used, but more technical, aspects to Custom Automations:
Replacement Codes
GET Steps
JavaScript Functions
We'll cover each in turn. 🤓
1. Replacement Codes
Replacement codes are an essential part of configuring Custom Automations. They allow you to place dynamic values, for example, a field on a certain object, or a URL pulled from an external system and are used in both intermediate steps (particularly for mapping IDs in GET Steps) and action steps, where they are used most commonly for populating fields with dynamic values. They're remarkably simple once you get the hang of them, but their notation can seem a little intimidating at first.
🚀 Tip
Typing in "<<" in any field in the Custom Automation editor will prompt a list of the available replacement codes. You can also use this notation when sending customised messages via automations. If you would like to learn more about that, check out this article!
Code Structure
Broadly, replacement codes follow the structure: "<<Part1.Part2.Part3>>" where each part is one of...
Part 1 (usually object e.g., <<object.Part2.Part3>>):
actor
The user or service that generated the trigger event.
automation
Properties of the current automation.
object
Properties of the trigger object.
oldDoc
The previous state of properties of the trigger object.
Step X
The execution result of previous steps (where X is the specific step number being referred to).
time
Relative time calculations.
update
Updated properties of the trigger object.
Part 2:
[empty]
If the property is a system property (field), there is no Part2 value.
Most commonly, this would be an ID e.g., <<object._id>>.
However, it can be any similar system field: <<object.name>> or <<actor.name>>.
custom
If the property is a custom property (field).
usage
If the property is a time-series metric.
sunits
If the property is a success unit.
lastTouchByType
If the property is a last touch date relating to different conversation types.
Part 3
name of property
The name of the specific property in question (e.g., "Use Case").
ID of metric
The ID corresponds to the metric being referred to (e.g., 63ab51c09c734c104d01f5871).
ID of object
The ID corresponds to a specific object (particularly used in GET Steps).
Code Examples
Replacement Code | Description | Examples |
<<actor>> | User or service that generated the trigger event | <<actor._id>> <<actor.type>> <<actor.name>> |
<<automation>> | A few fields describing the current automation | <<automation.id>> <<automation.title>> <<automation.createdBy>> |
<<object>> | Initial object (the object in the trigger expression) | <<object.name>> <<object.dueDate>> <<object.custom.fieldName>> <<object.usage.metricId>> <<object.sunits.metricId>> |
<<oldDoc>> | Previous state of initial object | <<oldDoc.name>> <<oldDoc.dueDate>> <<oldDoc.custom.fieldName>> <<oldDoc.sunits.metricId>> <<oldDoc.usage.metricId>> <<oldDoc.lastTouchByType.touchName>> |
<<Step>> | Provides access to the execution results of previous tasks. | <<Step 1.name>> <<Step 2.fieldName>> |
<<time>> | Relative time calculations | <<time.in a week>> <<time.in a month>> <<time.next Monday>> <<time.next month>> <<time.next working day>> <<time.now>> <<time.today>> <<time.tomorrow>> <<time.yesterday>> |
<<update>> | Updated fields of the initial object | <<update.name>> <<update.dueDate>> <<update.custom.fieldName>> |
2. GET Steps (Single)
"GET" steps are used for mapping from one object to another between the trigger and action portion of an automation, or between different action steps. For example:
Send a Slack message mentioning the company owner, when a company-related Asset is updated:
The trigger is on the Asset object; the action is in Slack but requires reference to a Company field.
Therefore, we have to use an intermediate "GET a single Company" step, to access the Company associated with the Asset, and then be able to access the Owner field from the Company object.
Update a Company field when Churn is logged:
The trigger is on the Churn object; the action is on the Company object.
Therefore, we have to use an intermediate "GET a single Company" step, to access the Company associated with the Churn.
Implementing a GET Step
Building a GET Step into your custom automation involves three key steps:
Add a GET single object Step to your automation just before you want to reference the related object (e.g., add a "GET a single Company" step if your trigger or previous step is not a Company, and you want to refer to one of its properties).
In the id field, within << >>, use a Replacement Code referring to the property on the previous object containing the Id of the related object to GET (e.g., the field on the Asset that contains the Company ID: <<object.companyId>>).
Refer to properties on the gotten object in the subsequent step(s) using a Step-based replacement code. Note that replacement codes:
Relating to the original object (here, Asset) is simply <<object.Part2.Part3>>.
Relating to other properties on the gotten object (here, Company) are of the form <<Step X.Part2.Part3>>.
🚀 Tip
Remember, you'll only be able to refer to a related object if there is some field on the initial object containing the related object's ID. Naturally, all objects are related to the Company object, but if for example, you want to refer to a Project related to an Asset, you'll need a custom field on the Asset level containing the associated Project ID.
🚀 Tip
See this article for how to use automation GET steps and Replacement Codes to populate custom messages.
3. Function Execution (JavaScript)
In more complex scenarios where Custom Integrations or sophisticated data transformations are required, you might need to execute a JavaScript function, which takes a series of inputs from a previous step or related object and transforms them, returning an output that can be used in subsequent steps.
📌 Important to note
The use of JavaScript from Custom Automations is a pretty advanced use case and not one we expect you to require or formulate regularly. Again, speak to your Technical Account Manager or Customer Success Manager before trying to implement a Function Execution step.
The Anatomy of a Function Execution
For Function Executions, we use:
Environment: Node.JS 12.x
Memory Limit: 128 MB
Time Limit: 10 sec
For easy handling of async code, we have implemented support of async/await, while for HTTP requests we have fetch external module.
Implementing a Function Execution step
Step implementation is extremely simple since a JavaScript function is only ever used to get values from a previous step, transform them, and return the transformed value. As such, just select "Execute Function" when adding a new automation step, and then type your JavaScript function (including << >> Replacement Codes where relevant) and ensure that you return a certain value which you can reference via a Replacement Code in a subsequent step.
For example:
We want to use the Execute Function to get results from the previous step, transform that data and pass the result to the next step:
const url = '<<Step 1.result.url>>';
const id = '<<Step 2.result.id>>';
const fullUrl = '${url}/${id}?format=json';
const fetchResponse = await fetch(fullUrl);
const userObj = await fetchResponse.json();
const result = userObj.results[0];
return{
randomUser: result
};