Introduction

When you leverage the S-Docs Mass Merge document feature, you have the power to generate a large number of documents for any object with just a few clicks. Once you enable this feature, all you have to do is select an object, select the records that you would like to generate documents for, and select the S-Docs templates for each document generated. For example, if you need to generate an account summary for every account in your Salesforce database, S-Docs can provide you with a solution in just a few simple clicks.

Additionally, the mass merge feature provides the ability to merge an entire batch of documents into a single document in a matter of seconds. As an example, if your task was to generate and print a large number of documents, you could simply perform a mass merge and print the resulting document, rather than generate a document for each record, having to download and print each one individually. When you take advantage of the S-Docs mass merge and batch documents feature, you eliminate tedious work and gain more time to focus on the bigger picture.

Preview: The Mass Merge & Batch Document Feature in Action

Before we get into the details of setting up and configuring a mass merge, we will explore this feature in action. In the following preview, we will be generating account summaries for contacts and combining the resulting batch of documents into a single printable PDF. We begin by creating a list view that lists all of our contacts with overdue accounts, and selecting all of the resulting contacts.

We then click the Add to Mass Merge List button at the top of the list view page to add these records to our mass merge list. We then click the View Mass Merge List button, bringing us to the mass merge page. Here, we can select up to 2 templates that we would like to use for this mass merge (note that the COMBINE ALL into single printable doc button only supports the selection of one template). In this case, we'll select the Account Past Due template, then click Go To Next Step.

On this page, we can review all of the records that we added to the mass merge list. We've added the mailing information for each of our contacts displayed in this list, but you can add any combination of relevant fields. Once we're satisfied with the records, we can click Start Mass Merge. A unique document will generate for each record in our list.

Note that there is a PDF icon next to each contact after generating the documents. A document can be downloaded by clicking on one of these icons. Each document is attached to the record it was generated for; if we go to the contact record page for “Jack Rogers,” the documents will be included in the S-Docs related list on that page, where we can download and/or email each document whenever we’d like. Thus, we have generated a batch of documents for a group of contacts.

At this point, we click the COMBINE ALL into single printable doc button in order to combine all of the generated documents into a single PDF file.

We can also print mailing labels for each of our contacts. Click here for a free mailing label template. In the "Print Labels/Envelopes" tab, all S-Docs Templates with a Document Category of "Mailing Label" will be available to choose from (if your version of S-Docs is missing "Mailing Label" from the "Document Category" picklist on the S-Docs Template object, you'll need to add it to the picklist values manually). To print mailing labels, we simply select a label template and click Print Labels/Envelopes to download a single DOC containing all of the mailing labels for easy printing.

Note: Combining all of the documents in a single printable document is limited to PDF templates only; however, we can generate large numbers of documents for any output file format supported by S-Docs.

Once we download our mass merged PDF and mailing label, we print them and that’s it! We have just printed cover letters, account summaries, and mailing labels for ten contacts with overdue accounts in just a few clicks, and we can now mail these documents to the contacts in question.

In the remainder of this guide, we will be setting up the buttons, pages, and lists that will enable the mass merge and batch document features for a particular Salesforce object.

Note: You will need to have at least one template created for the object that you would like to use in your mass merge. Additionally, if you are following these steps for a contact, then you can skip to Step 4: Add Buttons to Search Layouts. This is because for contacts, the Visualforce page and the Add to Mass Merge List and View Mass Merge List buttons come prepackaged with S-Docs.

STEP 1: Setting up S-Docs Mass Merge

Setting up mass merge in S-Docs requires a Visualforce page (one for each object used in mass merge) and a single Apex class, which we've provided here.

Note that you'll only have to create the page SDMassMerge once for all the objects you are setting up mass merge on. However, you will need to set up the Visualforce page for each object you are setting up mass merge on.

Create a new Apex class. To get this page, navigate to the Setup menu and type Apex Classes into the Quick Find bar. Click Apex Classes (under Custom Code) and then click New.

Paste in the following code (you only need to create this class once):
Your Apex Class should look like this:

Click Save.

Next, for each object that users will perform mass merge on, you'll need to create a Visualforce page. Navigate to the Setup menu and type Visualforce Pages into the Quick Find bar. Click Visualforce Pages, then click New.

Create a new Visualforce page called SDAddToMassMergeCHANGE_TO_YOUR_OBJECT_NAME using the following code:

Note: Make sure to change OBJECTAPINAME in the first line of code to the name of your object.

Note: When naming your Visualforce page, omit the __c if your object name contains it, as double underscores aren't allowed in VisualForce page names (but the __c does need to be included for custom objects in the code for the VisualForce page). It actually doesn't matter what the name of your page is. SDAddToMassMergeCHANGE_TO_YOUR_OBJECT_NAME is simply a naming convention intended to keep your Visualforce page collection neat and organized in case you have to create this page for several objects.

Make sure Available for Lightning Experience... is checked. For example, if your object API name is Check__c, your Visualforce Page should look like this:


If you require test coverage for the SDAddToMassMerge class, you can use the following test class (replacing all references to Opportunity with your object):


To recap:

  • Create only one Apex class
  • Create a Visualforce page for each object (and later a button for each object)

For example, after you performed these steps for 3 different objects, you would have created 3 Visualforce pages (one for each object), but just one Apex class (this class would control all 3 pages).

STEP 2: Create the "Add To Mass Merge List" button

1. Now, navigate to the “Buttons, Links, and Actions” page for the Salesforce object that you would like to use in a mass merge.

In Salesforce Lightning, simply navigate to Setup > Object Manager > Your Object > Buttons, Links, and Actions > New Button or Link.

In Salesforce classic, the instructions for custom and standard objects are a bit different.

Note: If you’re performing a mass merge on a custom object, please follow the instructions for part (a). If you’re performing a mass merge on a standard object, please follow the instructions in part (b).

a.) Creating a new button for a custom object

