In order to send data to Microsoft Dynamics, you can use the Sitecore Connect for Dynamics Connector (which sits on top of the Data Exchange Framework).
Installation
In order to sync the data from Sitecore to Dynamics, you need to first of all install two modules:
- Data Exchange Framework (DEF) - V8.0.0.0 is compatible with XP 10.3
Data Exchange Framework 8.0.0 | Downloads | Sitecore Developer Portal - Sitecore Connect™ for Microsoft Dynamics 365 for Sales = v8.0.0.0 is compatible with XP 10.3
Sitecore Connect™ for Microsoft Dynamics 365 for Sales 8.0.0 | Downloads | Sitecore Developer Portal
Note: The connector sits on top of DEF, so must be installed after DEF.
Local Setup
- The DEF setup guide (may) be useful.. but it also introduces things we dont need:
Configuring Data Exchange Framework - Try instead to just use the Sitecore to Dynamics guide:
Configuring Sitecore Connect for Microsoft Dynamics 365 for Sales
Note: before creating a tenant - see Tenant Items below
Global Items
The modules install a range of sitecore items in the following locations:
- /sitecore/system/Data Exchange [MASTER]
- /sitecore/system/Settings/Data Exchange [MASTER]
- /sitecore/templates/Data Exchange [MASTER]
- /sitecore/content/Applications/Data Exchange [CORE]
- /sitecore/content/Applications/Data Exchange Framework SDK [CORE]
Tenant Items
When configuring the Sitecore to Dynamic connector, you are asked to create a new ‘tenant’. This uses a branch template to create 100’s of new items under the Data Exchange node in ‘sitecore/system'. If we did this in each environment, then items with the same path in each environment would have different IDs and fail any attempts to serialise.
It is important that every environment has the exact same version of these items. Therefore, package up the created tenant and install it across environments (on top of the module install). Then serialise only those areas of the content tree that are likely to have customisations added. This avoids having to serialise the full tenant, which has lots of redundant data.
Setting up the pipelines
When installed, you are provided with a number of OTB pipelines, one of which syncs Contacts from XConnect to Dynamics. This pipeline only syncs the OTB Sitecore Facets, like Personal Details, Emails, Addresses etc. Customise this pipeline to map any additional fields from the new XConnect model to the Dynamics Contact model. Then map any 'Leads' (form submissions) from our custom facet, to new Inbound Interest entities.
As a recap the Read Contacts from xConnect Pipeline, does the following:
- Sets up the Dynamics Context
- Sets up the xConnect Context
- Reads all Contacts from xConnect and places them in the Pipeline Context Iterable Data location.
Note: we need to add our custom facet in the Contact Facets To Read field to have access to our new data. - Iterates through the xConnect data, places each Contact into the Pipeline Context Source location and runs each of the listed pipelines.
We need to create a Process Single Contact To Get Leads pipeline and add it to the list of pipelines called in step #4 above. That pipeline will do the following does the following:
- Resolve the Dynamics Contact (see issues syncing) using Pipeline Context Source and place it in Pipeline Context Target
- Use an xConnect Entity Facet List Property Value Accessor to read the Contact object from the Pipeline Context Source location (where #4 of previous pipeline placed the data), extract a collection of Lead objects from the Custom Facet. Then store them in the Pipeline Context Iterable Data location (for use in next iterating pipeline).
- Map XConnect Contact Model (from Pipeline Context Source) to Dynamics Model (Pipeline Context Target) - using a Mapping Set
- Map Dynamics Contact to XConnect (i.e. back fill Dynamics ID) and add xConnect Batch
- Add Dynamics Contact to the Queue
- Iterate through the collection of Leads (from Pipeline Context Iterable Data - step #2) and place each Lead into the Pipeline Context Source location and run the Process Single Lead pipeline.
We need to create a Process Single Lead pipeline that does the following:
- This step starts by retrieving the LeadId (a unique identifier) from the Lead object located in the Pipeline Context Source. It uses a Property Value Accessor named LeadId to extract the value. This GUID is then used to call Dynamics and attempt to resolve the entity, if it exists.
If the Lead entity exists, the system maps each property defined in the Entity Value Accessor Set named Dynamics Lead. If the Lead entity doesn't exist, a new one is created.
This Lead entity is then stored in the Pipeline Context Target location, where it is available to subsequent pipeline steps. - This step maps the contact Id from the parent Contact Entity (Stored in Pipeline Context Parent Target) to the Lead Entity (in Pipeline Context Target)
Note: In this step 'Pipeline Context Parent Target' refers to the 'Pipeline Context Target' from the previous pipeline. Which in this case is used to store the Dynamics Contact Entity. - This step maps data between the source object—the Lead (from the xConnect facet, stored in the Pipeline Context Source)—and the target object—the Lead Entity (from Dynamics, stored in the Pipeline Context Target).
The mapping is handled using a Value Mapping Set, which contains a collection of value mappings. Each mapping includes a Source Accessor and a Target Accessor, both of which reference a Property Value Accessor. These accessors identify either a property on the Lead object or an attribute on the Dynamics Lead entity. - The final step read the updated Lead Entity from the Pipeline Context Target and adds it to the batch of actions (Update/Create/Delete) that will be sent to Dynamics. This submit action is performed in the last step of the top-level Read Contacts from xConnect Pipeline.
Key Take Away
When setting these pipelines up, its really important to note where each step reads information from and where it copies it too. Each step effectively handles some data and passes it on to the next one. The way it passes it between them is to define the copy too and copy from locations.
Pipeline Details
Whilst it is hard to provide every bit of detail, below outlines the key steps and templates used. These steps will refer to Value Mapping Sets and Accessors that will be unique to your setup.
Note: If you are unsure exactly what mapping set or accessor to use, look at the example ones provided below - navigate to the same area of your content tree and replicate something similar to what has been defined already in that location.
Read Contacts from xConnect Pipeline
This pipeline remains mainly untouched, apart form adding the new facet to the 'read contacts' step. Then adding the new pipeline (below) to the iterate step.
Process Single Contact To Get Leads
[/sitecore/templates/Data Exchange/Framework/Pipelines/Pipeline]
- Resolve Dynamics Contact by Identifier
[custom (see issues): Extended Resolve Dynamics Entity By Identifier Pipeline Step]
[Attributes to Read:] Dynamics Contact
[Identifier Value Accessor:] Data Access/Value Accessor Sets/Providers/xConnect/xConnect Contact/Dynamics Contact Id on xConnect Contact
[EmailValueAccessor:] /Value Mapping Sets/Dynamics Contact to Lead Mappings/Contact Entity to Lead Entity/ContactId - Read Leads from Contact
[Copy Object from Context to New Location Pipeline Step]
[Source Object Value Accessor:] Data Access/Value Accessors/Providers/xConnect/xConnect Entity Facet List Property Value Accessor – Lead - Apply Mapping from Contact Model to Dynamics Contact
[Apply Mapping Pipeline Step]
[MappingSet:] Value Mapping Sets/xConnect Contact to Dynamics Contact Mappings/Contact Model to Dynamics Contact - Apply Mapping from Dynamics Contact to Contact Model
[Apply Mapping Pipeline Step]
[MappingSet:] Value Mapping Sets/xConnect Contact to Dynamics Contact Mappings/Dynamics Contact to Contact Model - Add Contact Model to xConnect Batch
[Add Entity to xConnect Batch Pipeline Step] - Add Dynamics Contact to Queue
[Add Entity to Queue Pipeline Step] - Iterate Leads and Run Pipelines
[Iterate Data and Run Pipelines Pipeline Step]
[Selected:] Process Single Lead
Process Single Lead
[/sitecore/templates/Data Exchange/Framework/Pipelines/Pipeline]
- Resolve Dynamics Lead
[Resolve Dynamics Lead]
[Entity Name:] Lead
[Attributes to Read:]
Data Access/Value Accessor Sets/Providers/Dynamics/Dynamics Lead
[Identifier Value Accessor:]
Data Access/Value Accessor Sets/Providers/xConnect/XConnect Contact Marketing Lead Accessor Set/LeadId
[Value Reader to Convert Identifier Value for Comparison:]
Data Access/Value Readers/Common/Guid As String Value Reader - Apply Mapping ContactId From Parent To Lead
[Apply Mapping Pipeline Step]
[MappingSet:] Value Mapping Sets/Dynamics Contact to Lead Mappings/Contact Entity to Lead Entity - Apply Mapping Pipeline Step
[Apply Mapping Pipeline Step]
[MappingSet:] Value Mapping Sets/xConnect Contact to Dynamics Contact Mappings/Lead Mapping Set 2 - Add Dynamics Lead to Queue
[Add Entity to Queue Pipeline Step]