uipath-orchestrator-api-node
    TypeScript icon, indicating that this package has built-in type declarations

    0.8.3 • Public • Published

    Version Documentation Maintenance License: Apache--2.0

    Node.js CI

    uipath-orchestrator-api-node

    UiPath Orchestrator のAPI を、Node.jsから呼び出すライブラリです。

    Table of Contents

    Installation

    $ npm install uipath-orchestrator-api-node

    Quick Examples

    Get a list of Robots

    ロボット一覧を取得してみます。

    const api = new OrchestratorApi(config)
    // まずは認証
    await api.authenticate()
    
    // ロボットを取得する
    const robots: any[] = await api.robot.findAll()
    for (const robot of robots) {
      console.log(robot)
    }

    実行結果

    {
      LicenseKey: null,
      MachineName: 'PBPC0124',
      MachineId: 4,
      Name: 'PBPC0124_kino',
      Username: 'xx\\kino',
      ExternalName: null,
      Description: null,
      Version: '19.10.2.0',
      Type: 'Development',
      HostingType: 'Standard',
      ProvisionType: 'Manual',
      Password: null,
      CredentialStoreId: null,
      UserId: null,
      CredentialType: null,
      RobotEnvironments: 'Main',
      IsExternalLicensed: false,
      Id: 2,
      ExecutionSettings: null }
    {
      ...

    このように、Orchestrator上の情報をAPI経由で取得することができます。

    Search for Robots

    検索条件を指定することで、条件に合致するリソースを検索することもできます。

    const api = new OrchestratorApi(config)
    await api.authenticate()
    
    // ロボットを取得する
    const machinename = 'PBPC0124'
    const userName = 'xx\\kino'
    const robots: any[] = await api.robot.findAll({
      $filter: `MachineName eq '${machinename}' and Username eq '${userName}'`,
    })
    console.log(robots)

    実行結果

    [
      {
      LicenseKey: null,
      MachineName: 'PBPC0124',
      MachineId: 4,
      Name: 'PBPC0124_kino',
      Username: 'xx\\kino',
      ExternalName: null,
      Description: null,
      Version: '19.10.2.0',
      Type: 'Development',
      HostingType: 'Standard',
      ProvisionType: 'Manual',
      Password: null,
      CredentialStoreId: null,
      UserId: null,
      CredentialType: null,
      RobotEnvironments: 'Main',
      IsExternalLicensed: false,
      Id: 2,
      ExecutionSettings: null
    }
    ]

    「`MachineName eq '${machinename}' and Username eq '${userName}'`」などとRobotの プロパティ名とその値を指定することで、条件に一致するRobotを検索することができました。 条件指定は $filter 以外にも $top$select などいくつかありますが、その仕様は API リクエストの構築 のサイトに詳しく書いてあります。

    Documents

    こちら に、サンプルとともにドキュメントを整理しています。

    Development status

    対応状況(2020/08/08時点)

    各APIへの対応状況です。専用のメソッドを用意しているモノに「〇」をつけています。用意していない場合も汎用のメソッドを呼び出す事で、基本的にどのAPIも呼び出すことが可能だと思います。 専用メソッドの実装は気まぐれでやってるので、割と歯抜けでスイマセン。。

    No. リソース 検索
    (findAll)
    検索
    (find)
    作成
    (create)
    更新
    (update)
    削除
    (delete)
    一括更新
    (upload)
    その他 備考
    1 license
    2 machine
    3 robot
    4 user 名前で検索(findByUserName)
    5 process Packageの検索(findPackage)
    Packageの削除(deletePackage)
    Packageのアップロード(uploadPackage)
    Packageのダウンロード(downloadPackage)
    6 release プロセス画面上の「名前」で検索(findByProcessKey)
    7 job ジョブの開始/終了(StartJobs/StopJob)
    8 schedule
    9 log 条件で検索(findByFilter)
    10 auditlog 条件で検索(findByFilter)
    11 queueDefinition 名前で検索(findByName)
    12 queueItem 削除は論理削除
    13 queueOperation TransactionのスタートでqueueItemを取得(getQueueAndStartTransaction)
    Transactionのステータス変更(setTransactionResult)
    14 setting 〇(update) キーで検索(findByKey)
    ファイルからデータ作成(readSettingsFromFile)
    データをExcel出力(save2Excel)
    15 asset Robot毎Asset更新(uploadPerRobot)
    Robot毎Asset検索(findAllEx)
    16 environment
    17 role
    18 folder 名前で検索(findByDisplayName)
    ユーザ割当(assignUsers/removeUser)
    フォルダを参照可能なユーザ検索(getUsers)
    ユーザが参照可能なフォルダ検索(getFolders)
    フォルダ一括削除(removeFolders)
    19 tenants
    20 hostLicense
    21 util 一括ダウンロード(excelDownload)
    ExcelデータPrint(excel2Console)
    22 汎用 getArray
    getData
    postData
    putData
    deleteData

    また、

    を追加しました。

    Preferences

    さて本ライブラリを使用するには、接続するUiPath Orchestratorの情報など、環境設定が必要です。

    UiPath Orchestrator がEnterprise版の場合は、テナント名、OCへログインするユーザ名とパスワードなどを下記のように:

    $ cat config/local.json
    {
      "userinfo": {
        "tenancyName": "default",
        "usernameOrEmailAddress": "admin",
        "password": "xxxxxx"
      },
      "serverinfo": {
        "servername": "https://www.example.com/"
      }
    }

    UiPath Orchestrator がCommunity版の場合は、Community版OC画面から取得できる情報を下記のように:

    $ cat config/local.json
    {
      "serverinfo": {
        "servername": "https://platform.uipath.com/[AccountLogicalName]/[ServiceName]",
        "refresh_token": "[User Key]",
        "tenant_logical_name": "[Tenant Logical Name]",
        "client_id": "[Client Id]]"
      }
    }

    参考: UiPath Orchestrator Community Edition のAPIを呼び出す件と、カスタムアクティビティをつくってみた

    もしくは、Enterprise/Community にかかわらず、APIをワークフローから呼び出すつまり「Orchestrator への HTTP 要求」アクティビティと同等にしたい場合は、下記の設定画面から取得できる情報を用いて

    001.png

    以下のように設定します。

    {
      "robotInfo": {
        "machineKey": "4eccxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx[マシンキー]",
        "machineName": "[マシン名]",
        "userName": "xx\\xxxx[Windowsアカウント]"
      },
      "serverinfo": {
        "servername": "https://www.example.com/"
      }
    }

    上記のような設定ファイルを環境に応じて作成してください。

    Usage

    How to use in TypeScript

    TypeScriptから利用する方法です。 最終的に、ディレクトリ構成はこんな感じになります。

    $ tree
    .
    ├── src
    │   └── index.ts
    ├── config
    │   └── local.json
    ├── package.json
    └── tsconfig.json
    $

    それぞれのファイルはたとえば以下のようにします。

    $ cat src/index.ts
    
    import config from 'config'
    import OrchestratorApi from 'uipath-orchestrator-api-node'
    
    async function main() {
        const api = new OrchestratorApi(config)
        // まずは認証
        await api.authenticate()
    
        // ロボットを取得する
        const robots: any[] = await api.robot.findAll()
        for (const robot of robots) {
            console.log(robot)
        }
    
        // ライセンスを取得する
        const license: any = await api.license.find()
        console.log(license)
    }
    
    if (!module.parent) {
        main()
    }
    $ cat package.json
    {
      "name": "api_use_ts",
      "version": "1.0.0",
      "description": "",
      "main": "dist/index.js",
      "scripts": {
         "tsc": "tsc",
         "start": "node ."
      },
      "license": "ISC",
      "devDependencies": {
        "@types/config": "0.0.36",
        "@types/node": "^13.7.0",
        "npm-run-all": "^4.1.5",
        "typescript": "^3.7.5"
      },
      "dependencies": {
        "config": "^3.2.5",
        "uipath-orchestrator-api-node": "latest"
      }
    }
    $ cat tsconfig.json
    {
        "compilerOptions": {
          "target": "ES2019", 
          "module": "commonjs", 
          "sourceMap": true, 
          "outDir": "./dist", 
          "strict": true, 
          "esModuleInterop": true,
          "forceConsistentCasingInFileNames": true 
        },
        "include": [
          "src/**/*"
        ],
    }

    実行してみます。

    $ npm i
    $ npx tsc
    $ node dist/index.js

    How to use in JavaScript

    JavaScriptから利用する方法です。 最終的に、ディレクトリ構成はこんな感じになります。

    $ tree
    .
    ├── config
    │   └── local.json
    ├── index.js
    └── package.json
    
    $

    それぞれのファイルは以下のようにします。

    $ cat index.js 
    
    const config = require('config')
    const { OrchestratorApi } = require('uipath-orchestrator-api-node')
    
    const oc = new OrchestratorApi(config)
    
    const main = async () => {
      const token = await oc.authenticate()
      const robots = await oc.robot.findAll()
      for (const robot of robots) {
        console.log(robot)
      }
    }
    
    if (!module.parent) {
      main()
    }
    $ cat package.json 
    {
      "name": "api_use",
      "version": "1.0.3",
      "description": "",
      "main": "index.js",
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
      },
      "author": "",
      "license": "ISC",
      "dependencies": {
        "uipath-orchestrator-api-node": "latest",
        "config": "^3.2.5"
      }
    }

    実行してみます。

    $ npm i
    $ node index.js

    How to customize with configuration file

    ちなみに設定ファイルは Own Coding で、

    const api2 = new OrchestratorApi({
      userinfo: {
        tenancyName: 'default',
        usernameOrEmailAddress: 'aaa',
        password: 'bbb',
      },
      serverinfo: {
        servername: 'https://platform.uipath.com/',
      },
    })

    などとしてもOKですし、

    NODE_CONFIG='{"userinfo":{"tenancyName":...}' node dist/index.js

    などと実行時の環境変数として渡してあげてもOKです。

    ライブラリのログ出力

    本ライブラリは Bunyan を用いてコンソールにログを出力しています。 出力レベルはERRORレベル以上のため、詳細にログを見たい場合はlocal.json

      "serverinfo": {
        "servername": "https://www.example.com/"
      },
      // ココより下を追記 (下記は、debug以上を出力する設定)
      "logging": [
        { "name": "main", "level": "debug" },
        { "name": "httpLogger", "level": "debug" }
      ]
      // main/httpLogger は内部で使用しているLoggerの名前

    など設定して、適宜表示を制御してください。

    source and npm repository

    ソースコードやnpmのリポジトリです。

    Revision history

    改訂履歴

    • 0.8.2 tokenモードでauthenticate したときにエラー処理を追加した。
    • 0.8.1 Tokenを直接渡されたときのFlag isToken を追加
    • 0.8.0 Interfaceファイルの場所変更、getRuntimeLicenses、getNamedUserLicenses などのDto名変更など
    • 0.7.9 ライセンスの利用状況を取得するメソッドlicense.getRuntimeLicenses,license.getNamedUserLicensesを追加
    • 0.7.8 Excel出力時に直接ファイルでなく、バイナリデータを取得するメソッドsave2ExcelBlobを追加
    • 0.7.7 configに Tokenを書けるように機能追加。Content-Typeを application/x-www-form-urlencoded でなく application/json に集約。configにuserinfoが存在しない場合、organizationUnit情報をとろうとして異常終了していたのを修正。
    • 0.7.6 Excelファイルの入出力を別のライブラリとして切り出したので、それをdependするように変更
    • 0.7.5 Excel出力で、Windows認証されたユーザTypeも出力するよう処理を追加。
    • 0.7.4 いくつかの機能追加
      • OrganizationUnitIdを切り替える機能を追加(api.organizationUnitId=2など)。
      • api.util.excelDownloadは、操作アカウントが参照可能なフォルダの情報を出力するように変更。
      • api.machine.findAllは通常ライセンスキーが入らないが、Excel出力時は入れるように処理追加。
      • ユーザ・フォルダ関連情報の出力については、TypeがUserであるすべてのユーザ・フォルダ関連を出力するよう変更
    • 0.7.3 ExcelDownloadにフォルダを追加
    • 0.7.2 strictSSLの設定、効いてなかったのを修正
    • 0.7.1 Folderサービス追加,POSTで204が返ってくるとエラーになっていたのを修正
    • 0.7.0
      • uploadの戻り値変更 Promise<any> -> Promise<any[]>
      • Robot の findByRobotName(name: string) の戻り値を変更 any -> Promise<any>
      • save2Excelの戻り値を変更 Promise<void> -> Promise<string> (フルパス)
      • ライブラリ操作機能を追加
      • setting に getWebSettings メソッドを追加。
      • utilのダウンロード対象に libraryを追加
      • Testケースのエラーログ出力を微調整
    • 0.6.6 自己署名証明書などのサーバだと、リクエスト時に証明書検証エラーになるため、設定ファイルに回避するパラメタを記載可能にした(参考)。あと多少のリファクタリングと、ドキュメント整備。
    • 0.6.5 util に excel 一括ダウンロード機能(hostテナント向け)メソッドを追加。またExcelがない環境むけにExcelファイルをConsoleへダンプする機能を追加。
    • 0.6.4 ITenantCrudService,IHostLicenseCrudService,IEnvironmentCrudService,を追加。
    • 0.6.3 Jobサービスに、Relese/Robot列を加えた findAllEx メソッドを追加。OrchestratorApi をexportしないとjsから利用できなかった( require('xxx').default ってやらないとダメ) ので、exportを追加
    • 0.6.2 ダウンロードメソッド api.util.excelDownload('./') を追加。Machine/Robot/User/Asset のテンプレートにREADMEシートを追加
    • 0.6.1 Assetの微調整。またDocument追加
    • 0.6.0 Logライブラリ(log4js)が、Webと相性がわるいぽく、ライブラリを Bunyan へ変更。Assetの操作を追加。
    • 0.5.0 Roleテスト実装(かなりテストレベル)。Excelテンプレを修正(Excel書き出しを自前実装にしたのでエラーになるカラムがなくなったため)。ファイルがindex.tsのみだったのをサービス毎に分割。Upload機能暫定追加(Robot/User/Machine)
    • 0.4.5 各種APIにsave2ExcelというメソッドでExcelダウンロードできる機能を追加。まだダンプレベルで項目の精査中、レベル。対象は、machine,robot,release,process,job,user,queueDefinitions,setting,log,auditlog
    • 0.4.4 Orchestratorの環境設定操作のAPI 追加。設定情報をExcelファイルでダウンロードする機能も。
    • 0.4.3 Organization Unit に対応。configのuserinfoに、「"organizationUnit": 1」 などと記述出来るようにした。
    • 0.4.2 Excel形式のログダウンロード機能追加(xlsx-populate-wrapper 追加)、AuditLog機能追加。ダウンロードサンプルを追加。構成をリファクタリング、Networkがエラーを返すときはステータスコードなども返す。(割とテストレベルかも、、)。
    • 0.3.9 実行ログのダウンロード機能を追加。またそのlog機能についてドキュメントを整備。
    • 0.3.8 queueDefinition/queue,queueOperation についてドキュメントを整備。あとコードのフォーマット(lint)。ロジックは変更なしです。
    • 0.3.7 nupkg関連のアップロード・ダウンロード機能を追加。各種機能のドキュメントを追加
    • 0.3.6 ドキュメントの整理のみ。
    • 0.3.5 release追加、jobの開始・停止を追加。Statのサンプルを追加
    • 0.3.4 ODataをそのまま返すオプションを追加。UserのCRUD追加。
    • 0.3.3 Robot/Machine のCRUD作成完了。テストコードも追加。Loggerの設定を見なおし。設定ファイルに外だし。
    • 0.3.2 認証ナシプロキシを設定できるように。電文を見たいときなどデバッグ時にご活用ください
    • 0.3.1 Queue/Transactionを操作するAPIに対応。
    • 0.3.0 QueueItemのCRUDを追加(もともとqueueって名前だったけどqueueItemに変更しました)。QueueDefinitionのCRUDを追加
    • 0.2.5 findAllもOptionalな引数を追加(GETのパラメタとして)。ActionsでUTするように整理
    • 0.2.3 user はCRUD作成完了、UnitTest追加( jest )、API に、汎用的なメソッドを追加。requestライブラリはformでなげると application/x-www-form-urlencoded になるのでjsonに変更
    • 0.2.0 Id指定でのロボットの取得、プロセス一覧の取得、対象オブジェクトごとにメソッドを整理、Enterprise/Community版 両対応
    • 0.1.0 初版作成

    Contributing

    Contributions, issues and feature requests are welcome!
    Feel free to check issues page.

    Show your support

    Give a ⭐️ if this project helped you!

    License

    Copyright © 2020 Masatomi KINO.
    This project is Apache--2.0 licensed.


    This README was generated by readme-md-generator

    Keywords

    Install

    npm i uipath-orchestrator-api-node

    DownloadsWeekly Downloads

    42

    Version

    0.8.3

    License

    Apache-2.0

    Unpacked Size

    426 kB

    Total Files

    98

    Last publish

    Collaborators

    • masatomix