Web Browser - Create session

Declaration

<AMWEBBROWSER ACTIVITY="attach" SESSION="text" BROWSER="text (options)" BROWSERCLOSE="YES/NO" MATCHWINDOWURL="text" MATCHWINDOWTITLE="text" MATCHWINDOWHANDLE="text" />

Related Topics   

Description

Creates and links a new session to a web browser instance previously opened by Automate Desktop. To end a session, use the Web Browser - Close activity.

NOTE:
  • The Web Browser action is not backwards compatible with the Web Browser (Legacy) action.
  • Automation with the Web Browser action is only compatible with Internet Explorer, Chrome, Edge, and Firefox browsers.
  • You must update the specified browser to the latest version and install it on the target system to ensure the Web Browser action functions correctly.
  • Unlike other session-based actions where sessions are optional, the Web Browser action requires the use of a session as each created session explicitly links to a specific web browser instance (you can create a session using the Web Browser - Create session or Web Browser - Open activity). A single task can support numerous sessions; however, since Web Browser activities are performed interactively (and not in the background), each session must run concurrently to avoid sending interactions to the wrong browser window.
  • For Chrome and Edge browsers, you must set the RemoteDebuggingAllowed policy to true to allow automation with this activity. For more information, see Known policy issue.

Practical usage

Used to attach a session to an already open browser window matching the specific criteria. To open a web browser, as well as create a session, use the Web Browser - Open activity.

Parameters

Browser

This activity uses Automate Desktop's Window Dissection technology to facilitate the discovery of existing windows and their controls. To select certain elements that match an open browser window in which to attach a session to:

  1. Make certain the window is open and in the foreground (that is, in front of all other open windows).
  2. Drag and release the magnifier icon over the window. If the window is supported by this activity, a green border appears around it.
  3. Upon releasing the icon, identified window properties are populated onto the editor.
Property Type Required Default Markup Description
Browser Text (options) Yes Chrome
  • BROWSER="chrome"
  • BROWSER-"edge"
  • BROWSER="firefox"
 Specifies the web browser to use with the session. The following browsers are supported:
  • Internet Explorer
  • Chrome (default)
  • Edge
  • Firefox
NOTE: Firefox does not require a separate extension to be installed with this version of the Web Browser action.
Session name Text Yes BrowserSession1 SESSION="mySession" The name of the session to create. A session explicitly links to a specific web browser instance. To automate a series of web browser steps,  subsequent activities must be linked to this session. The default session name is BrowserSession1.
NOTE: Sessions are supported in Internet Explorer, Chrome, Edge, and Firefox browsers only. Firefox does not require a separate extension to be installed with this version of the Web Browser action.
Close after completion Yes/No No No BROWSERCLOSE="NO" If selected, the web browser window automatically closes after task execution. If disabled, the window remains open after task execution to allow manual work to be performed in the window, if desired. This parameter is disabled by default.
Match by window title Text Yes (Empty) WINDOWTITLE="*Explorer" If enabled, indicates the session is attached to an open browser window matching the specified window handle. If disabled, the window handle is ignored. This parameter supports wildcard characters (for example, * or ?). For example, entering *Automate* includes any browser with the word "Automate" in its handle.
Match by window handle Number No (Empty) WINDOWHANDLE="555735" If enabled, indicates the session is attached to an open browser window matching the handle specified. If disabled, the window handle is ignored. A window handle is numeric code that uniquely identifies an open window. This parameter supports wildcard characters (for example, * or ?).
Match by URL Text No (Empty) URL="555735" If enabled, indicates the session is attached to an open browser window matching the URL specified. This parameter supports wildcard characters (for example, * or ?). For example, entering *Automate* would include any browser displaying the word "Automate" as part of its URL.

Description

Error Causes

On Error

Additional notes

Known policy issue

If you experience automation issues with your web browser and this activity, see the following:

IMPORTANT: Consult your system administrator before making changes to any policy.
Policy name Browser Required setting Description
RemoteDebuggingAllowed

  • Chrome

  • Edge

 true Issue:

If this policy is set to false, Automate Desktop will display the error message "Unable to determine browser version" while attempting to open or create a session with Chrome or Edge.

Resolution:

Set this policy to true to allow this activity to perform automation with Chrome or Edge. For more information on this policy, see:

Example

NOTE:
  • Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
  • To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.

Description

This sample task attaches a session to an existing Internet Explorer browser with the URL https://www.google.com/ and then navigates to www.microsoft.com.

Copy 
<AMVARIABLE NAME="theHandle" VALUE="" />
<AMWEBBROWSER URL="https://www.google.com" BROWSER="firefox" SESSION="BrowserSession1" WINDOWHANDLEVARIABLE="theHandle" />
<AMWEBBROWSER ACTIVITY="attach" SESSION="BrowserSession2" BROWSER="firefox" MATCHWINDOWHANDLE="%theHandle%" />
<AMWEBBROWSER ACTIVITY="navigate" SESSION="BrowserSession2" URL="www.microsoft.com" />