Email activator

Configure Revolution to monitor IMAP or Microsoft Exchange mailboxes and create filtering rules to set up email-based triggers. This allows you to trigger notifications based on specific incoming emails received by each individual inbox.

Important: Any email address you specify should be specific to using with this activator and should never be a personal email account. This is because administrators of the Revolution server will have access to the credentials for this email address, which would be a privacy and security violation.

  1. Configuring the mailboxes to monitor:
  2. Creating email trigger conditions
  3. Creating email-based notifications
  1. Go to Configuration > Email
  2. Select New > New IMAP Server Settings
    1. For Name, enter a name for the trigger to make it easily recognizable.

    2. For Available in All Sites:

      • Enable to ensure all your site locations have access.
      • Disable and select a Site to limit which site has access.

    3. For Authentication Type, select either Basic Auth or OAuth, depending on how you need to connect to the IMAP server. OAuth requires a token to connect to your IMAP server

      • Basic Auth flow:

        1. Enter the IMAP server Hostname and Port.

        2. For Username and Password, enter the credentials for the mailbox you want to monitor.

          Create multiple configurations to monitor multiple accounts.

        3. (Optional) Enable Use TLS.

          Note: In most cases you will want to select the Transport Layer Security cryptographic protocol.

      • OAuth flow:

        1. Enter the Hostname and Port of the IMAP server.

        2. For Username, enter the credentials for the mailbox you want to monitor

          Note: The Username must match the account used to create the Token.

        3. For Token, you can select a previously created OAuth or O365 token, or select Create New to create one with the following configurations:

          Tip: Clear your browser cache before creating the token to ensure an account from someone else is not cached and the token attempts uses that information instead.

          • Creating an O365 type Token:

            1. For Name, enter a name for the Token to make it easily recognizable.

            2. For Available in All Sites:

              • Enable to ensure all your site locations have access.
              • Disable and select a Site to limit which site has access.

            3. For Token Type, select O365.

            4. For Grant Type, select Authorization Code.

            5. For Custom Parameters, select Add and enter :

              scope = https://outlook.office.com/IMAP.AccessAsUser.All offline_access

            6. Select Authorize and follow any onscreen prompts.

            7. Select Save.

          • Creating an OAuth type Token:

            Important: This section assumes you have experience with OAuth authentication and any requirements from the service you are connecting to. Refer to the OAuth 2.0 site for information about this protocol.
            1. For Name, enter a name for the Token to make it easily recognizable.

            2. For Available in All Sites:

              • Enable to ensure all your site locations have access.
              • Disable and select a Site to limit which site has access.

            3. For Token Type, select OAuth.

            4. For Grant Type, select Authorization Code.

            5. For Client ID and Client Secret, enter the credential information for the service.

            6. For Authorize URI, enter the URI supplied by your service.

            7. For Access Token URI, enter the token URI supplied by your service.

            8. For Custom Parameters, select Add and enter parameters as required by your system.

            9. Select Authorize and follow any onscreen prompts.

            10. Select Save.

These instructions are specific to setting up monitoring of a Microsoft Office 365 mailbox using IMAP

Monitoring with an O365 Token

  1. Create the Token with the following settings:

    Tip: Clear your browser cache before creating the token to ensure an account from someone else is not cached and the token attempts uses that information instead.

    • Token Type: O365

    • Grant Type: Authorization Code

    • Custom Parameters: scope = https://outlook.office.com/IMAP.AccessAsUser.All offline_access

  2. Create the IMAP Server with the following settings:

    • Authentication Type: OAuth

    • Hostname: outlook.office365.com

    • Port: 993

    • Username: the monitored email account. It must match the email used to create the O365 Token

    • Token: Reference the Token you created.

Monitoring with an OAuth Token

Note: This procedure assumes you have familiarity with OAuth and Active Directory. Refer to the OAuth 2.0 site for information about this protocol.

  1. Create an Application Registration in Azure Active Directory

    1. The registration will create client ID and client secret keys you will reference in the setup

    2. Add at least the following API permissions and set their types

      • offline_access - Delegated

      • IMAP.AccessAsUser.All - Delegated

  2. Create the Token with the following settings:

    Tip: Clear your browser cache before creating the token to ensure an account from someone else is not cached and the token attempts uses that information instead.

    • Token Type: OAuth

    • Grant Type: Authorization Code

    • Client ID and Client Secret: The information generated with your Application Registration.

    • Authorize URI: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

    • Access Token URI: https://login.microsoftonline.com/common/oauth2/v2.0/token

    • Custom Parameters: scope = https://outlook.office.com/IMAP.AccessAsUser.All offline_access

  3. Create the IMAP Server with the following settings:

    • Authentication Type: OAuth

    • Hostname: outlook.office365.com

    • Port: 993

    • Username: the monitored email account. It must match the email used to create the O365 Token

    • Token: Reference the Token you createad.

  1. Go to Configuration > Email
  2. Select New > New Exchange Server Settings
    1. For Name enter a name for the trigger to make it easily recognizable.

    2. For Available in All Sites:

      • Enable to ensure all your site locations have access.
      • Disable and select a Site to limit which site has access.

    3. For Authentication Type, select either Basic Auth or OAuth, depending on how you need to connect to the Exchange server. OAuth requires a token to connect to your Exchange server.

    4. For URL, enter the server Exchange Web Services (EWS) address.

      You can determine this URL as follows:

      1. Ctrl+Right-Click on your Microsoft Outlook icon in the Notifications group of your Windows task bar (not the task bar icon itself).
      2. Select Test Email AutoConfiguration
      3. In the Test Email AutoConfiguration window select Test
      4. In the Results tab find the URL associated with Availability Service

    5. (Only applies for the Basic Auth Authentication Type) For Username and Password, enter the credentials for an account that has impersonation enabled and an Active Directory Domain for your email provider account.

      The email provider account must have impersonation enabled. The Microsoft Exchange Impersonation feature allows service applications, like Revolution, to access multiple mailboxes and also access the from, to, subject, and body fields of the email to include in the notification message template.

      See the external site Impersonation and EWS in Exchange for more information.

    6. Enter email addresses to define Monitored Mailboxes. Select the add <address> button below the entry box to save the value.

      You can specify multiple mailboxes to monitor from the same server domain.

    7. (Only applies for the OAuth Authentication Type) For Token, select an existing Token (of type OAuth or O365) or create a new one (select Create New from the drop-down). Configuration > Integrations > Token.

      Tip: Clear your browser cache before creating the token to ensure an account from someone else is not cached and the token attempts uses that information instead.

