First Steps

From iMacros
Jump to: navigation, search

Starting iMacros

iMacros is distributed as a browser add-on for Firefox, Chrome, and Internet Explorer. Two of the commercial editions of iMacros (Standard Edition and Enterprise Edition) also include the standalone iMacros Browser, a derivative of IE with a command-line interface.

This article primarily covers interaction with the iMacros Browser, however, the concepts and interface are fairly consistent among all the different versions of iMacros. Throughout this Wiki, iMacros commands and functionality are are associated with browser icons (iMacros Browser IE Plug-in Firefox Chrome) to designate their applicability to a particular browser.

Internet Explorer Plug-in

After installing the software, a new iMacros icon appears on the command bar of Internet Explorer (IE).

iMacros in the IE Tools menu
Click this icon to start iMacros.

IE Command Bar Button.png

If you have already customized your IE command bar, you might need to manually add the icon or reposition it so it's visible. Please see this relevant FAQ for more on how to do this.

You can also start iMacros for IE by selecting 'iMacros Web Automation' from the IE Tools menu.

The iMacros Browser (Standard and Enterprise Editions)

To start the iMacros Browser, select the program from the Windows Start Menu, double-click the icon on your desktop, or navigate to the file "imacros.exe" (typically in C:\Program Files\iOpus\iMacros) and double-click it using Windows Explorer.

To become familiar with iMacros run the "FillForm" demo macro that is automatically installed. This demonstrates the basic features of iMacros in a straightforward way. It navigates to a test form, fills the form and submits it, then returns to the iMacros Website.

The iMacros Graphical User Interface

We have invested a lot of effort in making the Graphical User Interface of the iMacros Browser and the Internet Explorer add-on as intuitive as possible. This section explains the basic elements.

The Main Window

The main window consists of three parts: the menu and toolbar at the top, the iMacros sidebar on the left, and the browser window on the right. Web pages are displayed in the browser window using a tabbed interface just like other browsers. You control iMacros with the elements in the sidebar on the left.

iMacros Browser.png


The iMacros Sidebar

The iMacros sidebar is divided into two parts. The top half displays a tree view of all your macros when iMacros is stopped, and the current macro code when you are playing or recording a macro. Only files with an .iim or .iimx (obfuscated macros) extension in the Macros folder are recognized by iMacros. The Macros folder is specified in the Path settings of the iMacros Options. The default macro folder is located in My Documents under iMacros\Macros.

The lower half of the sidebar consists of three tabs: Play, Record, and Edit. As the names suggest, the Play tab contains controls for playing macros, the Record tab contains controls for recording macros, and the Edit tab contains controls for editing macros, changing options, and getting help.

Sidebar Pin.png
Tip: iMacros Browser You can auto-hide the sidebar by "un-pinning" it from the main window (just click on the thumb-pin icon to pin or unpin the sidebar), or you can move the sidebar outside the main window to a "floating" position, or dock it on the right, if you prefer. You can also hide the toolbar from the View menu. IE Plug-in The sidebar needs to be open in IE for iMacros to function.


Recording Macros

What's a Click Mode?

It is important to note that the primary way iMacros records your interaction with a web page is by recording your mouse clicks on the various web page elements. iMacros records these clicks as well as text entered into input fields on web forms and translates them into TAG commands. If you are entering and selecting values in a series of fields on a web form, you need to navigate to each field with the mouse and click into/on that field.

Note: Navigating through fields with the keyboard (i.e. using the TAB key) is not supported and will not be recorded.

Before recording, it is important to understand the different modes of recording that you can use. This is also known as the Click Mode. The three main click modes are Automatic, Expert (Use complete HTML tag), and DirectScreen. To select a click mode, use the ClickMode menu item or open the Click Mode Dialog from the main toolbar or Record tab.

Click Mode Dialog.png

Automatic

iMacros attempts to choose the best recording options (recommended in most cases for recording on HTML websites). In the automatic mode iMacros looks at the different attributes an element has (such as ID, NAME, Text, HREF, etc.) and selects the one attribute it thinks fits best (for details, please see the "For advanced users" description). Note that the automatic mode never switches to Expert or DirectScreen mode. If you need these recording modes, please select them manually.

Expert

This mode is for advanced users: iMacros does not select just one attribute as in the automatic mode, but instead creates a TAG command that consists of all attributes of the clicked HTML element. The purpose is to give the user a quick overview of all of the element's attributes. Typically the user will use such a TAG command as a starting point, and then delete the attributes that should not be used. Often this is more convenient than building such a TAG command manually.

X/Y Firefox

iMacros for Firefox provides this mode for identifying elements by their position on the web page. This can be useful if the name and URL of the item you want to click on changes dynamically from visit to visit. It should also be used if the web page element is embedded in JavaScript and iMacros can not find the recorded name during replay because it was created "on the fly" by JavaScript. For more information on this mode, see the CLICK command.

DirectScreen

This is the ultimate solution if everything else fails. It simulates standard mouse clicks and movement within the browser window. This feature works with all web pages. For non-html elements such as Flash or Silverlight, you must use the DirectScreen mode. DirectScreen is only available in the iMacros Browser and iMacros for IE commercial editions.

Image Validation

Image validation (the IMAGECLICK and IMAGESEARCH commands) combines the power of DirectScreen with computer vision. To use it, open the Image Validation Wizard. For more details please see Image Recognition.


Image Validation Wizard: Use it to create the IMAGECLICK and IMAGESEARCH commands.

