Personal Community is an application that communicates with an instance of HealthShare Unified Care Record (referred to hereafter as “Unified Care Record”) to receive its patient data. (Personal Community relies on InterSystems IRIS for Health™ for its underlying functionality.) Personal Community uses the Unified Care Record to communicate with a Master Patient Index (MPI), which may be HealthShare Patient Index or another MPI.

All Personal Community member and Workbench user activities use the interoperability production to communicate with the Unified Care Record. For example, Personal Community receives its patient data from the Unified Care Record Registry and Access Gateway. This includes identifying data for patients, which consists of each patient’s medical record number (MRN) and its assigning authority. All data aggregation occurs on the Access Gateway, such as with data for terminology and consent.

Here is the Personal Community architecture:

When new members (patients or their proxies) enroll in Personal Community, they are added to the Unified Care Record registry.

When a member attempts to log in to Personal Community, the following occurs:

1. Personal Community looks up the member by   executing a patient search   in the Unified Care Record Registry.

2. The Unified Care Record   returns patient identifiers   and demographics.

3. After a successful login, Personal Community   requests patient data   from the Unified Care Record Access Gateway (which passes the request along and then receives an answer).

4. When Unified Care Record   returns patient data , the production receives it and then passes it to the Personal Community public application; the member can then view their medical record.

The member, who is logged in, can then perform various actions that the product supports on your site, such as requesting appointments and downloading medical records.

As patient identifiers are updated in the Unified Care Record, the Registry   sends PIX notifications   to Personal Community.

Prior to installing Personal Community, your project team must make several business decisions:

• The server on which Personal Community is being installed.

• The port number on which Personal Community will be available.

Record the decisions you make, as you will need to refer to these at subsequent points in the installation and post-installation process. These points are:

• While running the installation program from the operating system.

• While running the Installer Wizard in the HealthShare Unified Care Record Management Portal. 

• When configuring default settings for Personal Community.

Make sure the following prerequisites have been met before you attempt to install Personal Community:

• Personal Community must have access to an instance of Unified Care Record.

• Know the hostname and port number that Personal Community will use.

• You must have a license key.

• It is helpful, but not required that you know the name that your project team has chosen for Personal Community. If you have this information, you can set various values based on that name.

This documentation frequent references to the paths, directories, and files that are part of the Personal Community installation. Because these paths usually include six or more levels of directories, <hspc-home>   is used to reference the first directories in each path:

<hspc-home>

is equivalent to:

<install-dir> /hscommunity-content/ <local-namespace> /public

where:

• <install-dir>   — Specifies the location where Personal Community has been installed. For example, this documentation uses C:\InterSystems\HSPC\ .

• <local-namespace>   — Specifies the namespace that is created for Personal Community during installation. For example purposes, this documentation uses the namespace   HSPC .

InterSystems provides class reference documentation for the methods and classes referenced throughout this guide. To view the class reference documentation, go to the following URL for Personal Community:

<hostname> : <port-number>   /csp/documatic/%25CSP.Documatic.cls

Where:

<hostname>   — The machine where Personal Community is installed.

<port-number>   — The port number of the Personal Community web server.

Select the Personal Community namespace from the dropdown, and then navigate to the class.

Personal Community is supported on the following operating systems:

• Red Hat Enterprise Linux  7.9, 8.x, 9.0
• SUSE LInux 15 SP3
• Ubuntu 22.04
• macOS 11, 12 for x86-64 - Development builds only

Personal Community is a public-facing application, and as such strives to support as many browsers as possible. The tables below outline the browsers that Personal Community is tested on, supported on, and not supported on.

Tested

Personal Community was tested on the following browsers and mobile devices. Unless indicated otherwise, the most recent version was used:

The mobile application was tested on the following mobile operating systems:

Supported

Personal Community is additionally supported on the following browsers. InterSystems commits to fixing any critical issues that arise on these browsers:

Not Supported

Personal Community is not supported on the following browsers:

The Workbench is supported on the following browsers:

Each version of Personal Community works with the following versions of Unified Care Record:

*See Important 

Each version of Personal Community works with the following versions of Care Community:

To install Personal Community on Windows:

1. Copy the installation kit to the machine where you are performing the installation.

2. Unzip the file, if necessary.

3. Launch the installation program with administrative rights.

4. When Windows prompts you to run the installation program, confirm that you do.

5. On the   License Agreement   screen, review and accept the terms of the license agreement.

6. On the   Instance Name   screen, specify the name of the Personal Community instance that you are installing. (If you are performing an upgrade from a prior version of Personal Community, be sure to select the correct instance when prompted by the installation program.)

   IMPORTANT

   Record this instance name, as you will need it later.

7. On the   Setup Type   screen, select the desired Personal Community installation type. Typically, this is   Standard . (Select   Client   only if you are connecting to an existing Personal Community instance for development purposes.)

8. Also on the   Setup Type   screen, specify the destination directory for the installation. Record this location — you will need it for various configuration activities for Personal Community. This location will be referred to hereafter as the   installation directory   or “ install-dir ”.

   IMPORTANT

   Record the name of this directory, as you will need it later.

