How to add custom parameters and fields to Salesforce using convention based field mapping
The RaiseNow Salesforce integration supports convention based mappings of custom fields and parameters for objects addressed in the current process of transferring data to Salesforce. Simply put, if formulated correctly you may add fields and parameters to the widget on your website and have their data automatically passed on to Salesforce. There are a few things to keep in mind however:
- It is your responsibility to make sure the custom fields and parameters are formulated according to the conventions stated below and that the corresponding fields exist in Salesforce. If RaiseNow is not able to automatically identify the field in Salesforce due to a misspelled field name, the field will be ignored when passing the transaction data to Salesforce.
- Note further, that if a custom field has an invalid value (e.g. references a wrong campaign id or provides an invalid date format) then the transaction will not be transferred to Salesforce.
- In addition, only fields marked as being undateable in Salesforce can be written to. If you attempt to write to a write protected field, the transaction will not be transferred to Salesforce.
- Custom fields and parameters can only be written to fields on objects that are addressed in the current transfer process. This means the following Salesforce objects can be addressed:
- one-off donation:
- recurring donation
- one-off donation:
The naming convention that must be enforced is as follows:
- stored_sf is required by RaiseNow and designates a field to be stored for the salesforce integration
- RaiseNow uses one underscore as a convention for field names, where Salesforce object and field names use two underscores as a convention for field and object names. Do not get these mixed up and do not use underscores in your API field names within Salesforce as this will throw off the automatic mapping algorithm.
The following example code will do the following
- Setup two custom parameters for the object npe01Payment__c and the Contact object. Both specify a field Source__c on the respective object in Salesforce that should contain the string 'hosted-page'
- Create a custom field in order to query for the Contacts institution in the donation process. The field definition designates a field 'Institution__c' on the Contact object.
Assuming that you have initialised your widget in a HTML class '.root' the code to implement these parameters and fields would be:
// use the widget in the HTML tag marked with the attribute class="root"
// prefill the custom fields for Salesforce
How to hide the purpose selector and set campaign identifiers as a hidden parameter
You may want to integrate the Tamaro widget on a dedicated landing page promoting a single purpose/campaign. In this scenario the promotion of your campaign is done via the standard functions in the CMS of your choice. However, Tamaro must still be used for the donation checkout and the promoted campaign must be set as a transaction parameter to address the correct campaign within Salesforce.
Important: If the purpose is not hidden using the snippet provided below, please create a ticket via firstname.lastname@example.org. RaiseNow may need to apply a configuration option to your widget to unlock this feature.
Note: By defining the parameter "stored_campaign_id" within the paymentFormPrefill object you retain the possibility to overwrite this passing a new stored_campaign_id as a query string. For example: https://showcases.prod.rnw.io/salesforce-demo/tamaro-hide-purose.html?rnw-stored_campaign_id=1234567980