Incoming Email Integration with OAuth 2.0

 
Author
Message
SysAid Technical Writer
1124
 

Settings

Integration

Email

Email Integration Form

To view all of your email integrations or to create a new email integration, see the Email Integration list.

Set up email integration

To set up email integration

  1. In the General tab enter an name for your integration. This is the name that will appears in the email address list whenever you send an email.
  2. (Optional) Enter any description you'd like regarding this email profile.
  3. (Optional) Select if you want to set this email profile as your default email integration. You can use the default email account to send automatic notifications.
  4. Click Apply.

 

Outgoing emails in SysAid

By configuring outgoing email integration in SysAid, you gain several important benefits:

  • All emails sent from service records are saved as correspondence in the email message log, allowing you to review them later
  • Service records can send automatic notifications to administrators and end users, both on the creation of a new service record, and when details within the service record are changed (either by an end user or by another administrator)
  • You can enable email notifications for monitoring, software licenses, and reminders, allowing you to receive an instant update if there are any problems affecting your service desk
  • Receive critical email updates about escalated service records

 

SysAid Basic Edition gives you one outgoing email address, and SysAid Full Edition allows you to create as many as you like. Multiple outgoing email addresses can be useful if you have multiple departments that use SysAid, for example helpdesk@yourcompany.com and maintenance@yourcompany.com.

 

To configure SysAid email integration, fill out the relevant fields using the table below and then click Save.

 

Outgoing email settings

 


Item

Description

Enable outgoing email

Select this checkbox to enable outgoing email integration for this profile.

Email address This is the email address you are integrating with.

SMTP host name

This is the name of the computer that has the SMTP sever.

SMTP port

The default is 25, but you can change this if port 25 is blocked for any reason.

Encryption

You can allow SysAid to send emails using either SSL or TLS encryption if your SMTP server supports them.

SMTP user (optional for authentication)

If your SMTP server requires authentication, please enter a valid username here.

SMTP password (optional for authentication)

Your user password is only needed if your SMTP requires authentication.

Encoding

The international standard is utf-8. You should not need to change this.

Content type

Allows you to choose text format for outgoing emails (e.g. plain text, html).

Charset Allows you to choose the character set for outgoing emails. The international standard is utf-8. You should not need to change this.

Test outgoing email

Click Test to check that this email address is valid for sending emails from SysAid.

 

Incoming emails in SysAid

Incoming email integration in SysAid allows you to:

  • Automatically create service records from incoming emails, even if the emails are sent by users not registered in SysAid. You can use email rules to automatically route the service record to an administrator or administrator group and assign a status, category, urgency, impact, priority, and more based on the email's content, sender, and incoming address.

    Note: SysAid removes all emojis from emails before creating a tickets based on those emails.
  • Automatically log all end user responses within a service record*, ensuring that all communication relevant to a service record is saved in one place.
  • Automatically update the status of a service record when an end user responds, thereby notifying the administrator that he or she needs to review the service record again.

To display the original email in its SR, use the SR Source Email field.

 

SysAid Basic Edition gives you two incoming email addresses, and SysAid Full Edition allows you to create as many as you like.

 

Note: SysAid does not send emails to integrated email addresses. Any attempts to send an automatic or manual message to an integrated email address will be unsuccessful.

 

