Difference between revisions of "Browser Automation"

From iMacros
Jump to navigation Jump to search
Line 288: Line 288:
  PROXY ADDRESS=imacros.net:8080 BYPASS=*imacros*
  PROXY ADDRESS=imacros.net:8080 BYPASS=*imacros*
[[Image:NGIM-icon.png|iMacros 2021.0]]'''Note:''' Please refer [[PROXY]] command to know further about the '''Proxy Server settings provided in iMacros 2021'''.
[[Image:NGIM-icon.png|iMacros 2021.0]] '''Note:''' Please refer [[PROXY]] command to know further about the '''Proxy Server settings provided in iMacros 2021'''.
== Error Handling ==
== Error Handling ==

Latest revision as of 11:29, 19 April 2021

iMacros Automation

Many tasks you can automate using iMacros require multiple or regular executions, like filling in an online form with many datasets or regularly downloading a status report. iMacros has several features to support this kind of automation:

Not all iMacros editions support all features. See Features Comparison.

Playback looping iMacros Browser IE Plug-in Firefox iMacros 2021.0

The Play button will repeat the macro up to the maximum loop number specified in the Repeat field. Note that you can set the !LOOP variable inside the macro, so it does not need to start at 1.

Shortcuts iMacros Browser IE Plug-in Firefox iMacros 2021.0

Instead of opening the iMacros Browser, marking the macro you want to play and then clicking the play button, you can create a shortcut to start iMacros and automatically run a predefined macro.

Shortcut Properties

To create a shortcut:

  • Locate imacros.exe. This is the iMacros Browser, typically located in "C:\Program Files\iMacros" (or "C:\Program Files (x86)\iMacros" in 64-bit systems)
  • Right-click on imacros.exe and select the "Create a Shortcut" option.
  • A new file called Shortcut to imacros.lnk will be created in the same folder. Select the file and right-click on it.
  • Select "Properties" and the left dialog will come up.
  • In the box Target you find an entry similar to "C:\Program Files\iMacros\Ipswitch\iMacros\imacros.exe".
  • Change this to "C:\Program Files\Ipswitch\iMacros\imacros.exe" -macro yourmacro -noexit. You must use quotation marks around the command.
  • Note: Do not change the path in the box "Start in".
  • Ready! You can now move this shortcut to a convenient place (like the Desktop) and start iMacros by simply double-clicking on the shortcut.

For a detailed explanation of the various command line options please see the section on Command Line Interface.

Command Line Interface (CLI) and Batch Files iMacros Browser iMacros 2021.0

Related example batch: Examples\Batch Files

Note: Not all iMacros editions come with the Command Line Interface, or accept command line switches/parameters. Please refer to the Features Comparison page to see if your iMacros edition supports it.

The iMacros Browser (iMacros.exe) and the iMacros Sidebar for IE (iMacros.Sidebar.exe) support several Command Line Interface that control the behaviour of the browser. Also, the browser can be called from batch files. Batch files are very simple programs that allow some structures the iMacro macro language does not support directly. Such structures include conditional programming (if...then...else...), loops (for...do...) and file input/output. They consist of a series of commands, can be created and edited by any editor (e.g. Notepad) and have the file ending .bat. Batch files can be started in the standard way, by double-clicking on the file, but also through the Scheduler (See the Schedule Tasks section on this page), which is a part of the Windows operating system by default.

Please note that file shortcuts can be looked at as simply a batch file that consists of only one line: the command line calling the program.

The most important part of a batch file that starts iMacros is the command line to start the browser. As mentioned before, this command supports several command line options that control the behaviour of the browser. The general command line syntax is

imacros -command_line_switch1 switch_value1 -command_line_switch2 switch_value2 ...

After completing the macro the iMacros Browser automatically stops and closes. To keep the browser open, use the -noexit switch.

You can now use batch files to conveniently execute several iMacros in a sequence:

echo Start iMacros batch file 
imacros -macro FormExampleMacro 
imacros -macro Check_Altavista 
imacros -macro Buy_Now! 
echo Done!

In the above macro, the batch command echo is used to print messages to the standard output.

Other important command line switches are those setting variables. With the command line switch -var_varname you can create your own custom variables. Imagine, you want to call a macro (searchEngine.iim) that enters the content of the variable "keywords" into a search engine and presses submit. You can set the search value via the command line:

imacros -macro searchEngine -var_keywords "Ipswitch iMacros"

