Macro: Record and Replay Automated Actions

Macro is available in the Starter plan and above.

Table of Contents:

What is a Macro in Distill?
How to create a Macro?
How to use a Macro for monitoring?
How to use Macro actions after checks?
How to edit a Macro?
What are conditions in Macros
How to add conditions in Macro steps?
Steps and their descriptions
Troubleshooting & how to check if a Macro is working correctly
Need help?
Suggested reading

What is a Macro in Distill?

Macro allows you to record a sequence of actions performed on a web page. Some examples of webpage actions are scrolling, button clicks, or form-fill up on the page. Once you record the Macro, you can replay it on the webpage.

In Distill, you can use Macros in two ways:

For monitoring the desired section of the webpage, where the content displays only after the web page actions (button click, scroll, etc) are performed.
As a Macro action after Distill checks the web page for changes. When Distill detects a change in your monitor, Macro will replay the actions on the web page.

Use macros when the page URL doesn’t change after actions like submitting forms, sorting, filtering, logging in, or searching. Macros can replicate these actions, taking you to the desired page view.

You will need to follow two steps for monitoring webpages that need Macro:

Create a Macro that records the flow of actions on the web page.
Use the saved Macro and play it before monitoring the section on the web page.

Here’s a video tutorial with an example showcasing how to create a macro, record actions, and use it on a webpage monitor.

How to create a Macro?

You can create Macros from the web app or the browser extension.

Click on the “Macros” option from the hamburger icon. It will open the “Macros” page at https://monitor.distill.io/#/w/0/macros/.

A menu with Macro option

Enter the “Macro Name”, the “URL” in the respective placeholder and click on the “Add New Macro” button. It will open the URL in Distill’s remote browser.
Once the page loads, you can perform the web page actions to display the final content. You will also see the corresponding steps for each action in the right panel as shown below.
[Optional] Click on the “Replay” button to ensure that the correct flow of actions has been captured.
Click on the “Save” button to save the Macro.

The Macro list will open after saving a Macro and will show the newly added Macro.

How to use a Macro for monitoring?

You can use a Macro to make selections on a page for monitoring. This will work for both cloud and local monitors. To use it for a local monitor, you will have to change the device from the Option page or the Watchlist.

Here are the steps to use a Macro:

Click on the “Add Webpage” button from the Watchlist. Enter the URL and click on “Go”.
From the visual selector toolbar, click on the “Macro” menu option. It will show all the saved Macro for the URL. Select the Macro from the drop-down list.
Click on the play button for the Macro. This will play the recorded actions and reach the final page where you can make selections to monitor.
Once Macro finishes playing, turn “on” the selection mode to make selections. Save the selections.
You can configure the settings like check interval, device and others from the Options page and Save.

How to use Macro actions after checks?

Macro actions are available for a local monitor.

Create a Macro as explained above to record the actions on the web page.
Create a monitor for that web page by clicking on “Add Webpage” from the Watchlist.
Add the “Run Macro” action from the actions list. It is available in the Options window.

In this case, when Distill checks the monitor and detects a change, macro actions will trigger. It will open the web page in a new tab and replay the actions you have recorded in the macro.

How to edit a Macro?

You can edit, add, or delete a step for an existing Macro.

Navigate to the Macro list at https://monitor.distill.io/#/w/0/macros/.
Click on the “Open Recorder” button for the Macro that you need to edit.
Click on the “overflow icon” as shown below for a step and edit as needed. This opens up a menu with a drop-down.

You have the option to Replace, Insert Step Before, Insert Step After, and Delete the step.
The properties and values associated to the steps are editable by clicking on them. Once edited, click on the tick mark button.

6. Once done click “Save” to save the changes made to your Macro.

Edits saved will apply to all the monitors using this Macro.

What are conditions in Macros?

Within the steps in the Macro, you can add a Conditional block (IF…ELSE). It allows you to execute specific steps based on whether a condition evaluates to true or false. Its is similar to IF…ELSE structure in programming languages.

You can leverage Macro conditional blocks in several scenarios, including but not limited to:

Managing Intermittent Pop-ups: You can use conditional blocks to handle pop-ups that appear sporadically. If a pop-up is detected, the macro executes a specified set of steps; otherwise, it continues with an alternate sequence.
Ensuring Continuous Access: For pages requiring authentication, conditional blocks can automate the login process. This is especially useful if you’re monitoring a page and find yourself logged out.