Navigate to the Setup menu and type Objects into the Quick Find bar. Click objects, then find the name of the custom object that you would like to use in a mass merge. Click the name of the object (do not click the edit button). In this example, we will be creating an Add to Mass Merge List button for the Check object, a custom object representing the data for a standard business check.

Next, a page will display for your custom object.

Take note of the API name at this point, as you will require it in later steps. The API name is often just the “Object Name” appended with __c (note the two underscores), but sometimes this is not the case, so please take note of that here. In the case of our custom Check object, we will note that our API name is Check__c.

On the page for your custom object, scroll down to “Buttons, Links, and Actions” and click New Button or Link. This concludes part (a).

b.) Creating a new button for a standard object

Navigate to the Setup menu and type the name of your standard object into the Quick Find bar. Find and click on Buttons, Links, and Actions in the dropdown menu. Then, click New Button or Link.

At this point, please note the API name for your standard object:

mass merge - step 1 (7)

Note that the API name is the same as the object name for all objects except for products; for a product, the API name will be Product2. This concludes part (b).

2. We will now define our button. For the fields listed on the “New Button or Link” page, please use the following:
Label: Add to Mass Merge List
Name: Add_to_Mass_Merge_List
Display type: List Button (please ensure that Display Checkboxes (for Multi-Record Selection) is checked as well)
Behavior: Display in Existing Window without Sidebar or Header
Content Source: URL
URL: /apex/SDAddToMassMergeCHANGE_TO_YOUR_OBJECT_NAME?objectName=CHANGE_TO_YOUR_OBJECT_API_NAME

Once completed, the page should appear as follows:

Note: If your use case requires a View Mass Merge List button in addition to the Add To Mass Merge List button, you can simply repeat this step, naming the button "View Mass Merge List" instead of "Add To Mass Merge." This works because the Add To Mass Merge button redirects to the mass merge page by default.

STEP 3: Add Button to Search Layout

1. You will now need to edit the list view page for your object.

In Salesforce Lightning, simply navigate to the object manager page for your object and click Search Layout for Salesforce Classic in the sidebar. Find the List View layout and click Edit, then add the Add To Mass Merge List button to the layout.

In Salesforce classic, the instructions for custom and standard objects are a bit different.

Note: If you’re performing a mass merge on a custom object, please follow the instructions for part (a). If you’re performing a mass merge on a standard object, please follow the instructions in part (b).

a.) Adding buttons to search layouts for a custom object

Navigate to the Setup menu and type Objects into the Quick Find bar. Click Objects, then find the name of the custom object that you would like to use in a mass merge. Click the name of the object (do not click the edit button). In this example, we will be using the Check object.

Now, scroll down to the Search Layouts table. Click Edit next to the layout titled “[Object Name] List View,” where [Object Name] is the name of your object (excluding brackets).

This concludes part (a).

b) Adding buttons to search layouts for a standard object

