MKIが解説するServiceNow開発blog

ServiceNow にまつわるMKIナレッジを紹介いたします。

DocuSignでのフローの進行状況を取得する

外部連携

はじめに

みなさんこんにちは、三井情報株式会社です。

DocuSign連携シリーズ第一弾、第二弾ではServiceNowからDocuSignへの連携方法をご紹介しました。
ただ、このままではDocuSignへ渡った後の進行状況はDocuSignでしかわかりませんよね。
そこで今回はDocuSign上での進行状況もServiceNowで確認できるような、DocuSignとServiceNowの設定方法をご紹介したいと思います。

～DocuSign連携シリーズ～

①カタログアイテムからDocuSignへ遷移
➁REST APIを使用してDocuSignの申請データを作成
③DocuSignでのフローの進行状況を取得　←今回

連携時の動き

連携時の動作概要は以下のとおりです。
① DocuSign上で承認を行う
② DocuSignからエンベロープの更新情報をServiceNowへ送信（リアルタイム）
③ ServiceNowのレコードに取得結果を反映し、WFのノードを進める
f:id:mki-blog:20220221125107p:plain

使用する機能

今回使用する機能は以下です。
図中の番号順に設定方法を解説します。
f:id:mki-blog:20220221125142p:plain
※1. Scripted REST API
外部システムから受信したリクエストを加工する機能です。
詳しくは過去記事（ServiceNowにWebhookでデータ連携）を参照してください。

事前準備

使用する機能を紹介しましたが、その前にServiceNow/DocuSign双方で事前準備を行います。

1.　リクエストアイテムとエンベロープのキーを設定

ServiceNowのリクエストアイテムレコードに紐づくDocuSignのエンベロープを特定できるよう、それぞれに共通の値を持たせます。
今回はリクエストアイテムNoをエンベロープの「shinseiNo」という項目にセットしたいと思います。
DocuSignのテンプレートに以下のように項目を追加します。
エンベロープをPower Formから作成する場合はonSubmitの処理に、REST APIから作成する場合はボディに「shinseiNo」に値をセットするように指定します。
f:id:mki-blog:20220221125250p:plain

2.　受信者ごとのステータス格納先を作成（ServiceNow）

DocuSignから取得するデータ（Webhook）にはエンベロープの受信者ごとのステータスが含まれています。
そのためServiceNow側にそれら（受信者ごとのステータス）を保持する体制を作ります。
今回はリクエストアイテムに紐づく変数にステータスを保持するようにします。
作成イメージは以下です。
f:id:mki-blog:20220221125320p:plain
DocuSignからステータスを取得する都度、上記の変数の値を更新します。

3．エンベロープの更新情報を送信するよう設定（DocuSign）

DocuSignはただエンベロープを作成したり更新したりするだけでは、外部システムにリクエストを送信しません。
事前に設定をすることで特定のタイミングで特定のシステムへリクエストを送信してくれるようになります。
設定方法はエンベロープをPower Formから作成するのか、REST APIから作成するのかで異なります。

Power Formからエンベロープを作成する場合

DocuSign Connectというサービスを使用します。
DocuSign Connectを設定するとアカウント（環境）に作成された全てのエンベロープの更新情報をリアルタイムで外部へ送信してくれます。
PowerFormで作成したエンベロープには「特定のPowerFormで作成したエンベロープだけの更新情報を送信する」という設定ができません。
詳しい設定方法は「➁DocuSign Connect（DocuSign）」で説明します。

REST APIからエンベロープを作成する場合

REST APIを実行する際にリクエストボディに外部システムへエンベロープの更新情報を送信するよう設定します。
リクエストボディのサンプルを以下に記載します。
DocuSign連携シリーズ第2回の「REST APIを使用してDocuSignの申請データを作成」でご紹介したものと組み合わせて使用してください。
※REST APIについてはAPI Referenceを参照してください。

{
"eventNotification": {
    "includeHMAC": "true",　※1
    "envelopeEvents": [
       {
        "envelopeEventStatusCode": "Delivered"　※2
　　　　},
      {
        "envelopeEventStatusCode": "Completed"　※2
      }
    ],
    "url": "https://～～～～",　※3
    "eventData": {
      "format": "json",
      "includeData": [　※4
        "recipients"
      ],
      "version": "restv2.1"
    },
    "loggingEnabled": "true"
  },

※1. includeHMAC
trueにすることでリクエストヘッダーにハッシュ値が含まれます。
受信側システム（ServiceNow）はこのハッシュ値とDocuSignで発行されるキーを使用することでメッセージの信頼性を検証できます。
メッセージの検証方法については過去記事（HMAC-SHA256を利用したWebhookメッセージの検証方法）を参照してください。

※2. envelopeEventStatusCode
外部システムへ更新情報を送信するタイミングを指定します。
複数のタイミングで送信したい場合は、その数だけ{}も含めて記載します。
サンプルJSONはエンベロープを送信した時と完了した時の2回送信します。

※3. url
リクエストの送信先URLを記載します。
今回はScripted REST APIsで作成したURLを指定します。
例) https://インスタンス名.service-now.com/ベースAPIパス

※4. includeData
リクエストボディに含めるデータを指定します。
今回は受信者ごとのステータスが欲しいので「recipients」を指定します。

以上で事前準備の完了です。

①Scripted REST APIs （ServiceNow）

DocuSignからのリクエストを受け取り、その内容をテーブルに反映する処理を行います。

Scripted REST APIs（親）

