Admins / Architects

Well-Architected Document Generation for a Well-Architected Salesforce

By Igor Stuyver

Branded content with PDF Butler

Salesforce implementations thrive when well-architected, focusing on streamlined business processes. Studies have shown (and everyone would agree!) that well-architected systems decrease costs, lower maintenance, and allow for continuous innovation.

In the realm of CRM and Lead-to-Cash processes, the necessity for document generation is evident. Quotes, contracts, purchase orders, and invoices are integral to these processes. Yet, many Salesforce architects treat document generation, digital signature, or document collaboration as mere add-ons rather than vital components. 

While meticulous designs and architectures are crafted, these crucial pieces often receive insufficient attention. This includes considerations such as corporate identity, integration into processes, necessary information retrieval from Salesforce, document structure, additional data requirements based on products, and the list goes on. 

This article serves as a call to action for Salesforce Architects to see the full picture, and adopt a holistic approach in order to successfully provide an end-to-end solution for your teams.

Why is Document Generation Crucial? 

Document generation is a cornerstone in sales organizations, driving revenue, streamlining processes, and ensuring effective communication. In the fast-paced, digitally-driven business landscape of today, Salesforce Architects must prioritize efficiency, accuracy, and competitiveness in their implementations. 

Document generation is a vital component that not only streamlines processes but also enhances communication, contributing significantly to the overall success of modern businesses – an imperative goal for architects and business analysts.

Considerations for Architecting Document Generation in Modern Business

The overarching goal is to reduce costs, lower maintenance, and ensure scalability across users and use cases. Achieving this requires adherence to architectural best practices, akin to Salesforce’s principles for Lightning and its Lightning components.

Following the Model-View-Controller (MVC) design principle, separation of data and logic from the template is crucial. This ensures loose coupling, independent updates, reusability, and most importantly, no logic within the template (e.g., DOCX file), allowing easy updates by business users. 

PDF Butler stands as an exemplar of being well-architected, based on these best practices.

Naming Conventions

Being an architect myself, this is extremely important to me. Having a good naming convention and systematically implementing it makes sure that the configuration is easy to follow and that new admins can be more productive.

For Merge Fields:

You should put the name of the object with the name of the field. Internally, we commonly use two ways of setting merge fields:

  1. Upper-casing: e.g. OBJECT_FIELD
  2. Camel-casing: e.g. ObjectField

For example, if the object is a contact, and the field is first name, the two ways would be:

  • Upper-casing: [[!CONTACT_FIRSTNAME!]]
  • Camel-casing: [[!ContactFirstName!]]

Or, if the object is My_Object__c, and the field is Field__c, it could look like:

  • Upper-casing: [[!MY_OBJECT_FIELD!]]
  • Camel-casing: [[!MyObjectField!]]

For Data Source:

Make it descriptive yet short – try not to make it too complicated.

For example, the data source that retrieves the opportunity: opportunity. There is only one opportunity selected, so do not call it opportunities.

Whereas, the data source that retrieves the quote lines: quote lines. There will be multiple records selected, so the name should show in plural.

And, the data source that retrieves the quote lines filtering out category “hardware”: Quote Lines – Category Hardware.

For Config Types:

A merge field can have multiple objectives. For instance, in the below example, we want to re-use the merge field to identify the row to replicate and to fill in the product name. This will increase readability.

Product NameQuantityTotal Price

In the example above, there would be two config types using the merge field “LINE_PROD_NAME”:

  1. TABLE_ROW: To replicate the row for each record in the data source. The name of the config type would be: TABLE_ROW – LINE_PROD_NAME.
  2. SINGLE: The TABLE_ROW would have a child config type of type SINGLE to fill in the product name: SINGLE – LINE_PROD_NAME

So the naming convention we propose: <CONFIG TYPE> – <MERGEFIELD>.

Environment Planning & Deployment

In your project you will have multiple sandboxes and a production environment. For instance, your deployment process can be:

Note: This is just an example and each company or project can decide what fits best.

With PDF Butler, you can link a configuration to a certain stage to be used by the specific sandbox. Therefore, you have a clear view on how to deploy and add PDF Butler in your deployment pipeline. 

There are a wide range of deployment options ranging from fully manual to fully automated. With a Salesforce Command Line Interface, it’s easy to retrieve configurations and store them locally or in your code repositories like Git. Plus, you can even set up a Continuous Integration and Continuous Delivery (CI/CD) process.

Lightning UI Integration

It is important to make sure you are providing the best user experience possible. This means that you must think about how to generate, present, and provide actions on the generated document. 

These could be generated from a Lightning component or from a quick action, and when generated, they may show a preview for the document and actions such as emailing.

It must also be possible to build your own Lightning components and to integrate the generation process in a Lightning Flow.


