Parameter Deep Dive: Background Mode using DS7

Another Thursday, another helping of Tips & Tricks from yours truly.  I’m excited to introduce the first post in a recurring series of “Parameter Deep Dives” where we focus on a specific Conga Composer® parameter and discuss the finer points of how it can be used.  Today, we start with what is probably my favorite parameter in the entire Conga arsenal: DS7 for background mode.

 

What is “background mode”, you ask?  Background mode is a way of bypassing the classic Conga Composer user interface for, in many cases, one-click automation of an entire Composer solution.  We’re all about efficiency over here at the Conga ranch and love removing clicks, choices and decisions from a business process.  Background mode is great at accomplishing exactly that, particularly for the benefit of end users, and makes for an extremely streamlined document generation and delivery experience.

 

Sound good?  Then let’s get cracking.

The parameter responsible for initiating background mode is DS7.  DS7 can be set to a variety of values depending on what type of automation you’re looking for.  Because background mode is designed to bypass the Composer interface, the general rule of thumb is that you’ve predefined ALL of the selections that a user would typically need to make in the interface to accomplish your desired merge.  We like to joke that our development guys are still working on the “clairvoyance module”, so you’ll still need to define things like your template ID, your desired output format, activity logging settings and email recipients before automating the process.

 

There’s a lot of ways background mode can be leveraged, but let’s walk through two common scenarios where, in my opinion, it kicks the most amount of ass.

If a Composer solution is simply rigged to merge an output file for immediate download, background mode can make that process automatic.  Setting your DS7 parameter to a value of either 3 or 13 will give you an automatic file download.

 

 

 

https://www.appextremes.com/apps/Conga/Composer.aspx

?sessionId={!API.Session_ID}

&serverUrl={!API.Partner_Server_URL_80}

&id={!Account.Id}

&TemplateID=a03E0000008GNPk

&reportid=[Contacts]00OE0000000HM5a,

[Opptys]00OE0000000HM5k,

[Cases]00OE0000000HM5p,

[Usage]00OE0000002SxHS

&QueryId=[QueryContacts]a04E0000001QpxR,

[AvgUsage]a04E0000004Rv4W,

[UsageChart]a04E0000004RzIs?pv0=,

[SiteVisits]a04E0000004RzIx

&DS7=3

 

The example shown above uses DS7=3 for what I like to call “semiautomatic” background mode.  The user is still prompted with a dialog and given the option to either download or close, but it’s vastly simpler than the traditional interface.  For fully automatic downloads, DS7=13 can be applied for a true single-click experience.*

 

*A word of caution: web browsers are typically wary of allowing an application to automatically download a file to the user’s computer, so proceed carefully when going fully automatic.  Unsurprisingly, Internet Explorer typically has the most trouble with this setting, so using &DS7=3 is often a more tactful approach.

The name says it all.  Why click and make selections when you can predefine email recipients, your document template and an email template for streamlined excellence?

 

 

https://www.appextremes.com/apps/Conga/Composer.aspx

?sessionId={!API.Session_ID}

&serverUrl={!API.Partner_Server_URL_80}

&id={!Opportunity.Id}

&ReportID=[Widgets]00OE0000002Sww0,

[Labor]00OE0000002SwwA

&EmailToId={!Opportunity.Billing_ContactId__c}

&TemplateID=a03E0000008GNQ4

&CETID=a02E0000005QPkX

&DS7=2

 

You also have a semiautomatic and a fully auto option for sending emails with background mode.  Applying a value of 2 to the DS7 parameter automates the creation of your document and email, but takes you to the actual email screen before sending it out the door.

 

 

For the adventurous, simply using a value of 12 instead of 2 for your DS7 parameter will automatically send the email with no preview.  It’s quick and extremely streamlined, but I strongly recommend testing your solution thoroughly before going fully auto.

 

Those are two common scenarios where background mode makes a lot of sense, but it can also be used to automatically:

• Attach your output file to a Salesforce record

• Send a document for eSignature using Adobe^® EchoSign^® or DocuSign^®

