Web: Office 365 (O365) Email Settings: Difference between revisions

Latest revision as of 15:57, 31 July 2023

Office 365 Azure Active Directory / Entra ID Setup

NOTE: Microsoft renamed Azure Active Directory to Microsoft Entra ID in August 2023. Some changes may appear from the screen shots shown.

In the Azure Active Directory / Entra ID menu, click on "App registrations"

At the top of the "App registrations" page, click on the "+ New Registration" link

In the "Register an application" page:

Enter a "Name" for the application, for example, "Prime 16 Email Application".
Leave the "Supported account types" selection of "Accounts in this organizational directory only".
In "Redirect URI", choose "Public client/native (mobile & desktop)" and enter "http://localhost:3017" in the next box.
Click the "Register" button

This should return you to the new app registration. Your chosen Name for the application should appear at the top of the form. Now click on the "API permissions" link

In the "API permissions" page, click on the "+ Add a permission" link

In the "Request API permissions" box, select "Microsoft Graph"

When asked "What type of permissions does your application require?", choose "Delegated permissions"

From the resulting list below that, check the box next to the following options;

OpenId permissions:

email
offline_access
openid
profile

IMAP

IMAP.AccessAsUser.All

MailboxSettings

MailboxSettings.Read

Mail

Mail.Read
Mail.Read.Shared
Mail.ReadWrite
Mail.ReadWrite.Shared
Mail.Send
Mail.Send.Shared

SMTP

SMTP.Send

User

User.Read

Click "Add permissions" at the bottom of the "Request API permissions" box.

The resulting page should look like this:

Click "+ Add a permission" link in the "API permissions" page.

This time, select "APIs my organization uses" at the top. In the search box, enter "Office 365 Exchange Online". Choose the resulting entry, then choose "Delegated permissions". Then, in "EWS" select the "EWS.AccessAsUser.All" entry. Choose "Add permissions" at the bottom.

Click the "Grant admin consent for kempscaseworks.com" at the top of the "API permissions page". And choose yes. This will keep users from seeing the "Do you grant consent to this application" when they attempt to use the Email system

Prime 16 Setup

Within Prime 16, go to Administration-->Administration Menu. Select "Office 365 (O365) Email Setup" from the Administration system options. You can also type "365" in the search box to find it quickly. Enter the values as follow:

Office 365 Settings
Item	Entry
OnlyOneRowAllowed	True
Redirect URI	<your url to the basic webite>/O365/O365Login.aspx. So, for example, that might be: https://demo.kempscaseworks.com/prime16/o365/o365login.aspx
the Client ID	<copy value for Application (client) ID from the App registration you created above as shown File:Screenshot 2022-12-09 at 1.17.45 PM.pnghere>
client Secret	<Enter a random string, for example: jo2i3jutr98uyxcvoijkn2>
scope	https://outlook.office.com/IMAP.AccessAsUser.All%20offline_access%20email%20openid
auth Uri	<copy value the App registration, click on Endpoints and enter the value from "OAuth 2.0 authorization endpoing (v2)". That should look like this: https://login.microsoftonline.com/<your directory tenant id>/oauth2/v2.0/authorize >
token Uri	<copy value the App registration, click on Endpoints and enter the value from "OAuth 2.0 token endpoing (v2)". That should look like this: https://login.microsoftonline.com/<your directory tenant id>/oauth2/v2.0/token

Close this form to save the entries.

Staff Member Setup

Open the Staff Member Input Form Administration-->Administration Menu. Search "Staff" to quickly find the "Staff - Search/Edit" option and select it. Find and open a staff person's entry.

In the "Email Setup" tab, ensure the following entries:

