Jenkins 插件

此插件允许您构建和部署 UiPath 自动化流程，以及运行 UiPath 自动化测试用例。

要打包使用 UiPath Studio 2020.10 及更高版本创建的项目，您需要使用此扩展程序的 2.1 及更高版本。

先决条件

• 在 Windows 或 Linux 上运行的 Jenkins 服务器。
• 至少一个在 Windows 上运行的 Jenkins 从属节点（执行步骤所必需）。

• Orchestrator 实例（支持基本身份验证、联合身份验证或云身份验证）。

  • 测试功能需要 Orchestrator 2020.4 或更高版本。
  • 在 HTTPS 下使用内部部署 Orchestrator 时，请确保导入 SSL 证书，以便可以信任对 Orchestrator 的 HTTPS 调用。

安装并启用插件

可以使用“插件管理器”屏幕从连接到互联网的任何 Jenkins 安装中安装 Jenkins 插件。

作业

UiPath 运行作业

“UiPath 运行作业”构建后步骤将启动已在 Orchestrator 实例上部署的流程。在 Orchestrator 2020.10 版本中，您可以在“流程”选项卡中找到此任务运行的流程。在 Orchestrator 2021.10 及更高版本中，您可以在“流程”下的“自动化”中找到此任务运行的流程。

配置

作业参数	描述
流程（必填）	流程名称。 您可以从 Orchestrator 用户界面获取流程名称。 如果流程部署在新式文件夹中，则此参数应为“流程”选项卡中的 流程 名称。 如果流程部署在传统文件夹中，则参数必须由流程的 名称 和 环境 组成（例如： NAME: ProcessA ENVIRONMENT: Production ProcessName: ProcessA_Production ）。
参数	JSON 输入文件的完整路径。 当流程需要输入时使用。 JSON 文件格式示例： { "StringArgument_In": "MyConfigurationValue", "IntArgument_In": 1, "DictionaryArgument_In": { "Key1": "Value1", "Key2": "Value2" } }
优先级	运行作业优先级。
策略	指定作业运行策略、已动态分配的作业，或者机器人指定的作业。选择以下选项之一： 动态分配 特定机器人
作业类型 （仅适用于新式文件夹）	选择要用于执行作业的运行时的许可模式。
Orchestrator 地址	您将在其中运行流程的 Orchestrator 实例的地址。
Orchestrator 租户	指定 Orchestrator 租户。
Orchestrator 文件夹	指定部署指定流程的文件夹。 要输入子文件夹，请确保同时输入父文件夹的名称和子文件夹的名称。例如，AccountingTeam\TeamJohn。
身份验证	要对 Orchestrator 进行身份验证，您需要预先在 Jenkins 中创建凭据。 有四个用于身份验证的选项： (1) 使用用户名和密码对本地部署 Orchestrator 进行身份验证。 ( 2 ) 使用刷新令牌（API 密钥）对 Cloud Orchestrator 进行身份验证。 (3) 使用 外部应用程序身份验证向 Cloud Orchestrator 进行身份验证。 (4) 使用 外部应用身份验证对本地部署 Orchestrator 进行身份验证。
作业结果输出路径	指定作业结果的输出路径（例如testResults.json ）。 结果以 JSON 格式输出。 若未获指定，结果将以 UiPathResults.json 形式输出到工件阶段目录中。输出结果为 JSON 格式。
超时	指定作业运行的超时时间 (以秒为单位)。
作业失败即失败	至少有一个作业失败时，任务失败。默认值为 TRUE。
等待作业完成	等待作业运行完成。默认值为 TRUE。
追踪日志记录级别	用于启用跟踪日志记录的设置为以下级别之一： 无 重要事项 错误 Warning 信息 详细。 （默认设置为“ 无”）。 可用于调试目的。
作业数	作业运行数。默认值为 1。
用户（仅适用于新式文件夹）	用户名。此用户不可为计算机用户或 Orchestrator 用户。 对于本地用户，格式应为 MachineName\UserName。
计算机（仅适用于新式文件夹）	计算机名称。
机器人名称	指定机器人名称的逗号分隔列表。

