Merge code mapping

Merge code mapping allows you to specify a Upland Qvidian merge code for a Salesforce.com object and Salesforce.com field. For the specified object and field, you can also specify an Salesforce.com value and provide the name of the merge code value. When Salesforce.com data is retrieved to a Upland Qvidian created document or project's Data Entry Screen component, it is transferred to the merge code specified for the object and field and, if applicable, the name of the merge code value.

When creating a mapping, the SFDC Object identifies the object or record type (e.g. Account, Contact, Opportunity). Because the "New Qvidian Document" function will be launched from a specific object within Salesforce, all values in the SFDC Object must be represented by a path from the SFDC Object to where the Qvidian Document originated. To create a new Merge Code mapping (from the Merge Code Mapping workspace in Upland Qvidian), three items are required:

• SFDC Object: The string that is required to define which field gets mapped to which merge code. In other words, when creating a mapping, the SalesforceObject identifies the object or record type, such as Account, Contact, and Opportunity. Because the New Qvidian Document function will be launched from a specific object within Salesforce, all values in the SalesforceObject must be represented by a path from the Salesforce Object where the Qvidian Document originated. If the SFDC Object is the originating object, its name is the only path needed. If the SFDC Object is related to the originating object (e.g. the Account associated to the Opportunity – and the New Qvidian Document originated from the Opportunity), the path (or relationship) must be identified.
• SFDC Field: A value that is equal to the SFDC Field Name if it is a standard field or the API Name if it is a custom field.
• Merge Code: A pre-defined merge code from architecting, which is a field you need to add into the proposal document type.

SSO and merge code mapping

For SSO customers there are two options:

• Map the merge codes on Salesforce.com, so that the values are passed in when the Create New Qvidian Project / New Qvidian Opportunity Document button is clicked.
• Give the Salesforce Connection user, one who will be working in the Administration > Salesforce > Connection page in Upland Qvidian, "Read" access to any Salesforce object you are attempting to map and check the Always Use box on the "Create Salesforce Connection dialog" box. This tells the merge code to use these credentials to pull its data mapped in Upland Qvidian.

Example: This Merge Code Mapping is configured via the Administration > Salesforce > Merge Code Mapping workspace. The Merge code mapping section shows an example of merge code mapping in which the <<client>> merge code value will populate with the name of the Account to which the Opportunity is tied in Salesforce.

Work with the Merge Code Mappings grid

Search

• To search for a mapping, enter text into the search box at the top right of the grid, and click the Search icon or Enter.
• To re-display all mappings in the grid, delete the entire entry in the box by clicking the X.

Filter the grid

Use the advanced filters to display specific mappings quickly on the grid.

1. Hover over the column header until you see the Filter icon appear.

2. Click the Filter icon to display the following dialog to set filtering parameters:

   • Text Columns: Select either Contains All, Contains Any, Matches Any, Matches Exactly, Starts with, Ends with, Is Empty, Is Not Empty, or Does Not Contain from the Operator dropdown menu. The Contains All, Contains Any, Does Not Contain, and Matches Any operators allows you to enter more than one value by pressing the Enter key after each value. The Starts with and Ends with operators allow you to enter a text value to find. The Is Empty and Is Not Empty operators do not require a value.
   • True/False Columns: Select either the Is True or Is False radio button.
   • Numeric Columns: Select either Equals, Greater than, Less than, Greater than or equal to, Less than or equal to, Not Equal to, Between, Matches Any, Is Empty, or Not Empty from the Operator dropdown menu. The Between operator shows two fields for the starting and ending values of the range you want to find. Is Empty and Not Empty operators do not require a value. All other operators require a single value.
   • Date Columns: Select either On, After, Before, Between, Is Empty, or Not Empty from the Operator dropdown menu. The Between operator shows two fields for the starting and ending dates of the range you want to find. Is Empty and Not Empty operators do not require a value. All other operators require a single value.
3. Click Apply.

Tip: To clear the filter, click the Clear Filter icon in the header, and then click Clear. You can also click out of the filter dialog to close it.

Sort columns

• To sort columns chronologically or alphabetically, click the column header name. The records will display in ascending order.
• To switch from ascending to descending order, click the selected column header name again.

Select grid rows

• Select your desired grid row(s) using the checkboxes or by clicking the rows and using CTRL+CLICK or SHIFT+CLICK to select multiple records.

