Report DataSource

PDF Butler allows you to use the results of a Salesforce Report directly as a data source for document generation. Instead of querying Salesforce objects with SOQL, you can leverage an existing report, including all of its filters, to populate your documents.

This approach is ideal when you already have a report that contains exactly the records and fields you want to include in your generated document.

Be aware that Salesforce has to run the Report for us to be able to use the results. Running Reports in Salesforce is slow. So, if you can use a SOQL DataSource instead of a Report that would be better for performance. Please note also that only tabular report formats are supported.

Report DataSource #

#

How It Works #

When a Report Data Source is configured:

• PDF Butler executes the selected Salesforce report.
• All report filters are respected.
• The report results are returned as a List of Objects.
• The data can then be used in your document just like any other list data source.

Any changes made to the report (such as adding or modifying filters) are automatically reflected the next time a document is generated.

Prerequisites #

Before configuring the data source:

• Create the Salesforce report that contains the data you want to use.
• Ensure the report includes all required columns.
• Obtain the Report API Name.

Note

In Salesforce Lightning, the Report API Name is not easily accessible. You can retrieve it by opening the report in Salesforce Classic, navigating to Report Properties, and copying the Unique Name of the report.

Create a Report Data Source #

1. Navigate to Data Sources.
2. Click New.
3. Select the Report record type.
4. Enter a name for the data source.
5. Set the Type to List of Objects.
6. Enter the Report API Name (Unique Name from Salesforce Classic).
7. Save the data source.

The Report Data Source is now available for use in your document configuration.

Add the Data Source to the DocConfig #

1. Open your DocConfig.
2. Upload or select your document template.
3. Add the newly created Report Data Source.
4. PDF Butler automatically loads all fields available in the report.

If you later add or remove columns from the Salesforce report, click Reload from Salesforce to synchronize the available fields.

Note

All report fields are imported as Text fields because Salesforce reports return formatted display values rather than native field types.

Configure the Document #

Configure the document as you would with any standard list data source.

Typical configuration includes:

• Creating a Table Row Config Type.
• Selecting the Report Data Source.
• Mapping the desired report fields.
• Creating Merge Fields for each column you want to display.

For example, you might include:

• Opportunity Name
• Account Name
• Opportunity Owner
• Stage
• Amount

Each row in the generated document corresponds to one record returned by the report.

Generating the Document #

Once the configuration is complete:

1. Open the Salesforce record or page where the document generation action is available.
2. Generate the document.
3. All report rows are inserted into the document.

No additional configuration is required.

Dynamic Report Filtering #

One of the main advantages of using Report Data Sources is that report changes are automatically reflected in generated documents.

For example: Closed Won Opportunities

If you modify the report to include only:

• Opportunity Status = Closed Won

the generated document will contain only Closed Won opportunities.

Example 2 : Opportunities Above a Certain Amount

If you add a report filter such as:

• Amount > 100,000

only opportunities meeting that criterion will appear in the generated document.

Because PDF Butler executes the report at runtime, it always uses the report’s current definition.

Reloading Report Fields #

If the report structure changes:

• new columns are added,
• existing columns are removed,
• field labels are updated,

return to the Report Data Source and click Reload from Salesforce.

This refreshes the list of available fields without requiring the data source to be recreated.

REPORT DataSource – Label vs Value #

 

When using a Report Data Source in PDF Butler, Salesforce returns both the formatted display values shown in the report and the underlying raw values for many fields.

By default, report fields use the formatted values displayed in Salesforce. However, if you need to perform calculations, apply PDF Butler formatting, or use formulas, you should use the corresponding Value fields instead.

Formatted Values vs. Raw Values #

Each report field may expose two versions of its data:

Field Type	Description	Example
Display Field	The formatted value shown in the Salesforce report.	EUR 220,000.00
Value Field	The underlying raw value without Salesforce formatting.	220000

The display field is intended for presentation, while the value field is intended for calculations and further processing.

Reloading the Report Data Source #

After creating a Report Data Source:

1. Open the Document Configuration.
2. Select your Report Data Source.
3. Click Reload from Salesforce.

When the data source is reloaded, PDF Butler imports both:

• the display fields, and
• their corresponding Value fields.

These additional fields allow you to work with the raw data returned by Salesforce.