管道示例

pipeline {
  agent any
  environment {
      MAJOR = '1'
      MINOR = '0'
  }
  stages {
    stage ('Build') {
        UiPathRunJob(
          credentials: UserPass('825c83c9-9a14-44eb-883a-af54f8078af0'),
          failWhenJobFails: true,
          folderName: 'A_Classic',
          orchestratorAddress: 'https://testorchestrator.some-domain.com',
          orchestratorTenant: 'Default',
          parametersFilePath: '',
          priority: 'Low',
          processName: 'ProcessA_EnvB',
          resultFilePath: 'output.json',
          strategy: Dynamically(jobsCount: 1, machine: 'TestMachine', user: 'TestUser'), timeout: 3600, waitForJobCompletion: true, traceLoggingLevel: 'None'
        )
        UiPathRunJob(
          credentials: UserPass('825c83c9-9a14-44eb-883a-af54f8078af0'),
          failWhenJobFails: true,
          folderName: 'A_Classic',
          orchestratorAddress: 'https://testorchestrator.some-domain.com',
          orchestratorTenant: 'Default',
          parametersFilePath: '',
          priority: 'Low',
          processName: 'ProcessA_EnvB',
          resultFilePath: 'output.json',
          strategy: Robot('robot1,robot2'),
          timeout: 1800,
          waitForJobCompletion: false,
          traceLoggingLevel: 'None'
        )
    }
  }
}

UiPath 管理资产

“ UiPath 管理资产 ”步骤使您能够部署、更新或删除 Orchestrator 实例上的资产。 要部署资产，您必须在 CSV 文件中对其进行描述，如下例中以uft-8编码的文件所示。

name,type,value,description
asset_1_name,text,asset_value,this is an test description   # we can have comments
asset_2_name,integer,123
asset_3_name,boolean,false
asset_4_name,credential,"username::password"

资产分为四种类型：

• 文本
• 整数
• 布尔值
• 凭据。对于凭据，您必须通过使用 :: 分隔两个字段来对用户名和密码进行编码。
  
  

  

  
  

配置

作业参数	描述
操作	如何处理提供的资产：部署或删除。 如果已部署的资产存在，则系统将对其进行更新。
Orchestrator 地址	您将在其中部署或更新资产的 Orchestrator 实例的地址。
Orchestrator 租户	指定系统用以对资产进行部署或更新的 Orchestrator 租户。
Orchestrator 文件夹	指定将部署或更新资产的文件夹。 要输入子文件夹，请确保同时输入父文件夹的名称和子文件夹的名称。例如，AccountingTeam\TeamJohn。
身份验证	要对 Orchestrator 进行身份验证，您需要预先在 Jenkins 中创建凭据。 有四个用于身份验证的选项： (1) 使用用户名和密码对本地部署 Orchestrator 进行身份验证。 ( 2 ) 使用刷新令牌（API 密钥）对 Cloud Orchestrator 进行身份验证。 (3) 使用 外部应用程序身份验证向 Cloud Orchestrator 进行身份验证。 (4) 使用外部应用程序身份验证向本地部署 Orchestrator 进行身份验证。
CSV 文件路径	包含资产详细信息的 CSV 文件的路径。 同一文件可用于部署或更新资产，但更新不需要该类型。 type字段也可以为空，但列必须存在。 对于删除，仅使用name列，因此其他列可以为空，但必须存在。 您可以为每个资产设置可选说明（例如： type 、 value 、 description ）。 请确保删除所有换行符，因为每一行都将被解释为新资产。
追踪日志记录级别	用于启用跟踪日志记录的设置为以下级别之一： 无 重要事项 错误 Warning 信息 详细。 （默认设置为“ 无”）。 可用于调试目的。

管道示例

