Transaction Manager: Integration - POST

Learn how to write data to a third-party application such as Salesforce by using the POST integration.

Prerequisites

This article assumes that you have a Logik environment that is integrated to a corresponding Salesforce [SF] environment. To complete the necessary integrations, see Installing the Salesforce Transaction Manager Integration Package extension before you continue.

When the end user initiates a function that writes Logik data back to the corresponding SF Transaction record, Logik must have the SF Transaction’s record identifier on hand. To understand how to retrieve the SF Transaction ID and save it into Logik for future use, see Transaction Manager: Integration - GET.

Salesforce setup

In this example, we write LGK data to the SF fields listed below. Please review the Salesforce Transaction and TransactionLine objects to ensure these fields are present.

Header Fields (SF object:LGK__Transaction__c)

• LGK__Stage__c: Holds the Stage of the Logik transaction.
• LGK__PricingExtendedNet__c: The transaction (header-level) net total.
• LGK__Id__c: Mapped to the id of the parent transaction.

Line Fields (SF object: LGK__TransactionLine__c)

• LGK__Quantity__c: Line-level quantity.
• LGK__PricingList__c: Line-level list price.
• LGK__PricingNet__c: Line net price, or discounted piece price.
• LGK__PricingExtendedNet__c: Line net total, or extended net price (includes quantity).
• LGK__ParentTransactionLineId__c: Checks if txn.line.custom.parentLineReferenceId exists. If it does, it assigns the corresponding line's id; otherwise, it sets the value to null.
• LGK__Product2Id__c: Mapped to the partnerId of the product associated with the current transaction line.

POST integration using Composite Graph

The LGK POST integration uses the Salesforce Composite Graph API to update multiple Salesforce objects simultaneously in a single API call, allowing both header-level and line-level fields to be updated in the same request.

The Salesforce (SF) Composite Graph API enables bundling multiple operations into a single request, making it highly efficient for integrations. It allows writing to multiple Salesforce objects in a single POST call, reducing API usage, ensuring data consistency, and enabling atomic transactions—where either all operations succeed or none are applied. This simplifies integration processes and improves error handling. For more details on the Composite Graph construct, see Composite Graph | REST API Developer Guide | Salesforce Developers.

Because the Composite Graph API is a core Salesforce capability, no setup is necessary. However, we introduce the concept here, before we populate a Composite Graph in the LGK POST call, described below. In the example below for POST, the integration uses the previously mentioned header-level and line-level fields in the Salesforce Setup section above, with the option for users to add or remove fields as per their requirements.

Transaction Manager setup

The Transaction ID mappings mentioned in the Salesforce Setup section help Logik send the right line IDs to Salesforce and manage updates, deletions, and additions effectively. By mapping LGK__TransactionId__c to the parent transaction ID, Salesforce can link all line-level changes to the correct transaction, ensuring proper association. The LGK__ParentTransactionLineId__c checks for a parent line reference; if present, it assigns the corresponding line ID, ensuring that only valid lines are updated or deleted. If no reference exists, it sets the value to null. The LGK__Product2Id__c maps to the product’s partner ID, ensuring the correct product is linked to the line for accurate pricing and discount application. These dynamic mappings ensure that Salesforce can accurately update quantities, delete lines, and add new ones while preserving user's line-level discounts by maintaining proper associations with transaction and product data.

This integration transform requires the use of two custom line fields, lineReferenceId and parentLineReferenceId. These fields must be set up to store a variation of the txn.line.id and potentially txn.line.parent.id system fields.

Rules

The Salesforce Composite Graph API does not support hyphens in certain identifiers, which can cause issues when sending data that includes hyphenated IDs, such as the LGK line IDs. To make the integration work, the system removes any hyphens present in the LGK line IDs before sending them to Salesforce. This ensures that the IDs comply with Salesforce's format requirements and that the integration functions correctly without errors related to invalid characters. By removing the hyphens, the system ensures that all identifiers are accepted by Salesforce, allowing the integration to process updates and other operations smoothly.

To remove hyphens by using a rule, create a determination rule action to make line-level reference Id fields SF-compatible. You can add both of the lineReferenceId Determination Action and parentLineReferenceId Determination Action in a single rule.

Below are two determination scripts (transaction line level) for how the fields should be defined.

// 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;

The rule should be configured as follows, with two determination actions to handle txn.line.custom.lineReferenceId and txn.line.custom.parentLineReferenceId:

Add Connection

The screenshot below shows the “External Connection” as “Salesforce” Connection in the POST integration.

If you want to create a new connection, see the "Creating a Connection" section in Transaction Manager: Integrations.

To POST data back to Salesforce, you need the SF transaction record ID. If you have not yet set up the GET integration to fetch the transaction ID, see Transaction Manager: Integration - GET.

Add integration

1. Navigate to the Integrations section and create a new integration.
   • HTTP method: POST
   • Path:/services/data/vXX.X/composite/graph, where vXX.X is the latest composite graph version. You can check for the latest version here.
   • Line Item Details to Include: Selected Lines
   • Connection: Salesforce

     

2. In the Request Transformation section, add this sample transaction JSON (header and line-level fields may vary according to your preference):

{
  "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}}
      ]
    }
  ]
}

This transformation template will be added to the Transformation Template in the Request Transformation section as follows:

For more information about Handlebar syntax, see Transaction Manager: Integrations - Handlebars syntax.

Debugging the POST call

To use the Integration Admin interface to debug a POST call that is not working as expected, follow these steps:

1. Copy the “transaction Id” for which the integration is not working and paste it in the small box “Transaction ID” and click “Fetch JSON”.

   

   The application will populate the ‘Sample Transaction JSON’ box.

   

2. Under the Transformation Template input, click “Run Transformation”. This will processes the transaction information – contained in the Sample Transaction JSON input – through the transformation logic and generate a Transformation Result that you can test using Postman.

   For more information about setting up Postman to interface with your Salesforce org, see Connect Postman to Salesforce.