Staff Email Settings Setup
Item	Entry	Notes
Email Name (shown in outgoing email)	User Name	If the user will be given permission to send and read mail from a shared mailbox in the organization system AND they want only to use that email from within Prime, you may enter the Name for that shared email box here and leave the "Send As Email Name" entry below blank.
Account type	IMAP
Incoming mail server	outlook.office365.com
Incoming port	993
Incoming security	SSL
Outgoing mail server	smtp.office365.com
Outgoing port	587
Outgoing security	TLS
Email server username	user.name@organization.org
Email server password	<enter some random string, for example: asd908ju2>	Any random string will be fine when using the Office 365 Email system with Azure Active Directory / Entra ID.
User Office 365 System	Check the box
Send As Email Address	IntakeGroup@organization.org	If the user will be given permission to send and read mail from a shared mailbox in the organization system, you can enter the email address for that shared mailbox here to give the user the ability to select to send from or to read email in that account.
Send As Email Name	Intake Group Mailbox	This is the name that will be included on outgoing email from the shared mailbox.

Staff Member Use

Send An Email

Open a client record. In the Context Menu, choose "Send Email".

The client's email address should be shown in the "Send To" box.

Choose the appropriate "Send As" email. There may be more than one to choose from.

Edit the Subject and body of the email.

If you wish to send documents from the Document Tracking system, click the button. Or to choose a local file (on your workstation), click the "Choose File" button.

Choose whether to add a case note by selecting the checkbox.

When ready, to send the email, click the "Send email" button.

Pull an Email into a Client Record

To pull an email into the Case from your email system, open the client record. In the Context Menu, choose "Get Email".

Choose the appropriate email box from the dropdown and click the "Refresh Email List".

From the resulting list of emails in the Inbox, click "Copy Email to Case" to copy that particular email to the case. If there are attachments that the system sees as attachments, they will be saved to the case's document tracking system.

Always ensure the email and attachments are saved properly in the case before deleting the email.

View Associated Email

To view email that has been associated with a case, open the client record. In the Context Menu, choose "Associated Email".

This will show both incoming and outgoing email associated with the case.

