For hosted customers please raise a new case online and reference the title of this article. Please provide the name or URL of the Mosaic instances this relates to.
This knowledge article is intended for engineers who are familiar with installation and configuring of Weblogic / MIS. For MIS installation guidance please use this article
Supporting MS Modern Authentication
Mosaic minimum version: 24.1
Support for email notifications to MS Exchange with Oauth2 is compatible with Mosaic from version 24.1 onwards.
📌Note: To open the below link, you'll need to log in to the Customer Success Portal.
Please see the Mosaic 24.1 release notes for detail: Access Mosaic Case Management: 24.1.0.0 release notes
Pre-requisites
Mosaic Interface Server (MIS) version 4.1.1.0 or later.
Mosaic 5.13.1.0 or later.
SMTP/Mail server specified must support TLS connection.
Provide a username and password for the SMTP/Mail server (no anonymous connections).
SMTP/Mail server password must only contain alpha numeric characters (no special characters).
Firewall rules allow connection to the SMTP/Mail server.
Mosaic Email configuration
The Mosaic Email configuration screen, Tools, Configuration Tools, Email, is used to define the SMTP/Mail server Hostname or IP address, Port, the username and password for authentication by that server and the Sender email address and failover email address, Alerts Email Settings, From Address & Failover Address. The From and Failover Address can be the same. The email specified in the From Address must be allowed to send emails.
The email settings can be tested outside of Mosaic from the Mosaic app server using telnet. This will confirm that the appropriate firewall rules are in place, see example below, replace [mymailserver.com] with the value specified in Host name.
telnet mymailserver.com 25
If you are specifying a hostname rather than an IP address for the SMTP/Mail server you may need to add this to the hosts file on the Mosaic app server first.
Check and clear any backlog of case note alert emails
Mosaic user could have been trying to send case note email notifications before this feature was setup and configured correctly. This would result in a back log of emails waiting to be sent. It is important to confirm this before implementing to avoid the possibility of 100's or 1000's of old emails been sent all at once. Any old emails waiting to be sent can be expired using the instruction below. It is important that you obtain written permission from the customer beforehand.
The following SQL will identify any case note email alerts waiting to be sent. It is recommend to perform a count(*) first has the results could be quite large. You can change count(*) to just * if you wish to see the records.
select count(*) from case_note_recipients where notify_email = 'Y' and email_status = 'N' select count(*) from case_note_recipients where notify_email = 'Y' and email_status = 'P' select count(*) from mo_case_note_alert_recipients where notify_email = 'Y' and email_status = 'N' select count(*) from mo_case_note_alert_recipients where notify_email = 'Y' and email_status = 'P'
To expire the case note email alerts use the following SQL where applicable, as determined by the previous SQL.
update case_note_recipients set email_status = 'RE' where notify_email = 'Y' and email_status = 'N';
update case_note_recipients set email_status = 'RE' where notify_email = 'Y' and email_status = 'P';
update mo_case_note_alert_recipients set email_status = 'RE' where notify_email = 'Y' and email_status = 'N';
update mo_case_note_alert_recipients set email_status = 'RE' where notify_email = 'Y' and email_status = 'P'
Case note alerts recipients check box
From Mosaic version 20.1.0.0 onwards the system property caseNoteAlertsEmailEnabled needs setting to TRUE for the Case note alerts recipients check box to be shown. To show this check box run the SQL below.
📌 Note: This change will not take effect until Mosaic is restarted.
UPDATE system_properties SET value='TRUE' WHERE name='caseNoteAlertsEmailEnabled';
Configuring MIS
Copy the jar file mos_email-resource-adapters.jar from location mis-dist.zip\mis\resource-adapters to the MIS deployment folder specified in the MIS server start arguments in Weblogic. e.g. /home/oracle/mis-deployment.
Unzip the configuration-dist.zip available in mis/configuration and copy mos_email-resource-adapter.properties from configuration-dist.zip\interfaces\mos_email to the MIS deployment folder specified in the MIS server start arguments in Weblogic. e.g. /home/oracle/mis-deployment. mos_email-resource-adapter.properties has the Cron expression for the Job Scheduler to trigger on specified intervals to:
Pick a step or request for sending email.
Update a step or request email sent status.
Pick a failed step and request a retry to send the email.
Update retried step and request email sent status.
Pick a case note for sending email.
Update a case note email sent status.
Pick a failed case note for retry.
Update retried case note email sent status.
Update mos_email-resource-adapter.properties with the correct email.port (for example: 587 or 25).
📌 Note: For later versions of MIS email.port has been removed from the mos_email-resource-adapter.properties and is specified in Mosaic. See Tools - Configuration Tools - Email Settings.
Configure the email message body
When a request is created in a workflow step, Mosaic can be configured to send an email notification to the involved workers. You can configure the email message body to include text that will direct you to Mosaic. There are two options; one that will direct you to the Mosaic login page (default) and one that will direct you to the person summary related to the workflow step. These options can be applied to single person workflow steps.
Mosaic login URL in system properties must be the URL of the Mosaic instance. This can be configured as follows (replace <MOSAIC_LOGIN_URL> with the actual value):
update system_properties
set value = 'https://<MOSAIC_LOGIN_URL>/'
where name = 'MosaicLoginURL'
Include a link to the person summary
To include a link to the person summary in the email alert notification, you need to update the email template text by running the following SQL script:
update notification_rule
set message_template = 'A [REQUEST_TYPE] request for (person with id [PERSON_ID]|organisation with id[ORGANISATION_ID]|group with id [GROUP_ID]|No Subject) has been assigned to (you|[WORKER_NAME]|[TEAM_NAME]). Please log in to Mosaic (at [MOSAIC_LOGIN_URL][PERSON_ID]) to view the request.'
where not_rule_type = 'REQASSIGNNOTIFY'
With this message template, when a request is created in a workflow step for a person and email alerts have been configured, the email notification will contain a link that will direct you to the person summary.
Default configuration
The default configuration of email recipients can be reverted by running the following scripts:
update notification_rule
set message_template = 'A [REQUEST_TYPE] request for (person with id [PERSON_ID]|organisation with id[ORGANISATION_ID]|group with id [GROUP_ID]|No Subject) has been assigned to (you|[WORKER_NAME]|[TEAM_NAME]). Please log in to Mosaic (at [MOSAIC_LOGIN_URL]) to view the request.'
where not_rule_type = 'REQASSIGNNOTIFY'