Conga Workflow Configuration Guide (7)

Configuration Guide
Release 7 – Winter ‘13
This configuration guide is intended to walk you through how to set up Conga
Workflow® to automate Conga Composer ® solutions.
Contact Support:
support@congamerge.com
Americas
(866) 502-3334 (toll free)
(303) 465-1616
EMEA
+44 (0) 203 608 0165
APAC
+61 2 8417 2399
© 2014 Conga. All Rights Reserved. Conga, Conga Suite, Conga Composer, Conga Workflow and Conga Conductor
are all trademarks or registered trademarks of Conga, as are other names and marks. All other trademarks or
registered trademarks are the properties of their respective owners.
Configuration Guide
Contents
General Disclaimer .............................................................................................................. 3
............................................................................................................................................. 4
Purpose................................................................................................................................ 4
Before You Get Started .................................................................................................... 4
Configuring a Conga Workflow Solution ............................................................................. 4
QMode Parameters ............................................................................................................. 5
Configure a Salesforce Workflow Rule ............................................................................... 6
Caveats, Warnings and Known Issues ............................................................................... 9
Troubleshooting Conga Workflow..................................................................................... 10
Hyperlink Formula Fields – A Troubleshooter’s Best Friend ........................................ 10
Troubleshooting Tips ...................................................................................................... 11
Appendix: How to Manually Convert a Salesforce Custom Button into a Formula......... 12
Replacing Ampersands (&) in Your Data ...................................................................... 13
© 2014 Conga
Release 7 – Winter ‘13
2
Configuration Guide
General Disclaimer
Conga Composer solutions depend on and leverage technology from a multitude of
software and hardware vendors including but not limited to Salesforce.com, Microsoft
and Conga, and the providers of various Internet browsers (“Third Party Technology”).
Conga Composer does not perform well, or at all, in certain configurations of Third Party
Technology, and unfortunately it is impossible for us to know or predict all of these
problematic configurations. Moreover, Conga has no control over your configuration of
Third Party Technology, data flow to and from Salesforce.com, or the Internet. As a
result, output from Conga Composer can be impacted by numerous factors beyond the
control of Conga, including:
•
Template design errors in Microsoft Word, Excel, PowerPoint templates, PDF
Forms or Conga HTML email templates
•
The nature and scope of data and/or images being retrieved for merging into
templates
•
Individual user’s browser, network, ISP and hardware settings and associated
limitations
•
The availability and performance of the Salesforce.com service and other
software-as-a-service solutions such as e-signature, e-commerce and other
AppExchange products, and periodic updates, enhancements or other changes
to such services made by their respective vendors
•
Salesforce.com updates, security settings including User Profiles and
Permissions, folder and object access and field-level security
•
Internet performance, regional and even global outages
For these reasons, Conga cannot guarantee that your particular implementation
of Third Party Technology and the Conga technology – even if configured based
on this documentation and/or guidance offered by Conga Support personnel - will
perform consistent with your expectations or requirements, or provide the output
you desire. Accordingly, Conga disclaims any and all liability resulting from, or
related to, performance issues of Conga to the extent arising from the
implementation or configuration of Third Party Technology.
508 Compliance
Conga Composer is an installable package from the Salesforce AppExchange, which
integrates with an individual customer's existing implementation of Salesforce. When
properly configured, Conga Composer will run within an existing Salesforce instance
without the need to view, manipulate or configure the application outside of
the Salesforce user interface.
The use of Conga solutions is entirely represented by standard Salesforce user
interface components when properly configured. Therefore, customers seeking the 508
Compliance VPAT documentation are referred to Salesforce.
© 2014 Conga
Release 7 – Winter ‘13
3
Configuration Guide
Warning!
If you plan to automate a Conga Composer solution using a
Word template with Conga Conductor or Conga Workflow,
please use traditional merge fields (e.g. «ACCOUNT_NAME»)
instead of text-based merge fields (e.g. {{ACCOUNT_NAME}}).
See the Conga Composer Word Templates Guide for Release
7 to learn about traditional merge firelds.
Purpose
Conga Workflow can initiate a Conga Composer solution, thus enabling the creation of
a document without direct user interaction.
Using Conga Workflow in this manner is intended as a substitution for manually clicking
a Composer button. It is NOT intended for processing thousands of simultaneous
requests due to Salesforce API constraints.
Before You Get Started
This guide assumes that you’re generally familiar with Salesforce workflow. In particular,
you should know how modifying a field on a record can trigger Salesforce workflow to
perform an action, such as sending an Outbound Message.
Heads Up
Conga Workflow is an add-on to an active Conga Composer
subscription and is purchased separately. The service must be activated
by Conga before use. Please contact us at support@congamerge.com
to subscribe.
Configuring a Conga Workflow Solution
To configure Conga Workflow, follow these steps:
1. Create a Composer button/link solution that fully accomplishes the solution you’d
like to automate
2. Create a field on the master object to trigger a Salesforce workflow rule. You can
use a checkbox field, or any other kind of field as the control mechanism
© 2014 Conga
Release 7 – Winter ‘13
4
Configuration Guide
3. Copy the URL from the button in Step 1 to the clipboard. It will be pasted into a
formula field in the next step
a. On the master object, create a formula field (text). You may call it
whatever you like, i.e. “Conga Solution URL”
4. Ensure the formula field is visible to the user profile that will be launching the
Conga Workflow process.
Note: It is not necessary to place the field on the object’s Page Layout, but it may
be useful during the development process.
QMode Parameters
Conga Composer uses settings to customize the behavior of solutions. Additional
parameters, called QMode parameters, are required when working with Conga
Workflow or Conga Conductor ® solutions.
QMode Parameter
Description
&QMode=1
Attaches the merged output to the master object.
Note:
Do not use in conjunction with other parameters that attach the file,
(e.g. &LG3=2.)
&QMode=2
Do not use with Conga Workflow, only valid for Conga Conductor
solutions.
&QMode=3
Emails the output file.
Requires:
•
&TemplateId
•
&EmailTemplateId
•
&EmailToId
Note:
For an Opportunity with a Primary Contact (Contact Roles), it’s not
necessary to set the &EmailToId.
Also, if you use &EmailTemplateId, you must specify the EmailToId.
If you use &EmailSubject, you must specify &EmailAdditionalTo.
© 2014 Conga
Release 7 – Winter ‘13
5
Configuration Guide
QMode Parameter
Description
&QMode=4
Delivers the output via EchoSign.
Requires:
•
&QMode=5
EchoSign parameters
Attaches the output file to a folder on the Documents tab.
Requires:
•
&QMode=6
&DocFolderId
Attaches the output file to a workspace in Salesforce Content.
Requires:
•
&QMode=7
&ContentWorkspaceId
Delivers the output via DocuSign.
Requires:
•
&Qmode=94
DocuSign parameters
Creates an EchoSign Agreement but does not automatically deliver
it.
Requires:
•
EchoSign parameters
Configure a Salesforce Workflow Rule
Conga Workflow triggers the execution of individual Conga Composer solutions via
Salesforce workflow rules. In this example, we want Conga Workflow to run a
Composer solution every time a user saves a record that has a checkbox field called
“Conga Workflow Trigger” checked.
© 2014 Conga
Release 7 – Winter ‘13
6
Configuration Guide
1. Create a Workflow Rule.
2. Create an Outbound Message and set the endpoint URL to the following value:
https://workflow.appextremes.com/apps/Conga/PMWorkflow.aspx
IMPORTANT: Select the “User as Send As”, and enable “Send Session Id”.
Warning
In the list of available fields the ID field is selected by default. Do not
select any other fields).
3. Link the Outbound Message to the workflow rule. (From the workflow rule, edit
the workflow actions and select the outbound message created in the prior step.)
© 2014 Conga
Release 7 – Winter ‘13
7
Configuration Guide
4. Create a Field Update action to reset the field used to trigger the workflow. In
this case, we’ll created a Field Update action to set the trigger checkbox back to
False.
5. Link the Field Update action to the workflow rule.
Warning
If you do not reset the field, you risk unleashing an endless cycle.
6. Activate the workflow rule.
© 2014 Conga
Release 7 – Winter ‘13
8
Configuration Guide
Caveats, Warnings and Known Issues
•
Conga Workflow is limited to 500 solutions per 24-hour period and not more than
50 solutions per batch. Conga Workflow is a transaction-based service. You
will be charged per use
•
If updating records with a tool like the Salesforce Data Loader, we strongly
recommend you use the credentials of a user who’s Profile has “Disable
Outbound Messages” enabled to avoid inadvertently triggering a massive merge
operation
•
Keep in mind that the number of outbound emails permitted through Salesforce is
dependent on the edition you’ve purchased. At the time of this writing, Salesforce
allows 1,000 emails per 24-hour period for Performance edition and 500 emails
per 24-hour period for all other editions. (Consider Conga Composer’s integration
with SendGrid if you need to exceed the Salesforce limits)
•
Each merge operation consumes at least 20 API calls, and some consume as
many as 50. Therefore, you’ll need to gauge the number of merge operations you
plan to consume with the number of API calls you’re allowed in a 24-hour period
•
Since an Outbound Message operates under the authority of a named user, be
excessively careful to ensure that you do not trigger a merge operation that
exposes more information than a user would normally have privilege to access.
Consider using a collection of workflow rules and outbound messages that
execute depending on the identity of the end-user
•
“User” fields normally made available executing a standard Conga Composer
solution will, in the case of a workflow-triggered operation, be those of the user
under whose authority the workflow is running. Thus, an Invoice template with a
merge field intended to retrieve the name of the person pressing a button/link will
instead be populated with the name of the admin or named user defined by the
Conga Workflow setup
•
Conga Workflow processes requests on a first-come basis. It is possible, but
unlikely, that your request won’t be processed because the session has expired.
You can minimize this likelihood by increasing the API Session Timeout value
•
Please ensure that ampersands in text fields passed via Conga Workflow have a
space before and after the ampersand character
•
Conga Workflow is intended to be executed against individual records (batches
of 1). While it is possible to update many records in Salesforce, resulting in a
batch of Conga Workflow requests, the use of Conga Workflow in this manner
risks tripping an automatic Conga system governor designed to prevent a
"runaway" process from “looping” uncontrollably and potentially harming certain
systems. Also, if ANY record in a batch of Conga Workflow requests contains an
invalid value in the Conga Composer URL field, the ENTIRE BATCH will fail.
© 2014 Conga
Release 7 – Winter ‘13
9
Configuration Guide
Troubleshooting Conga Workflow
Conga Workflow solutions can be impacted by multiple factors that are difficult or
impossible to troubleshoot by triggering a workflow rule. The technique described below
is the best way to effectively test the URL formula field – via the standard Conga
Composer user interface - offering access to the View Data workbook, template
visibility, license status and other useful insights.
Typically, this approach will allow the identification of problems with reports/queries and
template access that can cause extended duration routines resulting from Salesforce
timeouts.
Conga recommends the use of this technique as a first step whenever challenges arise
in the use of Conga Workflow.
Hyperlink Formula Fields – A Troubleshooter’s Best Friend
Conga recommends the use of a hyperlink formula field as a debugging tool for
implementations of Conga Workflow.
Here is the content of a typical workflow field (we'll call it: CW_URL__c):
"&id=" + Id +
"&TemplateID=a0B50000000OiWY" +
"&DefaultPDF=True" +
"&QMode=3"
The following example allows you to easily debug and verify access to the Conga
Workflow URL field CW_URL__c:
HYPERLINK("https://workflow.appextremes.com/apps/Conga/PointMerge
.aspx?SessionId="
& $Api.Session_ID
&"&ServerUrl=" & $Api.Partner_Server_URL_80
& CW_URL__c, "Test Conga Workflow URL via UI")
Note: QMode parameters will not function when called using this technique (launching
via the Merge button will return an output file to the browser), but all other elements will
perform as specified (Activity Logging, etc.)
© 2014 Conga
Release 7 – Winter ‘13
10
Configuration Guide
Troubleshooting Tips
The primary factors that affect the behavior of a Workflow URL field are:
•
Field accessibility (restricted to certain profiles)
•
Whether it contains a value
•
The field contains or references fields containing ampersands that don't have
spaces around them when intended as data
Example: "Ben&Jerry's" (don't do this!) versus "Ben & Jerry's" (this is fine). Conga can't
distinguish between the data and the parameters if the ampersands within the data don't
have spaces. See “Replacing Ampersands (&) in Your Data” in the Appendix.
© 2014 Conga
Release 7 – Winter ‘13
11
Configuration Guide
Appendix: How to Manually Convert a Salesforce Custom
Button into a Formula
1. Copy the URL from your working Conga Composer button and paste it in your
formula field’s formula window
For example:
https://composer.congamerge.com
?sessionId={!API.Session_ID}
&serverUrl={!API.Partner_Server_URL_130}
&id={!Opportunity.Id}
&templateId=a0I80000000laT3
&fp0=1
&LG4=1
2. Remove the following unnecessary lines:
a. https://composer.congamerge.com
b. ?sessionId…}
c. &serverUrl…}
3. Convert the remaining lines into a valid Salesforce formula. The formula must
adhere to the following rules:
•
Literal text strings must be enclosed in quotes (" … ")
•
Literal spaces within literal text strings must be replaced with plus signs
(+)
•
Merge fields from the button must be replaced with the corresponding field
available in the formula. For example, {!Opportunity.Id} would be
replaced with Id
•
Each element (literal text strings and fields) must be joined with the
concatenation operator (+)
4. Append the QMode parameter to indicate the solution Conga Composer should
run
For example: + "&QMode=1"
Button URL
Formula
https://composer.congamerge.com
?sessionId={!API.Session_ID}
&serverUrl={!API.Partner_Server_URL_130}
&id={!Opportunity.Id}
&templateId=a0I80000000laT3
&fp0=1
&LG4=1
“&id=”+Id+
“&templateId=a0I80000000laT3”+
“&fp0=1”+
“&LG4=1”+
“QMode=1”
© 2014 Conga
Release 7 – Winter ‘13
12
Configuration Guide
Replacing Ampersands (&) in Your Data
Say your formula references the Account Name field in the OFN parameter. Since some
Warning
The formula field uses ampersands (&) to identify parameters. If you
reference fields that might contain ampersands within the formula, you
must replace the ampersands with a character string that Conga
recognizes as a substitute for ampersands: “{~~~}”.
Account Names might contain an ampersand, you should replace the ampersands like
this:
Incorrect
Correct
"&OFN=" + Account.Name
"&OFN=" + SUBSTITUTE (Account.Name, "&", "{~~~}" )
© 2014 Conga
Release 7 – Winter ‘13
13