9. On the   Install Web Gateway   screen, specify whether or not to install the Web Gateway and configure external web servers for it.

   IMPORTANT

   The installation program offers the option of installing a private Apache web server, which is useful for demo and development systems. For production systems, you must use the Web Gateway and an external web server. (See the   InterSystems Supported Platforms   document for a list of production web servers that are appropriate for the operating system and hardware configuration you are using.)

10. On the   Enter Port Numbers   screen, choose ports for the superserver and the web server.

    IMPORTANT

    Record these port numbers, as you will need it later.

11. On the   Initial Security Settings   screen, specify the security level for the installation, where the choices are   Normal   or   Locked Down . For details about the different initial security settings, see the “ Initial InterSystems Security Settings ” section of the   Installation Guide .

12. On the   Please enter user credentials   screen, specify the operating system account under which Personal Community runs. This can either be the operating system account (“SYSTEM”) or a particular user on the system. If you choose to use the SYSTEM account, the installation program still creates an account for the user who performs installation; if you choose a user on the system, the installation program does not create the SYSTEM account.

13. On the   HealthShare Users Configuration   screen, specify the password for various users: _SYSTEM, Admin, SuperUser, CSPSystem, and the user performing the installation. For information about these accounts, see “ Predefined User Accounts .”

    IMPORTANT

    Record these passwords for future reference and store them in a highly secure location.

14. Finally, on the   Ready to Install the Program   screen, select   Install .

To install Personal Community on Linux or Mac OS:

1. Copy the kit to the machine where you are performing the installation.

2. Unzip the file, if necessary.

3. As root or using   sudo , launch the installation program.

4. The program will display a list of all the instances of InterSystems products that are installed on the system for reference. At this point, you will be prompted to enter a name for the Personal Community instance. When asked to confirm this choice, do so. (If you are performing an upgrade from a prior version of Personal Community, be sure to select the correct instance when prompted by the installer.)

   IMPORTANT

   Record this name, as you will need it later.

5. Specify a destination directory for the installation. This must be the full pathname of a physical directory, not a symbolic link. When asked to confirm this choice, do so.

   IMPORTANT

   Record the name of this directory, as you will need it later.

6. Specify the level of initial security settings for the instance, where the choices are   Normal   and   Locked Down . For details about the different initial security settings, see the “ Initial InterSystems Security Settings ” section in the documentation for the   Installation Guide .

7. Specify the owner of the instance.

8. Specify and confirm the password for all the following accounts within Personal Community: _SYSTEM, Admin, SuperUser, CSPSystem and the user who is performing the installation. For more details about these accounts, see “ Predefined User Accounts .”

   IMPORTANT

   Record this password, securely, for future reference.

9. Specify the name of the operating system group with privileges to start and stop the instance.

10. Specify whether or not to configure additional security options. These are:

    • The group for the underlying InterSystems IRIS for Health™ processes.

    • The user for the IRIS superserver and its jobs.

      IMPORTANT

      Record these selections, if you make them, as you will need this information later.

11. Specify the port number for the IRIS superserver.

    IMPORTANT

    Record this port number, as you will need it later.

12. Specify the port number for the private internal IRIS web server.

    IMPORTANT

    Record this port number, as you will need it later.

13. Specify whether or not to configure the Web Gateway to use an existing web server.

    IMPORTANT

    The installation program offers the option of installing a private Apache web server, which is useful for demo and development systems. For production systems, you must use the Web Gateway and an external web server. (See the   InterSystems Supported Platforms   document for a list of production web servers that are appropriate for the operating system and hardware configuration you are using.)

14. Specify whether or not to enter a license key.

    Note

    InterSystems recommends that you activate a license key in the Management Portal immediately after installation.

15. After reviewing the selections, confirm that you wish to proceed with the installation. The installation program then runs, providing information about its progress as it does so.

To activate a license key:

1. Log in to the Management Portal as a user with the  %Manager  role.

2. Go to the   License Key  page ( System Administration  >  Licensing  >  License Key ).

3. On that page, select  Activate New Key . This displays the  Activate a New License Key  dialog.

4. On the  Activate  dialog, specify the license key to activate.

5. Select  Activate .

For more details about this process, see further instructions in the System Administration guide .

To perform setup tasks, use the Personal Community Installer Wizard:

1. Log in to the Management Portal.

2. Run the HealthShare   Installer Wizard :

   1. On the Management Portal home page, select   HealthShare . This displays the   HealthShare Management Portal .

   2. In the banner of the   HealthShare Management Portal , select   Installer Wizard .

3. In the   Installer Wizard , select   Configure Personal Community . This displays the   Configuration   page for Personal Community.

