Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All
Expand Minimize

AutoMapEntity Message (CrmService)

banner art

[Applies to: Microsoft Dynamics CRM 4.0]

Find the latest SDK documentation: CRM 2015 SDK

Works for all deployment typesWorks online only

Creates the attribute mappings between two entities.

The relevant classes are specified in the following table.

TypeClass
RequestAutoMapEntity
ResponseAutoMapEntity

Remarks

Use this helper function after you create a new relationship. It will map all the attributes between the two related entities where the attribute names are identical, and the types are identical. The may result in some mappings that are not desirable so you should always check the resulting mapping before you publish the customization.

To use this message, pass an instance of the AutoMapEntity class as the request parameter in the Execute method.

To perform this action, the caller must have access rights on the entity instances. For a list of required privileges, see AutoMapEntity Privileges.

Example

The following code example demonstrates how to add a link between two entities that participate in a many-to-many relationship.

[C#]
// Set up the CRM Service.
CrmAuthenticationToken token = new CrmAuthenticationToken();
// You can use enums.cs from the SDK\Helpers folder to get the enumeration for Active Directory authentication.
token.AuthenticationType = 0; 
token.OrganizationName = "AdventureWorksCycle";
 
CrmService service = new CrmService();
service.Url = "http://<servername>:<port>/mscrmservices/2007/crmservice.asmx";
service.CrmAuthenticationTokenValue = token;
service.Credentials = System.Net.CredentialCache.DefaultCredentials;

// Create a custom attribute for the account entity.
StringAttributeMetadata customAccountAttribute = new StringAttributeMetadata();
customAccountAttribute.SchemaName = "new_rentalcontracttype";
customAccountAttribute.RequiredLevel = new CrmAttributeRequiredLevel();
customAccountAttribute.RequiredLevel.Value = AttributeRequiredLevel.None;
customAccountAttribute.MaxLength = new MetadataServiceSdk.CrmNumber();
customAccountAttribute.MaxLength.Value = 100;
customAccountAttribute.EntityLogicalName = EntityName.account.ToString();
customAccountAttribute.LogicalName = "new_rentalcontracttype";
customAccountAttribute.DisplayName = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Type", 1033);
customAccountAttribute.Description = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Contract Type", 1033);

// Create the request for adding the custom attribute to the account entity
CreateAttributeRequest createAccountAttribute = new CreateAttributeRequest();
createAccountAttribute.EntityName = EntityName.account.ToString();
createAccountAttribute.Attribute = customAccountAttribute;

// Add the custom attribute to the account entity
metadataService.Execute(createAccountAttribute);

// Create a custom entity
EntityMetadata subscriptionEntity = new EntityMetadata();
subscriptionEntity.SchemaName = "new_rentalcontract";
subscriptionEntity.OwnershipType = new CrmOwnershipTypes();
subscriptionEntity.OwnershipType.Value = OwnershipTypes.UserOwned;
subscriptionEntity.DisplayName = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Contract", 1033);
subscriptionEntity.DisplayCollectionName = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Contracts", 1033);
subscriptionEntity.Description = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("SDK Sample Entity", 1033);

// Create the primary attribute
StringAttributeMetadata primaryAttribute = new StringAttributeMetadata();
primaryAttribute.SchemaName = "new_name";
primaryAttribute.RequiredLevel = new CrmAttributeRequiredLevel();
primaryAttribute.RequiredLevel.Value = AttributeRequiredLevel.None;
primaryAttribute.MaxLength = new MetadataServiceSdk.CrmNumber();
primaryAttribute.MaxLength.Value = 100;
primaryAttribute.EntityLogicalName = "new_rentalcontract";
primaryAttribute.LogicalName = "new_name";
primaryAttribute.DisplayName = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Name", 1033);
primaryAttribute.Description = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Contract Name", 1033);

// Create the request object for the custom entity
CreateEntityRequest createEntity = new CreateEntityRequest();
createEntity.Entity = subscriptionEntity;
createEntity.HasActivities = false;
createEntity.HasNotes = true;
createEntity.PrimaryAttribute = primaryAttribute;

// Execute the request
CreateEntityResponse entityResponse = (CreateEntityResponse)metadataService.Execute(createEntity);

// Create an attribute with the same name as the one added to the account entity above.  This will cause a map to be created 
// for these two fields automatically when the AutoMapEntity function is called.
StringAttributeMetadata subscriptionTypeAttribute = new StringAttributeMetadata();
subscriptionTypeAttribute.SchemaName = "new_rentalcontracttype";
subscriptionTypeAttribute.RequiredLevel = new CrmAttributeRequiredLevel();
subscriptionTypeAttribute.RequiredLevel.Value = AttributeRequiredLevel.None;
subscriptionTypeAttribute.MaxLength = new MetadataServiceSdk.CrmNumber();
subscriptionTypeAttribute.MaxLength.Value = 100;
subscriptionTypeAttribute.EntityLogicalName = "new_rentalcontract";
subscriptionTypeAttribute.LogicalName = "new_rentalcontracttype";
subscriptionTypeAttribute.DisplayName = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Type", 1033);
subscriptionTypeAttribute.Description = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Contract Type", 1033);

// Create the request for adding the new attribute to the custom entity
CreateAttributeRequest createAttribute = new CreateAttributeRequest();
createAttribute.Attribute = subscriptionTypeAttribute;
createAttribute.EntityName = "new_rentalcontract";

// Execute the request
metadataService.Execute(createAttribute);

// Create a 1:N relationship for this entity to the built-in entity 'account'
OneToManyMetadata oneToManyRelationship = new OneToManyMetadata();

// The account entity will be the 'one' in this one-to-many relationship
oneToManyRelationship.ReferencedEntity = EntityName.account.ToString();

// The custom subscription entity will be the 'many' in this one-to-many relationship
oneToManyRelationship.ReferencingEntity = "new_rentalcontract";

// Set the metadata properties
oneToManyRelationship.SchemaName = "new_account_rentalcontract";
oneToManyRelationship.AssociatedMenuBehavior = new CrmAssociatedMenuBehavior();
oneToManyRelationship.AssociatedMenuBehavior.Value = AssociatedMenuBehavior.UseLabel;
oneToManyRelationship.AssociatedMenuGroup = new CrmAssociatedMenuGroup();
oneToManyRelationship.AssociatedMenuGroup.Value = AssociatedMenuGroup.Details;
oneToManyRelationship.AssociatedMenuLabel = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Account", 1033);
oneToManyRelationship.AssociatedMenuOrder = new MetadataServiceSdk.CrmNumber();
oneToManyRelationship.AssociatedMenuOrder.Value = 10000;

// Make the relationship behaviour 'parental' by setting all cascade properties to 'Cascade'
oneToManyRelationship.CascadeAssign = new CrmCascadeType();
oneToManyRelationship.CascadeAssign.Value = CascadeType.Cascade;
oneToManyRelationship.CascadeDelete = new CrmCascadeType();
oneToManyRelationship.CascadeDelete.Value = CascadeType.Cascade;
oneToManyRelationship.CascadeReparent = new CrmCascadeType();
oneToManyRelationship.CascadeReparent.Value = CascadeType.Cascade;
oneToManyRelationship.CascadeShare = new CrmCascadeType();
oneToManyRelationship.CascadeShare.Value = CascadeType.Cascade;
oneToManyRelationship.CascadeUnshare = new CrmCascadeType();
oneToManyRelationship.CascadeUnshare.Value = CascadeType.Cascade;

// Create a request to add the 1:N relationship to the custom subscription entity
CreateOneToManyRequest createRelationship = new CreateOneToManyRequest();

// The 'many' subscription entities will need to store the id to the 'one' account they are related to.
// So we will now create a lookup to store that id.
createRelationship.Lookup = new LookupAttributeMetadata();

// Set the lookup properties
createRelationship.Lookup.SchemaName = "new_parent_accountid";
createRelationship.Lookup.AttributeType = new CrmAttributeType();
createRelationship.Lookup.AttributeType.Value = AttributeType.Lookup;
createRelationship.Lookup.DisplayName = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Account Lookup", 1033);
createRelationship.Lookup.RequiredLevel = new CrmAttributeRequiredLevel();
createRelationship.Lookup.RequiredLevel.Value = AttributeRequiredLevel.None;
createRelationship.Lookup.Description = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Sample Lookup", 1033);
createRelationship.OneToManyRelationship = oneToManyRelationship;

// Add the relationship to the custom entity
CreateOneToManyResponse relationshipResponse = (CreateOneToManyResponse)metadataService.Execute(createRelationship);

// Publish all customizations
PublishAllXmlRequest publishAllRequest = new PublishAllXmlRequest();

// NOTE:  The custom attributes cannot be used until they have been published.
service.Execute(publishAllRequest);

// Retrieve the entitymap record created for the relationship above.
ColumnSet returnColumns = new ColumnSet();
returnColumns.Attributes = new string[] {"sourceentityname", "targetentityname"};

ConditionExpression sourceEntityCondition = new ConditionExpression();
sourceEntityCondition.AttributeName = "sourceentityname";
sourceEntityCondition.Operator = ConditionOperator.Equal;
sourceEntityCondition.Values = new string[] {EntityName.account.ToString()};

ConditionExpression targetEntityCondition = new ConditionExpression();
targetEntityCondition.AttributeName = "targetentityname";
targetEntityCondition.Operator = ConditionOperator.Equal;
targetEntityCondition.Values = new string[] {"new_rentalcontract"};

FilterExpression sourceTargetFilter = new FilterExpression();
sourceTargetFilter.Conditions = new ConditionExpression[] {sourceEntityCondition, targetEntityCondition};
sourceTargetFilter.FilterOperator = LogicalOperator.And;

QueryExpression entityMapQuery = new QueryExpression();
entityMapQuery.ColumnSet = returnColumns;
entityMapQuery.EntityName = EntityName.entitymap.ToString();
entityMapQuery.Criteria = sourceTargetFilter;

BusinessEntityCollection entityMaps = service.RetrieveMultiple(entityMapQuery);

Guid entityMapId = Guid.Empty;

if (entityMaps.BusinessEntities.Length > 0)
{
   entitymap ourEntityMap = entityMaps.BusinessEntities[0] as entitymap;
   entityMapId = ourEntityMap.entitymapid.Value;
}

// Create the request.
AutoMapEntityRequest autoMapRequest = new AutoMapEntityRequest();
autoMapRequest.EntityMapId = entityMapId;

// Execute the request.
AutoMapEntityResponse autoMapResponse = service.Execute(autoMapRequest) as AutoMapEntityResponse;
[Visual Basic .NET]
' Set up the CRM Service.
Dim token As New CrmAuthenticationToken()
' You can use enums.cs from the SDK\Helpers folder to get the enumeration.
token.AuthenticationType = 0
token.OrganizationName = "AdventureWorksCycle";
 
Dim service As New CrmService()
service.Url = "http://<servername>:<port>/mscrmservices/2007/crmservice.asmx";
service.CrmAuthenticationTokenValue = token;
service.Credentials = System.Net.CredentialCache.DefaultCredentials

' Create a custom attribute for the account entity.
Dim customAccountAttribute As New StringAttributeMetadata()
customAccountAttribute.SchemaName = "new_rentalcontracttype"
customAccountAttribute.RequiredLevel = New CrmAttributeRequiredLevel()
customAccountAttribute.RequiredLevel.Value = AttributeRequiredLevel.None
customAccountAttribute.MaxLength = New MetadataServiceSdk.CrmNumber()
customAccountAttribute.MaxLength.Value = 100
customAccountAttribute.EntityLogicalName = EntityName.account.ToString()
customAccountAttribute.LogicalName = "new_rentalcontracttype"
customAccountAttribute.DisplayName = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Type", 1033)
customAccountAttribute.Description = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Contract Type", 1033)

' Create the request for adding the custom attribute to the account entity
Dim createAccountAttribute As New CreateAttributeRequest()
createAccountAttribute.EntityName = EntityName.account.ToString()
createAccountAttribute.Attribute = customAccountAttribute

' Add the custom attribute to the account entity
metadataService.Execute(createAccountAttribute)

' Create a custom entity
Dim subscriptionEntity As New EntityMetadata()
subscriptionEntity.SchemaName = "new_rentalcontract"
subscriptionEntity.OwnershipType = New CrmOwnershipTypes()
subscriptionEntity.OwnershipType.Value = OwnershipTypes.UserOwned
subscriptionEntity.DisplayName = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Contract", 1033)
subscriptionEntity.DisplayCollectionName = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Contracts", 1033)
subscriptionEntity.Description = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("SDK Sample Entity", 1033)

' Create the primary attribute
Dim primaryAttribute As New StringAttributeMetadata()
primaryAttribute.SchemaName = "new_name"
primaryAttribute.RequiredLevel = New CrmAttributeRequiredLevel()
primaryAttribute.RequiredLevel.Value = AttributeRequiredLevel.None
primaryAttribute.MaxLength = New MetadataServiceSdk.CrmNumber()
primaryAttribute.MaxLength.Value = 100
primaryAttribute.EntityLogicalName = "new_rentalcontract"
primaryAttribute.LogicalName = "new_name"
primaryAttribute.DisplayName = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Name", 1033)
primaryAttribute.Description = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Contract Name", 1033)

' Create the request object for the custom entity
Dim createEntity As New CreateEntityRequest()
createEntity.Entity = subscriptionEntity
createEntity.HasActivities = False
createEntity.HasNotes = True
createEntity.PrimaryAttribute = primaryAttribute

' Execute the request
Dim entityResponse As CreateEntityResponse = CType(metadataService.Execute(createEntity), CreateEntityResponse)

' Create an attribute with the same name as the one added to the account entity above.  This will cause a map to be created 
' for these two fields automatically when the AutoMapEntity function is called.
Dim subscriptionTypeAttribute As New StringAttributeMetadata()
subscriptionTypeAttribute.SchemaName = "new_rentalcontracttype"
subscriptionTypeAttribute.RequiredLevel = New CrmAttributeRequiredLevel()
subscriptionTypeAttribute.RequiredLevel.Value = AttributeRequiredLevel.None
subscriptionTypeAttribute.MaxLength = New MetadataServiceSdk.CrmNumber()
subscriptionTypeAttribute.MaxLength.Value = 100
subscriptionTypeAttribute.EntityLogicalName = "new_rentalcontract"
subscriptionTypeAttribute.LogicalName = "new_rentalcontracttype"
subscriptionTypeAttribute.DisplayName = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Type", 1033)
subscriptionTypeAttribute.Description = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Rental Contract Type", 1033)

' Create the request for adding the new attribute to the custom entity
Dim createAttribute As New CreateAttributeRequest()
createAttribute.Attribute = subscriptionTypeAttribute
createAttribute.EntityName = "new_rentalcontract"

' Execute the request
metadataService.Execute(createAttribute)

' Create a 1:N relationship for this entity to the built-in entity 'account'
Dim oneToManyRelationship As New OneToManyMetadata()

' The account entity will be the 'one' in this one-to-many relationship
oneToManyRelationship.ReferencedEntity = EntityName.account.ToString()

' The custom subscription entity will be the 'many' in this one-to-many relationship
oneToManyRelationship.ReferencingEntity = "new_rentalcontract"

' Set the metadata properties
oneToManyRelationship.SchemaName = "new_account_rentalcontract"
oneToManyRelationship.AssociatedMenuBehavior = New CrmAssociatedMenuBehavior()
oneToManyRelationship.AssociatedMenuBehavior.Value = AssociatedMenuBehavior.UseLabel
oneToManyRelationship.AssociatedMenuGroup = New CrmAssociatedMenuGroup()
oneToManyRelationship.AssociatedMenuGroup.Value = AssociatedMenuGroup.Details
oneToManyRelationship.AssociatedMenuLabel = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Account", 1033)
oneToManyRelationship.AssociatedMenuOrder = New MetadataServiceSdk.CrmNumber()
oneToManyRelationship.AssociatedMenuOrder.Value = 10000

' Make the relationship behaviour 'parental' by setting all cascade properties to 'Cascade'
oneToManyRelationship.CascadeAssign = New CrmCascadeType()
oneToManyRelationship.CascadeAssign.Value = CascadeType.Cascade
oneToManyRelationship.CascadeDelete = New CrmCascadeType()
oneToManyRelationship.CascadeDelete.Value = CascadeType.Cascade
oneToManyRelationship.CascadeReparent = New CrmCascadeType()
oneToManyRelationship.CascadeReparent.Value = CascadeType.Cascade
oneToManyRelationship.CascadeShare = New CrmCascadeType()
oneToManyRelationship.CascadeShare.Value = CascadeType.Cascade
oneToManyRelationship.CascadeUnshare = New CrmCascadeType()
oneToManyRelationship.CascadeUnshare.Value = CascadeType.Cascade

' Create a request to add the 1:N relationship to the custom subscription entity
Dim createRelationship As New CreateOneToManyRequest()

' The 'many' subscription entities will need to store the id to the 'one' account they are related to.
' So we will now create a lookup to store that id.
createRelationship.Lookup = New LookupAttributeMetadata()

' Set the lookup properties
createRelationship.Lookup.SchemaName = "new_parent_accountid"
createRelationship.Lookup.AttributeType = New CrmAttributeType()
createRelationship.Lookup.AttributeType.Value = AttributeType.Lookup
createRelationship.Lookup.DisplayName = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Account Lookup", 1033)
createRelationship.Lookup.RequiredLevel = New CrmAttributeRequiredLevel()
createRelationship.Lookup.RequiredLevel.Value = AttributeRequiredLevel.None
createRelationship.Lookup.Description = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.CreateSingleLabel("Sample Lookup", 1033)
createRelationship.OneToManyRelationship = oneToManyRelationship

' Add the relationship to the custom entity
Dim relationshipResponse As CreateOneToManyResponse = CType(metadataService.Execute(createRelationship), CreateOneToManyResponse)

' Publish all customizations
Dim publishAllRequest As New PublishAllXmlRequest()

' NOTE:  The custom attributes cannot be used until they have been published.
service.Execute(publishAllRequest)

' Retrieve the entitymap record created for the relationship above.
Dim returnColumns As New ColumnSet()
returnColumns.Attributes = New String() {"sourceentityname", "targetentityname"}

Dim sourceEntityCondition As New ConditionExpression()
sourceEntityCondition.AttributeName = "sourceentityname"
sourceEntityCondition.Operator = ConditionOperator.Equal
sourceEntityCondition.Values = New String() {EntityName.account.ToString()}

Dim targetEntityCondition As New ConditionExpression()
targetEntityCondition.AttributeName = "targetentityname"
targetEntityCondition.Operator = ConditionOperator.Equal
targetEntityCondition.Values = New String() {"new_rentalcontract"}

Dim sourceTargetFilter As New FilterExpression()
sourceTargetFilter.Conditions = New ConditionExpression() {sourceEntityCondition, targetEntityCondition}
sourceTargetFilter.FilterOperator = LogicalOperator.And

Dim entityMapQuery As New QueryExpression()
entityMapQuery.ColumnSet = returnColumns
entityMapQuery.EntityName = EntityName.entitymap.ToString()
entityMapQuery.Criteria = sourceTargetFilter

Dim entityMaps As BusinessEntityCollection = service.RetrieveMultiple(entityMapQuery)

Dim entityMapId As Guid = Guid.Empty

If entityMaps.BusinessEntities.Length > 0 Then
   Dim ourEntityMap As entitymap = TryCast(entityMaps.BusinessEntities(0), entitymap)
   entityMapId = ourEntityMap.entitymapid.Value
End If

' Create the request.
Dim autoMapRequest As New AutoMapEntityRequest()
autoMapRequest.EntityMapId = entityMapId

' Execute the request.
Dim autoMapResponse As AutoMapEntityResponse = TryCast(service.Execute(autoMapRequest), AutoMapEntityResponse)

See Also

Concepts

Reference


© 2010 Microsoft Corporation. All rights reserved.


Show:
© 2015 Microsoft