Zoho CRMからのZoho Sign文書送信と署名完了時のステータス更新

Zoho CRMからのZoho Sign文書送信と署名完了時のステータス更新

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

概要：

Zoho CRM から取引先担当者／見込み客（エンドユーザー）に署名依頼用の文書を送信する場合、Zoho Sign 拡張機能で追加される「Send for Zoho Sign」既定ボタンを使用するか、ワークフローやボタンに関連付けたカスタム関数を使用して送信します。このとき、受信者が署名文書内で入力した項目値は、組み込みの自動化機能では Zoho CRM に書き戻すことができず、署名文書がカスタム関数で作成されているため、拡張機能側でも文書のステータスを追跡できません。これを解決するための回避策をご紹介します。

Info
以下のソリューションは、署名完了時に Zoho Sign から詳細を取得するために Zoho Flow を利用するため、Zoho One ユーザー、または Zoho Flow 有料スタンドアロンユーザーの場合に Zoho Flow を使って導入できます。

ユースケース：

Zoho CRM の取引先担当者データに対して Zoho Sign 文書を送信するシナリオを想定します。文書には、エンドユーザーが署名するための署名項目と、エンドユーザーが入力する「Company Name」という別の項目が含まれています。
 
サンプルスクリプト：
取引先担当者データのメールアドレス宛てに署名文書を送信します。
 
  1. templateid = '476594000000050259';
  2. actionid = '476594000000050280';
  3. contactdetails = zoho.crm.getRecordById('Contacts',ContID);
  4. ContactEmail = contactdetails.get('Email');
  5. CompanyName = contactdetails.get('Account_Name').get('name');
  6. AccountID = contactdetails.get('Account_Name').get('id');
  7. FirstName = contactdetails.get('First_Name');
  8. LastName = contactdetails.get('Last_Name');
  9. actionMap = Map();
  10. fieldTextData = Map();
  11. fieldTextData.put('Company','' + CompanyName + '');
  12. fieldTextData.put('First Name','' + FirstName + '');
  13. fieldTextData.put('Last Name','' + LastName + '');
  14. actionMap.put('field_data',{'field_text_data':fieldTextData});
  15. eachActionMap1 = Map();
  16. eachActionMap1.put('recipient_name','' + FirstName + '');
  17. eachActionMap1.put('recipient_email','' + ContactEmail + '');
  18. eachActionMap1.put('action_type','SIGN');
  19. eachActionMap1.put('action_id',actionid);
  20. eachActionMap1.put('role','Reviewer');
  21. eachActionMap1.put('verify_recipient','false');
  22. fieldList = List();
  23. fieldList.add(eachActionMap1);
  24. actionMap.put('actions',fieldList);
  25. submitMap = Map();
  26. submitMap.put('templates',actionMap);
  27. parameters = Map();
  28. parameters.put('is_quicksend','true');
  29. parameters.put('data',submitMap);
  30. sendtemplate = zoho.sign.createUsingTemplate(templateid,parameters);
  31. info sendtemplate;
 
ここで、
  1. templateidは、Zoho Sign で作成したテンプレートの ID です。
  2. actionidは、次のサンプルを使用して取得できます。
    1. actiondetails = zoho.sign.getTemplates();
    2. actionid = actiondetails.get('templates').getJSON('actions');
  3. 引数 ContID には、対象となる取引先担当者の ID をマッピングします。
次に、文書のステータスと、受信者が文書内で入力した値を取得し、Zoho CRM に書き戻す手順を見ていきます。 

手順 1：

上記の関数に、Zoho CRM 内に Zoho Sign 文書データを作成するためのスクリプトの一部を追記して修正する必要があります。

Notes
メモ：

「Zoho Sign Document」は、Zoho CRM 用 Zoho Sign 拡張機能によって作成されるカスタムタブです。「Send for Zoho Sign」ボタンを使用して Zoho Sign 文書を署名依頼として送信すると、「Zoho Sign document」タブにデータが作成されます。このデータには、文書 ID（Zoho Sign 文書 ID）、文書が送信された CRM 上の親レコード、文書のステータスなどの情報が含まれます。
 

スクリプト：

  1. SignDocumentID = sendtemplate.get('requests').get('request_id');
  2. DocumentName = sendtemplate.get('requests').get('request_name');
  3. mp = Map();
  4. mp.put('zohosign__Contact',ContID);
  5. mp.put('zohosign__Account',AccountID);
  6. mp.put('zohosign__ZohoSign_Document_ID',SignDocumentID);
  7. mp.put('Name',DocumentName);
  8. Create = zoho.crm.createRecord('zohosign__ZohoSign_Documents',mp);
  9. info Create;
 
ここで、
  1. コード内の 'zohosign__Contact'、'zohosign__Account'、'zohosign__ZohoSign_Document_ID'、'Name' は、Zoho Sign Documents タブにある取引先担当者、取引先、Zoho Sign 文書 ID、Zoho Sign 文書名フィールドの API 名に置き換えてください。
  2. 'zohosign__ZohoSign_Documents' は、Zoho Sign Documents タブのタブ API 名に置き換えてください。
  3. ContId と AccountId は、それぞれ取引先担当者データと取引先データの ID です。