4. On this page, specify values for the following fields:

   • Local name   — Required. The name of the Personal Community namespace (and database). (Subsequent examples in this documentation refer to the   HSPC   namespace.)

     IMPORTANT

     • The maximum length of the namespace name is 31 characters.

     • InterSystems recommends that you do not use “HSPortal” as the name of the namespace. This is because “HSPortal” is the name of the package for Personal Community; choosing this name may result in future issues, such as overwritten data during upgrades.

   • Network Name   — Required. The unique identifier for Personal Community on the network. The Installer Wizard populates this field with a string that is the network hostname, a colon, and the value of   Local name , such as   MyHost:HSPC ; you can, but are not required to, use this string.

   • Description   — Optional. Any additional information about the local copy of Personal Community.

   • Disabled   — Whether or not the local copy of Personal Community is available for use. Personal Community is enabled by default.

   • Production   — Required. The name of the business production for Personal Community. The Installer Wizard populates this field with a string that combines the value of   Local name   and the string   PKG:HSCOMMProduction , such as   HSPCPKG:HSCOMMProduction ; you are not required to use this string.

   • Template   — Required. The template for the Personal Community production. Select the   HSPortal.Production.SampleProduction.PortalProduction   template.

   • Alternate Database Location   — Optional. The default location for the production database,   IRIS.DAT , is   installDir /mgr/ localName . To specify a location for the database other than the default, enter the alternate location in the   Alternate Database Location   field. If you specify an absolute location, then that location will be created if it does not exist. Your database will be in   alternateDatabaseLocation / localName . If you specify a relative location then the database will be created in   installDir /mgr/hslib/ alternateDatabaseLocation / localName .

   • Registration ID – Optional. A unique value that identifies this configuration. It will be generated automatically if you leave this field blank. If you wish to enter a specific value, you may enter it here. Once a configuration has been saved, this value cannot be changed.

   • Enter a Hub Host   — Required. The name of the machine where the Unified Care Record Registry is located.

   • Enter a Hub Port   — Required. The web server port number on which the Unified Care Record Registry accepts connections.

   • Enter a Hub Name   — Required. The namespace of the Unified Care Record Registry, such as   HSRegistry .

   • Connect to Hub Securely   — Required if this is a production system. Optionally select it for a development or test system.

     • The web server on your Registry instance should be configured to only allow secure connections to the Registry.

     • You should have an SSL/TLS configuration on this instance that can communicate with the Unified Care Record Registry (see “ Using SSL/TLS ” in the “Setting Up Secure Communication in Unified Care Record” chapter of   Securing Unified Care Record Instances ). This SSL/TLS configuration should have the same name as the SSL/TLS configuration on the Unified Care Record Registry, as all instances in a federation share a single service registry, and the HSRegistry service registry identifies which SSL/TLS configuration to use.

     Once you select   Connect to Hub Securely , enter the SSL/TLS configuration in the   SSL Configuration   field that appears. Now, the Hub endpoint URL will be created using “https” rather than “http”, and the identified SSL/TLS configuration will allow the Gateway to connect to the Unified Care Record Registry securely at initial startup.

   • Initial Hub End Point   — Required. The web address for the HealthShare Registry. The Installer Wizard populates this field; you can, but are not required to, use the auto-populated string. The string is of the form:

     protocol :// registry-host : registry-port /csp/healthshare/ registry-name /services /HS.Hub.HSWS.WebServices.cls

     where the portions of the address in italics are:

     • protocol   —   https   or   http , depending on whether you selected the   Connect to Hub Securely   option.

     • registry-host   — The name of the machine where the Unified Care Record Registry is located.

     • registry-port   — The port number on which the Unified Care Record Registry accepts connections.

     • registry-name   — The namespace of the Unified Care Record Registry.

     For example, a Registry has an address such as:

     http://RegistryHost:57772/csp/healthshare/HSREGISTRY/services/HS.Hub.HSWS.WebServices.cls
     
     
     
     
     

5. Select   Save   at the bottom of the page. Your configurations should now appear in the   Defined Configurations   table.

6. In your configuration’s row of the   Defined Configurations   table, select   Activate . This displays the   Activate Configuration   dialog.

7. In the   Activate Configuration   dialog, select   Start . This sets up the Personal Community namespaces, databases, and production mappings.

8. When activation is completed, the dialog displays an   Activation Done   message. Select   Close   to dismiss the dialog.

To specify system default settings for Personal Community:

1. Log in to the InterSystems IRIS for Health Management Portal.

2. Switch to your Personal Community namespace.

3. Go to the   System Default Settings   page ( Interoperability   >   Configure   >   System Default Settings ).

4. On the   System Default Settings   page, specify the   Setting Value   for each element of each setting as required:

   1. Select the row for the setting and select the   Edit   button at the top of the age. This displays the   Edit System Default Setting   page.

   2. In the   Setting Value   field, enter the value for the setting.

   3. Select   Save .

The following are the Personal Community system default settings, which are listed in the sample file that appears at the end of this section. Each setting is listed by its name, with the value of the setting’s   Item Name   column included, if it is required for disambiguation.

SMTPServer

The SMTP server that Personal Community uses to route mail.

From

The email address from which Personal Community sends mail. For this setting’s value, specify a complete email address, including a domain.

Device

The name of the device used by the   HS.IHE.PIXv3.Consumer.Operations   business operation.

PIXv3ReviseTarget

