iMacros Javascript Scripting Interface

Automate complex tasks: iMacros commands refer to web page elements, so any programming logic must be put into a script that then uses iMacros to automate the website. For this purpose iMacros for Firefox contains a built-in Javascript Scripting Interface, which runs directly inside the browser.

The following information focuses on this built-in Javascript Scripting Interface. Supported commands (see below):

Note that the syntax of the regular, commercial Windows Web Scripting Interface and the built-in Firefox Javascript Scripting Interface is identical (unless where explicitly noted). Therefore they use the same documentation.

By default each Javascript step is shown during replay. This option is useful for testing and debugging, but it slows down the Javascript execution artificially. To run Javascript at its normal (very fast) speed please uncheck this option.

Javascript code running inside iMacros. The the//imacros-js:showsteps yes/no comment at the top of your Javascript file (including the //) overrides the global setting of “Show Javascript” checkbox in the option dialog.

Javascript examples.png
Examples: iMacros for Firefox automatically installs the SI-Send-Macro-Code.js - View Script Source Code:


Sample Javascript script for use with iMacros for Firefox.

 /*Simple send code example */
 var MyMacroCode
 var jsNewLine="\n"
 MyMacroCode = "CODE:"
 var i
 MyMacroCode = MyMacroCode+"URL GOTO=" + jsNewLine
 MyMacroCode = MyMacroCode+"URL GOTO="
 iimDisplay("Send Macro via iimPlay")
 /*Some different ways to do looping*/
 iimDisplay("For Loop")
 for (i = 1; i <= 2; i++)
   iimPlay("CODE:URL GOTO="+i*10)
 iimDisplay("While Loop")
 var i=1;
 while (i<=2)
   iimPlay("CODE:URL GOTO="+i*100)
 iimDisplay("Do...While Loop")
 i = 1;
   iimPlay("CODE:URL GOTO="+i*1000)
 while (i <= 2)
 /*Howo to generate a random wait time*/
 var mydelay
 /*Generate a number between 1 and 10*/
 iimDisplay("Random wait t="+mydelay)
 MyMacroCode = "CODE:"
 MyMacroCode = MyMacroCode+"URL GOTO=" + jsNewLine
 MyMacroCode = MyMacroCode+"WAIT SECONDS=" + mydelay + jsNewLine
 MyMacroCode = MyMacroCode+"URL GOTO="
 iimDisplay("Script completed.")

Important: iMacros macros must have the “.iim” file extension and Javascript scripts must have the “.js” file extension.

Note: Firefox can be remote controlled by the regular iMacros Scripting Interface via iimInit (“-fx”). The Javascript Scripting Interface does not include iimInit and iimExit, because they are not required. The Javascript runs inside the browser. The regular iMacros Scripting Interface is now available for Linux. It allows you to remote control Firefox and Chrome via Python.

Running multiple iMacros js scripts simultaneously

If you need to run more than one js script in iMacros for Firefox at the same time, you have to use a different Firefox profile for each script and make sure each opens as a different process.

Scripting Firefox

Mozilla Firefox, the complete browser, can be scripted with the commercial iMacros Enterprise Edition (= iMacros Scripting API). So while the free Java scripting runs inside Firefox, the API allows you to control Firefox from external software (C++, C#, Python, Perl,…). For details, see the chapter with the iimOpen command.


Displays a short message in the iMacros browser. A typical usage would be to distinguish several running iMacros Browsers or display information on the current position within the script.


int ret_code = iimDisplay ( String message [, int timeout] ) 


  • String message
    The message that is to be displayed in the iMacros Browser
    #HIDEDISPLAY# – hides the message box
    #KIOSKMODE# – enables kiosk mode
    #KIOSKMODEOFF# – disables kiosk mode
  • int timeout
    The optional timeout value determines when the Scripting Interface returns a timeout error if the command is not completed in time. The default value is 10 seconds.


Visual Basic Script example:

Dim imacros1, imacros2, iret 

Set imacros1 = CreateObject("imacros") 
iret = imacros1.iimInit() 
iret = imacros1.iimDisplay("This is the 1st iMacros Browser")   

Set imacros2 = CreateObject("imacros") 
iret = imacros2.iimInit() 
iret = imacros2.iimDisplay("This is the 2nd iMacros Browser")

In iMacros for Chrome, if the sidebar is not available (e.g. if you start the browser from scripting interface API or run macros from bookmarks menu)errors and iimDisplay() messages are shown in a desktop notification pop-up window.


Defines variables for use inside the macro and assigns values to them. There are limitations as to what variables you can set using this command. You can set all built-in variables which you also can set via the command line. Additionally, you can set all user defined variables. After iimPlay all variables are erased. The return code is always 0.


int ret_code = iimSet ( String VARNAME, String VARVALUE )


  • String VARNAME
    A string defining which variable is to be set. The variable is created by iimSet. It does not have to be defined somewhere. Use VARNAME to create a user defined variable named {{VARNAME}} (case insensitive). Note: You can not use any of the built-in variables with iimSet.
  • String VARVALUE
    The value which is to be assigned to the variable.
    In contrast to TAG commands, blank spaces must not be replaced by <SP>. iimSet() takes care of that.


Loop over a number, for example to extract one table element after the other

Dim imacros, iret, i 
Set imacros = CreateObject("imacros") 
iret = imacros.iimInit() 
For i=0 To 4  
  ' You have to convert the value into a string! 
  iret = imacro.iimSet("myloop", CStr(i)) 
  iret = imacros.iimPlay("mymacro") 

Note that variables defined with iimSet lose their values after each iimPlay. This is by design. If you want to use the same variables and values in another macro, you need to use iimSet again:

iret = imacro.iimSet("greeting", "hello") 
iret = imacros.iimPlay("1st-macro") 
iret = imacro.iimSet("greeting", "hello") 
iret = imacros.iimPlay("2nd-macro")

See Also

Related forum posts:


Plays a macro. After the macro has played all options that have been set with the iimSet command are reset. Use iimGetLastExtract to get the extracted text. Upon the next iimPlay() call, internal variables like !TIMEOUT_PAGE and !EXTRACT for instance, will also be reset to their default values.

There are two fundamentally different ways of playing a macro using the iimPlay command. The first is to specify the filename (without the extension) of the macro in the String macro parameter. The other is to generate macro code on-the-fly in your program, preceded by “CODE:”, and pass it directly to iimPlay via the String macro parameter (see note below).


int ret_code = iimPlay ( String macro [, int timeout] )


  • String macro
    Either the macro’s filename without the extension, a string holding macro commands or the macro code.

(1) iimPlay (“demo-download”) – If you just supply the macro name, iMacros looks for the file in the standard macro folder (as specified in the Options dialog).
(2) iimPlay (“c:\MyMacros\macro1.iim”) – Full path*
(3) iimPlay (“Test\macro1″) – Relative path* to the iMacros Macros folder
(4) iimPlayCode (“URL GOTO….”) (old: iimPlay (“CODE:URL GOTO….”) => Code Example, Tips: see note below.

* Backslashes in the path need to be escaped when using Javascript or any other language that requires backslashes in paths to be escaped.
For example: “c:\\MyMacros\\macro1.iim”

  • int timeout
    The optional timeout value. If iimPlay does not return before this time span, the Scripting Interface returns a timeout error -3. No extraction data is returned in this case. The default value is 600 seconds. This is the timeout for the overall macro runtime. This value should not be confused with the several timeouts inside a macro. The iimPlay timeout is typically triggered by a browser crash, a browser freeze or if the macro runtime exceeds this value.

Error Handling

iimPlay returns a detailed error code for every problem encountered. Please see the Scripting Interface Return Codes and the general iMacros Error-Codes, which are transmitted via the iimPlay command back to the calling application.

The return codes of iimPlay can not only be used to deal with “big” issues such as web browser crashes etc, but are often simply used to react to missing elements on a website. So if an element is not found on a website, and then the TAG command reports an error, and iimPlay returns this error to the script. Example: If you extract book ISBN numbers, some books may not have an ISBN number and the TAG command reports a “not found” error.

The error codes of iimPlay are exactly the same that you get from the iMacros Browser/IE/Firefox itself. In addition, there there Interface specific error codes that deal with unexpected errors timeouts or browser crashes.


Play a macro located in the Macros\ directory of your iMacros installation (Visual Basic Script example):

Dim imacros, iret 
Set imacros = CreateObject("imacros") 
iret = imacros.iimOpen() 
iret = imacros.iimPlay("mymacro") 

Play some on-the-fly generated code (Visual Basic Script example):

Dim imacros, iret, mycode, myURL 

myURL = ""  

mycode = "URL GOTO=" + myURL + vbNewLine 
mycode = mycode + "TAG POS=1 TYPE=FONT ATTR=TXT:<SP><SP>Online<SP>Store" 

Set imacros = CreateObject("imacros") 
iret = imacros.iimOpen() 
iret = imacros.iimPlayCode(mycode)


Relative path

  • You have the option to use the relative path to the iimPlay command. For example, if your macro is in a subfolder “test” of the iMacros Macros folder, you may use iimPlay(“test\yourmacro”). The same is valid for the iMacros for Firefox built-in Javascript Scripting Interface.


  • The recommended method for playing a macro generated-on-the fly is to assign the entire macro to a single string and then use one call to iimPlayCode to play the macro. While it is possible to use multiple calls to iimPlayCode to play each line of your macro separately, keep in mind that each time you call iimPlay or iimPlayCode, all of the iMacros internal variables are reset, and this can produce undesired results if you call each line of your macro this way.
  • Several commands in a macro generated on-the-fly must be separated by the CR (carriage return) symbol. These are vbNewLine or vbCrLf in Visual Basic or \r\n in C, C++ or C#.
  • iimPlayCode is not yet supported in iMacros for Firefox. Please continue to use iimPlay(“CODE:…”) instead.
  • Use the iMacros Editor “Code Generator” (in the File menu) for converting your macro to inline code.

Drop-down list boxes

  • If you start a macro via iimPlay which contains a TAG TYPE=SELECT… statement and the specified value is not in the drop down list then the iimPlay command returns an -1700 error code. In the corresponding error message (see iimGetErrorText) the maximum index is given. You can use this value, for example, to always select the last entry of a changing drop down list.

Playing iMacros for Firefox Javascript (.js) files

  • The version of iimPlay provided with the iMacros Enterprise Edition supports the playback of Javascript (.js) scripts in iMacros for Firefox. For example:

ret = iim1.iimOpen("-fx")
ret = iim1.iimPlay("MyScript.js")
  • The version of iimPlay provided with the built-in Javascript scripting interface in iMacros for Firefox only supports the playback of macro (.iim) files. However, there is a workaround as described in the following forum post:


Name change: Please use iimGetExtract instead. See API enhancements for details.

Returns the contents of the !EXTRACT variable. If the last command was iimPlay and if EXTRACT is used inside a macro iimGetLastExtract returns the extracted text. If the EXTRACT command could not find the extraction anchor then an #EANF# (Extraction Anchor Not Found) message is returned. If there is no EXTRACT command in the macro which was just played then iimGetLastExtract returns an empty string (“”).

If in one macro several EXTRACT commands appear then the results are separated by the string [EXTRACT]. If complete tables where extracted, adjacent table elements are separated by the string #NEXT# and ends of table rows are delimited by the string #NEWLINE#.


String extract = iimGetLastExtract ( [int index_of_extracted_text]   )


Since version 6 this command supports the option to return the extracted information separately, so no further parsing and splitting is required:

iimGetLastExtract () – returns all extracted information at once

iimGetLastExtract (0) – returns all extracted information at once

iimGetLastExtract (1) – returns 1st extracted data

iimGetLastExtract (2) – returns 2nd extracted data (and so on)


Display the extracted results from a macro (Visual Basic Script example):

Dim imacros, iret 
Set imacros = CreateObject("imacros") 
iret = imacros.iimInit() 
iret = imacros.iimPlay("myextractmacro") 
MsgBox "The extract was: "+ vbNewline + _ 
iret = imacros.iimExit()

See Also

Related forum posts:



Returns the text associated with the last error.

Name change: Please use iimGetErrorText instead. See API enhancements for details.


String err_message = iimGetLastError()




Display a dialog if iMacros cannot be initialized (Visual Basic Script example):

Dim imacros, iret 
Set imacros = CreateObject("imacros") 
iret = imacros.iimInit() 
If iret < 0 Then 
  MsgBox "An error occured: " + vbNewline + _ 
End If