Email Listener Activity

V10.4

Overview

Use the Email Listener activity to listen to an email inbox and start a dynamic workflow when a new email arrives to the inbox. You can then use the returned email object in other workflow stages.

IMPORTANT
The JES executes this activity. So, you must grant permissions to the workflow and activity to the user that runs the JES service.

If you copy a workflow that contains an Email Listener activity, the new workflow has an Email Listener activity with same associated job definition. So now, two Email Listener activities will use the same job definition, which is not supported in Cora SeQuence.

In the new workflow, delete the existing Email Listener activity from the copied workflow, and create and configure a new activity with a new job definition. 

Use case

At a customer service center, start a service request workflow for the relevant team when an email is received from a specific customer.

Configure an Email Listener activity in a workflow

Add an Email Listener activity in your workflow, and double click to configure. On the Job Definition window, the settings on the Job and the Advanced options tab are similar to any other job activity, and doesn't need any changes. Configure the Command tab to listen to a mailbox.

Job tab

• Name: Name of the activity.
• Job Instance: Select from the list of servers on which the JES (Job Execution Service) is installed.
• Job is enabled: Select to enable the job. We recommend that you enable the job only after you completely develop the workflow, or workflow execution testing has started.

Command tab

• Protocol:
  • EWS
  • Graph API (most recommended)
  • IMAP
  • POP3

• Email Server: The email server to connect to. For example, outlook.office365.com.
• SSL: The option based on the email server configuration.
• Port: The default port per the selected SSL Option. Default is 80, but it can be overwritten.
• Mailbox and credentials: The mailbox that needs to be listened to, and the credentials to connect to the mailbox.
• Target email: The SMTP email address.
• Action: The action to be performed on the emails received, move to a specific folder or delete.
• Move autoreply message to this folder without creating an instance: Select to move the autoreply emails to a folder and avoid creation of a new case instance.
• Source folder: The folder from where the messages will be processed.
• Target folder: The folder where all processed messages will be stored, in case 'Move to folder' action is selected. This field is disabled for 'Delete' action.
• Include message attachments and linked resources: Select to save email attachments and linked resources in the database.
• Save message content as attachment: Select to save message content as .eml file attachment for Graph API, and .msg file attachment for other protocols.

Advanced options tab

• Job execution schedule: Sets a schedule for job run.
• Delay job start: Delays the job start.
• Stop job if it executes more than: Stops the job after set time.

Watch this video to learn how to set up the Email Listener activity to listen to an inbox and start a workflow when a new email arrives.

Limitation

• In case of the high volume of requests across all applications, the Graph API protocol for Email Listener encounters throttling and limits any more requests from the client for a specific time period. In such a scenario, the system displays an error status code 429, and the requests fail. Wait for the recommended Retry-After delay, and try the request again.
• For V9.6 and earlier, the Graph API protocol for Email Listener doesn't save the .msg attachments to the system.
  From V9.6.1 onwards these attachments are saved to the system as .eml files.

Best practice

As a best practice to enhance the JES performance, either split the job to two or more inboxes, or don't predefine host for the job, so that it is sent to the least busy JES. By doing this, you can reduce the number of operations per request or reduce the frequency of requests.

Want to learn by doing?  Check out this hands-on exercise. Note that only internal users can access the link.

V8.8.5, V9.3.1 and later

Overview

Use the Email Listener Activity to listen to an email inbox and start a dynamic workflow when a new email arrives to the inbox. You can then use the returned email object in other workflow stages.

IMPORTANT: The JES executes this activity. So, you must grant permissions to the workflow and activity to the user that runs the JES service.

If you copy a workflow that contains an Email Listener Activity, the new workflow has an Email Listener Activity with same associated job definition. So now, two Email Listener Activities will use the same job definition, which is not supported in Cora SeQuence.

In the new workflow, delete the existing Email Listener Activity from the copied workflow, and create and configure a new activity with a new job definition. 

Use case

At a customer service center, start a service request workflow for the relevant team when an email is received from a specific customer.

Configure email listener activity in workflow

Add an email listener activity in your workflow, and double click to configure. On the Job Definition window, the settings on the Job and the Advanced options tab are similar to any other job activity, and doesn't need any changes. Configure the Command tab to listen to a mailbox.

On the Job tab:

• Name: name of the activity.
• Job Instance: the list includes each server on which the JES (Job Execution Service) is installed.
• Job is enabled: we recommend that you enable the job only after you completely develop the workflow, or workflow execution testing has started.

