【UiPath】OrchestratorのWebhookを利用してジョブの停止をTeamsに投稿しよう（UiPath Integration Service編）

# １．はじめに
　OrchestratorのWebhookを利用してジョブの停止をトリガーに、Teamsにメッセージ投稿してみたいと思います。OrchestratorのWebhookとは、Orchestrator側のジョブのイベント（作成や開始、停止など）が発生したときに外部通知する仕組みとなります。特にジョブが停止した場合は状況把握のためにも逃さず通知を受け取りたいため、同仕組みを利用してTeamsに投稿してみたいと思います。なお、Webhookの詳細は[公式Doc](https://docs.uipath.com/ja/orchestrator/automation-cloud/latest/user-guide/about-webhooks)を参照ください。
　今回の実装では以下のような形式でTeamsにメッセージ投稿できるようにしたいと思います。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3301393/d73fc142-11ad-f748-4003-e4edc66d337e.png)

# ２．Webhook受信からTeams投稿の方法
　Webhook受信からTeams投稿の方法には、多くの方法があります。
| # | 方法 | 概要 |
| :--- | :--- | :--- |
| 1 | [PowerAutomate（クラウドフロー）](https://qiita.com/tomohiroArai/items/82fdb40bda750bc2277a) | PowerAutomateにてWebhookを受信後、Teamsに投稿する |
| 2 | UiPath Integration Service（Webhook+Teams） | Integration Service（Webhook）トリガーにてWebhookを受信後、Integration Service（Teams）を利用してTeamsに投稿する |
| 3 | Amazon API Gateway+AWS Lambda | Amazon API GatewayにてWebhookを受信後、AWS Lambdaを利用してTeamsに投稿する |

他にもAzure側のサービスを組み合わせることで上記を実現することは可能となりますが、**今回は#2のUiPath Integration Service（Webhook+Teams）による方法**を紹介したいと思います。

# ３．環境情報
利用する環境は以下の通りとなります。
| ソフトウェア名 | バージョン情報 |
| :--- | :--- |
| OS | Windows10 |
| UiPath Studio | 23.10.9 |

:::note warn
2024年12月5日訂正
Studio v24.10.6以前では動作エラーとなるため、Studio v24.10.7以降またはStudio v23.10.xをご利用ください。
~~2024年11月22日現在
Studio v24.10.xでは動作エラーが発生するため、Studio v23.10.xを利用しています。Studio v24.10.x利用の方は修正を待ってからお試しいただくか、一時的にダウングレードしていただくなど検討を頂ければと思います。~~
:::

:::note info
クロスプラットフォームはStudio Webから作成するのが便利ですが、Integration Serviceのプレビュー機能が利用できない制限があるため、今回はStudioを利用します。
:::

# ４．UiPath Integration Service（Webhook+Teams）による方法
　UiPath Studioを開き、新規プロジェクトを作成します（設定は下表の通りとなります）。
| # | 設定項目 | 設定内容 | 備考 |
| :--- | :--- | :--- | :--- |
| 1 | 名前 | 任意 |  |
| 2 | 説明 | 任意 |  |
| 3 | 対応OS | クロスプラットフォーム | 詳細オプション内 |
| 4 | 言語 | VB | 詳細オプション内 |

#### (1) パッケージインストール
　以下に示すパッケージをインストールしてください。（規定で存在するSystem.Activitiesなどのパッケージは必要に応じてバージョン更新などをしてください）
 | ソフトウェア名 | バージョン情報 |
| :--- | :--- |
| UiPath.HttpWebhook.IntegrationService.Activities | 5.0.0-preview |
| UiPath.IntegrationService.Activities | 1.9.0 |
| UiPath.System.Activities | 23.10.6 |
| UiPath.UIAutomation.Activities | 23.10.13 |
| UiPath.WebAPI.Activities | 1.18.0 |

#### (2) トリガーの追加
　アクティビティの検索ウィンドウに「Webhook」と入力し、「`Create Webhook Trigger`」選択し、「Main Sequence」内にドラッグします。

#### (3) コネクションの作成（Webhook）
　Webブラウザを利用し、Automation Cloudにアクセス後「Integration Service」を開きます。
　Integration Serviceにて「Webhookを受信してTeams投稿するプロセスを動かす」フォルダーを選択します。
　フォルダー選択後、「コネクション」タブをクリックし、「コネクションを追加」をクリックします。
　検索ウィンドウに「Webhook」と入力し、「`HTTP Webhook`」を選択します。
　「What application is this webhook for?」項目に「Webhook受信元のアプリケーション名」（例では「`Orchestrator`」）を入力し、「接続」をクリックします。
 
#### (4) コネクション設定等（Webhook）
　「Create Webhook Trigger」のコネクションに先ほど作成したコネクション名（例では「`Orchestrator`」）を選択します。
　プロパティにある「Webhook Event Payload」に変数「`str_Payload`（あくまでも例）」を作成後設定します。

:::note info
コネクション名が表示されない場合はStudio下部にある更新ボタンをクリックすると、情報が更新されます。それでも表示されない場合は一度トリガー自体を削除し、再配置してみてください。
:::

#### (5) JSON文字列の変換
　「Create Webhook Trigger」で受信した内容はJSON文字列となるため、「JSON を逆シリアル化」を次に配置します。
　「JSON文字列」に「`str_Payload.Content.ToString`」を設定します。
　プロパティにある「JSON オブジェクト」に変数「`jobj_Content`（あくまでも例）」を作成後設定します。
 
#### (6) Teamsへのメッセージ投稿
　アクティビティの検索ウィンドウに「Teams」と入力し、「チャネル メッセージを送信」選択し、一番下にドラッグします。

#### (7) コネクションの作成（Teams）
　Webブラウザを利用し、Automation Cloudにアクセス後「Integration Service」を開きます。
　Integration Serviceにて「Webhookを受信してTeams投稿するプロセスを動かす」フォルダーを選択します。（Webhookと同じフォルダー）
　フォルダー選択後、「コネクション」タブをクリックし、「コネクションを追加」をクリックします。
　検索ウィンドウに「Teams」と入力し、「`Microsoft Teams`」を選択します。
　「接続」をクリックします。

:::note info
「管理者の承認が必要」とメッセージ表示された場合は以下のサイトなどを参考にIT部門へ調整が必要となります。
[https://jpazureid.github.io/blog/azure-active-directory/azure-ad-consent-framework/](https://jpazureid.github.io/blog/azure-active-directory/azure-ad-consent-framework/)
:::
 
#### (8) コネクション設定等（Teams）
　「チャネル メッセージを送信」のコネクションに先ほど作成したコネクション名を選択します。
　「チーム」から投稿したい任意のチームを選択します。
　「チャンネル」から投稿したい任意のチャンネルを選択します。
　「メッセージ本文」には以下を入力します。
```vb.net
String.Format("時刻：{0}に{1}のジョブが停止しました。",
TimeZoneInfo.ConvertTimeFromUtc(DateTime.SpecifyKind(DateTime.Parse(jobj_Content("Jobs")(0)("EndTime").ToString()), DateTimeKind.Utc), TimeZoneInfo.FindSystemTimeZoneById("Tokyo Standard Time")).ToString("yyyy/MM/dd HH:mm:ss"),
jobj_Content("Jobs")(0)("Release")("ProcessKey").ToString())
```
なお、PowerAutomate同様にジョブの停止時間をTeamsに投稿していますが、Webhook内の時刻がUTCとなっているため、JSTの表記となるように変換を行っています。他にも単純なやり方として9時間加算するなどのやり方がありますが、タイムゾーンを明示する方法を採用しています。

最終的なワークフローは以下のようになります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3301393/d92bf06d-f265-eb6e-5176-db7379d3a754.png)

#### (9) 受信用のURL取得
　受信用のURLは「Create Webhook Trigger」に存在するURLを取得します（Orchestratorの最後の設定で利用するため、メモ帳などに記録ください）。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3301393/9ae67aed-a62a-0cfe-1a86-ed6701d514a3.png)

