💡First: See this article for a list of all the methods you can use to update or relate to existing Salesforce data with forms.
The Upsert feature allows you to specify that a form submission should update an existing record in Salesforce if it exists already; otherwise create new records.
When to Use Upsert
Upsert is best used with blank forms on a public website. Your end-users will find this form by browsing, on a search engine or another non-personalized or non-solicited mechanism.
Upsert is particularly useful if you do not want to expose any Salesforce data on the form but still want to update data on an existing Salesforce record.
How to Use Upsert
In the form editor - under the field settings of each Salesforce field - is an upsert setting that when enabled will mark this field as being considered in the upsert criteria. To mark a field as an Upsert field, simply check the box labeled 'Update existing Salesforce record matching this field value' in the field's settings area.
For fields that have this option enabled, we will check your org upon form submission for existing records that match the value provided in all of those fields. If a match is found, we will update the record with the information submitted in the form. Otherwise, we will create a new record.
Upsert Field Considerations
There are a number of important factors to consider when deciding to use Upsert functionality for your forms:
- We will only update existing records if exactly one (1) match is found. If no matching records are found, we will create a new record. However, if multiple matching records are found, the form submission will fail, and no records will be created or updated.
- When you enable upsert for more than one field for an object, all of the fields will be considered when looking for an existing record. For example, if you check 'Update existing Salesforce record matching this field value' for First Name and Last Name, only records that match both the first name and last name of the form submission will be updated.
- Each of your form's primary and related objects has100 its own upsert fields. For each object, only the fields marked as upsert fields for that object will be considered when looking for a matching existing record. For example, it’s possible that a form with 2 objects and Upsert configured on fields of both of these objects, we can create 1 new record and upsert to another record. That is to say that upsert matching works on a per-object basis and is independent between objects.
Duplicate and Matching Rules
Since Upsert is typically used to avoid duplicate records it is important to talk about how Salesforce handles duplicate management.
Salesforce Duplicate and Matching Rules are designed for real-time duplicate matching. Logged in users can see messages indicating duplicate matches have been found and can thus alter behaviour - by updating the matching record instead or changing submission details to create a non-matching record. This bi-directional interaction is not available to applications that use the API. As a result, it is important to be aware of how your org has configured duplicate and matching rules.
By default, Salesforce will configure duplicate matching to block submissions that match on a set of standard fields. If you experience submission errors due to duplicates being blocked you and this is not desired behaviour then we recommend two options.
- Permit duplicates to be created. Do not block duplicates from being created by default. This means to avoid duplicates you can use features like Upsert in our forms product. You can also consider using a duplicate management software like OpenRise or LeanData.
- Custom Matching Rules: Block duplicates from being created but define custom matching rules that match on a narrower set of fields that are more common for use within Salesforce UI but allow you to not block form submissions.