Skip to main content
Engage Configuration Guide
Updated over 10 months ago

Before configuring Engage please ensure that Engage has been successfully installed for your Penelope database.

We highly recommend that Engage is not enabled in a production environment until it has been successfully installed. If the Penelope components of Engage are enabled prior to installation, clients with Message Settings enabled could receive emails requesting they complete Documents and/or respond to Discussions. Until Engage has been installed, the links in these emails will not be functional.

Table of Contents


Getting started with Engage

Engage enables clients to participate in their service provision through the Workflow and Discussion features in Penelope.

In Penelope version 4.4.0.0 and higher, both the Workflow and Discussion features have extended, client-based functionality to allow for two-way communication between staff and their clients. When Engage is installed and enabled and clients have consented to receive email communication, staff can initiate email-based communication (either a Workflow or Discussion) sent from Penelope to the client.

Clients are presented with a link to an external-facing webpage where they can either complete Document(s) or reply to a Discussion. Note that communication via SMS is not supported for Engage.

Note: Record of communications sent to clients through Engage cannot be deleted from Penelope including manually created and Action Trigger-based communications. You also cannot delete Documents completed by a client or a client’s response to a Discussion. Consequently, any records (for example, Service File, Individual Profile, etc.) that include client-facing communication cannot be deleted from Penelope.

Workflows Client

Workflows allow clients to complete Documents outside of Penelope. Client Workflows can occur at the Individual, Case, Service File, and Service Event levels in Penelope.

You can create two types of Client Workflows: New Document and Checklist tasks.

When you select a single Document for the client to complete, a New Document task is created; when you select two or more Documents for the client to complete, a Checklist task is created. After you save the task, an email communication is sent to the client with a link to complete the assigned Document(s).

When the client clicks the link, they will see the Document(s) they’ve been asked to complete. They will also have the ability to ask the staff member a question about the Documents (note that this option will not appear if you have disabled client responses), and the option to refuse to complete the Document(s).

Clients can respond to a discussion a maximum of three times until the worker replies. If the client chooses to ask a question, they initiate a Discussion that is visible in the Messages section of the associated screen in Penelope. If the client refuses to complete the Document(s), the task is reassigned to the worker and the client will not be able to access the workflow task again.

Discussions

Client Discussions can be initiated allowing workers and clients to conduct two-way communications. This back-and-forth communication becomes part of the client’s clinical record in Penelope. Client discussions can occur at the Individual, Individual Account Summary, Individual Policy, Case, Service File, Service Event, Group, and Group Event levels in Penelope. After you save the initial Discussion, an email is sent to the client with a link to reply to the message.

Clients can then reply to the communication by following the link.

Once the client responds, the text is visible from the Messages tab on the screen in Penelope that is associated with the discussion.

Clients can respond to a discussion a maximum of three times until the worker replies.

Email and site footers Both the Engage site and emails sent from Engage include additional information and links in the footer of the page and the bottom of the email respectively. This information includes your Agency or Site name and address, links to Help, Privacy Policy, and Technical Problem information, and (optionally) additional footer text.

As part of the configuration process, you specify whether you want your Agency name and address or the client’s assigned Site name and address to appear. Further, you can specify the destination of the links to the Help, Privacy Policy, and Technical Problems.

The Help URL is designed to contain a link to your “How-to” materials that your clients can review should they have questions about using Engage. While you are welcome to post a link to our Reply to your practitioner tutorial, we encourage you to create your own agency-branded materials. Not only will your clients be more familiar with your own branding, you can include other pertinent information relevant to your agency’s use of Engage.

The Privacy Policy URL is designed to contain a link to your agency’s confidentiality, privacy, (or similar) policy.

The Technical Problems URL is designed to contain a link to any troubleshooting information or contact information where your clients can get help with filling out a document/replying to a discussion. Please note that this link should not direct clients to Penelope Software Technical Support but rather a point-person at your agency.

The other text (for example, “Each Document will guide you through a series of questions…”) is standard to Penelope/Engage and cannot be modified. Lastly, you can also configure a link to your agency’s logo or specify any additional text you want to appear in the footer (shown as “Welcome to our Engage site!” in the example above).

About configuring Engage

Before you begin configuring Engage, please ensure that Engage has been successfully installed for your Penelope database. We highly recommend against enabling Engage in a production environment until you have successfully installed Engage. If the Penelope components of Engage are enabled in a production environment prior to the installation of Engage, clients with Message Settings enabled could receive emails requesting they complete documents and respond to discussions.

Until Engage has been installed, the links in these emails will not be functional. For more information about installing Engage, please contact our Technical Support team by logging a ticket here: support ticket.