pipeline {
  agent any
  environment {
      MAJOR = '1'
      MINOR = '0'
  }
  stages {
    stage ('Build') {
        UiPathAssets (
            assetsAction: DeployAssets(), 
            credentials: Token(accountName: '', credentialsId: ''), 
            filePath: '${WORKSPACE}/test.csv', 
            folderName: 'Default', 
            orchestratorAddress: 'https://test-orchestrator.somedomain.com', 
            orchestratorTenant: 'Default',
            traceLoggingLevel: 'None'
        )
        UiPathAssets(
            assetsAction: DeleteAssets(),
            credentials: UserPass('825c83c9-9a14-44eb-883a-af54f8078af0'),
            filePath: '${WORKSPACE}/test.csv',
            folderName: 'Default',
            orchestratorAddress: 'https://test-orchestrator.somedomain.com',
            orchestratorTenant: 'Default',
            traceLoggingLevel: 'None'
        )
    }
  }
}

UiPath 包

应用程序： RPA

类型： 构建任务

UiPath Pack 在标准作业和管道中提供，可用于将现有 UiPath 项目打包到 NuGet 包中。

配置

作业参数	描述
选择版本控制方法	UiPath 包已进行版本控制。 使用 UiPath 包，您可以在 3 个不同的选项之间进行选择： (1) 自动生成 (2) 定义自定义版本 (3) 使用项目中设置的当前版本。
项目路径	待打包项目所在位置。该位置可为 project.json 文件的直接路径，或包含一个或多个项目的目录。如果是后者，则针对每个级别，系统均会分别打包每个项目。
OutputFolder	要在其中创建包的文件夹的路径。
输出类型	项目的输出类型。 项目类型有 5 个选项： (1) 项目的输出类型 (2) 打包流程项目 (3) 打包库项目 (4) 打包测试项目 (5) 打包对象项目。
运行工作流分析	在打包之前运行工作流分析，通过预定义的规则检查项目是否存在违规行为。 在出现错误时使作业失败。 默认情况下，不运行分析。
追踪日志记录级别	用于启用跟踪日志记录的设置为以下级别之一： 无 重要事项 错误 Warning 信息 详细。 （默认设置为“ 无”）。 可用于调试目的。
使用 Orchestrator	打包库时使用 Orchestrator 订阅源。 Orchestrator 必须为 20.4 或更高版本。 库订阅源需要允许在“ 租户 ” >“ 设置 ” >“ 部署”中进行 API 密钥身份验证。
Orchestrator 地址	还原库依赖项的 Orchestrator 实例地址。
Orchestrator 租户	应从中还原库依赖项的 Orchestrator 租户。
身份验证	要对 Orchestrator 进行身份验证，您需要预先在 Jenkins 中创建凭据。 有四个用于身份验证的选项： (1) 使用用户名和密码对本地部署 Orchestrator 进行身份验证。 ( 2 ) 使用刷新令牌（API 密钥）对 Cloud Orchestrator 进行身份验证。 (3) 使用 外部应用程序身份验证向 Cloud Orchestrator 进行身份验证。 (4) 使用 外部应用身份验证对本地部署 Orchestrator 进行身份验证。

管道示例

ipeline {
  agent any
  environment {
      MAJOR = '1'
      MINOR = '0'
  }
  stages {
    stage ('Build') {
      steps {
        UiPathPack (
          outputPath: "Output\)\)\)\)${env.BUILD_NUMBER}",
          projectJsonPath: "UiBank\)\)\)\)project.json",
          version: [$class: 'ManualVersionEntry', version: "${MAJOR}.${MINOR}.${env.BUILD_NUMBER}"]
          useOrchestrator: true,
          traceLoggingLevel: "None",
          orchestratorAddress: "OrchestratorUrl",
          orchestratorTenant: "tenant name",
          credentials: [$class: 'UserPassAuthenticationEntry', credentialsId: “credentialsId”]
        )
      }
    }
  }
}

UiPath 部署

应用程序： RPA

类型： 构建后任务

