Use Application/Browser

UiPath.UIAutomationNext.Activities.NApplicationCard

Description

Opens a desktop application or web browser page to use in UI automation.

Attention:

Internal URLs cannot be opened using this activity when the browser does not directly accept them as command-line arguments.

You cannot open Chrome (chrome://) or Edge (edge://) internal pages. You can open, however, Firefox (about:) internal pages.

After you drag and drop the activity in the workflow and indicate the application or web page to use, add the activities to be performed inside the Use Application/Browser activity. If the application is not already open, it opens when the project is executed.

This activity is compatible with Object Repository.

Note:

• Starting with UI Automation v20.10.x, multiple Use Application/Browser activities can be nested into each other. This enables you to automate multiple applications simultaneously.
• Starting with UI Automation v21.10.3, the Use Application/Browser activity can open applications in remote environments.
• Starting with UI Automation v22.10.1, the activity can also open browsers in remote environments.

Project compatibility

Windows - Legacy | Windows | Cross-platform

Windows - Legacy, Windows configuration

Designer panel

• Select Indicate Application to identify the application by moving the mouse to its window and selecting it. If the target is a browser web page, navigate to the page before you indicate the application.
• After you indicate the target, manage the target by selecting the menu options button and choosing one of the following options:
  • Indicate target on screen - Indicate the application again.
  • Highlight Target - View the indicated application on your screen surrounded in a box.
  • Show informative screenshot - View a screenshot of the target application or web page.
  • Remove informative screenshot - Remove the screenshot of the target application or web page.
  • OCR Engine - Select one of two options:
    • Embedded OCR Engine - Use the OCR engine embedded in the Computer Vision AI model, namely UiPath Screen OCR.
    • Custom OCR Engine - Use a custom OCR engine. When this option is selected, a panel is added in the activity card where you can drop a different OCR engine activity than UiPath Screen OCR.
  • Add to Object Repository - Add the current UI element to a library project, from where it can be reused throughout your automation process.

• You can launch a new instance of the application or a new browser session, retaining the current configuration settings, by using the button next to the Application Path (in case of an application) or Browser URL (in case of a browser) field. If opening a Browser via this button, all configurations made in the Options - Browser property section are applied, thus enabling you to test the behaviour of the activity at design time, mitigating possible failures at run time.

• Configure application launch settings:
  • If the application is a web browser, you can select Plus on the right side of the Browser URL field, and then use one of the options in the menu to edit the URL of the web page to open.
  • If the application is not a web browser, you can:
    • Specify parameters to pass to the target application at startup from the Application arguments field. For example, if the target application is Acrobat Reader, you can open a specific PDF file by providing the full path to the file. To open the file C:\Sample.pdf, select Plus > Text, and then enter C:\Sample.pdf in the Text Builder. Certain application types are automatically identified and autofill the Arguments property, such as Java apps, Office Suite apps, Adobe Acrobat, or Windows File Explorer.
    • Select Plus on the right side of the Application path field, and then use one of the options in the menu to edit the full path of the executable file to open. For applications installed in user mode, the automation does not save the actual path that includes the username, a relative path is used and displayed in the field as User Folder.
      Note: When the path defined in the Application path field is dynamic, selecting Indicate target on screen in child activities generates an error if the target application is not already open.
    • Check or uncheck the Match exact title checkbox. This option appears only when you indicate the entire window of an application and not just an element inside the application. Also, this option does not appear when you indicate a web browser. When checked, only applications that exactly match the current application title are used in the automation. When left unchecked (default), the window with the closest matching title is used in the automation.

Properties panel

Common

• Continue on error - Specifies if the automation should continue even when the activity throws an error. This field only supports Boolean values (True, False). The default value is False. As a result, if the field is blank and an error is thrown, the execution of the project stops. If the value is set to True, the execution of the project continues regardless of any error.

• Display name - The name displayed for the activity in the Designer panel. A display name is automatically generated when you indicate a target.

  Important:

  The display name of the Use Application/Browser activity is also used as a reference that points to the application or browser that is being targeted. After indicating the target, unless manually set, the display name is automatically changed to the following format:

  • For Applications: Use Application: [title] - [app name]
  • For Browsers: Use Browser [browser type] : [title]

  In the case of nested application cards, each activity inside a card displays a drop-down menu in its body which enables you to choose the application card you want to use it with.

• Timeout - Specify the amount of time (in seconds) to wait for the activity to be executed before throwing an error. The default value is 30 seconds.

  Note: When indicating a window in a Remote Desktop environment, the timeout default setting is set to 60 seconds.

Input

• Unified Target Application - Expand this category to configure the following settings:

  • Arguments - If the application is not a web browser, you can specify parameters to pass to the target application at startup. You can use this property to open a specific file with the application. For example, if the target application is Acrobat Reader, you can open a specific workbook by providing the full path to the file. To open the file C:\Sample.pdf, enter "C:\Sample.pdf". Certain application types are automatically identified and autofill the Arguments property, such as Java apps, Office Suite apps, Adobe Acrobat, or Windows File Explorer.

  • File path - If the application is not a web browser, specifies the full path of the executable file to open. If a file path is specified, the URL property is cleared.

    Note: When the path defined in the File path field is dynamic, selecting Indicate target on screen in child activities generates an error if the target application is not already open.
• Selector - An XML fragment that stores the attributes of a user interface element.
• URL - If the application is a web browser, specifies the URL of the web page to open. If a URL is specified, the File path property is cleared.

Input/Output Element

• Input Element - The target element you want to use with this application, stored in an UIElement object. This object can be retrieved from the Output Element property of another UI Automation activity. You can use this property field to pass the target element from a previous activity to this one without having to indicate it again. This field supports only UIElement variables.
• Output Element - Outputs the target element indicated in this activity to an UIElement variable which can then be reused in other activities. This field supports only UIElement variables.

Misc

• Private - If selected, the values of variables and arguments are no longer logged at Verbose level. This field supports only Boolean (True, False) values. The default value is False.

Options

• Close - Select when to close the target application after the automation executes all the activities added inside this activity:
  • Never - Never close the application.
  • IfOpenedByAppBrowser - Close only if the application was opened by the automation. This is the default value.
  • Always - Close the application every time.

• Input mode - Select which method the Robot should use to interact with the target application:

  • Hardware Events - Uses the hardware driver to perform the action. This is the slowest method, it cannot work in the background, but it is compatible with all desktop apps.

  • Simulate - Simulates using accessibility APIs. Recommended for browsers, Java based applications, SAP. Usually more reliable than Hardware Events. Sends all text in a single action. Works even if target app is not in focus. Please test if your target application UI element supports this.

  • Chromium API - Performs actions using debugger APIs. Works only for Chromium elements. Sends all text in one go. Works even if target app is not in focus. For more details, check out this page.

  • Window Messages - Simulate using Win32 messages. Recommended for desktop apps. Usually more reliable than Hardware Events. Sends all text in a single action. Works even if target app is not in focus. Please test if your target application UI element supports this.

  • Background - Runs actions in the background. Tries to use either Simulate or Chromium API where possible, while complex activities (image, native text) run as usual, in the foreground. It is highly recommended to use this method with the Verify Execution feature.

    Note: Using the Background input mode with Universal Windows Platform applications is not supported, which means applications of this type cannot be automated in the background.
• Open - Select when to open the target application for the execution of the automation:
  • Never - Never open the application.
  • IfNotOpen - Open only if the application is closed. This is the default value. Works only if the File Path or URL fields are populated.
  • Always - Open another instance of the application even if one is already open. Works only if the File Path or URL fields are populated.

• Resize window - Defines whether the application/browser is resized when initialized.

  • None – No resize is applied to the application/browser.
  • Maximize – The application/browser is maximized when initialized.
  • Restore to current size – The application/browser is resized and moved to the position and size it had when indicated, if possible.
  • Minimize – The application/browser is minimized when initialized.
• Window attach mode - Defines where inner activities search for their target elements.
  • Application instance - Inner activities search the indicated application instance, including all parent and child windows (alerts, popups, etc). Other instances of the application are excluded.
  • Single window - Inner activities search only in the indicated window.

Options - Browser

• Incognito/private window - If selected, opens the new browser session in incognito/private mode. By default, this check box is cleared.

• User data folder mode - The User data folder mode you want to set. It is used to start the browser with a specific user data folder.

  • Automatic - Automatically triggers Picture-in-Picture (PiP) mode with a separate user data folder from the default one. If the User data folder path is not set, a folder is automatically generated. This can be helpful when you're looking for browser isolation during automation tasks and keep the data separate from the main browsing session.
  • DefaultFolder - Uses the default browser folder, no matter if it runs in the main browsing session or a PiP session. This option is useful if you want the robot to use the existing user data folder and you don't need a separate or isolated session for automation tasks.
  • CustomFolder - Uses the folder specified in User data folder path. If User data folder path is not set,an auto generated path is used. This option gives you more flexibility and control to manage your folders for different automation tasks by setting a custom path for the user data folder.

  Setting the browser user data folder is only available for Chrome, Edge Chromium, and Firefox.

• User data folder path - The user data folder that the browser uses. Defaults to %LocalAppData%\UiPath\PIP Browser Profiles\BrowserType if not set.

  More details about User Data Folder Mode and User Data Folder Path can be found here.

• WebDriver mode - Indicates how the WebDriver is used when opening a new browser session. The following options are available:

  • Disabled - Disables the use of WebDriver.
  • WithGUI - The GUI of the browser is displayed.
  • Headless - The browser is launched silently, with no GUI.

  More details about WebDriver can be found here.

Cross-platform configuration

The name of the activity in cross-platform projects is Use Browser and it can be used to automate only Chrome browser windows and Java applications.

To automate Java applications, you need to set to True the Enable Java automation (preview) project setting (Project Settings > UI Automation > Generic).

• Select Indicate target on screen to identify the application by moving the mouse to its window and selecting it. If the target is a browser web page, navigate to the page before you indicate the application.
• After you indicate the target, manage the target by selecting the menu options button and choosing one of the following options:
  • Indicate target on screen - Indicate the application again. In case the Descriptor is defined in Object Repository, you have to unlink from Object Repository it if you want to indicate a Descriptor only for the current activity.
  • Show in Object Repository - Opens the Object Repository panel with the Descriptor selected.
  • Unlink from Object Repository - Unlinks the Descriptor from Object Repository.
  • Add to Object Repository - Add the current UI element to a library project, from where it can be reused throughout your automation process.
• Work in scope - Choose the browser tab rendering the web application to automate. If you indicated a Java application, it is listed in the drop-down menu among the browser tabs. The option is hidden when only one tab is available.
• Generate - Opens the UI Automation Autopilot Recorder, where you can generate UI Automation workflow sequences. You can also select the Generate the UI automation activities using Autopilot icon from the top right corner of the informative screenshot box. For more details, check out the UI Automation Autopilot Recorder page.
• URL - The URL of the web application. The value is automatically filled after choosing the tab. You can also choose to Open URL in a new tab by going to the more options menu. If the URL is already open, you can bring it into focus or open it again in a new tab.
• Requires Authentication? - Enables multi-factor authentication. For more details, check out the UI Automation Browser Connection page.

Additional options

Timings

• Timeout - Specify the amount of time (in seconds) to wait for the activity to be executed before throwing an error. The default value is 30 seconds.

• Continue on error - Specifies if the automation should continue even when the activity throws an error. This field only supports Boolean values (True, False). The default value is False. As a result, if the field is blank and an error is thrown, the execution of the project stops. If the value is set to True, the execution of the project continues regardless of any error.

Options

• Open - Defines whether to open the target application before executing the activities in it.
  • Always - Open the browser window every time.
  • If not open - Open a new browser window, if none matches the selector and the URL. This is the default value.
  • Never - Never open the browser window.
• Close - Defines whether to close the target application before executing the activities in it.
  • Always - Close the browser window every time.
  • If opened by Use Browser - Close only if the browser window was opened by the Use Browser activity. This is the default value.
  • Never - Never close the browser window.
• Input mode - The method used to generate keyboard and mouse input.
  • Chromium API - Performs actions using debugger APIs. Works only for Chromium elements. Sends all text in one go. Works even if target app is not in focus.
  • Simulate - Simulates the action using accessibility APIs. Works for browsers. Sends all text in a single action. Works in the background (even if the target application is not in focus).
• Incognito/private window - If selected, opens the new browser session in incognito/private mode. This field only supports Boolean values (True, False). The default value is False.

• User data folder mode - The user data folder mode you want to set. It is used to start the browser with a specific user data folder.

  • Automatic - Automatically triggers Picture-in-Picture (PiP) mode with a separate user data folder from the default one. If the User data folder path is not set, a folder is automatically generated. This can be helpful when you're looking for browser isolation during automation tasks and keep the data separate from the main browsing session.
  • Default folder - Uses the default browser folder, no matter if it runs in the main browsing session or a PiP session. This option is useful if you want the robot to use the existing user data folder and you don't need a separate or isolated session for automation tasks.
  • Custom folder - Uses the folder specified in User data folder path. If User data folder path is not set,an auto generated path is used. This option gives you more flexibility and control to manage your folders for different automation tasks by setting a custom path for the user data folder.

  Setting the browser user data folder is only available for Chrome, Edge Chromium and Firefox.

• User data folder path - The user data folder that the browser uses. Defaults to %LocalAppData%\UiPath\PIP Browser Profiles\BrowserType if not set.

Target

• Match exact title - Available only for desktop applications. When set to On, only applications that exactly match the current title are used in the automation. When set to Off, the window with the closest matching title are used in the automation. The default value is Off.
• Selector - List of attributes used to find a particular browser window.
• Arguments - Parameters to pass to the target application at startup.

Input/Output

• Input element - The UI element on which the activity is executed, stored in an UIElement object. This field supports only UIElement objects. This object can be obtained from the Output Element property field of other UI Automation activities.
• Output element - Outputs a target UI Element and stores it in a UIElement object, which can be further used to target the same element with other activities.