Merge Mappings From Custom Programming (APEX) – Formstack

Trigger Formstack Documents functions as part of APEX code using the outlined functions and typical use cases.

NOTE: Troubleshoot issues related to the implementation of custom APEX code cannot be provided by Formstack Support.

Article Contents:

Generate a Document

Preview a Document

Get Generated Document Attachments

Get Generated Document URL

Generate Documents in Batch

Generate Batch Combined PDF

Merge Document without Mapping

Merge Report Data

Generate Document Merge Data

Upload File to Docs

Generate a Document

Use Case: Triggering a single document merge, for example automatically generating a document based on a specific value tied to a legal case, student application, or health record.

To trigger the merge of a specific mapping from code in your Org, use the following function to merge documents from anywhere inside your Salesforce instance to pass along the Mapping ID, Record ID, and Object name:

Boolean WebmergeGenerator.generateDocument(
    String formstackMappingId, 
    String salesforceRecordId, 
    String salesforceObjectName
);

For example, your Salesforce APEX code may look like:

Boolean mergeSuccess = webm.WebmergeGenerator.generateDocument(
    'XYZ00000001234', 
    'ABC00000000123', 
    'Account'
);

Preview a Document

Use Case: Generating a document preview within your Salesforce org. This will create a test merge with a watermark for review.

To trigger the preview for a specific mapping, you can use previewDocument() to pass along the Mapping ID, Record ID, and Object name. Here is what the function looks like:

String WebmergeGenerator.previewDocument(
    String formstackMappingId, 
    String salesforceRecordId, 
    String salesforceObjectName
);

For example, your Salesforce APEX code may look like:

String fileURL = webm.WebmergeGenerator.previewDocument(
    'XYZ00000001234', 
    'ABC00000000123', 
    'Account'
);

Get Generated Document Attachments

To get a list of the documents that were created, you can use the following function to return a list of attachment/s that have been created, but not inserted/committed, for the record:

List WebmergeGenerator.generateDocumentGetAttachments(
    String formstackMappingId, 
    String salesforceRecordId, 
    String salesforceObjectName
);

For example, your Salesforce APEX code may look like:

List generatedAttachments = webm.WebmergeGenerator.generateDocumentGetAttachments(
    'XYZ00000001234', 
    'ABC00000000123', 
    'Account'
);

Get Generated Document URL

To get a temporary URL to the file that was created, you can use the following function to return a temporary URL to download into your own file system:

String WebmergeGenerator.generateDocumentGetUrl(
    String formstackMappingId, 
    String salesforceRecordId, 
    String salesforceObjectName
);

For example, your Salesforce APEX code may look like:

String fileUrl = webm.WebmergeGenerator.generateDocumentGetUrl(
    'XYZ00000001234', 
    'ABC00000000123', 
    'Account'
);

Generate Documents in Batch

Use Case: High volume document generation whereby you want to batch the document generation to make the Salesforce org run as efficiently as possible. This is a best practice for any processes that require merging a large amount of data or a lot of records, to ensure your Salesforce Flex Queue runs optimally. This is also something you want to implement if you are seeing "Apex CPU Time Limit Exceeded" errors which tells you, you need to make your Salesforce org run more efficiently.

To generate multiple documents in batch (for example, from a list view), you can use this function to return a boolean true/false based on the success of creating the batch:

Boolean generateDocumentBatch(
    String formstackMappingId, 
    List salesforceRecordIds, 
    String salesforceObjectName
);

For example, your Salesforce APEX code may look like:

List sfRecords = new List {'ABC00000000123', 'ABC00000000789'}; 
Boolean success = webm.WebmergeGenerator.generateDocumentBatch(
    'XYZ00000001234', 
    sfRecords, 
    'Account'
);

Generate Batch Combined PDF

Use Case: You are looking to batch output a single PDF, for example, to route to a printer for printing.

To generate multiple documents in batch and combine them into a single PDF, you can use this function to return a boolean true/false based on the success of creating the batch:

Boolean generateDocumentBatchCombined(
    String formstackMappingId, 
    List salesforceRecordIds, 
    String salesforceObjectName
);

For example, your Salesforce APEX code may look like:

List sfRecords = new List {'ABC00000000123', 'ABC00000000789'}; 
Boolean success = webm.WebmergeGenerator.generateDocumentBatchCombined(
    'XYZ00000001234', 
    sfRecords, 
    'Account'
);

Merge Document without Mapping

To send data over to Formstack Documents to merge into a document (without a mapping), you can use this function to return the HttpResponse from the merge request to save the file/response from there:

HttpResponse doMerge(
    Map mergeData,
    String mergeUrl
);

For example, your Salesforce APEX code may look like:

Map mergeData = new Map{};
mergeData.put('Name', 'John Smith');
mergeData.put('Phone', '434-555-3499');
HttpResponse response = webm.WebmergeGenerator.doMerge(
    mergeData, 
    'https://www.webmerge.me/merge/12345/abcdef';
);

Merge JSON Data

You can also use JSON to send data over to your Formstack document:

HttpResponse doMerge(
    String jsonString,
    String mergeUrl
);

For example, your Salesforce APEX code may look like:

String jsonString = '{"Name":"John Smith", "Phone":"434-555-3499"}';
HttpResponse response = webm.WebmergeGenerator.doMerge(
    jsonString, 
    'https://www.webmerge.me/merge/12345/abcdef';
);

Preview Document

You can also preview a merge using doPreview() instead of doMerge():

HttpResponse doPreview(
    Map mergeData,
    String mergeUrl
);

HttpResponse doPreview(
   String jsonString,
   String mergeUrl
);

Merge Report Data

