Use QVARs in your Conga Composer solutions.

QVars

QVars (Querystring Variable) allow users to reference the results of Conga Queries as the value of other parameters in the same Composer solution. The benefit of QVars is referencing gathered data for use in a Composer solution's button URL or formula field.

QVar Parameters

There are two QVar parameters used in Composer solutions:

  • QVar0ID
    • The QVar0ID parameter designates a specific Conga Query record for Composer to execute.
      • The parameter value is a Conga Query's 15 digit record ID.
    • This parameter is required to use QVars in a Composer solution.
    • The maximum amount of QVar0ID parameters in a Composer solution is six.
      • Each QVar is represented as an individual parameter, such as QVar0ID, QVar1ID, and QVar2ID.
      • Users can relate only one Conga Query record ID for each QVarID parameter.

The Conga Query must return only one column of data and must not retrieve more than 50 rows of data.

  • QVar0Format
    • The QVar0Format parameter formats the results of the QVar0ID parameter's executed SOQL Query.
      • The parameter value is a 5 digit code.
    • This parameter is not required for all QVar use cases, but it is highly suggested to use for QVar solutions that return multiple data values.
    • Users can use the QVar0Format parameter up to six times in a Composer solution.
      • Each QVar0Format parameter corresponds to a QVar0ID parameter, such as QVar0Format, QVar1Format, and QVar2Format.
    • QVar0Format is useful for separating multiple retrieved values by delimiters, enclosing retrieved values by apostrophes and quotes, and truncating retrieved record IDs to 15 digits.
      • For more information on formatting retrieved data with the QVar0Format parameter, see QVar0Format.

Using {Qvar} as a Parameter Value

{QVar0} is the syntax used to reference the result of a QVar0ID parameter's related SOQL Query. Each {QVar}correlates to a specific QVarID parameter.

For Example, users would use {QVar0} as a parameter value to reference QVar0ID's retrieved query results. If a user references the results of Qvar0ID as the EmailToID parameter's value, the syntax is &EmailToId={QVar0}.

Use QVarID parameters in sequential order. For Example, add the QVar0ID before QVar1ID in a Composer button url or formula field. Using the QVarID parameters out of sequential order may result in unstable QVar performance.

QVar Use Cases

The examples below depict common use cases for using QVars in Conga Composer solutions.

Using a Contact ID as an Email Recipient

  • The EmailToID parameter is a useful way to specify an email recipient for a Conga Email Template. The EmailToId parameter requires a Contact, User or Lead record ID as the parameter value. Salesforce's custom buttons allow users to reference Contacts through lookup fields, or with the Primary Contact Role, but there are many scenarios where users must traverse through related records to find the right email recipient.

  • Instead of finding the correct related Contact record in Composer's email user interface, use a QVar to select an email recipient automatically.

  • For example, a user needs to send a proposal from an Opportunity using Conga Composer and the email recipient is always going to be the related Account's Primary Contact. There is not a way to reference that contact's record ID directly from the Composer button on the Opportunity. To resolve this issue, use a QVar to reach up to the Account, locate its Primary Contact, and retrieve the Primary Contact's record ID.

  • Example Object Schema:

  • Example SOQL Query for QVar:

  • The Account ID is the pv0 variable in the above SOQL Query and the query is filtered to return only Primary Contact Roles.
  • The next step is to take the Conga Query's 15 digit record ID and use it as the value of a QVar. The necessary QVar parameter in the Composer button is QVar0ID. This parameter makes the result of the query accessible as a variable in the Composer solution. Once defined, the variable is available for use by referencing it as {QVar0}.
  • Example parameter configuration:

    1. The Conga Query ID is referenced with &QVar0Id.
    2. The Opportunity's related Account ID is passed to the first filter in the query.
    3. The {QVar0} result is used as the value for the &EmailToID parameter.


  • When a user launches the Composer button and the query executes, the actual 15 digit Salesforce ID of the desired Contact record replaces {QVar0} and the email recipient is automatically selected.


Using a Salesforce Attachment as a Conga Template

  • Conga Composer Templates are typically stored and referenced by uploading the file to the Conga Template Manager. The TemplateID parameter can reference the record IDs of these Conga Templates to predefine template selection.
  • In many situations, it makes sense to include a file that is attached to a Salesforce record as a template for a Composer solution. This is not usually a template with merge fields included - more often it is a document such as one of the examples below:
    • Custom terms and conditions added to a proposal document.
    • A candidate's resume included in a job application document.
    • A contract addendum.

  • A QVar is useful to retrieve the record ID of a Salesforce Attachment record and then reference that Attachment record as the value of the TemplateID parameter. In this use case, the SOQL Query requires some additional custom filtering to direct the QVar on what type of Attachment to select.

  • For example, a user wants to select the file attached to an Opportunity that represents custom terms and conditions for a proposal.

    • Example SOQL Query:

  • Similar to the previous example, there are two filters used in the query. The first filter looks for a dynamic parent ID and the second filter looks for Attachments with the word "Terms" in the file name. The second filter is entirely customized to the type of file a user needs to select. A user could also filter for a specific file extension, a particular keyword, or any other unique identifier.
    Tip: Establishing a file naming convention is a recommended best practice when using this type of QVar. Setting up QVars to retrieve Attachments in only worthwhile it is used dynamically across records for the same purpose.

  • Example parameter configuration:

    1. The Conga Query ID is referenced with &QVar1Id.
    2. The proposal template is hard-coded as the first template merged using the &TemplateID.
    3. The {QVar1} result is used as the second value for the TemplateID parameter, separated by a comma.


  • When a user launches this Composer button, it replaces {QVar1} with an Attachment record ID and then Composer merges both templates. The merged templates may be combined into a single output file or merged separately in a .zip file.

Using Multiple Email Addresses as CC Recipients

  • The previous examples both used QVars to retrieve single data values (Contact ID and Attachment ID). However, QVars are highly useful for returning multiple data values, such as a handful of email addresses that need to be included as additional recipients on an outbound email.

    When working with multiple values in a QVar, it is almost always necessary to format the result to separate each value by commas or surround each value with quotations. The QVar0Format parameter simply allows users to format a QVars resulting data.

    In this scenario, a user is on an Opportunity record and needs to email the related Account's Primary Contact (accomplished with the QVar in the first example) in addition to CCing related Contacts with Opportunity Contact Roles of "Decisions Maker".

  • Example SOQL Query for QVar:

  • Example of Decision Makers (Contact Roles) on an Opportunity:

  • The above SOQL query will return all three email addresses. To separate each email address with commas, it requires the QVar0Format parameter.

  • Example parameter configuration:


    1. The Conga Query ID is referenced with &QVar2Id.
    2. The results of the query are formatted with &QVar2Format. The parameter value of 10000 separates each data value with a comma (appropriate for multiple email addresses).
    3. The {QVar2} result is used as the value for the EmailCC parameter.


Using All Three QVar Use Cases to Send an Email - Bringing It All Together

  • Using all three QVars described above together creates an elegant and streamlined Composer solution:

    1. The first QVar retrieves the Account's Primary Contact and defines it as the main email recipient.
    2. The second QVar retrieves the Decision Maker Contact Roles and includes them as CC recipients.
    3. The third and final QVar retrieves the attached terms and conditions file and combines it with a proposal template as a single PDF attachment.