:::note warn
Integration Serviceからフォルダー選択後、該当のコネクションをクリックすると、上部にURLが表示されており、そちらからも確認が可能となります。（一部組織やテナント名がIDから通常のURLに変わっていますが、同じ結果となります。）
:::

#### (10) パブリッシュ
　テナントフィードにパブリッシュを行います。

# ５．Automation CloudおよびOrchestrator側の設定
#### (1) ロボットアカウントの作成
　Automation Cloudの組織にてロボットアカウントの作成を行います。
　Orchestratorにてテナントの「アクセス権を管理」タブからロボットアカウントの追加を行います。（例では「Allow to be Automation User」を利用します。）
　**※無人オートメーションの設定では「仮想マシンの事前設定済みの資格情報」を選択してください。**
　「Webhookを受信してTeams投稿するプロセスを動かす」フォルダーにロボットアカウントを割り当てます。（例では「Automation User」を利用します。）

#### (2) マシンの作成
　Orchestratorにてテナントの「マシン」タブから「マシンを追加」をクリックし、「Cloud ロボット - サーバレス」を選択します。
　テンプレート名を通常のマシンテンプレート作成時と同様に入力し、「プロビジョニング」をクリックします。
　「Webhookを受信してTeams投稿するプロセスを動かす」フォルダーにマシンを割り当てます。

#### (3) プロセスの配置
　「Webhookを受信してTeams投稿するプロセスを動かす」フォルダーに移動し、「プロセス」を開きます。
　「プロセスを追加」をクリックし、先ほどパブリッシュしたパッケージを選択後、「次へ」をクリックします。
 　「パッケージ要件」にて、作成したコネクションが設定されているかを確認し、問題なければ、「次へ」をクリックします。（参考画像）
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3301393/9fc43f98-2211-f8c9-6da8-3c5be508126c.png)

　「Cloud ロボット - サーバレス」のサイズ設定があるため、「小」を選択後、「作成」をクリックします。

#### (4) Webhookの設定
　Orchestratorにてテナントの「Webhook」タブから「Webhookを追加」をクリックし、任意の名前を付け、URLには(7)の手順で取得したURLを貼り付けます。さらに、「個別のイベントを選択」後、「ジョブ」内の「job.stopped」にチェックを入れ、保存します。

# ６．Postmanなどによる事前確認
　詳細は割愛しますが、以下画像のようにPOSTメソッドによりBodyにJSONデータを定義してテストを行います。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3301393/03d7397d-3861-0636-ee48-f5d8bd70cb11.png)

# ７．さいごに
　今回はWebhookの通知をTeamsに投稿する方法として、UiPath Integration Serviceによる方法を紹介しました。皆様の運用が少しでも便利になればと思っています。
　UiPathに必要なライセンスに関してはご利用環境に応じて確認してください。
　本記事はあくまでも個人の見解を述べているものとなりますので、参考情報として頂ければと存じます。