Specifically, for local monitors tracking access to password-protected pages, you may encounter session timeouts that result in being logged out. In these instances, you can insert an IF…ELSE conditional block within your macro to check the login status. If logged out, the macro can automatically execute steps to log back in, preventing errors and ensuring continuous monitoring.

How to add conditions in Macro steps?

Steps to add if…else in the Macro recorder:

Click on the action where you want to add a condition. It will open a drop-down with a list. Select if…else.

IF block is added. Click the caret text to expand drop down that shows condition options.

Add logic with AND / OR and include your step in the body by clicking add statement.

There is a provision to “Add clause” in Macro steps. This gives you the ability to check for multiple conditions when each condition leads to a different outcome of steps. Follow these steps to add a clause with an ELSE…IF

Click on the overflow button and pick the option to Add Clause, before or after where ever applicable.

Adding a else-if block in macros conditions for handling multiple outcomes

You can club the ELSE…IF with an IF block when you are checking for multiple scenarios.

Handling multiple outcomes of steps using else-if clause

How to use Assert expression in the Macro recorder?

Assert expression is used for error-checking during the macros execution.

Use assert to verify the webpage’s expected behavior when the macro steps are being executed.
If an assertion fails due to any missing response to the step in the macro, it will raise an exception to halt execution of next steps.
Assert will error out the monitor with an error code E_ASSERT.

For example, verifying if a page exists before beginning to check any section inside it.

For this, use the “Assert” expression in the Macro steps to check if the page contains the text like “404” or “Page not Found”. If the page’s does contain this text, we will assert an error with the return text “Page does not exist”.

Using assert expression in the macro steps

When you run the monitor, and page is not found, the macro will assert an error and stop further checks from executing.

Steps and their descriptions

CLICK (click): Simulates a mouse click on a specified element, such as a button or a link, triggering any associated actions or events.
DRAG (drag): Replicates a drag-and-drop action by clicking, holding, and moving an element from one location to another within the browser.
FOCUS (focus): Sets the focus on a specified element, like an input field or a dropdown menu, making it the active target for user interactions.
KEYPRESS (keypress): Simulates a keyboard key press event on a focused element, such as typing a letter or pressing Enter.
MOUSEMOVE (mousemove): Mimics the movement of the mouse pointer over a specified element, triggering any related hover effects or events.
OPEN (open): Opens a specified URL in the browser, navigating to the desired web page.
SCROLL (scroll): Scrolls the browser window to a specified position or element, bringing the target into view.
SELECT (select): Selects an option within a dropdown menu or similar element, making it the active choice.
TYPE (type): Simulates typing text into a focused input field, such as a text box or search bar.
WAIT_DOC (wait_doc): Pauses the macro execution until the web page’s content is fully loaded.
WAIT_FOR_DURATION (wait_for_duration): Introduces a pause in the macro execution for a specified duration of time, typically in milliseconds.
WAIT_FOR_ELEMENT (wait_for_element): Waits for a specified element to become available on the web page before proceeding with the macro execution.

Troubleshooting & how to check if a Macro is working correctly

When you replay a Macro, the sequence of steps will execute and successfully executed steps will have a green check mark. If a Macro is working correctly you will see a green check mark against all the recorded steps.

Macros error out usually when:

The page didn’t load correctly.
The page loads correctly but the page is a new kind of the page that cannot be handled with current recorded steps.
The page loaded correctly but the elements’ identifiers used to build selectors have changed. The steps fail by not being able to locate the elements correctly.

If you encounter an error, you will see that the Macro does not proceed beyond the step that has an issue. If a monitor is associated to a Macro with an issue it will show an EMACRO error message. Click view details to learn more about the issue.

The check log will give you details of where the Macro playback failed and at which step. You can go back to replay the Macro and find out the step with issues and either edit or re-record the step.

Need help?

If you need help with a macro or have a URL that is not handled yet, feel free to contact us using our forum https://forums.distill.io/. You can explore existing discussions or post to get help on any topic.

For instructions on how to import, export, and edit macros on a webpage using JSON refer this video.