Default v Compact column mode

You can switch between the default and compact column modes. Unless updated, the grid will remain in default mode. Compact mode shortens the height of the grid rows.

• To switch between the modes, go to My Preferences within the header Profile menu and select the Default and/or Compact radio buttons.

Add a new merge code mapping and merge code value(s)

You can add a merge code for a Salesforce.com object and an Salesforce.com field. Once the new mapping is saved, the Merge Code Mapping dialog re-displays where you can select the mapping record, specify an Salesforce.com value, and then specify a name for the merge code value.

1. Go to Administration > Salesforce > Merge Code Mapping.
2. Click Create Mapping. The "Create Merge Code Mapping" dialog displays.
3. From the Mapping Details tab, enter the SFDC Object string that is required to define which field gets mapped to which merge code. When creating a mapping, the SalesforceObject identifies the object or record type, such as, Account, Contact, and Opportunity. Because the function will be launched from a specific object within Salesforce, all values in the SalesforceObject must be represented by a path from the Salesforce Object where the Qvidian Document originated.
4. In the SFDC Field field, enter a value that is equal to the SFDC Field Name if it is a standard field or the API Name if it is a custom field.

Example: The API Name of a Custom Object is usually appended with the following: "__c". For example, "CustomObject__c".

5. Select the desired merge code from the Merge Code dropdown menu.

Note: This is a pre-defined merge code from architecting, which is a field you need to add into the proposal document type.

6. From the Merge Code Values tab, click the Add Merge Code Values link.
7. Enter the SFDC Value and Merge Code Value.
8. Click Add. To add more merge code values, click the Add Merge Code Values link.

Note: To edit a merge code value, hover over the desired value and click the Edit icon. To remove a merge code value, hover over the desired value and click the Remove icon.

9. Click Create. The Merge Code Mapping dialog re-displays. The selected merge code displays for the Salesforce.com object and Salesforce.com field as a record in the grid. At this point you can add a merge code value and specify the name of the value.

Edit merge code mappings and/or merge code values

1. Use one of the following methods to edit a merge code mapping or merge code values: 
   • Hover over the merge code you would like to edit and click the Edit icon. The "Edit Merge Code Mapping" dialog displays.
   • Select the checkbox of the desired item and click the Edit icon at the top of the grid. The "Edit Merge Code Mapping" dialog displays.
   • Double-click the row of the desired merge code. The "Edit Merge Code Mapping" dialog displays.
2. Edit the merge code mappings and/or merge code values as desired.

Note: To edit a merge code value navigate to the Merge Code Values tab, hover over the desired value, and click the Edit icon. To remove a merge code value, hover over the desired value and click the Remove icon.

3. Click Save. Click Cancel to discard any changes.

Duplicate a merge code mapping

1. Use one of the following methods: 
   • Hover over the merge code mapping you would like to duplicate and click the Duplicate icon. The "Create Merge Code Mapping " dialog displays.
   • Select the merge code mapping you would like to duplicate and click the Duplicate icon at the top of the grid. The "Create Merge Code Mapping " dialog displays.
2. Edit and/or add the merge code mapping and merge code value(s) as desired.
3. Click Create or Cancel to discard any changes.

Delete merge code mapping(s)

• To delete a single merge code: Hover over the desired row and click the Delete icon. You are prompted to confirm the deletion.
• To delete multiple merge code: Select the checkboxes of the rows would like to delete and click the Delete icon. You are prompted to confirm the deletion.
• To delete all merge codes: Click the Delete icon at the top of the grid column. You are prompted to confirm the deletion.

About SFDC Objects

If the SFDC Object is the originating object, its name is the only path needed. If the SFDC Object is related to the originating object (e.g. the Account associated to the Opportunity – and the New Qvidian Document originated from the Opportunity), the path (or relationship) must be identified.

String Syntax

The syntax of the relationship path is a variation of a string like this:

Object(Id).(ObjectId)

More complex strings will have several objects and ID's in the path. This string represents a way to link from a parent object to a child object and what fields to use to link them (field names are provided in parenthesis). To identify this information, you need to see the details of the Salesforce database/configuration.

Object1(Id).(Object1Id)Object2[0:ConditionField=SomeValue ORDER BY OrderByField1](Id).(Object2Id)Object3[1:AnotherConditionField=SomeOtherValue ORDER BY OrderByField2](Id).(Object3Id)Object4

