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上にエンベロープが作成されます。
終わりに
フローを作成するまでの事前設定が複数あるので難しく感じますが、特に認証設定は一度設定するだけで完了する便利な機能です。
興味のある方はぜひ試してみてください。