Zoho WriterのMerge APIによるサブフォームフィールドと画像フィールドの結合

Zoho WriterのMerge APIによるサブフォームフィールドと画像フィールドの結合

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

概要

Zoho Writer のマージ API を使用すると、Zoho CRM のデータを使ってドキュメントに動的に差し込みできます。これには、標準項目、関連リスト（サブフォーム）項目、画像項目のマージが含まれます。本ガイドでは、Deluge スクリプトと API 通話の両方を使用して、サブフォーム項目および画像項目を Writer テンプレートにマージする手順を説明します。

手順

  1. Zoho Writer を開き、新しいマージテンプレートを作成します。
  2. メインタブと関連リスト（サブフォーム）の両方の項目に対して、［項目］挿入オプションを使用してマージ項目を挿入します。
テンプレートコンテンツ例:

Hello <<Contacts.First Name>>
Send a mail to <<Contacts.Email>>

Invoice Owner
Invoice Number
Created By
Due Date
<<Invoices.Invoice Owner>>
<<Invoices.Invoice Number>>
<< Invoices. Created By>>
<<Invoices.Due Date>>

Product_Code

Product_Description

Item_Quantity

Item_Price

 

«Products.Product_Code»

 

«Products.Product_Description»

 

«Products.Item_Quantity»

 

«Products.Item_Price»

手順 2: API を使用して RL 項目情報を取得する

次の Deluge コードを使用して、テンプレート内のすべてのマージ項目を取得します。
fields = invokeurl
[
type: GET
connection:'<CONNECTION_NAME>'
];
info fields;
Notes

  • <DOCUMENT_ID> を実際の Writer ドキュメント ID に置き換えてください。

  • 接続の設定方法については、Zoho Connectionsを参照してください。

手順 3: Deluge スクリプトで RL 項目をマッピングする  

invoicesRecords = zoho.crm.getRecordById('Invoices', invoiceId);

 

CustomerInvoice = Map();

CustomerInvoice.put('First_Name', invoicesRecords.get('Account_Name').get('name'));

CustomerInvoice.put('Email', invoicesRecords.get('Account_Name').get('id'));

 

invoicesList = list();

invoiceDetails = Map();

 

invoiceDetails.put('Invoices.Owner', invoicesRecords.get('Owner').get('name'));

invoiceDetails.put('Invoices.Invoice_Number', invoicesRecords.get('Invoice_Number'));

invoiceDetails.put('Invoices.Created_By', invoicesRecords.get('Created_By').get('name'));

invoiceDetails.put('Invoices.Due_Date', invoicesRecords.get('Due_Date'));

invoicesList.add(invoiceDetails);

 

productList = list();

productDetails = Map();

productDetails.put('Products.Product_Code', invoicesRecords.get('Product_Code'));

productDetails.put('Products.Product_Description', invoicesRecords.get('Product_Description'));

productDetails.put('Products.Item_Quantity', invoicesRecords.get('Item_Quantity'));

productDetails.put('Products.Item_Price', invoicesRecords.get('Item_Price'));

productList.add(productDetails);

 

 

CustomerInvoice.put('Invoices', invoicesList);

CustomerInvoice.put('Products', productList)

 

 

mergedata = Map();

mergedata.put('merge_data', {'data': CustomerInvoice});

mergedata.put('subject', 'Invoice Details');

 

//任意

mergedata.put('message', '請求書を添付しましたのでご確認ください。');

info mergedata;

 

zoho.writer.mergeAndSend('eb4kob4cf65bb6d074af7a7de21e561119eb9', 'pdf', invoicesRecords.get('email'), mergedata, '<CONNECTION_NAME>');

ステップ 4: RL 項目を含む JSON データのサンプル（API 経由）

{

'data': [

{

'First_Name': 'Amelia',

'Email': 'amelia@zylker.com',

'Invoices': [

{

'Invoices.Owner': 'John',

'Invoices.Invoice_Number': 1279,

'Invoices.Created_By': 'Amelia',

'Invoices.Due_Date': '07/10/2020'

}

]

'Products': [

{

'Products.Product_Code': 'A123',

'Products.Product_Description': 'Mobile Cases',

'Products.Item_Quantity': 2,

'Products.Item_Price': 1000

}

]

}

]

}

ステップ 5: 画像項目の値を Merge API に渡す

マージに画像項目を含めるには、次の操作を行います。
  • バージョン 5 以降の Get データ API を呼び出し、CRM レスポンスからプレビュー画像 ID [Preview_Id__s] を取得します。
  • 次のパターンを使用して、画像 URL を手動で作成します。
