【ServiceNow×DocuSign】REST APIを使用してDocuSignの申請データ(エンベロープ)を作成する方法

ServiceNowからREST APIを使用してDocuSignの申請データ(エンベロープ)を作成する方法をご紹介します。

連携時の動き

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

使用する機能

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

①テンプレート（DocuSign）

DocuSignでテンプレートを事前に作成し、テンプレートIDを控えておきます。

作成する際には [受信者情報]に必ず申請者と承認者欄を作成してください。
[役割名]は必須、[名前]と[メール]はカタログアイテムから取得する場合は空白で構いません。

詳しい作成方法はこちらのDocuSign eSignatureユーザーガイドを参照してください。

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

1.DocuSign eSignature[設定]タブで[アプリとキー]>>[アプリ/インテグレーションキーの追加] >>アプリ名を入力>>アプリの作成　の順にクリックします。

2.各項目を以下のように入力します。

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

③認証設定（Servicenow）

③-1.アプリケーションレジストリ

DocuSignとの認証設定を行います。

【操作方法】
1.システムOauth>>アプリケーションレジストリ>>新規>>サードパーティ OAuth プロバイダーに接続します　
　をクリックし、新規作成画面を起動します。

2.各項目を以下のように入力します。

③-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.各項目を以下のように入力します。

3.[HTTP要求-コンテンツ]にリクエストボディをJSON形式で記載してきます。
詳しくはDocuSignの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を指定する。
reatedはエンベロープを下書き保存するステータスのため、
エンベロープ作成直後に承認依頼を出したい今回はsentとする。

※2.templateRole
テンプレートで設定している受信者情報を指定する。
受信者の数だけ記載する。サンプルスクリプトは受信者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上にエンベロープが作成されます。

終わりに

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