UiPath Integration for Azure DevOps
About this extension
This extension allows you to build and deploy UiPath automation processes, as well as run UiPath automated test cases.
In order to pack projects created with UiPath Studio starting from 20.10, you need to use a version starting from 2.1 of this extension.
Prerequisites
- Task execution must be performed on a Windows-based build agent
- Orchestrator instance (basic, federated or cloud authentication are supported)
- Testing features require Orchestrator version 20.4 or newer
- When using an on-premise Orchestrator under HTTPS, make sure to import the SSL Certificate so that the HTTPS calls to Orchestrator can be trusted
Tasks
▶ UiPath Run Job
The UiPathRunJob task starts an already deployed process on an Orchestrator
instance. The processes this task refers to are found in Automations->Processes
on newer versions of Orchestrator and directly on the Processes tab on older
versions of Orchestrator.
📖 YAML snippet:
- task: UiPathRunJob@2
displayName: 'Start ProcessProject'
inputs:
#orchestratorConnection: 'service-connection-name' # Service connection to UiPath Orchestrator
#processName: 'ProccessProject_CI-Pipeline' # The name of the process
#parametersFilePath: 'Input\\jobParameters.json' # json file with input values if the process requires them
#priority: 'Low' # Options 'Low', 'Normal', 'High'
#folderName: 'MyFolder' # Specify the folder to deploy to. For clasic folders, you can use specific robot names. For modern folders, you can use specific user and machine names.
#strategy: 'Dynamically' # Options 'Specific', 'Dynamically'
#jobCount: 1 # The number of job runs. (default 1) - used if strategy is 'Dynamically'
#user: 'MyUser'
#machine: 'machine'
#robotsIds: 'robot1, robot2'
#resultFilePath: 'Output\\testResults.json'
#timeout: 3600
#failWhenJobFails: false
#waitForJobCompletion: false,
#traceLevel: 'None' # Options: Critical, Error, Warning, Information, Verbose, None
⚙️ Configuration
| Argument |
Description |
| orchestratorConnection |
(Required) A service connection to an Orchestrator instance on which a Process will be started. |
| processName |
(Required) Process name. You can take the process name from the Orchestrator UI. If the process is deployed in a Modern Folder then this argument should be the NAME of the process in the Processes tab. If the process is deployed in a Classic Folder, then the argument must be formed by the NAME of the process and the ENVIRONMENT (eg: NAME: ProcessA ENVIRONMENT: Production ProcessName: ProcessA_Production). |
| parametersFilePath |
Specify the full path to a json input file, e.g. Input\jobParameters.json. |
| jobType |
This feature is available only on modern folders! Choose the license model of the runtime under which the job is to be executed. |
| priority |
The job run priority. (default Normal) |
| folderName |
(Required) Specify the folder to deploy to. For classic folders, you can use specific robot names. For modern folders, you can use specific user and machine names. |
| strategy |
Specify the job run strategy, dynamically allocated job(s) or robot specific job(s). Options: Dynamically, Specific |
| resultFilePath |
Specify the output full path of the job results, e.g. Output\testResults.json. The results are output in json format. If not specified, the results are output to the artifact staging directory as UiPathResults.json. The output is in json format. |
| timeout |
Specify the job run(s) timeout in seconds. |
| failWhenJobFails |
The task fails when at least one job fails. (default true) |
| waitForJobCompletion |
Wait for job run(s) completion. (default true) |
| traceLevel |
Setting used to enable the trace logging to one of the following level: None, Critical, Error, Warning, Information, Verbose. (default None). Useful for debugging purposes. |
|
Parameters used for strategy Dynamically |
| jobCount |
The number of job runs. (default 1) |
| user |
The name of the user. This feature is available only on modern folders! This should be a machine user, not an orchestrator user. For local users, the format should be MachineName\UserName |
| machine |
The name of the machine. This feature is available only on modern folders! |
|
Parameters used for strategy Specific |
| robotsIds |
Comma-separated list of specific robot names. |
💼 UiPath Manage Assets
The UiPathManageAssets step enables you to deploy, update or delete assets on an Orchestrator instance. In order to deploy assets, you must describe them in a CSV file encoded in UTF-8 like the one in the example below
name,type,value, description
asset_1_name,text,asset_value,
asset_2_name,integer,123,asset_3_name,boolean,false, this is an asset description asset_4_name,credential,"username::password",
There are 4 types of assets text, integer, boolean and credential. For
the credential you must encode the username and password by using :: to
separate the two fields.
📖 YAML snippet:
- task: UiPathAssets@2
displayName: 'Deploy/Update assets'
inputs:
#orchestratorConnection: 'service-connection-name' # Service connection to UiPath Orchestrator
#assetActionType: 'Deploy' # Options: Deploy, Delete
#csvFile: 'assets_deploy.csv' # the path to the csv file containing the assets description,
#traceLevel: 'None' # Options: Critical, Error, Warning, Information, Verbose, None
⚙️ Configuration
| Argument |
Description |
| assetActionType |
(Required) What to do with the provided assets: deploy or update. You can only deploy an asset with the same key (name) once.
Options: Deploy, Delete |
| csvFile |
(Required) The path to the csv file containing the asset details. The same file can be used to deploy or update the assets although the type isn't required for update. The type field can also be empty but the column must be present. For delete, only the name column is used, so the other columns can be empty but they must be present. Optionally a description can be set for each asset with the following syntax: type, value , description |
| Please make sure that the description does not include any line breaks. Those would be interpreted as a new asset. |
|
| folderName |
Required. The folder to deploy to. If the folder is a classic folder, you will also need to set the environments argument. For modern folders, setting the environments is not required. |
| orchestratorConnection |
(Required) A service connection to an Orchestrator instance whose assets we want to manage. |
| traceLevel |
Setting used to enable the trace logging to one of the following level: None, Critical, Error, Warning, Information, Verbose. (default None). Useful for debugging purposes. |
The UiPathInstallPlatform has a prepackaged tool that all the other UiPath tasks are using. This will make it unnecessary for the other tasks to download the tool from https://www.myget.org/F/uipath-dev/. The task is optional, but it should be used as it reduces the time to execute the other tasks. The task is required when build agents do not have access to https://www.myget.org/F/uipath-dev/. The task should be executed before all other tasks in the extension.
📖 YAML snippet:
- task: UiPathInstallPlatform-preview@2
displayName: 'Install platform to cache internal tool'
📦 UiPath Pack
The UiPathPack task enables you to package an existing UiPath project into a NuGet package.
📖 YAML snippet:
- task: UiPathPack@2
inputs:
#versionType: AutoVersion # Options: AutoVersion, CurrentVersion, ManualVersion
#version: '1.0.0' # Required when versionType == ManualVersion
#projectJsonPath: '$(Build.SourcesDirectory)\MyFirstProcess'
#outputPath: '$(Build.ArtifactStagingDirectory)\Packages\MyFirstProcess'
#outputType: 'None' # Options: Process, Library, Tests, Objects, None
#runWorkflowAnalysis: 'False'
#orchestratorConnection: 'service-connection-name' # Service connection to UiPath Orchestrator,
#traceLevel: 'None' # Options: Critical, Error, Warning, Information, Verbose, None
⚙️ Configuration
| Argument |
Description |
| versionType |
Required. UiPath package versions can be generated automatically, manually from a specified version, or read from the project file. Auto-generating the version works similarly to how Studio performs the versioning when publishing a package. |
| projectJsonPath |
Required. The location of the project(s) to be packaged. It can be a direct path to a project.json file or a directory with one or multiple projects. In the latter case, each level one project is packaged individually. |
| outputPath |
Required. Path to a folder, where the created package(s) should be placed. |
| version |
Required only when using manual versioning. Specifying the package version provides the possibility of tracking the built packages and their source versioning more efficiently. For example, the Microsoft assembly pattern can be utilized to build the NuGet package version: [Major].[Minor].[BuildNumber].[RevisionNumber]. |
| outputType |
'Process' | 'Library' | 'Tests' | 'Objects' | 'None'
The way in which the project is packed. If None is selected then the project will be picked from the projects json file. |
| runWorkflowAnalysis |
Run the workflow analysis before packing, checking the project via predefined rules for violations. Fail the job in case of errors. By default the analysis is not run. |
| orchestratorConnection |
A service connection to a Orchestrator instance that has on it's feed dependencies of the project(s) to be packed. Usually used for packing libraries. The Orchestrator must be 20.4 or higher. The library feed needs to allow API Key authentication in Tenant -> Setting -> Deployment. |
| traceLevel |
Setting used to enable the trace logging to one of the following level: None, Critical, Error, Warning, Information, Verbose. (default None). Useful for debugging purposes. |
🚀 UiPath Deploy
The UiPathDeploy task lets you deploy a UiPath NuGet package onto UiPath Orchestrator.
📖 Pipeline Example:
- task: UiPathDeploy@2
inputs:
#orchestratorConnection: # Service connection to UiPath Orchestrator
#packagesPath: '$(Build.ArtifactStagingDirectory)\Packages\ITAutomationProcess'
#folderName: 'ITAutomation'
#environments: 'AutomationRobots' # Optional,
#traceLevel: 'None' # Options: Critical, Error, Warning, Information, Verbose, None
⚙️ Configuration
| Argument |
Description |
| packagesPath |
Required. The path to your UiPath NuGet package(s). |
| orchestratorConnection |
Required. A service connection to the Orchestrator instance onto which we will deploy the package. |
| folderName |
Required. The folder to deploy to. If the folder is a classic folder, you will also need to set the environments argument. For modern folders, setting the environments is not required. |
| environments |
Optional. Required only when using a classic folder and wanting to also create or update processes for this pacakge, otherwise not applicable. The environment(s), separated by a comma, onto which the package will be deployed as a process. |
| entryPoints |
Required. Specify entry points to create or update a process. The entry point specifies the filePath starting from the root of the project.
Conditions:- Entry points are available for Orchestrator version 21.4 or higher (e.g. 21.4.UiPathDeploy.entryPoints). For Orchestrator versions lower than 21.4, you need to enter any value, as the field must not remain empty.
- Default entry point set to
Main.xaml. - For classic folders (deprecated) you can specify only one entry point for each environment
For more information, see Orchestrator Entry Points. |
| traceLevel |
Setting used to enable the trace logging to one of the following level: None, Critical, Error, Warning, Information, Verbose. (default None). Useful for debugging purposes. |
Note :
Make sure that your network allows access to the following NuGet package feed:
▶ UiPath Run tests
The UiPathTest task runs an existing test set on Orchestrator, or packages, deploys and runs test cases as a transient test set in one go, by specifying the path to a UiPath test project.
After the test run has finished, the test results will be uploaded to AzureDevOps and can be viewed in the Tests tab. Additionally, a JUnit test results file will be output to the test result output path, when specified.
Depending on the result, the build will be either marked as successful (all test cases are passed), or failed (at least one test case failed).
📖 Pipeline Example:
- task: UiPathTest@2
inputs:
#testTarget: TestProject # Options: TestProject, TestSet
#orchestratorConnection: # Service connection to UiPath Orchestrator
#testProjectPath: '$(Build.SourcesDirectory)\MobileAutomationTests' # Required only when testTarget = TestProject
#testSet: 'MobileAutomationTests' # Required only when testTarget = TestSet
#folderName: 'MobileAutomationTesting'
#environment: 'TestingRobots' # Required only when testTarget = TestProject and the folder is a classic folder
#testReportDestination: '$(Build.ArtifactStagingDirectory)\report.xml' # Optional
#timeout: 200 # Optional, default = 3600s,
#traceLevel: 'None' # Options: Critical, Error, Warning, Information, Verbose, None
⚙️ Configuration
| Argument |
Description |
| testTarget |
Required. If the target is TestSet, the task will execute a test set and you will need to specify the testSet parameter value. If the target is TestProject, you will need to provide the testProjectPath and the environment (only needed if running in a classic folder). |
| testProjectPath |
Required when testTarget = TestProject. The location of a test project to be deployed in Orchestrator and executed as part of a transient test set. |
| testSet |
Required when testTarget = TestSet. The name of a pre-existing test set on the Orchestrator. |
| testReportDestination |
Optional. Specify the path where the test results should be stored. The test results are saved in JUnit format. |
| orchestratorConnection |
Required. A service connection to the Orchestrator instance on which we will run the tests. |
| folderName |
Required. The folder to run the tests in. If the folder is a classic folder and testTarget = TestProject, you will also need to set the environment field. For modern folders, setting the environments is not required. |
| environment |
Optional. Required only when using a classic folder and testTarget = TestProject. |
| timeout |
Optional. The execution timeout for the test run. The default value is 3600 seconds. If the timeout exceeds before the execution on Orchestrator is finished, the build will cancel and be marked as failed. |
| traceLevel |
Setting used to enable the trace logging to one of the following level: None, Critical, Error, Warning, Information, Verbose. (default None). Useful for debugging purposes. |
Creating the Service Connection
For the UiPathDeploy and UiPathTest tasks you will need to first create a Service Connection. To do this, open your AzureDevOps project page, e.g. https://myorg.visualstudio.com/MyProject, go to Settings -> Service Connections -> UiPath Orchestrator Connection and add the service connection details.
If you're using an on-premise Orchestrator instance, you will likely want to use basic authentication, with either your normal username or, if federated authentication is enabled, your federated user, e.g. MYDOMAIN\me.
Step 1: Configure your external application and scopes in Automation Cloud.
After adding the application, keep the App ID, Secret and Application Scopes at hand, to be used for the next step.
Note: If you generate and use a new Secret, the old one is going to be invalidated.
Step 2: Create a service connection in your pipeline and configure the Account Name, Tenant and add the App ID, Secret and Application Scopes generated through Automation Cloud.
Working with an external application: When you configure your pipeline, select this new service connection as the Orchestrator connection.
Note: Consider using the external app in individual pipelines to avoid invalidation errors.
To learn how to configure connections to Orchestrator instances hosted on Automation Cloud, see the explanation below.
How to set the connection arguments for an Automation Cloud Orchestrator
Questions
Do you have any questions regarding the plugin? Ask them here.
Release Notes
For the full list of changes, see Release Notes for Azure DevOps Extension.