Note that the name of the variable after the var_ prefix must correspond to the variable name used in the macro:

' searchEngine.iim
URL GOTO=http://www.google.com/search?q={{keywords}}

For setting more variables, you can simply add more -var_varname parameters:

imacros -macro searchEngine -var_keywords "Ipswitch iMacros" -var_date 05/06/2008

Check on the return value at batch level

The iMacros executable imacros.exe sets the predefined batch file variable ERRORLEVEL. The value is either 1 if the macro was completed successfully or negative if an error was encountered. ERRORLEVEL is used almost exclusively with a conditional construct, e.g.:

imacros -macro searchEngine -var_SEARCHSTRING Ipswitch[SP]iMacros
IF NOT %ERRORLEVEL%  == 1 ECHO Problem encountered

For more details please see the included example batch file Example-Errorlevel.bat.

Please note an important restriction here is that each call to iMacros runs in a separate browser that is closed when the macro finishes. This means you cannot have subsequent macros continuing from where the previous one finished. To have a macro login to a website and second macro loop through the site you need to use the scripting interface.

Schedule Tasks iMacros Browser IE Plug-in Firefox iMacros 2021.0

iMacros is fully compatible with all standard task schedulers, including the built-in Microsoft Windows Task Scheduler (please see this article for important tips about scheduling macros).

The Microsoft Task Scheduler is part of your Windows system. It "hides" in the "Control Panel" folder, which is located in the "My Computer" folder on your desktop.

By using Task Scheduler, you can schedule tasks such as iMacros or system tools like the Disk Defragmenter to run at a defined time that is most convenient for you. The Task Scheduler starts each time you start Windows and runs in the background, checking if any scheduled task is due. With Task Scheduler, you can schedule a task to run daily, weekly, monthly, or at certain times such as system startup.

You can access the Task Scheduler from the Windows Control Panel under Administrative Tools.

For more information please see the Task Scheduler sample code chapter.

Dialog Manager

iMacros handles all these dialogs

The Dialog Manager allows you to manage all those pesky dialogs that appear with Internet Explorer from time to time. Because the iMacros Browser emulates Internet Explorer the same dialogs appear in the iMacros Browser too.

Important: You can insert the ONDIALOG, ONLOGIN (etc.) dialog commands anywhere in the macro but it has to be before the TAG command that triggers the dialog.

The dialog manager is always enabled and active. If some dialogs quickly disappear during replay, it is because the Dialog manager closes them automatically.

Login iMacros Browser IE Plug-in Firefox iMacros 2021.0

Login Dialog

iMacros fills all login dialogs for you using the ONLOGIN command. The password is stored with the method you selected on the Security tab of the Options dialog. More details about the different password storage options can be found here.

Javascript iMacros Browser IE Plug-in Firefox iMacros 2021.0

JavaScript Dialogs (Related example macro: Demo-JavascriptDialog )

iMacros handles all Javascript dialog boxes for you using the ONDIALOG command.

You can even extract the text of a dialog by adding SET !EXTRACTDIALOG YES to your macro.

Web Page Dialogs iMacros Browser IE Plug-in

(Related example macro: Demo-WebPageDialog)

Web page dialogs are similar to Javascript dialogs, except they display HTML content. iMacros can control them using the ONWEBPAGEDIALOG command. Since web page dialogs can contain any number of buttons or boxes you can automate them by sending a specific list of keyboard commands to them. For example "KEYS=Hello{ENTER}{CLOSE}" will enter the word "Hello" on the dialog, press ENTER key and then close the dialog.

During replay "ONWEBPAGEDIALOG KEYS={WAIT<sp>2}{CLOSE}" is active by default to close unwanted ad dialogs.


  1. Web page dialogs are not normal HTML browser windows. Therefore they do not open in a separate tab but pop up in front of the current window.
  2. Web page dialogs are either modal or modeless. A modal dialog box must be closed before you can continue working with the rest of the web application. The ONWEBPAGEDIALOG can automate both types of web page dialogs. For modeless web page dialogs, you can use also use the DirectScreen Technology.
  3. There are also other options to automate web page dialogs.

Print iMacros Browser IE Plug-in iMacros 2021.0

(Related example macro: Demo-Print)

The dialog manager works with the print dialog. For more details please see the ONPRINT event, the PRINT and the PRINTPDF commands.

Security Dialogs iMacros Browser IE Plug-in Firefox

