The renewal maintenance has officially ended for Progress iMacros effective November 30, 2023.
This Wiki site will also no longer be moderated from the Progress side.
Thank you again for your business and support.
Sincerely, The Progress Team
Difference between revisions of "iimRunner"
(27 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
(Related example macros: [[connect-to-iimrunner.vbs]]) | (Related example macros: [[connect-to-iimrunner.vbs]]) | ||
− | iimRunner.exe is | + | iimRunner.exe is part of the iMacros web browser scripting solution included with the Enterprise Edition. It helps you to '''start the iMacros, iMacros for Internet Explorer or iMacros for Firefox 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). | 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#Return_values|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? == | ||
+ | |||
+ | ''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 [[Web_Scripting#How_to_run_iMacros_unattended|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! | ||
+ | |||
+ | == GUI == | ||
[[Image:Iimrunner.png|thumb|center|250px|iimRunner Screenshot]] | [[Image:Iimrunner.png|thumb|center|250px|iimRunner Screenshot]] | ||
Line 13: | Line 27: | ||
'''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. | '''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!). | + | '''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 [[iimInit]] 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.'' | ||
+ | |||
+ | == Settings == | ||
+ | |||
iimRunner uses a small XML file called iimrunner.xml to store its settings: | iimRunner uses a small XML file called iimrunner.xml to store its settings: | ||
Line 31: | Line 55: | ||
'''LogLevel:''' INFO, ERROR (log only errors) | '''LogLevel:''' INFO, ERROR (log only errors) | ||
+ | |||
+ | == Log == | ||
+ | |||
+ | The log file is disabled by default. To enable it, assign an appropriate path and file name to the [[iimRunner#Settings|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. | ||
[[Image:Iimrunnerlog.png|450px|thumb|center|Among other information, the iimRunner log file displays the [[Windows Logon Types|Windows Logon Type]].]] | [[Image:Iimrunnerlog.png|450px|thumb|center|Among other information, the iimRunner log file displays the [[Windows Logon Types|Windows Logon Type]].]] | ||
− | Important: The tool expects the iimRunner.xml settings file in the same directory as iimRunner.exe. | + | '''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. | 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 == | |
+ | |||
*[http://forum.iopus.com/viewtopic.php?t=1439 Tips for using iimRunner] | *[http://forum.iopus.com/viewtopic.php?t=1439 Tips for using iimRunner] | ||
*[[Windows Logon Types]] - Overview | *[[Windows Logon Types]] - Overview |
Revision as of 12:14, 17 June 2016
(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, iMacros for Internet Explorer or iMacros for Firefox 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?
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!
GUI
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 iimInit 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.
Settings
iimRunner uses a small XML file called iimrunner.xml to store its settings:
<?xml version="1.0" encoding="utf-8"?> <configuration> <appSettings> <add key='MaxNumberOfInstances' value='50'/> <add key='LogName' value='d:\1tmp\runner.txt'/> <add key='LogLevel' value='INFO'/> </appSettings> </configuration>
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)
Log
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.
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
- Tips for using iimRunner
- Windows Logon Types - Overview
- How to run iMacros unattended
- How to use iimRunner from a batch file: Instead of starting imacros.exe directly, start a small VBS script that starts iMacros.exe via iimInit ("-runner").
- Use RunAs to test iimRunner
- Case Study: AlertFox - Award-winning web transaction monitoring service.