Automation

From iMacros
Jump to: navigation, search

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]


Play (Loop) Button

Repeat.gif

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

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

Related example batch: Examples\Batch Files

The iMacros Browser (included in Standard and Enterprise 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 (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 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. You can set the built-in variables !VAR1, !VAR2 and !VAR3 using the following switch:

imacros -var1 iOpus[SP]iMacros

With the command line switch -var_varname you can create your own custom variable. 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

If you want iMacros to read a value from the command line use the CMDLINE command in your macro.

CMDLINE !VAR1 http://www.iOpus.com/iim.htm 
SET !VAR2 nobody@nospam.iOpus.com 
TAG TYPE=INPUT:TEXT FORM=NAME:f1 ATTR=NAME:name CONTENT=Tom Tester!VAR1

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

Scheduled Tasks

To use the scheduling service on Windows 98, NT, 2000, click on the My Computer icon located on the Desktop. Then double-click on Control Panel to get to the Scheduled Tasks folder.

In Windows XP and Server 2003 you can access this from the Start Menu and clicking on Settings and then Control Panel to Scheduled Tasks.

Double-click Add Scheduled Task. Follow the instructions in the Add Scheduled Task Wizard. Select the Open advanced properties for this task for more set up options.




Command Line Runas

What you enter as the "Run" file could look like this:

"C:\Program Files\iOpus\iMacros\imacros.exe" -macro YourMacro -tray -loop 50

Important: The actual command must be inside quotation marks whereas the command line options must be placed outside.

Important: If you want your task to run even if no user is logged in, you must enter a user name and password in the "Run As" box.

Alternatively you can point to a Batch file or Windows Scripting (VBS) file that contains the specific instructions to start the software. Thus you can conveniently execute several commands in a sequence.

Control via the Scripting Interface

If you own the Enterprise Edition iMacros automatically installs the Scripting Interface. Using these powerful commands you can control iMacros with any Windows programming language that supports the use of COM objects.

Almost all Windows programming languages support this technology, including the free Windows Scripting Host, Visual Basic 6, Visual Basic .NET, C#, Java, Perl, Phyton, C++, ASP, PHP, ASP.NET. On the iOpus homepage [1] many examples for different programming languages can be found.

This Chapter will provide some examples of how to use the Scripting Interface. The examples will be using Visual Basic Script, Visual Basic .NET, starting iMacros from a web site, starting iMacros as a Windows Service, and running iMacros under a restricted user account such as in ASP/ASP:NET/PHP. On our web site we have tutorials for many other programming languages.

Example using Windows Scripting Host

Related example scripts: Examples\Windows Scripting Host

The Window Scripting Host interprets programs written in a language called Visual Basic Script, which is related to Visual Basic and the macro languages of the Microsoft Office package (VBA). Visual Basic Script files can be created and edited with any editor (e.g. Notepad), are executed by double-clicking them, and have the file ending .vbs.

The iMacros Browser is controlled from Visual Basic Script by calling commands of the Scripting Interface.

The following example creates an instance of the iMacros Browser, sets some variables, and plays a macro. The return value of the macro is then checked for errors. To run this example copy this text into a file with the ending .vbs, e.g. test.vbs. After double-clicking the file, iMacros will start in tray mode since in line 4 the command line switch -tray is activated. This means that an iMacros icon will apear in the system tray during replay. You can maximize iMacros by double-clicking this icon.

'initialize Scripting Interface
Set iim1 = CreateObject ("imacros")
i = iim1.iimInit() 

' setting variables
i = iim1.iimSet("-var1", "Tom Tester")
i = iim1.iimSet("-tray", "")

' displaying message
i = iim1.iimDisplay("This is a test")

' play macro
i = iim1.iimPlay("myfirstmacro")

' check success
If i > 0 Then
  s = "Everything OK"
Else
  s = iim1.iimGetLastError()
End If
MsgBox s

' exit iMacros
i = iim1.iimExit()

Example using Visual Basic.NET

Please see the VB.NET example projects that are included with the iMacros Trial version.

Intellisense Support

Related example scripts: Examples\Visual Basic

For full Intellisense support for all Scripting Interface commands in your .NET projects (C#, VB.NET, ASP.NET and others) or in Visual Basic 6.0, you need to add the iMacros interface (iimInterface.dll) reference to your project.

1. Here is how to do this in Visual Studio 2003/2005 (.NET)

Fig 1 Add a reference file
Fig 2 Select the iMacros Type Library component
Fig 3 Display all Scripting Interface commands with Intellisense











2. Here is how to do this for Visual Basic 6

Fig 4 Select the iMacros component
Fig 5 Display all Scripting Interface commands with Intellisense









Start iMacros from a Web Page

The following code example shows you how to start a macro from within a web page using Visual Basic Script and the Scripting Interface:

<html>
<head>
<SCRIPT ID=clientEventHandlersVBS LANGUAGE=vbscript>
</SCRIPT>
</head>
<body>

<a onclick=test() href="#">Click here to start script</a>

</body>
</html>

To test this code, simply save it as .HTM file and view it in your web browser. Make sure to allow the execution of scripting content on web pages.

In this example iMacros needs to be installed locally. It will run on the client. This is in contrast to the ASP example, where iMacros runs on the server (invisible to the user).

Start iMacros as a Windows Service

Windows Services is a topic for experts only. If you do not know what a Windows Service is there is a very good chance that you do not need this feature. If you are merely looking for a way to execute iMacros on a regular basis the Windows Scheduler will do the trick for you.

In the following we assume that you are familiar with the basic concept of a Windows Service.

You can start iMacros via any application that runs as a Windows Service - more information on services can be found here. The advantage of using a Windows Service is that the application can run even if no user is logged in. Due to a restriction enforced by Windows on services a service program can either be interactive (i.e. have a Console, read keyboard input, etc) or have network access - but not both at the same time. Since iMacros needs the ability to use the network more then user input you need to provide the user name and password of a normal Windows account.

If you use iMacros inside an application that runs as a Windows Service (as opposed to running under a regular user account) you need to provide a user name and a password:

There a two methods to do this:

(1) [Recommended]: Use "iimRunner.exe" to start iMacros under a regular user account (see the section on running iMacros under a restricted user account). This method is very easy to use and avoids all complications typically associtated with a Windows service

(2) Provide a password when you use iimInit:

int ret_code = iimInit( String command_line, boolean start_browser, String run_as_user, String run_as_password, String run_as_domain )

You can also provide the password encrypted. iMacros detects automatically if the password is in plain text or encrypted form. To encrypt your password record a macro where you enter the password into a password text field on a web page (with security settings to STOREKEY or TMPKEY) and then copy and paste an encrypted password.

Running iMacros as a Windows service does not affect the concept of a user session, because iMacros - while started by a service - effectively runs under the user account which you use in iimInit.

Running iMacros under a restricted user account (ASP/ASP.NET/PHP)

The problem of running iMacros from an ASP page is that by default all programs started by an ASP page have only the rights of the ASP user, which is a very restricted account. An ASP account is significantly more restricted than even the "Guest" user of a machine. However, iMacros needs at least the rights of a "Guest" account or "Limited account" in order to work correctly.

We created the "iimRunner.exe" method as a very easy and secure method to run iMacros from a very restricted user account such as the ASP.NET user account or a Windows Service.

Start the "iimRunner.exe" module inside the account that you want to use iMacros with. You can use for example the Windows task scheduler for this purpose: Select the option to start iimRunner.exe as soon as the computer boots.

Inside your script you only need to tell iimInit to use iimRunner to start iMacros.exe. This is done by adding the flag "-runner":

i= iim1.iimInit("-runner")

This is all that you need to do. Now the iMacros Browser can be controlled as before via iimPlay, iimExit etc.

As a special feature of iimRunner.exe it is possible to control the number of iMacros instances that are allowed to run in parallel. This is done by changing the MaxNumberOfInstances paramenter in the simple.config file located in the iMacros Program Files folder. If the max. number is reached iimInit returns a -7 error code.