Summary
Accessing the logs: simply open up the automation and click on the "Logs" tab.
Failed vs. Successful Step Executions: failed steps will show in red and successful steps will show in green.
Basic Troubleshooting: make sure the automation is enabled and check to see if there are any executions listed in the logs, if there are none then the automation criteria haven't been met.
Who is this article for?
All Planhat users.
Anyone who will be involved in building and troubleshooting automations.
Series
Simple Automation Troubleshooting with Execution Logs ⬅️ You are here
Article contents
Introduction
If you're building new automations or managing existing automations then it's important that you know how to troubleshoot them. There are several reasons why you're automation might be failing/not running:
The automation criteria haven't been met.
There is a spelling mistake/syntax error.
An object isn't being referenced correctly e.g. <<object.companyId>>, <<object._id>>, <<object.cId>>.
The automation setup isn't quite right.
In this article, we'll detail the process of troubleshooting automations to help you swiftly get them operational! 🤖
Understanding Automation Execution Logs
The Execution Logs for both Templated and Custom automations are accessible via the "Logs" tab:
Custom Automation:
Templated Automation:
How They’re Structured
The logs are arranged in reverse chronological order (from most to least recent). Each execution is shown on its own line, with an exact timestamp of when the automation was triggered. To demonstrate these logs' structure, and how to interpret them, we use the following templated automation as an example:
General:
Logs:
Each execution can be interacted with independently, to obtain more information:
The Execution Row
Click on the execution row, this will generate additional context, showing the "Event details" and each execution step. The step will be colour-coded green if it was executed successfully by the automation, and red if it was not successful.
🚀 Tip
Since Templated Automations have Custom Automations running under the hood, they'll reveal all intermediate steps in their Logs, even though these steps are hidden when you configure the automation itself.
In this example, I can see that the trigger condition of my automation "Downgrade is logged" was met, triggering the automation, and that both the GET Step required to fetch the company and the task-creation step to create a task on that company, was successful.
Event Details
Clicking on "Event details" will provide full context on the exact event that resulted in this automation being triggered. The details are structured as a JSON, and are searchable using the usual "find" keyboard shortcut (CTRL+F / COMMAND+F):
automationId: is simply the ID of this particular automation.
companyId: is the ID of the object-related company.
eventId: is the ID of the specific event that triggered this automation (which you can read more about from the "update" expression.
update: is a nested expression which tells you what changed during the event that resulted in the automation. If the automation was triggered by a filter (as it is in the example below), the logs will provide you with a full list of the trigger object properties, rather than just the specific properties that changed and resulted in the automation being triggered.
In this example, I can see that the downgraded companyId is "5ec83e9dc9ae746a6b6e52ee", and everything else following this in the "update" section are simply properties of this particular Churn object, in particular with "onlyDowngrade" marked as "true".
Step Details
Clicking on any execution step (which will show in either red or green) will provide additional context (again, structured as a text-searchable JSON) on what the step intended to do, and whether it was able to do it successfully:
"success" will take a value either of "true" (if the automation step was executed successfully) or "false" (if the automation step was unsuccessful).
"params" is a nested expression which tells you what the event you configured is doing on the backend.
"data" is important here whenever an object's properties are being created or updated, since it provides the actual content of the automation execution.
"executionResult" provides a summary of what the execution was (if successful) and a summary of why the execution was unsuccessful (if it failed):
"data" deserves special attention here, since it will contain context on any associated error.
In this example, I can see that the first automation step was successful. Since it is a GET object step, the "executionResult" is simply the company related to the Downgrade that triggered the automation. This is a particularly long nested expression because the automation has pulled every property of that company.
I then see that the second automation step was also successful. The "data" expression shows me exactly what I specified in the General tab: we are creating a Task with the title "NRR Review", on the Company we just got in Step 1, etc.. And the "executionResult" expression shows us the entire task that was created (including all the object properties that we did not even specify through the template).
Now you know how to access and understand the most important parts of automation Execution Logs, let's take a quick look at how Failed step executions differ from Successful step executions.
Failed vs. Successful Step Executions
There are two key differences between Failed and Successful steps in Execution Logs:
1. Failed steps will show Red and Successful steps will show Green.
2. The "executionResult" will show the error context, nested within the "data" expression, for a failed step. Conversely, it will show the action it took, for a successful step.
Failed Step:
The "executionResult" tells us that this automation execution failed because the companyId it refers to actually doesn't exist in Planhat, which is something you can validate by going into the Data module, searching for a company with that Id, and seeing if any results come up.
Successful Step:
The "executionResult" tells us that this automation created a task, and lists all the attributes of that task.
Top Tips for Troubleshooting
The following are some quick approaches to try to self-diagnose and resolve any issues arising with your automations, before reaching out to our Support team, or your dedicated Technical Account Manager, who are always happy to help. 😊
Automation Not Triggering
If your automation isn't firing, there won't be any executions listed at all in the logs, even though you're sure that the automation should have fired, since its criteria were met. If this is the case, you should check carefully that your automation is triggered by the criteria you think it is, then reach out to Planhat Support, since the execution logs are no use, without any attempted executions.
Automation Not Executing Tasks
The execution logs become a powerful troubleshooting tool when you can see in the logs that an automation has been triggered, but that it hasn't successfully executed one or more steps. In this situation, using the knowledge you've gained above, you should:
Open up the failed Step(s), starting with the earliest failed step.
Review the "executionResult" portion of the step, with a particular focus on the "data" expression, for any description of the root cause (e.g., "companyId should refer to existing company", which implies that according to Planhat, the company specified does not exist).
Go back to the "General" tab of the automation, to modify the automation in light of this message.
Wait for the automation to be re-triggered, or manually trigger the automation by creating an event that matches the trigger criteria.
Review the status of the step:
If it has been successful, repeat Steps 1-5 until all failed steps have been resolved.
If it has not been successful, contact Planhat Support for further guidance.
🚀 Tip
While this approach is no silver bullet for solving automations that fail to execute as expected, it's a very efficient way to both 1) identify and resolve the root cause independently and 2) gather valuable context that will help our Support and Technical Account Manager teams solve failures quickly, or uncover potential bugs.