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

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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/e3fceb3a-fe37-aaad-913e-bba332184f54.png)


## 使用する機能

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/451c22f4-241b-0560-198f-4ce23d446408.png)

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

作成する際には [受信者情報]に必ず申請者と承認者欄を作成してください。
[役割名]は必須、[名前]と[メール]はカタログアイテムから取得する場合は空白で構いません。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/d00d5e59-d4e9-b048-60a8-51d8d6b8026b.png)



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

https://support.docusign.com/jp/guides/ndse-user-guide-create-templates





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

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

2.各項目を以下のように入力します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/8d15a4b1-cd19-7543-a970-d10f41355074.png)
※ServiceNowのアプリケーションレジストリの設定については「③認証設定」で解説します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/d5f8740e-a3d4-8f37-e158-e9e2d188c082.png)






## ③認証設定（Servicenow）
### ③-1.アプリケーションレジストリ

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

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

2.各項目を以下のように入力します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/d1dd1ce3-df81-2b92-21ed-7cafde29a7bb.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/6736df67-8c9c-b233-5f10-cecca5a88b15.png)


### ③-2.アクセス制御（ACL）
OOTBではアプリケーションレジストリを登録したユーザ以外はトークンを使用できません。
そのためACLを追加することで全ユーザが今回登録したトークンを使用できるように設定します。

【操作方法】
1.ログインユーザのロールを昇格（security_adminを一時的に付与）します。

2.システムセキュリティ>>アクセス制御（ACL）>>新規　をクリックし、新規作成画面を起動します。

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

　・Oauth資格情報[oauth_credential]
　![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/2f78917b-a2e9-1bee-c4b4-f7ef20cfdfb4.png)
　![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/2d23b751-9a65-f041-33c3-731a9bf374bb.png)

　・Oauth資格情報[oauth_credential]　-　トークン
　![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/bb0f2573-b1c8-52c4-2364-c85c1b45a57d.png)
　![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/1b2fdc17-b49e-d645-4f78-f3a76e4a195f.png)


## ④REST APIの設定（ServiceNow）
### RESTメッセージ（親）
DocuSignのREST API（Envelopes:Create）のリクエストを作成します。

https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/create/


【操作方法】
1.システムWebサービス>>RESTメッセージ　の順にクリックし、新規作成画面を起動する。

2.各項目を以下のように入力します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/0d930e8e-eb4f-04b5-6c2f-8737cc3d9e01.png)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/45a130e3-b997-eb02-6b6a-3eb17d53950e.png)

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


### RESTメッセージ（子）
リクエスト本文を作成していきます。

【操作方法】
1.システムWebサービス>>RESTメッセージ>>RESTメッセージ関数>>新規　の順にクリックし、新規作成画面を起動します。	

2.各項目を以下のように入力します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/a9618949-1e4f-c96c-6193-5a6361a4c971.png)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/0f912f37-985e-6209-457a-f944ef27ebfd.png)


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

https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/create/

```json:リクエストボディ
{
   "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"
        }
    ]
}
```
<JSONの補足>
**※1.status**
createdまたはsentを指定する。
reatedはエンベロープを下書き保存するステータスのため、
エンベロープ作成直後に承認依頼を出したい今回はsentとする。

**※2.templateRole**
テンプレートで設定している受信者情報を指定する。
受信者の数だけ記載する。サンプルスクリプトは受信者3名のケース。

・roleName
　テンプレートの受信者の役割を指定。

・email
　受信者の「メール」を指定。
　ServiceNowの申請画面で指定した値を指定する場合は、変数とするため${email_1}といった書き方をする。
　今回は変数にセットする値はFlow Designerで指定する。

・name
　受信者の「名前」を指定。Emailと同じく変数としたい場合は${name_1}といった書き方をする。

・routingOrder
　受信者のルーティング順序を指定する。


## ⑤ワークフローエディタ
ワークフローから④で作成したRESTメッセージを呼び出します。

【操作方法】
1.ワークフロー>>ワークフローエディタ　をクリックします。

2.右上の「新規ワークフロー」ボタンを押下して、フローを作成します。
　作成方法は公式ドキュメントを参照してください。

https://docs.servicenow.com/bundle/rome-servicenow-platform/page/administer/workflow/reference/workflow-editor.html


3.REST APIを呼び出したいノードに「スクリプトを実行」アクティビティを配置します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2600769/507ffff8-e043-1a5d-0794-9b81c20e8905.png)

4.以下のようにスクリプトを記載します
```javascript:スクリプトを実行
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上にエンベロープが作成されます。


## 終わりに

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