CRM 4.0 Relationships Explained

Relationships in CRM 4.0 are quite powerful but hard to understand at first. There are so many moving parts tied to so many places that it is sometimes difficult to predict what the actual outcome is. So here is my attempt to explain a bit further what the relationships enhancements were in CRM 4.0. To start with let’s explain with a diagram what relationship types are available. Note that to determine the actual feasibility of a relationship (e.g. it may be the case that a specific relationship is not possible between an entity pair) you can use our APIs described here.

Relationships CRM 4.0

As you can see, the above gives you an enormous amount of flexibility on the types of relationships that you can model in CRM 4.0. Now let’s take a look at specific CRM 4.0 enhancements.


We performed a huge redesign of relationships in our backend. The major architectural changes were that we introduced the notion of many-to-many relationships and self referential relationships. To enable many-to-many relationships we implement intersect entities under the covers. To enable self referential relationships we added a couple of checks to prevent circular parental references and we also redid portions of several system relationships that were hardcoded to be metadata driven to enable system to system and multiple relationships.


One of the biggest requests that we had for CRM 4 was to enable customization of the labels that get displayed as part of relationships; furthermore, sometimes relationship are only used as a logical construct for backend operations and aren’t meant to be displayed; hence the ability to “hide” portions of the UI related to relationships was also a requirement. To accomplish all the above we introduced several metadata attributes that control the display behaviors of relationships.

· This screencast walks you to the creation of a simple N:N relationship and describes how different pieces relate to the UI.


Of course we had to provide means for programmers to take advantage of all the niceties that we implemented so we had to introduce a couple of new message and attributes and make some changes in the way fetchXml process relationships. Details are on the SDK but here are a couple of quick examples.

Creating new relationships

Yep, you can create brand new relationships (metadata) programmatically using the metadata API. Here is an example on how to create a Many-to-Many relationship. The CrmUtils class is just a wrapper class that a colleague created to create a label for only one language, 1033-English in this case (as you know CRM 4.0 is Multi Language enabled).

public static void createManyToManyTest(MetadataService metadataService)


ManyToManyMetadata manyToMany = new ManyToManyMetadata();

manyToMany.SchemaName = "new_relationship_name";

manyToMany.IntersectEntityName = "new_intersect_name";

//Side A

manyToMany.Entity1LogicalName = "account";

manyToMany.Entity1AssociatedMenuBehavior = new CrmAssociatedMenuBehavior();

manyToMany.Entity1AssociatedMenuBehavior.Value = AssociatedMenuBehavior.UseLabel;

manyToMany.Entity1AssociatedMenuGroup = new CrmAssociatedMenuGroup();

manyToMany.Entity1AssociatedMenuGroup.Value = AssociatedMenuGroup.Details;

manyToMany.Entity1AssociatedMenuLabel = CrmUtils.CreateSingleLabel("SIDE A pointing to Side B", 1033);

manyToMany.Entity1AssociatedMenuOrder = new CrmNumber();

manyToMany.Entity1AssociatedMenuOrder.Value = 15001;

//Side B

manyToMany.Entity2LogicalName = "contact";

manyToMany.Entity2AssociatedMenuBehavior = new CrmAssociatedMenuBehavior();

manyToMany.Entity2AssociatedMenuBehavior.Value = AssociatedMenuBehavior.UseLabel;

manyToMany.Entity2AssociatedMenuGroup = new CrmAssociatedMenuGroup();

manyToMany.Entity2AssociatedMenuGroup.Value = AssociatedMenuGroup.Details;

manyToMany.Entity2AssociatedMenuLabel = CrmUtils.CreateSingleLabel("SIDE B pointing to Side A", 1033);

manyToMany.Entity2AssociatedMenuOrder = new CrmNumber();

manyToMany.Entity2AssociatedMenuOrder.Value = 15001;

CreateManyToManyRequest manyToManyRequest = new CreateManyToManyRequest();

manyToManyRequest.IntersectEntitySchemaName = manyToMany.IntersectEntityName;

manyToManyRequest.ManyToManyRelationship = manyToMany;



Adding/Removing records for a relationship

To add a new record to a many-to-many relationship you can use the following code. A similar code can be used to remove a record, just use DisassociateEntities message request/response instead of AssociateEntities.

Note that working with N:N relationships is slightly different than working with a One-to-many relationship (for the later you use SetRelated and RemoveRelated messages instead).

public static void addRelatedTest(TitanMiscTests.CrmSdk.CrmService service)


//Links (relates) an account record to a lead record in a manyToMany relationship

Moniker moniker1 = new Moniker();

moniker1.Name = "account";

moniker1.Id = new Guid("4BD77CC1-8D6B-DC11-B026-0017A41E8C1D");

Moniker moniker2 = new Moniker();

moniker2.Name = "lead";

moniker2.Id = new Guid("D1CAB380-C56B-DC11-B026-0017A41E8C1D");

AssociateEntitiesRequest request = new AssociateEntitiesRequest();

request.Moniker1 = moniker1;

request.Moniker2 = moniker2;

request.RelationshipName = "new_account_lead_custom";



Retrieving relationships

