System Email Accounts

Navigation

1. Navigate to the backstage menu by clicking on the ServicePRO icon.
2. From the Setup tab, click on the System Email Accounts option as highlighted below.
   

   System Email Accounts Navigation

Configuring a System Email Account

ServicePRO System Email Accounts process incoming emails to create new requests or update existing requests, send request updates to users and send business rule notifications.

Configure System Email Accounts Window

• NEW - Create a new System Email Account
• UPDATE - Update an Existing Account
• DELETE - Delete a System Email Account
• Scan for new mail specifies how often the StarWatch process will scan the system email account for new email.
• Issue Alert if unable to process mail A ServicePRO Alert will be issued to all Support Reps currently logged in
• Create Announcement - An announcement will be created notifying that email processing has stopped

System Email Account Configuration Tabs

• Account Setting – Allows to enter email account information, processing properties and test the connection settings entered.
• Mail Server Type
• POP3/SMTP
• Exchange Server (EWS) - Recommended for Microsoft Exchange/Office 365 environments. (Note: To get the EWS URI please see the Configuring Calendar Synchronization Page)
• IMAP/SMTP
• Account Information
• Profile Name: The name of the system email account
• Email Address: The email account being used to send/receive email from
• Account Name: The username used to login to the email account
• Account Password: The password used to login to the email account
• Domain: The Active Directory domain name
• Select the Dispatch folder where new requests will be created.
• Process Emails from Users with the 'Email' option disabled in User Properties - will allow users who have their email marked as disabled to still send/receive email from this system email account
• The End User Reply behavior (non-requester) option decides if other users who have been CC'ed on an email sent from ServicePRO will be able to update the request by replying to that email (Note: A floating license is required to use this feature). There are 3 options:
• Do not allow - means that only the requester will be able to update the request
• Allow CC End Users to update - means that any end user who is part of the CC Recipient list (in the Notification section of the request) will be able to update the request
• Allow any End User to update - means that any end user will be able to update the request
• Find Sender using option allows ServicePRO to find a matching user based on 4 possibilities in case there are some discrepancies (such as a Display Name in ServicePRO not matching with Exchange):
• Email then Display Name
• Display Name then Email
• Email Only
• Display Name Only
• Processing CC'ed User when creating a request specifies the handling of 'CC' user who is not present in ServicePRO, when creating request from email processing. There are three possible ways to configure it:
• Create user and allow email - This is the default option. When this option is selected, the CC user will be created as a user in ServicePRO and enables email. This means that the emails from this user will be processed by StarWatch.
• Create user and don't allow email - When this option is selected, the CC user will be created as a user in ServicePRO and disables email. This means that the emails from this user will not be processed by StarWatch.
• Do not create user - When this option is selected, the CC user will not be created as a user in ServicePRO. (i.e.), If this option has been selected, when a non-ServicePRO user responds via email where they are CC'ed, it will not create a new ServicePRO user.
• Send a copy of all 'Request Failed' messages to allows a user to specify an email address where all Request Failed messages will be sent to (other than the requester). These messages can include: Sender Not Found, Email Update Disabled, Empty Email, Unknown Error, and Invalid Requester.
• Create text log for incoming email and Create text log for outgoing email creates a text log file of all incoming/outgoing email on the application server in the Starwatch log folder (default path: C:\HelpSTAR\HLPSTRCS\Modules\StarWatch\Logs)
• Click the Test Account Settings button (as shown in the image below) to confirm if ServicePRO can successfully connect to the system email account entered.
  

  Account Setting
  
  

• Reply Messages – Create custom reply messages. Reply emails are sent to requesters for all incoming emails. For specific events, such a message failure or logged request confirmation, you can create the text that will appear in emailed responses. The Reply Messages tab features a Rich Text Editor to allow you to customize formatting of emails sent to requesters.
  

  Reply Messages

• Outgoing Request Updates – Configure messages sent to users when their requests are updated. The Outgoing Request Updates tab features a Rich Text Editor to allow you to customize formatting of outgoing request updates to requesters. In addition, you can add Memo Variables to the Greetings tab such as request number or requester name. The Current Memo and Request History notifications will be accompanied by the text placed here.
  

  Outgoing Request Updates
  Options:
