== 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|Web Scripting Chapter]]
=== Play (Loop) Button [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|Firefox]]===
[[Image:Repeat.gif|left|frame|]]
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 [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|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:
[[Image:Shortcut prop.jpg|left|thumb|150px|Shortcut Properties]]
· 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_Reference#Command_Line_Switches|command line switches]].
=== Command Line Interface and Batch Files [[Image:IMacros-icon.png|iMacros Browser]]===
Related example batch: Examples\Batch Files
The iMacros Browser (iMacros.exe) and the iMacros Sidebar for IE (iMacros.Sidebar.exe) included in the Standard and Enterprise Editions support several [[Command_Reference#Command_Line_Switches|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 (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|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 "iOpus 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=<nowiki>http://www.google.com/search?q={{keywords}}</nowiki>
For setting more variables, you can simply add more -var_varname parameters:
imacros -macro searchEngine -var_keywords "iOpus 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 [[Web_Scripting|scripting interface]].
=== Schedule Tasks [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|Firefox]]===
iMacros is fully compatible with all standard task schedulers, including the built-in Microsoft Windows Task Scheduler (please see [[Web_Scripting#How_to_run_iMacros_unattended|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 this from the Start Menu and clicking on Settings and then Control Panel to Scheduled Tasks.
For more information please see the [[Sample_Code#Task_Scheduler| Task Scheduler]] sample code chapter.
==Dialog Manager==
[[Image:Dialogs-overview-all-ie.png|thumb|300px|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 always enabled and active. ''If some dialogs quickly disappear during replay, it is because the Dialog manager closes them automatically.''
===Login [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|Firefox]]===
[[Image:Dialog-login.png|100px|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 [[#Security|here]].
===Javascript [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|Firefox]]===
[[Image:Dialogs-javascript.png|150px|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 [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|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.
Notes:
# 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.
# 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]].
# There are also other options to [[Web_Page_Dialogs|automate web page dialogs]].
===Print [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|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 [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|Firefox]]===
[[Image:Dialog-security.png|150px|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.
[[Image:Page_secure_and_nonsecure_items_security_dialog.png|150px|Secure and NonSecure Items Security Dialog (IE Only)]]
The [[Disable_Secure_and_NonSecure_Items_Warning_Message|Secure and NonSecure Items Warning Message]] is not handled by the Dialog Manager, as this is an optional message that can be [[Disable_Secure_and_NonSecure_Items_Warning_Message|disabled in the Internet Explorer (IE) settings]]. The IE settings also apply to the iMacros Browser.
===Certificates [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]]===
[[Image:Dialog-client-authentication.png|150px|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 [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|Firefox]]===
[[Image:Dialog-debug.png|100px|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 [[Web_Testing#Q:___Is_there_any_way_to_verify_if_any_javascript_errors_have_been_thrown.3F|Is there any way to verify if any javascript errors have been thrown?]].
==Saving Web Sites ==
(Related example macro: Demo-ArchivePage, Demo-SaveAs )
[[Image:Savepage.gif|frame]]
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 use to save the currently displayed web page. These options are
;CPL
:The complete web page is saved. The files and images are saved separately and stored in a folder.
;MHT
:The web page plus images are saved in a single file (Web Archive).
;HTM
:The web page source is saved with no images. If the page has frames all framed HTML pages are saved automatically.
;TXT
:Only the web page text is saved; all HTML tags are omitted.
;PNG
:A screenshot of the web page is saved. Use "Save Screenshot" to record this command.
;EXTRACT
:The value of the variable !EXTRACT is saved in CSV format. Use "Save Extracted Data" to record this command.
===Web Site Screenshot [[Image:IMacros-icon.png|iMacros Browser|]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|FirefoxPlug-in]] [[Image:Cr-icon.png|Chrome]]===
[[Image:Web-page-screenshot-entire-screen.png|frame|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|SAVEAS command]]):
SAVEAS TYPE=PNG FOLDER=* FILE=My_Screenshot.png
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 web site you are visiting.
====Download Files====
(Related example macro: Demo-Download)
[[Image:Dialog-download.png|thumb|150px|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 )
[[File:ImageExtract.png|left|thumb|250px|Use the image extraction wizard to create TAG commands for saving images from a website.]]
The typical use for [[SAVEITEM]] is '''automated image downloading'''. To download an image switch to 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 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 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 sceenshot" of the image instead. This has the advantage that it works with every image, but does download the original file. See [[SAVE_ELEMENT_SCREENSHOT]]
====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
TAG POS=1 TYPE=H2 ATTR=TXT:Online<SP>Store
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
TAG POS=1 TYPE=H2 ATTR=TXT:Online<SP>Store CONTENT=EVENT:SAVE_ELEMENT_SCREENSHOT
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:
TAG POS=1 TYPE=B ATTR=TXT:Open<SP>PDF<SP>Document
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:
TAG POS=1 TYPE=B ATTR=TXT:Open<SP>PDF<SP>Document CONTENT=EVENT:SAVETARGETAS
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 ==
[[Image:Proxy.png|frame|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 192.1.8.1 and the port number 8080. Since no bypass is specified the default settings are used.
PROXY ADDRESS=192.1.8.1:8080
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.
PROXY ADDRESS=http=192.1.8.1:8080<SP>https=192.1.8.2:8080 BYPASS=NULL
To use a proxy server at address 66.98.229.110, but to not use it for URLs including the word "iMacros" use
PROXY ADDRESS=66.98.229.110:8080 BYPASS=*imacros*
You can also use the same command, but with URL instead of IP address.
PROXY ADDRESS=imacros.net:8080 BYPASS=*imacros*
== 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#Error_Handling|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.
