Advanced Data: Using SOQL to Add Variables

While standard merge fields and related lists cover basic document generation needs, you can also incorporate advanced data into your S-Docs templates by leveraging Salesforce Object Query Language (SOQL). Building SOQL queries allows you to retrieve and display critical business data that lives outside the structure of your base record — such as pulling information from outside a standard opportunity tree hierarchy.

Accessing the advanced data panel

The advanced data configuration tools are located within the template editor interface. To access them:

1. Click the plus icon to open the Variables panel. This panel serves as the primary entry point for all variable data.
2. Click the Advanced Data icon inside the Variables panel.

The Advanced Data configuration panel will launch on the right side of the interface.

Understanding object queries versus list queries

The Advanced Data panel provides two options for constructing queries. While both tabs share identical configuration options, they handle your data differently:

• Objects: This option returns one instance of records defined in the SOQL query - only the first record that matches criteria set in the SOQL query. It is ideal when you want to make multiple fields from a single record available as individual merge fields within the Variables panel.
• Lists: This option returns multiple instances of records defined in the SOQL query. It is ideal when you need to query for multiple records - such as when you have a related list that requires data from multiple records.

Creating a SOQL data source

Follow these steps to build, validate, and inject a SOQL query into your document template:

1. Open the Variables panel by clicking the plus icon on the left side of the interface.
2. Click the Advanced Data icon to launch the configuration options in the right menu.
3. Select either the Objects tab or the Lists tab based on your data display needs.
4. Click on the Click to add + button to open the new query.
5. Enter a highly descriptive name in the Label field so template authors can easily identify its purpose.
6. Input your SOQL query into the query editor text box.
7. Select a valid record in the Preview Record field.

Note: The Add Data Source button remains inactive until you select a preview record. It is required to preview record data to validate the query syntax and confirm that the query is returning accurate data.

1. Review the Results and Fields tabs to verify your query configuration.

This tab displays the data type, label, and API name to confirm your SOQL query is well-formed, even if your chosen preview record is currently missing data for those specific fields.

Note: Malformed SOQL will return an invalid error that contains a description of the errant syntax.

1. Click Add Data Source.

Need to make an update to a SOQL query? Simply navigate to the Advanced Data panel and click on the listed query when the icon is visible.

Result

Once you save a valid query definition, those fields automatically become available in the Variables panel for immediate use across your document template. The queried data will appear grouped under a new subcategory named after the configured SOQL data element.