Navigate to the Setup menu and type the name of your standard object into the Quick Find bar. Find and click on Search Layouts in the dropdown menu. Then, click Edit next to the layout titled “[Object Name] List View,” where [Object Name] is the name of your object (excluding brackets).

2. Now that you’re on the Edit List View page for your Object, select Add to Mass Merge List under “Available Buttons” and click the rightward-pointing arrow below Add to add your button to “Selected Buttons.” Repeat this step for “View Mass Merge List” if you created a button for it. Click Save.

The finished page should appear as:

This concludes part (b).

Winter '20 Release Note: If you are using S-Docs below version 4.53, you may experience an "Attempt to de-reference a null object" error when interacting with various forms of automation in S-Docs. In order to fix this bug, you can create a new SDocs Settings custom settings set. To do this, type "Custom Settings" into the Quick Find / Search bar in the Setup menu, and click Custom Settings. Click SDocsSettings, then click Manage at the top of the page. From there, click New. Fill out the following information: Name: SDocsSettings ConnectedAppLoginURL: Production: login.salesforce.com Sandbox: test.salesforce.com
SD Jobs Batch Size: 30 SD Jobs Move to Top of Flex Queue:

Additionally, ensure that you have a Remote Site Setting for either login.salesforce.com (production), or test.salesforce.com (sandbox).

STEP 4 (Optional): Create a List View for Your Object

If you wish to use list views that have already been created for your object, such as the ‘All’ list view, you may skip this step. However, for the list view you select, you will have to manually filter out all the records you would not like to appear in your mass merge. This might be tedious, and if you have some kind of criteria that would greatly optimize this process (e.g. you wish to print all Checks written for amounts less than $10,000), you can follow the instructions in this step to create a list view and use filter logic to achieve such goals.

1. In Salesforce Lightning, navigate to your object's tab. In this example, we will be navigating to the tab for our Check object. Under List View Controls (represented by a cog), click New.

Enter a descriptive view name. The list API name will auto-populate.

The filters menu will pop up. Change the Filter By Owner field to All Checks.

Next, click New Filter. Set the Field to Amount, the Operator to less than, and the Value to 10000. Then click Save. This means that our list will only include Checks written for amounts of less than $10,000.

Next, click the List View Controls again, then click Select Fields To Display.

Choose your fields. In this case, we'll add Payable To and Amount.

To do the same in Salesforce classic, navigate to the tab for your object. Our Check object happens to be displayed as a default tab, but if it weren’t displayed, we could click the All Tabs button ("+" symbol) and find it from there:

Click Create New View on our Object’s page:

On this screen, you can enter your View Name, Filters, and Fields to Display.

You will be redirected to the resulting List View. In our Check Example, our list does not contain checks 2 or 3 as their “Amount” fields are greater than or equal to $10,000. Click the checkbox on the right if you would like to select all the records to be added to the mass merge. You can also select or deselect them individually.

Note that we have our “Payable To” and “Amount” fields displayed in case we want to manually exclude a certain Payee’s check or a check of a certain dollar amount from our mass merge list. If we didn’t want to include one of these checks in our mass merge, we uncheck it. In this example, suppose that after filtering out checks with values greater than or equal to $10,000, we decided not to include the check paid to the order of Salesforce User. Since we included the “Payable To” field as a column, we don’t have to open all three records to see which one will be paid to Salesforce User; we can simply eyeball the list and uncheck the record corresponding to him. Then, this check will not appear in the resulting mass merge.

Note:We discussed a similar method in Step 2. Users can manually exclude records from their mass merge based on the fields displayed in the search layout list view as described above, or based on the fields displayed in the mass merge list described in Step 2. The latter technique is achieved by following the instructions for editing the Visualforce code in Step 2; the technique in Step 5 might be simpler to achieve.

STEP 5: Use the Mass Merge & Batch Document Feature

Before we use the mass merge and batch document feature, you should make sure that the list of S-Docs Jobs logs is clear. This isn't required, but helps keep the system clean. S-Docs Job records are created when you add records to a mass merge list; by default, they are not deleted after every mass merge. You can choose to enable this functionality in the template editor for the template that you're using with mass merge under the document options tab. Otherwise, let’s see how we can clean up the S-Docs Jobs log list manually. Navigate to the S-Docs app and click over to the S-Docs Jobs tab.

Select any jobs and click Delete Logs.

Now we can perform our mass merge. Navigate to your object and select a list view. In our Check example, we selected the list view “Checks Less Than $10,000” that we created in Step 5. Select the records that you would like to use for the mass merge and batch document feature. Then, click Add to Mass Merge List

This will bring you to the Mass Merge page. You'll begin on the Choose Templates tab.

First, [1] select the template you would like to use. You can select one document template and one HTML email template. Then, [2] click Go To Next Step. You can also [3] click on the Generate Docs tab to go to the next step; both buttons will take you to the same place. The tabs make it convenient to jump between different steps. If you want to amend the records being used for this mass merge, [4] click on the Add Records tab. For now, we'll click Go To Next Step. This will bring up the following screen.

As you can see, [1] the records we selected are listed in the mass merge list. To begin the process, [2] click Start Mass Merge. When you click this button, you'll be able to [3] view the status of each document as it generates.

If you want to log an activity on each record, [4] check this box.

Once this mass merge is complete, [5] the COMBINE ALL into single printable document button will become available. This button is pretty self-explanatory: when you click it, all of the documents that were generated will be combined into a single consolidated document. You can configure settings for this under the document options tab in the template editor for the template that you're using with mass merge. Finally, [6] click START OVER (clears selections) if you want to return to the beginning of this process.

Here's what your finished mass merge will look like.

Both records have a Status Link of 100%, meaning both checks successfully generated. You can now click the PDF icon next to each one to view the documents. Additionally, the COMBINE ALL into single printable document button is no longer grayed-out. Let's click this button.

In our check example, we will open the PDF that downloaded after clicking COMBINE ALL into single printable doc. As expected, the PDF contains both of our checks, each on its own page.

Generating and Emailing a Large Number of Documents

If you would like to generate and email a large number of documents, you can do so by selecting two templates in our mass merge: one template for the document you’d like to email, and another template for the email itself. Thus, to generate and email a large number of documents, all you have to do is select an S-Doc HTML email template and an S-Doc template for a PDF, Word document, etc. on our mass merge page, click Go to Next Step and then click Start Mass Merge. That’s it! S-Docs will then use the information in the HTML email template to send a personalized email to each record in our mass merge list; each of these emails will include the document that was generated for that particular record.

Generating and Printing Mailing Labels for your Mass Merge

If you plan on performing a mass merge, printing the resulting PDF, and mailing out the pages, you can use S-Docs to print off mailing labels for your letters. To do so, you first have to create a new S-Docs template for your mailing label (click here for a free mailing label template). Please make sure your template has the "Document Category" field set to "Mailing Label" (if your version of S-Docs is missing "Mailing Label" from the "Document Category" picklist on the S-Docs Template object, you'll need to add it to the picklist values manually), and that your mailing label template has User as its "Related To Type" and DOC or PDF as its output type; this is because S-Docs populates the mailing label list on the mass merge page with all S-Docs templates that meet these criteria.

You can copy and paste the following mailing label template into your label template’s source editor:
This template will print mailing labels for a list of contacts.

On the mass merge page, click over to the [1] Mailing Labels tab, [2] select your mailing label template, then [3] click Print Labels/Envelopes.

This will generate and download a printable mailing label.

mass merge - mailing (2)

Mass Merge Archive

In the Mass Merge Archive tab, you can find previously generated mass merge documents. You can click the PDF icon to view, print, or download these documents.

Appendix

Finding the API names for Your Standard Object’s Fields

In Salesforce Lightning, navigate to the Setup Menu, then find your object in the Object Manager. Navigate to the Fields and Relationships tab. All of the field API names will be available under the Field Name column.

In Salesforce Classic, navigate to Setup > Build > Customize > YourObjectNameHere > Fields.

For standard field names, the API names are found under the Field Name column.

For Custom Fields, the API names are found under the “API name” column in the section below.

Finding the API names for Your Custom Object’s Fields

In Salesforce Lightning, navigate to the Setup Menu, then find your object in the Object Manager. Navigate to the Fields and Relationships tab. All of the field API names will be available under the Field Name column.

In Salesforce Classic, navigate to Setup > Build > Create > Objects and click the name of your object (do not click the Edit button).

On the page for your custom object, scroll down to the “Standard Fields” and “Custom Fields & Relationships.” The API names for [1] Standard Fields will be located under the Field Name column, and [2] the API names for Custom Fields will be located under the API name column.

Set Apex Class Access from Profiles

If users are unable to access the mass merge page, you may need to add their profile to the mass merge apex class. Click here for instructions on how to do so.