@@ Line 1: / Line 1: @@
-== Basic Information ==
+==Office 365 Azure Active Directory / Entra ID Setup==
-The Office 365 (O365) Email Settings system relies on the organization having and utilizing two things:
+NOTE: Microsoft renamed Azure Active Directory to Microsoft Entra ID in August 2023. Some changes may appear from the screen shots shown.
-# An Azure Active Directory (AAD) system hosted on Microsoft Office 365 system; and,
+In the Azure Active Directory / Entra ID menu, click on "App registrations"
-# An Exchange Email system utilizing and connected to that AAD system.
-== Setup ==
+[[File:Screenshot 2022-12-09 at 9.37.34 AM.png|400px]]
-In Azure Active Directory admin center, click on "App registrations".  [[File:Screenshot 2022-11-29 at 1.53.48 PM.png|200px]]
+At the top of the "App registrations" page, click on the "+ New Registration" link
-Choose "New registration".  [[File:Screenshot 2022-11-29 at 1.55.14 PM.png|200px]]
+[[File:Screenshot 2022-12-09 at 9.40.47 AM.png|400px]]
-In the "Register an application" page, enter a name, such as "Prime 16 Web User Manual Demonstration" (used in this example).  For "Supported account types", choose "Accounts in this organization directory only".  Click the "Register" button.
+In the "Register an application" page:
-In the main page for the app registration, next to Client credentials, click the link.  [[File:Screenshot 2022-11-29 at 2.00.33 PM.png|200px]]
+# Enter a "Name" for the application, for example, "Prime 16 Email Application".
+# Leave the "Supported account types" selection of "Accounts in this organizational directory only".
+# In "Redirect URI", choose "Public client/native (mobile & desktop)" and enter <nowiki>"http://localhost:3017"</nowiki> in the next box.
+# Click the "Register" button
-In the Certificates & secrets page, click on "New client secret".  [[File:Screenshot 2022-11-29 at 2.01.33 PM.png|200px]]
+This should return you to the new app registration.  Your chosen Name for the application should appear at the top of the form.  Now click on the "API permissions" link
-Enter a description for the secret, such as "Prime 16 Demo Client Secret", and choose an expiration.  Make a note of this expiration and come back to create a new one shortly before that period to continue using this system.  Click the "Add" button.
+[[File:Screenshot 2022-12-09 at 9.51.30 AM.png|400px]]
-In the resulting page, make sure to copy the "Value" and "Secret ID" from the page.  The Value is only available once.  [[File:Screenshot 2022-11-29 at 2.04.48 PM.png|200px]]
+In the "API permissions" page, click on the "+ Add a permission" link
-Click on "Overview" to return to the main page.  Next to "Redirect URIs", click the link.  [[File:Screenshot 2022-11-29 at 2.07.50 PM.png|200px]]
+[[File:Screenshot 2022-12-09 at 9.50.32 AM.png|400px]]
-Click "Add URI" and add two new Redirect URIs.  The format of these will be, for example:
+In the "Request API permissions" box, select "Microsoft Graph"
-"https://test.kempscaseworks.com/demo_prime16/o365/o365login.aspx" and
+[[File:Screenshot 2022-12-09 at 9.55.05 AM.png|400px]]
-"https://demo.kempscaseworks.com/prime16/o365/o365login.aspx".  Only using your organization's test and production URI values.
-Save these new entries and return to the Overview.
+When asked "What type of permissions does your application require?", choose "Delegated permissions"
-Click on API permissions and "Add a permission".  Add the following:
+[[File:Screenshot 2022-12-09 at 9.56.47 AM.png|400px]]
-[[File:Screenshot 2022-11-29 at 2.12.21 PM.png|400px]]
+From the resulting list below that, check the box next to the following options;
-Follow the "Register service principals in Exchange" of the web page found here https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth
+'''OpenId permissions: '''
+::* email
+::* offline_access
+::* openid
+::* profile
+'''IMAP'''
+::* IMAP.AccessAsUser.All
+'''MailboxSettings'''
+::* MailboxSettings.Read
+'''Mail'''
+::* Mail.Read
+::* Mail.Read.Shared
+::* Mail.ReadWrite
+::* Mail.ReadWrite.Shared
+::* Mail.Send
+::* Mail.Send.Shared
+'''SMTP'''
+::* SMTP.Send
+'''User'''
+::* User.Read
-SPECIAL NOTE: Do not give access to one mailbox.  Only register an Azure AD application service principal in Exchange.
+Click "Add permissions" at the bottom of the "Request API permissions" box.
+The resulting page should look like this:
+[[File:Screenshot 2022-12-09 at 1.09.50 PM.png|400px]]
+Click "+ Add a permission" link in the "API permissions" page.
+This time, select "APIs my organization uses" at the top.  In the search box, enter "Office 365 Exchange Online".  Choose the resulting entry, then choose "Delegated permissions".  Then, in "EWS" select the "EWS.AccessAsUser.All" entry.  Choose "Add permissions" at the bottom.
+Click the "Grant admin consent for kempscaseworks.com" at the top of the "API permissions page".  And choose yes.  This will keep users from seeing the "Do you grant consent to this application" when they attempt to use the Email system
+[[File:Screenshot 2022-12-09 at 10.15.44 AM.png|400px]]
+==Prime 16 Setup==
+Within Prime 16, go to Administration-->Administration Menu.  Select "Office 365 (O365) Email Setup" from the Administration system options.  You can also type "365" in the search box to find it quickly.  Enter the values as follow:
+{| class="wikitable"
+|+ Office 365 Settings
+|-
+! Item !! Entry
+|-
+| OnlyOneRowAllowed || True
+|-
+| Redirect URI || <nowiki><your url to the basic webite>/O365/O365Login.aspx</nowiki>. So, for example, that might be:  <nowiki>https://demo.kempscaseworks.com/prime16/o365/o365login.aspx</nowiki>
+|-
+| the Client ID || <copy value for Application (client) ID from the App registration you created above as shown [[:File:Screenshot 2022-12-09 at 1.17.45 PM.png]]here>
+|-
+| client Secret || <Enter a random string, for example: jo2i3jutr98uyxcvoijkn2>
+|-
+| scope || <nowiki>https://outlook.office.com/IMAP.AccessAsUser.All%20offline_access%20email%20openid</nowiki>
+|-
+| auth Uri || <copy value the App registration, click on Endpoints and enter the value from "OAuth 2.0 authorization endpoing (v2)".  That should look like this:
+<nowiki>https://login.microsoftonline.com/<your directory tenant id>/oauth2/v2.0/authorize</nowiki>
+>
+|-
+| token Uri || <copy value the App registration, click on Endpoints and enter the value from "OAuth 2.0 token endpoing (v2)".  That should look like this:
+<nowiki>https://login.microsoftonline.com/<your directory tenant id>/oauth2/v2.0/token</nowiki>
+|}
+Close this form to save the entries.
+==Staff Member Setup==
+Open the Staff Member Input Form Administration-->Administration Menu.  Search "Staff" to quickly find the "Staff - Search/Edit" option and select it.  Find and open a staff person's entry.
+In the "Email Setup" tab, ensure the following entries:
+{| class="wikitable"
+|+ Staff Email Settings Setup
+|-
+! Item !! Entry !! Notes
+|-
+| Email Name (shown in outgoing email) || User Name || If the user will be given permission to send and read mail from a shared mailbox in the organization system AND they want only to use that email from within Prime, you may enter the Name for that shared email box here and leave the "Send As Email Name" entry below blank.
+|-
+| Account type || IMAP ||
+|-
+| Incoming mail server || outlook.office365.com ||
+|-
+| Incoming port || 993 ||
+|-
+| Incoming security || SSL ||
+|-
+| Outgoing mail server || smtp.office365.com ||
+|-
+| Outgoing port || 587 ||
+|-
+| Outgoing security || TLS ||
+|-
+| Email server username || user.name@organization.org ||
+|-
+| Email server password || <enter some random string, for example:  asd908ju2> || Any random string will be fine when using the Office 365 Email system with Azure Active Directory / Entra ID.
+|-
+| User Office 365 System || Check the box ||
+|-
+| Send As Email Address || IntakeGroup@organization.org || If the user will be given permission to send and read mail from a shared mailbox in the organization system, you can enter the email address for that shared mailbox here to give the user the ability to select to send from or to read email in that account.
+|-
+| Send As Email Name || Intake Group Mailbox || This is the name that will be included on outgoing email from the shared mailbox.
+|}
+==Staff Member Use==
+===Send An Email===
+Open a client record.  In the Context Menu, choose "Send Email".
+The client's email address should be shown in the "Send To" box.
+Choose the appropriate "Send As" email.  There may be more than one to choose from.
+Edit the Subject and body of the email.
+If you wish to send documents from the Document Tracking system, click the button.  Or to choose a local file (on your workstation), click the "Choose File" button.
+Choose whether to add a case note by selecting the checkbox.
+When ready, to send the email, click the "Send email" button.
+===Pull an Email into a Client Record===
+To pull an email into the Case from your email system, open the client record.  In the Context Menu, choose "Get Email".
+Choose the appropriate email box from the dropdown and click the "Refresh Email List".
+From the resulting list of emails in the Inbox, click "Copy Email to Case" to copy that particular email to the case.  If there are attachments that the system sees as attachments, they will be saved to the case's document tracking system.
+Always ensure the email and attachments are saved properly in the case before deleting the email.
+===View Associated Email===
+To view email that has been associated with a case, open the client record.  In the Context Menu, choose "Associated Email".
+This will show both incoming and outgoing email associated with the case.