トランザクションマネージャー:統合:POST
POST 統合を使用して、Salesforce などのサードパーティアプリケーションにデータを書き込む方法について説明します。
必須条件
この記事では、対応する Salesforce 環境に統合された CPQ 環境があることを前提としています。続行する前に、「 Salesforce Transaction Manager Integration Package 拡張機能のインストール 」を参照して必要な統合を完了してください。
エンドユーザーが対応する Salesforce トランザクションレコードに CPQ データを書き戻す関数を開始する場合、 CPQ Salesforce トランザクションのレコード識別子を手元に用意する必要があります。Salesforce トランザクション ID を取得し、後で使用するために CPQ に保存する方法を理解するには、「 トランザクションマネージャー:統合:GET」を参照してください。
Salesforce のセットアップ
この例では、以下にリストされている Salesforce フィールドに LGK データを書き込みます。Salesforce Transaction オブジェクトと TransactionLine オブジェクトを確認し、これらのフィールドが存在することを確認します。
ヘッダーフィールド (Salesforce オブジェクト:LGK__Transaction__c)
- LGK__Stage__cCPQトランザクションのステージを保持します。
- LGK__PricingExtendedNet__c はトランザクション (ヘッダーレベルの) 正味合計です。
- LGK__Id__c は親トランザクションの id にマッピングされます。
線グラフフィールド (Salesforce オブジェクト: LGK__TransactionLine__c)
- LGK__Quantity__c:明細レベルの数量。
- LGK__PricingList__c:明細行レベルの表示価格。
- LGK__PricingNet__c:明細正味価格、または割引個数価格。
- LGK__PricingExtendedNet__c:明細正味合計、または拡張正味価格 (数量を含む)。
- LGK__ParentTransactionLineId__ctxn.line.custom.parentLineReferenceIdが存在するかどうかを確認します。割り当てられている場合は、対応する明細の idが割り当てられます。割り当てられていない場合は、値が null に設定されます。
- LGK__Product2Id__c は、現在のトランザクション明細に関連付けられている製品の partnerId にマッピングされます。
複合グラフを使用した POST 統合
LGK POST 統合は、Salesforce Composite Graph API を使用して、1 回の API 呼び出しで複数の Salesforce オブジェクトを同時に更新し、ヘッダーレベルフィールドと行レベルフィールドの両方を同じ要求で更新できるようにします。
Salesforce Composite Graph API を使用すると、複数の操作を 1 つの要求にバンドルできるため、統合が非常に効率的になります。これにより、1 回の POST 呼び出しで複数の Salesforce オブジェクトに書き込むことができ、API の使用量が削減され、データの一貫性が確保され、すべての操作が成功するか何も適用されないアトミック トランザクションが可能になります。これにより、統合プロセスが簡素化され、エラー処理が改善されます。複合グラフ構造の詳細については、「複合グラフ |REST API 開発者ガイド |Salesforce 開発者。
複合グラフ API は Salesforce のコア機能であるため、セットアップは必要ありません。ただし、以下で説明する LGK POST 呼び出しで複合グラフを入力する前に、ここで概念を紹介します。以下の POST の例では、統合では、上記の [Salesforce セットアップ] セクションで前述のヘッダーレベルフィールドと行レベルのフィールドが使用され、ユーザーが要件に応じてフィールドを追加または削除できるオプションがあります。
トランザクションマネージャーのセットアップ
「Salesforce のセットアップ」セクションで説明されているトランザクション ID マッピングは、適切な明細行 ID CPQ Salesforce に送信し、更新、削除、および追加を効果的に管理するのに役立ちます。LGK__TransactionId__cを親トランザクション ID にマッピングすることで、Salesforce はすべての明細行レベルの変更を正しいトランザクションにリンクし、適切な関連付けを確保できます。LGK__ParentTransactionLineId__cは親ライン参照をチェックします。存在する場合は、対応する明細行 ID を割り当て、有効な明細行のみが更新または削除されるようにします。参照が存在しない場合、値は null に設定されます。LGK__Product2Id__cは製品のパートナー ID にマッピングされ、正確な価格設定と割引を適用するために正しい製品が明細行にリンクされるようにします。これらの動的マッピングにより、Salesforce は、トランザクションおよび製品データとの適切な関連付けを維持することで、ユーザーの明細行レベルの割引を維持しながら、数量を正確に更新し、明細を削除し、新しい数量を追加できるようになります。
この統合変換では、 lineReferenceId と parentLineReferenceId の 2 つのカスタムラインフィールドを使用する必要があります。これらのフィールドは、 txn.line.id および (場合によっては) txn.line.parent.id システムフィールドのバリエーションを保存するように設定する必要があります。
ルール
Salesforce Composite Graph API は特定の識別子でハイフンをサポートしていないため、LGK 行 ID などのハイフンで接続された ID を含むデータを送信するときに問題が発生する可能性があります。統合を機能させるために、Salesforce に送信する前に LGK 行 ID に存在するハイフンが削除されます。これにより、ID が Salesforce の形式要件に準拠し、無効な文字に関連するエラーなしに統合が正しく機能することが保証されます。ハイフンを削除することで、システムはすべての識別子が Salesforce によって受け入れられるようになり、統合で更新やその他の操作をスムーズに処理できるようになります。
ルールを使用してハイフンを削除するには、行レベルの参照 ID フィールドを Salesforce と互換性のあるものにする決定ルールアクションを作成します。lineReferenceId 判別アクションと parentLineReferenceId 判別アクションの両方を単一のルールに追加できます。
以下に、フィールドの定義方法に関する 2 つの決定スクリプト (トランザクション明細レベル) を示します。
// lineReferenceId Determination Action
var original = txn.line.id;
var result = "";
for (var i = 0; i < original.length; i++) {
if (original.charAt(i) !== "-") {
result += original.charAt(i);
}
}
return result;// parentLineReferenceId Determination Action
var original = txn.line.parent.id;
var result = "";
if (txn.line.parent.id != txn.id) {
for (var i = 0; i < original.length; i++) {
if (original.charAt(i) !== "-") {
result += original.charAt(i);
}
}
}
return result;ルールは次のように構成し、 txn.line.custom.lineReferenceId と txn.line.custom.parentLineReferenceIdを処理する 2 つの決定アクションを使用する必要があります。
以下のスクリーンショットは、POST 統合の外部接続が「Salesforce」であることを示しています。
新しい接続を作成する場合は、 トランザクションマネージャー:統合の「接続の作成」セクションを参照してください。
データをSalesforceにPOSTするには、SalesforceトランザクションレコードIDが必要です。トランザクション ID をフェッチするための GET 統合をまだ設定していない場合は、「 トランザクションマネージャー:統合:GET」を参照してください。
統合を追加
- [統合] セクションに移動し、新しい統合を作成します。
- HTTP メソッド:POST
- 追加パス:/services/data/vXX.X/composite/graph。 vXX.X は最新の複合グラフバージョンです。最新バージョンは こちらで確認できます。
- 含める品目の詳細:選択した明細
- 接続:Salesforce
- [変換の要求] セクションで、次のサンプルトランザクション JSON を追加します (ヘッダーレベルフィールドと行レベルのフィールドは好みに応じて異なる場合があります)。
{
"graphs": [
{
"graphId": "graph0",
"compositeRequest": [
{
"method": "PATCH",
"url" : "/services/data/v61.0/sobjects/LGK__Transaction__c/LGK__TransactionUUID__c/{{txn.id}}",
"referenceId": "parentTransaction",
"body": {
"LGK__Stage__c": "{{txn.stage}}",
"LGK__NetTotal__c": "{{txn.pricing.total}}"
}
}
{{#if lines}}
{{~#each lines~}}
{{#if txn.line.product.partnerId}}
,
{
"method": "PATCH",
"url": "/services/data/v61.0/sobjects/LGK__TransactionLine__c/LGK__TransactionLineId__c/{{txn.line.id}}",
"referenceId": "line_{{txn.line.custom.lineReferenceId}}",
"body": {
"LGK__TransactionId__c": "@{parentTransaction.id}",
"LGK__ParentTransactionLineId__c": {{#if txn.line.custom.parentLineReferenceId}}"@{line_{{txn.line.custom.parentLineReferenceId}}.id}"{{else}}null{{/if}},
"LGK__Product2Id__c": "{{txn.line.product.partnerId}}",
"LGK__Quantity__c": "{{txn.line.quantity}}",
"LGK__ListPrice__c": "{{txn.line.pricing.list}}",
"LGK__NetPrice__c": "{{txn.line.pricing.net}}",
"LGK__NetTotal__c": "{{txn.line.pricing.extendedNet}}"
}
}
{{/if}}
{{/each}}
{{/if}}
]
}
]
}この変換テンプレートは、[変換を要求] セクションの [変換テンプレート] 領域に次のように追加されます。
ハンドルバー構文の詳細については、「 トランザクションマネージャー:統合 - ハンドルバー構文」を参照してください。
POST 呼び出しのデバッグ
統合アドミンインターフェイスを使用して、期待どおりに機能していない POST 呼び出しをデバッグするには、次の手順を実行します。
- 統合が機能していないトランザクション ID をコピーし、小さな [トランザクション ID] ボックスに貼り付け、[ JSON のフェッチ] をクリックします。
アプリケーションによって [サンプルトランザクション JSON (Sample Transaction JSON)] ボックスが入力されます。
- [ 変換の実行] をクリックします。これにより、サンプルトランザクション JSON 入力に含まれるトランザクション情報が変換ロジックによって処理され、Postman を使用してテストできる結果が生成されます。
Postman を Salesforce 組織と連携させるための設定の詳細については、「 Postman を Salesforce に接続する」を参照してください。