The process that handles the PIX notifications that Personal Community receives from the Unified Care Record Registry. Do not change the value of any elements for this setting from their defaults. 

ExcludeIdentifierTypes

The assigning authority identifier types to be excluded as patient identifiers during the PIX consumer process. The defaults are   DN ,   LN , and   XX .

XDSbRegistryServiceName

The name of the service used by the   HS.IHE.XDSb.Consumer.Operations   business operation.

DefaultEnrollingUser

If your organization will use automated enrollment, you must supply a value for this setting. Choose a value that will be distinct from any other user identifiers and that will be appropriate to the purpose: for example,   DefaultEnrollingUser   itself may be adequate. (The identifier for the user does not have to be defined elsewhere.)

AddUpdateUser

The user account that Personal Community will use to add and update patients in the Unified Care Record Registry.

AddUpdateUserRoles

The role(s) associated with the   AddUpdateUser   setting (see previous entry).

SearchUser

T he user passed to the Unified Care Record Registry web service who represents Personal Community to search for patients.

SearchUserRoles

The role(s) associated with the   SearchUserRoles   setting (see previous entry).   SearchUserRoles   can be used as consent groups in consent policies for the Unified Care Record.

ServiceName

User

The user passed to the Unified Care Record Access Gateway to fetch patient data.

UserRoles

The role(s) associated with the   UserRoles   setting (see previous entry).   UserRoles   can be used as consent groups in consent policies for the Unified Care Record.

The following tasks establish the Personal Community web applications and start Personal Community:

1. Log in to the Management Portal.

2. On the Management Portal home page, select   HealthShare .

3. From the HealthShare menu, select the Personal Community namespace. This displays the management page for that namespace.

4. On that page, select   Initialize Community . This displays the   HealthShare Community Initialization Wizard .

5. In the   HealthShare Community Initialization Wizard , create the public web application for Personal Community:

   1. Select   Public Web Application . This displays an   Enter a web application   field.

   2. In that field, specify the name of the public web application, beginning with a leading forward slash. For example, the name for this web application might simply be   /public . (The Personal Community documentation uses this as the sample application name for the public application.)

   3. Select   Create application .

   This creates the Personal Community web application with the appropriate settings.

6. Also in the   HealthShare Community Initialization Wizard , create the Workbench web application:

   1. Select   Workbench Web Application . This displays an   Enter a web application   field.

   2. In that field, specify the name of the Workbench web application, beginning with a leading forward slash. For example, the name for this web application might simply be   /workbench . (The Personal Community documentation uses this as the sample application name for the Workbench.)

   3. Select   Create application .

   This creates the Workbench web application with the appropriate settings.

7. While still in the   HealthShare Community Initialization Wizard , select the management page for the namespace you have created; the link for this is at the top of the page. For example, if you created a   HSPC   namespace, the choice is   HSPC Management . This displays the management page for that namespace, which appears on the right near the top, such as   HSPC Management .

8. On that management page, select   Interoperability Management   at the top of the page. This displays the   Interoperability   page for this namespace.

9. On that page, go to the   Production Configuration   page (by selecting   Configure   >   Production ).

10. On the   Production Configuration   page, select the   Open   button. This displays the   Finder Dialog , which lists packages that you can open.

11. Select the package associated with the production you created in the   Installer Wizard . In the example case, this is   HSPCPKG . Opening this package displays a list of classes.

12. Next, select the class that is associated with the production you created. In the example case, this is   HSCommProduction . Selecting the class displays   Production Configuration   page for the production.

13. At the top of the   Production Configuration   page, select the   Start   button.

14. Select   OK   on the confirmation dialog. This starts the Personal Community production.

15. If Personal Community is mirrored, also make sure that the Reports production is running. If you need to start it, do so in the same manner as for the Personal Community production.

16. You can verify that Personal Community has been synchronized with the associated Unified Care Record instance. To do so:

    • Log in to the Management Portal for Unified Care Record.

    • Click   HealthShare  >   HSREGISTRY   >   Other Management  >   Synchronization .

    • Confirm that the   HSSYS   namespace for your Personal Community host and port is listed.

Personal Community is now up and running. The URL for the public application has the form:

http:// <hostname> / <public-web-application> /index.html

where:

• <hostname>   is the network identifier for the device on which you are running Personal Community, which you specified in the installation program.

• <public-web-application>   is the web application specified in step 5b, above.

The URL for the Workbench has the form:

http:// <hostname> / <workbench-web-application> /HSPortal.Workbench.UI.Home.zen

where:

• <hostname>   is the network identifier for the device on which Personal Community is running, which you specified in the installation program.

• <workbench-web-application>   is the web application specified in step 6b, above.

For example, if you have installed Personal Community on a machine whose hostname is   PersonalCommunityHost   and the names of its applications are   /public   and   /workbench , then the URLs are:

• Public application —   http://PersonalCommunityHost/public/index.html

• Workbench application —   http://PersonalCommunityHost/workbench/HSPortal.Workbench.UI.Home.zen

