Browser Automation

From iMacros
Revision as of 10:54, 20 July 2010 by Mf (Talk | contribs)

Jump to: navigation, search

iMacros Automation

Many tasks you can automate using iMacros require multiple or regular execution, 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:

· Play (Loop) Button [All Editions]

· Shortcuts [All Editions]

· Command line interface and Batch Files [PRO and SCRIPTING Editions]

· Schedule Tasks [PRO and SCRIPTING Editions]

· Scripting Interface [SCRIPTING Edition] - Please see the Web Scripting Chapter

Play (Loop) Button iMacros Browser IE Plug-in Firefox


The Play(Loop) will repeat the macro up to the maximum loop number specified. 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

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

To create a shortcut:

· Locate imacros.exe. This is the iMacros Browser, typically located in C:\Program Files\iMacros.

· 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 following dialog will come up:

Shortcut Properties

· In the box Target you find an entry similar to C:\Program Files\iMacros\imacros.exe.

· Change this to "C:\Program Files\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 switches.

Command Line Interface and Batch Files iMacros Browser

Related example batch: Examples\Batch Files

The iMacros Browser (included in PRO and Scripting Edition) supports several command line options 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 ( 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 ...

A command line that starts the iMacros Browser, executes the macro called YourMacroName, and passes a value to the built-in variable !VAR1 looks like this:

imacros -macro YourMacroName -var1 Hello[SP]World!

After completing the macro the iMacros Browser automatically stops and closes. Note that in command lines you need to use the square brackets instead of the usual pointy brackets (< and >) to escape a whitespace ([SP]) or linebreak ([BR]). This is because > and < are used for file input/output operations on the Windows command line and thus the command would not execute correctly.

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 SEARCHSTRING into a search engine and presses submit. You can set the search value via the command line:

imacros -macro searchEngine -var_SEARCHSTRING iOpus[SP]iMacros

for setting more variables, you can simly add more -var_varname parameters:

imacros -macro searchEngine -var_SEARCHSTRING iOpus[SP]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 iOpus[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 is fully compatible with all standard task schedulers, including the built-in Microsoft Windows Task Scheduler.

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 iOpus 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 this from the Start Menu and clicking on Settings and then Control Panel to Scheduled Tasks.

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.

You can disable the Dialog manager in the option menu or inside the macro with SET !DIALOGMANAGER NO. By default, the dialog manager is active. If some dialogs quickly disappear during replay, it is because the Dialog manager closes them automatically.

Login iMacros Browser IE Plug-in Firefox

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

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

(Related example macro: Demo-Print)

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

Security Dialogs iMacros Browser IE Plug-in Firefox

Security Dialog

Security dialogs can occur on many secure web sites. 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

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 web sites 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 Save Page button and select the format from the iMacros Save As dialog. 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 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.


The value of the variable !EXTRACT is saved in CSV format.


A screenshot of the web page is saved.

Web Site Screenshot iMacros Browser IE Plug-in

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 insert a SAVEAS TYPE=BMP command into the macro like in this example (for the FOLDER and FILE settings see the documentation for the SAVEAS command):


The file format is the standard Windows Bitmap format (BMP). This file format can used with any image editor. Also, it can be compressed effectively with any ZIP compression tool or the Windows built-in "compress contents" option for folders.

iMacros Browser IE Plug-in FirefoxPlug-inThe screenshot feature is supported in all iMacros versions, but there is an important difference: The iMacros Browser takes full page screenshots but iMacros for IE only captures the visible area. Both iMacros Browser and iMacros for Internet Explorer support taking screenshots from Flash, Flex and Silverlight applets. iMacros for Firefox supports the PNG format, but currently only for standard HTML content.

Save Website Elements

iMacros can intercept file downloads and even download pictures and other elements from the web site 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

In iMacros browser
In IE plug-in

(Related example macro: Demo-ImageDownload )

To download an image (or any other specific web page element) switch to recording mode, navigate to the page and press Save Item in the iMacros Browser or Save Item As in the Internet Explorer Plug-In.

The item download preview opens in the tab on the left. Next, select the image or item in the web browser window. The selection is then displayed in the preview section. If you like the selection press ok. The item download manager automatically adds a TAG line to your macro, e.g.:


You can also create download tag lines 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 to the iMacros download directory (usually C:\Program Files\iMacros\downloads\). The items are taken directly from the web browser that displayed them; to save time and bandwidth they are not downloaded again. The naming convention for downloaded images is the same as for downloaded files, i.e. they consist of the original file name and a date and time tag. This also means you can use the ONDOWNLOAD command to specify your name for the downloaded image.

You can also download images using SAVEPICTUREAS. The command is named after the corresponding function in the Internet Explorer menu: "Save Picture as". You can right-click on any web page element to see if the web page element supports this feature; if it does iMacros can handle it automatically for you. To create such a command click on the element you would like to save during record and add "CONTENT=EVENT:SAVEPICTUREAS" manually to the generated TAG command. To control the location and name of the downloaded file use the ONDOWNLOAD command.

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 archieved 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.

Save Picture As

(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 via the HTML of the website but directly by simulating the Internet Explorer "Save Picture As" command. This can be an advantage on complex websites or websites where images are constructed "on the fly".

To use SAVEPICTUREAS 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:SAVEPICTUREAS" to the recorded 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 to not use it for URLs including the word "iopus" use


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


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 define a macro to play after an error. This can be done globally through the Error Handling tab of the Options Dialog, or with SET !ERRORMACRO yourmacro within a macro, which will override any global setting.

You could also decide to ignore errors with SET !ERRORIGNORE YES.

Related Example Macro: Demo-SetErrorMacro

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

General classification:

-1xx : Installation and Setup related error codes

-2xx: Errors during Macro recording

-3xx: Errors during Macro replay

-4xx: Errors specific to the IE dd-On

-8xx: Errors specific to the Firefox Add-On

A detailed list of error codes is available.