Personal Community provides a default set of content files for the invitation to enroll API.  These files are:

• email-enroll-invitation-notification-text.html
• email-enroll-invitation-notification-html.html
• sms-enroll-invitation-notification-text.html

The default subject lines for emails are in the email_subjects.json file.

To customize the default invitation message:

1. If there is not already a custom copy of these content files, copy the existing files from

   <hspc-home> / base /content/ locale code/

   to

   <hspc-home> / custom /content/ locale code /

   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.

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

   <hspc-home> / base /config/email_settings/ locale code/

   to

   <hspc-home> / custom /config/email_settings/ locale code /

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

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.

Organizations may wish to create tailored messages for each workflow that uses the invitation to enroll API. This allows a site to have more curated, personalized messages related to the workflow that triggered the invitation.

For each workflow, the following set of content files need to be created for each supported language:

• email- <custom content key name>  -text.html
• email- <custom content key name> -html.html
• sms- <custom content key name> -text.html

Where <custom content key name>  is a distinct name for this set of content.  This value is what will be used in the API request to determine which set of content files to retrieve.

To create the new invitation message:

1. Place the new files in:

   <hspc-home> / custom /content/ locale code /

   Note

   These files will need to be placed in each  locale code directory that is enabled for Personal Community.

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.

Workbench users perform point-of-care enrollment, and the ability to do so is configurable on a per-user basis for them. By default, a Workbench user cannot perform point-of-care enrollment.

The   Direct Enrollment User   role grants this ability, so if no Workbench users hold that role, then none can perform point-of-care enrollment, and this disables it for all of Personal Community.

To enable or disable this ability for a Workbench user:

1. Log into the Workbench as a user who holds the   Workbench Account Manager   role.

2. Go to the   Manage Workbench Users   page ( Setup  > User Management ).

3. Select the user for whom you wish to enable or disable to ability to perform point-of-care enrollment. This displays the   User Account Details   page for that user.

4. On the   User Account Details   page, select the   Direct Enrollment User   checkbox to enable the ability; clear the   Direct Enrollment User   checkbox to disable it.

5. Select   Update User   at the bottom of the page.

This choice determines which email address Personal Community uses for members. The procedure for making this choice is:

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

2. Navigate to   Setup   >  Site Configuration .

3. On the   Site Configuration Settings   page, in the   Enrollment and Account Settings   section, locate the   Email options for point-of-care enrollment   option buttons.

4. From the   Email options for point-of-care enrollment   option buttons, select one of the following choices:

   • Accept user-supplied email   – Allows the prospective member to supply an email address during the in-person enrollment process. This option depends on the representative to authoritatively authenticate the person’s identity during the enrollment process.

   • Use MPI if present but require printed activation if not   – Attempts to use the email address that is present in the Master Patient Index (MPI); if there is no email address available, Personal Community requires that the prospective member receive the access code in person or by postal mail (which is sent to the home address in the organization system). This option depends on the accuracy of the email or physical address in the MPI.

   • Accept user-supplied email if no MPI email   – Attempts to use the email address present in the Master Patient Index (MPI); if there is no email address available, Personal Community allows the prospective member to supply an email address during the in-person enrollment process. This option depends on the representative to authoritatively authenticate the person’s identity during the enrollment process.

5. Select   Apply   at the bottom of the page to save this change.

When you first install Personal Community, self-requested enrollment is enabled by default. To disable it:

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

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

3. In the   Feature Controls   section, select the   Disable self-requested enrollment   checkbox.

4. Select   Apply   at the bottom of the page.

To enable self-requested enrollment if you have disabled it, on the   Site Configuration Settings   page, clear the   Disable self-requested enrollment   checkbox.

This choice determines which email address Personal Community uses for a member. The procedure for making this choice is:

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

2. Navigate to   Setup   > Site Configuration . This displays the   Site Configuration Settings   page.

3. On the   Site Configuration Settings   page, in the   Enrollment and Account Settings   section, locate the   Email options for self-requested enrollment   option buttons.

4. From the   Email options for self-requested enrollment   option buttons, select one of the following choices:

   • Accept user-supplied email   – Whether or not Personal Community uses the email address that the prospective member supplies for all its communications.

     In a production environment, it is recommended that Personal Community externally verify the validity of the email address. For example, an organization might send a printed copy of the access code to the physical address that is on file; the patient then must enter that code in order to complete enrollment.

   • Reject if no email in MPI   – Allows the prospective member to enroll only if an email address is already associated with them in the MPI. If the system has an email address, this is in the MPI, and Personal Community uses it as the prospective member’s email. If there is no email address for that person in the MPI, the enrollment is rejected.

   • Use MPI email if present but require printed activation if not   – Allows the prospective member to enroll if an email address is already associated with them in the MPI; if there is no address on file, this requires that they have a printed access code to enter. If the system has an email address, this is in the MPI, and Personal Community uses it as the prospective member’s email.

     This option is recommended for use in a production environment. If no MPI email is found, it requires the representative to print and send the access code to the prospective member’s street address; this provides increased security. Note that this option depends on the accuracy of the address in the MPI.

   • Accept user-supplied email if no MPI mail   – Attempts to use the email address present in the MPI; if there is no email address available, uses the email address supplied by the prospective member in the self-enrollment form.

     In a production environment, it is recommended that Personal Community externally verify the validity of the email address entered by the prospective member. For example, an organization might send a printed copy of the access code to the physical address that is on file; the prospective member then must enter that code in order to complete enrollment.

5. Select  Apply at the bottom of the page to save this change.

Incoming requests for enrollment are handled by Workbench users who are part of the   Self Enrollment   group. These users are referred to as   enrollment request agents .

To create an enrollment request agent:

1. Log in to the Workbench as a user with the   Workbench Account Manager   and   Task Processing   roles.

2. Navigate to   Tasks   >   Manage Agents .

3. Select the name of the user whom you want to make enrollment request agent. The   Agent Details   page will appear.

4. At the bottom of the page, select the   Self Enrollment   group, then select   Add groups to agent .

An enrollment request agent can reject a request, or they can forward the request into an enrollment exception queue for handling. If your project team prefers to have a separate exception queue, you must assign agents, referred to afterward as   enrollment exception agents , to handle it.

To create an enrollment exception agent:

1. Log in to the Workbench as a user with the Workbench Account Manager  and  Task Processing   roles.

2. Navigate to   Tasks   >   Manage Agents .

3. Select the name of the user whom you want to make enrollment request agent. The   Agent Details   page will appear.

4. At the bottom of the page, select the Enrollment Exceptions   group, then select   Add groups to agent .

Communications with the  HSPortal.Production.Service.APIEnrollmentService  web service have the following requirements:

• Coding is external to Personal Community — hence, the code is associated with whatever entity invokes the web service.

• Each enrollment request must include either an assigning authority (AA) and a medical record number (MRN) or a patient’s ID in the Master Patient Index (MPIID), or both. Different patients within your organization can use different identifiers.

• Each request must include the patient’s email address.

• Personal Community does not perform any validation on the enrollment message. Rather, it assumes that your code has confirmed that the enrollment is valid by enforcing the necessary business rules, such as for identity verification and enrollment consent validation.

• The service does not enroll anyone who is already enrolled in Personal Community. It checks this by looking at the existing MRNs in the patient’s record; if the patient already has an MRN from the Personal Community assigning authority, the request fails.

• By default, API enrollment requests must be made over HTTPS. Check with the Workbench administrator to verify the value of the SOAP over HTTPS setting.

• Use WS-Security headers for authentication and message-level security. The Web service does not support SAML.

The web service accepts the following data:

• A unique identifier for the patient to be enrolled, which is either:

  • MRN and AA – A valid MRN that already exists in the MPI as well as the AssigningAuthority code corresponding to the MRN.

  • MPIID – Valid HealthShare MPIID.

