Personal Community provides a series of patient facing workflows, designed to meet the needs of the global customer base. Regional needs for additional displays and workflows may be identified to best suit the region. In the event that a regional need is identified, and it is not in the global product roadmap, regions may create custom applications that can be embedded into Personal Community.

These custom applications can be added to the application as:

• New main menu option (displayed on the unauthenticated page, authenticated page, or both)
• New secondary menu option within an existing main menu.

These custom applications need to adhere to the intended use and best practices outlined below. 

This feature is intended to be used by regions to develop region-specific displays and content for Personal Community.  It is not intended to change the fundamental feature set of the application.

2.1. Sample Use Cases

The custom application feature is designed to support a variety of use cases.  These can include, but are not limited to the following:

• Displaying additional static content, such as educational resources to patients.
• Displaying additional clinical data available to Personal Community, such as insurance information, to patients.  This workflow supports organizations using existing Personal Community APIs to retrieve this data.
• Displaying additional data available to Personal Community using custom REST APIs.

2.2. Considerations and Limitations

2.2.1. Considerations

Regions building custom applications are the owners of the application and its functionality.  This includes:

• Maintenance of the application.  This includes all bugs and enhancement requests for the application.
• Support for the application.  Global product is not responsible for supporting any issues that arise within the content of the regional application.
• Upgrading the application.  This will need to be coordinated with all Personal Community upgrades moving forward.
• Deprecating the application when global functionality is released.

2.2.2. Limitations

The custom application feature has the following limitations:

• Applications may not alter the intended use statement for Personal Community.
• Applications introducing new workflows must be verified by risk and clinical safety prior to customer agreement.
• Applications are currently limited to Angular micro front-end applications.
• No role based access; all custom applications will be accessible by both patient and proxy.
• Location restrictions; applications may only be added to the main menu and sections that have an existing secondary menu option.
• Dynamic routing; while dynamic routes are supported, there is a limitation currently in how these routes behave with the standard refresh functionality.  If a user refreshes on a custom application that uses dynamic routes, they will be returned to the main page of the custom application.

3.1. Design Principles

As this application will be embedded into Personal Community, it should align with the design principals and best practices for this product. When creating your application, ensure that the following conditions have been met:

• Application is WCAG 2.2 Level AA compliant
• Application has a responsive design so it can be viewed on desktop, tablet, and mobile devices
• Application passes clinical safety review
• Application passes risk assessment review

3.2. Technical Requirements

The custom application feature of Personal Community uses the Angular Module Federation to inject micro front-ends into the application.   In Angular, the term "micro front-end" refers to the architectural strategy of dividing a large, massive Angular application into more manageable, independent front-end modules. Each module can be built, deployed, and maintained independently, and each represents a particular feature or functionality of the program.  

To allow your application to be included in the Personal Community Module Federation, it must be converted to a micro front-end.  This can be done by running the following two commands on your finished Angular application:

1. npm i -g @angular-architects/module-federation@14.3		
   

2. ng add @angular-architects/module-federation@14.3 --type remote   
   

After converting to a micro front-end, the application must be exposed properly to be embedded in Personal Community. The following steps assume that your application uses NgModules, has an AppModule and AppRoutingModule, and is not a standalone component. If it is a standalone component, you can run step 1 with "app" instead of "feature" to generate necessary files.

1. First, you will need a FeatureModule and FeatureRoutingModule that contain all the application code. To create those, run:
   

   1. ng generate module feature --routing --project=<app-name>
      

   2. ng generate module feature --routing --project=<app-name>
      

2. In the newly created web-pack.config.js , update "exposes" as follows:
   

     exposes: {
       './FeatureModule': './<path-to-app>/src/<path-to-feature-module>/feature.module.ts',
     },
   

3. Finally, move your application code so that it is contained and defined by the FeatureModule and FeatureRoutingModule. To support this functionality, FeatureModule and FeatureRoutingModule effectively act as AppModule and AppRoutingModule, respectively. 
   1. Move any route associated with your app so that it is defined in FeatureRoutingModule.
   2. Move any component used by your app so that is is declared in FeatureModule.
   3. Your AppRoutingModule should contain the following forward:

      1.   {
             // Use empty route to immediately redirect to the FeatureModule
             path: '',
             loadChildren: () =>
             import('./<path-to-feature-module>/feature.module').then((m) => m.FeatureModule),
           },
         

4.1. Installing the Custom Application in your Web Server

Your custom application needs to be accessible from a web server that your Personal Community instance can communicate with. 

Options for hosting your application include:

• As a web application within your Personal Community environment
• Directly from your webserver.  Note, if you are using a webserver on another environment you will need to configure the webserver to accept cross-orgin calls for this application.

It is important that your application is served over the same protocol as your Personal Community application. For a production system, all applications should be served over HTTPS.

4.2. Adding Custom Application Label to i18n Files

All strings displayed to patients in Personal Community come from the i18n files.  These files allow the application to easily support multiple languages and customized strings in the application.  As part of this feature, you will need to create a new key value pair to represent your custom application name. This value will be displayed as the title for the main or secondary menu item, so should be a short string or label.

The en-us.json file should always be updated as this is the default file used if keys are not found in other i18n files.

To add your application name to the i18n files:

1. Navigate to <install-dir> /csp/public/assets/i18n
2. Open the en-us.json file and find the "custom" section
3. Within this section, add your key value pair.  For example, "CUSTOM_RESOURCEAPPLICATION": "Resources"
4. Add this value with its proper translation to all i18n files in use for your implementation.

4.3. Adding Custom Icons for your Application

Applications that appear in the main menu are displayed with an icon when viewed on a desktop browser.  By default, Personal Community provides a standard icon that can be used.  This icon can be replaced with another Material Design icon in SVG format by completing the following:

1. Navigate to <install-dir> /csp/public/assets/images/custom.
2. Save your icon to this directory

4.4. Adding Custom Applications in the Workbench

On the available applications list, the Status column indicates whether or not the application is currently enabled and available for use in Personal Community, and the  Actions  column indicates what actions can be taken against this application.

Actions include:

• Settings - Displays the current settings for this application.
• Edit - Opens the Edit Application workflow to update application settings
• Delete - Deletes the application.  A deleted application cannot be recovered.

To add a new application to Personal Community:

1. Log into the Workbench as a user with the   Configuration Manager   role.
2. Go to the   Configuration Application   page ( Setup  >   Configuration Application ) and select the Embedded Applications tab. 
3. To add your application, click the  Add Application.
4. Complete the full list of settings and click  Save.