From iMacros
Jump to: navigation, search

(Related example macros: connect-to-iimrunner.vbs)

iimRunner.exe is part of the iMacros web browser scripting solution included with the Enterprise Edition. It helps you to 'start the iMacros browser as well as iMacros for Chrome, Firefox, or IE under a specific user account. You find it in the iMacros home directory, typically C:\Program Files\Ipswitch\iMacros.

iimRunner must be (auto-)started directly within the user account under which you want iMacros run. The best method is to use a shortcut in the user's startup folder. iimRunner must not run as a service, and we do not recommend to start it as a scheduled task (as application that are started via task scheduler have no full desktop access, and web browsers need the desktop).

To run iMacros via iimRunner use the iimOpen ("-runner") flag. The special iimOpen error codes -6 (iimRunner not running) and -7 (too many iMacros instances) give you feedback in case something goes wrong during the browser start.


Why use iimRunner?

Some browser components, e. g. Flash or some AJAX features do not work correctly when they are run under a Windows service account (tricky permission issues etc). For these cases, we created the iimRunner application. If you want to see it this way, iimRunner is a workaround for browser specific issues, but certainly not for iMacros bugs. iimRunner solves these problems because it makes sure the browsers run under a normal user account - that is the only enviroment browsers are designed and tested for.

To avoid the problems from the start, we recommend to use iimRunner whenever you want to run automated web browsers unattended, so your service/ASP.NET/PHP code "talks" with iimRunner, and iimRunner controls iMacros, Internet Explorer, Firefox or Chrome.

For geeks: Worried about functions like LogonUser(), ImpersonateLoggedOnUser() and RevertToSelf()? The RunAs agent takes care of all that under the hood and makes sure the web browsers are run correctly. The RunAs agent includes our 10-year web automation experience in a compact C++ executable!


iimRunner Screenshot

The tool displays three values:

Account: The user account under which it is running. iMacros will start under this account if iimInit ("-runner") is used.

Created processes count: Counts how many instances of imacros.exe were started via iimRunner.exe. This count always increases, it does not show the actual number of running processes. This value is mainly useful for debugging.

Running iMacros count: Shows the number of running iMacros Browser instances (regardless if they were started manually or by iimRunner!).

Tip: You can (indirectly) query the number of running iMacros instances from your code. This way you can make sure you do not start more instances than your machine can handle:

  • Set the instance limit you need in the iimrunner.xml file (see below)
  • When the limit is reached, iimRunner will not start more instances and iimOpen returns the -7 error code.

As a rule of thumb, 2-5 iMacros (or IE or Firefox) instances per CPU core are a good value for average machines. For Amazon hosting (EC2 cloud computing) we found 2-3 iMacros instances per "Compute Unit" works well. Note that it is the browsers itself that consume all the CPU power, not the iMacros logic.


iimRunner uses a small XML file called iimrunner.xml to store its settings:

 <?xml version="1.0" encoding="utf-8"?>
       <add key='MaxNumberOfInstances' value='50'/>
       <add key='LogName' value='d:\1tmp\runner.txt'/>
       <add key='LogLevel' value='INFO'/>

MaxNumberOfInstances: Maximum number of allowed iMacros Browser instances (as counted by the "Running iMacros count" value in the iimRunner window.)

LogName: iimRunner log file name and path. No file name disables logging.

LogLevel: INFO, ERROR (log only errors)


The log file is disabled by default. To enable it, assign an appropriate path and file name to the LogName setting in the iimrunner.xml file.

Note: We do not recommend specifying the iMacros program folder for the location of the log file since versions of Windows after and including Vista do not allow programs to write to the Program Files folder and will redirect the output to an alternate location.

Among other information, the iimRunner log file displays the Windows Logon Type.

Important: The tool expects the iimRunner.xml settings file in the same directory as iimRunner.exe.

Note: Running iimRunner via a scheduled task allows it to run silently, and if iimRunner runs silently (different user account or windows sessions) the iMacros instances it starts run silently as well.

See Also