''"That's a world of difference - moving from simple linear scripts to complex conditional scripts that can essentially do anything."''
Mordechai S., Israel, Enterprise Edition User.
== Control via the Scripting Interface [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|Firefox]]==
[[Image:Imacros-web-browser-scripting-58.gif|thumb|350px|Fig: The iMacros Enterprise Edition includes a powerful web scripting component (API) that has been refined over many years.]]
The iMacros Enterprise Edition (and the [[trial version]]) automatically installs the [[Command_Reference#Scripting_Interface_Command_Overview|Scripting Interface]]. Using [[Command_Reference#Scripting_Interface_Command_Overview|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, Python, C++, ASP, PHP, ASP.NET. On the iMacros homepage [http://imacros.net] 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("name", "Tom Tester")
i = iim1.iimSet("age", "34")
' 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 ===
Related example scripts: Examples\Visual Basic
The following example is part of a Visual Basic project that creates an iMacrosBrowser instance, plays a macro, and checks for errors - this example assumes the existence of a function called void Log(String logString), which logs messages.
Imports Status = iMacros.Status
Public Class Form1
Inherits System.Windows.Forms.Form
Private m_app As iMacros.App
Private Sub startIMacros()
Const cmdTimeout = 60
Dim s As iMacros.Status
m_app = New iMacros.App
s = m_app.iimInit("", True, "", "", 5)
s = m_app.iimPlay("demo-extract", cmdTimeout)
If s > 0 Then
Log("Macro completed ok")
ElseIf s < 0 And s > -100 Then
Log("Interface problem: " + CStr(s))
Else
Log("Macro problem: " + CStr(s))
End If
s = m_app.iimExit()
End Sub
End Class
==== Intellisense Support ====
Related example scripts: Examples\C#, 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/2008/2010 (.NET)
[[Image:Project-addreference.png|center|thumb|150px|Fig 1 Open the Add Reference dialog]]
[[Image:Addreference-select-imacros.png|center|thumb|350px|Fig 2 Select the iMacros Scripting Interface component. For a 64-bit project, please select the 64-bit Scripting Interface (iimInterface64.dll) instead.]]
[[Image:Csharp intellisense.png|center|thumb|450px|Fig 3 Display all Scripting Interface commands with Intellisense]]
2. Here is how to do this for Visual Basic 6
[[Image:InternetMacros-Component.png|center|thumb|150px|Fig 4 Select the iMacros component]]
[[Image:Intellisense-vb.png|center|thumb|150px|Fig 5 Display all Scripting Interface commands with Intellisense]]
=== Connect Excel to the Web ===
The following demo shows you how to connect Excel to the Web using Excel VBA and iMacros:
1. [http://forum.iopus.com/_uploads/ExcelVBA-Part1.htm Create the Macro]
2. [http://forum.iopus.com/_uploads/ExcelVBA-Part2.htm Use VBA to connect to the Web Browser]
=== 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>
<nowiki><!--</nowiki>
Sub test()
Dim iim1, iret
MsgBox ("This example starts a macro from within a web page")
Set iim1 = CreateObject("iMacros")
iret = iim1.iimOpen()
iret = iim1.iimDisplay("Start Macro now")
iret = iim1.iimPlay("Demo\FillForm")
If iret < 0 Then
MsgBox iim1.iimGetErrorText()
End If
iret = iim1.iimDisplay("Done!")
iret = iim1.iimClose()
End Sub
-->
</SCRIPT>
</head>
<body>
<nowiki><p><a onclick=test() href="#">Click here to start script</a></p></nowiki>
</body>
</html>
To test this code, simply save it as .HTM file and view it in either IE or the iMacros 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.
We assume you read this chapter because you want to run iMacros 24x7 unattended.
In a nutshell: You can not run iMacros *as* a Windows service but you can run it '''*from*''' a Windows service!
You can start iMacros via any application that runs as a Windows Service. 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 than user input you need to provide the user name and password of a normal Windows account. Also, due to the new licensing scheme introduced with iMacros 10.1, it is not possible to launch iMacros from a Windows service running under the System account. The service needs to run under a regular user account that has already activated iMacros and has a valid license file associated with it.
If you use iMacros inside an application that runs as a Windows Service (as opposed to running under a regular user account) it is best to launch iMacros in a separate user account.
The recommended approach is to use the [[iimRunner]] tool (iimRunner.exe) to start iMacros under a regular user account (see the section on [[#Running_iMacros_under_a_restricted_user_account_(ASP/ASP.NET/PHP)|running iMacros under a restricted user account]]). This method is very easy to use and avoids all complications typically associated with a Windows service.
=== How to run iMacros unattended ===
'''Use the Windows Task Scheduler (batch or interactive mode?)'''
When a scheduled task runs without the user being logged into the machine, this is considered batch mode. This method works well for many macros and scripts. However, while basic features of iMacros work when run in a non-interactive session (batch mode), all web browsers and the plug-ins they use (Flash, PDF, Java, Silverlight, etc.) are not designed to run in this mode. They are only tested to work correctly under an interactive user session. Examples of such problems are that some dialog boxes do not open or display correctly, [[SAVEAS]] dialogs might not work, or Flash and PDF add-ons do not function correctly. You can get problems that are tricky to debug. Note that this issue is not related to iMacros, but is rather a problem with the web browsers and their plug-ins themselves.
For the best results, please run iMacros in interactive mode by selecting the "Run only when user is logged on" option in Task Scheduler. Of course, this means that you need to keep the user account under which the macro runs logged into the machine.
'''Start a User Session Automatically'''
To make sure the user session under which iMacros runs is restarted after a reboot, you can do the following:
''Option 1: Use Auto-logon (recommended)''
If your PC or server is in a secure environment (e. g. a data center) there is an easy method to create an interactive session: Enable Autologon. This will start up the session right after your PC is booted up.
Link: [http://support.microsoft.com/kb/324737 How to turn on automatic logon in Windows]
''Option 2''
When auto-logon is not an option, you can set up a [[How_to_Schedule_a_RemoteInteractive_Session|remote interactive session]].
'''Note:''' You can lock the desktop of the interactive user account, however, if you are using [[iimTakeBrowserScreenshot]] to take a screenshot of the the entire browser window, you also need to keep the desktop unlocked (see [[How to avoid black screenshots]]).
See also:
* [[Windows_Logon_Types|Windows Logon Types Overview]]
* [[Web_Testing#Q:_How_can_I_set_up_a_24_hours_a_day.2C_7_days_a_week_.28non-stop.29_operation_with_iMacros.3F|How can I set up a 24 hours a day, 7 days a week (non-stop) operation with iMacros?]]
* [http://forum.iopus.com/viewtopic.php?t=19859 Interactive session the easy way]
=== 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]] tool (iimRunner.exe) 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 [[#Start_iMacros_as_a_Windows_Service|Windows Service]].
''The recommended approach is to to start [[iimRunner]] in an interactive or [[Windows Logon Types|RemoteInteractive]] session.'' Such a session can be established automatically via Task Scheduler on any Windows PC or Server, so that the interactive session with iimRunner starts with a server reboot just like a Windows service. Therefore, using an interactive session has only advantages! Our tech support created a guide on [[How to Schedule a RemoteInteractive Session]]. For registered users we also have a demo server available and/or can assist you in the setup.
Once iimRunner is running in the (remote)interactive session, you can use iimInit ("-runner"), iimInit ("-runner -ie") or iimInit ("-runner -fx") to start the browsers inside of it. '''iimInit itself can be called from any user account, including a Windows service or the ASP.NET user!''' This is the same concept that is used by the [http://www.alertfox.com Alertfox Web Application Monitoring] service to run 1000s of imacros unattended.
This is all that you need to do. Now the browser and macros can be controlled as before via iimPlay, iimClose, 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.
'''Related forum post:'''
* [http://forum.iopus.com/viewtopic.php?f=14&t=1439&p=4118#p4118 Tips for using iimRunner]
== Error Handling ==
After each command the Scripting Interface returns a code. Values greater than zero indicate success, negative values indicate a problem.
The error codes returned on the batch and scripting level are the same codes that are displayed in the iMacros software itself. They allow a fine reaction on every possible problem iMacros can encounter.
Related Example Script: [[Combine-Macros.vbs]]
=== Scripting Interface Return Codes ===
Cf. [[Scripting_Interface_Return_Codes]]
== Send Email ==
There are three ways to send emails with iMacros:
1. iMacros can fill out an online form that sends the email, for example a form on your website similar to the [http://m2f.news.yahoo.com/mailto/?prop=news&locale=us&url=http%3A%2F%2Fnews.yahoo.com%2Fs%2Fap%2F20071029%2Fap_on_sc%2Fspace_shuttle&title=Astronauts+to+look+at+solar+wing+gears&h1=ap/20071029/space_shuttle&h2=T&h3=624 "Email this story"] link on Yahoo:
2. [[send-email.vbs|Use VBS to send the email]].
3. You can use a local command line SMTP mail sender. Using for example a batch file that executes the macro you could call the command line mail progam depending on the status of the macro execution.
== See Also ==
[[Macro or Script|How to decide between macro or script?]], [[Component|iMacros as Component for .NET]]
