UiPathOrchを初めて使う前に、使い勝手について理解しておきたいこと

この記事は「RPA Advent Calendar 2024」の9日目の記事です。
## はじめに
UiPathOrch（正式名称：PowerShell Drive and Cmdlets for Orchestrator）は、Orchestratorの操作を行うPowerShellのモジュールです。UiPathOrchのマニュアルには、インストール・初期設定の方法から、各操作のコマンドレットまで、詳しい使い方が載っているので、必要に応じてマニュアルを読めばいいのですが、使い勝手の良い方法を見つけるまでに時間が掛かった経験から、マニュアルを読む前に知っておくと良いことを、簡単に説明したいと思います。
Orchestratorの操作なら、なんでもできるツールですが、ここではジョブの実績を取得する例で説明します。ジョブの実績を取得すれば、プロセス名別の稼働実績をグラフにしたい場合などに応用できます。
## 動作環境の設定で注意すること
複数人が各自のPCでUiPathOrchを使う場合には、使用するUiPathOrchのバージョンを決めておいて、UiPathOrchのインストール時に「-RequiredVersion」オプションでバージョンを指定するようにするのが、とても大切です。

```PowerShell:バージョンを指定してインストールしよう
Install-Module UiPathOrch -RequiredVersion 0.9.8.19
```
このように考える理由は、以下のようなトラブルを経験したからです。

:::note warn
《バージョン違いによるトラブル事例》
UiPathOrchは、Orchestratorへのログインするとき、「OAuth 非機密アプリ」での接続が推奨されています。Orchestratorの設定画面で、「OAuth 非機密アプリ」を追加してアプリIDを取得します。
マニュアルには、外部アプリケーションを定義する際に、[リダイレクトURL]欄に「 http://localhost/Temporary_Listen_Addresses 」と入力するように記載されています。ある時期にインストールしたUiPathOrch（バージョン0.9.8.2）では、マニュアルの通りで正しく接続できていたのですが、しばらくしてから別のPCにインストールしたときは、UiPathOrch（バージョン0.9.8.11）になっていて、ブラウザに「不明なエラーが発生しました。（#200）」が表示されて接続できませんでした。
![不明なエラー.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/128425/7914b3c2-acde-05b9-de99-5610bd74484b.png)
UiPathOrchConfig.jsonについてバージョンの違いを調べたところ、UiPathOrch（バージョン0.9.8.11）では、先頭部分に「RedirectUrl」を定義している部分が追加になっていて、以降の行も変更になっていることが分かりました。UiPathOrchConfig.jsonで「RedirectUrl」を定義している内容を、Orchestratorの外部アプリケーション定義の[リダイレクトURL]欄に入力して「OAuth 非機密アプリ」の定義をやり直してみると、正常に接続できました。

[リダイレクトURL]が異なる複数の外部アプリケーションを定義すると混乱する可能性があるので、このときは、後からインストールしたPCのUiPathOrchを削除して、バージョン指定でUiPathOrch（バージョン0.9.8.2）インストールし直しました。
:::
:::note info
随時、新機能が追加になっていて、とても頼もしいモジュールなのです。モジュールのバージョン指定ができることを知っていれば、トラブル回避も可能です。
:::
## ジョブを取得するときの使い勝手の良い出力方法
コマンドレット「Get-OrchJob」でジョブを取得することができます。
```PowerShell:ジョブ生成時刻の条件を指定してジョブを出力する
Get-OrchJob -CreationTimeAfter '2024/11/01 00:00:00'
```
出力形式を指定しないと、Table形式で出力されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/128425/44a14b80-f1c7-6b23-e232-2edc5f15a3b0.png)

なんか、出力項目が少ないですよね。
PowerShellウィンドウの横幅を少し広げて、同じコマンドを実行してみましょう。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/128425/e2e9a300-84f2-915e-ca6e-689951f3ec74.png)

あれ～、右端が表示できてないな、と思ってウィンドウを右に広げてみても、文字が隠れていた訳ではなくて、ウィンドウ横幅サイズに合わせて出力文字が切り捨てられていたことが分かります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/128425/fe30fd2c-3e9b-f1b5-b1f6-0b153a2a8f6a.png)

Table形式では出力される項目が制限されていたり、PowerShellウィンドウの横幅サイズによって出力文字が切り捨てられて使い勝手が悪いのです。

:::note info
《Table形式のビュー定義》
Table形式での出力項目と出力形式のビュー定義は、UiPathOrchモジュールのインストールディレクトリのOrchProvider.Format.ps1xmlファイルにあります。UiPathOrchのインストールディレクトリは、コマンドレット「Set-OrchLocation」を使ってカレントディレクトリをインストールディレクトリに移動すると分かります。
:::
という訳で、使い勝手が良い出力方法としては、用途に合わせて出力項目名を指定して、CSVファイルに出力するのがお勧めなんです。
ロボット名を出力することもできます。
```PowerShell:ロボット名を出力する
Get-OrchJob -CreationTimeAfter '2024/11/01 00:00:00' | Select ReleaseName,StartTime,EndTime,@{Name='RobotName';Expression={$_.Robot.Name}} | Export-csv C:\work\job.csv -Encoding utf8BOM
```
終了時刻と開始時刻の差から、実行時間の秒数を出力することもできます。
```PowerShell:実行時間（終了時刻-開始時刻）の秒数を出力する
Get-OrchJob -CreationTimeAfter '2024/11/01 00:00:00' | select ReleaseName,StartTime,EndTime,@{Name='OperatingSeconds';Expression={($_.EndTime-$_.StartTime).TotalSeconds.ToString('0')}},@{Name='RobotName';Expression={$_.Robot.Name}} | Export-csv C:\work\job.csv -Encoding utf8BOM
```
## まとめ＆補足
Table形式で出力した結果だけみて、『これじゃ使えないわ』と思ってしまったらもったいないのです。UiPathOrchはOrchestratorの操作がなんでもできる最強ツールだと思います。用途に合わせて出力項目の指定と出力形式を指定できることが分かっていただけたと思いますので、ぜひマニュアルを読み込んで、UiPathOrchを活用してください。
さらに、マニュアルに載ってなくて（載っていても自力で探せないときも含め）『こんな設定をしたいときはどうしたらいいの？』という疑問にぶつかったら、MarketPlaceのUiPathOrchのページにある[Q&A]タブで質問してみましょう。丁寧に回答していただけます。