Installation and Administration Guide Release 8 This installation guide will walk you through how to install and deploy Conga Composer, including recommended settings for the application. Contact Support: support@congamerge.com Americas (866) 502-3334 (toll free) (303) 465-1616 EMEA +44 20 3608 0165 APAC +61 28 417 2399 2014 Conga. All Rights Reserved. Conga, Conga Suite and Conga Composer 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.
Contents Contents... 2 General Disclaimer... 3 Upgrading from Conga Composer Release 7?... 4 Technical Requirements... 4 Installing Conga Composer... 5 What s in the Managed Package?... 5 Installation Instructions... 7 Enable Security Settings... 7 Upgrading Conga Composer... 8 Update Your Conga Composer Button URL... 8 Recommended Settings... 11 Basic Settings... 12 Allow Use of Local Templates... 12 Conga Template Manager... 13 Behavior Modification... 13 User Management Settings... 14 Integration Partners Settings... 15 Preparing to use Conga Composer in a Sandbox... 16 Enabling OAuth for Conga Composer... 17 Configure Conga Composer as a Connected App... 18 Configuring Conga Composer OAuth Buttons... 19 Creating Conga Composer Solutions... 21 Create Conga Composer Buttons and Merge Templates... 21 Create Reports That Meet Your Needs... 21 2014 Conga Release 8 2
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, Google, and the providers of various Internet browsers ( Third Party Technology ). Output from Conga Composer solutions can be impacted by these and numerous other 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/or hardware settings (see Conga Composer Installation and Administration Guide for additional details) The use of any encryption gateways or appliances that require any re-direct of Conga Composer traffic The availability and performance of the salesforce.com service and other software-as-aservice solutions such as esignature, ecommerce and other AppExchange products, and periodic updates, enhancements or other changes to such services made by their respective vendors Salesforce.com 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 Conga technologies even if configured based on Conga documentation and/or guidance offered by Conga Support personnel will perform consistent with your expectations or requirements, or provide the output you require. Accordingly, Conga disclaims any and all liability resulting from, or related to, performance issues associated with Conga products to the extent arising from your implementation, configuration, or the behavior 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 8 3
Upgrading from Conga Composer Release 7? While Conga has made every effort to make Conga Composer Release 8 backwards compatible with Conga Composer Release 7, a small number of cases have been reported where the behavior of and/or output from Conga Composer Release 8 varies in content or appearance from Composer Release 7. It is the Customer s responsibility to thoroughly test all existing solutions with Composer Release 8 to ensure they perform as desired, and to make any necessary adjustments to templates, queries, reports or other components. Welcome Conga Composer enables salesforce.com customers to customize, streamline and scale their document generation and reporting for unlimited use cases across all organizations and industries. With Conga Composer, users can create and distribute sophisticated documents in Word, PowerPoint, Excel, HTML email and PDF forms using data from any Salesforce object. Conga Mail Merge, available as a separate add-on to Conga Composer at no extra charge, allows you to simplify mass mailings to generate hundreds of printable letters, labels and envelopes all at once. You can also log activities, update fields, create follow-up tasks to every record in a mail merge, or automate the entire process using Conga QuickMerge. Please visit our website for further information on Conga Mail Merge or Conga QuickMerge. Technical Requirements To install and successfully use Conga Composer, you must have one of the following from each category: Salesforce Edition: Performance / Unlimited Enterprise Professional Developer Internet Browsers Firefox Chrome Internet Explorer (version 10 or later recommended) Safari 2014 Conga Release 8 4
Template Software: Microsoft Office 2013 (Mac 2011) and earlier Adobe Acrobat XI and earlier Warning Adobe LiveCycle PDFs are not supported. Installing Conga Composer What s in the Managed Package? Conga Composer application, including: Conga Template Manager a custom object into which Conga Templates are stored. This custom object does not count against your Salesforce limit on custom objects. Conga Email Templates a custom object to build and store HTML email templates. This custom object does not count against your Salesforce limit on custom objects. Conga Query Manager (a.k.a Conga Queries) a custom object to build and store SOQL queries. This custom object does not count against your Salesforce limit on custom objects. Conga Composer Reports folder Custom Tabs: About Conga Composer, Conga Composer Setup, Conga Email Templates, Conga Queries, Conga Resources, Conga Templates Conga Composer Custom Settings for Production Org ID which is useful for customers who create Salesforce Sandbox instances and Server Endpoint URL for third party data security services 2014 Conga Release 8 5
Heads Up In Release 8, Conga Mail Merge has been removed from the Conga Composer managed package and is now available as a separate add-on product at no extra charge. No existing Conga Mail Merge solutions will be removed or changed, but customers who use Conga Mail Merge will need to install the separate addon to continue running their solutions. In Release 8, Conga Query Manager is included in the Conga Composer managed package. Customers who used Conga Query Manager previous to Release 8 will see an additional Conga Queries tab after upgrading their managed package and can decide to either consolidate their existing queries in the new tab or keep both tabs. 2014 Conga Release 8 6
Installation Instructions 1. Install Conga Composer into your Salesforce instance from visiting our listing on the AppExchange 2. Click the Get It Now button and follow the on-screen prompts to install Conga Composer Heads Up You must provide System Administrator credentials to install an application from the AppExchange. Enable Security Settings You must enable security settings to allow Conga Composer to interact with your data: 1. For each user profile that has access to Conga Composer, ensure the API Enabled setting is active. 2. If you want to use Salesforce Reports as a data source for Composer solutions, ensure that Run Reports and Export Reports are enabled for each user profile that has access to Conga Composer. Warning Do not set Lock IP Sessions in Salesforce. Doing this will disable Conga Composer from being able to communicate with Salesforce, rendering Conga Composer unusable. 2014 Conga Release 8 7
Upgrading Conga Composer Conga Composer Release 8 offers a wealth of enhancements and is backward compatible with previous releases of Composer. We recommend most customers upgrade to this latest release immediately. Conga Composer is a composite application, which means that some parts of the system are installed into your Salesforce instance in a managed package, however most of the system runs on our servers. As a result, the portion of the system that runs on our servers does not require upgrading on your part. Updates to the servers are automatically made available at various times throughout the year. WARNING! DO NOT UNINSTALL the previous version of Conga Composer before upgrading to Release 8. If you uninstall before upgrading, you will lose all of your existing Conga Composer solutions and will have to rebuild each of them manually. The portions of the system that are installed into your instance of Salesforce can be upgraded by visiting our listing on the AppExchange, clicking the Get it Now button and following the prompts to update the installed components. Do not uninstall the previous version of Conga Composer before upgrading to Release 8. If you do uninstall before upgrading, you will lose all of your previous Conga Composer solutions and will have to rebuild each of them manually. Update Your Conga Composer Button URL For customers upgrading from previous versions of Conga Composer to Release 8, you ll want to update your Conga Composer button URLs to utilize the new user interface, template building options and support tools. This can be done in just a couple of minutes with some simple copying and pasting. 2014 Conga Release 8 8
1. After upgrading your existing Conga Composer application to Release 8, locate a Conga Composer managed button (available on standard Salesforce objects). For instance, click to Salesforce Setup Build Customize Opportunities Buttons, Links and Actions Conga Composer. Click the Edit link. 2. Highlight and copy the first three lines of the button URL: 3. Open the Conga Composer custom button that you want to update (for example, my custom button is called Invoice), and click Edit. Next, highlight and delete the first three lines of the button URL (from https through the Partner Server URL field). 4. Finally, paste the three lines of the button URL you copied above in step 2 at the beginning of this URL. (It should now begin with https://composer.congamerge.com instead of https://www.appextremes.com/...) Click Save. 2014 Conga Release 8 9
Heads Up Ensure there aren t spaces in your button URL (they sometimes appear at the ends of the lines after copying and pasting). Spaces in the button URL will prevent Composer from working. 5. Your updated button will now run on Composer Release 8, including the new user interface, template building options and support tools: 2014 Conga Release 8 10
Recommended Settings You can change various user management, integration and basic settings in Conga by visiting the Conga Setup page, which is accessible from Salesforce Setup, then Installed Packages and Configure for Conga Composer. Note: The Conga Setup link also appears on the Conga Composer dialog box, under the Tools & Settings drop-down menu for users who have the following permissions: View All Data Modify All Data View Setup 2014 Conga Release 8 11
Basic Settings Under the Basic tab, you can change the default settings for local template usage, template manager repositories and solution behaviors. Allow Use of Local Templates By default and as a recommended practice, only users with the Salesforce System Administrator profile are permitted to upload a template from their local hard drives. This feature is always enabled for administrators because of its utility in creating and testing templates. You may enable this feature for all other user profiles by checking the box to permit users to upload a template from a local drive. Tips and Tricks Local templates can also be enabled on a solution-by-solution basis via the Conga Composer parameter &DS8=1. Visit the Conga Composer Index of Parameters for more information. 2014 Conga Release 8 12
Conga Template Manager Instead of using the Salesforce Communication Templates repository, we strongly recommend that you store templates in the Conga Template Manager (see Storing Merge Templates for details). This custom object is included in the Conga Composer application so does not require separate installation. Behavior Modification The Behavior Modification settings govern how Conga retrieves data and how templates behave. If your organization is new to Conga, we strongly recommend that you enable all of the Behavior Modification settings. Warning If your organization is upgrading to Release 8 from Conga Composer 1.6 or earlier (or any version where you previously did not have these settings enabled), you may now enable these settings, however, they may affect your templates proceed with caution. Query Object Name Correction This setting corrects a problem in which Conga Queries resulted in object names with double underscores. For example, a merge field name for the Amount field on an Opportunity sometimes appeared as: OPPORTUNITY AMOUNT Instead of OPPORTUNITY_AMOUNT This was an issue because modifying the Conga Query sometimes resulted in slightly different field names, thus preventing a merge field from working properly. Prevent Auto-Incrementing Column Name This setting corrects a merge field naming problem in Reports and Queries in which column names were appended with _1 to delineate multiple instances of the merge field across the entire dataset. 2014 Conga Release 8 13
Word Templates: Require TableStart/TableEnd for Detail Regions This setting makes it necessary to use TableStart/TableEnd to access detail data, which is important because some customers have unintentionally discovered that Conga Composer would generate a separate document for each row of detail data in the absence of a TableStart/TableEnd. Simple Report Column Names This setting prevents Conga from altering field names used in Reports and Queries when a Salesforce ID column is also referenced in the Report or Query. Enable Text-based Merge Fields (Word) This setting enables text-based merge fields in Microsoft Word templates. If this setting is not enabled only Microsoft Word traditional merge fields are available. Text-based merge field: {{ACCOUNT_NAME}} Traditional merge field: «ACCOUNT_NAME» User Management Settings Manage Licenses in Salesforce (Recommended) Conga strongly recommends that user management be performed with the "Manage Licenses" tool in Salesforce setup (Setup Installed Packages Manage Licenses). This standardizes how user licenses are managed with other AppExchange products and gives greater flexibility for large organizations. To use this feature, please contact your Conga Business Analyst or email support@congamerge.com. 2014 Conga Release 8 14
Alternatively, customer with Salesforce instances of 100 or fewer users (of any type) may manage user licenses with the older User Management tool. Larger organizations (more than 100 users) must use the Salesforce Manage Licenses tool as described in the previous section. The User Management tab facilitates the following user license activities: Determine whether User Management is enabled for your account View the number of licenses your organization has purchased and how many of those licenses are assigned Sort or search the list of users by Name, Role or Profile To enable a license for a user, enable the checkbox for that user (to the left of the First Name) and click the Save Changes button. Integration Partners Settings Conga Composer integrates with a number of different providers. The Integration Partners tab introduces the partners and how their products are configured to work with Conga Composer. For more information, please refer to the Conga Composer Configuration Guide. 2014 Conga Release 8 15
Preparing to use Conga Composer in a Sandbox You can configure your instance of Salesforce so that if you later generate a Sandbox from the production instance, Conga will automatically transfer your license information to the Sandbox. This is recommended for any organization using Sandboxes as otherwise Conga will view each Sandbox as a new 30 day free trial of Conga Composer. 1. In your Production instance, copy your Salesforce Organization ID to the clipboard (Setup Company Profile Company Information) 2. In Setup, click Develop Custom Settings 3. Click Manage for Conga Composer 4. If necessary, click New to create a new record, otherwise Edit 5. For the Name field, enter Conga Settings 6. For the Production Org ID field, paste your Organization ID 7. Save the record With this Custom Setting established, Conga carries the ID of your Production instance to any Sandboxes generated. The first time you click a Conga button from within the Sandbox, Conga will recognize that the Sandbox is linked to an existing production instance and automatically transfer account subscription dates and template manager settings. User permissions are not transferred; Conga user license restrictions are not enforced in Sandbox instances. 2014 Conga Release 8 16
Enabling OAuth for Conga Composer Salesforce s OAuth (an abbreviation of open authorization) is an open protocol which allows secure authorization of desktop and web applications to access APIs. A commonly used analogy is the valet key to a car, which allows the car to be driven (perhaps a limited distance), but does not give access to the glove box or trunk. In the same way, OAuth allows users to authorize applications to access resources on their behalf via an access token, rather than by handing over their actual username and password. (Patterson, 2011) What s new with authentication in Composer 8? Conga has enabled Salesforce OAuth Authentication in Conga Composer8. OAuth Authentication, an industry-wide accepted protocol for secure API authorization, provides several key benefits: The identification process occurs securely between Salesforce and Conga servers, which reduces client-side security risks. The process makes it simple for a user (or administrators) to revoke the communication between Conga and Salesforce, if desired. What is the user experience with OAuth Authentication? If a user hasn t authorized Conga before, when he clicks a Conga Composer button, he is presented with a Salesforce dialog box asking whether to allow Conga Composer to access to various Salesforce functions. If the user authorizes Composer, Salesforce responds with a temporary code (which Composer uses in conjunction with a protected key) to allow the Composer to interact with Salesforce on the user s behalf. The user, or the administrative staff, can revoke Conga Composer s access at any time using the revoke link found in My Settings -> Personal -> Connections. There may be multiple entries for Conga. If access is revoked, the user will be presented with the Salesforce Authorization window the next time they use a Conga product. Is my organization required to use OAuth Authentication? No. Traditional Salesforce URLs, (that utilize a Salesforce Session ID), will still operate as usual. 2014 Conga Release 8 17
Are there any limitations when using OAuth Authentication? Yes; the use of Salesforce reports for Conga Composer solutions using OAuth is only supported in Conga Composer version 8.2 or later. If you re running version 8.0 or 8.1, we recommend upgrading (it s free!) to version 8.2. Alternately, you can use SOQL queries instead of Salesforce reports. Configure Conga Composer as a Connected App 1. Navigate to Setup Manage Apps Connected Apps Conga Composer 2. Click the Edit button and change the Permitted Users picklist to Admin approved users are pre-authorized 3. Designate which users connect to Conga Composer via OAuth by adding Profiles (click the Manage Profiles button) or Permission Sets (Manage Permission Sets) 2014 Conga Release 8 18
Configuring Conga Composer OAuth Buttons Utilizing Conga Composer via OAuth requires special Conga Composer OAuth buttons instead of the standard Conga Composer buttons. The Conga Composer OAuth buttons are included in the managed package. You can use either the managed buttons or copy and paste the URL from the button into a new custom button to customize it as you wish. Below, we create a custom OAuth button: 1. Locate a managed Conga Composer OAuth button by navigating to Leads, Accounts, Contacts, Opportunities, Cases, Contracts, or Solutions Buttons, Links and Actions Conga Composer (OAuth) 2. Copy the Button or Link URL to your clipboard. 3. Navigate to your desired standard or custom object. For this example, we re using the Account object. Click New Button or Link, give the button a Label, choose Display Type as Detail Page Link or Detail Page Button, select the Behavior as Display in new window and paste the Button or Link URL you copied in step 2, and Save. 2014 Conga Release 8 19
4. Click Window Open Properties and set the Height to 660 and Width to 900 and Save. 5. Add your button to the object s Page Layout. 2014 Conga Release 8 20
Creating Conga Composer Solutions Create Conga Composer Buttons and Merge Templates You can add Conga Composer buttons to any desired standard or custom objects. You can also create merge templates in a variety of formats: Word, Excel, PowerPoint, HTML email or PDF. See reference guides for each template type on the Documentation page of our website for details. Create Reports That Meet Your Needs See Using Salesforce Reports with Conga Composer in the Conga Composer Configuration Guide. You can also learn more in QuickStart 3 Gathering Additional Data. Video Watch the Conga QuickStart Series to get started creating Conga Composer solutions. 2014 Conga Release 8 21
Bibliography Patterson, P. (2011, March 3). Digging Deeper into OAuth 2.0 at Salesforce.com. Retrieved April 16, 2014, from Salesforce Developer Relations Blog: https://developer.salesforce.com/blogs/developer-relations/2011/03/diggingdeeper-into-oauth-20-at-salesforcecom.html 2014 Conga Release 8 22