DelugeでZoho Creatorの署名タスクを自動化する方法

お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

Zoho Sign では、独自のオンラインスクリプト言語Delugeを利用して、署名タスクを自動化できます。ユーザーは処理ロジックを追加して、署名タスクやワークフローを自動的に実行できます。たとえば、Zoho Creator で作成した新規ユーザーのオンボーディングアプリケーションがあり、担当の従業員がデータを入力して［送信］ボタンをクリックすると、NDA ドキュメントをすぐに送信して署名依頼を行うことができます。また、Deluge をサポートする他のアプリケーション向けにカスタム関数を作成し、署名タスクをトリガーすることもできます。

メモ:

Zoho Sign の Deluge タスクを使用した自動化で作成される各ドキュメント署名リクエストについて、Zoho Sign のサブスクリプションプランに応じて、5 件分の無料 Zoho Sign クレジットまたは Zoho Sign クレジットが消費されます。無料クレジットは、ライセンスユーザー数に応じて、エンタープライズプランの組織に毎月付与されます。
組織で無料クレジットを使い切った場合、それ以降のドキュメントごとに、追加購入した Zoho Sign クレジットが消費されます。

これは、現在 Zoho Sign がサポートしている各種 Zoho アプリ連携において、Deluge を使用して実現されるカスタム関数、ワークフロー、その他すべての自動化に適用されます。

仕組み

Deluge Script Builder では、ドラッグ＆ドロップのユーザーインターフェイスを使用して Deluge スクリプトを追加できるため、ユーザーは Deluge の構文や関数を参照・暗記する必要がありません。
要件に基づいてアプリケーションを作成できます。たとえば、採用管理アプリや在庫管理アプリなどを作成できます。
採用管理アプリでは、NDA、SNS 利用規定、IT サービス規定などの署名タスクを自動化するロジックを設定できます。
各ロジックに対して署名タスクを割り当て、従業員に署名用ドキュメントを送信できます。
Deluge により、一連のプロセスを自動化して簡素化できます。
Zoho Sign 用 Deluge タスクの手順ごとの操作方法は、ヘルプドキュメントのこちらのセクションに記載されています。

Zoho Sign でよく使用される Deluge タスク

ドキュメントを送信して署名を依頼する

ドキュメントを送信して署名を依頼するには、次の 3 つの手順を実行します。ドキュメントのアップロード、フィールドタイプの取得、受信者と受信者に関連付けるフィールドの追加です。

ドキュメントのアップロード:

ドキュメントをアップロードします。このドキュメントは、Zoho Creator のファイルフィールドとして保存されているもの、またはサードパーティの URL からダウンロードできるもののいずれかです。
ファイルオブジェクトを取得したら、uploadDocument タスクを使用します。

コード:

file = getUrl(<path to file>);
res = Zoho。sign。uploadDocument(file);
[OR]
res = Zoho。sign。uploadDocument(input。File_field);

レスポンスには、完了または失敗のステータスを含むマップが返されます。完了の場合、後続の処理で必要となるrequest_id とともに、作成されたドキュメントの詳細が返されます。また、どのドキュメントにフィールドを追加するかを指定するための document_id も含まれます。

フィールドタイプの取得:

Zoho Sign では、ドキュメントに追加できるさまざまなフィールドをサポートしています。各フィールドタイプには、ユーザーごとに固有の field_type_id が割り当てられています。アカウントで使用するフィールドタイプと ID を取得する必要があります。

getFieldIds タスクを使用して、フィールドタイプと ID を取得します。
レスポンスには、各フィールドタイプと対応するフィールドタイプ ID が含まれます。
この情報は別のマップに保存しておき、次の手順でフィールドを追加してドキュメントを送信する際に使用できます。

コード:

fieldIds = Zoho。sign。getFieldIds();
fieldTypes = fieldIds。取得する('field_types');
項目 = Map();
for each 項目 in fieldTypes
{
fieldJson = 項目。toMap();
項目。put(fieldJson。取得する('field_type_name'), fieldJson。取得する('field_type_id'));
}

受信者の追加:

最後の手順として、ドキュメントの送信先となる受信者と、その受信者に対して設定するフィールドを指定します。

submitRequest タスクを使用して、この手順を実行します。
受信者およびフィールドに関するデータは、マップとしてこのタスクに渡す必要があります。

送信するデータの形式は次のとおりです。

actions - 各受信者の詳細を含む配列。

各受信者オブジェクトに含まれる項目:

action_id - 直前の呼び出しで保存された action_id

fields - 受信者が署名者である場合に、その受信者に関連付けられるすべてのフィールドの詳細を含む JSON オブジェクト

