Generate and Download Document

This topic describes the details and steps for generating the document with JSON data and downloading the generated document to your browser. You might use this functionality differently to generate documents depending on your business case.

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.

Use Case

In this use case, we use the template saved in your Box account, merge the document with JSON data, convert it to PDF format, and then download it. 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.

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

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

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

Create a template with all merge fields and upload it to your Box 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: 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.

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, and getting the template from your cloud storage provider in the TemplateSources tag.

In this use case:

• 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: box (name of the cloud storage provider)
  • FileID: The location of a template file.

• generateDocumentDownload under output must be set to true. 
  

  

  For example

  "output": {

        "generateDocumentDownload": true

  }

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

{
  "LegacyOptions": {
    "DefaultPdf": "1",
    "OFN": "Box + Document Download 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":"box", "FileId": "{{FileId}}"}
  ],
  "output": {"generateDocumentDownload": true} 
}

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

Step 4: 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
    }
}

Step 5: Get the Downloadable URL(s)

After receiving a Completed status response in step 4, the document is ready to be downloaded.

Call the following Composer REST API service to get the downloadable URL(s) for download.

• lookupId: CorrelationId that you can find from the response of step 3.

{
    "isSuccessful": true,
    "statusCode": 200,
    "preSignedCreateResponseModel": {
        "correlationId": "<correlation id>",
        "fileInfoDetailsList": [
            {
                "transactionId": "<transactionId>",
                "url": "https://ENVIRONMENT_DOMAIN/PreSignedService/523954f3264c463fa6cbf36deaed3df2_DatasetJson/aae1bdcb-e520-4581-8e96-23aae5bc0b88/{{filename}}",
                "fileName": "<file name of document>",
                "tags": null
            }
        ]
    }
}

Step 6: Download the Document

Use the lookupIds available in the URL received in the response of step 5 to download the document.

Call the following Composer REST API service to download the document:

Refer to the example below to understand how to obtain the lookupId1 and lookupId2 from the URL received in step 5.

For example: If the URL received is: https://ENVIRONMENT_DOMAIN/PreSignedService/523954f3264c463fa6cbf36deaed3df2_DatasetJson/aae1bdcb-e520-4581-8e96-23aae5bc0b88/<filename>, then lookupId1=523954f3264c463fa6cbf36deaed3df2_DatasetJson and lookupId2=aae1bdcb-e520-4581-8e96-23aae5bc0b88