上記の変更を反映したサンプルスクリプトは次のとおりです：
必要なタブにデータを作成し、要求を追跡できるようにします。

  1. //actionid の詳細を取得
  2. /*actiondetails = zoho.sign.getTemplates();
  3. actionid = actiondetails.get('templates').getJSON('actions').getJSON('action_id');
  4. info actionid;*/
  5. templateid = '476594000000050259';
  6. actionid = '476594000000050280';
  7.  
  8. //取引先担当者と取引先の詳細を取得
  9. contactdetails = zoho.crm.getRecordById('Contacts',ContID);
  10. ContactEmail = contactdetails.get('Email');
  11. CompanyName = contactdetails.get('Account_Name').get('name');
  12. AccountID = contactdetails.get('Account_Name').get('id');
  13. FirstName = contactdetails.get('First_Name');
  14. LastName = contactdetails.get('Last_Name');
  15.  
  16. //Zoho Sign テンプレートを使用して、事前入力済みフィールドを持つ Zoho Sign ドキュメントを作成するためのパラメータマップを作成
  17. actionMap = Map();
  18. fieldTextData = Map();
  19. fieldTextData.put('Company','' + CompanyName + '');
  20. fieldTextData.put('First Name','' + FirstName + '');
  21. fieldTextData.put('Last Name','' + LastName + '');
  22. actionMap.put('field_data',{'field_text_data':fieldTextData});
  23. eachActionMap1 = Map();
  24. eachActionMap1.put('recipient_name','' + FirstName + '');
  25. eachActionMap1.put('recipient_email','' + ContactEmail + '');
  26. eachActionMap1.put('action_type','SIGN');
  27. eachActionMap1.put('action_id',actionid);
  28. eachActionMap1.put('role','Reviewer');
  29. eachActionMap1.put('verify_recipient','false');
  30. fieldList = List();
  31. fieldList.add(eachActionMap1);
  32. actionMap.put('actions',fieldList);
  33. submitMap = Map();
  34. submitMap.put('templates',actionMap);
  35. parameters = Map();
  36. parameters.put('is_quicksend','true');
  37. parameters.put('data',submitMap);
  38.  
  39. // テンプレートを作成
  40. sendtemplate = zoho.sign.createUsingTemplate(templateid,parameters);
  41. info sendtemplate;
  42. // Zoho CRM 内に Zoho Sign ドキュメントを作成
  43. SignDocumentID = sendtemplate.get('requests').get('request_id');
  44. DocumentName = sendtemplate.get('requests').get('request_name');
  45. mp = Map();
  46. mp.put('zohosign__Contact',ContID);
  47. mp.put('zohosign__Account',AccountID);
  48. mp.put('zohosign__ZohoSign_Document_ID',SignDocumentID);
  49. mp.put('Name',DocumentName);
  50. Create = zoho.crm.createRecord('zohosign__ZohoSign_Documents',mp);
  51. info Create;
 
Notes
メモ：
既存の関数にこの追加コードを組み込むことで、ドキュメントが署名用に送信されたタイミングで、Zoho CRM 内に Zoho Sign ドキュメントデータが作成されるようになります。また、署名ドキュメントのドキュメント ID を取得し、この CRM データに更新します。後から、このドキュメント ID を使用して、Zoho Sign 内の該当する署名ドキュメントからフィールド値を取得できます。

Step 2 :

Zoho Flow でフローを作成し、ドキュメントのステータス（Signed/Completed）が変更されたときにトリガーされるように設定し、その内容を Zoho CRM に更新する必要があります。Zoho Flow を使用する理由は、この自動化は Zoho Sign または Zoho CRM では設定できず、この処理に対する有効なトリガーポイントが存在しないためです。

Zoho Flow の一連の設定手順については、以下のスクリーンキャストを参照してください。


Step 3 :