The following fetch will retrieve all the leads associated with account with name “Foo” in the custom relationship whose intersect entity is “new_account_lead_custom”.

public static void retrieveEntitiesViaFetch(TitanMiscTests.CrmSdk.CrmService service)


string linkFetch = @"<fetch version=""1.0"" output-format=""xml-platform"" mapping=""logical"" distinct=""true"">

<entity name=""lead"">

<attribute name=""fullname""/>

<order attribute=""fullname"" descending=""true""/>

<link-entity name=""new_account_lead_custom"" from=""leadid"" to=""leadid"" visible=""false"" intersect=""true"">

<link-entity name=""account"" from=""accountid"" to=""accountid"" alias=""aa"">

<filter type=""and"">

<condition attribute=""name"" operator=""eq"" value=""Foo""/>






string result = service.Fetch(linkFetch);



The same query can be accomplished using QueryExpression as follows, note how the query is constructed from bottom to top when compared with fetchXml.

public static void retrieveEntityListFromManyToMany(TitanMiscTests.CrmSdk.CrmService service)


//This code will retrieve a list of "leads" associated with the entity "Foo" on the relationship whose intersect entity is "new_account_lead_custom"

//Filter by the specific record that we are looking for

//(In this example we assume that there are no other accounts with the name Foo, otherwise

// if would be recommended to use the account "id" instead of the name.

ConditionExpression conditionName = new ConditionExpression();

conditionName.AttributeName = "name";

conditionName.Operator = ConditionOperator.Equal;

conditionName.Values = new object[1];

conditionName.Values[0] = "Foo";

FilterExpression selectByName = new FilterExpression();

selectByName.Conditions = new ConditionExpression[] { conditionName };

//Create nested link entity and apply filter criteria

LinkEntity nestedLinkEntity = new LinkEntity();

nestedLinkEntity.LinkToEntityName = "account";

nestedLinkEntity.LinkFromAttributeName = "accountid";

nestedLinkEntity.LinkToAttributeName = "accountid";

nestedLinkEntity.LinkCriteria = selectByName;

//Create the nested link entities

LinkEntity intersectEntity = new LinkEntity();

intersectEntity.LinkToEntityName = "new_account_lead_custom";

intersectEntity.LinkFromAttributeName = "leadid";

intersectEntity.LinkToAttributeName = "leadid";

intersectEntity.LinkEntities = new LinkEntity[] { nestedLinkEntity };

//Create Query expression and set the entity type to lead

QueryExpression expression = new QueryExpression();

expression.EntityName = "lead";

expression.LinkEntities = new LinkEntity[] { intersectEntity };

RetrieveMultipleRequest request = new RetrieveMultipleRequest();

request.Query = expression;

//Execute and examine the response

RetrieveMultipleResponse response = (RetrieveMultipleResponse)service.Execute(request);

BusinessEntity[] entities=response.BusinessEntityCollection.BusinessEntities;

Console.WriteLine("Total related=" + entities.Length);



Humberto Lezama