You need to ask what kind of automation is required for your use case? This automation must be managed directly from Salesforce, some options include:

  • Flow
  • Batch processing
  • Apex

A good document generation system that is purposely built for Salesforce will support all native Salesforce automation tools.

Batch Processing 

There are many cases where batch processing is important, such as invoices, thank you letters, etc. You need to make sure your document generation tool can process in batch via Salesforce. 

If this is managed via Salesforce, it’s also easier to schedule and follow up on the processing. This is because all of the information is easily accessible via Salesforce Setup.


Creating a document is not enough. You might want to add actions before or after the document is generated. Some examples include:

  • After the document is generated:
    • Email the document to one or more recipients.
    • Send out for digital signature.
    • Define your own action and run a Lightning Flow or Apex with custom actions.
  • Before the document is generated:
    • Add validations to ensure all data is correct.
    • Change data, e.g. complex calculations.
    • Get data from external systems (such as billing or ERP) to combine with your Salesforce data in the generated document.

Reusable Components

You must be able to define components that are reusable. Creating reusable components is an architectural best practice to reduce maintenance costs and duplication.

What is usual to make reusable:

  • Data Sources: Selects the data from Salesforce.
  • Templates: Snippets of documents that can be plugged in and combined with other document configurations.

Multi-Language, Currency, Branding…

Every country in the world has different ways of formatting things such as dates, numbers, currencies, etc. Plus, customers like to be served in their own language.

Document generation tools must know how to format and support different languages and currencies without duplication of the document configurations as this will lead to higher maintenance and testing efforts. 

A well-known example is formatting dates in US versus EU, For example let’s use the March 5th, 2023:

  • US: 3/5/2023
  • EU: 5/3/2023

As you can see, mixing these up can have serious consequences and your documents will look very unprofessional.

The settings of the language/currency/branding must be done in the context of the customer, not the current Salesforce user! 

For example, an English-speaking sales rep in the Netherlands might need to generate a Dutch document for a client in the Netherlands. His user settings will be in English while the account/contact information is set to Dutch.

Salesforce Limits and How to Overcome

Think about the requirements you have to serve versus common Salesforce limits. These include:

  • Number of SOQL queries: Do you need more than 100 data sources to run your document configuration?
  • Big documents: How big will your document be? This is an important one to think about. If you import a lot of high-quality images, your document might be huge. This eats into your Salesforce storage, and it will blow up your customer’s inbox.
  • Number of records selected: Do you need to process a few, a few hundred, or a few thousands of records to add into your document?
  • Number of documents to be generated: In your process, is it one document or do you need to generate multiple documents in one go?

When you have considered all of the above, what about the future? When businesses and requirements scale up, your document generation tool must scale with you easily.

User & Admin Experience

How will you present the Document Generation process to your users? Admins need full freedom to listen to their end-users and their preferred processes to provide solutions that are well accepted and will add to the adoption of the Salesforce setup in general.

Business Enablement

Templates must be managed by business teams. Fixes of typos, text updates, branding changes, etc. is not the work of a Salesforce Admin or Developer.

Business teams must be able manage the templates in everyday tools like MS Word or Google Docs. These tools are well known by the business teams and give them the freedom to build and design the documents they envision.

There should not be any logic in the document – this is an architectural best practice to split the logic from the template, like in LWC. If there is logic inside the document, it is not possible for business teams to manage. They may break the logic and it will be hard to find the texts inside the document, leading to issues that the admin must fix.

In your organization you may have a Digital Asset Management (DAM) setup, then you will need to use images, product descriptions, etc. from this central repository.

Communities: Digital Experience Cloud

Make sure your document generation tool can integrate with Digital Experience Cloud But also consider what the impact on usability and cost is to enable a community?

This might not be an initial requirement, but as an architect you must design a future proof solution that can scale from only internal users to external users too.


Finally, make sure your document generation tool has constant innovation. Business requirements are constantly evolving, and Salesforce is also always innovating and providing new features.

You must be able to grow with business & industry requirements, so choose a tool that is future proof, with a team that listens to your requirements and is capable of explaining to others in your space.


In crafting a Lead-To-Cash Architecture, the significance of document generation cannot be overstated, and it should be a primary consideration from the project’s inception. 

Acknowledging that not all goals and requirements may be apparent at the project’s outset, it’s imperative to choose a tool that is open and future-proof – capable of evolving with your business and its expanding needs.

For a reliable and forward-thinking solution, explore the capabilities of PDF Butler. Visit our website or our Salesforce AppExchange listing to find out more.

The Author

Igor Stuyver

Igor is a Salesforce Architect and Owner of CloudCrossing at PDF Butler.

Leave a Reply