Generic HTML Browser

(Available from version 7.2 onwards.)

The Generic HTML Browser Library provides functions and events for controlling and monitoring tabs in web browsers other than Internet Explorer, including Chrome, Firefox, and Microsoft Edge.  

Note the following limitations on support for Microsoft Edge:

  • Only available if using NICE Real-Time Client 7.3 or higher.

  • Only versions of Microsoft Edge based on Chromium are supported. Previous versions of Edge that were based on other technologies are not supported.

The Internet Explorer built-in service provides similar functionality for Internet Explorer.

Instances of only one browser (e.g. only Chrome, Firefox, or Edge) should be open when using these functions to avoid unpredictable behavior.

From version 7.6, support was added to work with these browsers in parallel (that is, with multiple browsers of different types open simultaneously).

If multiple instances of a browser are open, each with one or more tabs open, the Generic HTML Browser functions will treat all open tabs as if they were open in the same, single instance of the browser. In general:

  • Where a function relates to the active tab, it will relate to the active tab in the instance of the browser that was activated most recently.

  • Where a function relates to tabs by ID, it will relate to the tabs irrespective of which instance of the browser they are open in as the tab IDs are unique across instances.

Prerequisites

To enable the functions in this library to work, the relevant connector extension must be installed and activated for the relevant browser.

You must also ensure that your project includes a screen element captured from either a Chrome, Firefox, or Edge browser, so that an rti_nativehost screen element will be listed under Screen Elements in the Assets Panel. It does not matter what screen element you capture from either browser.

Properties

The Generic HTML Browser Entity has the following property:

Property

Type

Description

Browser Name

text

The name of the browser to which to apply the generic browser methods

Functions

An individual example is provided for each function described in this topic.

Project Download

Download the project here and unzip to the folder %AppData%/Nice_Systems/AutomationStudio/Projects\.

This project includes all the workflows shown in the examples. Each workflow is named with the name of the function demonstrated.

The following functions are available from version 7.2 and above:

Activates a browser tab specified by its ID.

Parameters

Parameter

Input Type

Description

tab ID

number

The ID of the tab

Returns

Nothing

Example

Multiple tabs are open.