• Allow to update a request through email - Allows replies to this email to update the request
• Include Update Message - When a request is updated via email, this option adds text before the latest update that reads: "To update this request via email click on 'Reply' and delete the original text message to avoid duplication."
• Include Original Email - When a request is updated via email, this option sends you the details of the email update
• Send confirmation when a request is updated through email - When a request is updated via email, send an email confirming that the request has been updated (i.e. "Thank you for your update to Request No:")

• Reopening Request – Configure how to handle the reopening of closed requests by email updates. The following options are available:
• Allow to reopen anytime - Request can be reopened anytime and will be moved to the selected folder.
• Allow to reopen within given hours - Request can be reopened within the timeframe provide and will be moved to the selected folder. Option to notify requester that their request did not reopen is available.
• Do not allow to reopen - Request will never be reopened. Option to notify requester that their request did not reopen is available.
• Do not reopen but create a new request - Request will never be reopened but a new request will be created for the same requester.
  
  

  Reopening Request

• Attachments – Set the options for processing attachments. By default, email attachments are ignored. You can specify if attachments should be processed and attached to a service request. In addition, specific file types can be blocked if you do not want ServicePRO to process them.
  

  Attachments

• Block List – Do not process email messages starting with certain text in the subject line (such as “Out of Office”); Email messages with subject lines starting with the defined string will not be processed by ServicePRO to create a new request. Check the box under Send Reply if you want a 'Request Failed' notification to be sent to the sender of the email.
  

  Block List
  Click on the Save button to save your settings. You will be taken back to the Configure System Email Accounts window where your new settings will be added to the Email Accounts list. If multiple accounts are entered, the first account you configure is the "Default" system account. If you want to users to submit email requests to different email addresses, click the Add button to add accounts. This will open another Account Settings window.

• Ignore List - Process email messages but ignore this particular text from the subject line. This might be useful in cases where a string of text is automatically added to all external emails that are coming into the organization. This allows the email to update the existing request by making sure the email subject line remains the same.
  

  Ignore List

OAuth 2.0 EWS Authentication

When "Exchange Server (EWS)" server type is selected in the Account Setting section, a new field "EWS Authentication Kind" shows up. This field has two options to choose from "Basic” and “OAUTH 2.0".

By default, “Basic” EWS Authentication Kind is selected.
When ‘OAuth 2.0’ is selected for EWS Authentication Kind, ServicePRO and StarWatch Service will access the mailbox using the OAuth 2.0 authentication method, by utilizing the App ID, Tenant ID and Client Secret entered in the System Email Account Setup.

OAuth 2.0 EWS Authentication - Prerequisites

In order to enable the OAuth 2.0 EWS Authentication kind, the following the pre-requisites must be met.

Register ServicePRO Application in Azure

To use OAuth, ServicePRO application must have an application ID issued by Microsoft Entra ID [Previously called, Azure Active Directory].
You can register a new application in the Microsoft Entra ID [Previously called, Azure Active Directory] admin center or by login to https://portal.azure.com/

• 1. Open a browser and navigate to the Microsoft Entra ID [Previously called, Azure Active Directory] admin center and login using a personal account (aka: Microsoft Account) or Work or School Account.
• 2. Select Microsoft Entra ID [Previously called, Azure Active Directory] in the left-hand navigation, then select App registrations under Manage.
• 3. Select New registration. On the Register an application page, set the values as follows.
• Set Name to a friendly name for your app.
• Set Supported account types to the choice that makes sense for your scenario.
• For Redirect URI, change the dropdown to Public client (mobile & desktop) and set the value to https://login.microsoftonline.com/common/oauth2/nativeclient.

For more information you may refer to the steps given in "Register your application" section in order to register the application and then setup Application permissions. How to Authenticate EWS Application -Using OAuth

• 4. Choose Register. On the next page, copy the values of the Application (client) ID and Directory (tenant) ID and save them, you will need them later.

• 5. Configure for app-only authentication
• To use application permissions, follow these additional steps.
• Select Manifest in the left-hand navigation under Manage.
• Locate the requiredResourceAccess property in the manifest, and add the following inside the square brackets ([]):
  

  full_access_as_app permission
• Select Save.
• Select API permissions under Manage. Confirm that the full_access_as_app permission is listed.
• Select Grant admin consent for org and accept the consent dialog.
• Select Certificates & Secrets in the left-hand navigation under Manage.
• Select New client secret, enter a short description and select Add.
• Copy the Value of the newly added client secret and save it, you will need it later.
  

  App Registration: API Permissions

