Mergefields
- Anne Krieg
- Phu Nguyen (Unlicensed)
- 1 General
- 2 Creation of custom mergefields
- 3 Configuration
- 3.1 Mergefields related to Quote
- 3.2 Mergefields related to Account
- 3.3 Mergefields related to Contact
- 3.4 Mergefields related to User
- 3.4.1 Standard User Mergefields
- 3.4.2 Custom User Mergefields
- 3.5 Mergefields related to Opportunity
- 3.6 Mergefields related to Product
- 3.7 Special feature: variables from formula fields
- 3.8 Mergefields and translations
General
Placeholders or so-called "mergefields" are used to read field values from Salesforce dynamically at runtime in quotes. This function is available for the following objects:
Opportunity
Account
Contact
Quote
User
Product
With the help of merge fields, you not only map information very quickly in the quote, but also ensure that it is up-to-date - provided your base data in Salesforce is maintained cleanly and continuously.
In the quote itself, you use the placeholder in curly brackets, e.g. to pull the recipient's address data. As soon as the editing mode is finished, the mergefield is read out and the stored value appears.
Some mergefields are already predefined per object; you will find them listed below. However, you can also define placeholders for custom fields and use them in quotes as well.
Creation of custom mergefields
Custom mergefields can be added, structured by object, either in Admin Settings > Functionality - or via the corresponding setup texts:
Admin Setting | Corresponding Setup-Text |
|---|---|
Additional quote fields | quoteFields |
Additional opportunity fields | opportunityFields |
Additional account fields | accountFields |
Additional contact fields | contactFields |
Additional user fields | userFields |
Custom mergefields require the full API name including namespace, if available. This must also be entered in the setup parameter or in the settings. The upper and lower case can be ignored.
Note about custom variables with the prefix sf42_quotefx__SF42_
If you want to use custom fields as variables with the prefix sf42_quotefx__SF42_, please note the following:
Enter the correct API name in the setup text.
In the variable, replace the string 'sf42_quotefx__' with 'quote__'. The rest of the configuration remains the same as described below.
Example: The sf42_quotefx__SF42_QuoSum_Listprice__c field becomes the {quote__SF42_QuoSum_Listprice__c} variable.
Merge fields can also be used in certain setup texts. At this point, however, the complete placeholders are entered in curly brackets:
Admin Setting | Corresponding Setup-Text | Example |
|---|---|---|
Format of quote name in Salesforce | quotesavename | {QuoteNumber} - {AccountOpp_Name} {QuoteDate} |
Format of quote PDF file name | quoteattachementname | Angebot {QuoteName} |
Configuration
The Mergefields-Sidebar shows you all existing variables in correct formatting. The following sections serve for a better understanding and overview, which variables are standard and which have to be stored additionally in the setup. It is no longer necessary with version Summer '20 to write the variables manually into the quote.
Mergefields related to Quote
Standard Quote Mergefields
The following placeholders can be used directly in the quote editor. It is important that they are written in curly brackets:
Mergefield | referenced value / Salesforce field | Special feature |
|---|---|---|
{QuoteSumNet} | SF42_QuoteSum_Netto__c | Will only be read out in PDF. |
{QuoteName} | Name | |
{QuoteNumber} | SF42_QuoNumber__c | |
{QuoteDate} | SF42_QuoDate__c | |
{OrderDate} | SF42_QuoDate__c | |
{ValidDate} | SF42_QuoValidThruDate__c | |
{QuoteVersion} | SF42_QuoVersion__c | |
{VAT} | SF42_Tax_Quote__c | |
{QuoteSumVat} | SF42_QuoSum_Vat__c | Will only be read out in PDF. |
{QuoteSumGross} | SF42_QuoSum_Brutto__c | Will only be read out in PDF. |
{RelatedQuoteNumber} | SF42_relatedQuote__r.SF42_QuoNumber__c | |
{RelatedQuoteName} | SF42_relatedQuote__r.Name | |
{AcceptedQuoteNumber} | s. Auftragsbestätigung | |
{AcceptedQuoteName} | s. Auftragsbestätigung |
Custom Quote Mergefields
For custom mergefields, you can simply use the API name of the desired quote field enclosed in curly brackets, as long as it is stored in the associated setup text quoteFields.
Mergefields related to Account
In the case of mergefields for Accounts, the first thing to do is to distinguish between the different accounts involved in the quote (see section "Multi-level sales")
| Opportunity Account | Primary Account | Account 2 | Account 3 | Account 4 |
|---|---|---|---|---|---|
Object / Field in Salesforce | SF42_QuoAccount__c | SF42_QuoActiveAccount__c | SF42_QuoAccount2__c | SF42_QuoAccount3__c | SF42_QuoAccount4__c |
Definition | Standard | Primary Account for the respective quote | The label for Account 2 is set in the Account2 setup parameter, e.g. Reseller. | The label for Account 3 is set in the Account3 setup parameter, e.g. Distributor. | The label for account 4 is set in the Account4 setup parameter, e.g. Enduser. |
Prefix for Standard Mergefields | AccountOpp_ | active. | (setup-text account2)_ | (setup-text account3)_ | (setup-text account4)_ |
Standard Account Mergefields
The Standard Account Mergefields are appended to the respective account prefix with underscore (exception 'Primary Account: with dot). The following merge fields are available:
Mergefield | referenced value / Salesforce field | Example Opportunity Account | Example Primary Account | Example | Example | Example |
|---|---|---|---|---|---|---|
_Name | Account.Name | {AccountOpp_Name} | {active.Name} {Account} | {reseller_Name} | {distributor_Name} | {enduser_Name} |
_Street | Account.BillingStreet | {Street} | ||||
_Zip | Account.BillingPostalCode | {Zip} | ||||
_City | Account.BillingCity | {City} | ||||
_State | Account.BillingState | {State} | ||||
_Country | Account.BillingCountry | {Country} | ||||
_Payment | Account.SF42_Zahlungsbedingungen__c | {active.payment} | ||||
_Website | Account.Website | |||||
_Type | Account.Type | |||||
_Owner | Account.Owner.Name | |||||
_ShippingStreet | Account.ShippingStreet | |||||
_ShippingZip | Account.ShippingPostalCode | |||||
_ShippingCity | Account.ShippingCity | |||||
_ShippingCountry | Account.ShippingCountry | |||||
_ShippingState | Account.ShippingState |
Custom Account Mergefields
For Custom Account Mergefields, the API name of the referenced field is first stored in the associated setup text accountsFields. Then it is added to the respective account prefix separated by a dot:
| Opportunity Account | Primary account for the respective quote | Account 2 | Account 3 | Account 4 |
|---|---|---|---|---|---|
Object / Field in Salesforce | SF42_QuoAccount__c | SF42_QuoActiveAccount__c | SF42_QuoAccount2__c | SF42_QuoAccount3__c | SF42_QuoAccount4__c |
Prefix for Custom Mergefield | AccountOpp. | active. | (setup-text account2). | (setup-text account3). | (setup-text account4). |
Systematics | AccountOpp.ApiFieldname | active.ApiFieldname | setup-text account2.ApiFieldname | setup-text account3.ApiFieldname | setup-text account4.ApiFieldname |
Example Custom Mergefield using the "Industry" field as an example | {AccountOpp.Industry} | {active.Industry} | {reseller.Industry} | {distributor.Industry} | {enduser.Industry} |
Mergefields related to Contact
In the case of mergefields to the contact, it is also important to distinguish between the different accounts involved in the quote and their contacts (see section "Multi-level sales").
Contact Opportunity Account | Contact on primary account | Contact Account 2 | Contact Account 3 | Contact Account 4 | |
|---|---|---|---|---|---|
Object / Field in Salesforce | SF42_QuoContact__c | - | SF42_QuoContact2__c | SF42_QuoContact3__c | SF42_QuoContact4__c |
Definition | Standard | Associated contact of the primary account for the given quote. | The label is set in the Account2 setup parameter, e.g. Reseller. | The label is set in the Account3 setup parameter, e.g. Distributor. | The label is set in the Account4 setup parameter, e.g. Enduser. |
Prefix for Standard Mergefields | AccountOpp_Contact_ | active.Contact. | (setup-text account2)_Contact_ | (setup-text account3)_Contact_ | (setup-text account4)_Contact_ |
Standard Contact Mergefields
The default Contact Mergefields are appended to the respective Contact prefix with underscore (exception 'Primary Account: with dot). The following mergefields are available:
Mergefield | associated field name on the object | Example Contact Opportunity Account | Example Contact on primary account | Example | Example | Example |
|---|---|---|---|---|---|---|
_Contact_Name | Name | {AccountOpp_Contact_Name} | {active.Contact.Name} | {reseller_Contact_Name} | {distributor_Contact_Name} | {enduser_Contact_Name} |
_Contact_FirstName | FirstName | {FirstName} | ||||
_Contact_LastName | LastName | {LastName} | ||||
_Contact_Salutation | Salutation | |||||
_Contact_LetterSalutation | SF42_Letter_Salutation__c | |||||
_Contact_Email | ||||||
_Contact_Phone | Phone | |||||
_Contact_Fax | Fax | |||||
_Contact_Mobile | MobilePhone | |||||
_Contact_Street | Street | |||||
_Contact_Zip | PostalCode | |||||
_Contact_City | City | |||||
_Contact_Additional1 | SF42_Additional_Info_1__c | |||||
_Contact_Additional2 | SF42_Additional_Info_2__c | |||||
_Contact_Additional3 | SF42_Additional_Info_3__c | |||||
_Contact_Owner | Owner.Name |
Custom Contact Mergefields
For Custom Contact Mergefields, the API name of the referenced field is first stored in the corresponding setup text contactFields. Then it is added to the respective contact prefix separated by a dot:
Contact at Opportunity Account | Contact on active account | Contact Account 2 | Contact Account 3 | Contact Account 4 | |
|---|---|---|---|---|---|
Object / Field in Salesforce | SF42_QuoContact__c | <-> | SF42_QuoContact2__c | SF42_QuoContact3__c | SF42_QuoContact4__c |
Prefix for Custom Mergefield | AccountOpp.Contact. Opp.Contact. | active.Contact. | (setup-text account2).Contact. | (setup-text account2).Contact. | (setup-text account4)Contact. |
Systematics | AccountOpp.Contact.ApiFieldname Opp.Contact.ApiFieldName | Active.Contact.ApiFieldname | (setup-text account2).Contact.ApiFieldname | (setup-text account3).Contact.ApiFieldname | (setup-text account4).Contact.ApiFieldname |
Custom Mergefield example using the "Department" example | {AccountOpp.Contact.Department} {Opp.Contact.Department} | {Active.Contact.Department} | {reseller.Contact.Department} | {distributor.Contact.Department} | {enduser.Contact.Department} |
Mergefields related to User
Similar to Account, Mergefields that refer to Salesforce Users have different reference options and corresponding prefixes for the Mergefields.
User | Account Owner | Opportunity Owner | Manager Opp Owner | Quote Owner | Manager Quote Owner | |
|---|---|---|---|---|---|---|
Object / Field in Salesforce | User | SF42_QuoAccount__r.Owner | SF42_QuoOpportunity__r.Owner | SF42_QuoOpportunity__r.Owner.Manager | .Owner | .Owner.Manager |
Definition | Standard | Opportunity Account Owner | Opportunity Owner | Manager Opp Owner | Quote Owner | Manager Quote Owner |
Prefix for Standard Mergefields | User_ | AccountOpp_Owner_ | Opp_Owner_ | Opp_Manager_ | Quote_Owner_ | Quote_Manager_ |
Standard User Mergefields
The Standard User Mergefields are appended to the respective Contact prefix with underscore. The following placeholders are available:
Mergefield | associated field name on the object | Example User | Example Account Owner | Example Opportunity Owner | Example Opportunity Owner Manager | Example Quote Owner | Example Quote Owner Manager |
|---|---|---|---|---|---|---|---|
_Name | Name | {User_Name} | {AccountOpp_Owner_Name} | {Opp_Owner_Name} | {Opp_Manager_Name} | {Quote_Owner_Name} | {Quote_Manager_Name} |
_FirstName | FirstName | ||||||
_LastName | LastName | ||||||
_Alias | Alias | ||||||
_Title | Title | ||||||
_JobTitle | Title | ||||||
_Email | |||||||
_Phone | Phone | ||||||
_Fax | Fax | ||||||
_MobilePhone | MobilePhone | ||||||
_Mobile | MobilePhone | ||||||
_CompanyName | CompanyName | ||||||
_Company | CompanyName | ||||||
_Street | Street | ||||||
_PostalCode | PostalCode | ||||||
_Zip | PostalCode | ||||||
_City | City | ||||||
_Department | Department | ||||||
_Division | Division |
Custom User Mergefields
Custom Mergefields related to the user can only be created for two types: the user itself and the opportunity owner.
For Custom User Mergefields, first the API name of the referenced field is stored in the corresponding setup text userFields. Then it is added to the respective contact prefix separated by a dot:
User | Opportunity Owner | |
|---|---|---|
Object / Field in Salesforce | User | SF42_QuoOpportunity__r.Owner |
Prefix for Custom Mergefield | - | OppOwner. |
Systematics | API Feldname ohne Prefix | OppOwner.ApiFieldname |
Example Custom Mergefield | {SF42_UserDegree__c} | {OppOwner.SF42_UserDegree__c} |
Mergefields related to Opportunity
Standard Opportunity Mergefields
There is only one Standard Mergefield for Opportunity fields:
Mergefield | associated field name at Opportunity |
|---|---|
{Opp_Name} | Name |
Custom Opportunity Mergefields
For Custom Mergefields simply the API name of the referenced field can be used, provided it is stored in the associated setup text opportunityFields. Then the placeholder in curly brackets can be used in the quote.
Mergefields related to Product
Mergefields at product level are a special feature. They read column values of a Quote Line Item and can be used in the product description. Understandably, product variables are only effective within a data record.
Spaltenname | Name of the Variable | Feldtyp |
|---|---|---|
BuyPriceDist | {BuyPriceDist} | Currency |
BuyPricePartner | {BuyPricePartner} | Currency |
Description | {Description} | Text |
Discount | {Discount} | Percent |
Discount2 | {Discount2} | Percent |
Discount3 | {Discount3} | Percent |
Discount4 | {Discount4} | Percent |
DiscountDist | {DiscountDist} | Percent |
DiscountPartner | {DiscountPartner} | Percent |
Endprice | {Endprice, Unitprice} | Currency |
Listprice | {Listprice} | Currency |
Position | {Position} | Text |
Productcode | {Productcode} | Text |
Quantity | {Quantity} | Zahl |
QuantityMultiplier | {QuantityMultiplier} | Zahl |
QuantityUnitOfMeasure | {QuantityUnitOfMeasure} | Text |
ServiceDate | {ServiceDate} | Datum |
SpecialDiscount | {SpecialDiscount} | Percent |
SpecialDiscountDist | {SpecialDiscountDist} | Percent |
SpecialDiscountPartner | {SpecialDiscountPartner} | Percent |
SumListprice | {SumListprice} | Currency |
Sumprice | {Sumprice}, {Sum} | Currency |
SumPriceDist | {SumPriceDist}, {SumDist} | Currency |
SumPricePartner | {SumPricePartner}, {SumPartner} | Currency |
Tax | {Tax} | Percent |
Special feature: variables from formula fields
Normally, only limited mergefields can be generated from formula fields, because their contents, e.g. if they are fields on the quote itself, are generated only when the quote is saved.
Alternatively, you can manually set up the setup text saveTwiceForFormulaMergefields of type parameter and assign value true to the field "Longtext" sf42_quotefx__SF42_QuoSetup_Longtext__c.
The correct behavior is then as follows: When the editor is initially opened, variables that have no values on the template will initially remain empty; fields that have a value from the template will be copied with it. The first saving of a new quote in the editor is then triggered twice. Mergefields based on calculation fields from the quote will be resolved correctly in the editor and PDF afterwards.
Mergefields and translations
If the uniform picklists for state and country are enabled in the Salesforce setup (→ 'Enable Country & State Picklists') and translations are available for these values, the translations are output for the corresponding merge fields depending on the language setting. This also applies to the other merge fields set up by default.
Custom merge fields that refer to picklist fields will display existing translations if the corresponding field is marked with 'toLabel' in the associated setup text, e.g.
accountFields → Text module: toLabel(Industry)
Unless the field is a picklist, using toLabel will generate an error message.