以下のスニペット内の変数を置き換えるためのサンプル値:
Info
タブ = '見込み客'; //それぞれのタブ名を指定します
RecordId = '456789'; //CRM データ ID
RLModuleName= 'Products'; //関連リスト名
zohoapi_domain (US DC の場合) = 'https://www.zohoapis.com';//その他の DC については API ドメインを こちらで確認してください。

標準画像項目の場合  

// レコードを取得
recordInfo = invokeurl
[
url :zohoapi_domain+'/crm/v5/'+タブ+'/'+RecordId;
type :GET
connection:'<CONNECTION_NAME>'
];
recordInfoData = recordInfo.get('data').get(0);
dataMap = Map();
dataMap.put('Email',recordInfoData.get('Email'));
dataMap.put('Last_Name',recordInfoData.get('Last_Name'));
// 画像項目
if(recordInfoData.get('Image_Upload') != null)
{
imageId = recordInfoData.get('Image_Upload').get(0).get('Preview_Id__s');
imageUrl = zohoapi_domain+'/crm/v2.1/__attachment_preview/' + imageId; //生成した画像 URL
dataMap.put('Image_Upload',imageUrl);
}
info dataMap;

関連リスト内の画像項目の場合  

画像項目が関連リストデータ内にある場合は、まず Related Records Data API（バージョン 5 以降）を呼び出して、関連リストデータ ID を取得します。その後、この関連リストデータ ID を使用して Get Records APIを呼び出し、プレビュー画像 ID を取得します。
dataMap = Map();
//関連リスト ID を取得
relatedListsIds = invokeurl
[
url:zohoapi_domain+'/crm/v5/'+タブ+'/'+RecordId+'/'+RLModuleName+'?fields=Parent_Id'
type :GET
connection:'<CONNECTION_NAME>'
];
rlListData = relatedListsIds.get('data');
rlProductsList = List();
//関連リストデータを取得
for each データ in rlListData
{
rlId = データ.getJSON('id');
rlInfo = invokeurl
[
url :zohoapi_domain+'/crm/v5/+'RLModuleName+'/' + rlId
type :GET
connection:'crm'
];
rlInfoData = rlInfo.get('data').get(0);
rlMap = Map();
rlMap.put('Product_Name',rlInfoData.getJSON('Product_Name'));
rlMap.put('Product_Code',rlInfoData.getJSON('Product_Code'));
//関連リストの画像項目
if(rlInfoData.get('Image_Upload') != null)
{
rlImageId = rlInfoData.get('Image_Upload').get(0).get('Preview_Id__s');
imageUrl = zohoapi_domain+'/crm/v2.1/__attachment_preview/' + rlImageId; //生成した画像 URL
rlMap.put('Image_Upload',imageUrl);
}
rlProductsList.add(rlMap);
}
//関連リストを dataMap に追加
dataMap.put('Products',rlProductsList);
info dataMap;

補足事項

  • 常に /fields APIを使用して、項目名を動的に取得し、正確にマッピングしてください。
  • Writer テンプレート内の 差し込み項目名が、API や Deluge スクリプトで使用している JSON キーと完全に一致していることを確認してください。
  • すべての画像項目について、画像 URL を生成する際は、__attachment_preview エンドポイントを使用します。
    https://{zohoapi_domain}/crm/v2.1/__attachment_preview/{Preview_Id__s}
  • CRM API は画像のプレビュー ID のみを提供し、完全な URL は提供しません。そのため、URL の生成は必須です。
  • 正しい API バージョン（v5 は CRM 用、v2.1 は添付ファイルプレビュー用）を使用してください。
  • Deluge を使用する場合:
    • 必ず 接続を設定してください。
    • JSON のマッピングは、Writer テンプレートの構造と一致している必要があります。
  • Writer ドキュメント IDは、URL 内の次の形式から確認できます。
    /writer/open/<document_id>

トラブルシューティング

1. エラー／症状: サブフォームの画像が表示されない、またはメールマージ中にサブフォームのレコードを追加した後に表示されなくなる。

想定される原因: 画像項目が空である、テンプレート内でのマッピングが誤っている、またはマージデータに正しく含まれていない可能性があります。
メモ:これはサブフォームの件数そのものが原因ではありません。

推奨される対処方法:
  1. 差し込み項目名が、データソース内の項目名と完全に一致していることを確認します。
  2. API を使用している場合は、Get All Fields API を使用して利用可能な差し込み項目の一覧を取得し、正しい項目 ID とサブフォーム構造を確認します。
  3. 必要に応じて、差し込み項目をテンプレートに再挿入します。