text_fields - Text、Company、Job 件名、Full 名前、メールなど、すべてのテキストベースフィールドを含む配列

image_fields - 署名などの画像フィールドを含む配列

date_fields - すべての日付フィールドの詳細を含む配列

各フィールドに関連付けられるデータ:

document_id

page_no - フィールドが配置されるページ番号（0 から開始）

field_name - フィールドの表示名

x_value - ページ左下隅からのフィールドの X 座標

y_value - ページ左下隅からのフィールドの Y 座標

width - ページに対する幅（%）

height - ページに対する高さ（%）

field_type_id - 直前の呼び出しで取得した、フィールドタイプに関連付けられた field_type_id

is_mandatory

name_format （フルネームフィールドのみ） - 名前の形式（FULL 名前/FIRSTNAME/LAST 名前）

date_format （日付フィールドのみ） - 日付入力に使用する日付形式

text_property （すべてのテキストベースフィールドおよび日付フィールド） - 次のテキストプロパティを含みます

フォント

font_size

font_color - テキストに適用する色の 16 進コード

is_bold

is_italic

is_read_only（フィールドタイプが「Text」の場合のみ） - フィールドが閲覧専用かどうか

default_value（フィールドタイプが「Text」の場合のみ） - フィールドの初期値

コード:

actionMap = Map();
actionMap。put('request_name','test_AddFields');
textFields = List();
textField1 = Map();
textField1。put('field_name', 'Company');
textField1。put('is_mandatory', '真');
textField1。put('field_type_id', 項目。取得する('Company'));
textField1。put('document_id', doc_id);
textFields。追加する(textField1);
fieldMap = Map();
fieldMap。put('項目',{'text_fields':textFields});
fieldMap。put('recipient_name', 'John');
fieldMap。put('recipient_email','john@zylker.com');
fieldMap。put('action_type','SIGN');
fieldList= List();
fieldList。追加する(fieldMap);
actionMap。put('処理',fieldList);
submitMap = Map();
submitMap。put('requests', actionMap);
response = Zoho。sign。submitRequest(, {'data':submitMap});

レスポンスには、ドキュメントが正常に送信された場合、ステータスが完了のマップが含まれます。エラーが発生した場合はステータスが failure となり、メッセージキーにエラーの詳細が含まれます。

Zoho Sign テンプレートを使用してドキュメントを送信する

Zoho Sign テンプレートを使用すると、ドキュメントを一度作成して項目を追加し、必要に応じて何度でも再利用できます。テンプレートを使用する際は、受信者の詳細と、設定済みの事前入力項目を指定するだけでかまいません。同じドキュメントを Deluge から繰り返し送信する場合に特に便利です。ファイルのアップロードや項目の設定を毎回行う必要はありません。

メモ:この機能は、プロフェッショナル版およびエンタープライズ版でのみ利用できます。

Deluge から Zoho Sign テンプレートを使用するには、次の 3 つの手順が必要です。

Zoho Sign のテンプレート一覧を取得する（任意）
必要な Zoho Sign テンプレートの詳細を取得する
Zoho Sign テンプレートを使用してドキュメントを送信する

Zoho Sign のテンプレート一覧を取得する:

このタスクは、アプリケーション内でテンプレートの一覧を取得する必要がある場合に役立ちます。常に同じテンプレートだけを使用してドキュメントを作成する場合は、この手順は省略できます。

getTemplates タスクを使用して、Zoho Sign アカウントで作成されたすべてのテンプレートの一覧を取得します。これは、テンプレートキーの下にすべての Zoho Sign テンプレートの一覧を含むオブジェクトを返します。各テンプレートには template_id があり、後続の手順で必要になります。使用するテンプレートを選択したら、そのテンプレートの template_id を保存しておきます。

コード:

response= Zoho。sign。getTemplates();
{
'コード': 0,
'メッセージ': 'テンプレート list retrieved successfully',
'page_context': {
'sort_column': 'template_name',
'has_more_rows': 無効,
'start_index': 1,
'total_count': 1,
'sort_order': 'ASC',
'row_count': 1
},
'テンプレート': [
'{\'owner_email\':\'john@zylker.com\',\'created_time\':1521109119330,\'email_reminders\':真,\'document_ids\':[{\'document_name\':\'Zoho Sign。pdf\',\'document_size\':59808,\'document_order\':\'0\',\'total_pages\':1,\'document_id\':\'32076000000002005\'}],\'メモ\':\'\',\'reminder_period\':1,\'owner_id\':\'32076000000002003\',\'説明\':\'\',\'template_name\':\'Template1\',\'modified_time\':1521110073225,\'is_deleted\':無効,\'expiration_days\':15,\'is_sequential\':無効,\'template_id\':\'32076000000002011\',\'request_type_name\':\'その他\',\'owner_first_name\':\'John\',\'request_type_id\':\'32076000000000135\',\'owner_last_name\':\'Mathews\',\'処理\':[{\'ishost\':無効,\'verify_recipient\':無効,\'役割\':\'CEO\',\'action_id\':\'32076000000002014\',\'action_type\':\'SIGN\',\'private_notes\':\'\',\'recipient_email\':\'john@zylker.com\',\'signing_order\':-1,\'recipient_name\':\'John Mathews\',\'recipient_phonenumber\':\'\',\'recipient_countrycode\':\'\'}]}'
],
'ステータス': '完了'
}