• Email Address – An email address that is considered trusted. The service uses either the address in the MPI or a patient-provided address, depending on the value of the  Email options for automated enrollment  setting.

• Enrolling User – The identifier of the user who initiated the enrollment in the external system. It is not checked against any privileges within Personal Community or its underlying systems, and is simply recorded for auditing purposes. If this field is left empty, the identifier for the default enrolling user specified in the Personal Community production will appear in the log.

• Passphrase — A temporary password for validating the patient’s identity during account activation. Use of the passphrase is optional across the implementation (not per patient).

• Enrollment mode — Whether communications with the web service are synchronous or asynchronous. See the next section for details about each mode of communication.

• Proxy only flag — If set to 1, the patient will be enrolled as a proxy-only member.

• Preferred communication code — The preferred language for email or phone notifications sent to the patient by Personal Community. This code should be the two-letter code for a language, such as " es ", or a language and locale code separated by a hyphen such as " es-mx "
• Preferred UI language code — The preferred language for any text on the public application, as viewed by the patient. This code should be the two-letter code for a language, such as " es ", or a language and locale code separated by a hyphen such as " es-mx "

When contacting the web service, you can use synchronous or asynchronous mode:

• Sync Mode – Each request is processed synchronously; the transaction waits until the enrollment process returns a status. The call returns a response object, which contains its status and the reason for failure, if applicable. This is appropriate for a normal production transaction mode and can handle about 1 to 5 requests a second depending on system performance and MPI performance. This is the default.

• Async Mode – Each request is processed asynchronously; the transaction does not wait until the process completes. Every transaction returns a success status, and the enrollment transactions will queue up waiting for processing. There is no indication provided when an enrollment fails in the response message.  Enrollment errors in async mode are only visible in the Event Log. This method can queue up large numbers of enrollments rapidly and is appropriate for system setup tasks, such as bulk enrollment.

This choice determines which email address Personal Community uses for prospective members during automated enrollment.

If a prospective member attempts to enroll but has no email address in the Master Patient Index (MPI) of the Unified Care Record, Personal Community handle missing email addresses in one of two ways, which you specify using the   Email options for automated enrollment   setting on the   Site Configuration Settings   page ( Setup   >   Site Configuration ).

The procedure for making this choice is:

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

2. Navigate to Setup > Site Configuration.

3. On the   Site Configuration Settings   page, in the   Enrollment and Account Settings   section, locate the   Email options for automated enrollment   option buttons.

4. Choose one of the following two options:

   • Use supplied email   — Uses the email address that the prospective member supplies.

   • Use MPI emai l   — Uses the email address present in the MPI. If there is no such email address, the enrollment is rejected.

5. Select Apply   at the bottom of the page to save this change.

If you are using automated enrollment, you may need to modify enrollment timing. This is because, when using automated enrollment, Personal Community needs to coordinate the timing of each enrollment to follow the prospective member’s   registration   within the Unified Care Record. Due to possible delays with registration, enrollment in Personal Community can occur sooner than registration. In these circumstances, Personal Community attempts to enroll prospective members who are not yet registered, which causes other complications.

To prevent this timing problem from occurring, you may need to delay enrollment processing by a specified duration. This gives the registration process sufficient time to complete. To specify the amount of this delay, use the   DelayProcessing   setting of the   HSPortal_APIEnrollmentProcess   class to specify the number of seconds by which to delay processing.

The duration of this delay depends on the circumstances at your site. 

To delay processing:

1. Log into the Management Portal for Personal Community as a user with the   %EnsRole_Administrator   role and with the role that has read-write access to the database that you created during the installation process.

2. In the Personal Community namespace, go to the   System Default Settings   page. Specifically:

   1. Go to the Personal Community namespace by selecting   Switch   from the title bar and choosing its name in the namespace chooser.

   2. From the Management Portal, select   Interoperability   >   Configure   >   System Default Settings .

3. In the table of system default settings that are defined for the Personal Community production, select   New   to create a new entry. This displays the   New System Default Setting   page.

4. On the   New System Default Setting   page, enter the following values for the fields:

   • Production   — Your organization’s production name or *

   • Item Name   —   HSPortal_APIEnrollmentProcess

   • Host Class Name   — *

   • Setting Name   —   DelayProcessing

   • Setting Value   — The delay, in seconds, as required by your site’s constraints.

   You do not need to enter a value for   Description   and you do not need to mark the   Deployable   check box.

5. Select   Save .

When using automated enrollment you must supply an identifier for a default enrolling user. This identifier, which can be any combination of characters, will appear in   HS_Logging.LogData   whenever a member is auto-enrolled and the automated enrollment request for that member does not contain a value for the enrolling user field.

You may want to choose a unique string to distinguish log entries for members that are auto-enrolled from those that are enrolled by other means.

To specify a default enrolling user:

1. Log into the Management Portal as a user with the   %EnsRole_Administrator   role and with the role that has read-write access to the database that you created during the installation process

2. In the Personal Community namespace, go to the   System Default Settings   page. Specifically:

   1. Go to the Personal Community namespace by selecting   Switch   from the title bar and choosing its name in the namespace chooser.

   2. From the Management Portal, select   Interoperability   >   Configure   >   System Default Settings .

3. On the   System Default Settings   page:

   1. Select the row for   Default Enrolling User   and select the   Edit   button at the top of the age. This displays the   Edit System Default Settings   page.

   2. In the   Setting Value   field, enter the desired value.

   3. Select   Save .

4. In your Personal Community namespace, update the production. Specifically:

   1. Go to your Personal Community namespace by selecting   Switch   from the title bar and choosing its name in the namespace chooser.

   2. From the Management Portal, select   Interoperability   >   Configure   >   Production   and then select   Go .

   3. Select the   Update   button.

When a member is enrolled with automated enrollment and the automated enrollment request uses an MRN from an EMR’s assigning authority, the demographic information that appears in Personal Community will be drawn from the healthcare facility that a) has that MRN on file and b) has the lowest tier ranking and latest create or update time in the associated Unified Care Record.

To ensure that facilities with trusted demographic information are at the top of the list for data selection, or to change demographic information for a patient, work with the person who configures Unified Care Record to examine and, if necessary, adjust facility tiering and demographic data.

For more information about facility tiering and to change a tier, see the “ Facility Registry Fields ” section of the “Managing Facilities” chapter of   Unified Care Record Registries .

To change demographic data, see the “ Editing Patient Demographic Information ” section of the “Managing the Patient Registry” chapter of   Unified Care Record Registries .

The following topics address various settings for account, and authentication options. To specify the behavior of Personal Community to match your specifications, the procedure is:

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

2. Go to the   Setup   tab.

3. On the   Setup   tab, choose   Site Configuration . This displays the   Site Configuration Settings   page.

4. On the   Site Configuration Settings   page, in the   Enrollment and Account Settings   section, set the values for the following fields according to your policy decisions:

   • Minimum permitted age for access to the Personal Community   — The prospective member’s minimum age in years to be able to use Personal Community.

   • Notify members of password changes   — Whether or not to notify members that their password has been changed. If selected, the notification goes to the member’s external email address or mobile phone number on the account.

   • Notify patients of new messages   — Whether or not to send members an email when they have received a new message within Personal Community. If selected, the notification goes to the member’s external email address or mobile phone number on the account.

   • Notify patients’ proxies of new messages   — Whether or not to send members an email or text (SMS) when their principals have received a new message within Personal Community. If selected, the notification goes to the member’s email address or mobile phone number on the account.

   • Required enrollment fields implementation class   — The class that specifies the personal information that can be required for enrollment. 

   • Required enrollment fields   — The personal information that prospective members must supply when they sign up for an account. These information fields are for account validation. Depending on your policy, required fields may include any combination of the fields specified in the enrollment class you chose above and temporary passphrase.

   • Password reset expiration time (in hours)   — The duration (in hours) that a password reset token is valid. After this amount of time, the token expires and the prospective member must request another.

   • Pending user expiration time (in hours)   — The duration (in hours) that the activation code required for setting up an account is valid.  If the prospective member does not complete enrollment by the end of the expiration time, the activation code for completing enrollment expires.

   • Maximum expiration reset window (in hours)   — The maximum duration (in hours) for which a renewed activation code is valid.

   • Remembered password limit   — The number of previous passwords that the system stores for a member. The system prevents members from reusing any of these stored passwords.