Comments (26)

  1. Josie Fleschute says:

    I was reading this post to add some clarity to something I was working on.  It took me a moment to realize this post was about relationships and posted on Valentine’s Day.  Nice touch guys.

  2. Jason says:

    So how would a retrieve be performed for a M:M relationship? From what I’ve seen so far an attribute is not created. Is there a new Retrieve message for this?

  3. Shubhi says:

    Hi, Many To Many relationships can be retrieved using linked entities.

    Specify the LinkFrom entity as the entity to be retrieved and the related entity as the LinkTo entity.

    In order to retrieve records ,you will need to specify the the query condition as "related entity’s id column = related entity id value".

    Hope This Helps.


    Shubhi Bansal


  4. Rob says:

    Any chance we could get a full code example showing the retrieval of a N:N relationship?

  5. How to add a provision for selecting values from a new entity on "To" attribute in Email Activity (Party List type)?

    i followed the below path and i tried to include the selection of new entity.

    Step 1. click Customization under Settings.

    Step 2. Cick on Customize Entities.

    Step 3. Double Click on Email.

    Step 4. Click on Attributes and double click on the "To" attribute.

    Step 5. it showing the Party List.

    In Step 5, How to add a provision for selecting values from a new entity on "To" attribute in Email Activity ?


    Israel G Pradeep

  6. Bill Smith says:

    You have done an awesome job with this upgrade. The new CRM 4 is just about the perfect foundation for almost any system involving people and companies (ie 80% of the systems on the planet).

  7. harvir says:

    I was reading the post of Israel Pradeep "How to add a provision for selecting values from a new entity on "To" attribute in Email Activity (Party List type)?

    can you please let me know what happens in the step 5. as for me the Party list is in-active(greayed out)

    or is there any way if I can add my custom entity to the party list



  8. Caroline says:

    Hello, i just read this post and i would like to check if any one of you came across the following scenario in crm 4.o (since it works perfectly in crm 3.0):

    i have created a custom entity X.

    ‘Contact’ entity has a ‘one-to-many’ relationship with ‘X’

    ‘X’ has a one-to-many relationship with ‘Case’

    once published and u follow the scenario:

    contact-> X-> case, the lookup field in entity case that should contains the contact name displays the customer’s name with the account icon. and upon saving of the case, you get the following error ‘The requested record was not found or you do not have sufficient permissions to view it’.

    Anyone can help?

  9. Linna says:

    I don’t see the option to add attributes to the entity that is between the M:M relationship as I guess this entity is hidden?

    Is there a way to do this?



  10. xyzCha says:

    hi, If I would like to retrieve an existing relationship in CRM without knowing GUID but the name of contact. is it possible to retrieve the entity?

  11. Inaam Khan says:

    I have a problem, I am making many to many relationship from one custom entity with One system entity, and on some condition if for example records are more then 10 it should not add, please let me know how can i do that.


  12. Phill Yasen says:

    but I can’t set the emails language. ,

  13. Matt says:

    Hi there,

    thanks for the article – helped with my many to many relationship but have the following issue outstanding;

    I have a Contact record with a 1 to many relationship with a custom entity.

    I have found many examples on how to programmatically add a link between two

    entities in a many-to-many relationship e.g.

    but not on how to acheive this with a one to many relationship. SetRelated

    didnt work because it returned with an error about Contact Entity not being

    able to use SetRelated

    I have seen another post here on a similar issue but the resolution posted

    did not appear correct and did not work.

    Any help appreciated? links? blogs?

  14. cmann says:

    I’m trying to understand how to use Customer Relationships within the Lead, Contact, Opportunity to an Account, can anyone help?

    Also, is this the right flow; Lead, Contact, Opportunity to Account?


  15. Mark says:

    I am trying to create a relationship between Campaign Response and Leads, and I’ve added some fields to Campaign response to customize it.  When I create the relationship, and do a report using the report wizard, nothing displays.  So somehow the tables arent linking correctly.  I created the same relationship using a new crystal report, with the same results.  There are no real "fields" to link in those two entities from what I can see.  What am I missing here?

  16. Rahul lohar says:

    Is there a way to delete data from the relationship table that the N to N relationship creates using ms crm sdk.

    Actually i have a situation where i need to delete the data that i have inserted in the relationship to be displayed in Iparties treeview.

    The last and the only option i know right now is to just delete the N to N relationship and create a new one, but in my case i have more than 50 relationships to be made.that’s why i am loking for a bypass wherein i can keep the relationship and just delete the data from it.

    Cheers and thanks.


  17. rahul lohar says:

    Is there a way for deleting data in the N to N relationship data using the ms crm4.0 sdk

    The only way i know now is to just delete the relationship and recreate it for new data load in it

    So is there a way to delete this data programmatically ?

    Cheers and Thanks,


  18. Karlo says:


    Any way we could attach a callout/workflow when the MM entity is created?



  19. Bill Goergen says:

    One of the coolest things about MS CRM v4.0 is how easy it is to establish relationships between entities

  20. Michael Sullivan says:

    4.0 Relations are great, but I’m still finding a gap in the ability to have multiple "customer" relationships, which isn’t supported (according to what I’ve read.)

    There are many cases where a business is involved with a transaction (opportunity) with multiple customers (Accounts/Contacts) but you can’t use the "customer" relationship other that what is there.  Example:  A commercial mortgage broker wants to track their deals.  The buyer could be an account (company) or individual (contact) and the seller could be an individual (contact) or company (account);  However, you can’t track both on the opportunity without having an additional relationship for both the account and contact, when only one or the other is used.  Sure, you can hide the one not used, but you can’t dynamically change views, so it’s just not a great approach.

    Any chance Microsoft will open up access to the "cusotmer" relationship for us, or if not, are there any suggestions on how to more cleanly handle these situations.

  21. Staci Nisbett says:

    I am a relatively non-technical administrator of CRM 4.0 and I’m trying to discover ways to view relationships aside from first looking at the contact or company, then going to the relationships but I can’t find a way to setup a view for that.  I also cannot seem to find a way to customize the default relationship view from the contact or company record.

  22. JB says:

    Our company is struggling with MS Dynamics CRM Ver 4.0 limits one Contact to Account relationships.  In our business, Contacts may work for multiple Accounts at the same time. Any simple solutions?

  23. sara-ar says:

    Hi, I want to change the value of some attributes of account entity from a custom entity I created. in my custom entity I create some attributes that are same as account attributes but I do not know how I can create one-to-one relation between this two entity.

    Is there any way to solve this problem?

  24. sara-ar says:

    Hi, I want to change the value of some attributes of account entity from a custom entity I created. in my custom entity I create some attributes that are same as account attributes but I do not know how I can create one-to-one relation between this two entity.

    Is there any way to solve this problem?

  25. sara-ar says:

    Hi, I want to change the value of some attributes of account entity from a custom entity I created. in my custom entity I create some attributes that are same as account attributes but I do not know how I can create one-to-one relation between this two entity.

    Is there any way to solve this problem?

  26. sara-ar says:

    Hi, I want to change the value of some attributes of account entity from a custom entity I created. in my custom entity I create some attributes that are same as account attributes but I do not know how I can create one-to-one relation between this two entity.

    Is there any way to solve this problem?

Skip to main content