These instructions are specific to setting up monitoring of a Microsoft Office 365 mailbox using EWS.

Monitoring with an O365 Token

  1. Create the Token with the following settings:

    Tip: Clear your browser cache before creating the token to ensure an account from someone else is not cached and the token attempts uses that information instead.

    • Token Type: O365

    • Grant Type: Authorization Code

    • Custom Parameters: scope = https://outlook.office365.com/EWS.AccessAsUser.All offline_access

  2. Create the EWS Server with the following settings:

    • Authentication Type: OAuth

    • URL: https://outlook.office365.com/EWS/Exchange.asmx

    • Monitored Mailboxes: the monitored email account. It must match the email used to create the O365 Token

    • Token: Reference the Token you created.

Monitoring with an OAuth Token

Note: This procedure assumes you have familiarity with OAuth and Active Directory. Refer to the OAuth 2.0 site for information about this protocol.

  1. Create an Application Registration in Azure Active Directory

    1. The registration will create client ID and client secret keys you will reference in the setup

    2. Add at least the following API permissions and set their types

      • offline_access - Delegated

      • EWS.AccessAsUser.All - Delegated

  2. Create the Token with the following settings:

    Tip: Clear your browser cache before creating the token to ensure an account from someone else is not cached and the token attempts uses that information instead.

    • Token Type: OAuth

    • Grant Type: Authorization Code

    • Client ID and Client Secret: The information generated with your Application Registration.

    • Authorize URI: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

    • Access Token URI: https://login.microsoftonline.com/common/oauth2/v2.0/token

    • Custom Parameters: scope = https://outlook.office365.com/EWS.AccessAsUser.All offline_access

  3. Create the IMAP Server with the following settings:

    • Authentication Type: OAuth

    • URL: https://outlook.office365.com/EWS/Exchange.asmx

    • Monitored Mailboxes: the monitored email account. It must match the email used to create the O365 Token

    • Token: Reference the Token you createad.

  1. Go to Configuration > Email
  2. Select New > New Email Trigger Condition
    1. For Name enter a name for the condition to make it easily recognizable.

    2. For Available in All Sites:

      • Enable to ensure all your site locations have access.
      • Disable and select a Site to limit which site has access.
    3. Create any number of Match Conditions for the trigger.
      1. Select the email Field to match, which can be: To, From, Subject, or Body.
      2. Select the MatchType to perform, which includes:
        • Contains – The Field should contain the Pattern.

        • ExactMatch – The Field should completely match the Pattern.

          Note: In some cases, for the To and From fields, the value may be in a more complex form, such as:

          FirstName LastName <name@company.com>

          which means it may be best to use a Contains match for these fields if you only want to search by the email address.

        • Regex – The field should match what is searched for through the regular expression.

          This form of regex allows for named variables, which you can use in the body field template. The syntax is: (?<string>pattern). Where string is the name you will reference, and pattern is a valid regular expression pattern. The parentheses ( () ), question mark (?), and angle brackets ( <> ) are all required. For example:

          (?<phone>\d{3}-\d{3}-\d{4})

          See the external site Named Capturing Groups for more information. You can interactively experiment with regular expressions at the external site RegExr. Note that you should set the RegEx engine to PCRE for named variable support.

      3. Define the condition Pattern to match against the contents of the email Field.

        Note: The Pattern is case-sensitive

    4. (Optional) Create a Template, which can be used in the Body field (Message Details) of a Notification with the {ActivatorBody} variable.

      Your template can include a set of variables by selecting them from the Add text variables drop-down menu, which include the values: To, From, Subject, and Body.

      If you used the Regex MatchType, and created a named variable, you will see this value in the Add text variables drop-down menu. Using the named variable example from above, you would see an additional entry: "phone".

  1. Go to Notifications > Manage
  2. Select New Notification.
  3. Create a notification, where the following entries are specific to the email activator:
    • For Select Triggers, set Activator to Email and select the trigger condition(s) you created.
    • For Message Details, use the {ActivatorBody} variable for Body. This will use the Template you created in your trigger condition.