You may have a requirement to generate documents using record details/information from any other application (for example any web-based ERP, CRM, Java, .NET) applications. This can be achieved by including record details in the “jsonData” tag.

You must understand how to create merge fields when creating a Composer template that will merge data from a JSON payload that is part of an API request. For more information, see the following template examples and use case.

To get the desired merge result, you must analyze your JSON data structure and understand how to structure the merge fields and tables in the templates.

Example 1

In the following image of a sample payload, you can see that we have data in two places. We have firstName, lastName, and executiveSummary, followed by products with name, quantity, price, and total.

Sample Payload

{
	"firstName": "John",
	"lastName": "doe",
	"executiveSummary": "Below, you will find a proposal, etc. etc.",
	"products": [
		{
			"name": "test product",
			"quantity": 5,
			"price": 10,
			"total": 50
		},
		{
			"name": "Creative Name",
			"quantity": 10,
			"price": 20,
			"total": 200
		}
	]
}
CODE


The template will use a different merge object syntax for the first three merge fields and then for products fields. This is how the template and the final document output would look like:

Template Example

Template Output

The MAIN table (TableStart/TableEnd) will contain everything passed into the jsonData tag, and arrays included inside the jsonData tag will be kept in a new table (TableStart/TableEnd) named after the key used in the JSON.

In the example, Composer uses MAIN for the first three merge fields (firstName, lastName, and executiveSummary) and the remaining merge fields come from the PRODUCTS fields.

Example 2

In the following image of a sample payload, you can see that we have data in four places. We have firstName, lastName, and executiveSummary, followed by:

  • Products with name, quantity, price, and total.
  • Additional information with name and value.
  • Terms

Sample Payload

