Inbound Email Actions

Inbound email actions allow defining actions an instance takes when receiving an email. They allow to process inbound email as either an automatic reply or as a record in the system. The processing takes the type of incoming mail and other attributes into account.

They 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 watermark that associates the email with a task. If the conditions are met, then the inbound email action performs the pre-configured activities. They may be of two types:

• Record Action: runs a specified script.
• Reply Email: when triggered, sends a reply email.

Inbound email actions are most commonly used to process emails (for example, create a new incident when a received incoming email contains "Incident" in the subject line).

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.

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();
    }
}

/