To activate the Google tab, use Activate Tab by ID, setting tab id to the ID of that tab, which in this example happens to be 40. (You can discover tab ID's using Get List of Tabs.)

The Google tab is now activated.

Activates a browser tab specified by its title. If multiple tabs match the title specified, generally the tab with the lowest ID will be activated.

Parameters

Parameter

Input Type

Description

tab title

text

The title of the tab

Wildcards * (multiple characters) and ? (single character) are supported.

Returns

Nothing

Example

Three tabs are open:

  1. https://www.google.com (active)

  2. https://www.nice.com/

  3. https://www.nice.com/

To activate the 2nd tab, use Activate Tab by Title, setting tab title to *NICE*(using wildcards as the title includes additional text):

The middle tab is now activated:

Setting tab title to Enabling* would have the same result in this example.

Activates a browser tab specified by its URL.

Parameters

Parameter

Input Type

Description

tab URL

text

The URL of the tab.

Wildcards are not supported.

The tab URL must exactly match the URL in the browser. For example, if the browser tab URL is set to https://www.nice.com/, neither www.nice.com nor https://www.nice.com will be recognized.

Returns

Nothing

Example

Multiple tabs are open.

To activate the Google tab, use Activate Tab by URL, setting tab URL to https://www.google.com/.

The Google tab is activated.

Closes the tab that is currently active in the browser.

Parameters

Parameter

Input Type

Description

None

 

 

Returns

Nothing

Example

Multiple tabs are open.

To close the active tab, use Close Active Tab. For demonstration purposes, a timer was defined and the transition waits for the timer to elapse before closing the active tab. This allows you to activate another tab instead of the Automation Studio tab after starting debug, so as not to close Automation Studio.

The active tab is closed.

Closes a browser tab specified by its ID.

Parameters

Parameter

Input Type

Description

tab ID

number

The ID of the tab

Returns

Nothing

Example

Multiple tabs are open.

To close the Google tab, use Close Tab by ID, setting tab id to the ID of that tab, which in this example happens to be 40. (You can discover tab ID's using Get List of Tabs.)

The Google tab is closed.

Closes a browser tab specified by its title. If multiple tabs match the title specified, all those tabs will be closed.

Parameters

Parameter

Input Type

Description

tab title

text

The title of the tab

Wildcards * (multiple characters) and ? (single character) are supported.

Returns

Nothing

Example

Multiple tabs are open:

To close the 3rd tab, use Close Tab by Title, setting tab title to *MSN*(using wildcards as the title includes additional text):

The 3rd tab is now closed:

Closes a browser tab specified by its URL.

Parameters

Parameter

Input Type

Description

tab URL

text

The URL of the tab.

Wildcards are not supported.

The tab URL must exactly match the URL in the browser. For example, if the browser tab URL is set to https://www.nice.com/, neither www.nice.com nor https://www.nice.com will be recognized.

Returns

Nothing

Example

Multiple tabs are open:

To close the Google tab, use Close Tab by URL, setting tab URL to https://www.google.com/.

The Google tab is now closed.

Executes the specified command in the web browser. The table below lists the available commands and the parameter to be specified for each command.

Commands

Command

Parameter

Description
create_tab url Opens a new tab in the browser and opens the specified URL in that tab.

reload_active_tab

(None)

Reloads the tab that is currently active in the browser.

close_active_tab

(None)

Closes the tab that is currently active in the browser.

close_tab_by_title

title

Closes the tab in the browser that has a title that matches the title specified. If multiple tabs match the title specified, all those tabs will be closed.

Wildcards * (multiple characters) and ? (single character) are supported.
close_tab_by_url url

Closes the tab in the browser that is open to the URL specified. If multiple tabs match the URL specified, all those tabs will be closed.

The tab URL must exactly match the URL in the browser. For example, if the browser tab URL is set to https://www.nice.com/, neither www.nice.com nor https://www.nice.com will be recognized.

The following parameters must be specified when using this function:

Parameters

Parameter

Input Type

Description

command

text

The command to execute

The available commands are listed in the table above.

parameters

text

The parameter relevant to the command specified (see the table above) together with its value

The parameter and value must be specified as a JSON object, in the format:

{"key": "value"}

For example, if the command specified requires that the parameter url be provided, the parameters parameter must be specified as:

{"url": "https://www.nice.com/"}

Where no parameter is required, for example when using the command close_active_tab, an empty JSON object should be specified:

{}

Returns

Returns text { "success": true} if the command was executed, regardless of whether the command resulted in the desired outcome.

Example

Two tabs are open:

  1. https://www.google.com (active)

  2. https://www.msn.com/

This example first closes the active tab (Google) and then creates a new tab in which it opens the site https://www.nice.com/.

For demonstration purposes, a timer was defined and the transition waits for the timer to elapse before closing the active tab. This allows you to activate another tab instead of the Automation Studio tab after starting debug, so as not to close Automation Studio.

The Google tab is closed and a new tab for NICE is opened:

Executes a script on a web page and returns the result.

This function does not execute script in the browser document context. The script is executed in local scope, and does not have access to global HTML variables.

Parameters

Parameter

Input Type

Description

script

text

The script to execute.

The script must not be wrapped in quotation marks. For example:

  • alert(\"Hello\") is allowed
  • "alert(\"Hello\")" is not allowed

title

text

The title of the browser tab in which to run the script.

Wildcards * (multiple characters) and ? (single character) are supported.

Only one of the parameters title and URL must be specified.

URL

text

The URL of the browser tab in which to run the script.

The URL must exactly match the URL in the browser. For example, if the browser tab URL is set to https://www.nice.com/, neither www.nice.com nor https://www.nice.com will be recognized.

Only one of the parameters title and URL must be specified.

Returns

Returns the result of the script as text.

Example

This example returns the current Universal Coordinated Time (UTC) as provided by the National Research Council of Canada at the site https://nrc.canada.ca/en/web-clock/.

The time is displayed in this block:

Using Chrome developer tools, the id of that element can be seen to be timeDiv7.

The time can therefore be retrieved using the script document.getElementById('timeDiv7').innerHTML.

The site must be open:

The workflow below evaluates the script on the site and stores the result in the variable scriptResult.

In debug mode, the variable scriptResult is set to the current UTC time:

Reloads the active tab in the browser.

Parameters

Parameter

Input Type

Description

None

    

Returns

Nothing

Example

Multiple tabs are open.

To reload the active tab, use Reload Active Tab. For demonstration purposes, a timer was defined and the transition waits for the timer to elapse before closing the active tab. This allows you to activate another tab instead of the Automation Studio tab after starting debug, so as not to restart Automation Studio.

The active tab is reloaded.

The following functions are available from version 7.6 and above:

Closes all tabs specified by title.

If multiple instances of the browser are open, tabs with titles that match the specified title will be closed in all instances of the browser.

Parameters

Parameter

Input Type

Description

tab title

text

The title of the tab.

Wildcards * (multiple characters) and ? (single character) are supported.

Returns

Nothing

Example

Three tabs are open:

  1. https://www.nice.com/

  2. https://www.google.com (active)

  3. https://www.nice.com/

To close both https://www.nice.com/ tabs, use Close All Tabs by Title, setting tab title to *NICE* (using wildcards as the title includes additional text):

Both tabs to https://www.nice.com/ were closed:

Setting tab title to Transforming* would have the same result in this example.

Closes all tabs specified by URL.

If multiple instances of the browser are open, tabs with URLs that match the specified URL will be closed in all instances of the supported browsers.

Parameters

Parameter

Input Type

Description

tab URL

text

The URL of the tab.

Wildcards * (multiple characters) and ? (single character) are supported.

Returns

Nothing

Example

Three tabs are open.

  • www.nice.com

  • www.google.com

  • www.nice.com

This workflow closes all tabs open to URLs that include the text nice.

When the workflow is run, the two tabs open to www.nice.com are closed.

Runs a specified Javascript on a tab specified by ID and returns the value of a specified global variable.

Parameters

Parameter

Input Type

Description

tab ID

number

The ID of the tab

Javascript

text

The Javascript to run

global variable name

text

The global variable to return

Returns

Returns the value of the specified global variable as text.

Runs specified Javascript on an HTML document.

Parameter

Input Type

Description

Tab ID

number

The ID of the browser tab.

URL

text

The URL containing the document.

Document Index

number

The index of the required HTML document.

JavaScript

text

The script to execute.

Runs a specified Javascript on a tab specified by ID.

Parameters

Parameter

Input Type

Description

tab ID

number

The ID of the tab

Javascript

text

The Javascript to run

Returns

Nothing

Example

This example executes the Javascript below to display a simple message on the active tab:

alert('Hello World');

The script is run on the active tab:

Retrieves the IDs of tabs specified by title.

If multiple tabs match the specified title, the IDs will be returned for all of them.

If multiple instances of the browser are open, the IDs will be returned for all matching tabs in all instances of the browser.

Parameters

Parameter

Input Type

Description

tab title

text

The title of the tab.

Wildcards * (multiple characters) and ? (single character) are supported.

Returns

Returns the IDs of the tabs in a list of numbers

Example

Three tabs are open:

  1. https://www.nice.com/

  2. https://www.google.com/

  3. https://www.nice.com/

To retrieve a list of IDs of both https://www.nice.com/ tab IDs, use Get All Tab IDs by Title, setting title to *NICE*, and assign the value to a list of numbers (ListOfIds):

In debug mode, the variableListOfIds includes 2 elements as expected, each containing the ID of one of the https://www.nice.com/ tabs:

Setting tab title to Transforming* would have the same result in this example.

Retrieves the IDs of tabs specified by URL.

If multiple tabs match the specified URL, the IDs will be returned for all of them.

If specified without wildcards, the tab URL must exactly match the URL in the browser. For example, if the browser tab URL is set to https://www.nice.com/, neither www.nice.com nor https://www.nice.com will be recognized.

If multiple instances of the browser are open, the IDs will be returned for all matching tabs in all instances of the browser.

Parameters

Parameter

Input Type

Description

tab URL

text

The URL of the tab.

Wildcards * (multiple characters) and ? (single character) are supported.

Returns

Returns the IDs of the tabs in a list of numbers

Example

Three tabs are open:

  1. https://www.nice.com/

  2. https://www.google.com

  3. https://www.nice.com/

To retrieve a list of IDs of both https://www.nice.com/ tabs, use Get All Tab IDs by URL, setting tab URL to https://www.nice.com/, and assign the value to a list of numbers (ListOfIds):

In debug mode, the variable ListOfIds includes 2 elements as expected, each containing the ID of one of the https://www.nice.com/ tabs:

Setting tab URL to *www.nice.com* would have the same result in this example.

Retrieves the ID and title of each open tab in a list of key-value pairs.

Parameters

No parameters

Returns

Returns a list of type key-value pair. In each pair, the Key parameter stores the ID of a tab and the Value parameter stores its title.

Example

This workflow populates the key-pair list List_of_Tabs with details of all tabs open in a supported browser.

Three tabs are open in Internet Explorer.

When the workflow is run, the list List_of_Tabs is populated with the ID and title of each tab.

Retrieves the ID of the tab specified by title.

If multiple tabs match the specified title, the ID will be returned for the first matching tab to the right of the active tab (or of the active tab itself).

If multiple instances of the browser are open, the ID will be returned for the first matching tab to the right of the active tab (or of the active tab itself) in the instance of the browser that was activated most recently.

Parameters

Parameter

Input Type

Description

tab title

text

The title of the tab.

Wildcards * (multiple characters) and ? (single character) are supported.

Returns

Returns the ID of the first tab with matching title as a number

Example

Three tabs are open:

  1. https://www.nice.com/

  2. https://www.google.com

  3. https://www.nice.com/

To retrieve the ID of the first tab open to https://www.nice.com, use Get Tab ID by Title, set tab title to *NICE*, and assign the output to a number variable TabID):

In debug, the variable TabID is set to the ID of the first tab open to https://www.nice.com/:

Setting tab title to Transforming* would have the same result in this example.

Retrieves the ID of the tab specified by URL.

If multiple tabs match the specified URL, the ID will be returned for the first matching tab to the right of the active tab (or of the active tab itself).

If specified without wildcards, the tab URL must exactly match the URL in the browser. For example, if the browser tab URL is set to https://www.nice.com/, neither www.nice.com nor https://www.nice.com will be recognized.

If multiple instances of the browser are open, the ID will be returned for the first matching tab to the right of the active tab (or of the active tab itself) in the instance of the browser that was activated most recently.

Parameters

Parameter

Input Type

Description

tab URL

text

The URL of the tab.

Wildcards * (multiple characters) and ? (single character) are supported.

Returns

Returns the ID of the active tab as a number

Example

Three tabs are open:

  1. https://www.nice.com/

  2. https://www.nice.com/

  3. https://www.google.com

To retrieve the ID of the first tab open to https://www.nice.com, use Get Tab ID by URL, set tab URL to *nice.com*, and assign the output to a number variable TabID):

When the workflow is run, the variable TabID is set to the ID of the first tab open to https://www.nice.com/:

Retrieves the ID of the active tab.

If multiple instances of the browser are open, the ID of the active tab in the instance of the browser that was activated most recently will be returned.

Parameters

Parameter

Input Type

Description

None

    

Returns

Returns the ID of the active tab as a number

Example

Three tabs are open:

  1. https://www.nice.com/

  2. https://www.google.com

  3. https://www.nice.com/ (active)

To retrieve the ID of the active tab (the second instance of https://www.nice.com), use Get Tab ID of Active Tab and assign the output to a number variable (TabID):

In debug, the variable TabID is set to the ID of the active tab:

Retrieves the title of a tab specified by ID.

Parameters

Parameter

Input Type

Description

tab ID

number

The ID of the tab

Returns

Returns the title of the tab as text.

Example

Three tabs are open:

  1. https://www.nice.com/

  2. https://www.google.com

  3. https://www.nice.com/ (active)

This example retrieves the ID of the active tab using Get Tab ID of Active Tab, retrieves the title of that tab using Get Tab Title by ID, and stores the title in the text variable TabTitle:

When the workflow is run, the variable TabTitle is set to the title of the active tab:

Retrieves the URL of a tab specified by ID.

Parameters

Parameter

Input Type

Description

tab ID

number

The ID of the tab

Returns

Returns the URL of the tab as text

Example

Three tabs are open:

  1. https://www.nice.com/

  2. https://www.google.com

  3. https://www.nice.com/ (active)

This example retrieves the ID of the active tab using Get Tab ID of Active Tab, retrieves the URL of that tab using Get Tab URL by ID, and stores the title in the text variable TabURL:

When the workflow is run, the variable TabURL is set to the URL of the active tab:

Indicates if a supported browser is running.

Parameters

No parameters

Returns

Returns Boolean value true if a supported browser is running.

Example

Three tabs are open:

  1. https://www.nice.com/

  2. https://www.google.com

  3. https://www.nice.com/

This workflow tests whether any of the supported browsers (other than Internet Explorer) are running. The boolean variable Running is set to true one of those browsers is running.

When the workflow is run, the variable Running is set to true as expected:

Navigates to the specified URL in the tab specified by ID. The tab is not activated automatically.

Parameters

Parameter

Input Type

Description

URL

text

The URL to navigate to

tab ID

number

The ID of the tab

Returns

Nothing

Example

Three tabs are open:

  1. https://www.nice.com/

  2. https://www.google.com

  3. https://www.nice.com/ (active)

This example retrieves the ID of the active tab using Get Tab ID of Active Tab and navigates to the site www.yahoo.com:

The third tab, which was the active tab, is now open to www.yahoo.com:

Navigates to the specified URL in a new tab of the active instance of a supported browser. The new tab is set to active.

A new instance of a supported browser is opened if no instance is open.

If multiple instances of a supported browser are open, the new tab will be opened in the instance of the browser that was activated most recently.

Parameters

Parameter

Input Type

Description

URL

text

The URL to navigate to

Returns

Nothing

Example

Three tabs are open:

  1. https://www.nice.com/

  2. https://www.nice.com/

  3. https://www.google.com

This example opens www.yahoo.com in a new tab.

A new tab is added showing www.yahoo.com, and that tab is activated:

Navigates to the specified URL in a new instance of the most recently active supported browser.

Parameters

Parameter

Input Type

Description

URL

text

The URL to navigate to

Returns

Nothing

Example

This example opens https://www.nice.com/ in a new window.

A new browser window is opened to https://www.nice.com/.

Reloads the tab specified by ID. The tab is not automatically made the active tab.

Parameters

Parameter

Input Type

Description

tab ID

number

The ID of the tab

Returns

Nothing

Example

Three tabs are open.

  • www.nice.com

  • www.google.com

  • www.nice.com

This workflow reloads the first tab open to www.nice.com, using Get Tab by ID by Title to retrieve the tab ID.

The first tab is reloaded.

Specifies the web browser on which to operate.

Parameters

Parameter

Input Type

Description

NewHTMLbrowser

Dropdown list: [Chrome, Edge, Firefox]

Selected web browser.

Returns

Nothing

The following function is available from version 7.9 and above:

Parameters

Parameter

Input Type

Description

Id

Number

The ID of the required browser tab.

Returns

Returns the date/time the specified tab was created (DateTime)

The following function is available for version 7.5 and below:

Retrieves details of all browser tabs open in all instances of the browser.

If instances of Chrome, Firefox, and Microsoft Edge are open at the same time, tabs will only be retrieved from one of those browsers. When using the functions in this built-in service, it is recommended to have only one of the supported browsers open to prevent unpredictable behavior.

Parameters

Parameter

Input Type

Description

None

    

Returns

Returns information about all tabs as text. The text that is returned is in the form of a JSON array.

The JSON array returned is an array of multiple JSON objects, each representing a single tab. See the example below.

Significantly, the tab ID for each tab is returned in the id element. This can be used to populate the ID parameters required by many functions in this library.

Example

Three tabs are open:

  1. https://www.google.com

  2. https://www.nice.com/

  3. https://www.nice.com/

To retrieve details about all tabs, assign the output of Get List of Tabs to a text variable TabsInfo. The contents of InfoTabs is then written to a file at c:\Temp\TabsInfo.txt.

The contents of the text file are shown below.

[
  {
    "active": false,
    "audible": false,
    "autoDiscardable": true,
    "discarded": false,
    "favIconUrl": "https://www.google.com/favicon.ico",
    "height": 440,
    "highlighted": false,
    "id": 72,
    "incognito": false,
    "index": 0,
    "mutedInfo": {
      "muted": false
    },
    "pinned": false,
    "selected": false,
    "status": "complete",
    "title": "Google",
    "url": "https://www.google.com/",
    "width": 689,
    "windowId": 17
  },
  {
    "active": false,
    "audible": false,
    "autoDiscardable": true,
    "discarded": false,
    "favIconUrl": "https://www.nice.com/assets/img/favicon-nice/favicon.ico",
    "height": 440,
    "highlighted": false,
    "id": 19,
    "incognito": false,
    "index": 1,
    "mutedInfo": {
      "muted": false
    },
    "pinned": false,
    "selected": false,
    "status": "complete",
    "title": "Enabling Organizations to Operationalize Big Data | NICE",
    "url": "https://www.nice.com/",
    "width": 689,
    "windowId": 17
  },
  {
    "active": true,
    "audible": false,
    "autoDiscardable": true,
    "discarded": false,
    "favIconUrl": "https://www.nice.com/assets/img/favicon-nice/favicon.ico",
    "height": 440,
    "highlighted": true,
    "id": 73,
    "incognito": false,
    "index": 2,
    "mutedInfo": {
      "muted": false
    },
    "pinned": false,
    "selected": true,
    "status": "complete",
    "title": "Enabling Organizations to Operationalize Big Data | NICE",
    "url": "https://www.nice.com/",
    "width": 689,
    "windowId": 17
  }]

Events

Triggered when a tab is activated in the browser.

Triggered when a tab is closed in the browser.

Triggered when a tab is created in the browser.