System Email Accounts
- 1. Navigation
- 2. Configuring a System Email Account
- 3. OAuth 2.0 EWS Authentication
- 4. OAuth 2.0 Gmail Authentication
- 5. Requirements
- Navigate to the backstage menu by clicking on the ServicePRO icon.
- From the Setup tab, click on the System Email Accounts option as highlighted below.
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.
- 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
- Account Setting – Allows to enter email account information, processing properties and test the connection settings entered.
- Mail Server Type
- Exchange Server (EWS) - Recommended for Microsoft Exchange/Office 365 environments. (Note: To get the EWS URI please see the Configuring Calendar Synchronization Page)
- 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.
- Windows Authentication - uses the account on the HelpSTAR Starwatch Service for authentication to the system email account. No account password is required within ServicePRO but a domain account with appropriate permissions to the mailbox must be specified on the HelpSTAR Starwatch Service.
- Exchange Authentication - uses the credentials specified in the Account Information section to authenticate to the system. A password is required within ServicePRO but the HelpSTAR Starwatch Service can be run under the default "Local System" account.
- Agent Authentication - uses a separate mailbox's name, email address, and password to authenticate to the system email account which can now be specified in the EWS Settings section.
In order to use a Shared Mailbox for system email account, Agent Authentication method should be used, by specifying one of the user mailbox credentials that has access to the shared mailbox, under the Agent Authentication section. Note: The account being used must have the application impersonation role set on itself in the Exchange Admin console so that it can send emails on behalf of another account.
- 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.
- 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.
- 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.
- 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.
- 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.
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.
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 CONFIG files.
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 ():
- 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.
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.
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
<!--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
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.
- 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.
- When any changes are made to an existing System Email Account, Starwatch Service and Rule Service need to be restarted in order for the changes to take effect.
- When any changes are made to the System Text Messaging account, Starwatch Service and Rule Service need to be restarted in order for the changes to take effect.