5. Click   Apply   at the bottom of the page to save these changes.

 At the end of account activation, patients are presented with the Review Preference page to review and update their preferences.  This page is enabled by default and allows a patient to update the following:

• Email address
• Mobile phone number
• Communication preference
• Preferred language (if multiple languages are configured for Personal Community)

To disable review preferences or options within review preferences, in the Workbench:

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  Feature Control  tab. 
3. Select  Edit Mode   to make edits to the fields described in the following steps.
4. To disable the review preferences screen, In the   Account Settings   box, uncheck the checkbox to the left of   Enable   Review Preferences.
5. To disable a subset of the review preferences screen uncheck the following settings as needed:
   1. Allow Patients to Manage Email Address
   2. Allow Patients to Manage Mobile Phone Number
   3. Allow Patients to Select Preferred Communication Method  - If this is enabled, email and mobile phone will be enabled as well to ensure the communication details are correct for their selected preference.
   4. Allow Patients to Select Preferred Language

6. After you have finished, select   Submit   at the bottom of the page to save your changes. 

Your organization may want to:

• Change the formatting or validation of one of the standard fields.
• Use site-specific identifiers instead of the standard fields.

If this is the case, you will create a site-specific enrollment implementation class.

To create a site-specific enrollment implementation class:

1. Create a new class that extends  HSPortal.Account.Registration.RequirementsInterface.cls.

   IMPORTANT

   InterSystems strongly recommends that the new class should be part of a site-specific package. Do not add it to the HSPortal package.

2. In the site-specific class, specify values for the following parameters of the properties you will be using. These parameters are specific to a particular property, denoted by  1 or  2  in the name of the parameter.
   • PropertyNamePublic - The name of the key for display of each property in Personal Community. InterSystems strongly recommends that you prefix the name of each key with "CUSTOM_" . for example: Parameter Property1Public As %String = "CUSTOM_NATIONAL_ID" .

   • PropertyNameWorkbench - The string that will be the Workbench display name for the property.

     IMPORTANT

     If your organization will require only one field for enrollment, your class must contain a definition for only one property.

3. Override the following class methods as needed. These methods are specific to a particular property, denoted by  1  or  2 in the name of the method.
   • GetProperty  - Gets the value of a property from a data source in Personal Community such as HS.Types.PersonInfo or any class derived from it. This method is used to display the value of the property in patient detail pages. If none of those classes provides the relevant data, you can create an SDA extension for that purpose.
   • SetPatientInfoProperty  - Sets the value of the appropriate HS.Types.PersonInfo property to the value entered by the prospective member. This method is used for patient search or to add or update a patient identifier in the Unified Care Record Registry. 
   • GetPropertyValidationRegex  - Optional. Specifies a regular expression against which a property value will be checked. The syntax of the regular expression must be valid in both JavaScript and ObjectScript.
   • FormatProperty  - Optional. Removes UI formatting from the property value so that it can be compared with patient data from the Unified Care Record Registry.
   • PropertyErrorMessage - Optional. The error that appears when user input for a required field does not match the value of that field returned by  GetProperty .
4. Compile your new class.

5. Log in to the Workbench as a user who has the   Configuration Manager   role.

6. Go to the   Setup   tab.

7. On the   Setup   tab, choose   Site Configuration . This displays the   Site Configuration Settings   page.

8. In the   Enrollment and Account Settings   section, find Required enrollment fields implementation class   and enter the class you created above.

9. Click   Apply   at the bottom of the page to save these changes.

Save this name for the name of the key for each PropertyNamePublic parameter for UI customization. You should add those keys to the i18n language files that are currently in us.

To configure the general behavior for temporary passphrases:

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

2. Go to the   Setup   tab.

3. On the   Setup   tab, choose   Site Configuration . This displays the   Site Configuration Settings   page.

4. On the   Site Configuration Settings   page, in the   Passphrase Configuration   section, set the values for the following fields according to your policy decisions:

   • Permit passphrase enrollment   — Whether or not the enrollment process   allows   the use of passphrases for authentication. If selected, the prospective member is given a passphrase during preliminary account setup. When the prospective member completes the enrollment process, the application verifies their identity by prompting for that passphrase. (This is not available for self-requested enrollment.) See also the next field.

   • Require passphrase   — Whether or not the enrollment process   requires   the use of passphrases for authentication. If this option is selected, then the prospective member must use a passphrase. See also the previous field.

     IMPORTANT

     If your project team wants to also allow self-requested enrollment, you should not require  a passphrase to be entered

   • Email enrollment passphrase   — Whether or not to send patients their temporary passphrase by email. Enabling this functionality also enables the use generated passphrases.

   • Passphrase implementation class for temporary passphrases   — The class that Personal Community uses to enforce minimum requirements on temporary passphrases.

5. Click   Apply   at the bottom of the page to save these changes.

You can change the requirements for the temporary passphrase that a prospective member specifies when beginning the enrollment process.

To change the requirements for temporary passphrases:

1. Create a subclass of the HSPortal.Account.Sec.Passphrase class.

2. In the new subclass, specify values for the following class parameters, as appropriate:

   • MINPASSWORDLENGTH   — The minimum number of characters in the password. The default is 6.

   • MINUPPERCASE   — The minimum number of upper case characters in the password. The default is 1.

   • MINLOWERCASE   — The minimum number of lower case characters in the password. The default is 1.

   • MININTEGER   — The minimum number of numeric characters in the password. The default is 1.

   • MINNONALPHANUMERIC   — The minimum number of non-alphanumeric characters in the password, such as punctuation marks. The default is 0.

   • USEDICTIONARY   — Whether or not to test proposed passwords against a dictionary of frequently used strings. The default is 1 (true).

3. Compile the subclass.

4. Save this name for system configuration.

Personal Community provides tools to remind pending members to complete their enrollment and perform related tasks. Taken together, these tools are known as the  Enrollment Reminder Service . It allows you to configure settings to control the process of reminding potential members of their incomplete enrollment and, optionally, removing accounts of patients who have not completed enrollment.

The major component of this service is the task to provide reminders and optionally delete accounts. There are also templates for the emails that patients receive; these are known as the  activation reminder notification  and the  pending account deletion notification .

To enable the enrollment reminder service and have it send custom versions of its messages, the process is:

1. Modify the messages.

2. Create the task.

To modify the messages:

1. Edit the template files for the emails, which are located in the   <install-dir> /hscommunity-content/public/base/content  directory, where  <install-dir>  is the location where you installed Personal Community. The files are:

   • email-activationreminder-html.html

   • email-activationreminder-text.html

   • email-deletenotification-html.html

   • email-deletenotification-text.html

     IMPORTANT

     When you edit these files, place the modified versions in the <install-dir> /hscommunity-content/public/custom/  directory. Do not place them in  <install-dir> /hscommunity-content/public/base/  or   <install-dir> /hscommunity-content/public/combined/ .

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

3. Go to the  Content   tab.

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

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

To create the task:

1. Log into the Management Portal as a user who has a role with the %Admin_Operate:Use  privilege.

2. Go to the  Task Scheduler Wizard  page ( System Operation  >  Task Manager  >  New Task )

