Start Browser
Starts a web browser.
Command availability: IBM RPA SaaS and IBM RPA on premises
Script syntax
IBM RPA's proprietary scripting language has a syntax similar to other programming languages. The script syntax defines the command's syntax in the script file. You can work with this syntax in IBM RPA Studio's Script mode.
webStart --name(String) --type(BrowserTypes) [--userprofilepreferences(BrowserProfiles)] [--enableextensions(Boolean)] [--extensionsFolder(String)] [--disablegpu(Boolean)] [--bypassExternalProtocols(String)] [--useproxy(Boolean)] [--isautodetect(Boolean)] [--username(String)] [--password(String)] --proxyaddress(String) --proxyport(Numeric) [--headless(Boolean)] [--commandexecutiontimeout(TimeSpan)] [--pageloadtimeout(TimeSpan)] [--implicitwaittimeout(TimeSpan)] [--asynchronousjavascripttimeout(TimeSpan)] [--incognito(Boolean)] [--downloadpath(String)] (Browser)=value
Dependencies
Antivirus and ports can affect bots and block their operation:
- For antivirus, follow the instructions presented on the Antivirus notice section to add paths to the antivirus ignore list.
- Open the ports to trigger bots.
If you select Microsoft Edge as the browser that the Start browser command must open, you need to add commands to your script to handle pop-ups that appear if you enable the following input parameters:
- Enable extensions (
enableextensions) - Use proxy (
useproxy)
See the Examples for workarounds to these issues.
- If you use IBM RPA on premises or IBM RPA on Red Hat® OpenShift® Container Platform, the IBM RPA server downloads web drivers from the internet. These downloads can take several minutes, or up to 1 hour for Microsoft Edge. An Internet connection is required.
- When your bot runs the Start Browser command for the first time, the bot requests a web driver for download from the server. If the web driver is not available or can't be downloaded, the bot fails.
Input parameter
The following table displays the list of input parameters available in this command. In the table, you can see the parameter name when working in IBM RPA Studio's Script mode and its Designer mode equivalent label.
| Designer mode label | Script mode name | Required | Accepted variable types | Description |
|---|---|---|---|---|
| Instance name | name |
Required |
Text |
Name of the browser instance. |
| Browser type | type |
Required |
BrowserTypes |
Type of browser to use. See the type parameter options. |
| Use profile preferences | useprofilepreferences |
Required |
BrowserProfiles |
Starts the session logged into the desired user profile. There are some differences you may see on your automation regarding on what profile you select. See the useprofilepreferences parameter options for more information on each profile.Important:This parameter only works on Google Chrome, Mozilla Firefox, and Microsoft™ Edge . |
| Enable extensions | enableextensions |
Optional |
Boolean |
Allows installing extensions in the browser. |
| Extensions folder | enxtensionsfolder |
Optional |
Text |
Folder path with the extensions to install. |
| Disable GPU | disablegpu |
Optional |
Boolean |
Disables the graphics processing unit. |
| Bypass external protocols | bypassexternalprotocols |
Optional |
Text |
A string defining which protocols to ignore. |
| Use proxy | useproxy |
Optional |
Boolean |
Allows using a proxy-based connection. |
| Auto detect | isautodetect |
Optional |
Boolean |
Detects the proxy automatically. |
| User name | username |
Optional |
Text |
Proxy username. |
| Password | password |
Optional |
Text, Secure String |
Proxy user password. |
| Proxy address | proxyaddress |
Only when Auto detect is False |
Text |
Address for the proxy connection. |
| Proxy port | proxyport |
Only when Auto detect is False |
Number |
Port opened for the proxy connection. |
| Headless | headless |
Optional |
Boolean |
Does not display the browser window. |
| Execution timeout | commandexecutiontimeout |
Optional |
Time Span, Number, Text |
Timeout for starting the browser. |
| Page load timeout | pageloadtimeout |
Optional |
Time Span, Number, Text |
Timeout for loading page components. |
| Implicit timeout | implicitwaittimeout |
Optional |
Time Span, Number, Text |
Implicit timeout to run the command. |
| JavaScript timeout | asynchronousjavascripttimeout |
Optional |
Time Span, Number, Text |
Timeout for running JavaScript callbacks. |
| Incognito | incognito |
Optional |
Boolean |
Opens the browser window in incognito mode. |
| IE11 compatibility mode | iecompatibility |
Only when Microsoft Edge is the Browser type |
Boolean |
Enable to open Microsoft™ Edge in Internet Explorer 11 compatibility mode. If you use this parameter, follow the procedure on this troubleshooting topic to enable the Protected Mode option in Internet Explorer 11. |
| Download path | downloadpath |
Optional |
Text |
The path to save a downloaded file. The behavior of this parameter can change depending on the user profile set. |
type parameter options
The following table displays the options available for the type input parameter. The table shows the options available when working in Script mode and the equivalent label in the Designer mode.
| Designer mode label | Script mode name | Description |
|---|---|---|
| Google Chrome | Chrome |
Google Chrome browser. |
| Internet Explorer | InternetExplorer |
Internet Explorer browser. |
| Microsoft Edge | Edge |
Microsoft™ Edge (Chromium) browser. |
| Mozilla Firefox | Firefox |
Mozilla Firefox browser. |
useprofilepreferences parameter options
The following table displays the options available for the useprofilepreferences input parameter. The table shows the options available when working in Script mode and the equivalent label in the Designer mode.
| Designer mode label | Script mode name | Description |
|---|---|---|
| Default for automation | AutomationOptimized |
Loads the default IBM RPA Studio profile, ignoring the browser's profile preferences. |
| Automation-optimized user profile | UserProfileOptmized |
Load the browser's profile preferences, while still maintaining some IBM RPA Studio's preferences to optimize the automation. |
| Full user profile | StrictUserProfile |
Load the browser's profile preferences, while ignoring IBM RPA Studio's preferences. Important:Using this option might lead to your automation not working properly.
|
To have a better understanding on how each profile works with the browsers available, see the following sections:
- Default for automation and Automation-optimized user profile
| Element | Description |
|---|---|
| The command will always download PDFs, not only open them. | |
| Password | The command disables pop-ups related to password saving and password suggestions. |
| Download | The command will automatically handle the prompt of selecting the file path of all downloads. |
| Navigation | The command will disable reporting analytics information to browser servers. The command will also bypass useful verifications, however they could potentially block the bot execution flow, such as pop-up blocking. The command always open the browser maximized, and hide every message prompts. |
| Content | The command allows loading HTTP content on Google Chrome and Microsoft Edge. |
- Full user profile
| Element | Description |
|---|---|
| The behavior will depend on the configuration set on the browser. | |
| Password | The behavior will depend on the configuration set on the browser. |
| Download | The command won't handle any prompts related to downloads, your script must take care of it. If you're doing multiple downloads, you may see a message from browser that could potentially block the downloads. |
| Navigation | The command doesn't disable reporting analytics information by default and the behavior will depend on how the browser was configured. The command also doesn't bypass some verifications that could block the bot execution, so the script will need to handle them, and some of these behaviors will depend on how the browser is configured. |
| Content | HTTP contents will be loaded depending on the configuration set on the browser. |
Output parameter
| Designer mode label | Script mode name | Accepted variable types | Description |
|---|---|---|---|
| Browser | value |
Browser |
Returns the variable with the browser instance. |
Examples
Example 1: Starts the Google Chrome browser:
webStart --name browser --type "Chrome"
// Navigate to the ibm web page.
webNavigate --url "ibm.com"
webClose --name browser --leavebrowseropen
Example 2: Starts the Microsoft™ Edge browser, closes the Turn off extensions in developer mode pop-up and navigates to the IBM page.
webStart --name browser --type "Edge"
// Close the pop-up
click --safesearch --selector "XPath" --controlsimilarity 100 --forcerefresh --xpath "//window[@name=\'Turn off extensions in developer mode\']//button[@name=\'Close\']" --timeout "00:00:20
// Navigate to the IBM web page.
webNavigate --url "ibm.com"
webClose --name browser --leavebrowseropen
Limitations
- IBM Robotic Process Automation uses an extension to connect to proxy servers while browsing. To use the extension, ensure that you meet the following browser requirements:
- Google Chrome 108 or higher.
- Microsoft™ Edge 108 or higher.
- Only one browser instance can be open at a time. See Bot fails when it tries to open two Google Chrome browsers using user data for more details.