{
	"firstName": "John",
	"lastName": "doe",
	"executiveSummary": "Below, you will find a proposal, etc. etc.",
	"products": [
		{
			"name": "test product",
			"quantity": 5,
			"price": 10,
			"total": 50
		},
		{
			"name": "Creative Name",
			"quantity": 10,
			"price": 20,
			"total": 200
		},
		{
		 	"name": "Other",
			"quantity": 100,
			"price": 200,
			"total": 2000
		}
	],
	"additional":[
	{
	 "name": "Arbitrary Name",
	 "value": "Additional Value"
	},
	{
	 "name": "Other Arbitrary Name",
	 "value": "Really Long Value Here, Anything goes."
	}
],
"terms":[
	{
	"text": "Lorem Ipsum dolor sit amet, consectetur adipiscing elit. 
			 Donec eu finibus massa. Ut et purus odio. Donec pellentesque,
			 urna quis molestie bibendum, nibh tortor dapibus leo, sit amet
			 tincidunt mauris mi eu quam."
	},
	{
	"text": "Etiam id felis a velit egestas aliquam at vel est. In quis tristique lacus.
			 Vestibulum sit amet nisi nisi. Proin a mauris pellentesque, condimentum 
			 ex ut, euismod orci."
	},
	{
	"text": "Quisque laoreet tincidunt velit, sit amet placerat mi suscipit ac. Ut laoreet
			 et nibh id mattis. Cras sed felis malesueda, facilisis libero in, dapidus felis. 
			 Nunc sit amet egastas velit. Integer id mollis nisi."
	{
]
}
CODE

The template uses a different merge object syntax for the first three merge fields and then for the products, additional, and terms merge fields.

Template Example

Template Output

The MAIN table (TableStart/TableEnd) will contain everything passed into the jsonData tag, and arrays included inside the jsonData tag will be kept in a new table (TableStart/TableEnd) named after the key used in the JSON.

In the example here, Composer uses MAIN for the first three merge fields (firstName, lastName, and executiveSummary), and the following tables information for the respective arrays:

  • PRODUCTS
  • ADDITIONAL
  • TERMS

Use Case

In this use case, we use the template stored in the Salesforce application, merge the document using JSON Data into PDF format and then store it in Salesforce File. All of these composer parameters are added to the LegacyOptions tag and a JSON payload in the jsonData tag in the merge request body of the Merge API call.

Step 1: Prepare Template and Queries

Create Conga Template with all merge fields and upload it to the Salesforce application. Carefully note the template's unique key values.

Step 2: Retrieve Conga Authentication Token

A Conga authentication token is required when you submit a request to merge a document or check the merge request status. To get this token, pass the client ID and client secret you obtained when enabling the Salesforce org for Conga Composer API.

Call the following Composer REST API method to get the Conga authentication token.

End Point https://login-rls.congacloud.com/api/v1/auth/connect/token
Request Method

POST

Request Header
  • Content-Type: application/x-www-form-urlencoded
  • Content-Length: <calculated when request is sent>
Request Body
  • grant_type: client_credentials
  • scope: doc-gen.composer
  • client_id: <congaAuthClientId>
  • client_secret: <congaAuthClientSecret>
Response Body
{
   "access_token ":".....token value.....",
   "expires_in": 3600,
   "token_type": "Bearer",
   "scope": "doc-gen.composer"
}
CODE

Step 3: Retrieve Salesforce Access Token

Conga's merge service needs access to the Salesforce org to retrieve master record details, fetch template details, fetch data using conga queries, and execute actions in the Salesforce org. 

Refer to the following Salesforce documentation to get the Salesforce access token:

  1. For Salesforce Connected app, see Create a Connected App
  2. For Salesforce access token, see OAuth 2.0 Username-Password Flow

In response, you will get Salesforce access token and instance URL. Salesforce access token is sent to Conga Merge Service when a request is submitted to retrieve additional details from the Salesforce application for documentation generation.

Step 4: Create Merge Request and Submit

After completing the previous three steps, you can create a merge request to generate the document. The merge request contains several parameters that determine which features are included in the generated document.

  • sessionId: The Salesforce Access Token value retrieved in step 3.
  • masterId: Master object record ID from the Salesforce application.
  • templateId: Template record ID or key value from the Salesforce application. For more information, see TemplateId parameter.

You can control the behavior of document generation by including values in the legacyOptions tag and a JSON payload in the jsonData tag in the merge request body.

In this use case:

  • DS7: Generate a document and will link it to the master record in the Salesforce application. The document is generated using data in the jsonData payload.

  • SC0, SC1: Upload generated document to files related list and will link it to the Salesforce master object record.

  • DefaultPDF: Generate a document in PDF format.

  • jsonData: Create a JSON Data body as described above in the example. 

    You must include the escape character (\) for double quotes inside the jsonData tag.

Call the following Composer REST API method to create a document using the Merge API service.

End Pointhttps://coreapps-rlsprod.congacloud.com/api/ingress/v1/Merge
Request Method

POST

Request Header
  • Authorization: Bearer <congaAuthToken>
  • Content-Type: application/json
  • Content-Length: <calculated when the request is sent>
Request Body
{
  "SalesforceRequest": {
    "sessionId": "<sfAccessToken>",
    "masterId": "<sfMasterObjectRecordId>",
    "templateId": "<sfTemplateIdRecordId>",
    "serverUrl": "<instanceUrl>/services/Soap/50.0/<orgId>"
  },
  "LegacyOptions": {
    "SC0": "1",
    "SC1": "SalesforceFile",
    "DefaultPdf": "1",
    "DS7": "11"
  },
  "JsonData": "{\"firstName\":\"John\",\"lastName\":\"Doe\",
     \"executiveSummary\":\"Below, you will find a proposal, etc. etc.\",
     \"products\":[{\"name\":\"test product\",\"quantity\":5,\"price\":10,\"total\":50},
     {\"name\":\"Creatice Name\",\"quantity\":10,\"price\":20,\"total\":200}]}",
}
CODE
Response Body
{
 "correlationId": "<correlationId>",
   "status": "Accepted",
   "result": {
     "statusCode": "Success",
     "statusMessage": [
         {
             "code": "SUCC200",
             "description": "Success"
         }
     ] 
   }
}
CODE

Step 5: Check Merge Request Status

Once you send a request to generate a document, you will receive a correlationId in response. You can check the current merge status request using this correlationId.

Call the following Composer REST API service to check the merge request status.

Call this method repeatedly with a delay until the status changes from "Pending" to "Completed" or "Error."

  • correlationId: You can find the value for this parameter from the previous step to submit the merge request’s response body.
End Point

https://coreapps-rlsprod.congacloud.com/api/status/v1/status/{correlationId}

Request Method

GET

Request Header

Authorization: Bearer <congaAuthToken>

Response Body
{
    "statusPersistanceRecord": {
        "correlationId": "<correlationId>",
        "envelope": [
            {
                "version": "1.0.0",
                "correlationId": "<correlationId>",
                "transactionId": "<transactionId>",
                "topic": {
            --------------------------------------------------
            --------------------------------------------------             
        ],
        "message": "Completed",
        "lastUpdateTimeStamp": 638036833402666423,
        "createdDate": 638036830011162087
    }
}
CODE