Create your first Document
To create an IdealDoc document merge Data and a word template is needed. The IdealDoc Query record defines the set of queries to get the merge data while the IdealDoc Template record defines the template meta data and contains the actual docs Word template as File attachment.
Create the IdealDoc Query
Navigate to the IdealDoc Query tab to create a new IdealDoc Query record:
Choose a meaningful name for the query. For example “Account Overview Query”.
The external id needs to be unique and can be used for external systems to reference the query.
The actual SOQL queries can be entered either manually or by using the powerful query builder. In most cases the query builder should be chosen. Only for complex queries with sub queries the manual entry flag should be selected.
Query Builder:
If the query builder is used (i.e. checkbox “Manual Entry” NOT checked), the sub-tab “Query Builder” shows two sections:
Param Query: An optional query used to define additional parameters that can be used in the data queries. The only query parameter available to the param query is the id of the current record (:recordId). Using this paramter in the where condition some additional query parameters can be queried.
For example when querying the LastModifiedDate as “accountLastModDate” the additional query parameter :accountLastModDate can be used in the data queries below.
For example: “AccountId = :recordId AND ActivityDate < :accountLastModDate”
Data Queries: A set of SOQL and the corresponding merge field mapping.
By clicking “Add Query” a new SOQL query can be created. When selecting the query the query details appear:
For newly created queries a default query name gets generated which should be changed to a meaningful name.
Single Record:
By selecting the checkbox “Single Record” we can indicate that this query will always return exactly one entry. The impact of selecting the “Single Record” checkbox is that all the defined merge fields will be available directly in the Word template without iterating through list entries.
Sort Descending:
In case a query field was defined with a sort order, whether to sort ascending or descending
SObject:
The SObject this query should be based on. The SObject can be selected through the autocomplete dropdown. To close the dialog, press enter. Query fields can only be selected once an SObject has been selected. Once one or more query fields have been defined, the SObject cannot be changed anymore.
Where Condition:
The where condition of the corresponding SOQL query. The id of the record from where the document creation process was started is available as query parameter :recordId.
For example:
“Id = :recordId" queries the current record.
“AccountId = :recordId" queries all the child records of the current Account with recordId = :recordId
Additional default query parameters:
:currentUserId: Id of the currently logged in User
:now: Current Date and Time
:today: Todays date
Group Condition:
Parent Query:
Parent Key:
Child Key:
Merge Fields:
The Query Builder includes our innovative mapping editor which allows to navigate and select SObject fields quick and easy. By typing in the “Filter Fields” form field, the available SObject fields are filtered dynamically. By clicking on a field from the list, the Mapped Name and API Name are automatically populated. The “Mapped Name” defines the merge field name which will be used in the Word Template. The proposed default value of this mapped name can be changed freely.
Wildcard (*) can be used when filtering. For example by typing “*(>” all the lookup fields of the current SObject are displayed. When clicking on a green arrow of a lookup fields you can navigate to the related SObject.
Functions:
By defining a “Function” it is possible to create an aggregate query. For example you can sum a number or find some max values. However, you need to define all fields as function fields or none:
If one field is a grouped field, which means the GroupBy function is selected for this field, the Group Condition (Having) becomes editable.
Copy Merge Fields
A very powerful feature of the query builder which makes creating Word templates very easy and efficient is to be able to copy & paster merge fields directly from the query builder into your Word document.
It is possible to copy individual merge fields or all merge fields at one (Copy All) into the clipboards to support the creation of the docx template.
When all fields of a non single records query are copied, the fields are automatically copied in a table format.
CAUTION:
The copy to clipboard function only works if the “new” Lightning Web Security is enabled in Salesforce under Setup → Security → Session Settings:
Manual Query Entry
If for some reasons, you need to create queries including subqueries, the query needs to be entered manually.
When entering queries manually the query builder cannot (and should not) be used anymore for this query.
The queries need to be entered as a JSON data array: [{ Query 1} , { Query 2 }, … ]
Here is an example of a manually entered query (and data mapping) including a subquery:
Data Queries:
[
{
"name": "AccountQuery",
"singleRecord": true,
"query": "SELECT Name, (SELECT FirstName, LastName, Email FROM Contacts) FROM Account WHERE Id = :recordId",
"mapping": {
"AccountName": "Name",
"ContactRecords": "Contacts.records"
}
}
]
Please be aware that you can only map the fields from the main query. The subquery fields need to be used as they are returned from SOQL.
Create the IdealDoc Template
The IdealDoc template defines the actual document template which should be used to merge the final IdealDoc document.
Each IdealDoc record represents one document template and consists of some configuration and the actual Word (docx) template file. To create a new IdealDoc template record navigate to the IdealDoc Templates tab in Salesforce and click on the “New” button:
When creating a new template record the following information should be filled:
IdealDoc Template Name: Meaningful record name, e.g. “Account Overview Template”
External Id: A unique template identifier string which will be used to reference this template in Salesforce flows or other automations
Category: A template category information which can be used to group related templates when selecting them in a dialog. E.g. “invoices”, “quotes” etc.
IdealDoc Query: A lookup to the IdealDoc Query record which defines the required queries to gather all the data needed in this template
Active: A checkbox which allows to activate or deactivate the template. Inactive templates will not be available for selection in a dialog.
After creating a new IdealDoc template record the detail record screen looks like this:
Under the “Details” sub-tab the previously entered meta data can be edited. In the “Files” section the actual Word (docx) template file should be uploaded. For a reference on how to create a valid Word (docx) template please see Word Template Reference v2 or Word Template Reference v1 .
IMPORTANT: Only template records that contain at least one file will be available in the document generation. Always the last recently uploaded or modified File will be used when creating a document!
Template Configuration:
On the “Configuration” sub-tab, template specific configuration settings can be defined:
The configuration settings defined on the template override the default settings defined on the specific settings records (see: Initial Setup ).
The following settings can be defined:
Engine Version: Version of the document templating engine to be used. Whenever possible, version 2 should be used. Version 1 is deprecated and doesn’t support all advanced features.
File Name: The file name of the generated document. When defining the file name, merge fields from the queries can be used (e.g. {{Name}}) and also some global variables like @global.date = current date and @global.index = index of documents in case of multiple documents are generated in one job.
Input Format: Default input format. Usually docx. Might be set to pdf in case a static pdf should be merged as part of a multi doc merge.
Output Format: Default output format. Either PDF or DOCX. Will usually be overriden in the merge dialog. However, for automated generation of pdf documents, the default output format can be defined on the template.
Date Locale:
Date Format Pattern:
Date Time Format Pattern:
Number Locale:
Number Format Pattern:
Thousands Delimiter:
Decimal Delimiter:
Static Data: