Limitations, known issues, and troubleshooting for healthcare solutions powered by Dynamics 365

2025-05-28

This article provides information about the limitations, issues, or errors you might see when using the Dynamics 365 healthcare solutions in Microsoft Cloud for Healthcare, and how you can resolve them.

Limitations

The healthcare solutions can't be deployed in a Microsoft Dataverse environment without:
- A database
- Appropriate Microsoft Dynamics 365 apps
- Licenses for the required Dynamics 365 apps
For more information, go to Deploy the healthcare solutions.
Microsoft Cloud Solution Center, used for deploying the healthcare solutions, doesn't provide information about the deployment status. To view the deployment status of your solutions, go to your environment in the Microsoft Power Platform admin center. For more information, go to Manage Dynamics 365 apps.

Known issues

The installation of the healthcare solutions in Microsoft Cloud for Healthcare can take multiple hours.
Installing the healthcare solutions in an environment where the Dynamics 365 healthcare accelerator is already installed can cause inconsistencies in the user experience.
Before installing the Patient access solution, ensure that the target environment has only one portal of Customer self-service type. Otherwise, installing the Patient access solution can lead to unintended behavior and overwrite other portals in the environment. You must also ensure that you don't create additional portals in the target environment after deploying the Patient access solution.

Troubleshoot

This section explains how to troubleshoot some common issues that you may encounter while using the Microsoft Cloud for Healthcare solutions.

Care plan control

Issue: Care plan doesn't load care plans, but the patient has care plans related to them.

Cause/description: Security role is missing access to an entity that is used by the control.

Resolution: Update the security role to provide access to the following entities:
- Codeable concept
- Care plan care team
- Care plan activity goal
- Goal
- Referral request
Issue: Care plan doesn't list related care team members.

Cause/description: Care plan doesn't have a related care plan care team record.

Resolution: Add a new care plan care team record that relates the care plan to a care team.

Care team control

Issue: An error was encountered in the care team control - "Couldn't retrieve Care Team/Care Team Participants".

Cause/description: The control was unable to retrieve the records for the care team or care team participants.

Resolution: This issue is most likely due to incorrect configuration of the security role.
Issue: An error was encountered in the care team control - "Couldn't retrieve participants".

Cause/description: The control was unable to retrieve the care team participants records.

Resolution: This error is most likely due to incorrect configuration of the security role.
Issue: An error was encountered in the care team control - "Couldn't open quick form".

Cause/description: The control wasn't able to open the Dynamics form for the record.

Resolution: This issue could be due to misconfiguration of the quick view form, a popup blocker, or security role configuration.

FHIR sync administration

Issue: Error: In order to create a new entity map, you must be able to create alternate keys within Dataverse. The entity updater service attempts to create a new alternate key for the Azure FHIR ID. If you're unable to elevate your permissions, you can have someone with the necessary permissions create a new alternate key in the following format: DisplayName=Azure FHIR Key, SchemaName=msemr_AzureFHIRKey. After the key is created, you can attempt creating the entity map again.

Cause/description: User doesn't have the required platform permissions to create attributes and alternate keys.

Resolution: Add the FHIR sync administrator security role to the user.
Issue: Error: Can't create an alternate key for Azure FHIR ID because the attribute hasn't yet been created. In order to create a new entity map, you must be able to create attributes within the system. The entity updater service attempts to create new attributes to support the syncing of data with Azure FHIR. Elevate your permissions and try to create the entity map again.

Cause/description: User doesn't have the required platform permissions to create attributes and alternate keys.

Resolution: Add the FHIR sync administrator security role to the user.
Issue: Invalid sync agent logging enabled variable.

Cause/description: An incorrect value is entered for the FHIR Sync Agent Logging Enabled variable.

Resolution: Valid values are true or false. Follow these steps to set the variable value to a valid value.
1. Sign in to Microsoft Power Apps for your environment.
2. In the left pane, select Data, and then select Tables.
3. Select the All filter option, and then search for EnvironmentVariableValue.
4. Select Environment Variable Value.
5. From the command bar, select Edit data in Excel.
6. Update the values listed as yes or no to the respective true or false value.
Issue: Invalid sync agent enabled variable.

Cause/description: An incorrect value is entered for the FHIR Sync Agent Enabled variable.

Resolution: Valid values are true or false. Follow these steps to set the variable value to a valid value.
1. Sign in to Microsoft Power Apps for your environment.
2. In the left pane, select Data, and then select Tables.
3. Select the All filter option, and then search for EnvironmentVariableValue.
4. Select Environment Variable Value.
5. From the command menu, select Edit data in Excel.
6. Update the values listed as yes or no to the respective true or false value.
Issue: Contact not synced.

Cause/description: The Contact entity doesn't have the msemr_azurefhirsyncenabled field set to true.

Resolution: To sync the patient data between Dataverse and Azure FHIR, set this field to true for that patient record.
Issue: Contact missing Azure FHIR ID.

Cause/description: The Contact record doesn't have an Azure FHIR ID (msemr_azurefhirid). The system only supports contacts being synced that originate from Azure FHIR.

Resolution: Create the patient in Azure FHIR first, and then let the contact flow to Dataverse for enrichment.
Issue: No FHIR changes detected.

Cause/description: For the given record, no changes were detected based on the entity maps.

Resolution: No action needed. If a change isn't being pushed that should be, then you should update the entity map with the appropriate attribute map configuration.
Issue: Missing required fields.