*End-user replies added to existing service records

  1. When an administrator sends an email from within a service record, or when SysAid sends the end user an automatic email regarding a service record, the email subject line contains the service record number in the format #XXX (e.g. Regarding Service Record #124).
  2. When SysAid incoming email integration receives an email, it scans the subject line. If a service record number is found (e.g. #XXX), SysAid checks to see if a service record with that ID exists. If it does, SysAid adds the email to the message log for that service record and updates the SR's status.
  3. Therefore, if end users respond to emails sent from SysAid (without removing the SR# from the subject line), their responses go back into SysAid and are added to the message log of the appropriate service record.

 

Set up email integration

 

Incoming email settings



Item

Description

Enable incoming email

Check this option to enable incoming email integration. Emails received by SysAid will either open new service records or be added to existing ones. SysAid integrates with any email box that supports POP3, IMAP, OWA, or MAPI. 

Important: All emails sent to the incoming email address are removed from the mail server after being imported into SysAid. As a result, this address cannot be used for any other purpose. Create a dedicated email address to use specifically for email integration.

Protocol

Allows you to choose your preferred protocol for integration with your mail server -- POP3, IMAP, MAPI, EWS (Microsoft Exchange or Office 365), or OWA (Outlook Web App). Note that OWA integration works with MS Exchange 2007 and 2010 only.

Note: Currently, SysAid does not directly support MAPI in Microsoft Exchange 2013 or highter. This is due to Microsoft's decision to change the MAPI protocol from RPC to HTTP. For more information on using MAPI with Microsoft Exchange see here.

 

Server address/URL

The name of your mail server for incoming email.

 

If you are using the OWA or EWS protocol, be sure to enter the server URL for the mail server without any suffixes. For example, enter https://serverURL not https://serverURL/owa.

Encryption

You can allow SysAid to receive emails using either SSL, TLS, or TLS 1.2 encryption if your incoming mail server supports them. Only visible in POP3 or IMAP protocols.

User/Domain user

The username for the email address you're using for incoming email integration.

Password The password for the username.
Update SR based on last SR # in email subject By default SysAid connects incoming emails with the first SR # in their subject. When this is selected, SysAid updates the last SR in the subject, if you check the new checkbox in the email integration form.

Search service record number in email body

When this option is selected, SysAid also searches the body of incoming emails for numbers of already existing SRs.

Change status to

SysAid routes the email replies on existing service records to the end user and any assigned admins, and changes the status of the service record to the status you specify here. You could, for example, use the status "User Responded" for this purpose.

 

Important: This feature interferes with the Route Email Correspondence With End User Through SysAid Server feature, configurable within Advanced Backward Compatibility settings, as any reply (from an end-user or administrator) changes the SR's status. Currently, the two features are not meant to be used simultaneously. If you are using the Route Email Correspondence feature, we recommend setingt this value as "Do not change".

 

Unless SR status is

When a user replies to a service record that currently has a status listed here SysAid does not change the status based on the above field. Example: If you have the "Closed" status listed here then if a user replies to a service record with a status of "Closed" status does not change. This is useful to avoid service records being reopened by the users after they have been closed.

Ignore emails with subject match to (regular expression) Emails containing (insert regular expression) in their subject line will be ignored. This helps you to protect your email account from spam. Separate expressions using the pipe character: | . Example: (Undelivered Mail Returned|SPAM|Out of office)
Create new service records from emails containing the same subject & body only from the following senders

SysAid stores the last 1,000 emails in memory. If any new email matches one of those old emails exactly in all three of the sender, subject, and body fields, then it will not create a new service record. This is to prevent duplicate requests for emails sent multiple times. However, in some cases, the same email might intentionally be sent multiple times, such as a printer reporting low ink. Therefore, if this box is checked, emails sent from any email addresses or SysAid usernames entered into this field will always create new service records, even if the emails look like duplicates.

Forward ignored emails to

Insert the username(s) of the individual(s) who should receive the ignored emails.

Important: Do not insert a user with an email address that appears in your list of incoming email addresses. Make sure to use a user with a real email address.

Send a copy of the incoming emails to
(for Enterprise editions only)

After SysAid has imported an email into SysAid using email integration, you can choose to have a copy of that email sent to an email address of your choice.

Important: Do not insert a user with an email address that appears in your list of incoming email addresses. Make sure to use a user with a real email address.

Test incoming email

Click Test to check that this email address is valid for receiving emails to SysAid.

 

Setting up incoming email integration with OAuth 2

You can set up email integration with the OAuth 2.0 protocol. Currently this is only supported by incoming SysAid email integration.




To set up incoming email integration with the OAuth 2.0 protocol

  1. Select the Enable incoming email check box.
  2. From the Protool drop-down, select OAuth 2.0.
  3. Select the service provider you want to use. Currently, OAuth 2.0 email integration only supports Microsoft 365
  4. Register your application in Azure:
    1. In your Microsoft 365 account, navigate to Azure Active Directory > App registrations.
    2. Click New registration.
    3. Enter a name for your application.
    4. In the supported account types, select the single tenant option.
    5. (optional) select a platform configuration.
    6. Click Register.
  5. Create a client secret:
    1. In App registrations, navigate to Certificates & secrets.
    2. Click New Client secret.
    3. Enter a description.
    4. In the Expires area, select Never.
    5. Click Add.
    6. Copy the generated secret from the Value column.
    7. Back in the SysAid email integration form, paste the secret in the Client secret field.
  6. Setup API permission:
    1. Back in Azure, navigate to API permissions and click Add a permission.
    2. Choose Microsoft Graph.
    3. Click Delegated Permissions.
    4. Check the User.Read permission.

    5. Click Add Permissions.
    6. Click Application Permissions.
    7. Check the following permission.
      - Calendars.ReadWrite
      - Mail.ReadWrite
      - Mail.Send
      - User.Read.All

    8. Click Application Permissions.
    9. Click Grant admin consent for <domain name>.
    10. Click Yes to confirm.
  7. Copy the Tenant ID and Client ID:
    1. In Azure Active Directory, navigate to App registrations and select the app you just set up.
    2. Copy the Application (client) ID and paste it into the Client id field in the SysAid email integration form.
    3. Copy the Directory (tenant) ID and paste it into the Tenant id field in the SysAid email integration form.


  8. Follow the instructions above for setting incoming email integration. Be sure that the Microsoft 365 inbox that you add is dedicated specifically for incoming email integration with SysAid.

 

 

 

 

 

SysAider
1
 
Hi EisenmanAvi,

Thanks for your instructions to setup OAuth 2.0 in SysAid.

As indicated on the Microsoft documentation (https://techcommunity.microsoft.com/t5/exchange-team-blog/improving-security-together/ba-p/805892), OAuth 2.0 will be mandatory as of 13/10/2020.

In your steps described above are granting SysAid access to all mailboxes of the organization (read/write access on emails and calendars), which is something that probably most organizations won't be happy of doing.

Could you please include the steps required to limit the scope, so SysAid can have access only to certain mailboxes?
More info on: https://docs.microsoft.com/en-us/graph/auth-limit-mailbox-access

Thanks,
José
SysAid Technical Writer
1124
 
Hi Jose,

I just opened up a feature request for this. I will let you know if/when I hear any updates on this.

Thanks and have a great day,
Avi
SysAider
1
 
HI Avi,

Just a FYI that I had brought this same issue to the attention of SysAid back in August 2020. A ticket was created and closed a week later. I was told that there was nothing that could be done about the mailbox access and that we should look for a workaround. We are hoping to be able to find a workaround or we will be forced to discontinue the use of SysAid.

Please keep me in the loop of any updates.

Thanks,

Scott
SysAider
1
 
Hi,

Is there an update on this issue? My organization is also concerned with that permission set required by SysAid.

Thanks,
Ilia
EJL
SysAider
1
 
Also concerned about access to all mailboxes. Due to the end of basic authentication and EWS by Microsoft in October 2022, OAuth 2.0 appears to be the only solution for the email integration with SysAid. It's a little disappointing that we will need to trade one security problem for another.

This message was edited 1 time. Last update was at Oct. 12, 2021 09:17 PM