Security Dialog

Security dialogs can occur on many secure websites. The iMacros Dialog Manager automatically clicks the security dialog boxes so your macros are not interrupted. This is done using the ONSECURITYDIALOG command.

By default, the settings are BUTTON=YES and CONTINUE=YES. These settings are active even without an ONSECURITYDIALOG command in your macro.

Secure and NonSecure Items Security Dialog (IE Only)

The Secure and NonSecure Items Warning Message is not handled by the Dialog Manager, as this is an optional message that can be disabled in the Internet Explorer (IE) settings. The IE settings also apply to the iMacros Browser.

Certificates iMacros Browser IE Plug-in iMacros 2021.0

Certificates Dialog

Some secure web pages ask you to select a client-side certificate. The dialog manager can do this for you using the ONCERTIFICATEDIALOG command.

Page Errors iMacros Browser IE Plug-in Firefox

Error Dialog (Related example macro: Demo-OnError)

Page script errors can occur on many websites for a variety of reasons. The iMacros Dialog Manager automatically clicks the Internet Explorer error dialog boxes so your macros are not interrupted by script errors! This is done using the ONERRORDIALOG command.

By default, the settings are BUTTON=YES and CONTINUE=YES. These settings are active even without an ONERRORDIALOG in your macro.

For more details please see Is there any way to verify if any javascript errors have been thrown?.

Saving Web Sites

(Related example macro: Demo-ArchivePage, Demo-SaveAs )


iMacros automatically downloads and saves web pages for you. Use the Tasks drop down and select "Save Page", "Save Screenshot", or "Save Extracted Data". iMacros will then insert a SAVEAS command in the macro, holding information about the format and the location where the file is saved. The default location is in the downloads\ directory of your iMacros installation. This command is very easily tweaked after the macro has been recorded to fit your needs.

You have different options as to which format you wish to use to save the currently displayed web page. These options are

The complete web page is saved. The files and images are saved separately and stored in a folder.
The web page plus images are saved in a single file (Web Archive).
The web page source is saved with no images. If the page has frames all framed HTML pages are saved automatically.
Only the web page text is saved; all HTML tags are omitted.
A screenshot of the web page is saved. Use "Save Screenshot" to record this command.
The value of the variable !EXTRACT is saved in CSV format. Use "Save Extracted Data" to record this command.

Web Site Screenshot IMacros-icon.png IE Plug-in FirefoxPlug-in Chrome iMacros 2021.0

iMacros takes screenshots of the entire web page, no matter what length

(Related example macro: Demo-TakeScreenshot )

The iMacros Browser can automatically take screenshots of web pages. This includes the part "below the fold", i.e. iMacros takes the screenshot of the entire web page, no matter the length, even if it scrolls off-screen!

To take a web page screenshot, use the "Tasks" option "Save Screenshot" while recording a macro, or insert a SAVEAS TYPE=PNG command into the macro like in this example (for the FOLDER and FILE settings see the documentation for the SAVEAS command):


iMacros uses the standard, lossless PNG format. This file format can be used with any image editor.

Save Website Elements

iMacros can intercept file downloads and even download pictures and other elements from the website you are visiting.

Download Files

(Related example macro: Demo-Download)

Save Dialog handled by iMacros
Whenever a file download is initiated, Internet Explorer will present you with the dialog shown. This dialog allows you to select want you would like to do with the file. If you choose to save it it will also ask you for the file name and location.

Downloads are controlled by the ONDOWNLOAD command. It has two parameters that control the file name and the folder in which to save the file. It must appear before the macro command that starts the download.

Note: The general web page timeout also applies to downloads. So make sure that the timeout value is long enough to cover the complete download time. If needed you can also increase the timeout value manually inside the macro with the SET !TIMEOUT_PAGE command.

Save Item

(Related example macro: Demo-ImageDownload )

The typical use for SAVEITEM is automated image downloading. To download an image switch to a recording mode, navigate to the page and press "Extract Image" in the recording tab. The Image Extraction Wizard opens and whatever image you select from now on will be displayed on the preview. The proper TAG command, e.g.
TAG POS=1 TYPE=IMG ATTR=HREF:http://imacros.net/wp-content/uploads/2013/12/imacros-ipswitch.png CONTENT=EVENT:SAVEITEM 
will be automatically generated and, if you are satisfied with the final result, you can add the commands to the macro being recorded. You may also change the final folder location and file name.