• Send your output file to Salesforce^® Content or SpringCM^®

 

Now that we’ve explored a couple of ways that background mode can be used, let’s cause a disturbance in the force with some advanced tactics for the DS7 parameter.

 

We’ve seen many scenarios where an administrator wants their users to experience the glory of background mode by creating a completely predefined Composer solution, but need to allow themselves the flexibility of using the full Composer user interface.  A simple IF formula in the button URL accomplishes this by assigning a different value to the DS7 parameter based on the running user’s profile (or other conditions).

 

https://www.appextremes.com/apps/Conga/Composer.aspx

?sessionId={!API.Session_ID}

&serverUrl={!API.Partner_Server_URL_80}

&id={!Opportunity.Id}

&ReportID=[Widgets]00OE0000002Sww0,

[Labor]00OE0000002SwwA

&EmailToId={!Opportunity.Billing_ContactId__c}

&TemplateID=a03E0000008GNQ4

&CETID=a02E0000005QPkX

&DS7={!IF( $User.ProfileId = "00eE0000000sqP8", "0", "2")}

 

In the above button URL, you can see that the entire value of DS7 is an IF formula.  If the running user’s Salesforce profile Id is that of a system administrator (naturally, the 15-character Id will be different in each environment), then 0 is the assigned value.  If not, the value is set to 2.  To accommodate more complex conditions, you could also make clever use of a CASE formula to assign different background mode behavior to a variety of profiles or roles if they use the same button.

 

A perfect complement to the DS7 parameter is the BML parameter, which stands for “background mode label”.  This handy little setting allows you to predefine a custom message (up to 50 characters) which displays in the background mode dialog upon clicking a Composer button or link.  Just make sure spaces are represented as ‘+’ symbols.

 

Parameter:

 

&BML=Click+download+for+your+account+brief.

 

Result:

 

The DS7Preview parameter is also exceptionally useful for previewing PDF output files before they’re sent via email or for eSignature using background mode.  It gives the running user a nice halfway point in an automated solution where they can scope out the file created by Composer and either cancel or continue.  It’s a very simple parameter – just put &DS7Preview=1 into the button URL of a Composer solution using background mode and you’re all set.

The real value of background mode is predefining selections and bypassing the interface, but what if you want to have control over just a few settings while still enjoying the benefits of automation?  Much like how we used an IF field in the Composer button URL to disable background mode for admin users, you can create an entire DS7 dashboard on an object’s page layout to control exactly what Composer parameters you need defined.  Think of it like a custom console – here’s a basic example of how to approach this:

 

 

I’ve created a little section of the Opportunity’s page layout that contains a Contact lookup field, a checkbox to determine if the output file will be attached to the quote and a checkbox to toggle the output format.  Starting with a Word template for a quote, I’ve predefined those settings on the layout in tandem with some IF formulas in the Composer button URL:

 

https://www.appextremes.com/apps/Conga/Composer.aspx

?sessionId={!API.Session_ID}

&serverUrl={!API.Partner_Server_URL_80}

&id={!Opportunity.Id}

&ReportID=[Widgets]00OE0000002Sww0,

[Labor]00OE0000002SwwA

&TemplateID=a03E0000008GNQ4

&CETID=a02E0000005QPkX

&DS7=12

&DefaultPDF={!IF( Opportunity.PDF_Output__c = true, "1", "0")}

&EmailToId={!Opportunity.Email_RecipientId__c}

&LG4={!IF( Opportunity.Attach_Output_File__c = true, "1", "0")}

&LG3={!IF( Opportunity.Attach_Output_File__c = true, "2", "0")}

 

Using the above button logic and custom fields on the Opportunity, creating the quote leaves me with the following result:

 

 

Boom!  I have control over my email recipient, activity logging settings and output format – all without touching the standard Conga Composer interface.

 

I hope this gives you some ideas about how to use DS7 for background mode – there are tons of possibilities for the use of this parameter beyond what was discussed in this post, so I encourage you to go forth and automate!  See you next week.