On the Command tab:

• Protocol:
  • EWS
  • Graph API (most recommended)
  • IMAP
  • POP3

Based on the selected protocol, different fields from the following appear on the Command tab.

• Email Server: add the email server to connect to, for example outlook.office365.com
• SSL: select the option based on the email server configuration.
• Port: default port set per the selected SSL Option. It can be overwritten.
• Mailbox and credentials: mailbox that needs to be listened to.
• Target email: the SMTP email address.
• Action: the action to be performed on the emails received, move to a specific folder or delete.
• Source folder: the folder from where the messages will be processed.
• Target folder: the folder where processed messages will be stored, in case of 'Move to folder' action selected. Disabled for action selected as 'Delete'.
• Include message attachments and linked resources: Cora SeQuence saves email attachments and linked resources.
• Save message content as attachment: Cora SeQuence saves message as .eml file for Graph API, and .msg file for other protocols.

On the Advanced options tab:

• Job execution schedule: sets a schedule for job run.
• Delay job start: delays the job start.
• Stop job if it executes more than: stops the job after set time.

Watch this video to learn how to set up the Email Listener activity to listen to an inbox and start a workflow when a new email arrives.

Limitation

• In case of the high volume of requests across all applications, the Graph API protocol for Email Listener encounters throttling and limits any more requests from the client for a specific time period. In such a scenario, the system displays an error status code 429, and the requests fail. Wait for the recommended Retry-After delay, and try the request again.
• For V9.6 and earlier, the Graph API protocol for Email Listener doesn't save the .msg attachments to the system.
  From V9.6.1 onwards these attachments are saved to the system as .eml files.

Best practice

As a best practice, consider one of the following:

• Reducing the number of operations per request.
• Reducing the frequency of requests.

This can be achieved by one of the following:

• Splitting the job to two or more inboxes.
• Using several JES with no specific host predefined. Thus hosting the job to least busy JES.

Want to learn by doing?  Check out this hands-on exercise. Note that only internal users can access the link.

V9.3 and earlier (except 8.8.5)

Context

Use the Email Listener Activity to listen to an email inbox and start a dynamic workflow when a new email arrives to the inbox. You can then use the returned email object in other workflow stages.

IMPORTANT: The JES executes this activity. Therefore, you must grant permissions to the workflow and activity to the user that runs the JES service.

Limitation

If you copy a workflow that contains an Email Listener Activity, in the copied workflow, you need to delete and then create a new Email Listener Activity.

This is necessary, because when you copy a workflow that contains an Email Listener Activity, the associated job definition is not copied. This causes two Email Listener Activities to use the same job definition, and this functionality is not supported. The Email Listener Activity in the copied workflow needs to be recreated with a new job definition. To do this, delete the Email Listener Activity from the copied workflow, then create and configure a new Email Listener Activity.

Use cases

• At a customer service center, start a service request workflow for the relevant team when an email is received from a specific customer.

Add and configure email listener activity in workflow

Add an email listener activity in your workflow, and double click the activity to configure. On the Job Definition window, there are three tabs that require configuration: Job, Command, and Advanced options. The settings on Job and Advanced options tab are similar to any other job activity, and doesn't need any changes. The main settings are done on the Command tab.

• On the Job tab:
  • Job Host: the list includes each server on which the JES (Job Execution Service) is installed.
  • Job is enabled: we recommend that you enable the job only after you completely develop the workflow, or workflow execution testing has started.
• On the Command tab:
  • Protocol settings:
    • EWS
    • POP3
    • IMAP
  • Include message attachments and linked resources: saves email attachments and linked resources.
  • Save message content as attachment: saves message as .msg file.

To connect to Microsoft Office 365 with EWS, define the following settings:

• Protocol: EWS
• Email Server: outlook.office365.com
• SSL: Implicit
• Port: default port set per the selected SSL Option. It can be overwritten.
• Mailbox and credentials: mailbox that needs to be listened to.
• Target email: the SMTP email address.
• Source folder: the folder from where the messages will be processed.
• Action: the action to be performed on the emails received, move to a specific folder or delete.
• Target folder: the folder where processed messages will be stored, in case of 'Move to folder' action selected. Disabled for action selected as 'Delete'.
• Include message attachments and linked resources: Cora SeQuence saves email attachments and linked resources.
• Save message content as attachment: Cora SeQuence saves message as .msg file.