Working with Related Entities
Related entities in Dynamics define a relationships between one or more entities such as the Contact-to-Account relationship, the Lead-to-SourceCampaign relationship, the Lead-to-MarketingList relationship, etc.
Setting up relationships between entities like this is fully supported by the plugin. Starting in version 1.10.0, the plugin includes a Dynamics Lookup Field feature that makes this much easier by automatically populating form dropdowns with records from Dynamics 365 — no more manually looking up and pasting GUIDs.
This article covers both approaches:
- Using the Dynamics Lookup Field (recommended, v1.10.0+) — automatically populates a dropdown with records from Dynamics
Using the Dynamics Lookup Field (Recommended)
Starting in version 1.10.0, you can populate any Gravity Forms dropdown directly with records from Dynamics 365. This is the easiest way to set up entity relationships — the form submitter selects a record by name, and the plugin handles the GUID and relationship binding automatically.
For the purpose of this walkthrough, we are going to map the Source Campaign field for the Lead entity in Dynamics. The process is the same regardless of the related entity field you wish to map.
- In your Gravity Forms form editor, add a Drop Down field to your form.
You can name it anything you like — for our example, we'll name it "Source Campaign." - With the Drop Down field selected, check the "Populate from Dynamics" checkbox in the field settings panel.
- From the Populate Mode dropdown that appears, select "Lookup (Records)."
- Select the Entity Type that contains the lookup relationship. In our example, we select "lead" since the Source Campaign field is on the Lead entity.
- Select the Lookup Attribute from the dropdown. In our example, we select "CampaignId" (the Source Campaign lookup field). The plugin will show all Lookup-type attributes for the selected entity.
- The field's choices will automatically populate with active records from the target entity (in this case, active Campaigns from Dynamics 365). The Campaign name is shown as the choice label, and the Campaign's GUID is stored as the choice value.
- Optionally, check "Keep in Sync with Dynamics" to automatically refresh the choices each time the form is loaded. When enabled, choices are cached for performance (default: 1 hour, configurable in plugin settings under Lookup Cache Duration).
- Click Update on your form to save the changes.
- Navigate to your form's feed mapping for Dynamics by choosing Settings > Dynamics CRM from the menu at the top of your form.
- Under the Map Fields section, add a new field to your mapping and choose "Source Campaign (CampaignId)" under the Dynamics CRM Field column and map it to your new "Source Campaign" Drop Down field.
- Click the Update Settings button at the bottom of the screen to save your Dynamics feed settings.
- Now, any new form entries will create a lead linked to whichever Campaign the form submitter selected from the dropdown. The plugin automatically formats the correct OData relationship binding — no GUID handling needed.
Note: A maximum of 250 active records are shown in the dropdown, ordered alphabetically by display name. You can adjust the cache duration in Forms > Settings > Dynamics CRM > Lookup Cache Duration (seconds). Setting the value to 0 disables caching. Clicking "Refresh Metadata" in the plugin settings also clears all lookup caches.
Using a Hidden Field with a GUID (Manual Approach)
If you are using a version prior to 1.10.0, or if you want to statically map all form entries to the same related entity record (rather than letting the user choose), you can use the manual hidden field approach.
For the purpose of this walkthrough, we are going to walk through mapping the Source Campaign field for the Lead entity in Dynamics. The process is the same regardless of the related entity field you wish to map.
- The first thing we need to know in order to establish a relationship between two entities is the ID of the related entity.
- We're going to use a helpful open-source Google Chrome extension called Dynamics 365 Power Pane in order to make this process easier. You can install the Chrome extension here.
- Next, if you have not already done so, login to your Dynamics instance.
- Once logged-in, navigate to the Marketing > Campaigns list.
- Next, click on the target campaign. In our example, we want all leads coming from a specific form on our site to be mapped to the "Website Leads" marketing campaign, so we'll click on that record.
- On the campaign detail screen, this is where we are going to leverage our newly installed Chrome extension. Notice, the lightning bolt icon in the top left corner. This is added by the Power Pane extension. Click the lightning bolt to bring up the power pane menu and then click the Record Id menu item.
- This will open a Record id dialog box (show below). In the dialog box, click the "Copy it!" link shown below the record id. Finally, click the OK button to close the dialog.
- With the record id copied, we can now go back to WordPress and place a hidden field on our form called Source Campaign.
- On the Advanced tab for our hidden field, we'll paste the record id we copied to our clipboard in the Default Value box for our field:
- Next, we'll click Update on our form to save the changes.
- Finally, we'll navigate to our form's feed mapping for Dynamics by choosing Settings > Dynamics CRM from the menu at the top of our form.
- On that screen, under the Map Fields section, we'll add a new field to our mapping and choose "Source Campaign (CampaignId)" under the Dynamics CRM Field column and map it to our new "Source Campaign" hidden field we added to our form.
- Finally, we'll click the Update Settings button at the bottom of that screen so save our Dynamics feed settings.
- Now, any new form entries will create a lead with a Source Campaign of "Website Leads."
The steps above are the same regardless of the entity relationship you wish to create. This can be used for associating a lead or contact with a Marketing list based on the form they fill out or any other type of relationship between entities in Dynamics.
Using the power of the Gravity Forms Dynamics CRM Add-On and entity relationship fields you can achieve fine-grained control over your WordPress to Dynamics 365 integration.