3. On the  Task Scheduler Wizard  page, specify values for the fields as follows:

   • Task Name  — Specify the name that you wish the task to have.

   • Namespace to run task in  — Select the namespace that your instance of Personal Community is using. If you have followed the example of the installation guide, this is HSPC.

   • Task Type  — Select   Personal Community Activation Reminders .

     Note

     If this choice is not available, you have selected the wrong namespace.

     Selecting this task displays the following fields, which also require values:

     • DaysBetweenReminders  — How frequently, in days, Personal Community sends out reminder notifications. Specify a value from 1 to 21 days; the default is 7 days.

     • DeleteOld  — Whether or not Personal Community deletes accounts for pending members who have received the maximum number of reminder notifications. Specify that the accounts are deleted by selecting the check box; by default, Personal Community does not delete accounts.

       Note

       Some accounts, such as those that are in proxy relationships with another, or that were formerly in proxy relationships and had actions taken against them such as a message, cannot be deleted. This is to preserve auditing data.

     • MaxReminders   — The maximum number of reminder notifications that Personal Community sends to a pending member. Specify an integer value of at least 1; the default is 3.

     • ReactivationHours   — The number of hours for which the pending member’s new access code is valid. Specify an integer value of at least 24; the default is 96.

     For general information about creating tasks, see the “ New Task ” section of the “Managing InterSystems IRIS” chapter of the  System Administration Guide .

     
     

4. Once you have completed the fields on this page, select  Next . This displays the page of the wizard for specifying how frequently the task runs.

5. On this page, specify how often the Task Manager runs the task, as well as other scheduling constraints.

6. Select  Finish . This adds the task to those scheduled to run, and displays the  Task Schedule  page, where the task is now listed. (To go directly to the  Task Schedule  page, select  System Operation  >  Task Manager  >  Task Schedule .)

Each time the task runs, it sends out the activation reminder notification. If you have configured the service to delete the accounts for patients who have not completed enrollment, the task also sends out the pending account deletion reminder.

Personal Community can act as a service provider to an external identity provider using OAuth 2.0.  Personal Community is designed to support the following access token types:

1. ID Token
2. JSON web token (JWT)
3. Opaque token with token introspection

While configuring Personal Community to act as a service provider, organizations will need to choose which of the access token types to use during sign-in and enrollment.

With external credentials, members enroll by authenticating themselves with the external identity provider. 

After successful authentication, Personal Community matches the member’s identity to a patient’s health record in the Unified Care Record. This results in a member account being created.

The external identity provider should provide an OpenID Connect (OIDC) userInfo endpoint to be used during the enrollment. This endpoint is required when using ID Token and Opaque token authentication, and is strongly recommended to be used with JWT as well.

The OIDC userInfo endpoint will provide Personal Community the unique identifier for the patient that will be used to identify the member within the Unified Care Record. Additionally, the userInfo should provide Personal Community with additional demographic information about the member.  This information can be used to populate the Personal Community demographics for the member.

If an external identity provider is using a JWT and not providing an OIDC userInfo endpoint, the JWT will need to provide a unique identifier to Personal Community that can be used to match the patient in the Unified Care Record.  If the JWT can provide additional demographic information about the member, that will be used to populate the Personal Community demographics during enrollment.  If it cannot, demographic information from the Unified Care Record will be used.

You must use an enrollment configuration class to determine what information, given by the external identity provider, is used to match members with a patient’s health record in the Unified Care Record. This is required for successful enrollment. Optionally, this class also contains the condition(s) to be met for member enrollment to be permitted.

To create a site-specific enrollment configuration class:

1. Create a new class that extends   HSPortal.OAuth2.Client.IdentifierEnrollmentConfiguration .
2. Override the OAuth2AccessTokenType   to select your access token type. By default this is set to IdToken. Other available options are JWT and Opaque.

3. Override the following methods in order to implement the required workflow behavior for your site:

   • RetrieveMRNFromUserInfo   — Required - Determines which identifier to use from the u serInfo   object from the OIDC userInfo endpoint or the JWT object that Personal Community receives from the external system. This identifier is used to match the member’s identity to a patient’s health record in the Unified Care Record. For example, in the   HSPortal.OAuth2.Client.Vendor.NHSLogin.v1.NHSLoginEnrollmentConfiguration   class, this is defined as: pUserInfoObject."nhs_number"

   • IsEnrollmentPermitted   — Optional - Determines the condition(s) to be met for member enrollment to be permitted. By default, all authenticated members are permitted for enrollment. This method uses the   UserInfo   object that Personal Community receives from the external system as input. For example:

      Set tIsPermitted = 
          ''$ListFind(tNHSNumberAllowList,pUserInfoObject."nhs_number")
      Quit tIsPermitted
     

     where tNHSNumberAllowList is a list of MRNs for members you permit for enrollment.

   • UpdateEnrollmentData   — Optional - Updates a patient’s demographic data by populating data from the external system via the u serInfo   object from the OIDC userInfo endpoint or the JWT object  that Personal Community receives from the external system. Demographic data that is not available from the external system will be populated from existing data for the patient from the UCR.

     The method signature is as follows:

     Method UpdateEnrollmentData(
                          pUserInfoObject As %RegisteredObject,
                          pScope As %String,
                          ByRef pEnrollmentData As %Zen.proxyObject)
     {}
     

     This method maps property values from   pUserInfoObject   to property values in   pEnrollmentData , based on the OpenID scope specified by   pScope .

     By default, the following property values are populated from the UserInfo object:

     pEnrollmentData Property Name	pUserInfoObject Property Name
     pEnrollmentData.FirstName	pUserInfoObject."given_name"
     pEnrollmentData.LastName	pUserInfoObject."family_name"
     pEnrollmentData.DateOfBirth	pUserInfoObject."birthdate"
     pEnrollmentData.Email	pUserInfoObject."email"

     You can choose from the following property values to populate from the   UserInfo   object:

     • FirstName

     • MiddleName

     • LastName

     • DateOfBirth

     • Sex

     • Address1

     • Address2

     • City

     • State

     • Zipcode

     • Email

4. Override the   PATIENTLOOKUPTYPE   parameter, which is used to distinguish enrollment configurations.

5. Compile your new class.

To create an SSL/TLS configuration on your instance of Personal Community:

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

2. Go to the   SSL/TLS Configurations   page ( System Administration   >   Security   >   SSL/TLS Configurations ) and select   Create New Configuration .

3. Enter a name of your choice for the configuration.

4. Make sure that the configuration is enabled: the   Enabled   checkbox should already be selected.

5. For   Type , make sure that   Client   is selected.

6. For   Server certificate verification , make sure that   None   is selected.

7. For   Protocols , make sure that   TLSv1.1   and   TLSv1.2   are selected.

8. Select the   Save   button to save the new configuration.

To create an X.509 credential set:

1. Determine which public certificate and private key will be used for OpenID Connect, as specified by the policies your organization has adopted regarding public key cryptography, especially private keys.

2. Copy the source files for the public certificate and private key to the machine that hosts the Personal Community installation.

3. Log in to the Management Portal for Personal Community as an InterSystems IRIS user who has the   %Manager   role.

4. Navigate to   System Administration   >   Security   >   X.509 Credentials .

5. Create and save a credential set   as indicated below:

   • Alias   — An identifying name of your choice

   • File containing X.509 certificate   — The full pathname of the public certificate file

   • File containing associated private key   — The full pathname of the private key file

You must set up an OAuth 2.0 client server with your external identity provider. To do so:

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

2. Go to the   OAuth 2.0 Client   page ( System Administration   >   Security  >   OAuth 2.0   >   Client ) and select   Create Server Description .

3. Select   Manual   for manual setup.

4. You will need to obtain the following information from your external identity provider:

   • Endpoints   — you will need the URLs for:

     • the Issuer endpoint.

     • the Authorization endpoint.

       Note

       There is a case where patients do not have to authenticate with the external identity provider. This occurs when the patient signs in with external credentials, signs out, and signs back in immediately without closing the browser. Because the patient has an active session with the external identity provider, they are not prompted to authenticate again.

       You may wish to enforce that a patient is  always  prompted to authenticate with the external identity provider. Provided that your external identity provider supports this, this can be enforced by adding  ?prompt=login   to the end of the authorization endpoint.

     • the Token endpoint.

     • the Userinfo endpoint.

     • the JWKS endpoint.

   • Credentials   — you will need a valid username and password for the OAuth authorization service, referred to as the OAuth client ID and client secret.

   • Scope   — the following scope, at a minimum, is required for enrollment to function properly: openid profile

5. With the given information, configure accordingly.

To configure the Personal Community public application home page for enrollment and sign-in with external credentials, you must make the following InterSystems IRIS for Health™ Terminal call in your Personal Community namespace:

set status = ##class(HSPortal.OAuth2.Client).CreateOrUpdateOAuth2Client(
                       pApplicationName,
                       pLoginFilename,
                       pEnrollFilename,
                       pLoginModalFilename,
                       pEnrollModalFilename,
                       pIssuer)

where:

• pApplicationName   — the name of the OAuth 2.0 client server you created.

• pLoginFilename   — the path to an SVG file for sign-in with external credentials.

• pEnrollFilename   — the path to an SVG file for enrollment with external credentials.

• pLoginModalFilename   — the path to an SVG file for the sign-in modal.

• pEnrollModalFilename   — the path to an SVG file for the enrollment modal.

• pIssuer   — optional - the custom issuer used to validate the Access Token and ID Token. By default, this is set as the value stored in  Issuer endpoint  in your  OAuth 2.0 Client  configuration.

To establish enrollment with your external identity provider, call the  CreateOrUpdateEnrollmentConfiguration() method in your enrollment configuration class with the following values for parameters:

• pApplicationName — The name of the OAuth 2.0 client server you created.
• pAssigningAuthorityName — The name of the assigning authority, as defined in the Unified Care Record.
• pUse — The identifier type, as defined in the Unified Care Record.
• pOAuth2Audience –  Optional. The OAuth2 Audience. OAuth2 Audience (aud) verifies if the access token is intended for a specific recipient or audience, ensuring that the token is used by the right party or application.
• pOAuth2AccessTokenType — The access token type selected in your enrollment configuration class. For existing implementations, this will be IdToken.

To create an SSL/TLS configuration on your instance of Personal Community:

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

2. Go to the   SSL/TLS Configurations   page ( System Administration   >   Security   >   SSL/TLS Configurations ) and select   Create New Configuration .

3. Enter a name of your choice for the configuration.

4. Make sure that the configuration is enabled: the   Enabled   checkbox should already be selected.

5. For   Type , make sure that   Client   is selected.

6. For   Server certificate verification , make sure that   None   is selected.

7. For   Protocols , make sure that   TLSv1.1   and   TLSv1.2   are selected.

8. Select the   Save   button to save the new configuration.

To create an X.509 credential set:

1. Determine which public certificate and private key will be used for OpenID Connect, as specified by the policies your organization has adopted regarding public key cryptography, especially private keys.

2. Copy the source files for the public certificate and private key to the machine that hosts the Personal Community installation.

3. Log in to the Management Portal for Personal Community as an InterSystems IRIS user who has the   %Manager   role.

4. Navigate to   System Administration   >   Security   >   X.509 Credentials .

5. Create and save a credential set   as indicated below:

   • Alias   — An identifying name of your choice

   • File containing X.509 certificate   — The full pathname of the public certificate file

   • File containing associated private key   — The full pathname of the private key file

To set up an OAuth 2.0 client server for NHS login on your instance:

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

2. Go to the   OAuth 2.0 Client   page ( System Administration   >   Security  >   OAuth 2.0   >   Client ) and select   Create Server Description .

3. Select   Manual   for manual setup.