UiPath Deploy 在标准作业和管道中提供，可让您将 UiPath NuGet 包部署到 UiPath Orchestrator 上。

配置

作业参数	描述
包路径	包含 UiPath Nuget 包的文件夹。
Orchestrator 地址	用以对包进行部署的 Orchestrator 实例地址。
Orchestrator 租户	用以对包进行部署的 Orchestrator 租户。
Orchestrator 文件夹	待部署的文件夹。如果此文件夹为传统文件夹，您还将需要设置 environments 字段。对于新式文件夹，则无需设置 environments 字段。 要输入子文件夹，请确保同时输入父文件夹的名称和子文件夹的名称。例如，AccountingTeam\TeamJohn。
环境 （传统文件夹为必需 ）	将包部署为流程的环境。对于包含现有流程的项目和环境，系统将更新流程，使其使用最新的项目版本。指定系统将包部署为流程的环境。对于包含现有流程的项目和环境，系统将更新流程，使其使用最新的项目版本。
入口点	指定入口点以创建或更新流程。入口点指定从项目根目录开始的 filePath。 条件： 入口点可用于 Orchestrator 21.4 或更高版本（例如 21.4.UiPathDeploy.entryPoints)。对于低于 21.4 的 Orchestrator 版本，您需要输入任何值，因为该字段不得留空。 默认入口点设置为 Main.xaml。 对于传统文件夹（已弃用），您只能为每个环境指定一个入口点。 有关详细信息，请参阅“Orchestrator 入口点”。
身份验证	要对 Orchestrator 进行身份验证，您需要预先在 Jenkins 中创建凭据。 有四个用于身份验证的选项： (1) 使用用户名和密码对本地部署 Orchestrator 进行身份验证。 ( 2 ) 使用刷新令牌（API 密钥）对 Cloud Orchestrator 进行身份验证。 (3) 使用 外部应用程序身份验证向 Cloud Orchestrator 进行身份验证。 (4) 使用外部应用程序身份验证向本地部署 Orchestrator 进行身份验证。
追踪日志记录级别	用于启用跟踪日志记录的设置为以下级别之一： 无 重要事项 错误 Warning 信息 详细。 （默认设置为“ 无”）。 可用于调试目的。

备注：

确保您的网络允许访问以下 NuGet 包订阅源:

• https://api.nuget.org/v3/index.json
• https://uipath.pkgs.visualstudio.com/_packaging/nuget-packages/nuget/v3/index.json
• https://uipath.pkgs.visualstudio.com/Public.Feeds/_packaging/UiPath-* Internal/nuget/v3/index.json
• https://www.myget.org/F/workflow
• http://www.myget.org/F/uipath
• https://www.myget.org/F/uipath-dev/api/v3/index.json

管道示例

pipeline {
  agent any
  environment {
      MAJOR = '1'
      MINOR = '0'
  }
  stages {
    stage ('PostBuild') {
      steps {
        UiPathDeploy (
          packagePath: "path\)\)\)    o\)\)NuGetpackage",
          orchestratorAddress: "OrchestratorUrl",
          orchestratorTenant: "tenant name",
          folderName: "folder name",
          environments: "environment",
          credentials: [$class: 'UserPassAuthenticationEntry', credentialsId: “credentialsId”],
          traceLoggingLevel: 'None'
        )
      }
    }
  }
}

UiPath 运行测试

应用程序：测试

类型： 构建后任务

UiPath Run 测试 可在标准作业和管道中使用，并允许您：

• 在 Orchestrator 中运行现有测试集。
• 通过指定 UiPath 测试项目的路径，打包、部署和运行测试用例。

测试运行完成后，“ 测试结果 ” 选项卡将发布到 Jenkins 内部版本，并显示详细结果。 此外，系统还会在测试结果输出路径（如果指定）中创建 JUnit 测试结果文件，如果未指定，则会在工作区根目录中创建。

根据结果，构建将被标记为成功（所有测试用例都通过）或不稳定（至少一个测试用例失败）。