For more information you may refer to the steps given in "Configure for app-only authentication" section in order to register the application and then setup Application permissions. How to Authenticate EWS Application -Using OAuth

After completing the application registration in your Microsoft Entra ID [Previously called, Azure Active Directory], please capture the Application ID, Tenant ID and Client Secret values.
Note:-
Reason why 'full_access_as_app' permission setting is needed:
We need permission to fetch emails from all mailboxes that are configured in ServicePRO with the application identity configured in Azure portal. Application cannot use every user's password to access mailbox therefore it requires permission to fetch emails. We are using EWS in order to access emails and based on Microsoft guideline given below, application requires full mailbox access to in order to access emails: https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth

Update ServicePRO configuration files (For Versions 14.2.21.x and below)

Update the following keys in the ServicePRO Server web.config file and in the exe configuration files StarWatch Service, Rule Service and Calendar Sync Service using the Application ID, Tenant ID and Client Secret that were captured after completing Step above.

<!--The application ID from your app registration -->
<add key="starwatchewsscope" value="https://outlook.office.com/.default" />
<add key="starwatchappId" value="#####" />
<!--If you registered your app to support only users in your organization, change the value of this key to your tenant ID -->
<add key="starwatchtenantId" value="######"/>
<!--The application's client secret from your app registration. Needed for application permission access -->
<add key="starwatchclientsecret" value="#########"/>

Default locations for each configuration file (Drive may defer depending on installation):
ServicePRO Server: C:\HelpSTAR\HSSITES\HSSupportNET\service\web.config
ServicePRO Web: C:\HelpSTAR\HSSITES\ServicePRO.Cloud9\web.config
Starwatch Service: C:\HelpSTAR\HLPSTRCS\Modules\Starwatch\StarWatchService.exe.config
Rule Service: C:\HelpSTAR\HLPSTRCS\Modules\RuleService\RuleService.exe.config
Calendar Sync: C:\HelpSTAR\HLPSTRCS\Modules\CalendarSync\HelpSTAR.CalendarIntergationService.exe.config

Update OAUTH 2.0 Settings (For Versions 14.2.22.x and above)

When Authentication Kind is selected as “OAUTH2.0”, the ServicePRO Administrator can input the settings required for OAuth 2.0 authentication, like EWS Scope, EWS Application Id, EWS Tenant Id and EWS Client Secret key from the User Interface itself. They don’t need to add these key values in the Configuration files on the server.
In the System Email Account Setup When OAuth 2.0 is selected for Authentication Kind, please make sure to click on the ellipsis button next to the field. Update the keys in the UI for the Application ID, Tenant ID and Client Secret that were captured after completing the above step.
•       If setting up a new System Email Account for the first time, with Exchange Server (EWS) -Authentication Kind as OAUTH 2.0, the user should enter these values in the OAUTH 2.0 Settings dialog directly.
•       For an existing system email account that was set with OAUTH 2.0 authentication, the saved values from the web.config file will be populated into the OAUTH 2.0 settings in the user interface automatically by the system.

OAuth 2.0 Gmail Authentication

When "POP3/SMTP or IMAP/SMTP" server type is selected in the Account Setting section, a new field " Authentication Kind" shows up. This field has two options to choose from "Basic” and “OAUTH 2.0". By default, “Basic” Authentication Kind is selected.
When ‘OAuth 2.0’ is selected for Authentication Kind, please make sure to click on the ellipsis button next to the field and enter the JSON private key that was downloaded for the Gmail Service account (Step 3.8 in the Gmail OAuth 2.0 setup document) in the dialog that opens up. In the Email Address field, please make sure to enter the Service Account email address that was created in step 3.4 in the Gmail OAuth 2.0 setup document. ServicePRO and Starwatch Service will access this mailbox using the OAuth 2.0 authentication.

Requirements

• The system email accounts function with POP3/SMTP, IMAP/SMTP or Exchange Web Services (EWS) compliant email systems.
• A mailbox must exist on the mail server for each system email account you wish to use in ServicePRO.
• The StarWatch service must be running to process incoming and outgoing email.
• ServicePRO will only processes email requests that it can find a matching email address for in the database (unless otherwise configured with an Email Business Rule).
• Ensure that all users submitting email requests have their email enabled and their email address entered correctly.
• System email accounts can be configured to process attachments.