You can also install Engage for a training environment. If your training environment contains a copy of data from a production database and you intend to test Engage functionality in the training, we recommend you consider removing data from Individual Message settings to ensure absolutely no erroneous emails are delivered to individuals.

Engage configuration must be completed in two sections of the System Administration panel: External Communications and Engage. Configuring the email component of External Communications is a mandatory component of the Engage configuration process as the Engage setup section cannot be modified until email has been successfully configured.

Once you have configured email, you will then need to enable Client Delivery in the client Message Settings section and configure additional settings. If you have previously configured External Communications and enabled client delivery, the Engage feature will be available for configuration immediately upon upgrading.

The remainder of the configuration tasks take place in the Engage Setup section where you can choose which components of the Engage feature you want to use and specify your agency URLs.

Please note that Engage requires an externally accessible URL. The URL entered on the Engage Setup page must include https://. Prior to enabling Engage, Penelope tests the link to ensure that it is functional.

The Engage status/ping box is there to ensure that everything works if you want to test prior to enabling Engage. This will only work if Engage is up and running at the URL and if Engage can access the database. If the URL is invalid, you cannot enable Engage. Process flow: Configure Engage for the first time.

Note: Although you can configure the Engage feature within Penelope prior to installing the Engage component, you should not enable Engage in a production environment until the standalone Engage components have been installed.

Step 1: Configure external communications settings for email

To enable the Engage feature, you must configure your email External Communication settings. If you have already configured your External Communication settings for use with email (note that SMS cannot be used with the Engage feature), you can use the same settings.

Note: if you face difficulty or issues, Penelope implemented SendGrid as a better option.

Prerequisite:

You must be logged in to Penelope using a System Administrator account.

1. In the System Setup section, click External Communications.

2. In the Email section, click Edit.

3. Complete the following fields with information from your email provider:

4. Click Save.

5. To ensure the settings are configured accurately, click Test.

6. In the Recipient field, type an email address to send a test email to.

7. In the Subject and Body fields, type content you would like to include in the test email.

8. Click Save.

9. If the test email is received successfully, click Enable. Otherwise, review and adjust the settings in step 3 until the test passes.

Step 2: Configure client message settings

Prerequisite:

You must be logged in to Penelope using a System Administrator account.

1. In the System Setup section, click External Communications.

2. Click the Recipient Configuration tab.

3. In the Client Message Settings section, click Edit.

4. In the Client Settings section, click the Enable Client Delivery option.

5. (Optional) To enable Event Confirmation options, complete the following fields:

a. To send event confirmations, click the Send event confirmation option.

b. In the Send confirmation before field, type the number of hours before an event that the message should be sent.

c. In the Sender of confirmation field, type which Worker should be listed as the message sender.

d. To enable return messages, click the Include return message option.

e. If desired, in the Include additional recipients on return of confirmation, select the desired Worker Category.

6. (Optional) To enable Event Updates, complete the following fields:

a. To send notifications to a client when an event is booked, click the Send Event booking notification option.

b. To send notifications to a client when an event is rescheduled, click the Send Event reschedule notification option.

7. (Required) To enable Client Communication and Workflow settings, click any of the following options:

• Enable from Individual Account Summary

• Enable from Individual Policy

• Enable from Individual Profile

• Enable from Case

• Enable from Service File

• Enable from Service Event

• Enable from Group (Note: Engage Discussions and Workflows are not available for Groups)

• Enable Group Event (Note: Engage Discussions and Workflows are not available for Group Events)

8. Click Save.

Step 3: Configure Engage

Prerequisite:

You must be logged in to Penelope using a System Administrator account.

1. In the System Setup section, click Engage.

2. Click Edit.

3. In the General Settings section, configure the following settings:

4. In the Engage Presentation Settings section, configure the following settings:

5. Click Save.

Note: It can take up to 15 minutes for the Help, Privacy Policy, Technical Problems, and Organization Contact URLs to update on the Engage site (though they will take immediate effect in emails sent to clients).

Step 4a: Test Engage to validate the connection between Penelope and Engage

1. In the System Setup section, click Engage.

2. In the Engage Status section, click Ping.

If you encounter issues while testing Engage, review the configuration settings outlined at Steps above and complete the test again until you have a successful connection.

For additional help, please contact the Support team.

Penelope Software 12 Troubleshooting

You might see errors like the example below when trying to ping Engage:

"Penelope does not recognize the SSL certificate for Engage and cannot establish a connection with Engage. Please refer to the Engage help materials for further detail on how to troubleshoot this error."

Solution 1: Update Penelope's JVM to a newer patch set (for example, from Java 7.X.1 to Java 7.X.2) or upgrade Java (for example, from Java 7 to Java 8).

Next, attempt to ping Engage again to determine if further action is required. If the ping is successful, you can continue with the remaining configuration steps.

