We recently wrote a data loader for a client which needed to load multiple contacts against an opportunity. The most logical way to do this was to utilize the Stakeholder grid on the opportunity. The underlying structure behind this grid uses connections with a connection role category of ‘Stakeholder’. Out of the box this category allows for the following roles:
- Champion
- Decision
- End User
- Economic Buyer
- Stakeholder
- Influencer
- Technical Buyer
We are using the ‘Stakeholder’ role for the example within this article.
Using connections enables us to use a many to many relationship (N:N) to satisfy the requirement without the need for modifications.
How to create a new connection via the SDK?
The variables we need to create a new opportunity stakeholder connection are:
- Opportunity ID (guid)
- Contact ID (guid)
- Connection Role ID (guid)
The Connection Role ID is easy to find and in this case as we are specifically after the “Stakeholder” role. Out of the box there is only one and this can be found by using the query below:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
QueryExpression oQuery = new QueryExpression("connectionrole"); oQuery.ColumnSet.AddColumns("connectionroleid"); oQuery.Criteria = new FilterExpression(); oQuery.Criteria.AddCondition("name", ConditionOperator.Equal, "Stakeholder"); EntityCollection oResults = oServiceProxy.RetrieveMultiple(oQuery); foreach (Entity oConnRole in oResults.Entities) { Return oConnRole.Id.ToString(); } |
The other two (contact and opportunity ID) are fairly self explanatory.
I tend to store my IDs as strings within code and convert them when I need to used them. It’s just a habit.
Use the following code to create the new stakeholder connection:
|
1 2 3 4 5 6 7 8 |
Entity oConnection = new Entity("connection"); oConnection["record1id"] = new EntityReference("contact", new Guid(sContactID)); oConnection["record2id"] = new EntityReference("opportunity", new Guid(sOpportunityID)); oConnection["record1roleid"] = new EntityReference("connectionrole", new Guid(sStakeholderRoleID)); oConnection["description"] = "Stakeholder"; oServiceProxy.Create(connection); |
I do add a description of Stakeholder in the above code so that from a contact connection grid point of view, it’s clear what the role is. Alternatively you can create a new role or update the Stakeholder role to work in reverse and update the record2roleid field with this role by adding the following line to the code:
|
1 2 |
oConnection["record2roleid"] = new EntityReference("connectionrole", new Guid(sConnectionRole2ID)); |
Gotchas with connections
Because a Dynamics 365 connection creates a many to many relationship with a “connection” entity in the middle (i.e. between the opportunity and contact) we can have multiple connections to and from the same opportunity and contact, and therefore create duplicate stakeholders on the one opportunity.
If this were a straight native N:N relationship (i.e. no connection entity in the middle) we would hit a key error trying to save an identical relationship.
To get around this, check to see if the connection between the two records already exists.
Checking to see if the connection already exists
Use the following Dynamics 365 SDK QueryExpression to check if the connection between the opportunity and contact record already exists. It uses both the Contact ID (guid) and Opportunity ID (guid).
The result will either return a connection ID (guid) or a blank string. If it’s blank it does not exist.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
ColumnSet oColumnSet = new ColumnSet("connectionid"); ConditionExpression oConditionContactId = new ConditionExpression(); oConditionContactId.AttributeName = "record1id"; oConditionContactId.Operator = ConditionOperator.Equal; oConditionContactId.Values.Add(sContactID); ConditionExpression oConditionOppID = new ConditionExpression(); oConditionOppID.AttributeName = "record2id"; oConditionOppID.Operator = ConditionOperator.Equal; oConditionOppID.Values.Add(sOppId); FilterExpression oFilter = new FilterExpression(); oFilter.FilterOperator = LogicalOperator.And; oFilter.AddCondition(oConditionContactId); oFilter.AddCondition(oConditionOppID); QueryExpression oEntityQuery = new QueryExpression("connection"); oEntityQuery.ColumnSet = oColumnSet; oEntityQuery.Criteria = oFilter; EntityCollection oConnectionRecords = oServiceProxy.RetrieveMultiple(oEntityQuery); //Loop through the results: foreach (Entity oConnection in oConnectionRecords.Entities) { if (oConnection.Id != Guid.Empty) { return oConnection.Id.ToString(); } } return ""; |
Feel free to comment if you have any issues or questions.
