Inbound Email Actions

Inbound email actions are most commonly used to process emails. For example, if an incoming email contains "Incident" in the subject line, the system creates an incident record.

Inbound email actions are similar to business rules in the usage of scripts and conditions that perform actions on the target table. Emails are checked by inbound email actions for defined conditions and some watermarks that associate the email with a task. If the conditions are met, the inbound email action performs the pre-configured activities. There are two type of them:

• Record Action: runs a specified script (create, update, or delete a record in the system).
• Reply Email: when triggered, sends a reply email.
  

Use a script to define how the system will respond to certain triggers – this could be a specific email topic, keywords in its body, or more complex conditions. Unlike Notification Rules, inbound email actions enable the user to interact with the records in the system.

For example, while processing an incident in the Information Needed state, the system inserts the body of this email to the Additional Comment field in the Activity Feed when the caller sends their response. The condition is that the caller's email contains a specific text in its subject, and the task number it includes matches the one in the incident record. That is, the inbound email action defines what happens in the system after receiving an email.

Inbound action chain

Inbound Action includes three major groups of parameters:

• An action to execute when an email is received. It is defined with a script.
• A condition that an email should meet for the action to be executed.
• Parameters that control the processing flow.

The third group of parameters is required to organize multiple Inbound Actions in a way that they check an incoming email to match the condition defined in each of them, in a certain order. The less is the value in the Order field of an Inbound Action, the earlier this Inbound Action checks if a received email matches its execution condition. As a result, each email goes through an ordered chain of condition checks, from the Inbound Action with the least Order value to the one with the biggest, with the following processing logic: 

1. If an Inbound Action has the Active checkbox disabled (its value is set to 'false'), this Inbound Action is skipped. Inbound Actions with the Active checkbox enabled (its value is set to 'true') are processed further.
2. If an email matches no condition of any Inbound Action, it passes all the way down the processing chain.
3. If the condition of an Inbound Action is matched, the execution of the action script of that Inbound Action starts. The further processing flow depends on the value of the Stop processing when complete checkbox of this Inbound Action:

• • If the checkbox is not selected, the email is checked to match the condition of the next Inbound Action down the chain, and the logic proceeds from Step 2 again.
  • If the checkbox is selected, the rest of the Inbound Actions down the chain are skipped, and the processing chain is terminated. 

As a result, one inbound email can trigger execution of none, one or several action scripts in a row, depending on the values of the Active, Order and Stop processing when complete fields in each Inbound Action defined in the system.

Configuring inbound email action

1. Navigate to System Notification → Inbound Email Actions.
2. Click New and fill in the fields.
3. Click Save or Save and Exit to apply changes.

const newTask = new SimpleRecord('task');
newTask.subject = email.subject;
newTask.description = email.body_text;
if (email.blind_carbon_copy) {
    newTask.attention_required = true;
}
cosnt insertedTaskID = newTask.insert();

Use case

We need to configure an inbound action implementing the following logic:

• When the system receives an email with topic containing keyword "access", a new incident is created and assigned to the group responsible for security and access to the system and data.

We create an inbound action as below:

(function runAction( /*SimpleRecord*/ event, /*SimpleRecord*/ email) {

    ss.importIncludeScript('EmailHelper');
    const helper = new EmailHelper();

    const letter = email.subject.match('aсcess'); // Keywords checking
    if (letter) {
        const incident = new SimpleRecord('itsm_incident');
        incident.subject = email.subject;
        /* If the sender's address is registered in the system,
        the Caller field will contain reference to an existing User record.
        If the address is unknown, the caller will be defined as Guest */
        incident.caller = helper.userIDbyEmail(helper.parseSender(email.from));

        incident.description = email.body_text;
        incident.state = '-2'; // Registered
        incident.contact_type = '20'; // Email
        incident.assignment_group = '162920380313692887'; // Security Group
        incident.impact = '2'; // Moderate
        incident.urgency = '2'; // Moderate
        const insertedIncidentId = incident.insert();

        if (insertedIncidentId != 0) {
            ss.debug(`Email ${email.sys_id} processing result: Incident with ID ${insertedIncidentId}`);

            const attach = new SimpleAttachment();
            attach.copy('sys_email', email.sys_id, 'itsm_incident', insertedIncidentId);
            return;
        }
        ss.error(`Inbound Action Failed!\nErrors:` + JSON.stringify(incident.getErrors(), null, 2));
    }
})(event, email);

Inbound actions logging

Every inbound action triggering is logged in the Script Log table. These logs can be filtered using the criteria below:

• Source IS Inbound Action
• Essence Document CONTAINS 0229fa8a-bcbe-1f11.

Use the Condition Builder to build filters that fit your needs.

Recommendations

The incoming mail parsing returns the address value for the From field of a record from the Email (sys_email) table in lower case. 

When searching for a user by the email in the Script column, you should not use the IS operator because the value of email can be entered with uppercase letters. For example, J.Doe@mail.com.

user.get('email', 'j.doe@mail.com');

Also, do not use the LIKE operator when searching for a user by email because the search will find a user with a similar email, for example, 'raj.doe@mail.com'.

user.get('email', 'like', 'j.doe@mail.com')

The following example shows the script with the userIDbyEmail() method that search a user by email value:

class MyEmailHelper extends EmailHelper {
    userIDbyEmail(email) {
        const user = new SimpleRecord('user');
        user.addQuery('email', 'startswith', email);
        user.addQuery('email', 'endswith', email);
        user.selectAttributes('sys_id');
        user.setLimit(1);
        user.query();
        if (user.next()) {
            return user.sys_id;
        }
        return this.searchGuest();
    }
}

/