Solution 2: Manually import the Engage SSL certificate to Penelope's JVM "keystore" using the Java "keytool" command. Exercise caution with this step to ensure you do not affect the general Penelope configuration.

Next, attempt to ping Engage again to determine if further action is required. If the ping is successful, you can continue with the remaining configuration steps.

Solution 3: Create a new SSL truststore based on the Engage SSL certificate and pass it to Penelope's startup command line as runtime JVM arguments.

Next, attempt to ping Engage again.

Step 4b: Test Engage To validate that the Engage site will load correctly

1. In a browser, navigate to: https:///testPage Result: The following “Oops…” page should appear in your browser:

Step 5: Configure an existing client’s Message Settings

Complete these steps to update an existing client’s profile with their preferred email address and/or cell phone number for use with the External Communications and Engage features.

In version Penelope 4.4.1 and above, you can configure a new client’s Message Settings as part of the intake process in the Intake Wizard or Add Individual tools.

Prerequisite:

You must be logged in to Penelope using an Intake-Mgmt, Clinical Worker, or Admin-Exec account.

1. Browse to the client’s Individual Profile.

2. Click the Message Settings tab.

3. Click Edit.

4. In the Email Communications via drop-down, select which email address the client wants to use.

5. In the SMS Communications via drop-down, select which SMS-capable phone number the client wants to use.

6. In the Client Consents to Receive section, choose which types of communication the client has agreed to receive.

7. Click Save.

Step 6: Customize Documents for use with Engage

For more information about customizing client-facing Documents for use with the Engage feature, see the Documents Guide.

Step 7: Customize Action Triggers for use with Engage

For more information about customizing Action Triggers for use with the Engage feature, see the Action Triggers Guide.

Penelope Software 14 Managing Engage About managing or disabling Engage In general, we do not recommend disabling the Engage or External Communications features after you have begun using them to communicate with clients.

That said, exceptions exist in extreme circumstances such as if your agency is in the process of changing email providers. If you need to update or change information about your email provider, you should only edit the External Communication settings. Engage will remain enabled, but you will not be able to make changes to the Engage setup or send new Workflow or Discussion communications to clients until the changes are complete.

We only recommend making changes to External Communication sessions during off-peak or inactive hours at your agency to avoid interfering with staff sending Workflow or Discussion communications to clients.

We highly recommend that you do not disable the Engage feature as this action is irreversible (disabling Engage is considered as clearing the Enable Client Workflows and Enable Client Discussions options).

If you disable Engage, all active Workflows and Discussions currently assigned to clients will be reassigned to a worker.

Clients will also be removed as followers on the Discussion or Workflow tasks, and cannot be re-added. Both of these outcomes are irreversible.

Note that existing Engage Discussions and Workflows will not queue up to be sent out once Engage is re-enabled. Workers will need to create a new Discussion or Workflow to send to their clients.

Modify the URL for accessing Engage

Prerequisite:

You must be logged in to Penelope using a System Administrator account.

1. In the System Setup section, click Engage.

2. Click Edit.

3. In the URL for accessing Engage field, type the new URL (including https://) for Engage.

4. Click Save.

Modify which name and address appear in Engage landing pages

Prerequisite:

You must be logged in to Penelope using a System Administrator account.

1. In the System Setup section, click Engage.

2. Click Edit.

3. In the Engage Presentation Settings section, select which name and address you want to display on Engage landing pages.

4. Click Save.

Modify how you refer to a worker in Engage

Prerequisite:

You must be logged in to Penelope using a System Administrator account.

1. In the System Setup section, click Engage.

2. Click Edit.

3. In the Refer to worker as field, type the term you’d like to use for workers. For example, Therapist. Penelope Software 15

4. Click Save.

Modify the URLs used in Engage landing pages

Prerequisite:

You must be logged in to Penelope using a System Administrator account.

1. In the System Setup section, click Engage.

2. Click Edit.

3. Complete any of the following options:

• In the Help URL field, type the help link for your organization.

• In the Privacy Policy URL field, type the privacy policy link for your organization.

• In the Technical Problems URL field, type the technical problems link for your organization.

• In the Organization contact URL field, type the organization contact link for your organization.

4. Click Save.

Note: Modifying these URLs can take up to 15 minutes to take effect on the Engage site (though they will take immediate effect in emails sent to clients). We recommend modifying the URLs at a time when it is unlikely you will need to send Engage Discussions or Workflows to your clients.

Modify the footer information in Engage landing pages

Prerequisite:

You must be logged in to Penelope using a System Administrator account.

1. In the System Setup section, click Engage.

2. Click Edit.

3. In the Additional footer information field, type any additional text you want to display on Engage landing pages.

4. Click Save.

Did this answer your question?