Solution Import Failed: The entity relationship role of the referencing entity is required when creating a new one-to-many entity relationship (0x80048470)

BEFORE WE GET STARTED

The source organization (where the solution was exported from) was CRM Online 2015. I am assuming Update 1.0. The version number found in solution.xml was 7.1.0001.3138.

The target organization (where the solution was being imported from) was CRM Online 2015 - Update 1.1 (7.1.1.4210).

THE STORY

In CRM Online (2015 Update 1.1), I exported a solution from one organization and imported it into another. When attempting to import the solution I received the typical (unhelpful) error:

An error has occurred. Try this action again. If the problem continues, check the Microsoft Dynamics CRM Community for solutions or contact your organization's Microsoft Dynamics CRM Administrator. Finally, you can contact Microsoft Support.

After inspecting the log file, I found the error message I needed:

The entity relationship role of the referencing entity is required when creating a new one-to-many entity relationship new_sharepointdocument_SharePointDocumentLocations.

Beside this message I noticed that this error occurred when CRM was attempting to process the sharepointdocument_SharePointDocumentLocations relationship.

Hold on a sec. What? Let's take a look at that again.

Name: sharepointdocument_SharePointDocumentLocations

ErrorText: new_sharepointdocument_SharePointDocumentLocations

Aww.

CRM.

(Pat on the head)

So, it appears that CRM isn't seeing this as a system/OOB relationship (notice the "new_" prepended to the name of the relationship). This may be the cause of the issue, or it may be the result of a deeper issue. Let's examine further.

If we open the solution .ZIP file and look at customizations.xml we find the following element/block:

    <EntityRelationship Name="sharepointdocument_SharePointDocumentLocations">

      <EntityRelationshipType>OneToMany</EntityRelationshipType>

      <IsCustomizable>1</IsCustomizable>

      <IntroducedVersion>1.0</IntroducedVersion>

      <IsHierarchical>0</IsHierarchical>

      <ReferencingEntityName>SharePointDocumentLocation</ReferencingEntityName>

      <ReferencedEntityName>SharePointDocument</ReferencedEntityName>

      <CascadeAssign>Cascade</CascadeAssign>

      <CascadeDelete>Cascade</CascadeDelete>

      <CascadeReparent>Cascade</CascadeReparent>

      <CascadeShare>Cascade</CascadeShare>

      <CascadeUnshare>Cascade</CascadeUnshare>

      <ReferencingAttributeName>RegardingObjectId</ReferencingAttributeName>

      <RelationshipDescription>

        <Descriptions>

          <Description description="Unique identifier of the object with which the SharePoint document location record is associated." languagecode="1033" />

        </Descriptions>

      </RelationshipDescription>

      <field name="regardingobjectid" requiredlevel="none" imemode="auto" lookupstyle="single" lookupbrowse="0" format="regarding">

        <IsSecured>0</IsSecured>

        <DisplayMask>ValidForAdvancedFind|ValidForForm|ValidForGrid</DisplayMask>

        <IsAuditEnabled>1</IsAuditEnabled>

        <displaynames>

          <displayname description="Regarding" languagecode="1033" />

        </displaynames>

      </field>

    </EntityRelationship>

Yup. It's definitely missing the EntityRelationshipRoles and EntityRelationshipRole elements (these usually follow the field element).

THE FIX

WARNING: These methods are technically unsupported. Your first consideration should be to contact Microsoft support regarding this issue - as it appears to be a bug.

Possibly, you could re-create the EntityRelationshipRoles and EntityRelationshipRole elements yourself (which I didn't test - so you're on your own if you choose that path). We could do this from finding another EntityRelationshipRole element in customizations.xml and using it as a template.

The better solution is to remove this block entirely. The effect will be that the sharepointdocument_SharePointDocumentLocations relationship that already exists in your target system will be left untouched. Unless you customized this relationship in some way, this is exactly what you want to happen.

Open the customizations.xml file from your solution .ZIP file, remove the EntityRelationship element/block, save your changes, and import the fixes .ZIP file, and voila!

Btw, I experienced the same problem with the sharepointsite_SharePointDocumentLocations relationship, so go ahead and remove the EntityRelationship element/block for that as well.