As part of initial Personal Community configuration, you must specify an authentication domain for Personal Community to use. This can be an existing authentication domain or one that you create specifically for Personal Community. An   authentication domain   specifies a logical grouping of users and controls a set of common characteristics. For Personal Community, the authentication domain controls the characteristics of Workbench users. These characteristics include:

• Default roles and groups. (At a minimum, the domain should allow the   HSPortal   roles to be assigned.)

• Association with a facility

• Required password pattern

• Password reuse policy

• Inactivity time limit

• Password lifetime

• Maximum number of failed login attempts

• Lost password recovery mechanism

• Use of two-factor authentication

• Use of an external authentication system, such as LDAP

• Use of an external authorization service

To create and specify the use of an authentication domain:

1. If you are not using an existing authentication domain, create a new one on the Unified Care Record from which Personal Community receives data. For background information on authentication domains, consult the Unified Care Record documentation: the “ Setting Up Security Domains ” chapter of   Securing Unified Care Record Instances .

   If you have multiple authentication domains, then you will most likely create a new, separate one for Workbench users. If you have a single authentication domain, confirm that its characteristics are appropriate for Workbench users; this will likely determine whether or not you create a new one.

2. In the Workbench, specify the authentication domain in use. (This requires that the Personal Community production is synchronized with the Unified Care Record Registry, which occurs automatically when the Personal Community production starts.) On the Workbench   Site Configuration Settings   page ( Setup   >   Site Configuration ), in the   Workbench user login domain   field, select the domain for Personal Community. Select the   Apply   button.

A Workbench administrator is a HealthShare Workbench user who holds all possible privileges — equivalent to a super user.

To create a Workbench administrator:

1. Log in to the Workbench as _SYSTEM, Admin, SuperUser, or the user who performed the installation, at http:// <hostname> / <workbench-web-application> /HSPortal.Workbench.UI.Home.zen .

   The password for each of these users is the one that you established in the installation program.

2. Within the Workbench, go to the Workbench Users page:

   1. Select the Setup tab.

   2. In the left pane, select User Management .

3. On the Workbench Users page, select Create User Account . This displays the Create User Account page.

4. On the Create User Account page , complete the fields as follows:

   • Login Domain — The authentication domain for Workbench users, as specified on the Site Configuration page.

   • Login ID — Required. The value that the user enters to log in to the Workbench. Each user ID can potentially have multiple login IDs, one for each authentication domain.

   • User ID — Required. The user’s identifier as displayed in the Workbench and that is a unique identifier in the Unified Care Record user registry. It need not be the same as the login ID.

   • Description — Optional. Text associated with this account.

   • First name — Required. The first name of the Workbench user.

   • Middle name — Optional. The middle initial or middle name of the Workbench user.

   • Last name — Required. The last name of the Workbench user.

   • User enabled — Whether or not the account is activated. The administrator must be enabled.

   • Change password on next login — Optional. Whether or not the administrator must change their password from the initial or current one.

   • Password and Confirm password — Required. The password associated with the account, entered twice to confirm it.

   • Full Workbench Administrator — A role granting the complete and maximum set of privileges that a Workbench administrator can hold, aside from processing tasks. Hence, granting the user this role grants the user all other roles except for Task Processing (which is also required) and Dashboards and Reports Administrator. For more information about Workbench roles, see the section “About Workbench Roles” in the guide Configuring HealthShare Personal Community.

   • Task Processing — A role granting the ability to perform activities on the Tasks tab. This role is required for a Workbench administrator.

   • Dashboards and Reports Administrator — A role granting the ability to view all data associated with Personal Community operational reporting.

     IMPORTANT

     This is a highly privileged role, as it provides access to reporting data for all organizations and clinical groups. Note also that this role differs from the Dashboards and Reports role; the Dashboards and Reports role, which is part of the general Workbench roles, grants only access to the Dashboards page.

   • Access to Clinical Group Dashboards — The clinical groups for which the Workbench administrator can view reports.

     If a Workbench administrator has all possible privileges, this field must list all clinical groups. However, clinical groups must exist before you can grant access to them. Hence, as you add clinical groups to Personal Community after you create the Workbench administrator, add the groups to this list so that the administrator can view meaningful use reports on them.

   • Access to Organization Dashboards — The organizations for which the Workbench administrator can view meaningful use reports. To grant a Workbench administrator full privileges, include all organizations in this field.

     If a Workbench administrator has all possible privileges, this field must list all organizations. However, organizations must exist before you can grant access to them. Hence, as you add organizations to Personal Community after you create the Workbench administrator, add the organizations to this list so that the administrator can view meaningful use reports on them.

5. Select Create User to create the Workbench administrator.

Once you have created a Workbench administrator, the administrator can start configuring features.

For Personal Community to be able to retrieve information from a Unified Care Record, it must have a facility defined in the Unified Care Record Registry. To establish a facility:

1. Log in to the Management Portal on the Unified Care Record associated with Personal Community.

2. On the Management Portal home page, select   HealthShare .

3. Select the namespace for the Registry (for example,   HSRegistry ).

4. Select   Registry Management   >   Facility Registry . This displays the   Facility Registry   page.