Example 1

The Qvidian Document originates from the Opportunity and we want to reference the name of the Account associated with the Opportunity. The SFDC Field that links the Opportunity and Account SFDC Objects is AccountId.

Opportunity(AccountId).Account

Example 2

The Qvidian Document originates from the Opportunity and we are using the primary contact's information.

Opportunity.(OpportunityId)OpportunityContactRole[IsPrimary=true](ContactId).Contact

In case where there are multiple children of a particular type expected you can specify the index of a child or a condition, or a combination of both index and condition by placing it in square brackets. If the index is not specified, index 0 is assumed (the first child). Fields named “Id” can be omitted all together. So, the following is an exact equivalent of the value above:

Object1.(Object1Id)Object2[ConditionField=SomeValue SomeValue ORDER BY OrderByField1].(Object2Id)Object3[1:AnotherConditionField=SomeOtherValue SomeOtherValue ORDER BY OrderByField2].(Object3Id)Object4

Example 3

The Qvidian Document originates from the Account and we want to reference the second Opportunity associated to the Account. The SFDC Field that links the Account and Opportunity SFDC Object is AccountId, and the second opportunity has an index value of 1.

Account.(AccountId)Opportunity[1]

Example 4

The Qvidian Document originates from the Account and we want to reference the first Opportunity associated to the Account that has a value of New Business in the opportunity type field.

Account.(AccountId)Opportunity[Type=’New Business’]

Example 5

The Qvidian Document originates from the Account and we want to reference the third Opportunity associated to the Account that has a value of New Business in the opportunity type field.

Account.(AccountId)Opportunity[2:Type=’New Business’]

Example 6

Strings can go across objects (i.e. Opportunity and Account). The Qvidian Document originates from the Account and we want to reference the third Opportunity associated to the Account that has a value of New Business in the opportunity type field AND has a potential revenue amount above $10,000.

Account.(AccountId)Opportunity[2:Type=’New Business’ AND Amount>10000]

Order By

The ORDER BY clause in conditions is optional but can be useful if you expect multiple records in Salesforce to match your condition and want to ensure they always come in a specified order (e.g. almost every record in Salesforce has a CreatedDate field and everything can be ordered by that).

You cannot use the ORDER BY clause without a condition. If there is no condition you need, but you still want to order records you can create some condition that is always true (e.g. virtually every Salesforce object has an ID field that is never NULL). This means you can construct things like:

Id <> NULL ORDER BY CreatedDate.

Example 1

The Qvidian Document originates from the Opportunity and we want to reference all (figuring up to 10) Products associated with the Opportunity Line Item associated to the Opportunity. In this example we will assume that there are three tables involved: Opportunity, OpportunityLineItem, and PriceBookEntry. The field OpportunityID links the Opportunity and OpportunityLineItem tables. The field PriceBookEntryID links the OpportunityLineItem and PriceBookEntry tables. Since we want all associated line item products (again, assuming the maximum will be 10), we need ten entries in the SalesForceMapTable referring to indexes 0 through 9.

Opportunity.(OpportunityId)OpportunityLineItem(PriceBookEntryId).PriceBookEntry[0:Id <> NULL ORDER BY CreatedDate]
Opportunity.(OpportunityId)OpportunityLineItem(PriceBookEntryId).PriceBookEntry[1:Id <> NULL ORDER BY CreatedDate]
…
Opportunity.(OpportunityId)OpportunityLineItem(PriceBookEntryId).PriceBookEntry[9:Id <> NULL ORDER BY CreatedDate]

Special Characters

Conditions that are used to select child records cannot contain certain special characters directly. These characters are listed in the table below. If you must use one of these characters in your condition, you have to URL encode it. For example, use %2E instead of a period (.).

Common SFDC Objects and Fields

The most common SFDC Object values used in mappings to Upland Qvidian are:

In SFDC, an ID field exists for each Accounts, Opportunities, and Contacts objects of Salesforce to be able to retrieve the proper information related to that specific object. The ID that corresponds to each SFDC objects are as follows:

The most common SFDC field names used in mappings to Upland Qvidian are as follows:

Identifying Relationships

To identify the fields that identify relationships between two Salesforce objects, locate the Child Relationships folder under the Salesforce object, to locate the relationships.

The related field provides the Salesforce field that relates the two. The Child Fields folder provides the fields in the related object.