配置

作业参数	描述
目标	在 UiPath Orchestrator 上指定现有测试集（以执行测试集）。 提供 UiPath 测试项目的project.json路径（以执行测试项目）。
测试结果输出路径	已执行的测试集将测试结果返回为junit.xml 。 指定应存储结果的路径，相对于 Jenkins 工作区目录（例如result.xml ）。
输入参数	为测试用例定义自定义参数，以覆盖测试集级别的默认值。通过参数，您可以在运行时参数化测试用例。要定义参数，您需要发布包含参数的包。
Orchestrator 地址	用以对包进行部署的 Orchestrator 实例地址。
Orchestrator 租户	用以对包进行部署的 Orchestrator 租户。
Orchestrator 文件夹	待部署的文件夹。 如果此文件夹为传统文件夹，您还将需要设置 environments 字段。 对于新式文件夹，设置environments 。不是必需的。 要输入子文件夹，请确保同时输入父文件夹的名称和子文件夹的名称。例如，AccountingTeam\TeamJohn。
环境 （传统文件夹为必需 ）	将包部署为流程的环境。对于包含现有流程的项目和环境，系统将更新流程，使其使用最新的项目版本。指定系统将包部署为流程的环境。对于包含现有流程的项目和环境，系统将更新流程，使其使用最新的项目版本。
身份验证	要对 Orchestrator 进行身份验证，您需要预先在 Jenkins 中创建凭据。 有四个用于身份验证的选项： (1) 使用用户名和密码对本地部署 Orchestrator 进行身份验证。 ( 2 ) 使用刷新令牌（API 密钥）对 Cloud Orchestrator 进行身份验证。 (3) 使用 外部应用程序身份验证向 Cloud Orchestrator 进行身份验证。 (4) 使用外部应用程序身份验证向本地部署 Orchestrator 进行身份验证。
超时 (秒)	测试运行的执行超时。 默认值为 7200 秒。 如果在 Orchestrator 上的执行完成并返回结果之前超时，则构建将取消并标记为失败。
追踪日志记录级别	用于启用跟踪日志记录的设置为以下级别之一： 无 重要事项 错误 Warning 信息 详细。 （默认设置为“ 无”）。 可用于调试目的。

管道示例

pipeline {
  agent any
  environment {
    MAJOR = '1'
    MINOR = '0'
  }
  stages {
    stage ('PostBuild') {
      steps {
        UiPathTest (
          testTarget: [$class: 'TestSetEntry', testSet: "My Test Set"],
          orchestratorAddress: "OrchestratorUrl",
          orchestratorTenant: "tenant name",
          folderName: "folder name",
          timeout: "10000",
          traceLoggingLevel: 'None',
          testResultsOutputPath: "result.xml",
          credentials: [$class: 'UserPassAuthenticationEntry', credentialsId: "credentialsId"]
        )
      }
    }
  }
}

获取 Cloud Orchestrator API 密钥

为外部应用程序配置服务连接

步骤 1：配置外部应用程序和作用域。 添加应用程序后，请保留应用程序 ID、密码和应用程序作用域，以便在下一步中使用。

注意：如果您生成并使用新密码，则旧密码将失效。

步骤 2： 在 Jenkins 中将应用程序凭据配置为密码文本。 对于此步骤，您需要在 Automation Cloud 中生成的密码。

步骤 3：在“构建后操作”下为每个任务配置身份验证，方法是添加“帐户名称”，后跟“应用程序 ID”、“密码”和“通过 Automation Cloud 生成的应用程序作用域”。

注意： 考虑在各个管道中使用外部应用程序，以避免失效错误。

附加信息

• 指定的所有路径都应为当前工作区的本地路径。 您可以在路径中使用环境变量，但应确保它们生成的路径是工作区的本地路径。
• 要部署包或运行测试，请确保经过身份验证的用户具有“ 文件夹视图” （或 “组织单元视图”）和（仅限 20.4+ ） “后台任务视图” 权限。
• 要打包库，请确保在连接到 Orchestrator 实例时，经过身份验证的用户具有“ 库查看” 权限。