5. On the   Facility Registry   page, specify values for the following fields — and only the following fields:

   • Facility Code   — An identifier for the facility.

   • OID   — A unique identifier for Personal Community, which is based on an OID obtained from   HL7.org .

   • Create Assigning Authority   — When selected, specifies that HealthShare should also create an assigning authority with the same code as the facility. Select this.

   • Gateway Name   — Leave this field blank.

   • Tier   — The priority that Personal Community demographics receive in the Unified Care Record. For overview information about Personal Community and tiers, see the “ Specifying the Tier for Personal Community Data ” section of the “Other Site Options” chapter of the   Implementation Roadmap for HealthShare Personal Community ; for the process of specifying the tier, see the “ Specifying the Tier for Personal Community Data ” section of the “Other Site Options” chapter of   Configuring HealthShare Personal Community .

6. Select   Save   to save the facility.

7. Ensure that the Workbench lists the assigning authority that you have just created:

   1. Log in to the Workbench as a user with the   Configuration Manager   role.

   2. Go to the   Site Configuration Settings   page ( Setup   >   Site Configuration ).

   3. On the   Site Configuration Settings   page, in the   Application Settings   section, change the value of the   Assigning authority (AA)   field to the one you defined in step 5. (The AA code is the same as the facility code.)

   4. Select   Apply   to save the specified value.

To set up PIX notifications, the procedure is:

1. In the Unified Care Record Registry, create an OID for the Personal Community PIX Consumer:

   1. Log in to the Management Portal for the Unified Care Record as a user with the %Manager role.

   2. Select the namespace corresponding to the Registry.

   3. Go to   IHE Configuration   >   OID Registry .

   4. In the OID registry, select   Add OID . The dialog below will appear.

   5. Enter a unique code and a unique OID to represent your PIX consumer device. The code can be a string such as “MyCommunity.PIXv3ConsumerDevice”. For more information about OIDs, see the section “Managing the OID Registry” in the chapter “Unified Care Record Registries” of the guide   Running a HealthShare Unified Care Record .

   6. Select   Device   as the type.

   7. Select   Save .

2. Create a service registry entry for the Personal Community PIX Consumer Service in the Unified Care Record Registry:

   1. In the Management Portal for your Personal Community instance, locate the URL for the PIX Consumer Service, such as

      http://myorganization.com:57772/csp/healthshare/hspc/services/HS.IHE.PIXv3.Consumer.Services.cls
      
      

   2. In the Management Portal for the Unified Care Record, select the namespace for the Registry and navigate to   HealthShare   >   Registry Management   >   Service Registry .

   3. Select   Parse WebService URL .

   4. In the dialog that appears, enter the URL that you located in step a.

   5. Select   OK . This displays the dialog for creating a new service registry entry, with the   Host ,   Port , and   URL   fields already populated.

   6. In the   Name   field, enter a unique value, such as “MyCommunity.PIXv3.Consumer”.

   7. In the   Device   field, Code for the OID you created earlier.

   8. In the   Device Function   field, enter   PIXv3.Consumer .

   9. In the Username Token Profile, enter the credentials needed to communicate with the Personal Community instance, such as "HS_Services".

   10. Select   Save .

3. In the Management Portal for the Unified Care Record, add an entry to the   PIX Notification Registry :

   1. Go to   IHE Configuration   >   PIX Notification Registry .

   2. Select   Add Entry . The dialog below will appear.

   3. In the   Consumer Device Code   field, select the code for the OID that you created earlier.

   4. Leave the   Domains   field blank.

   5. Make sure   All Domains   is selected.

   6. Select   Save .

For the PIX operation in the Unified Care Record Registry (typically PIXv3.Notification.Operations), InterSystems recommends changing the default value of the   Reply Code Actions   setting to:

E=RF

In the Management Portal for the Unified Care Record:

1. Go to the Unified Care Record Registry namespace.

2. Go to the   Production Configuration   page ( Interoperability   >   Production ).

3. Locate the PIX business host, such as PIXv3.Notification.Operations.

4. In the   Reply Code Actions   field, enter   E=RF .

5. Select   Apply .

This value specifies that, if a notification is not sent to Personal Community, then the business operation attempts to resend the message. The business operation attempts to resend the message according to the value of   Retry Interval , until reaching the   Failure Timeout . If the business operation reaches the   Failure Timeout , it fails that notification and then attempts to send the next notification.

By default, all messages for your Personal Community production are retained. Over time, the volume of data can increase to a point where event log and Message Viewer performance suffer.

To avoid this problem, InterSystems strongly recommends that a purge task be run at frequent intervals. The class for this task ships with Personal Community and can be enabled via the Task Scheduler.

To enable the task:

1. Log into the Management Portal for Personal Community as a user with the   %EnsRole_Administrator   role.

2. Navigate to   System Operation   —>   Task Manager   —>   New Task . This displays the Task Scheduler Wizard screen.

3. For   Task Name , enter a descriptive name for the task. This is the name by which you will later be able to identify the task in the Task Schedule.

4. In the   Namespace to run task in drop-down list , select the Personal Community namespace.