Zoho CRM の Zoho Sign Documents タブに対してワークフローを設定します。ワークフローは、Zoho Sign ドキュメントデータのステータスが「Signed」に更新されたときにトリガーされます。目的は、署名ドキュメントで更新された値を取得し、同じ内容を取引先担当者データに反映することです。

  1. ［設定］>［自動化］>［ワークフフロー ルール］に移動し、［ルールを作成］をクリックします。
  2. タブ名として「Zoho Sign Documents」を選択し、ワークフロー ルールの名前を指定します。
  3. 次に、トリガーとして「データのアクション」の「編集」を選択し、続く項目で「特定の項目が変更された場合」を選択します。項目名の選択を求められますので、「Document Status」項目を選択します。

  4. ワークフローの条件を「Document Status が Signed」で設定します。

  5. ［即時アクション］で［関数］>［関数を設定］をクリックし、関数名を入力して、関数名と表示名を指定します。次に、以下のコードを貼り付けます。
 
  1. //SignDocument レコードの詳細を取得
  2. signdocumentdetails = zoho.crm.getRecordById('zohosign__ZohoSign_Documents',ID);
  3. DocID = signdocumentdetails.get('zohosign__ZohoSign_Document_ID');
  4. ContactID = signdocumentdetails.get('zohosign__Contact').get('id');
  5. documentdetails = zoho.sign.getDocumentById(DocID);
  6.  
  7. //CRM で更新する項目を取得
  8. CRMFieldInfo = documentdetails.get('requests').get('actions').get(0).get('fields');
  9. //info CRMFieldInfo;
  10. //連絡先データを更新
  11. for each rec in CRMFieldInfo
  12. {
  13. if(rec.get('field_name') == 'Company')
  14. {
  15. Company = rec.get('field_value');
  16. info Company;
  17. mp = Map();
  18. mp.put('Title',Company);
  19. update = zoho.crm.updateRecord('Contacts',ContactID,mp);
  20. info update;
  21. }
  22. }
 

Notes
Notes :
マップ内の「ID」を、対応する Zoho Sign ドキュメント ID と関連付けてください。Company は、受信者に入力してもらうために署名ドキュメント内に追加した項目です。


 

Conclusion:

上記の手順を Flow で実装することで、ドキュメントを受信者に送信して署名してもらい、署名プロセス中に受信者が入力した値を自動的に取得して Zoho CRM に反映させることができ、スムーズかつ効率的なデータ同期が実現します。

上記の Flow を使用したコードでは、以下の内容を更新しています。
  1. Zoho Sign ドキュメントが Zoho CRM から特定の連絡先レコードに対して直接送信されます。
  2. エンドユーザーはメール通知を受け取り、ドキュメントを開いて署名します。署名プロセス中に、「Company」という名前の追加項目の入力を求められます。
  3. ドキュメント送信後、Zoho Sign Documents タブ内の対応するレコードのデータは、Flow によってステータスが Signed に自動更新されます。
  4. 上記の処理に基づき、連絡先タブ用に作成したワークフローによって、取得した Company の値が Contacts タブ内の「Title」という項目に更新されます。
上記手順の結果については、以下のスクリーンキャストをご参照ください。
 

 
 

Tips:

  1. スクリプト内では、タブおよび項目の API 名を正しく使用していることを確認してください。
  2. スクリプト作成時は、Zoho CRM の Function IDE 内のコンソールセクションで動作を確認できるよう、各変数に対して info() ログを追加することをお勧めします。
  3. ステートメント数や実行時間の制限に抵触しないよう、カスタム関数では最適化されたコードを使用してください。詳細は Deluge の制限事項をご参照ください。
  4. 関数スクリプト内でコネクションを使用する場合は、想定する API アクションを実行できるよう、コネクションに必要なスコープが追加されていることを確認してください。また、Deluge の Invoke URL や統合タスクに渡す際は、コネクションのリンク名（例：crm_connection）を使用してください。
  5. Deluge 関数で get() メソッドを使用する際は、「get value is null」というエラーが発生して即時に実行が停止するのを防ぐため、ifNull() 条件文を併用するようにしてください。関数をワークフロー ルールなどの自動化に関連付けている場合、このエラーが発生すると該当データの関数実行が停止します。ifNull 文の詳細については、ヘルプリンクをご参照ください。
  6. 自動化機能（例：ワークフロー ルール）経由で、関連付けられた関数が対象データで実行されていない場合は、「設定 >> Developer Hub >> Functions >> Failures」で失敗理由を確認してください。
 
Notes
Notes :
ヘルプリンクにアクセスして、カスタム関数の実行中に発生する可能性のある一般的な Deluge エラーメッセージについてご確認ください。
  

コードの最適化方法

本番環境でのログ出力を最小限にする
  1. info() ログを過度に追加すると、実行速度が低下する可能性があります。テスト時には各変数に info() ログを追加し、テスト完了後は不要な info() ログをコメントアウトしてください。つまり、デバッグ目的でのみ条件付きログを使用するようにします。

Try-Catch ブロックを使用する
  1. すべての行を try で囲むのではなく、try-catch ブロックを使用して例外を適切に処理してください。コードのどの行で問題が発生したかを特定できるよう、必要なエラーメッセージをログに出力します。構文とサンプルコードについては、以下のヘルプリンクを参照してください。

Notes
Notes :
スムーズに導入するため、本番環境にデプロイする前に、まずサンドボックス環境で設定を構成・テストすることをお勧めします。


Quote
本カスタムソリューションは、Zoho パートナーサポートの Sakthi Priya によって作成されました。

ご不明な点がございましたら、partner-support@zohocorp.com までお気軽にお問い合わせください。

Notes
また、「ヨーロッパおよび英国のパートナー」の皆さまは、partner-support@eu.zohocorp.com までご連絡くださいますようお願いいたします。