Cause/description: The record doesn't have data for all the Azure FHIR required fields. Before a record is sent to the FHIR server, all Azure FHIR required fields need to be populated.

Resolution: Provide data for all the Azure FHIR required fields. The required fields can be identified by reviewing the attribute maps and sorting them by the FHIR Required Attribute field.
Issue: Missing mapped attributes for {entityname}.

Cause/description: No attribute maps are defined for the entity, but it's configured to send messages to the service bus.

Resolution: Create attribute maps for the entity.
Issue: Missing app service configuration.

Cause/description: The app ID hasn't been set in the FHIR sync agent environment variable.

Resolution: Update the environment variable with the app ID and create the app user in Dataverse with the Sync admin for FHIR App Reg User permissions.
Issue: Missing service bus configuration.

Cause/description: The FHIR sync agent environment variables that contain the service bus information aren't populated.

Resolution: Update the environment variables with the correct service bus information.
Issue: Sync disabled.

Cause/description: The sync agent has been disabled through the environment variable.

Resolution: Update the environment variable to true if you want the sync agent to be enabled and running.
Issue: Error sending message to service bus.

Cause/description: An error occurred in communicating with the service bus.

Resolution: Validate that the service bus information is correct in the environment variables and that you can communicate with the service bus.

Timeline Gantt control

Issue: An error was encountered in the Timeline control: Custom JSON schema parsing failed, reverting to default entities.

Cause/description: This error appears when the customMappingJSON field in the Power Apps component framework (PCF) control configuration isn't in a valid JSON format and can't be parsed properly.

Resolution: Analyze the text in the customMappingJSON field and ensure that it complies with all JSON rules.
Issue: An error was encountered in the Timeline control: Failed to fetch entity data.

Cause/description: When this error is displayed, look for the error details, possibly provided as a downloadable file. An XRM-related method generally returns this error.

Resolution: Depending on the error details, there could be many resolutions. The most common solutions are fixes to the security role (record access) or fixes to incorrectly mapped fields in the customMapping JSON configuration field.

Issue: Items not showing up on the Timeline that should.

Cause/description: Some fields aren't being populated.

Resolution: List of fields mapped to timeline to make them appear:

{
    "primaryIdField": "activityid",
    "logicalName": "msemr_appointmentemr",
    "displayName": "Appointment (EMR)",
    "titleField": "subject",
    "descriptionField": "msemr_description",
    "startDateField": "msemr_starttime",
    "endDateField": "msemr_endtime",
    "regardingField": "regardingobjectid"
},
{
    "primaryIdField": "msemr_careplanid",
    "logicalName": "msemr_careplan",
    "displayName": "Care Plan",
    "titleField": "msemr_title",
    "descriptionField": "msemr_plandescription",
    "startDateField": "msemr_planstartdate",
    "endDateField": "msemr_planenddate",
    "regardingField": "msemr_patientidentifier"
},
{
 "primaryIdField": "msemr_encounterid",
    "logicalName": "msemr_encounter",
    "displayName": "Encounter",
    "titleField": "msemr_name",
    "descriptionField": "msemr_name",
    "startDateField": "msemr_encounterstartdate",
    "endDateField": "msemr_encounterenddate",
    "regardingField": "msemr_subjectpatient"
},
{
    "primaryIdField": "msemr_medicationrequestid",
    "logicalName": "msemr_medicationrequest",
    "displayName": "Medication Request",
    "titleField": "msemr_name",
    "descriptionField": "msemr_name",
    "startDateField": "msemr_dispenserequestvalidityperiodstartdate",
    "endDateField": "msemr_dispenserequestvalidityperiodenddate",
    "regardingField": "msemr_subjecttypepatient"
},
{
    "primaryIdField": "msemr_procedureid",
    "logicalName": "msemr_procedure",
    "displayName": "Procedure",
    "titleField": "msemr_description",
    "descriptionField": "msemr_description",
    "startDateField": "msemr_performedstartdate",
    "endDateField": "msemr_performedenddate",
    "regardingField": "msemr_patient"
},
{
    "primaryIdField": "msemr_referralrequestid",
    "logicalName": "msemr_referralrequest",
    "displayName": "Referral Request",
    "titleField": "msemr_name",
    "descriptionField": "msemr_description",
    "startDateField": "msemr_occurenceperiodstartdate",
    "endDateField": "msemr_occurenceperiodenddate",
    "regardingField": "msemr_requesteragentpatient"
},
{
     "primaryIdField": "activityid",
     "logicalName": "task",
     "displayName": "Task",
     "titleField": "subject",
     "descriptionField": "description",
     "startDateField": "scheduledstart",
     "endDateField": "scheduledend",
     "regardingField": "regardingobjectid"
},
{
    "primaryIdField": "msemr_conditionid",
    "logicalName": "msemr_condition",
    "displayName": "Condition",
    "titleField": "msemr_name",
    "descriptionField": "msemr_name",
    "startDateField": "msemr_onsetperiodstartdate",
    "endDateField": "msemr_onsetperiodenddate",
    "regardingField": "msemr_subjecttypepatient"
},
{
    "primaryIdField": "msemr_allergyintoleranceid",
    "logicalName": "msemr_allergyintolerance",
    "displayName": "Allergy Intolerance",
    "titleField": "msemr_name",
    "descriptionField": "msemr_name",
    "startDateField": "createdon",
    "endDateField": "createdon",
    "regardingField": "msemr_patient"
}

Share via