5. In   Task Type , select   Ens.Util.Tasks.Purge . A blue box with additional options will appear:

   1. Make sure that   BodiesToo   is selected. This ensures that both request headers and bodies will be deleted.

   2. Make sure that   KeepIntegrity   is selected. Enabling   KeepIntegrity   is essential if Workbench task management features will be used in the installation.

   3. In the   NumberOfDaysToKeep   field, enter an integer greater than 0, or keep the default of 7.

   4. In the   TypesToPurge   drop-down list, choose the types of data you want to delete, such as   Events Only .

6. For more information on the rest of the settings, see the “ Using the Task Manager ” section of the System Administration Guide.

7. Select   Finish . The task is now set up to run on a schedule, which you can change; see “ Using the Task Manager .”

   IMPORTANT

   After the purge task is scheduled, you may find over time that it does not delete an adequate amount of data. You can handle this by changing the settings on the task or by running the task on demand from the Task Schedule at any point.

The installation program creates the web applications for Personal Community with the required security configuration. For introductory information about web applications, see “ Web Applications .”.

Ensure that the URL paths and directories are configured to hand off the requests off to the instance of InterSystems IRIS for Health™ for Personal Community via the instance’s Web Gateway. To configure these paths and directories, create two new applications in the Web Gateway, in the   Application Access   section. For more information about the Web Gateway and configuring web servers, see the   Web Gateway Configuration Guide .

Along with the principal setup activities for HTTPS access on the web server that supports Personal Community, you must ensure that both the Personal Community and Workbench web applications are explicitly disabled in the Web Gateway for the private Apache web server.

To disable the use of the private Apache web server for the Personal Community and Workbench web applications, the procedure is:

1. Confirm that access via the external web server is operational.

2. In the Management Portal, go to the   Web Gateway Management   page.

3. On that page and its associated pages, perform the following actions:

   1. Create a web application corresponding to the Workbench.

   2. Disable access to that application through the private web server.

   3. Create a web application corresponding to Personal Community.

   4. Disable access to that application through the private web server.

After web server setup for HTTPS is complete, enable the HTTPS URL for the public application:

1. Log into the Workbench as a Workbench administrator.

2. Navigate to   Setup   >   Site Configuration .

3. Change the   Personal Community base URL   to the correct HTTPS URL.

4. Select   Apply   to save changes.

The Personal Community public application uses a REST API to request patient data. By default, CORS processing for REST requests is enabled but not restrictive in Personal Community. This way, a browser in one domain or on another server in the same domain can request and display patient data from a Personal Community instance that is in another domain or on another server.

Since much of the data displayed in Personal Community is confidential, you may want to lock down browser access to the data to only those devices within a given domain. Changes to CORS settings will not affect the availability of data to requests made by an application other than a browser.

To configure CORS settings for the Personal Community public application:

1. Log into Workbench as a Workbench administrator.

2. Navigate to   Setup   >   Site Configuration .