【操作方法】
1．システムWebサービス >>　Scripted REST APIs　をクリックし、新規作成画面を起動する。
2．[名前]と[API ID]に任意の文字列を入力し、[保存]をクリックする。
3．[セキュリティ：デフォルトACL]の選択を解除し、[更新]をクリックする。
4．[リソース：新規]をクリックする。

【画面イメージ】
f:id:mki-blog:20220221130107p:plain

Scripted REST APIs（子）

【操作方法】
1．入力値は以下のとおり。
f:id:mki-blog:20220221130128p:plain

【画面イメージ】
f:id:mki-blog:20220221130148p:plain

[タイプ]に入力するスクリプトのサンプルは以下です。
取得したリクエストから受信者ごとのステータスを抽出するところまでを記載します。

(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
 //HMACを使用してWebhookメッセージの検証
　　//bodyの値
　　var bodyAll =request.body.data;

　 //Headerの値
　　var headers =JSON.stringify(request.headers);

  //DocuSignで作成した秘密鍵と、取得したbodyを使用してハッシュ値を作成する
  var mac = new GlideCertificateEncryption;
  var key = 'Docusignで作成する秘密鍵';
  key = GlideStringUtil.base64Encode(key);
  var payload = JSON.stringify(bodyAll);
  var hash = mac.generateMac(key, "HmacSHA256", payload);

 //HMAC署名の確認
　if(headers.indexOf(hash) !== -1){

//エンベロープIDを変数にセット
　　var envelopeId = JSON.stringify(bodyAll.envelopeId);

//署名者情報を変数にセット
　　var signersStatus = bodyAll.recipients.signers;

//受信者ごとのステータスと申請番号を取得する
　　var statuslist = [];
　　var fieldList = [];
　　for (var i=0; i< signersStatus.length; i++) {
　　　//署名者ごとのステータスを連想配列に格納する
　　　var roleStatus = {}; 
　　　roleStatus.name = signersStatus[i].roleName.toString();
　　　roleStatus.status = signersStatus[i].status.toString();
　　　statuslist.push(roleStatus);
　　　//申請番号の取得
　　　//DocuSignの入力フィールドに格納されている値を変数にセット
　　　var tabs = signersStatus[i].tabs.textTabs;

　//各入力項目の値を連想配列に格納する
　　　for (var a=0; a< tabs.length; a++) {
　　　　var textTabs = {};
　　　　textTabs.tabLabel = tabs[a].tabLabel.toString();
　　　　textTabs.value = tabs[a].value.toString();
　　　　fieldList.push(textTabs);
　　　}
　　}
　　//申請番号の値のみ取得する
　　var getShinseiNo;
　　var fieldLists = fieldList.filter(function(item, index){
　　　if (item.tabLabel == 'shinseiNo') {
　　　　getShinseiNo = item.value;
　　　
　　　}
　　});
　　//署名者ごとのステータスをセット
　　var statuslists = statuslist.filter(function(item, index){
　　　if (item.name == '作成者') {
　　　　getsakuseisyaStatus = item.status;
　　　}else if(item.name == '確認者'){
　　　　kakuninsyaStatus = item.status;
　　　}else if(item.name == '発議者'){
　　　　hatssugisyaStatus = item.status;
　　　}else if(item.name == '決裁者'){
　　　　kessaisyaStatus = item.status;
　　　}
　　});

以降、要求アイテムテーブルにエンベロープIDと各受信者のステータスをupdateする。


サンプルスクリプトの冒頭で行っている処理については過去記事（HMAC-SHA256を利用したWebhookメッセージの検証方法）にて解説しています。

➁DocuSign Connect（DocuSign）

Power Formから作成したエンベロープの更新情報をServiceNowへ送信する設定を行います。

【操作方法】
1．DocuSign eSignatureの[設定]タブで、
[インテグレーション] >> [DocuSign Connect] をクリックします。
2．[設定の追加] > [カスタム] をクリックします。
3．各項目を以下のように入力します。
f:id:mki-blog:20220221130555p:plain

③CONNECTキー（DocuSign）

REST APIから作成したエンベロープの更新情報をServiceNowへ送信する設定は、事前準備のエンベロープ作成時点で行っています。
DocuSignからのリクエストの信頼性をServiceNow上で検証するためにCONNECTキーの発行を行います。

【操作方法】
1．DocuSign eSignatureの[設定]タブで、
[インテグレーション] >> [DocuSign Connect] をクリックします。
2．[CONNECTキー]タブをクリックします。
3．[秘密鍵の追加]をクリックします。
キーはServiceNowでの処理で使用するので控えておいてください。

【画面イメージ】
f:id:mki-blog:20220221130642p:plain

④ワークフローエディタ

ワークフローエディタには「条件待ち（Wait for condition）」というアクティビティがあります。これはレコードが特定の条件を満たすとノードを進める、という機能を持ったアクティビティです。
今回はステータスを格納している変数の値が「complete」となった時、フローを進めるというように設定します。

【操作方法】
①Workflow　>>　ワークフローエディタ　をクリックする。
➁[新規ワークフロー]をクリックする。
③入力値は以下のとおり。
f:id:mki-blog:20220221130746p:plain
④画面右の[コア]タブから[条件待ち]アクティビティをドラッグする。
⑤入力値は以下のとおり。
f:id:mki-blog:20220221130807p:plain


おわりに

DocuSign連携シリーズは今回で以上になります。
本シリーズはServiceNowとDocuSignの良いとこどりをした連携で、企業活動のペーパーレス化に貢献できるのではと考え検証、ご紹介させていただきました。

最後まで読んでいただき、ありがとうございました。


三井情報株式会社
ソリューション技術本部
クラウドソリューション部
第四技術室
佐久間衣歩