Generate Document Using JSON Data

This topic describes the details and simple steps for grabbing the template from your cloud storage provider, generating the document with JSON data, and sending the generated document to your cloud storage provider. You might use this functionality differently to generate documents depending on your business case.

You can use the following cloud storage providers as per your business use case:

• AWS
• Box
• Google Drive
• DropBox
• OneDrive
• Salesforce
• SharePoint
• SFTP

Prerequisites

• Contact your Account Executive with your 18-digit OrgID to enable the Composer API feature.

• Refer to the Authentication section to generate the Client ID and Client Secret that will be used in the code to connect to the Conga Authorization server.

• Authorize yourself to connect with the required cloud storage providers from the Composer Setup menu > Document Download Delivery for API.
• Refer to the How to get File ID for Composer API Request topic for the File ID that will be used in the request body for grabbing and sending the generated document to your cloud storage provider.
• Refer to the JSON Payload Template Example and Use Case topic for the template creation when you have JSON data payload to be merged into the template. 

Use Case

In this use case, we use the template saved in your Sharepoint, merge the document with JSON data, convert it to PDF format, and then store it in your Sharepoint folder and also in Notes & Attachments on the Salesforce master object. All of these composer parameters are added to the legacyOptions tag of the merge request body, as well as a JSON payload in the jsonData tag.

Step 1: Prepare the Template and Store it in your Sharepoint folder

Create a template with all merge fields and upload it to your Sharepoint folder. Carefully note the template's file ID. For more information on how to create a template and get the File ID, see the following topics:

• JSON Payload Template Example and Use Case

• How to get a File ID for Composer API Request

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.

{
   "access_token ":".....token value.....",
   "expires_in": 3600,
   "token_type": "Bearer",
   "scope": "doc-gen.composer"
}

Step 3: Retrieve Salesforce Access Token

Conga's merge service needs access to the Salesforce org to retrieve master record details 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.

In the merge API request body, you can control the behavior of document generation by including values in the legacyOptions tag, a JSON payload in the jsonData tag, grabbing the template from your cloud storage provider in the TemplateSources tag, and sending the generated document to your cloud storage provider in the Destinations tag.

In this use case:

• SC0, SC1: Upload generated document to Notes & Attachments on the Salesforce master object record.

• DefaultPDF: Generate a document in PDF format.

• OFN: Output File Name, overriding the default name of the file.

• 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.

• TemplateSources
  • IntegrationName: sharepoint (name of the cloud storage provider)
  • FileID: The location of a template file.
• Destinations
  • IntegrationName: sharepoint (name of the cloud storage provider)
  • FolderID: The location of a folder where you want to save the generated file.

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

{
  "SalesforceRequest": {
    "sessionId": "<sfAccessToken>",
    "masterId": "<sfMasterObjectRecordId>",
    "serverUrl": "<instanceUrl>/services/Soap/50.0/<orgId>"
  },
  "LegacyOptions": {
    "SC0": "1",
    "SC1": "attachments",
    "DefaultPdf": "1",
    "OFN": "SharePoint to SharePoint Testing"
  },
  "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}]}",
  "TemplateSources": [
    {"IntegrationName":"sharepoint", "FileId": "a38e07e6-24f8-487f-bc38-8948f3c3840d,Folder1/Folder2/test1.docx"}
  ]
  ,
  "Destinations": [
    {"IntegrationName": "sharepoint", "FolderId": "a38e07e6-24f8-487f-bc38-8948f3c3840d,Folder1/Folder2/Folder3"}
  ]
}

{
   "correlationId": "<correlationId>",
   "status": "Accepted",
   "result": {
     "statusCode": "Success",
     "statusMessage": [
         {
             "code": "SUCC200",
             "description": "Success"
         }
     ]  
   }
}

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.

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