トランザクションマネージャーのユースケース:Google Docs を使用したドキュメントの生成
Google Docs と Google Apps Script を使用して、トランザクションマネージャーからドキュメントを生成します。
トランザクションマネージャーからドキュメントを生成するには、Google Docs と Google Apps Script を組み合わせることで効率的で簡単なソリューションが得られます。Apps Script を使用してカスタム API を作成することで、直接 URL から GET および POST リクエストを簡単に受信できます。これによりミドルウェアが不要になり、 CPQ や Transaction Manager などのサービスとの統合が合理化されます。
- CPQ Webhook:ドキュメントの作成を開始する POST 要求を自動的に送信します。
- トランザクションマネージャー:プロセスを管理および自動化するために使用します。
CPQデータをプルするための Google ドキュメントの設定
開発者ウィンドウにアクセスするには、スクリプトを統合する Google ドキュメントを開きます。メニューバーで、[Extensions > Apps Script] に移動して開発環境を開きます。
カスタム JavaScript を記述して、データを処理し、Apps Script エディタを使用して Google ドキュメントを操作できます。
コーディング
Google Apps Script には GET および POST 要求が含まれています。
- GET 要求 (
doGet) は単純なテキスト出力で応答し、Web アプリが実行されていることを確認するのに役立ちます。 - POST 要求 (
doPost) は、受信データ (通常は JSON) を処理し、テンプレートに基づいてドキュメントを生成し、新しく作成されたドキュメントへのリンクを返します。
この ビデオ では、Google ドキュメント アプリ スクリプトで doGet と doPost がどのように機能するかについて説明します。
トランザクションマネージャーを使用する場合は、JSON を変換して Google Docs に送信する必要があります。以下にテンプレートの例を示します。Webhook を使用している場合は、データが Google Docs に送信される方法については、「 Webhook 」を参照してください。
次のコードブロックは、doPost 関数に POST として送信される変換テンプレートの例を示しています。
{
"transaction": {
"uuid": "{{txn.uuid}}",
"term": {{txn.term}},
"stage": "{{txn.stage}}",
"status": "{{txn.status}}",
"account": "{{txn.account}}",
"endDate": "{{txn.endDate}}",
"netTotal": {{txn.netTotal}},
"termUnit": "{{txn.termUnit}}",
"createdBy": "{{txn.createdBy}}",
"quoteName": "{{txn.quoteName}}",
"startDate": "{{txn.startDate}}",
"accountName": "{{txn.accountName}}",
"createdDate": "{{txn.createdDate}}",
"opportunity": "{{txn.opportunity}}",
"paymentTerm": "{{txn.paymentTerm}}",
"quoteNumber": "{{txn.quoteNumber}}",
"contractTerm": {{txn.contractTerm}},
"contractType": "{{txn.contractType}}",
"currencyCode": "{{txn.currencyCode}}",
"estTaxAmount": {{txn.estTaxAmount}},
"modifiedDate": "{{txn.modifiedDate}}",
"billToAddress": "{{txn.billToAddress}}",
"hardwareTotal": {{txn.hardwareTotal}},
"servicesTotal": {{txn.servicesTotal}},
"shipToAddress": "{{txn.shipToAddress}}",
"softwareTotal": {{txn.softwareTotal}},
"discountAmount": {{txn.discountAmount}},
"expirationDate": "{{txn.expirationDate}}",
"lastModifiedBy": "{{txn.lastModifiedBy}}",
"primaryContact": "{{txn.primaryContact}}",
"customerSegment": "{{txn.customerSegment}}",
"discountPercent": {{txn.discountPercent}},
"transactionType": "{{txn.transactionType}}",
"estTaxPercentage": {{txn.estTaxPercentage}},
"agreementDiscount": {{txn.agreementDiscount}},
"taxEntityLocation": "{{txn.taxEntityLocation}}",
"transactionNumber": {{txn.transactionNumber}},
"totalPriceEstimate": {{txn.totalPriceEstimate}},
"overallDealDiscount": {{txn.overallDealDiscount}},
"annualTransactionBands": "{{txn.annualTransactionBands}}",
"annualTransactionCount": {{txn.annualTransactionCount}},
"accountSpecificDiscount": {{txn.accountSpecificDiscount}}
},
"lines": [
{{#each lines}}
{
"uuid": "{{txn.line.uuid}}",
"productInfo": {
"productId": "{{txn.line.productId}}",
"productSku": "{{txn.line.productSku}}",
"productCode": "{{txn.line.productCode}}",
"productName": "{{txn.line.productName}}",
"productType": "{{txn.line.productType}}",
"productDescription": "{{txn.line.productDescription}}"
},
"pricing": {
"netPrice": {{txn.line.netPrice}},
"listPrice": {{txn.line.listPrice}},
"discountAmount": {{txn.line.discountAmount}},
"discountPercent": {{txn.line.discountPercent}},
"netTotal": {{txn.line.netTotal}},
"customerLineDiscount": {{txn.line.customerLineDiscount}},
"agreementLineDiscount": {{txn.line.agreementLineDiscount}}
},
"dates": {
"startDate": "{{txn.line.startDate}}",
"endDate": "{{txn.line.endDate}}",
"createdDate": "{{txn.line.createdDate}}",
"modifiedDate": "{{txn.line.modifiedDate}}"
},
"quantity": {{txn.line.quantity}},
"currencyCode": "{{txn.line.currencyCode}}",
"configUUID": "{{txn.line.configUUID}}",
"orderDetails": {
"globalOrder": {{txn.line.globalOrder}},
"orderNumber": {{txn.line.orderNumber}},
"transactionLineNumber": {{txn.line.transactionLineNumber}}
},
"termDetails": {
"term": {{txn.line.term}},
"termUnit": "{{txn.line.termUnit}}",
"termMultiplier": {{txn.line.termMultiplier}}
},
"approvals": "{{txn.line.approvals3}}",
"lastModifiedBy": "{{txn.line.lastModifiedBy}}"
}
{{#unless @last}},{{/unless}}
{{/each}}
]
}doGet 関数を設定せずに URL にアクセスしようとすると、エラーが表示されます。doGet を他の目的で使用しない場合は、常に次のように設定し、テキストを変更するだけでよいでしょう。
function doGet(e) {
return ContentService.createTextOutput('Logik Transaction Manager Document Generation Web App is running.');
}ライブ URL にアクセスすると、次のメッセージが表示されます。
doPost は、POST 要求を介して CPQ から送信される Webhook または統合ペイロードを処理する可能性が高いため、重要です。
次に、 doPost 関数を使ってGoogleドキュメントを生成する関数を作成します。
Google Apps スクリプトでは、 doPost 関数は、Google ドキュメントテンプレートに入力するデータ (JSON 形式) を含む POST 要求を受け取ります。Google Doc を操作するための主なロジック ( つまり、{{EXAMPLE}} のようなプレースホルダーを実際の値に置き換える) は、 doPost から呼び出される別の関数に配置されます。
doPost 関数を設定するには、着信 POST 要求を処理する doPost 関数を定義し、カスタムドキュメント生成関数を呼び出します。以下は、その構成方法の例です。
function doPost(e) {
// Parse the JSON data from the POST request
const postData = JSON.parse(e.postData.contents);
// Call the function to create and populate the Google Doc
const docLink = createGoogleDocFromTemplate(postData);
// Return the public link to the generated document in the response
return ContentService.createTextOutput(docLink);
}このコードでは、次のようになります。
postDataオブジェクトには、POST 要求で送信された解析済みデータが含まれています。createGoogleDocFromTemplate(postData)は、Google Docs の生成を処理するために定義する関数です。docLinkは、生成された Google ドキュメントへの公開リンクであり、呼び出し元に返されます。
次に、ドキュメント生成機能を作成します。createGoogleDocFromTemplate 関数は次のことを行います。
- Google ドキュメントテンプレートのコピーを作成します。
- ドキュメント内のプレースホルダー (
{{EXAMPLE}}など) を、対応するデータに置き換えます。 - 生成されたドキュメントへの公開リンクを返します。
createGoogleDocFromTemplate 関数の例を示しています。function createGoogleDocFromTemplate(data) {
// Specify the ID of the Google Doc template
var templateId = 'YOUR_TEMPLATE_DOC_ID_HERE';
// Make a copy of the template
var templateDoc = DriveApp.getFileById(templateId).makeCopy();
var doc = DocumentApp.openById(templateDoc.getId());
var body = doc.getBody();
// Replace placeholders with actual data from the POST request
body.replaceText('{{ACCOUNT_NAME}}', data.transaction.accountName);
body.replaceText('{{QUOTE_NUMBER}}', data.transaction.quoteNumber);
body.replaceText('{{USER}}', data.transaction.createdBy);
// Continue to replace all other placeholders...
// Save and close the document
doc.saveAndClose();
// Make the document public (optional, based on your needs)
templateDoc.setSharing(DriveApp.Access.ANYONE, DriveApp.Permission.VIEW);
// Return the public link to the newly created document
return templateDoc.getUrl();
}この関数では、次のことを行います。
- templateId 変数には、Google ドキュメントテンプレートの ID が格納されます。「
YOUR_TEMPLATE_DOC_ID_HERE」はテンプレートの実際の ID に置き換える必要があります。 makeCopy() はテンプレートのコピーを作成します。replaceText('{{EXAMPLE}}', data.key)は、ドキュメント内の各プレースホルダーを受信 POST 要求の実際のデータに置き換えます。たとえば、{{ACCOUNT_NAME}}はdata.transaction.accountNameに置き換えられます。- ドキュメントは
setSharing()で公開されますが、必要に応じて共有設定を調整できます。
ログ記録
Google Apps Script には、デバッグ用の Logger.log() による組み込みのログ記録が用意されていますが、Google Cloud Logs ではより優れたログ記録を使用できます。ログにアクセスするには:
>に移動 スクリプトからの出力を確認します。次に、プロジェクトを Google Cloud Platform に接続してログを表示します。
Google Cloud Logs Explorer で、フィルター resource.type="app_script_function" を適用して、アプリに関連するログを表示します。
展開中
- Apps Script エディターの右上隅にある [展開] ボタンをクリックします。
- [Web アプリとして展開] を選択します。
- プロジェクトバージョンを設定します (新しいバージョンを作成することもできます)。
- アプリにアクセスできるユーザーを定義します。
- [実行方法]:これは [自分] に設定する必要があります。これにより、スクリプトがユーザーの権限で実行されます。
- アクセス権を持つユーザー: [任意の人] (公開) を選択します。
展開されると、ライブ使用用には /exec で終わり、テスト用は /dev で終わる URL が取得されます。これは、ユーザーが doGet 関数をトリガーしたり、 doPost をトリガーするための POST 要求を送信したりするためにターゲットとする URL です。
次の例では、省略記号 (...) はスクリプトの一意の App Script 番号を表しています。
- ライブ:
https://script.google.com/macros/s/.../exec - 開発:
https://script.google.com/macros/s/.../dev
変更をライブにプッシュする前にテストする場合は、開発 URL を使用して実際のデータでスクリプトをテストします。
再展開するたびに、新しいバージョンのスクリプトを作成する必要があります。次の手順を実行します。
- Google Apps Script エディターで、右上の [展開 ] ボタンをクリックします。
- メニューから [展開の管理] を選択します。
- [展開] ウィンドウで、既存の展開の [編集 ] をクリックするか、新しい展開を作成します。
- [ バージョンの選択] をクリックし、[ 新しいバージョン] をクリックします。
ポップアップウィンドウで、バージョンに名前または説明を付けることができます。これはオプションですが、変更の追跡に役立ちます。[ 保存] をクリックして新しいバージョンを作成します。
現在の展開を表示または管理するには、次の手順を実行します。
- Google Apps Script エディターで、[ 展開] をクリックします。
- [展開の管理] を選択します。ここには、スクリプトのすべてのアクティブなバージョンが表示されます。
- バージョンの横にある 3 つのドットメニューをクリックすると、任意のバージョンを編集、削除、または再展開できます。
- 編集:既存の展開を更新して新しいバージョンを指すようにします。
- 削除:展開を完全に削除します (注:展開が削除されると、ライブリンクは機能しなくなります)。
必要に応じて、古いバージョンの Web アプリにロールバックできます。
- 検索項目 .
- 元に戻したい以前のバージョンを見つけて 、[編集] をクリックします。
- [ バージョンを選択 ] メニューから以前のバージョンを選択します。
- [ 展開] をクリックして、以前のバージョンをアクティブ化します。
これにより、新しいバージョンで発生する可能性のある問題を簡単に元に戻すことができます。