REST APIを使用してDocuSignの申請データを作成

はじめに

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

DocuSign連携シリーズ第二弾としてREST APIを使用してDocuSignの申請データ(エンベロープ)を作成する方法をご紹介します。
前回ご紹介した方法では申請直後のみの連携でしたが、今回ご紹介するRESTメッセージを活用するとフローの好きなタイミングでエンベロープが作成できるようになります。
ServiceNow上で最終承認まで下りた後に正式な電子署名ドキュメントを作成したい、という時に活用できると考えています。

また認証設定をしたり、REST APIを呼び出したりと汎用性のある実装方法なので是非目を通していただけたらと思います。

～DocuSign連携シリーズ～

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

連携時の動き

今回ご紹介する連携時の動作は以下のとおりです。
1. ServiceNowでワークフローを承認。
2. DocuSignのREST API（Create an Envelope）を呼び出し、申請内容をもとにエンベロープを作成する
3. DocuSignから承認者へ依頼メールが送信される。承認作業はDocuSign上で行う。

使用する機能

今回使用する機能は以下です。
図中の番号順に設定方法を解説します。

①テンプレート（DocuSign）

DocuSignでテンプレートを事前に作成し、テンプレートIDを控えておきます。
詳しい作成方法はこちらのDocuSign eSignatureユーザーガイドを参照してください。
作成する際には [受信者情報]に必ず申請者と承認者欄を作成してください。
[役割名]は必須、[名前]と[メール]はREST APIから取得する場合は空白で構いません。

➁アプリとインテグレーションキーの作成（DocuSign）

ServiceNowとの認証設定を行います。
【操作方法】
1. DocuSign eSignature[設定]タブで[アプリとキー]>>[アプリ/インテグレーションキーの追加] >>アプリ名を入力>>アプリの作成　の順にクリックします。
2. 各項目を以下のように入力します。

※ServiceNowのアプリケーションレジストリの設定については「③認証設定」で解説します。

【画面イメージ】

③認証設定（Servicenow）

アプリケーションレジストリ

DocuSignとの認証設定を行います。
【操作方法】
1. システムOauth>>アプリケーションレジストリ>>新規>>サードパーティ OAuth プロバイダーに接続します　をクリックし、新規作成画面を起動します。
2. 各項目を以下のように入力します。

【画面イメージ】

アクセス制御（ACL）

OOTBではアプリケーションレジストリを登録したユーザ以外はトークンを使用できません。
そのためACLを追加することで全ユーザが今回登録したトークンを使用できるように設定します。
【操作方法】
1. ログインユーザのロールを昇格（security_adminを一時的に付与）します。
2. システムセキュリティ>>アクセス制御（ACL）>>新規　をクリックし、新規作成画面を起動します。
3. 各項目を以下のように入力します。

Oauth資格情報[oauth_credential]

【画面イメージ】

Oauth資格情報[oauth_credential]　-　トークン

【画面イメージ】

④REST APIの設定（ServiceNow）

RESTメッセージ（親）

DocuSignのREST API（Envelopes:Create）のリクエストを作成します。

【操作方法】
1. システムWebサービス>>RESTメッセージ　の順にクリックし、新規作成画面を起動する。
2. 各項目を以下のように入力します。

【画面イメージ】

3. 画面上部で右クリック>>保存　をクリックし、画面中央部の関連リンク-Oauthトークンの取得　をクリックします。

RESTメッセージ（子）

リクエスト本文を作成していきます。
【操作方法】
1. システムWebサービス>>RESTメッセージ>>RESTメッセージ関数>>新規　の順にクリックし、新規作成画面を起動します。
2. 各項目を以下のように入力します。

【画面イメージ】

[HTTP要求-コンテンツ]にリクエストボディをJSON形式で記載してきます。
詳しくはDouSignのAPI Referenceを参照してください。

{
   "status": "sent",　※1
    "templateId": “XXXXXXXXX",
    "templateRoles": [　※2
        {
            “roleName”: “●●●",
            "email": "${email_1}",
            "name": "${name_1}",
            "routingOrder": "1"
        },
        {
            “roleName”: “▲▲▲",
            "email": "${email_2}",
            "name": "${name_2}",
            "routingOrder": "2"
        },
        {
            “roleName”: “■■■",
            "email": "${email_3}",
            "name": "${name_3}",
            "routingOrder": "3"
        }
    ]
}

※1. status：createdまたはsentを指定する。createdはエンベロープを下書き保存するステータスのため、エンベロープ作成直後に承認依頼を出したい今回はsentとする。
※2. templateRoles：テンプレートで設定している受信者情報を指定する。受信者の数だけ記載する。サンプルスクリプトは受信者3名のケース。
　　・roleName：テンプレートの受信者の役割を指定。
　　・email：受信者の「メール」を指定。ServiceNowの申請画面で指定した値を指定する場合は、変数とするため${email_1}といった書き方をする。今回は変数にセットする値はFlow Designerで指定する。
　　・name：受信者の「名前」を指定。Emailと同じく変数としたい場合は${name_1}といった書き方をする。
　　・routingOrder：受信者のルーティング順序を指定する。

⑤ワークフローエディタ

ワークフローから④で作成したRESTメッセージを呼び出します。
【操作方法】
1. ワークフロー>>ワークフローエディタ　をクリックします。
2. 右上の「新規ワークフロー」ボタンを押下して、フローを作成します。
作成方法は公式ドキュメントを参照してください。
3. REST APIを呼び出したいノードに「スクリプトを実行」アクティビティを配置します。

4. 以下のようにスクリプトを記載します。

var requestBody;
var responseBody;
var status;
var sm;
try{
	
　sm = new sn_ws.RESTMessageV2("docusign", "Envelopes_create");　※1
　sm.setStringParameterNoEscape(email_1 ', currentEmail);　※2
　sm.setStringParameterNoEscape(name_1 ', currentName);　※2
　var response = sm.execute();
　responseBody1 = response.haveError() ? response.getErrorMessage() : response.getBody();

} catch(ex) {
　responseBody2 = ex.getMessage();
　status = '500';
} finally {
　requestBody = sm ? sm.getRequestBody():null;
}

<スクリプトの補足>
※1. RESTMessageV2(“name", "methodName")
name ：RESTメッセージ（親）の名前
methodName ：RESTメッセージ（子）の名前

※2. setStringParameterNoEscape (“name", “value")
name ：RESTメッセージのコンテンツ内に定義した変数名
value ：変数に割り当てる値

設定は以上です。
キャプチャのようにフローを作成すると、申請→承認が完了するとDocuSign上にエンベロープが作成されます。

おわりに

いかがでしたでしょうか。
フローを作成するまでの事前設定が複数あるので難しく感じますが、特に認証設定は一度設定するだけで完了する便利な機能です。
興味のある方はぜひ試してみてください。
最後まで読んでいただき、ありがとうございました。

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