4. Enter the following values for fields:

   • Issuer endpoint   — the URL for the endpoint provided by NHS login(for example,   https://auth.sandpit.signin.nhs.uk/token ).

   • SSL/TLS configuration   — select the SSL configuration you created previously for this OAuth setup.

   • Authorization endpoint   — the authorization endpoint URL (for example,   https://auth.sandpit.signin.nhs.uk/authorize ).

   • Token endpoint   — the token endpoint URL (for example,   https://auth.sandpit.signin.nhs.uk/token ).

   • Userinfo endpoint   — the userinfo endpoint URL (for example,   https://auth.sandpit.signin.nhs.uk/userinfo ).

   • Source other than dynamic registration   — make sure that   JWKS from URL   is selected

   • URL   — the JWKS URL for NHS login (for example,   https://auth.sandpit.signin.nhs.uk/.well-known/jwks.json ).

5. Click   Save .

6. Select   Client Configuration   for the server you just created (listed by   Issuer endpoint ) and select   Create Client Configuration .

7. Select   General   and enter the following values for fields:

   • Application name   — NHSOAuthClient (or another descriptive name of your choice). This name will be needed later to complete configuration.

   • Client name   — NHSlogin (or another name of your choice — optional).

   • Make sure that the configuration is enabled: the   Enabled   checkbox should be selected.

   • Client Type   — select   Confidential .

   • SSL/TLS configuration   — select the SSL configuration you created previously for this OAuth setup.

   • Under   Client redirect URL :

     • Make sure that the   Use TLS/SSL   checkbox is selected.

     • Host name   — the host name of your Personal Community server.

     • Port   — the port of your Personal Community instance (Optional).

     • Prefix   — the value for   Web Server Prefix   in the   Configure SSL Access   page ( System Administration   >   Configuration   >   Additional Settings   >   Startup   )

   • Required grant types   — make sure that   Authorization code   is selected

   • Authentication type   — make sure that   Private key JWT   is selected

   • Authentication signing algorithm   — make sure that   RS512   is selected

8. Select   Client Information   and enter the following values for fields:

   • Authorization display   — leave all items blank.

   • Default scope   —   openid profile

9. Select   JWT Settings   and enter the following values for fields:

   • Make sure that the   Create JWT Settings from X509 credentials   checkbox is selected.

   • X509 credentials   — select the X.509 credentials you created previously.

   • Private key password   — enter the password created for the X.509 credentials above

   • IDToken Algorithm   — For   Signing Column , make sure that   RS256   is selected

10. Select   Client Credentials   and enter values for the following fields, as provided to you by NHS login:

    • Client ID

    • Client secret

11. Select the   Save   button to save the new configuration.

To configure the Personal Community public application home page for enrollment and sign-in with external credentials, you must make the following InterSystems IRIS for Health™ Terminal call in your Personal Community namespace:

set status = ##class(HSPortal.OAuth2.Client).CreateOrUpdateOAuth2Client(
                       pApplicationName,
                       pLoginFilename,
                       pEnrollFilename,
                       pLoginModalFilename,
                       pEnrollModalFilename,
                       pIssuer)

where:

• pApplicationName   — the name of the OAuth 2.0 client server you created.

• pLoginFilename   — the path to an SVG file for sign-in with external credentials.

• pEnrollFilename   — the path to an SVG file for enrollment with external credentials.

• pLoginModalFilename   — the path to an SVG file for the sign-in modal.

• pEnrollModalFilename   — the path to an SVG file for the enrollment modal.

• pIssuer   — optional - the custom issuer used to validate the Access Token and ID Token. By default, this is set as the value stored in  Issuer endpoint  in your  OAuth 2.0 Client  configuration.

To establish enrollment with NHS login, make the following InterSystems IRIS for Health™ Terminal call in your Personal Community namespace:

set status = ##class(HSPortal.OAuth2.Client.Vendor.NHSLogin.v1.NHSLoginEnrollmentConfiguration).CreateOrUpdateEnrollmentConfiguration( pApplicationName, pAssigningAuthorityName, pUse,pOAuth2Audience,pOAuth2AccessTokenType) 

With the following values for parameters:

• pApplicationName  — the name of the OAuth 2.0 client server you created.
• pAssigningAuthorityName  — the name of the assigning authority, as defined in the Unified Care Record.
• pUse  — the identifier type, as defined in the Unified Care Record.
• pOAuth2Audience –  Optional. The OAuth2 Audience. OAuth2 Audience (aud) verifies if the access token is intended for a specific recipient or audience, ensuring that the token is used by the right party or application.
• pOAuth2AccessTokenType —  the access token type selected in your enrollment configuration class. For existing implementations, this will be IdToken.

To perform various activities automatically on a regular basis, Personal Community provides several system tasks.

You can set up any of these tasks as new tasks in the Task Scheduler Wizard. For more information about creating new tasks generally, see the “ New Task ” section of the “Managing InterSystems IRIS” chapter of the   System Administration Guide .

The available tasks are:

• Personal Community Disable Accounts for Minors - This task is used to disable accounts for patients who are minors.
• Personal Community Enable Accounts for Minors Reaching Majority - This task is used to enable accounts for patients reaching the age of majority.
• Personal Community Password Expiration Task - This task is used to set passwords to expire automatically after a certain number of days and to deactivate expired passwords.
• Personal Community Proxy Termination for Minors - This task is used to automatically terminate proxies for minors when the minors reach a certain age.

Each task can be configured using the following instructions:

Personal Community Disable Accounts for Minors

• AgeInYears   — The age at which a minor's account must be disabled automatically. The minimum value is 1. When local law specifies different handling when the member is some number of days older than a year, a number of days can be added to the year by specifying a value for   AgeInDays .

• AgeInDays   — When local law specifies different handling for a number of days beyond a round number of years, enter that value here.

• Range   — The number of days to check for before the actual date cutoff to make sure that all accounts that might have been missed on previous runs of the task are captured. The minimum is 1 and the maximum is 14.

Personal Community Enable Accounts for Minors Reaching Majority

• AgeInYears   — The age at which a minor's account may be re-enabled automatically due to their reaching majority. The minimum value is 1. When local law specifies different handling when the member is some number of days older than a year, a number of days can be added to the year by specifying a value for   AgeInDays .

• AgeInDays   — When local law specifies different handling for a number of days beyond a round number of years, enter that value here.

• Range   — The number of days to check for before the actual date cutoff to make sure that all accounts that might have been missed on previous runs of the task are captured. The minimum is 1 and the maximum is 14.

Personal Community Password Expiration Task

• MaximumPasswordUsage   — The maximum length of a password’s life, in days, before the member must change it. The minimum value is 7.

Personal Community Proxy Termination for Minors

• AgeInYears   — The age at which any proxies for a minor must be terminated automatically. The minimum value is 1. When local law specifies different handling when the member is some number of days older than a year, a number of days can be added to the year by specifying a value for   AgeInDays .

• AgeInDays   — When local law specifies different handling for a number of days beyond a round number of years, enter that value here.

• Range   — The number of days to check for before the actual date cutoff to make sure that all accounts that might have been missed on previous runs of the task are captured. The minimum is 1 and the maximum is 14.

External systems can be kept informed of account status changes by either requesting a patient's account status using the Personal Community Enrollment Status REST API or configuring Personal Community to send account status change notifications.

Account status possible values include:

The business operation that you implement can evaluate the type of account or MPI event that occurred and apply logic to each notification you wish to pass on to an external system. To implement a site-specific business operation:

1. Create a class definition for the business operation. It should contain an   OnMessage()   method of the form:

   Method OnMessage(pStatusChangeNotification 
       As HSPortal.Production.Message.StatusChangeNotification, 
       Output pResponse As %Library.Persistent) 
       As %Status {}
   

2. Within the   OnMessage()   method, you can identify the type of notification received with this statement:   Set tStatus = ##class(HSPortal.Account.Utils).GetMRNStatus(.tUserState, .tUserStateDisplay, pStatusChangeNotification.MRN) . The possible values for   tUserState are the account status possible values.

3. Define the desired logic for each notification type.

4. Compile the subclass.

You can send alerts of changes to Personal Community account status and updates to the MPI record (such as a visit to a new facility) to an external system. You may choose to implement one or both of these updates.

To set up account status and MPI update notifications for an external system:

1. Make sure you have the correctly named class definition for the business operation. The developer who implemented the class should be able to give it to you.

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

3. In your Personal Community namespace, go to the production page. Specifically:

   1. Go to your Personal Community namespace by selecting   Switch   from the title bar and choosing its name in the namespace chooser.

   2. From the Management Portal, select   Interoperability   >   Configure   >   Production .

4. Add the business operation whose name you verified in step 1.

5. Enable the business operation.

6. In the  HSPortal_MRNStatusChangeProcess  business process, set the   AssigningAuthorityOperationMap   property value as follows:

   AssigningAuthorityCode1-OperationName[ , AssigningAuthorityCode<n>-OperationName...]
   

   so that each assigning authority code for which you want to receive MPI update notifications is represented.

   For example, if you wanted to receive MPI updates for assigning authority code ABC and your business operation was named   MPIUpdateOperation , your   AssigningAuthorityOperationMap   value would look like this:

   ABC–MPIUpdateOperation 
   

   IMPORTANT

   If the assigning authority code is hyphenated, it must be wrapped in double quotes as follows:

   ''Hyphenated-ABC''-MPIUpdateOperation
   

7. If PIX notifications are required, configure the   HSPortal_PIXConsumerProcess   business process as follows:

   • • Make sure that   StatusChangeHandler   is set to   HSPortal_MRNStatusChangeProcess .

     • Set   StatusChangeAssigningAuthorities   to include the entire set of assigning authority codes for which PIX notifications need to be sent, as a comma-separated list.

     • Set   MRNIdentifierTypes   to the list of MRN identifier types for which PIX notifications need to be sent, as a comma-separated list.

8. In the   HSPortal_StatusChangeService   business service, set   StatusChangeHandler   to   HSPortal_MRNStatusChangeProcess .

You can change the requirements for the password that a member uses to sign into Personl Community.

To change the requirements of the password:

1. Create a subclass of the Acct.Sec.Password class.

2. In the new subclass, specify values for the following class parameters, as appropriate:

   • MINPASSWORDLENGTH   — The minimum number of characters in the password. The default is 6.

   • MINUPPERCASE   — The minimum number of upper case characters in the password. The default is 1.

   • MINLOWERCASE   — The minimum number of lower case characters in the password. The default is 1.

   • MININTEGER   — The minimum number of numeric characters in the password. The default is 1.

   • MINNONALPHANUMERIC   — The minimum number of non-alphanumeric characters in the password, such as punctuation marks. The default is 0.

   • USEDICTIONARY   — Whether or not to test proposed passwords against a dictionary of frequently used strings. The default is 1 (true).

   • HASHBYTES — The length of te password hash generated. The default is 20 bytes.
   • ITERATIONS — The number of times the encryption algorithm is invoked during the whole of the encryption process.  The default is 65536.
   • SALTBYTES — The number of bytes of random data, known as salt, used in the encryption process to make data more difficult to decrypt.  The default is 64 bytes.

3. Compile the subclass.

4. Save this name for system configuration.

To specify the use of custom password requirements:

1. Log into the Workbench as user who has the Configuration Manager role.
2. Navigate to  Setup  >  Site Configuration .

3. On the  Site Configuration Settings  page, in the  Passphrase Configuration  section, select the class in use in the  Passphrase implementation class for standard passwords  field according to your policy decisions. This is the class that Personal Community uses to enforce minimum requirements on standard account passwords, which the developers on your implementation team have set.

4. Select  Apply  at the bottom of the page to save these changes.
5. Modify the content that Personal Community displays if a user enters a password that does not meet the defined requirements. This content is in the file content-password-requirements.html .

By default, the Personal Community account lockout policy is that if there are three failed login attempts within five minutes, the account is locked for five minutes. This is a particular implementation of one of the Personal Community mechanisms, which are known as the   time-based   lockout mechanism and the   successive failure   lockout mechanism.

To implement account lockout behavior that differs from the default, extend the   HSPortal.Account.Sec.Lockout   class.

In the subclass that you create, you can:

• Modify the time-based lockout mechanism.

• Modify the successive failure mechanism.

• Implement a site-specific mechanism.

• Specify alternate lockout messages.

To implement site-specific lockout behavior, the procedure is:

1. Create a subclass of the   HSPortal.Account.Sec.Lockout   class in the Personal Community namespace.

2. Modify this subclass.

3. Compile the subclass, which makes it available for use by Personal Community.

4. Enable your lockout class.  You can do this by running the following InterSystems IRIS for Health Terminal call in your Personal Community namespace:

   Enable Custom Lockout Class

   Set status = ##class(Acct.Config).SetLockoutClass("classname")
   

   where  classname is the name of the custom lockout class, including its full package.

Modifying the Time-Based Lockout Mechanism

The time-based account lockout mechanism uses the following logic:

If there are 
    MAXPERIODICFAILEDLOGINS within FAILEDLOGINPERIOD seconds,
then lock the account for
    PERIODICLOGINLOCKOUTTIME seconds.

The capitalized terms in the logic are all parameters of the   HSPortal.Account.Sec.Lockout   class:

• MAXPERIODICFAILEDLOGINS   — Specifies the maximum number of times that there can be failed login attempts during the specified amount of time. The default value is 3; a value of   ""   or   0   disables the policy.

• FAILEDLOGINPERIOD   — Specifies the amount of time in seconds during which failed login attempts are measured. The first failed login attempt after a successful login begins the timing of this period. The default value is 300.

• PERIODICLOGINLOCKOUTTIME   — Specifies the duration of the lockout in seconds. The default value is 300; a value of   ""   or   0   indicates an indefinite lockout.

To modify this mechanism, specify values for these parameters in your custom class.

Modifying the Successive Failure Mechanism

The successive failure account lockout mechanism uses the following logic:

If there are 
    MAXSEQUENTIALFAILEDLOGINS,
then lock the account for
    SEQUENTIALLOGINLOCKOUTTIME seconds.

The capitalized terms in the logic are all parameters of the   HSPortal.Account.Sec.Lockout   class:

• MAXSEQUENTIALFAILEDLOGINS   — Specifies the maximum number of times that there can be failed login attempts. The default value is   "" ; a value of   ""   or   0   disables the policy. Hence, this mechanism is disabled by default.

• SEQUENTIALLOGINLOCKOUTTIME   — Specifies the duration of the lockout in seconds. A value of   ""   or   0   indicates an indefinite lockout.

To modify this mechanism, specify values for these parameters in your custom class.

Implementing a Site-specific Mechanism

All the logic for the lockout mechanism appears in the  OnCheckLockout   method of the  HSPortal.Account.Sec.Lockout  class. Your organization can implement its own mechanism by overriding this method in your custom class and implementing new code in it.

Specifying Alternate Lockout Messages

The  GetLockoutMessage   method includes the logic that displays lockout messages for members who provide the proper username and password for a locked account. Your organization can implement site-specific messages by overriding this method in your custom class and replacing its content.

To configure your Personal Community production for two-factor authentication:

1. Logon to the Management Portal for Personal Community as a user with the  %EnsRole_Administrator  role.
2. In your Personal Community namespace, go to the  Production Configuration  page. Specifically:
   1. Go to your Personal Community namespace by selecting  Switch  from the title bar and choosing its name in the namespace chooser.
   2. From the Management Portal, select  Interoperability > Configure > Production .

3. Set up the business process:

   1. On the  Production Configuration page, under Processes , select the  + icon, to add a new business process. This displays the Business Process Wizard .
   2. Select the HSPortal.Production.Process.TwoFactorAuthenticationNotificationProcess  class in the  Process Class  drop down menu and do the following:
      1. Fill in the Process Name field with the following name : HSPortal_TwoFactorAuthenticationNotificationProcess.
      2. Select the  Enabled  check box and then select the  Apply  button to enable the component.
   3. After you add the process, set its property values as follows:
      • Under  Basic Settings:
        • EmailOperation  - Select HSPortal_EmailOperation  from the drop down menu.
4. Set up the business service:
   1. On the  Production Configuration  page, under   Services , select the  +  icon, to add a new business operation. This displays the  Business Service Wizard .
   2. Select the HSPortal.Production.Service.TwoFactorAuthenticationNotificationService  class in the   Service Class  drop down menu and do the following:
      1. Fill in the   Service Name   field with the following name: HSPortal_TwoFactorAuthenticationNotificationService.
      2. Select the  Enabled  check box and then select the  Apply  button to enable the component.
   3. After you add the service, set its property values as follows:
      • Under  Basic Settings:
        • NotificationTarget - Select HSPortal_TwoFactorAuthenticationNotificationProcess from the drop down menu.

To enable two-factor authentication for patient sign-in:

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

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

3. In the  Feature Controls  section, under Authentication , select the  Enable Two-Factor Authentication for Sign-In  checkbox.

4. Select  Apply  at the bottom of the page.

Communications with the   HSPortal.Production.Service.APIProxyService   web service have the following requirements:

• Coding is external to Personal Community — hence, the code is associated with whatever entity invokes the web service.

• Each proxy request must include identifiers for both the proxy and the principal. These can be either an assigning authority (AA) and a medical record number (MRN) or a patient’s ID in the Master Patient Index (MPIID), or both. The proxy and the patient can use different identifiers.

• Both the proxy and the principal must already be enrolled in Personal Community.

• Personal Community does not perform any validation on the proxy message. Rather, it assumes that your code has confirmed that the proxy relationship is valid by enforcing the necessary business rules, such as for identity verification and proxy consent validation.

• The request must specify the relationship between the proxy and the principal.

• By default, API proxy requests must be made over HTTPS. Check with the Workbench administrator to verify the value of the SOAP over HTTPS setting.

• Use WS-Security headers for authentication and message-level security. The Web service does not support SAML.

The web service accepts the following data:

• A unique identifier for the proxy, which is either:

  • MRN and AA – A valid MRN that already exists in the MPI as well as the AssigningAuthority code corresponding to the MRN.

  • MPIID – Valid HealthShare MPIID.

• A unique identifier for the principal, which is either:

  • MRN and AA – A valid MRN that already exists in the MPI as well as the AssigningAuthority code corresponding to the MRN.

  • MPIID – Valid HealthShare MPIID.

• Relationship — A value of   Father ,   Mother ,   Son ,   Daughter ,   Spouse ,   Partner , or   Other .

To add a proxy relationship type:

1. Log into the Workbench as a user with the Configuration Manager role.
2. Select the  Setup tab.
3. From the  Setup  tab's menu choices, select  Proxy Relationship Types .  This displays the Proxy Relationship Types page.
4. On the  Proxy Relationship Types  page, select  Add Proxy Relationship Type .  This displays the  Proxy Relationship Type Details  page.
5. On the  Proxy Relationship Type Details  page:
   1. In the  Name field, enter the name under which this proxy relationship type will appear in the Workbench.  For example: if the personal relationship between principals and proxies that you want to describe is "attorney-client," you could use the name  Attorney  or  Attorney-Client .
   2. In the  Description field, enter a description for this definition.  The definition will appear to Workbench users only: members will not see it.
   3. Select  Save .
   4. Add at least one translation for the proxy relationship type.  Each translation contains display text for a specific locale; this display text appears on the account pages of both proxy and principal to describe their personal relationship:
      1. Select  Add Translation .  This displays the  Translation Details  page.
      2. In the  Locale select list, choose a locale for the translation.  All Personal Community instances allow you to choose the "English" locale; if your instance is localized for other languages, those options will appear in the list as well.  For more information on localization, see the "Supporting Multiple Languages: Localization" section of the "Working with Screen Text, Help, and Notifications" chapter of  Customizing the HealthShare Personal Community User Interface.
      3. In the  Proxy Display  text box, enter the label that will be displayed for the proxy's relationship to the principal when the account of either principal or proxy is viewed in the Workbench.  Using the  Attorney-Client  example, you would enter  Attorney  here.
      4. In the  Principal Display text box, enter the label that will be displayed for the principal's relationship to the proxy when the account of either principal or proxy is viewed in the Workbench or when the proxy logs into Personal Community.  Using the   Attorney-Client example, you would enter  Client here.
      5. Select  Save .

To add a translation to a proxy relationship type:

1. Log into the Workbench as a user with the Configuration Manager role.
2. Select the  Setup tab.
3. From the  Setup tab's menu choices, select  Proxy Relationship Types .  This displays the  Proxy Relationship Types  page.
4. On the  Proxy Relationship Types  page, select the row for the proxy relationship type to which you want to add a translation.  This displays the  Proxy Relationship Type Details  page.
5. On the  Proxy  Relationship Type Details page:
   1. Select  Add Translation .  This displays the  Translation Details  page.
   2. In the  Locale select list, choose a locale for the translation.  The locale for which you wish to add a translation should be listed.  If it is not listed, confer with the person on your project team who does UI customization.
   3. In the  Proxy Display  text box, enter the label that will be displayed for the proxy's relationship to the principal when the account of either principal or proxy  is viewed in the Workbench.  User the  Attorney-Client  example, you would enter  Attorney here.
   4. In the  Principal Display text box, enter the label that will be displayed for the principal's relationship to the proxy when the account of either principal or proxy is viewed in the Workbench or when the proxy logs into Personal Community.  Using the  Attorney-Client example, you would enter  Client here.
   5. Select  Save .

To change a translation in a proxy relationship type:

1. Log into the Workbench as a user with the  Configuration Manager role.
2. Select the  Setup tab.
3. From the  Setup tab's menu choices, select  Proxy Relationship Types .  This displays the  Proxy Relationship Types page.
4. On the  Proxy Relationship Types  page, select the row for the proxy relationship type to which you want to add a translation.  This displays the  Proxy Relationship Type Details page.
5. On the  Proxy Relationship Type Details  page:
   1. Locate the row for the translation you want to change and choose  Modify .
   2. Change the locale, if required.
   3. Change the display text for  Proxy Display  or  Principal Display , if required
   4. Select  Save .

To remove a translation from a proxy relationship type:

1. Log into the Workbench as a user with the  Configuration Manager  role.
2. Select the  Setup  tab.
3. From the  Setup tab's menu choices, select  Proxy Relationship Types .  This displays the  Proxy Relationship Types  page.
4. On the  Proxy Relationship Types  page, select the row for the proxy relationship type to which you want to add a translation.  This displays the  Proxy Relationship Type Details  page.
5. On the  Proxy Relationship Type Details page, locate the row for the translation you want to change and choose  Remove , then confirm the action at the resulting prompt.

To disable a proxy relationship type:

1. Log into the Workbench as a user with the Configuration Manager role.
2. Select the  Setup  tab.
3. From the  Setup tab's menu choices, select  Proxy Relationship Types .  This displays the  Proxy Relationship Types  page.
4. On the  Proxy Relationship Types  page, select the row for the proxy relationship type that you want to disable.  This displays the  Proxy Relationship Type Details  page.
5. On the  Proxy Relationship Type Details  page, choose  Disable , then confirm the action at the resulting prompt.

To re-enable a proxy relationship type:

1. Log into the Workbench as a user with the Configuration Manager role.
2. Select the  Setup tab.
3. From the  Setup tab's menu choices, select  Proxy Relationship Types .  This displays the  Proxy Relationship Types page.
4. On the  Proxy Relationship Types page, select the row for the proxy relationship type that you want to re-enable.  This displays the  Proxy Relationship Type Details  page.
5. On the  Proxy Relationship Type Details  page, choose  Enable , then confirm the action at the resulting prompt.

If you have an external system with an API for consent, you can create a custom business operation that calls this API to send patient consent information to Personal Community.

Using the API response, the operation must map fields from the external system to data fields in Personal Community. For any given consent field that your external system has, make sure that there is only one value per patient. If the field contains a data in a table, for example, it will not work properly when sent to Personal Community.

Personal Community supports the following data types for consent:

• Text 
• Date
• Checkbox
• Radio 
• Select
• Signature

Dates need to be in the form  YYYY-MM-DD.

If a Signature data type is utilized, it will be required to be entered each time a patient makes an update to the consent.  A Signature can be stored as data type %Stream.GlobalBinary. 

To create a site-specific business operation for consent:

1. Create a new class that extends HSPortal.Production.Operation.AbstractConsentOperation.cls

   IMPORTANT

   InterSystems strongly recommends that the new class should be part of a site-specific package. Do not add it to the HSPortal package.

2. Override the following class methods:

   • OnConsentListRequest  - Fetches the consent list, of the data type HSPortal.Production.Message.ConsentListRequest, that will be provided to the patient. This method expects two parameters:
     • pRequest - HSPortal.Production.Message.ConsentListRequest
     • pResponse - HSPortal.Production.Message.ConsentListResponse
   • OnConsentUpdate - Sends the updated consent back to the external system. This method expects two parameters:
     • pRequest - HSPortal.Production.Message.ConsentUpdateRequest
     • pResponse - HSPortal.Production.Message.ConsentUpdateResponse
3. Compile your new class.

After you've created your custom class, you will need to create a business operation and modify a business service in the Personal Community production:

1. Logon to the Management Portal for Personal Community as a user with the  %EnsRole_Administrator  role.
2. In your Personal Community namespace, go to the  Production Configuration  page. Specifically:
   1. Go to your Personal Community namespace by selecting  Switch  from the title bar and choosing its name in the namespace chooser.
   2. From the Management Portal, select  Interoperability > Configure > Production .

3. Set up the business operation:

   1. On the   Production Configuration  page, under  Operations , select the  +  icon, to add a new business operation. This displays the  Business Operation Wizard .
   2. Select the custom class you created in the  Operation Class  drop down menu and do the following:
      1. Fill in the Operation Name field with a name of your choice, for instance : External _ConsentOperation.
      2. Select the  Enabled  check box and then select the  Apply  button to enable the component.
   3. After you add the operation, set its property values as required.
   4. Select  OK   to save the business operation.
4. Modify the  HSPortal_ConsentService   business service:

   1. On the  Production Configuration  page, under  Services , select   HSPortal_ConsentService .

   2. Modify its property values as follows:

      • SubmissionTarget  - The name of your custom business operation. In this example,  External_ConsentOperation .

To enable consent management, in the Workbench:

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  Feature Control  tab. 
3. Select  Edit Mode   to make edits to the fields described in the following steps.
4. To enable viewing of consent preferences, In the Account Settings box, select the checkbox to the left of Enable Consent.
5. To additionally enable editing of consent preferences, select from the following in the Account Settings box:
   
   • Enable Patient Consent Management  - select this checkbox to allow patients to manage their own consent preferences. 
   • Enable Proxy Consent Management  - select this checkbox to allow proxies to manage the consent preferences of their principal.

6. After you have finished, select   Submit   at the bottom of the page to save your changes.