Changing Modes

Show Click Mode Dialog Button.png

In most cases you will record your macros using just one click mode, but you aren't limited to just one click mode per macro. In fact, you can mix the modes in a single macro by changing the click mode while you are recording! This is useful if you encounter problems while attempting to record one or more elements on a web page: simply switch to a different click mode and try clicking the element again.

You may also have to change click modes if you notice that your recorded commands are not playing back successfully. In this case try selecting a different click mode and re-record your macro.

To record a macro

Record Button.png

To start recording a macro, select one of the following methods:

  • Click the "Record" button on the Record tab of the iMacros sidebar
  • Click the "Record" button on the toolbar.
  • Press Ctrl+F5.

Now simply perform whatever tasks you wish to record, such as surfing to web sites, filling out forms, making a test order on your e-commerce site or any other task of your choosing.

After you have finished recording press "Stop". The current recording is automatically saved as a macro named "#Current". Press "Save Macro As..." to save it as a different name, or right-click the macro in the macro list and select "Rename".

Hints for successful recording

  • Select elements to record by clicking them with the mouse (don't use the TAB key to navigate through fields).
  • During recording do not use your browser's Back or Forward button or change the address line. Use the buttons supplied by iMacros instead (iMacros Browser and IE add-on only).
  • Recording "Clicks". If a macro generates an error during replay you can experiment by selecting the link recording option (Click Mode) manually from the dialog after clicking Click Mode.
  • Because the iMacros recording language is fully documented it is easy to edit and "tweak" the macro manually after recording!
  • The iMacros Standard and Enterprise Edition licenses include free Silver Level tech support, so our support team is ready to help you with your project and any recording issues that you might encounter.

Related animated tutorial: Recording a macro

Note: The relationship between a recorded TAG command and the actual web page HTML code is fully documented. There is also an example page to test the iMacros recording. Advanced users can use this documentation to manually created TAG commands based on the HTML source of the website and/or have a program generate the iMacros macro commands.

Playing Macros

Play Toolbar Button.png

To play a macro, first select the macro in the macro list and then choose one of the following methods:

  • Click the "Play" button on the toolbar.
  • Click the "Play" button or on the Play tab of the sidebar.
  • Simply double-click the macro in the list.
  • Press the F5 key.
During playback a blue frame shows you which parts of the web page are being manipulated. To play a recorded sequence multiple times, fill in the Max. number of times to repeat the macro and press the "Play (Loop)" button.
Play Loop.png

Controlling playback speed

There are two different options that affect the speed at which macros are replayed. These can be set in the General tab of the Options dialog as well as within the macro with the !REPLAYSPEED variable.

The first option is the replay speed, which can be set to three different values:

  • FAST: the macro is replayed at maximum speed (Recommended in most cases).
  • MEDIUM: iMacros waits for 0.25s between each command.
  • SLOW: iMacros waits for 1s between each command.

The second option is to add timing information during recording (DirectScreen click-mode only). If the "Add timing information" checkbox is checked in the Click Mode Dialog, then WAIT statements are automatically included in the macro. Thus, during replay these WAIT statements slow down the macro playback.

Of course, you can also always manually add WAIT statements to your macro to further control the speed.

Errors during replay

We work hard to make iMacros as "intelligent" as possible, but it still is not as smart as you. If an error occurs during replay it is mostly due to a "tricky" web page in which one of the automatic suggestions of the iMacros Recorder failed. In almost all cases re-recording the macro with different settings or manually editing the macro solves the problem. For recording tips please see the Recording section and for information on how to edit your macro go to the Editing Macros section.

Related forum posts:

See also:

Tip: If you want to prevent the blue frame from being drawn around tagged elements during playback, add the following statement to your macro:

SET !MARKOBJECT NO

Editing Macros

Edit Macro Button.png

(Related example macro: FillForm)

All recorded macros are stored as a plain text file with the an .iim extension in the folder specified by the "Folder Macros" setting on the Path tab of the Options dialog. The default macro folder is located in My Documents under iMacros\Macros.

You can manually edit and tweak the macros using any text editor you like, for example Notepad, which is shipped with the Windows operating system by default.

To open a macro, first select the macro in the macro list and then choose one of the following methods:

  • Click the "Edit Macro" button on the toolbar.
  • Click the "Edit Macro" button on the Edit tab of the sidebar.
  • Right-click the macro in the list and select "Edit macro".
  • Press the F9 key.

The editor specified by the "External editor" setting on the Path tab of the Options dialog (iMacrosEditor by default) will open and display the macro - in this example we chose the FillForm demo macro:

iMacrosEditor.png

As a simple edit step, let's change the content of a form text field now. To change the Name below from "Tom Tester" to "Dr. A. Award" locate the TAG command that contains "Tom Tester" and change is as shown below:

Old:

TAG POS=1 TYPE=INPUT:TEXT FORM=NAME:f1 ATTR=NAME:n1 CONTENT="Tom Tester"   

New:

TAG POS=1 TYPE=INPUT:TEXT FORM=NAME:f1 ATTR=NAME:n1 CONTENT="Dr. A. Award" 

If the value of the CONTENT parameter contains spaces, you must either:

  • Enclose the value in double-quotes
  • Replace all spaces in the text with <SP> and substitute all newlines with <BR>, e.g. CONTENT=Dr.<SP>A.<SP>Award. (Related forum post).

After you save the changes to the file, iMacros will immediately apply them during the next replay of the macro.


Next Steps