Health Accelerator Extension Overview

The Dynamics 365 Health Accelerator provides you a baseline set of entities, forms, views, relationships and even a model driven application. These components are designed to be used as the foundation for your application. There are many options for building applications on the Dynamics 365 Business Application Platform. Let’s review them and then go into more detail on how we would go about extending and building new applications based on the Dynamics 365 Health Accelerator. Each of these options represent opportunities leveraging the Dynamics 365 platform for Apps and Analytics. Future articles will showcase integrating with Office and Microsoft Teams. While this series is focused on the Health Accelerator, the overall details will work for any accelerator you have leveraging.

• Canvas based Power Apps
• Model Driven Power Apps
• Model Driven Power Apps for Customer Engagement
• Model Driven UCI Power Apps for Customer Engagement
• Analytic Applications for Power BI

Each of these represents a unique opportunity to not only build new applications, but to leverage the Health Accelerator to connect, embed or extend your existing application, service or platform, whether it exists on Dynamics 365, Microsoft Azure or other 3^rd party on-premise or online hosted solution. In this first blog post in the series we will review how to extend the Common Data Model for the Dynamics 365 Health Accelerator by leveraging Model Driven Power Apps for Customer Engagement.

Note: As this is not intended to be a comprehensive review of the Business Application Platform, If you are new to the platform and wish to learn more please review some of the links at the bottom of my previous article here.

Install the Accelerator

To be able to follow this guide you will need at least a Trial instance of Dynamics 365. To setup a trial please go here. Select the type of trial you would like to use. In this case I would suggest a Sales trial. Dynamics will require that you have an Office 365 Tenant, so if you do not have one, my suggestion would be as follows.

• Create a outlook.com account or other mail provider
• Go to this link and create an E3 trial here. Use the email you created above for this new trial. Once this is complete, go to the link provided above to create a Dynamics 365 Trial.

Now that you have your Trial Customer Engagement Instance, in the same browser open a new tab and go to https://appsource.microsoft.com/en-US/ . In the search box type in Accelerator for Dynamics 365 and hit search. You will see the following application.

Click on Free Trial and fill in the information requested. As you go through the process you may be asked to select which Instance of Customer Engagement you want to install the application into. Make sure you select your Trial instance of Customer Engagement.

Extending the Health Accelerator’s Common Data Model

For the Health Accelerator the Common Data Model represents two combined sets of entities. First are the Microsoft Dynamics 365 Common Data Model entities, which represent the core entities provided with any Customer Engagement Application or CDS 2.0 database for Power Apps. For a review of the Common Data Model please look here. The Microsoft Dynamics 365 provides a GIT repo that enables you to download and provide feedback on the entities in the model, which can be found here. Second are the extensions specifically provided in the Health Accelerator solution. These extensions represent enhancements to existing entities, such as Contact and Account, as well as new entities such as Care Plans. The Health Accelerator entity model can be found in GIT here.

Extending the model means that you either want to create new entities, extend existing entities and / or create new relationships between new or exist entities to be able to perform the required functionality. Below are a few ways in which you can extend the Common Data Model. Remember that any changes you make to existing entities or when you add new entities exist only within your solution. They are visible to the entire system but are part of your private applications extensions. Let’s review some of the ways to extend the model.

From within Customer Engagement

Once you have installed the solution you should have a tab opened to your new trial instance of Dynamics Customer Engagement. If you closed it, please re-open it. Once you hit it open follow the next steps as we prepare to extend the model.

• Click on the down arrow next to the heading Dynamic Health 365 (note the heading might be cut off a little). Then click on settings. You should see the following

• There are two ways that we can extend the model. First, we could select “Customizations” (under Customization heading) above. This would allow us to modify the system installed based solution. While you will see all entities under this option and be able to change them, it is not recommended that you change the at this level, because your goal is to distribute your solution to others. So instead, please select the “Solutions” option (under Customization heading). You should see something like the following, based on your trial it could be different, or if you have installed other solutions already.

Create a New Solution

In the above picture you can see the actual accelerator solution. However, we do not want to change this solution directly. Our goal is to create a new solution that we can distribute to customers via AppSource, not modify the base accelerator solution. So now we need to create a new solution

• Click on New and fill in the information you want for your solution. The screen should look like this.
• Give a Display Name, which is the named used when rendering, the Name (Unique).
• For publisher click on the little search icon and either click new to create a new one or click on any existing publisher name. For your real application you will want to create your own publisher
  • To do this. Click on the Search icon on the right of the publisher line
  • Click Load More Results in the pop up

• • Click New on the Search / Select screen

• • Create your Publisher

• • Note: The prefix you use here is important. You should think of one that matches both your company strategy. This will help identify items that you create and that your company publishes on AppSource.
  • Click Save and Close
  • It will bring you back to Search / Select screen but should have your new Publisher selected. If not please select it
  • Click Add