テンプレート詳細の取得:

使用するテンプレートとその template_id がわかっている場合は、そのテンプレートの詳細を取得します。これにより、テンプレート内の差し込み項目の役割に必要なメールアドレスを割り当てることができます。
また、テンプレートに含まれる必須の事前入力項目を埋める際にも役立ちます。
getTemplateById タスクを使用して、テンプレート ID から詳細を取得します。
レスポンスにはテンプレートの詳細が含まれます。テンプレートに含まれる受信者の詳細と、設定されている事前入力項目の詳細が含まれます。

テンプレートオブジェクトには操作リストがあり、テンプレートに設定されている受信者の数だけ要素が含まれます。

また、document_fields リストもあります。テンプレート内の各ドキュメントはオブジェクトに関連付けられており、各オブジェクトには、そのドキュメントに含まれる事前入力項目の項目リストが含まれます。

サンプルレスポンス:

{
'コード': 0,
'メッセージ': 'テンプレート一覧を正常に取得しました',
'page_context': {
'sort_column': 'template_name',
'has_more_rows': 無効,
'start_index': 1,
'total_count': 1,
'sort_order': 'ASC',
'row_count': 1
},
'テンプレート': [
'{\'owner_email\':\'john@zylker.com\',\'created_time\':1521109119330,\'email_reminders\':真,\'document_ids\':[{\'document_name\':\'Zoho Sign。pdf\',\'document_size\':59808,\'document_order\':\'0\',\'total_pages\':1,\'document_id\':\'32076000000002005\'}],\'メモ\':\'\',\'reminder_period\':1,\'owner_id\':\'32076000000002003\',\'説明\':\'\',\'template_name\':\'Template1\',\'modified_time\':1521110073225,\'is_deleted\':無効,\'expiration_days\':15,\'is_sequential\':無効,\'template_id\':\'32076000000002011\',\'request_type_name\':\'その他\',\'owner_first_name\':\'John\',\'request_type_id\':\'32076000000000135\',\'owner_last_name\':\'Mathews\',\'処理\':[{\'ishost\':無効,\'verify_recipient\':無効,\'役割\':\'CEO\',\'action_id\':\'32076000000002014\',\'action_type\':\'SIGN\',\'private_notes\':\'\',\'recipient_email\':\'john@zylker.com\',\'signing_order\':-1,\'recipient_name\':\'John Mathews\',\'recipient_phonenumber\':\'\',\'recipient_countrycode\':\'\'}]}'
],
'ステータス': '完了'
}
{

コード:

template_id = <テンプレート ID を指定>;
response = Zoho。sign。getTemplateById(template_id);
prefill_fields = List();
if(response。取得する('ステータス')contains('完了'))
{
recipients = response。取得する('テンプレート').取得する('処理');
document_fields = response。取得する('テンプレート').取得する('document_fields');
for each ドキュメント in document_fields
{
prefill_fields。addall(ドキュメント。取得する('項目'));
}
}

Zoho Sign テンプレートを使用してドキュメントを送信する:

これは最終手順で、テンプレートを送信する宛先の受信者や、設定済みのプレフィル項目を割り当てます。この手順では、処理（actions）リストと項目リストが役立ちます。この手順には、createUsingTemplate タスクを使用します。また、対象テンプレートのtemplate_idもここで必要になります。

このタスクのパラメーターは次の構造になります:

パラメーターは、キー data と、以下の値を含む値を持つマップに追加する必要があります。

処理: テンプレートに関連付けられているすべての役割の詳細を含むリスト。各アクションマップには次を含める必要があります。
recipient_name- 受信者の名前
recipient_email- 受信者のメール ID
action_id- 直前の getTemplateById の結果の処理（actions）配列で返された actions_id の値
役割- テンプレートで指定されている役割名
action_type- SIGN/VIEW（テンプレートで指定されているとおり、その人物が署名者か、コピーを受け取るだけか）
field_data- テンプレートに追加されたプレフィル項目のデータを含みます
field_text_data- プレフィルとして追加されたすべてのテキスト項目について、その項目名と関連付けられた値を含むマップ
項目-boolean_data- プレフィルとして追加されたすべてのチェックボックス項目について、その項目名と真/false の値を含むマップ
is_quicksend- ブール値。真の場合はテンプレートが送信され、それ以外の場合はドキュメントが下書きとして保存され、Zoho Sign の Web ユーザーインターフェイスから手動で送信する必要があります

コード:

テンプレートに textField_1 という 1 つのプレフィル項目があり、2 人の受信者が追加されているとします。

actionMap = Map();
fieldTextData = Map();
fieldTextData。put('TextField_1', '確認用ドキュメント');
actionMap。put('field_data',{'field_text_data':fieldTextData});
eachActionMap1 = Map();
eachActionMap1。put('recipient_name','James');
eachActionMap1。put('recipient_email','james@zoho.com');
eachActionMap1。put('action_type','SIGN');
eachActionMap1。put('action_id','32076000000002014');
eachActionMap1。put('役割','Reviewer');
eachActionMap1。put('verify_recipient','無効');
eachActionMap2 = Map();
eachActionMap2。put('recipient_name','Tony');
eachActionMap2。put('recipient_email','tony@zoho.com');
eachActionMap2。put('action_type','SIGN');
eachActionMap2。put('action_id','32076000000014006');
eachActionMap2。put('役割','Manager');
eachActionMap2。put('verify_recipient','無効');
fieldList = List();
fieldList。追加する(eachActionMap1);
fieldList。追加する(eachActionMap2);
actionMap。put('処理',fieldList);
submitMap = Map();
submitMap。put('テンプレート',actionMap);
パラメーター = Map();
パラメーター。put('is_quicksend','真');
パラメーター。put('data',submitMap);
response = Zoho。sign。createUsingTemplate(32076000000002011, パラメーター);

レスポンスにはマップが含まれ、ドキュメントが正常に送信された場合、ステータスは完了になります。エラーが発生した場合、ステータスは failure となり、メッセージキーにエラーの詳細が表示されます。

ドキュメントステータスを取得する

ヘッダーに OAuth アクセストークンを含めて、ドキュメント詳細取得 APIを使用し、ステータスを含むドキュメントの詳細を取得します。

レスポンス形式:

{
'code': 0,
'requests':
{
'request_status': 'inprogress',
'メモ': 'Hi\nA メモ\nMr. Tester\nHow ar eyouuu ?',
'owner_id': '2000000002002',
'説明': '',
'request_name': '移動する a メモテスト',
'modified_time': 1522746018025,
'action_time': 1522746018310,
'is_deleted': false,
'expiration_days': 1,
'is_sequential': true,
'sign_submitted_time': 1522746018310,
'owner_first_name': 'V********',
'sign_percentage': 33.34,
'expire_by': 1522866540000,
'is_expiring': true,
'owner_email': 'v******@***.com',
'created_time': 1522746018025,
'document_ids': [
{
'document_name': '従業員 NDA.pdf',
'document_size': 26591,
'document_order': '0',
'total_pages': 2,
'document_id': '2000000492171'
}
],
'self_sign': false,
'in_process': false,
'request_type_name': 'その他',
'request_id': '2000000492177',
'request_type_id': '2000000000135',
'owner_last_name': '',
'処理': [
{
'verify_recipient': false,
'action_id': '2000000492180',
'action_type': 'SIGN',
'private_notes': '',
'recipient_name': 'S**********',
'recipient_email': 's*******@***.com',
'signing_order': 0,
'allow_signing': true,
'action_status': 'UNOPENED',
'recipient_phonenumber': '',
'recipient_countrycode': ''
}
]
},
'メッセージ': 'ドキュメントが取得されました',
'ステータス': '完了'
}

コード:

resp = invokeurl
[
url :'https://sign.zoho.com/api/v1/requests/[Requestid]'
種類 :取得する
ヘッダー:ヘッダー
];
if(resp。取得する('ステータス').contains('完了'))
{
docStatus = resp。取得する('requests').取得する('request_status');
}

すでに送信済みのドキュメントに関連付けられているファイルをダウンロードする

ドキュメントへの署名が完了したら、署名済みドキュメントをダウンロードして、アプリケーション内や CRM データ、その他の場所に保存できます。downloadDocument Deluge タスクを使用すると、これを実行できます。このタスクを使用するには、対象ドキュメントの request_id が必要です。複数のドキュメントがある場合は、すべてのドキュメントを含む ZIP ファイルが返されます。

コード: