View source for Webextensions


== Overview ==

This page provides information that applies to all of the iMacros browser extensions based on the WebExtension framework, i.e. iMacros for Chrome and Firefox. For information that is specific to each of these extensions (including version history), please also refer to their individual pages:

* [[iMacros for Chrome]]
* [[iMacros for Firefox]]

== License ==

[https://www.progress.com/legal/license-agreements/imacros-imail-and-messageway iMacros End User License Agreement]

== Installation [[Image:Cr-icon.png|Chrome]] [[Image:Ff-icon.png|Firefox]] ==

Download and install the latest version of the iMacros extension from the respective browser web store. No administrative rights are required for the installation.

The extension corresponds to the [[Features_Comparison|free version]], which can be used for non-commercial purposes to record and replay small macros stored as ''bookmarks''. Some iMacros features are only available with a Personal Edition (or higher) license. This includes file access to play macro files, read/write CSV files, and other extended functionality as detailed in the table below:
{|class="wikitable" style="text-align: center"
!Feature	
!Free edition	
!Paid version (any)	
!Affected commands
|-
|Play macros	
|Only as bookmarks, up to 50 lines.	
|As bookmarks and files, any length
|
|-	
|Record macros	
|Only as bookmarks, up to 50 lines	
|As bookmarks and files, any length
|	
|-
|Save macros	
|Only as bookmarks	
|As bookmarks and files	
|
|-
|Read input from CSV files	
|No	
|Yes	
|[[!DATASOURCE]]
|-
|Save extracted data to file	
|No	
|Yes	
|[[SAVEAS]], [[SAVEITEM]]
|-
|Make screenshots of webpage	
|No	
|Yes	
|[[SCREENSHOT]], [[SAVEAS]]
|-
|Save stopwatch data to a file	
|No. Data can still be referenced in macro via the [[!STOPWATCHTIME]] variable	
|Yes	
|[[!FILESTOPWATCH]], [[!FOLDER_STOPWATCH]]
|-
|Profile macro performance	
|No	
|Yes	
|[[!FILE_PROFILER]]
|}

=== File Access ===

If you want to use iMacros in your business or would like to store macros as regular text files to exchange them across other versions of iMacros (Chrome, Firefox, iMacros Browser, iMacros for IE), read/write CSV files, and other extended functionality, you will need iMacros File Access. iMacros File Access is already included and installed by default when you [https://imacros.net/store/ purchase any iMacros license] for iMacros 2021 (v14) or later. Please note that iMacros File Access is only available for Windows. Currently we do not offer a version for Mac or Linux.

After running the iMacros installer, the license will be automatically activated. Please also restart any running instances of Chrome or Firefox after installing.

=== Trouble Activating ===

* If you encounter any errors or have any issues activating the license, please contact our [https://www.progress.com/support/phone-support Customer Service].

* If activation was successful but you still see the File Access is not available message in Chrome, there might be a [https://www.chromium.org/administrators/policy-list-3#NativeMessaging group policy] blocking iMacros.FileAccess. Please, check with your system administrator whether this is the case.

== First Steps ==

After you installed the iMacros extension in your browser you will see the iMacros icon in the toolbar, which is used to open the iMacros sidebar. First we recommend that you look at a few demo macros. After this start recording your own first macro. To get started, a simple website like this wiki or our company website are good. To record, open the iMacros panel and click record. When you are done recording, click the stop icon either in the panel or in the browser toolbar. The iMacros icon changes to a stop button with line counter during recording and replay. You can then playback the macro or view/edit the macro code.

{|
|[[Image:Imacros for chrome screenshot.png|left|thumb|600px|The iMacros for Chrome Panel: You can start playing macros either from the iMacros panel or from your bookmarks or macros that are embedded into websites.]]
|[[Image:browserAction.png|right|thumb|400px|The iMacros icon changes to a stop button with line counter during recording and replay, or a play button when paused. The [[WAIT]] command displays the wait time as countdown.]]
|}

The iMacros panel has a '''play loop''' button to run macros repeatedly. This can be useful for checking a certain web page status or for web testing. While the loop is running, the current loop number is stored in the [[!LOOP]] internal variable.

Example usage: Create a macro that refreshes the current page every 5 seconds:
  VERSION BUILD=1031208
  REFRESH
  WAIT SECONDS=5
[[Image:Chrome automate page refresh.png|center|thumb|200px|Start the PAGE REFRESH macro with the LOOP button.]]

Spend some time to get familiar with this wiki, it has lots of in-depth information on all iMacros functionality, as well as have a look at the Resources page on the iMacros website.

== Tips for using iMacros browser extensions freeware ==

Some of iMacros functionality is now only available with a paid license. These are features we believe are most likely to be used in a business environment and should not affect hobby users of iMacros.

Because we think there is still a lot of value in the freeware, we would like to give you a few tips to overcome some of the limitations, if you would like to keep using the freeware for your personal tasks.

# Existing macro files can easily be copied to bookmarks through the clipboard: open the macro file in any text editor, copy its contents to the clipboard and paste over an existing bookmark macro which is open in the macro editor. If you do not have any bookmark macro, start recording to create one. Use SaveAs to save with a new name.
# Long macros can be divided in smaller chunks and played one after the other. Just be aware that variables and macro settings are reset after each play.
# Besides the 3 user variables (!VAR1, !VAR2, and !VAR3), the !EXTRACT macro variable can also be used to "park" values. Or one can make use of an auxiliary html file loaded in another tab. A dummy form like in http://demo.imacros.net/Automate/AutoDataEntry might be all you need.
# To input data from CSV files, use an html file with a table where your data is displayed on a browser tab, see below. Tag the table elements from that tab instead of reading from a file. Excel can save a worksheet (an imported CSV file) to html.
<code>
  <html>
  <head>
    <style>
        .table
        {
            width: 100%
        }
        .row .cell
        {
            padding: 5px;            
            border: 1px solid black;
        }
        
    </style>
    <script>
        window.onload = function () {
            var datasource = document.getElementById('datasource');
            datasource.addEventListener('change', function (e) {
                var csvFile = datasource.files[0];
                var fileReader = new FileReader();
                fileReader.onloadend = function (e) {
                    var table = document.getElementById('table');
                    var lines = fileReader.result.split(/\r?\n/);
                    var n = 0;
                    lines.forEach(function (line) {
                        n++;
                        var tr = document.createElement("tr");
                        tr.setAttribute("class", "row");
                        tr.setAttribute("id", "row_" + n);
                        var cells = line.split(/,/);
                        var m = 0;
                        cells.forEach(function (cell) {
                            var td = document.createElement("td");
                            m++;
                            td.setAttribute("id", "cell_" + n + "-" + m);
                            td.setAttribute("class", "cell");
                            var text = document.createTextNode(cell);
                            td.appendChild(text);
                            tr.appendChild(td);
                        });
                        table.appendChild(tr);
                    });
                }
                fileReader.readAsText(csvFile);
            }, false);
        }
    </script>
  </head>
  <body><nowiki>
    Select CSV file:
    <input type="file" id="datasource" />
    <div>Table with loaded CSV file:</div>
    <table id="table" class=table></table></nowiki>
  </body>
  </html>
</code>

== iMacros as Bookmarklets ==
{|
|[[Image:Manage imacros2.png|left|thumb|400px|center|You can rename, edit or delete your iMacros via your browser's bookmark manager]]  


| If you are used to other iMacros versions, you might be surprised that iMacros for Chrome and iMacros for Firefox do not store its macros as text files. The reason for this is that web extensions can not access the file system. Instead we store macros as [[Bookmarklet|bookmarklets]] inside the regular browser bookmarking system. 

As the macros are packed as bookmarklets, you can just drag & drop them to your bookmarks folder or bookmarks bar. This means you can take full advantage of Chrome and Firefox syncing to have your macros synced across computers. You can sync your iMacros macros just like normal bookmarks. And with the iMacros secure password encryption that means that you can even store login macros securely in the cloud.

<!--Example: [http://preview.tinyurl.com/44res8x  Search the German railway website for train connection from Frankfurt International Airport to Mannheim] - Select "Proceed to this site" to run the macro!-->

|}

== Social Scripting ==

Users can embed the complete macro in a simple link that can be shared with friends and coworkers. Users can also embed the link on their homepage, blog and company Intranet. In this way, users can help website visitors perform certain tasks. Instead of telling visitors how to fill out a form, users can let iMacros fill out the form for them. All information is stored inside the link as a text string, and nothing is stored on our servers.

For example, click on [http://preview.tinyurl.com/yk696yn this link] to search for available flights at orbitz.

'''Important:''' Make sure the embedded macro is url-encoded using e.g. [http://meyerweb.com/eric/tools/dencoder/ this tool].

'''Tip:''' To send macros (bookmarklets) by email, use the a link shortener service.

== Command Line Support ==

Neither Firefox Quantum, nor Chrome provide command line information for extensions, but user "cammarin" suggested a great way to use iMacros via the command line: '''Embed the iMacros bookmarklet in a local web page.'''

# Chrome only: Make sure that "Allow access to file URLs" is enabled for the iMacros extension as shown [[iMacros_for_Chrome#Using_Chrome_with_the_iMacros_RunAs_Agent_.28iimRunner.29|here]].
# Create a bookmark for the macro you want to launch
# Right-click on the bookmark in the browser (not in the iMacros sidebar) and select Edit
# In the URL field, copy the value of the e_m64 variable, e.g. everything between quotes where you see: var e_m64 = "..."
# Paste this value in place of the corresponding value for var e_m64 in the HTML file shown below

Example:
  <html>
      <body onload="window.setTimeout('document.getElementById(\'criimlaunch\').click();', 1000);">
 
         <script>
            var e_m64 = "UFJPTVBUJTIwSEVMTE8hJTBBVVJMJTIwR09UTyUzRGh0dHAlM0ElMkYlMkZpbWFjcm9zLm5ldCUyRiUwQVBST01QVCUyMEJZRSE";
         </script>
 
         <a id="criimlaunch" href="javascript:(function() {try{if(!/^(?:chrome|https?|file)/.test(location)){alert('iMacros: Open webpage to run a macro.');return;}
            var macro = {};macro.source = decodeURIComponent(atob(e_m64));macro.name = 'MacroBookmarklet';
            var evt = document.createEvent('CustomEvent');evt.initCustomEvent('iMacrosRunMacro', true, true, macro);
            window.dispatchEvent(evt);}catch(e){alert('iMacros Bookmarklet error: '+e.toString());}}) ();">Launch iMacros</a>
 
      </body>
  </html>

Example command line / batch file:
  "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" file:///D:/web/test.htm

"test.htm" is the local webpage with the bookmarklet. <!--Note that you need to open another tab first, otherwise Chrome is not ready to start the bookmarklet. So the workaround is to simply open "www.google.com" before our local website with the bookmarklet.  This way you can also start your macro via the [https://wiki.imacros.net/Browser_Automation#Schedule_Tasks Windows task scheduler] or a Linux crown job.

'''Update:''' This approach is no longer working. We discovered that you can make it work by adding a call to alert() as the first line in the launchMacro() function. Obviously this is not acceptable since it would require user intervention to dismiss the dialog. If you know of a fix or other approach, please post the solution [https://forum.imacros.net/viewtopic.php?f=21&t=21954 here].-->

Alternatively, you can embed the macro source code directly into the HTML file and skip the process of creating a macro bookmark altogether (special thanks to forum user [http://forum.imacros.net/memberlist.php?mode=viewprofile&u=29694 iimfun] for this solution!):

 <html>
    <body onload="window.setTimeout('document.getElementById(\'criimlaunch\').click();', 1000);">
 
       <script>
          var macroCode = <nowiki>''</nowiki>;
          macroCode += 'PROMPT HELLO!\n';
          macroCode += 'URL GOTO=http://imacros.net/\n';
          macroCode += 'PROMPT BYE!\n';
 
          function launchMacro()
             {
             try
                {
                   if(!/^(?:chrome|https?|file)/.test(location))
                   {
                      alert('iMacros: Open webpage to run a macro.');
                      return;
                   }
 			   
                   var macro = {}; 
                   macro.source = macroCode;
                   macro.name = 'EmbeddedMacro';
 			   
                   var evt = document.createEvent('CustomEvent');
                   evt.initCustomEvent('iMacrosRunMacro', true, true, macro);
                   window.dispatchEvent(evt);
                }
             catch(e)
             {
                alert('iMacros Bookmarklet error: '+e.toString());
             };
          }
       </script>
 
       <a id="criimlaunch" href="javascript:launchMacro();">Launch iMacros</a>
 
    </body>
 </html>

Related forum post: [http://forum.imacros.net/viewtopic.php?f=21&t=21954 How to run a macro from the command line using Chrome]

==Scripting Chrome and Firefox==
Chrome and Firefox can be scripted with the [[Web Scripting|iMacros scripting interface (API)]] included with some of the [[Features Comparison|iMacros paid editions]]. The API allows you to control Chrome and Firefox from [[Sample Code|external scripts and programs (C++, C#, Python, Perl, Javascript, PowerShell, etc...)]]. For details, see the chapter with the [[iimOpen|iimOpen command]].

'''Notes:'''
* In order to control iMacros for Chrome or Firefox via the iMacros scripting interface, you must install [[Webextensions#Add_File_Access|File Access for iMacros Extensions]].
* File Access is installed by default when installing any edition of iMacros 2021 (v14) and newer.
* For iMacros Enterprise v12.0 and older, please also read '''ScriptingInterface.readme.txt''' located in %localappdata%\Programs\iMacros after installing File Access!

===Using Chrome and Firefox with the iMacros RunAs Agent (iimRunner)===

iimRunner only works with a non-default Chrome UserDataDir or Firefox profile. See [[iMacros for Chrome]] and [[iMacros for Firefox]] for more details.

===Where is the iimDisplay message? ===
iMacros web extensions show iimDisplay messages as a desktop notification pop-up window.
[[File:chrome_iimdisplay_desktop_notification.png|center|thumb|400px|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'''.]]

== Getting Help ==

For issues activating the license, see the [[Webextensions#Trouble_Activating|above section]]. If you run into any other issues, please don't hesitate to reach out on the [http://forum.imacros.net iMacros forums]. Take a good look through the [http://forum.imacros.net forums] before asking your question, we might already have a solution or work around available!

For direct email and phone support from a Progress technical support representative, consider upgrading to a Professional or Enterprise Edition license.

== See Also ==
[[Personal Edition]], [[iMacros for Chrome]], [[iMacros for Firefox]], [[iMacros for Firefox Legacy]], [[Features Comparison]]