• Give it a version and leave config page blank.
• Then Click the Save Icon (it does not say save). If you accidentally click Save and Close, it will take you back to your “All Solutions” view screen. Just double click your new solution to come back to this screen
• I have created my MGHI Patient Care application per the below configuration

Create New Entities

In this first step we will be creating new entities. These new entities will help focus our model driven application.

• Click on Entities. You will see that when you do no entities are listed. That is because we have no added any “existing” entities to extend or created any new entities yet.

• Click on New, to add a new entity. Adding a new entity is the first way to extend the Health Accelerator Model. Effectively you end up with three parts now to your model. The Dynamics 365 base entities, the Health Accelerator extensions and now your Private Extensions. The following screen should appear. I am creating a new Patient Travel History entity to track any recent travel details to help with diagnosing issues.

• Let me go through some of the key items on the screen
  • Display Name: The rendered visualization of the name in the UI. When you are looking at a specific instance of something you see the Display Name
  • Plural Name: When you have a specific Site Map Icon, it uses the Plural Name to represent how to quickly view a list of all your “instances” of that entity
  • Name: The name has two parts. The prefix, which is defined when you create a new Publisher. Remember when we created your application, you either selected an existing or created a new Publisher. The prefix is set there. This insures that all entities that you want to be associated to an application are easily identifiable. The rest of the Name should be automatically populated when you type in the Display Name.
  • Data Source: leave blank for now as these are not virtual entities. Virtual entities are entities that are stored on another system but are defined here and accessed remotely.
  • Primary Image: leave blank for now. But this represents the icon that you want displayed in the menu’s and forms for this entity
  • Color: leave blank for now
  • Description: it’s a good idea to provide solid descriptions when the time comes
  • Areas that display this entity: Remember what I said about “Plural name”. Each one of these “areas” represents a drop down in the menu of the Dynamics 365 container that renders in your browser. If you want an entity to be listed and thereby accessible from that menu, click those that you want to add it to. If you want to create your own “area” we will show you how to update the sitemap later. For now, let’s select Settings, just so that we can see our entity appear somewhere.
  • Communications and Collaboration: I am not going to go into detail just yet on this. However, these settings enable you to provide greater focus to how the entity is used within the system, business workflows, mail flows, activities etc.
  • Once you have populated this Tab, click on the Primary Field Tab. The Primary Field can only be text. You will want it to be meaningful if required, if you do not want to require it, because a required string field doesn’t make sense for your entity then you can set it to optional. In my case I am defaulting it to the Destination as a single string. This means this field will be very simple and I will just type in where they say they went in this line.

• Click the Save Icon (not Save and Close). It will tell you it is creating the entity, which may take a few moments. Once again here you just want to save it, not save and close. If you do save and close, you will need to go back to the new entity under the Entity left menu option and double click it to open this screen

So far, we have created a new entity and that entity will have at most the Primary Field attribute or “field”. But now we want to add more fields to the new entity to make it useful for our application.

• Once the screen above is opened again, click on Fields on the left menu under Common.
• One the screen is open, select the View drop down on the top middle and choose Custom. We only need to see the custom fields that we are adding. By default, it will show all fields, so you would see all the system generated fields and the default Primary Field that you created. The Primary Field is not considered a custom field like any fields you add after defining the entity.

• Click New and it will bring up the Field definition screen. I am not going to go through creating many entities as the process is the same, but for each field that you want to add, you will need to provide the following
  • Display Name: The label used when rendering the field on the screen
  • Name: the true name of the field. Here you will notice the prefix again. The name will auto populate when you type in the Display Name.
  • Field Requirement: Here is where you can enforce if its required or not
  • Field Security: will discuss later, but it is used to lock down specific fields to specific people or roles
  • Auditing: whether you want to audit(track) changes to the values in this field, for an instance of the entity this field belongs too
  • Description: it’s a good idea to provide a solid description
  • Data Type: the data type of field it is
  • Field Type: the type of field. These options change based on the Data Type
  • Format: options will depend on the Data Type and Field Type
  • Maximum Length: only available on text field Data Types

• Once you have filled in the details, you can click Save and Close. This will take you back to the Fields list of the entity, where you should now see this field listed under the Custom view. In my case I created a few fields related to details of the Car entity I created.

• Continue to create fields based on your needs

Create New Relationships

Now that you have created new entities you have to decide on the types of relationships that you want to build. Model driven applications are highly driven by the relationships that exist between entities. Let’s look at a couple of examples. For a deeper look at creating relationships please visit our documentation here.

