A guide to help you determine the best solutions for you.
Microsoft Dynamics CRM Upgrades and Custom Security Roles
During a CRM Upgrade, especially across multiple versions, it is imperative to review and likely recreate custom security roles. You might think this is extra work, but as you will see in several examples, errors can occur and in troubleshooting the issue will turn out to be security role related. Even in CRM Online this is important as changes for instance from CRM 2013 to CRM 2013 SP1 to CRM 2015 can be affected.
This won’t be a long troubleshooting lesson, but when a strange reproducible error occurs, I always suggest getting a CRM Trace to get a better error. If the issue is with CRM Online, determine if you can replicate it with the Outlook client as you will be able to get a trace there. The Diagnostics package for Outlook CRM Client has a checkbox to establish tracing as seen in the screenshot below. If the issue is in an on premise CRM application and the Outlook client is not in use, I suggest the CRMDiagTool2011, which still works in 2015 despite it’s 2011 moniker. This one stop tool allows you to turn tracing on and off without delving into the registry.
Once you get the error reproduced (I typically repro twice…quickly, to make sure it shows in the trace) TURN OFF TRACING. I can’t stress this enough as the log files will continue to grow long past your memory of turning on the tracing and you will be faced with evaporating disk space. You will then embark on the journey of discovery. Review the logs, knowing you likely won’t know what everything means and that is OK. Start at the end and work your way up (and if using Notepad, be sure to turn on Word Wrap) to find the first instance of the error.
Here is how you will know there is a problem with a permission. From an example log:
[2015-05-04 12:15:10.459] Process:OUTLOOK |Organization:xxxxxxxx-4c42-435c-9cf4-xxxxxxxxxxxx |Thread: 30 |Category: Application.Outlook |User: 00000000-0000-0000-0000-000000000000 |Level: Error |ReqId: | ThreadsSupport.ExecuteThreadProc ilOffset = 0x2
at ThreadsSupport.ExecuteThreadProc(ThreadProc threadProc, IntPtr parameter) ilOffset = 0x2
> TraceException: Unhandled Exception: System.Runtime.InteropServices.COMException: Principal user (Id=xxxxxxxx-36fe-e311-803d-xxxxxxxxxxxx, type=8) is missing prvReadConvertRule privilege (Id=a51aa4b3-b0c3-4b81-a290-9ed4b0db8fb1)
at Microsoft.Crm.Application.SMWrappers.CrmServiceForOutlook.Execute(OrganizationRequest request, Boolean wrapException)
at Microsoft.Crm.Application.SMWrappers.EmailForOutlook.Microsoft.Crm.Application.SMWrappers.IEmailForOutlook.DeliverPromote(String messageId, String subject, String from, String to, String cc, String bcc, Double receivedon, String submittedBy, String importance, String body, IDynamicEntityCollectionForOutlook attachments, Int32 attachmentCount, IDynamicEntityForOutlook extraProperties, String entityXml, String regardingId, Int64 regardingObjectType, String crmId, Int32& notification)
First clue is that it isn’t Read, Create, etc. on XXXXX entity. Have you heard of the prvReadConvertRule privilege? I hadn’t. At a minimum, I have something I can throw into my search engine of choice. Turns out this is a new feature with 2013 SP1 that didn’t cause any issues in CRM 2013 SP1 client, but does now with 2015. Worst case is that I have a trace and an error to send to Microsoft support. At this point, you should know that the user has a custom security role. First troubleshooting step for me will be to give an OOTB security role to that user and see if the issue persists, like Salesperson. This has all the “normal” albeit low-end rights. You can compare the OOTB role to your custom role and see where the differences are.
Another more extreme example was a recent client upgrade from 4.0 all the way to CRM 2015. You see, CRM 4.0 didn’t have Server Side Sync, nor did CRM 2011, so when those custom roles are upgraded, they will miss out on some of the very basic permissions surrounding Server Side Sync. We encountered this with a client where through our Test and Enable of mailboxes in the system, we came across some interesting errors ONLY on the synchronization of Contacts, Appointments and Tasks testing, Incoming and Outgoing email tested just fine.
Here are the errors (names changed to protect the innocent):
So the one at 4:52 made us realize that we might need some additional rights and that a custom security role was in play. So we went looking to the Salesperson role and under Business Management section there is a Mailbox entity with User rights on Read, Write, and append. As the second test 2 minutes later showed, we were still not home. The problem is that error wasn’t nearly as helpful in its wording, so after doing a bit more review with Dustin Mathern, we found the Email Server Profile rights in the same section. Once we added those rights to the custom role, the errors ceased and we got a successful test.
In summary, with all upgrades, we should be vigilant to review custom security roles and dare I say, we should create them again. Best practices always suggest that a copy of an existing OOTB security role be used. Take the time to discuss what the original intent of the custom role was, as it is possible that the need no longer exists. Using an OOTB role as a template will typically get you around the “hidden” permissions that existed in earlier versions of CRM.
When dealing with custom security roles and strange errors, for testing purposes I always immediately suggest giving the Salesperson role as this is basic and has all the normal, albeit low-end, rights. If the error persists and you are in control of the testing situation, a higher bump in security role could also be done to further test.