Dynamically Filter Reports and Queries with pv Values

Note: While Salesforce Reports are useful to gather data for Composer solutions, it is highly recommended to use Conga Queries due to better data gathering performance, versatility, and stability.

What is a pv Value?

PV (or pv) stands for parameter value, which is a value that can be passed into a filter on a Salesforce report or Conga query. The first filter on a report or query is called pv0, the second pv1, the third pv2, and so on.

Note: A Composer solution can contain up to 6 pv values.

What Does It Have to Do with Composer?

Conga Composer automatically passes the Id of the record from which you are launching Composer (known as the master object record Id) into the pv0 filter on your report or query (assuming you are using one). In this way, Composer is able to return data specific to the record you are working with.

For example, if you are gathering Contacts with a query, rather than returning ALL Contacts in your Salesforce org, Composer passes the Id of the master record into the pv0 filter on the query so that only Contacts related to the record you are working with are returned and merged into the document.

How Does it Work?

Composer's default behavior is to pass the master object record Id into the pv0 filter. What you need to do is ensure your report or query has a blank filter to accept that value.

Using the example above, if you are retrieving Contacts with a report or query and your master object (the object on which you have built your Composer button) is an Account, you will need to add a filter for Account Id and leave it blank, like this:

If the master object is an Opportunity, you would add a filter for an Opportunity Id. If doing the same with a query, you will create this filter on Step 3 of the Conga Query Builder, and it will look like this:

The resulting SOQL statement looks like this (the WHERE clause filtering on pv0 is the equivalent of the filter in the report): SELECT Name, Phone, Title FROM Contact WHERE AccountId = '{pv0}'

What Else Can I Do with pv Values?

In addition to the default behavior described above, you can use pv values to create advanced filter configurations to gather and merge data specific to your use case. These configurations include:

Pass no value to pv0 (which is helpful when using Composer as a reporting tool to gather org-wide data)
Pass a value other than the master object id into the pv0 filter
Pass values to multiple filters (pv0, pv1, etc.)
Pass multiple values to the same filter
Pass a Null Value

The primary use case for passing a null value is when performing a Global Merge. In this case, you likely don't want to filter your reports on a specific record because you are conducting a record-independent merge.

To do so, append the report or query Id in your button URL with ?pv0=

Note: If using the Conga Solution Manager, there is a field under Advanced Configuration on the Add Report or Add Query screen where you can add a "+" to the pv0 field, which will append the button URL for you and pass a null value.

Pass a Value Other Than the Master Object Id

To filter pv0 on a value other than the master object Id, simply add the new field on which you want to filter to the URL. For example, if your master object is an Opportunity, but you want to filter your data source on the Account Id instead of Opportunity Id to get a list of Contacts from the Account, your URL would look like this: ?pv0={!Account.Id}or?pv0={!Account.Id}

Note: If using the Conga Solution Manager, there is a field under Advanced Configuration on the Add Report or Add Query screen where you can add the {!Account.Id} merge field as the pv0 value and it will update the URL for you.

Warning: Do not pass through a field with special characters such as commas or ampersands, as that will cause issues with the URL.

Pass Values to Multiple Filters

You may want to filter your data source on two or more criteria, such as filtering a list of Contacts on those in the same State/Province as the Account and who are also doctors. To do so, you can pass multiple pv values by creating a report or query filter for each value you want to pass (pv0, pv1, and so on.) and appending the URL as follows (Note you must separate each pv value with a ~):

?pv0={!Account.BillingState}~pv1=Dr.or?pv0={!Account.BillingState}~pv1=Dr.

Note: If using the Conga Solution Manager, there is a field under Advanced Configuration on the Add Report or Add Query screen where you can add the pv1 value and it updates the URL.

For this scenario, your report would look like this (notice the second filter for the pv1 value of Dr.):

Your SOQL statement would look like this: SELECT Name, Phone, Title FROM Contact WHERE Account.BillingState = '{pv0}' AND Salutation = '{pv1}'

Pass Multiple Values to the Same Filter

You can also pass multiple values into the same filter. Using the example above, if you want to return a list of Contacts who are in the same State or Province as the Account and who are either doctors or professors, you need to update the button URL by adding the additional value for the pv1 filter and separating it from the previous value with a " | " symbol, like this (note you don't need to change anything in the report or query because it already has a filter for pv1):

?pv0={!Account.BillingState}~pv1=Dr.|Prof.

Note: If using the Conga Solution Manager, there is a field under Advanced Configuration on the Add Report or Add Query screen where you can add the additional value and it updates the URL.

Pass Multiple Values into a Query

You can pass multiple values into a query filter as well, however, this requires a slight change to the query syntax. Using the example Contacts query above we would have to modify the SOQL statement to look like this: SELECT Name, Phone, Title FROM Contact IN{pv1})

and the button url to: ~pv1='Dr.'|'Prof.'

Conga Product Documentation

Welcome to the new doc site. Some of your old bookmarks will no longer work. Please use the search bar to find your desired topic.