3. You can change the CORS settings as follows:

   1. You can enable or disable CORS for Personal Community entirely by checking or removing the checkmark from the "Include header to enable CORS..." checkbox.

      Disabling CORS entirely may prevent browser access to Personal Community in some cases. Instead of disabling CORS completely, InterSystems strongly recommends that you leave it enabled and restrict access by origin instead.

   2. If you keep CORS enabled and you want to restrict cross-domain access, you MUST change the following setting:

      • Access-Control-Allow-Origin : The origin (identified by [ scheme: //]host[: port ], such as   http://example.com:80   or   server.foo.org ) of the devices from which requests for data via a browser will be accepted. All other browser requests will be denied.

   3. If you keep CORS enabled, you may also change the following settings.

      • Access-Control-Max-Age : Allows caching of CORS preflight requests for the given number of seconds. If you set this field to 0, caching is disabled entirely.

      • Access-Control-Allow-Headers : Specifies the allowable HTTP headers for a request.

        IMPORTANT

        The   Content-Type   header, which is present by default, must remain in the   Access-Control-Allow-Headers   field for Personal Community API calls to function properly.

4. Select Apply   to save changes.

Personal Community features several SOAP APIs that provide programmatic access for:

• Enrollment

• Proxy relationship creation

• Secure messaging from external systems

• Clinical group and provider data updates

By default, these APIs must access Personal Community over HTTPS.

To disable the requirement for HTTPS for SOAP API access:

1. Log into Workbench as a Workbench administrator.

2. Navigate to   Setup   >   Site Configuration .

3. Under   Personal Community SOAP APIs , clear the checkbox next to   Personal Community SOAP APIs may be accessed only via HTTPS .

4. Select  Apply to save changes.

In production, Personal Community must have a publicly accessible URL. To establish this URL:

1. Log in to the Workbench as a user with the   Configuration Manager   role.

2. Go to the   Site Configuration Settings   page ( Setup   >   Site Configuration ).

3. On the   Site Configuration Settings   page, in the   Application Settings   section, specify the value of the   Personal Community base URL   field.

4. Select   Apply   to save the specified URL.

This specifies the URL, so that you can continue the setup and implementation processes. With this URL, members will be able to log into Personal Community. For example, a URL for this might be:

https://my.healthcareorganization.org/mypatientportal/

To customize the branding of the public application:

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  Branding tab. 
3. Select  Edit Mode to make edits to the fields described below.
4. If you would like to upload an icon, select  Upload Icon and choose an icon from your computer. This should be an SVG file. 
5. After you have finished, select  Submit at the bottom of the page to save your changes. 

7.1.1. Section 1: Branding Naming

In this section, there are three names you can customize:

• Organization Name -  the organization's name.
• Tab Title -  the title of the application's tab in the user's browser.
• Application Name - the name of the application.

7.1.2. Section 2: Branding Theme

In this section, you can customize colors and padding within the application. The different sections are described below:

Major Theme Color Configuration 

In this section you can configure most of the colors present in the application:

• Primary Color  - the color of the application header and primary buttons.
• Secondary Color  - the color used for indicating focus while navigating the application.
• Background Color  - the primary background color on most pages of the application.
• Accent Color  - a color the can be used to emphasize a particular section of the application.
• Disclaimer Color  - a color that can be used to highlight important information to members.
• Warning Color  - a color that can be used to emphasize warning information to members. 
• Dark Text Color  - the color of dark text on light backgrounds.
• Light Text Color  - the color of light text on dark backgrounds.

Disabled Input and Form Section Color Configuration

In this section you can configure colors related to forms:

• Disabled Input Color  - the background color of a disabled form field. 
• Form Section Color  - the color of the horizontal line between consecutive form sections.

Neutral Color Configuration

In this section you can configure neutral colors. These colors are typically various shades of grey, and are used to indicate inactive functionality. 

• Main Neutral Color  - the base neutral color.
• Neutral Color 2 (Light)  - a light neutral color.
• Neutral Color 3 (Medium Light)  - a medium light neutral color.
• Neutral Color 4 (Very Light)  - a very light neutral color.
• Neutral Color 5 (Lightest)  - the lightest neutral color.
• Dark Neutral Color - the darkest neutral color.

Visualization Color Configuration

In this section you can configure the colors used to distinguish different users when proxy users are enabled.

Padding Configuration

In this section you can configure the padding (the space between html elements)

• Padding Large  - the padding of html elements as viewed on a desktop browser.
• Padding Small  - the padding of html elements as viewed on a mobile device.

Margin Configuration

In this section you can configure the margins of the application pages as viewed on a desktop or mobile device. 

• Margin Large  - the margins of the page as viewed on a desktop browser.
• Margin Small  - the margins of the page as viewed on a mobile device.

You must update the following page content files when implementing Personal Community:

• content-home-splash.html - this file should contain content for your organization's unauthenticated home page.
• content-termsofuse.html - this file should contain your organization's terms of use for Personal Community.

You may also update the welcome message on the Personal Community home page.

To modify page content:

1. In the Workbench, enable the setting that displays the source file for each page’s content in the public application:

   1. Log into the Workbench as a user with the Configuration Manager role.

   2. Go to the Site Configuration Settings page ( Setup > Site Configuration ).

   3. In the Content Settings section, select Highlight Personal Community content .

   4. Select Apply .

   This is also known as enabling content highlighting or enabling the debug flag .

2. If there is not already a custom copy of the content file, copy the existing file from

   <hspc-home>/base/content/en/

   to

   <hspc-home>/custom/content/en/

   Note

   If such a file already exists, do not create a new copy, as this may overwrite any customizations your organization has already made in it.

3. Edit the custom copy of the file as required for your organization.

   Note

   1. If this is a right to left language, the files should contain:

   <html dir= "rtl" ></html>

   The customer would then put their content within the tags.

4. Refresh the content for your organization's site.

To refresh content:

1. Log into the Workbench as a user who has the Configuration Manager role.

2. Go to the Content tab.

3. On the activity pane, select Content Updates . This displays the Content Updates page.

4. On the Content Updates page, choose Refresh Content .

This updates every aspect of each application to display the custom content, including text, images, and so on.

To customize the welcome message in the Personal Community public application:

1. Open your language file: <install-dir>/csp/public/assets/i18n/ <locale> .json
   where <locale> is made up of:
   • A required <language> parameter, which is a two-letter code for a language, such as es or zh .
   • A hyphen ( –) character only if you are creating a locale for a country's varient of a language
   • An optional <locale> parameter, which represents the lowercase two-letter code for a national variant of that language OR a string that identifies the file as unique to your organization. The variant is appended to the language code with a hyphen. 
     
     
2. Locate the " WELCOME_TITLE" string .  By default, this value will use display the patient's first name.  To update this value to use the patient's full name, change {{ firstName}} to {{ fullName}}.  

7.3.1. Co ntent files for the Public Application

Home

Records

Appointments

Messages

Bills

Other Pages

7.3.2. Content Files for the Workbench

Home

Tasks

Members

Setup

Content

Dashboards

Other Pages

7.3.3. Help Files for the Workbench

Home

Tasks

Members

Messages

Setup

Content

Dashboards