To send report data over to Formstack Documents to merge into a document, you can use this function to return a boolean true/false based on the success of creating the merge:

Boolean mergeReport(
    String reportId,
    String mergeUrl
);

For example, your Salesforce APEX code may look like:

Boolean success = webm.WebmergeGenerator.mergeReport(
    'RRR00000001234', 
    'https://www.webmerge.me/merge/12345/abcdef';
);

Generate Document Merge Data

Generate Map with merge data based on a Mapping, but get the resulting data of the mapping so you can modify it in Apex before merging the document.

This function will evaluate all the configurations defined in the mapping, including SOQL queries, and return a Map of the result. The key will be the merge field, and the value is the result of the field mapping.

Here is what the function looks like:

String WebmergeGenerator.generateDocumentMergeData(
    String formstackMappingId, 
    String salesforceRecordId, 
    String salesforceObjectName
);

For example, your Salesforce APEX code may look like:

Map generatedAttachments = webm.WebmergeGenerator.generateDocumentMergeData(
    'XYZ00000001234',  //Mapping Id
    'ABC00000000123',  //Record Id
    'Account' //Object api name
);

The following is an example of how to use generateDocumentMergeData():

Step 1

Create a Formstack Mapping and grab the ID

Step 2 - Part 1

Create a class called: NewDocument and include the following code(make sure to enter the merge URL of your document in the doMerge() method ):

public class NewDocument {
    public Id Id { get; set; }
    public String Name { get; set; }
    public String Phone { get; set; }
    public Account acct { get; set; }
    public NewDocument(ApexPages.StandardController controller) {
        acct = (Account) controller.getRecord();
        Id = acct.Id;
    }
    public PageReference GenerateDocument() {
        Map generatedAttachments = new Map{};
        //Generate merge data
        generatedAttachments = webm.WebmergeGenerator.generateDocumentMergeData(
            'a06ak000005AaRHAA0',  //Mapping Id
            '001ak00000UVRmDAAX',  //Record Id
            'Account' //Object api name
        );
        HttpResponse response = webm.WebmergeGenerator.doMerge(
            generatedAttachments,
            'https://www.webmerge.me/merge/1153297/e9l8pc '
        );
        PageReference pageRef = new PageReference('/'+Id);
        pageRef.setRedirect(true);
        return pageRef;
    }
}

Step 2 - Part 2

Create a new VisualForce page with and include the following code:

Step 3

Place that Visualforce page as a button in any place inside the Account layout.

Step 4

Go to any of the Account records and click on the "Merge Document" button.

Expected Result

If you go to your Formstack Documents account, you should see a merge successfully executed.

Also, the Salesforce data should be there.

Upload File to Docs

In order to programmatically merge Salesforce files, it is necessary to generate a publicly accessible URL, allowing Formstack Documents to retrieve, download, and merge the file seamlessly.

Use Case: Generate publicly available URLs from Salesforce files, you can use uploadFileToDocs() to pass along the Blob and File name.

Here is what the function looks like:

String WebmergeGenerator.uploadFileToDocs(
    Blob sampleFileBody, 
    String fileName
);

For example, your Salesforce APEX code may look like:

// Create Blob
String sampleText = 'This is a test file for upload.';
Blob sampleFileBody = Blob.valueOf(sampleText);
String fileName = 'TestFile.txt';
// Generate File URL
String fileUrl = webm.WebmergeGenerator.uploadFileToDocs(sampleFileBody, fileName);

For the fileName be sure to include a valid file type from the following list:

  'pdf',
    'docx',
    'doc',
    'docm',
    'xlsx',
    'xls',
    'xlsm',
    'pptx',
    'ppt',
    'txt',
    'png',
    'bmp',
    'gif',
    'jpg',
    'jpeg',
    'html',
    'xml',
    'csv',
    'tif',
    'tiff'

The following is an example of how to use uploadFileToDocs():

Step 1

Create a class called: NewDocument and include the following code(make sure to enter the merge URL of your document in the doMerge() method ):

public class NewDocument {
    public Id Id { get; set; }
    public String Name { get; set; }
    public String Phone { get; set; }
    public Account acct { get; set; }
    public NewDocument(ApexPages.StandardController controller) {
        acct = (Account) controller.getRecord();
        Id = acct.Id;
        Name = acct.Name;
        Phone = acct.Phone;
    }
    public PageReference GenerateDocument() {
        system.debug('Name'+ Name);
        system.debug('Phone:'+ Phone);
        // Create Blob
        String sampleText = 'This is a test file for upload.';
        Blob sampleFileBody = Blob.valueOf(sampleText);
        String fileName = 'TestFile.txt';
        // Generate File URL
        String fileUrl = webm.WebmergeGenerator.uploadFileToDocs(sampleFileBody, fileName);
		System.debug('File URL: ' + fileUrl);
        Map mergeData = new Map{};
        mergeData.put('Name', Name);
        mergeData.put('Phone', Phone);
        mergeData.put('fileUrl', fileUrl);
        HttpResponse response = webm.WebmergeGenerator.doMerge(
            mergeData,
            'https://www.webmerge.me/merge/1153297/e9l8pc '
        );
        PageReference pageRef = new PageReference('/'+Id);
        pageRef.setRedirect(true);
        return pageRef;
    }
}

Step 2

Create a new VisualForce page with and include the following code:

Step 3

Place that Visualforce page as a button in any place inside the Account layout.

Step 4

Go to any of the Account records and click on the "Merge Document" button.

Expected Result

If you go to your Formstack Documents account, you should see a merge successfully executed.

Also, the Salesforce data should be there.

Merge JSON Data

Preview Document

Related articles