Let’s take a standard example, where I have just created my first custom entity, in this case it was called “Car”. For this discussion let’s assume that this entity has information about the cars that a person owns. In this example a person is equivalent to “Contact” in the standard Dynamics 365 Common Data Model. What we want to do is create a relationship between Contact and “Car”. In our example we will further assume that each Contact or person, can own more than one Car. This would mean that we have a 1 to Many relationships between Contact and Car. In Power Apps for Customer Engagement this type of relationship is called a 1:N.

What we want to enable is a 1:N relationship between Contact and Car, so that we can leverage our model and therefore our application, to assign one or more Cars to each Contact. To do this we need to first look at the second way to extend the Common Data Model using existing entities.

Extending the Model with Existing Entities

Before we can complete our previous Relationship example we will need to extend our new Application by adding the existing entity of Contact to it. This will allow us to create the relationship that we need without modifying the base solution of the system as mentioned before. We only need this relationship to exist if our application is installed.

Note: We are adding Contact to our example application because in the Health Accelerator Contact is leveraged for Patient, Practitioner and Related Person at this time. Within that entity we added a Contact Type option set. So right now we are effectively adding Patient. If you want to learn more, please check out the reference API documentation link at the bottom of this blog post.

• Once again, we need to open the Settings \ Solutions screen and double click to open our Solution
• Once opened, click on Entities on the left side. If you added more than 1 entity, click on the dark triangle next to the word Entities to expand the list in the menu itself

• Click “Add Existing” from the menu above (right next to New). This will prompt you to select whatever existing items that are available to the system such as entities, dashboards, plugins and more. For now, we are only focused on adding Contact
• Once you scroll down and select Contact, the OK button will highlight. Click OK to move to the next screen

• Next, we will be prompted to select which artifacts that are related to Contact do we also wish to take a dependency on for our application. You would normally select allot more of these than we will for this example. In future blog posts in this series, we will be demonstrating how to build applications, which will require more.
• In this case I just want the entity and the entity metadata (check box at the top) which are all the default items I need. Finish is already highlighted, so click FINISH

• Once this is done, you should now see Contact under the Entities menu item on the left and in the entities list for our application

Completing our Relationship Example

Now that we have added Contact to our solution we can complete this example by creating the necessary relationship.

• If you haven’t already click on the dark triangle next to the word Contact in the menu, as in the image above. You will see a list of items underneath it; Forms, Views, Charts, etc. One item in particular is important 1:N Relationships. Let’s add our new relationship. Remember this relationship will allow us to build an application that assigns 1:N (or one to many) Cars to each Contact (person)
• Click the 1:N Relationship menu item on the left
• Change the View to Custom, as you have with the other screens. You should see the following, an empty set of relationships

• Click new 1-to-Many Relationship from the menu (first option)
• In the following screen, which I have filled out, let’s review the details

• Primary Entity: dictates the 1 relationship in the 1:N relationship direction
• Related Entity: dictates the N relationship in the 1:N relationship direction
• Display Name: the rendered name on the screen
• Name: the unique name of this relationship (you can have many 1:N relationships with the same related entity, so they need to be unique each time)
• The rest of these fields I will cover in more detail when we dive into building applications
• Click Save and Close

Finishing Up

One we have created the relationship there is one more important thing to point out. When you created the 1:N relationship, you started from the Contact entity. You could have started at the Cars entity and created an N:1 and it would have done the same thing. In this case while we start at Contact if you go to the Cars entity and click the dark triangle to expand it. Then click on N:1 Relationships menu item, you will actually see that the relationship is listed there as an N:1. In this case I have filtered again by Custom so I can only see what I created. This is intentional so that the directionality of the relationship is correct.

Now that we have created our relationship, we have demonstrated one way in which we can extend the schema.

Extending the Model with New Fields for Existing Entities

One additional example of extending the model would be to add new fields to existing entities such as contact. Image that you wanted to add more fields that you used to support your implementation of Patient. You would follow the same instructions given to add fields to your new entities. Those fields added to existing entities would show up under the “Custom” view with your prefix and name. This associates those fields only to your application and therefor only exist when your application is installed.

Summary

This first look at how to extend the Dynamics 365 Health Accelerator was focused on extending the Common Data Model for Health to create your own private Common Data Model extensions used by your own business application. We focused on how this was accomplished within the Dynamics 365 Power Apps for Customer Engagement UI. We created new entities, we added existing entities and we created new relationships between those entities. All of this exists as part of our custom application and are therefore part of our private Common Data Model extensions. Next, we will continue this series and focus on how to extend the Common Data Model by using the Power Apps for Canvas based applications UI.

Links for Review

• Announcement of the Dynamics 365 Health Accelerator
• Basic Configuration for the Dynamics 365 Health Accelerator
• Common Data Service for Apps
• Common Data Model
• Building Model Driven Applications
• Building Canvas based Applications
• Developer Guide for Dynamics 365 for Customer Engagement
• GIT for the Microsoft CDM (Common Data Model)