Mail Handler Actions

Actions editor

In the actions editor conditions (IF, ELSE IF, ELSE) and actions (like Create issue, Add comment, Execute transition, Autoreply, etc...) can be added. Conditions and actions can be added under each other and are executed in that order they appear in the list on the left side. 

Whenever you click on a condition or an action, its details will appear on the right side. Any modification to the properties of the action or a condition will appear immediately on the left side.

Actions added below a condition are executed if the given IF or ELSE condition is evaluated to true. There are some special actions, like Set field value that can be added under other actions like Create issue or Execute transition actions. In such cases, these child actions will be executed together with the parent action in a single step. For example, when a new issue is created, fields can be initialized as well, like a single transaction, avoiding to generate a few notification emails about issue updated in that case these actions were executed separately, each in a single step.

To add an action under a condition or another action, hover the mouse and use the plus ( + ) sign on the right to open the pop-up menu:

To add an action or condition at the top level, use the plus ( + ) sign at the bottom of left side list:

This way complex rule and action definitions can be created.

The following is a very simple mail handler:
It checks if issue is not found (by issue keys found in the email's subject) and creates a new Bug issue in SP project. The issue's summary will be the email's subject and the description will contain the email's body.
Else, if the issue was found, then a comment will be added to the existing issue and the comment's content will be the email's body.

Add to Request Participants

This action adds the selected recipients to the Request Participants of the request.

If the customer does not exists, it creates a customer with the email address and adds them as customer to the project, before adding them to the Request Participants. If the customer already exists, but not a customer on the Service Management project, it adds them to the project as customers, then adds them to the Request Participants.

Please note that it does not add the newly created customers as executing user as Mail Handler Actions#Create customer does. To achieve this, first add a "Create customer" action and then an "Add to Request Participants" action with the "To" selected.

Create issue

Use this action to create a new issue in a core/software project or request in a service management. Set at least the Project and Issue/request type.

Split regexp can be used keep only the first part of the body before a pattern that is specified in the regexp. Note that multiple regular expressions can be defined (each on a new line) and they must begin and end with a / sign, like: /Re:/

At Attachment handling you can configure when you want to add the attachments to the issue. There are 4 options you can select from:

  • Never add
  • Skip if attachment with the same name exists
  • Skip if attachment with the same name and size exists
  • Always add

Update issue

This action can be used to update (set field values) an existing issue. Currently it has no parameters, by default it does nothing, add Set field value actions under this action to update multiple fields in a single step.

Suppress Jira's built-in notifications: By default Jira sends a notification about every issue updates. This notification can be suppressed by enabling this option. Please note that to use this option, administer Jira or administer Project permissions are required.

If you try to update an issue with supress Jira's built-in notification without the required permissions, you get an exception saying "To discard the user notification either admin or project admin permissions are required". If you see this error message in the incoming log, either disable the suppress feature, grant permission to the user or use fallback to a default reporter who has the required permission.

Limitations:

  • Due to Jira permission handling a customer cannot update a request even if the reporter is the customer itself. As a solution for this we are planning a feature to select a user for executing Mail Handler: 

Set field value

This action sets the value for a specified field.

For all actions you have to select a field, a content and an update mode (append or overwrite). Once the content is selected, further content-specific configuration can be done. The configuration part for the content changes dynamically based on the selection.

Currently supported custom field types are

  • Priority
  • Reporter
  • single and multi user picker custom fields
  • text based custom fields

And currently supported sources are:

  • email participants: You can select which participant you want to use as a value. Participants can be either of the following: To, From, Cc, Bcc
  • email body/subject: Source is either the subject or the body of the email. You can define a regex and refer to the group which contains the value to set. Group 0 means the whole text.

Add comment

Split regexp can be used keep only the first part of the body before a pattern that is specified in the regexp. Note that multiple regular expressions can be defined (each on a new line) and they must begin and end with a / sign, like: /Re:/

Visibility allows you to restrict the comment added by the mail handler. The Values are grouped into 3 groups:

  • Service Management allows you to make the comment private
  • Project Roles allows you to restrict comment visibility on Project Roles
  • Groups allows you to restrict comment visibility on Groups

If you don't want to put any restriction on the comment, just set it to 'All users'.

Add comment action has the same Attachment handling strategies as the Mail Handler Actions#Create issue action has.

Send auto reply emails

Use this action to send auto replies. The same templates can be used that are listed under Outgoing Mails/Templates

Execute workflow transitions

This action can execute transition on the issue. Set the Destination status into which the issue should be moved.

If there are multiple transitions to this destination status, then the preferred one can be choosen in the Use transition field by setting the id or the name of the transition. When name is specified, then a regexp can be used as well. Note that only one regexp is allowed.

By the default, the first found transition is used to move the issue to required destination status

Create customer

This action creates a Service Management Customer with the sender's email address if not existing yet and sets it as executing user. If it already exists, then it will be logged and no customer will be created.

You have to provide a Service Management project which you want to assign the customer.

Split regexp

During processing before splitting the mail body by regexp, the whole body is converted to Jira wiki format and regexp is applied on the converted value.

This means that in case of html emails, regexps must be written for wiki format.

Conversion rules:

html formatwiki format
<hr />
----