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:

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 Pointhttps://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: 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.

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
{
  "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} 
}
CODE
Response Body
{
   "correlationId": "<correlationId>",
   "status": "Accepted",
   "result": {
     "statusCode": "Success",
     "statusMessage": [
         {
             "code": "SUCC200",
             "description": "Success"
         }
     ]  
   }
}
CODE

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.
End Pointhttps://coreapps-rlsprod.congacloud.com/api/presigned/v1/PreSignedService/{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

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.
End Pointhttps://coreapps-rlsprod.congacloud.com/api/presigned/v1/PreSignedService/{correlationId}
Response Endpointhttps://coreapps-rlsprod.congacloud.com/api/presigned/v1/
Request Method

GET

Request Header

Authorization: Bearer <congaAuthToken>

Response Body

The response should contain:

  • “isSuccessful” parameter: “true”

  • The URL to use to start downloading the merged document.

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

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

End Pointhttps://coreapps-rlsprod.congacloud.com/api/presigned/v1/PreSignedService/{correlationId}
Request Method

GET

Request Header

Authorization: Bearer <congaAuthToken>