You can also create download taglines manually. During recording simply click on the wanted item and add "CONTENT=EVENT:SAVEITEM" to the generated TAG line in an editor of your choice.

The downloaded files are copied from Internet Explorer cache to the iMacros download directory. Use the ONDOWNLOAD command to specify a name and location for the downloaded image.

Some websites use "tricks" to make image downloads tricky. But not for iMacros: You can also "take a screenshot" of the image instead. This has the advantage that it works with every image, but does download the original file. See SAVE_ELEMENT_SCREENSHOT

Use the image extraction wizard to create TAG commands for saving images from a website.

Save Element Screenshot

(Related example macro: Demo-ImageDownload)

This command is similar to SAVEITEM, which is the default command for image downloading. However, unlike SAVEITEM it does not access the image which was stored in IE cache but it makes a "screenshot" of the image element. This way the saved image is exactly the one displayed on the browser. This can be an advantage on websites where images are constructed "on the fly".

For elements of type IMG, you can use the Image Extraction Wizard to produce the right TAG and ONDOWNLOAD commands for using the SAVE_ELEMENT_SCREENSHOT by choosing "Take screenshot of image" as Method (radio button). However SAVE_ELEMENT_SCREENSHOT can be used on any element type, and in this case, you need to manually edit a recorded macro. Click on the element you wish to download and iMacros will produce a command like


This would simulate a mouse click on the link. Since this is not what we want we need to edit the macro and add "CONTENT=EVENT:SAVE_ELEMENT_SCREENSHOT" to the recorded TAG command. You will then have


The image files produced in this way are always in the PNG format. Use the ONDOWNLOAD command to specify the name and location for the downloaded image, however, you cannot change the image format, even you use a different file extension.

Save Target As

(Related example macro: Demo-SaveTargetAs)

To download any kind of web content such as .WVM or .AVI videos, sound files such as .MP3, or documents such as .PDF, first click on the link that connects to the item. In the case of a .PDF file such a link is typically called "Open document" or for a video file "Show video". iMacros records a TAG command:


This would simulate a mouse click on the link. This is not what we want, we need a command similar to the right-click command "Save Target As" in Internet Explorer. This can be achieved by editing the macro and adding "CONTENT=EVENT:SAVETARGETAS" to the recorded normal TAG command. You will then have:


The files downloaded in this way are copied to the iMacros download directory by default. You can use the ONDOWNLOAD command to specify the name and location for the downloaded image.

Proxy Server

Proxy Server

The PROXY command instructs the iMacros Browser to connect to the Internet through a proxy server by using the settings you specify. A proxy server acts as an intermediary between your internal network (intranet) and the Internet, retrieving files from remote Web servers. You can define a specific proxy server for each macro. Each running instance of the iMacros Browser can have its own proxy server.

If a proxy server is active the word "PROXY:" is displayed in the status bar.

The following examples show the general use of the PROXY command. E.g., this command uses a local proxy server for both http and https at the address and the port number 8080. Since no bypass is specified the default settings are used.


This command specifies two different proxy server for the http and https protocol. No bypass is defined so iMacros uses these proxy servers even for local addresses.


To use a proxy server at address, but do not use it for URLs including the word "iMacros" use


You can also use the same command, but with URL instead of IP address.

PROXY ADDRESS=imacros.net:8080 BYPASS=*imacros*

iMacros 2021.0 Note: Please refer PROXY command to know further about the Proxy Server settings provided in iMacros 2021.

Error Handling

iMacros can handle all errors that occur during replay. Since replay of macros can be achieved by different means the error management is different as well.

Macro level

You can decide to ignore macro errors with SET !ERRORIGNORE YES.

You can also perform sophisticated logic and generate an error condition using the EVAL command.

Batch file level

The variable %ERRORLEVEL% is filled after the macro is completed. Values greater than zero indicate success, negative values indicate a problem.

Related Example Batch File: Example-Errorlevel.bat

Scripting level

Please see the chapter on Web Scripting for sophisticated error handling via the Scripting Interface.

Error Codes

See Error and Return Codes

General classification:

-1xx: User interaction

-8xx: Errors specific to the Firefox and Chrome Add-Ons

-9xx: Errors specific to the Firefox and Chrome Add-Ons

-1xxx: iMacros Browser and IE plugin replay errors

A detailed list of Error and Return Codes is available.