Fix errors when accessing SharePoint files from within Dynamics 365

When SharePoint integration works, it is a valuable tool that saves on Dynamics storage; however, it’s not without its challenges. We take a look at some of the issues you may face and how to solve them.

Scenario 1: No users can access a Dynamics 365 record’s documents

If your users are able to access the files for other records from the same table, but not for a specific record, then they may be presented with an error similar to this:

“Folder xxxxx has been renamed or deleted from SharePoint. It was expected inside xxxxx path. Restore the folder on SharePoint and try again.”

If this occurs, you have a number of options:

1. If the folder has been deleted, create a new one with the folder name specified in the error message.
2. If the folder has been renamed and you’re happy to change the folder back to the name expected by Dynamics, then rename it accordingly.
3. If the folder has been renamed and you don’t want to rename the folder in SharePoint, you can edit the Document Location record which links the Dynamics 365 record to the SharePoint folder. In Dynamics 365, you can perform an Advanced Find and search for records where the Regarding field is that of the record with the error. Once you have located it, it should look something like this:
   
   Simply edit the Relative URL to match the folder name in SharePoint and click Save. This should fix the link between the record and folder.

Scenario 2: A specific user (or group of users) cannot access the SharePoint documents for any Dynamics 365 records

If an error message similar to this is displayed:

“You don’t have permissions to view files in this location. Contact your Microsoft Teams owner or SharePoint administrator for access”

There are three main causes for this issue:

1. The most common cause is the user not having the right permissions at the SharePoint end. Amend the Site and folder permissions for that user or group of users accordingly.
2. The user is missing the correct permissions within their Dynamics 365 role(s). They should have at least Read permissions on the SharePoint Sites and Document Locations tables. Amend their role accordingly and have the user try again.
3. If the Dynamics 365 and SharePoint permissions all look correct, and the user can access the SharePoint files when going directly to the SharePoint site, then you might have encountered a more unusual scenario where the userpuid, a hidden unique ID on a Dynamics 365 user record doesn’t match the value in a field called puid within the user record in Azure Active Directory. See below for the steps need to rectify this mismatch.

Fixing a mismatch between Dynamics 365 userpuid and Azure Active Directory puid

Firstly, it’s worth pointing out that this change can only be made by Microsoft themselves; there are no tools available that allow for administrators to fix the problem themselves. However, a lot of time can be saved by carrying out the checks on the two fields and presenting the differing userpuid/puid fields to Microsoft at the outset.

What causes the mismatch?

When a user is created in Azure/Microsoft 365 and given a Dynamics 365 or Power Platform licence, that user is then automatically created in Dynamics 365. However, if that user is then deleted from Azure/Microsoft 365, the user record remains in Dynamics 365, to ensure data integrity for owned records or lookups referencing that user. The problem comes when someone creates that user again in Azure/Microsoft 365 with the same username (email address) as before; Dynamics 365 is already aware of the user, so sees no need to create it. However, the hidden userpuid field is used to determine access within SharePoint, so if there is a mismatch, an error will be displayed.

How can I get the userpuid and puid values?

Obtaining the Dynamics 365 userpuid value – Unfortunately, this cannot be queried from within the Dynamics user interface itself. However, there are a number of methods available:

• The simplest method is via an API request. Ensure that you are logged into Dynamics 365 as someone with sufficiently high administrator privileges and enter this URL in the same browser:

  <YOUR DYNAMICS 365 URL>/api/data/v9.2/systemusers?$select=userpuid,internalemailaddress&$filter=(internalemailaddress%20eq%20%27<USER EMAIL ADDRESS>%27)

  replacing <YOUR DYNAMICS 365 URL> with the URL of your live Dynamics 365 environment and <USER EMAIL ADDRESS> with the email address of the user experiencing the SharePoint issue. When you visit the URL, you will receive  a response that includes output similar to

  userpuid":"10037FFEAA77975E"

  Make a note of this value and repeat the process for any other affected users.

• If you use Power BI, you can query the systemuser table and the userpuid field will be displayed for all users.
• If you use XrmToolBox, you can build a query using the FetchXML Builder tool.

Obtaining the Azure Active Directory puid value

This is a value that an affected user can obtain for you with your guidance:

1. Have the user visit: https://developer.microsoft.com/en-us/graph/graph-explorer in their browser.
2. Have them click the Sign in to Graph Explorer button and log in with their usual Microsoft 365 account credentials:
   
3. Once logged in, have them click the Get My Profile button:
   
   In the lower part of the screen, you should see details about the user, including their name and email address.
4. In the upper part of the screen, click the Access Token button:
   
   This will present a long string of text. Either highlight and copy the text manually or click the Copy icon to copy the text to your clipboard.
5. Have the user visit https://jwt.ms/ and paste their copied Access Token string into the first box. The decoded token will then be displayed and among the values, you will see something like:
   “puid”: “10030000A040493B”
   Make a note of this value and repeat the whole process for any other affected users.

If the userpuid and puid values do not match, then this is a problem that Microsoft will have to correct on your behalf. Provide both of these values for all affected users and Microsoft will be able to make a back-end correction which will fix the issue.

Summary

Although Dynamics 365 and SharePoint work well together 99% of the time, there can be scenarios where administrative action is required. However, these issues can be addressed and your users can soon get back to working with the two platforms seamlessly again. If you are an existing client of Strategy 365 and wish to discuss the content of this guide, please get in touch with one of our experts.