• 有关管理外部应用程序的更多详细信息：

  • 对于 Cloud Orchestrator - 请参阅 官方文档。
  • 对于内部部署 Orchestrator - 请参阅官方文档。

Jenkins 插件故障排除

如果遇到安装或升级问题，请考虑以下故障排除方案：

未经授权的错误

说明: 未经授权的错误。

补救措施：

• 如果您使用 基本身份验证：确保网页登录名中的用户名-密码组合正确。

  如果启用了联合身份验证，请确保在任务中将用户名写入“DOMAIN\user”

• 如果您使用 令牌身份验证：

  • 从 API 访问面板撤消令牌并生成新令牌。
  • 确保生成密钥的用户可以访问 Orchestrator，并且在 Orchestrator 实例上拥有用户帐户。
• 如果您 针对内部部署的 Orchestrator 进行身份验证：确保 Orchestrator 证书有效，并且运行作业的计算机信任 Orchestrator 证书，以防您使用自签名证书。 由于 Orchestrator 使用的证书无效，您可能会收到此错误。 这可能意味着它存在错误的 CN 或其他验证问题。

禁止的错误

解决方法：用户无权执行该操作。 确保用户有权读取文件夹、上传包、创建和更新流程、读取测试集和测试用例、读取后台任务以及创建和运行测试集。

未找到文件夹/环境

解决方法：确保 CI/CD 插件使用的经过身份验证的用户具有 Folders.View 和 BackgroundTask.View （仅适用于 20.4）权限。

包已存在 (冲突)

解决方法：确保您尝试部署的包不存在具有相同版本的包。 如果存在，请考虑使用自动包版本控制，以便在每次部署时升级新版本。

运行命令失败 (一般错误)

解决方法：如果 Jenkins 工作区位于磁盘上用户无权访问的位置（例如C:\Windows or C:\Program Files ），请确保将工作区放置在用户可以访问的路径上。

Jenkins 无法处理包含非拉丁字符的路径

解决方法：调用 UiPath 插件时，Jenkins 无法正确传递非标准编码字符。 未知字符将替换为??? 。

该解决方案取决于 Jenkins 在服务器和代理主机上的部署方式，但需要在 Java 选项中将file.encoding设置为 UTF-8：

Windows

在 Windows 上作为服务运行 Jenkins 时：在服务配置文件中，在标签内添加参数。 请按照以下示例脚本操作。

<arguments>-Xrs -Xmx512m -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -Dfile.encoding=UTF-8 -jar "%BASE%\)\)jenkins.war" --httpPort=8080 --webroot="%BASE%\)\)war"</arguments>

在 Docker 中运行 Jenkins 时：按照以下示例脚本，通过--env JAVA_OPTS="..."将 JAVA_OPTS 传递给容器。

docker run --name myjenkins -p 8080:8080 -p 50000:50000 --env JAVA_OPTS=-Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -Dfile.encoding=UTF-8 jenkins/jenkins:lts

在 Tomcat 中运行 Jenkins 时：使用环境变量CATALINA_OPTS 。 请按照以下示例脚本操作。

export CATALINA_OPTS="-DJENKINS_HOME=/path/to/jenkins_home/ -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -Dfile.encoding=UTF-8 -Xmx512m"

Linux

在基于 Debian 或 Ubuntu 的 Linux 发行版上运行时：在配置文件中搜索参数JAVA_ARGS ，并添加文件编码。 请按照以下示例脚本操作：

JAVA_ARGS="-Dfile.encoding=UTF-8 -Xmx512m"

在基于 RedHat Linux 的发行版上运行时：在配置文件中搜索参数 JENKINS_JAVA_OPTIONS 并添加文件编码。 请按照以下示例脚本操作。

JENKINS_JAVA_OPTIONS="-Dfile.encoding=UTF-8 -Xmx512m"