Skip to main content

2.10.3. Email Processing

Note:

The Email Processing feature is available only when the additional package messaging-mail is installed.

The Mail Processing shortcut group has been introduced to integrate the platform with email services for managing messages. This group includes the following shortcuts:

  • Email Sources — a shortcut that allows you to add your email mailbox to the platform for further work with its messages.
  • Email Processing Rules — a shortcut that allows you to automate the sorting and processing of incoming messages based on defined criteria.
  • Received Messages — a shortcut for viewing and managing all messages received through configured email sources.
  • Mail Operations Log — a shortcut for tracking all email operations, including errors and processing statuses.

2.10.3.1. Add an Email Source​

  1. In the navigation panel, select the Studio 1 workspace.

  2. Select the Integration 2 shortcut group, then select the Mail Processing 3 shortcut group.

  3. Select the Email Sources 4 shortcut.

  4. In the toolbar, select Create 5.

  5. Fill in the fields using the hints in the table below.

    FieldDescription
    Protocol*Select the protocol for receiving mail:
    • IMAPS — a secure email access protocol that uses SSL/TLS encryption for a protected connection.
    • IMAP — a standard email access protocol without encryption. It has all the features of IMAPS, but data is transmitted in plain text over port 143, making it vulnerable to interception.
    • POP3S — a secure version of the POP3 protocol with SSL/TLS encryption.
    • POP3 — a basic version of the POP3 protocol without encryption.
    For most modern mail servers, IMAPS is recommended as it provides the best balance between functionality and security.
    Server*Enter the URL of the incoming mail server. Here are the URLs for popular mail servers:
    • Gmail: imap.gmail.com. ⚠️ Note: A Gmail mailbox can only be connected if two-factor authentication is enabled on it.
    • Ukr.net: imap.ukr.net
    • Outlook.com: outlook.office365.com — all authentication types are available for this server: Basic and OAuth2.
    Port*Specify the port for connecting to the server. For the IMAPS protocol, for example, enter port number 993.
    Full SSLEnable this option for a secure connection to the mail server via SSL/TLS. Recommended to protect credentials.
    Login*Enter the email address or username for authorization on the mail server.
    ⚠️ Note: Gmail can only be connected if IMAP/POP3 access is configured in it. In that case, the Login field must contain the credentials for that configured access — the login and password for the mailbox itself are not accepted.
    Authentication TypeSelect the authentication type for connecting to the mail server. This depends on your mail server settings:
    • Basic — standard authentication using a login and password.
    • OAuth2 — a modern authentication method that provides enhanced security without transmitting a password. The platform supports integration with Microsoft Azure (via the Microsoft Entra ID service) as an OAuth2 provider.

  6. Fill in the remaining fields depending on the selected authentication type:

    FieldDescription
    Password*Enter the password for accessing the mailbox.
    ⚠️ Note: Gmail can only be connected if IMAP/POP3 access is configured in it. In that case, the Password field must contain the credentials for that configured access — the login and password for the mailbox itself are not accepted.
    DescriptionAdd a brief description of this email account's purpose for easier administration.
    Note:

    Fields marked with * are required.

  7. Select the Verify button to check that you have entered the correct credentials for your mailbox.

  8. Select the Next button.

  9. Fill in the fields using the hints in the table below.

    FieldDescription
    Monitoring folder*Select the folder in your mailbox where you want to monitor new messages:
    • Custom — a custom folder (you need to specify the name)
    • Drafts — the drafts folder
    • Inbox — the inbox folder (recommended)
    • Sent — the sent messages folder
    • Spam — the spam folder
    • Trash — the deleted messages folder
    Action on message receipt*Select the action to be performed on messages after processing:
    • Delete from folder — permanently delete the message from the mailbox
    • Move to folder — move the message to the specified folder in your mailbox
    • Mark with keyword — add a label to the message without moving it
    Destination folder
    field is available only for the Move to folder action    		Select the folder from the list to which you want to move messages.
    ℹ️ Note: The Monitoring folder value cannot match the Destination folder value. Two different folders must be selected for these two parameters.
    Keep received messages, days Enter a number that represents how many days messages will be stored in the system. By default, messages will be stored in the system and will not be deleted.
    Note:

    Fields marked with "*" are required.

  10. Select the Next button.

  11. Select the Delete messages that do not match any rule 1 checkbox if you want to delete messages that do not match any of the filtering rules.

  12. In the Logging level 2 field, select which types of data you want to record in the mail operations log:

    • Debug (recommended) — log all types of notifications, including information about establishing a connection, selecting a folder, or receiving messages. Additionally, all messages you add in the server script via logger.debug(), logger.info(), logger.warn(), and logger.error() will be logged.
    • Info — log only warnings, errors, and general information about mail processing statuses. Additionally, messages you add in the server script via logger.info(), logger.warn(), and logger.error() will be logged.
    • Warning — log only warnings and errors in mail processing. Additionally, messages you add in the server script via logger.warn() and logger.error() will be logged.
    • Error — log only errors in receiving mail. Additionally, messages you add in the server script via logger.error() will be logged.
    Note:

    Additional logging messages can be configured in the server script of email processing rules.

  13. Select the Add button.

  14. In the top panel, select Activate to set the rule status to Active.

After successfully adding the email source, the system will automatically start monitoring the specified folder and processing new messages according to the configured email processing rules.

2.10.3.2. Create an Email Processing Rule​

To create an email processing rule, you can fill in all or some of the tabs:

  1. General — general rule settings, such as the name, description, and the email source to which this rule will be applied.

  2. Filters — conditions by which the system will determine which emails to process. If no filters are set, the platform will process all messages received in the connected mailbox.

  3. Variables from message — configuration of variables that the system will automatically extract from filtered (or all) emails and store for further use in the Actions tab.

  4. Actions — configuration of actions that the system will perform on messages that meet the defined filter conditions. You can select one or more actions to apply to each matching message.

2.10.3.2.1. General​

  1. In the navigation panel, select the Studio 1 workspace.

  2. Select the Integration 2 shortcut group, then select the Mail Processing 3 shortcut group.

  3. Select the Email Processing Rules 4 shortcut.

  4. In the toolbar, select Create 5.

  5. Fill in the fields using the hints in the table below.

FieldDescription
Email source*Select the email source (mailbox) whose messages you want to work with.
Name*Enter a clear name for the rule.
Priority*Enter any integer to define the execution order of this rule. This field is relevant if you have created multiple rules for a single email source. Use the Priority field to set the order in which these rules will be applied. Rules with a lower number are executed first.
Description Add a brief description of the rule.
Note:

Fields marked with "*" are required.

2.10.3.2.2. Filters​

  1. Go to the Filters 1 tab, then fill in the fields 2 using the hints in the table below.
    Use this tab to configure the conditions by which the system will determine which emails to process. If no filters are set, the platform will process all messages received in the connected mailbox.

FieldDescription
Interpret as regular expressionsIf the toggle is not enabled, the platform will interpret the data entered in the fields literally. If enabled, you can use regular expression format — a special JavaScript syntax for compactly writing complex search rules. Examples: .*@example\.com (all addresses of a domain), ^support@ (addresses starting with "support@"), \d{4} (four-digit numbers).
Sender containsEnable the Sender contains toggle if you want to filter messages by this criterion. Then, in the field below, enter part of the sender's address or domain (for example, "@company.com" or "support").
Recipient containsEnable the Recipient contains toggle if you want to filter messages by this criterion. Then, in the field below, enter part of the recipient's address or keywords.
CC containsEnable the CC contains toggle if you want to filter messages by this criterion. Then, in the field below, enter part of the address from the CC field of the message.
Subject containsEnable the Subject contains toggle if you want to filter messages by this criterion. Then, in the field below, enter keywords or phrases that should be present in the message subject.
Message body containsEnable the Message body contains toggle if you want to filter messages by this criterion. Then, in the field below, enter text fragments to search for in the message content.
Use script for filteringEnable the Use script for filtering toggle if you want to apply a custom script with more complex processing logic. Then, in the field below, enter the script code.

The script must be in JavaScript format. All message variables (data) are available in the script:
  • @property \{string\} from
  • @property \{string\} to
  • @property \{string|null\} cc
  • @property \{string|null\} subject
  • @property \{string\} body
  • @property \{string\} bodyText
  • @property \{string\} rawContent
  • @property \{string\} sentDate
  • @property \{Array<\{name: string, contentType: string, data: ArrayBuffer\}>\} attachments
Note:
  • If no filter condition is enabled and configured, the actions you define in the next tab will be applied to all messages received at the specified email source.
  • If multiple conditions are enabled, a message will be filtered only if it matches all active filters. That is, if you have multiple conditions enabled and a message matches only one of them, the rule will not trigger and the message will be ignored by this filter.

2.10.3.2.3. Variables from message​

  1. Go to the Variables from message 1 tab if you want to extract a specific type of data from the message (for example, the sender's email address).

  2. Select the Add variable 2 button.

    Where to use these variables?

    Variables from message are values that the system automatically extracts from filtered (or all) emails and stores for further use. For example, you can create a variable attach and store the files attached to the message in it.

    These variables can then be used in the Actions tab — in particular in the Create document action to write information from the message into a document attribute. Variables can also be used in the Server script action to pass message data to other parts of the platform or to implement complex logic.

  3. Fill in the fields 1 using the hints in the table below, then select the Add 2 button.

FieldDescription
Name*
  • The name must be unique for each variable.
  • The name must be short (typically up to 10 characters).
  • Use only Latin letters and digits.
  • Do not start the variable name with a digit.
  • Only the following special characters are allowed: $ and _.
Description Enter a brief description of the variable's purpose.
Data type*Select the type of data you want to extract from the message:
  • Attachment — a file (or multiple files) attached to the email (for example, PDF, JPG, DOCX).
  • Date — the date the email was sent or received.
  • Object — use this type if you need to return structured data in JSON format. This is a single result that can contain multiple related values. Example: If the message subject contains an order number and the body contains an amount and currency, you can collect this data into one variable.
  • Text — a text fragment from the message, including letters, digits, and special characters, depending on the configured search conditions.
  • Number — numeric values from the message. The system will ignore letters and special characters and return only the number matching the specified search conditions.

  1. Fill in the remaining settings according to the data type:

    For data type: Attachment
    FieldDescription
    Standard attributes*Leave the value attachments (Object) — this is the only possible value for this data type.
    Method*Select the data search method:
    • Search attachments — search will be performed based on the specified conditions.
    • Script — search will be performed using the script you provide.
    Script*
    field is available only for the Script method    		Enter the script you want to use to search for and extract the required message attachments.
    File types
    field is available only for the Search attachments method    		In the list, select the checkboxes next to the file formats you want to extract from the message.
    Attachment sequence number
    field is available only for the Search attachments method    		Enter a number corresponding to the sequence number of the attachment. For example, if you always want to extract only the first attachment, enter 1.
    File name
    field is available only for the Search attachments method    		From the list, select the filtering criterion for the file name:
    • Matches regular expression — the name will match the conditions of the regular expression you can enter in the field below.
    • Contains — the name will contain the text you can enter in the field below.
    • Does not contain — the name will not contain the text you can enter in the field below.
    Require value
    field is available only for the Search attachments method    		Select this checkbox if extracting the attachment is mandatory. In that case, if the system cannot extract the attachment, the message will not be processed.
    Can have more than one value
    field is available only for the Search attachments method    		Select this checkbox if you allow extracting more than one attachment when they match the conditions defined above. If the system finds multiple attachments, they will be extracted as an array. If no value is found, an empty array will be returned.
    For data type: Object
    FieldDescription
    Standard attributes*Select one of the following data extraction sources:
    • attachments — the object will contain all attachments from the message.
    • ccObj — the object will contain the name and email address of the user specified in the CC field.
    • fromObj — the object will contain the name and email address of the user specified as the sender (from).
    • toObj — the object will contain the name and email address of the user specified as the recipient (to).
    Method*Leave the value Script — this is the only possible value for this data type.
    Script*
    field is available only for the Script method    		Enter the script you want to use to search for and extract the required objects.
    For data type: Date
    FieldDescription
    Standard attributes*Select one of the following data extraction sources:
    • sentDate — the date the message was sent.
    • receivedDate — the date the message was received.
    Method*Select the data search method:
    • From ... to — search will be performed based on the specified conditions. In the From field below, you can configure where the required information starts: at the beginning of the message body, or starting with any of the specified characters, specified text, or text matching a regular expression. Similarly, in the To field, you can specify where or how the required information ends.
    • Regular expression — the date will match the conditions of the regular expression you can enter in the field below.
    • Script — search will be performed using the script you provide.
    Require value
    field is available only for the From ... to and Regular expression methods    		Select this checkbox if extracting the value is mandatory. If the system cannot extract the data, the message will not be processed.
    Can have more than one value
    field is available only for the From ... to and Regular expression methods    		Select this checkbox if you allow extracting more than one value when they match the conditions defined above. If the system finds multiple values, they will be extracted as an array. If no value is found, an empty array will be returned.
    Remove leading and trailing spaces
    field is available only for the From ... to and Regular expression methods    		Select this checkbox if you want to strip leading and trailing spaces (if any) from the extracted result.
    Ignore case
    field is available only for the From ... to and Regular expression methods    		Select this checkbox to make the search case-insensitive. This helps find values regardless of how they are written in the message.
    For data type: Text
    FieldDescription
    Standard attributes*Select one of the following data extraction sources:
    • from — the full text from the From field: may contain only an email address, or a name together with an email (for example, John Doe <john@example.com>).
    • body — the full HTML content of the message (includes styles, tags, formatting). Use this if you need the HTML specifically.
    • bodyText — the plain text of the message without HTML tags.
    • cc — the recipient addresses in the CC field. May be one or more addresses as a string.
    • fromObj.email — the sender's email address.
    • fromObj.name — the sender's name, if specified in the message. Example: "John Doe" from the entry "John Doe <john@example.com>"
    • rawContent — the raw content of the email in its original form, without pre-processing. May include headers, service information, and the message body.
    • subject — the subject of the email as specified by the sender.
    • to — the recipient addresses in the To field. May contain one or more email addresses as a string.
    Method*Select the data search method:
    • From ... to — search will be performed based on the specified conditions. In the From field below, you can configure where the required information starts: at the beginning of the message body, or starting with any of the specified characters, specified text, or text matching a regular expression. Similarly, in the To field, you can specify where or how the required information ends.
    • Regular expression — the text will match the conditions of the regular expression you can enter in the field below.
    • Script — search will be performed using the script you provide.
    Require value
    field is available only for the From ... to and Regular expression methods    		Select this checkbox if extracting the value is mandatory. If the system cannot extract the data, the message will not be processed.
    Can have more than one value
    field is available only for the From ... to and Regular expression methods    		Select this checkbox if you allow extracting more than one value when they match the conditions defined above. If the system finds multiple values, they will be extracted as an array. If no value is found, an empty array will be returned.
    Remove leading and trailing spaces
    field is available only for the From ... to and Regular expression methods    		Select this checkbox if you want to strip leading and trailing spaces (if any) from the extracted result.
    Ignore case
    field is available only for the From ... to and Regular expression methods    		Select this checkbox to make the search case-insensitive. This helps find values regardless of how they are written in the message.
    For data type: Number
    FieldDescription
    Standard attributes*Select one of the following data extraction sources:
    • from (Text) — numbers from the From field, which may contain only an email address or a name together with an email (for example, John Doe <john@example.com>).
    • body (Text) — numbers from the full HTML content of the message (includes styles, tags, formatting). Use this if you need the HTML specifically.
    • bodyText (Text) — numbers from the plain text of the message without HTML tags.
    • cc (Text) — numbers from the recipient addresses in the CC field.
    • ccObj (Object) — numbers from the name and email address of the user specified in the CC field.
    • fromObj (Object) — numbers from the name and email address of the user specified as the sender (from).
    • fromObj.email (Text) — numbers from the sender's email address.
    • fromObj.name (Text) — numbers from the sender's name, if specified in the message. Example: "John Doe" from the entry "John Doe <john@example.com>"

    • If in the Standard attributes field you selected an attribute of type Text, see the instructions for the remaining fields in the table "For data type: Text".

    • If in the Standard attributes field you selected an attribute of type Object, see the instructions for the remaining fields in the table "For data type: Object".

2.10.3.2.4. Actions​

  1. Go to the Actions 1 tab, then select Add action 2.

  2. Fill in the fields 1 using the hints in the table below, then select the Add 2 button.

FieldDescription
Type*Select one of the following types:
  • Server script — allows you to execute custom server-side code. Suitable for complex logic, integrations, or passing message data to other parts of the platform. Recommended for users with programming skills.
  • Execute email action — adds action buttons to the message, allowing the user to complete a task or initiate a process without navigating to the platform.
  • Create document — automatically creates a new document of the selected type and allows you to configure the mapping of document attributes to variables extracted from the message.
  • Recognize document — allows you to automatically process message attachments and recognize their content using AI or IDP, with subsequent extraction of the required data. Note that the Tesseract technology is not supported for this action.
  • Start process — automatically starts the selected BPMN process when a matching message is received. Allows you to pass message data to the process and, if needed, link the process instance to a specific object in the system.
  • Send message to process — allows you to send a message to a business process that is waiting for it. This is analogous to the existing Send message functionality. Used to start a new process or to continue/control the execution of an already running process.
Priority*Enter any integer to define the execution order of this action. This field is relevant if you have created multiple actions for a single rule. Use the Priority field to set the order in which these actions will be applied. Actions with a lower number are executed first.
Description Add a brief description of the action.
Note:

Fields marked with "*" are required.

  1. Follow the next steps according to the selected action type:

    Next steps for the Server script type

    In the Server script field, paste the required server script corresponding to the action you want to perform on the filtered emails. See Server script example for adding messages to a table.

    Next steps for the Execute email action type

    To continue configuring email actions, see the Configure email actions section.

    Next steps for the Create document type

    To use this handler, make sure you have created variables from message (in the previous settings tab) that will be used to pass data to the document.

    1. In the Document type field, select the document type to be created by this handler.

    2. To configure the state of the new document, select one of the following options:

      • A Set initial state — the created document will have the state you marked as "Initial" in the States tab in the document type. If the "initial" state value is changed in the document type, the handler will automatically take these changes into account.

        Note:

        If you disable the "initial state" in the States tab, the state will be set to the handler's default values.

      • B Specify state — a field will appear where you can select one of the available states from the list that you have enabled for this document in the States tab. In this case, changing the "initial" state in the document type will not affect the state of the created document — it is fixed and remains unchanged.

        Note:

        If the specified state is deleted, the system will automatically replace it with the state that has the "initial" status.

    3. In the Author section of the document, select one of the following options:

      • A Message sender — the author of the created document will be the user who sent the email.
      • B Select author — a Position field will appear where you can select one of the system users to assign as the document author.
      Note:
      • If no document author is specified, the document will be created on behalf of the rabbit-router Service service account.
      • If the selected author has an assignment but no linked user, the document will be created on behalf of the rabbit-router Service service account.
      • The document will be created even if the selected author does not have access to the document type.
      • Document attachments are created on behalf of the user (not the position).

    4. Add a mapping between the variables from message (which you created in the previous tab) and the document type attributes into which the values of these variables will be passed.

      1. Select Edit.

      2. In the left panel, open the required attributes folder 1, then drag the required attribute to the Attribute settings 2 section.

      3. In the added attribute, in the Variable 1 field, select from the dropdown list the name of the variable whose value you want to write to this attribute.

        Note:

        The dropdown list only shows variables of the same type as the attribute type. For example, in an attribute of type Date, only variables of type Date will be displayed.

      4. Add the remaining attributes you want to populate with values from the message variables.

      5. Select Apply 2.

        Example of a configured mapping:

        Note:

        The platform will highlight mapping error entries in red. Such errors can occur in the following cases:

        • If after configuring the mapping you change the document type in the Document type field, and its attributes differ from the previously mapped attributes. In that case, the platform will highlight in red those attributes that no longer match the new document type.
        • If after configuring the mapping you change the list of attributes on the form of the selected document type.
        • If after configuring the mapping you return to the Variables from message tab and change the name or type of a variable.

        If the error is related to a document attribute, the icon will be displayed in the Attribute code A column. If the issue relates to a variable, the same icon will appear in the Variable B column.

        A rule with such mapping errors can be saved, but cannot be activated until the mismatch is resolved.

    Next steps for the Recognize document type

    1. In the Recognition template 1 field, select the template to be used for document recognition. Recognition templates of the Tesseract provider cannot be used for this action.

    2. Optional: Select the Automatically create document 2 checkbox if you want the system to automatically create a document after recognition. If the checkbox is not selected, recognition is performed without creating a document (with a preview), and you can confirm document creation manually later.

    3. Create a variable of type Attachment in the Variables from message tab and configure it to contain the attachment you want to recognize.

    4. In the Source 1 field, select the Attachment type variable you created in the previous step.

      Note:

      If the source variable contains 2 or more attachments, a single recognition record containing multiple documents will be created in the recognition log.

    5. Optional: In the Document author 2 field, select the user on whose behalf the recognition will be performed. The selected user will receive a notification about the recognition result. If no user is specified, the action is performed on behalf of the system account without sending notifications.

    Next steps for the Start process type

    1. In the Process definition 1 field, select the process to start.

    2. In the Version 2 block, select how to determine the process version:

      • Use latest version — the system will always start the most recent version of the process.
      • Use specified version — select a specific process version in the field below.

    3. Optional: In the Business key 1 field, select the variable whose value will be used as the business key of the process.

    4. Optional: Enable the Link process instance to object 2 toggle if you need to associate the process with a specific object in the system.

    5. If the toggle is enabled:

      1. In the Entity name 1 field, select the entity to link the process to. For example, if you want the process to be linked to a specific document, select the Documents (dfx_Document) entity.
      2. In the Variable 2 field, select the variable that contains the object ID. This can be a Number type variable you created in the Variables from message tab.

    6. Optional: In the Process variables block, configure data transfer to the process. For example: if you have a process that automatically creates a leave request, you can pass data from the message to it, such as the employee name, leave dates, etc. To do this, create the corresponding variables from the message in the Variables from message tab, and then link them to process variables in this block.

      1. Select Edit.

      2. Drag the variables from message to the Process variables section.

      3. In the added variable, in the Process variable 1 field, enter the name of the process variable to which the value of the message variable should be passed.

      4. Repeat these steps for all variables you want to pass to the process.

      5. Select Apply 2.

        Example of a configured variable transfer to the process:

    Next steps for the Send message to process type
    Notes:

    • To use the Send message to process action, you must first create a business process that is waiting for a message. For this, the process must contain one of the following elements:

      • Message Start Event — starts a new process when a message is received.
      • Intermediate Message Event — waits for a message during process execution and continues after receiving it.
      • Event Subprocess — contains elements that can react to a message at any point during process execution (with or without interruption).

      Also, in the settings of these elements, specify the message name. You will need to enter this name in the settings below.

    1. Select one of the methods for specifying the message name 1:

      • Extract message name from email — select a Text type variable whose value will be used as the message name.
      • Set message name manually — enter the value in the Message name field.

    2. Depending on the option selected in the previous step, in the Message name 2 field, enter the message name or select the Text type variable that contains the message name.

      Note:

      If you selected Set message name manually, the entered value must exactly match the value specified in the Name field of the Message section in the corresponding BPMN process element that is waiting for the message (for example, in the message start event).

    3. Optional: In the Process instance ID variable 1 field, select the Number type variable that contains the process instance ID.

    4. Optional: In the Business key 2 field, select from the list the Text type variable that will be used as the business key of the process.

    5. Optional: In the Correlation keys block, configure additional identification of the process to which the message should be sent. For example: if multiple processes are waiting for the same message, you can use correlation keys to determine which specific process the email relates to.

      1. Select Edit.
      2. Drag the variables from message to the Correlation keys section.
      3. In the added variable, in the Key 1 field, enter the name of the process variable by which the correlation will be performed.
      4. Repeat these steps for all required keys.
      5. Select Apply 2.

    6. Optional: In the Local correlation keys block, configure correlation for the local context of the process. For example: this may be useful if the process contains nested subprocesses and you need to find a specific execution context.

      1. Select Edit.
      2. Drag the variables from message to the Local correlation keys section.
      3. In the added variable, in the Key 1 field, enter the name of the local process variable.
      4. Repeat these steps for all required keys.
      5. Select Apply 2.

    7. In the Process variables block, configure data transfer to the process. For example: if you have a process that automatically creates a leave request, you can pass data from the message to it, such as the employee name, leave dates, etc.

      1. Select Edit.
      2. Drag the variables from message to the Process variables section.
      3. In the added variable, in the Process variable 1 field, enter the name of the process variable to which the value should be passed.
        Note:

        If you specify the name of a variable that already exists in the process, its current value will be replaced with the value passed from the email. That is, the old variable value will be overwritten with the new one.

      4. Repeat these steps for all variables you want to pass to the process.
      5. Select Apply 2.

    8. Optional: In the Local process variables block, configure data transfer to the local context of the process. For example: this may be useful if the value should only be used within a specific subprocess.

      1. Select Edit.
      2. Drag the variables from message to the Local process variables section.
      3. In the added attribute, in the Process variable 1 field, enter the name of the local process variable.
      4. Repeat these steps for all variables you want to pass.
      5. Select Apply 2.

  2. In the toolbar, select Save.

  3. In the top panel, select Activate to set the rule status to Active.

Note:

Before processing an email, the system automatically checks and sanitizes the HTML content of the message body to remove potentially dangerous fragments.

  • During sanitization, the system removes elements that may contain or execute malicious code (for example: <script>, <iframe>, <form>, <input>, <button>, <video>, <audio>, <canvas>, <option>, <select>), and also prohibits inline styles (<style>) and unsafe attributes (<border>, <cellpadding>, <cellspacing>, <align>, <valign>).

  • At the same time, the system preserves safe formatting — text, headings, lists, tables, links, and images — using only an allowed set of HTML tags and attributes.

Server script example for adding messages to a table​


const {App,Repository,DataStore} = require('@unitybase/ub')
module.exports = {
/**
* @param {object} params
* @param {EmailMessage} params.message
* @param {Logger} params.logger
*/
run({message, logger}) {
  const messageID = extractMessageId(message.rawContent)
  logger.debug('messageID: ' + messageID)
  const documentID = extractDocumentId(message.body)
  logger.debug('documentID: ' + documentID)
  if (!documentID) {
    return
  }
  const tableAttrID= UB.Repository('frm_Attribute')
    .attrs('ID')
    .where('code', '=', 'email_table') //set table attribute code
    .selectScalar()

  const collectionAttrID= UB.Repository('frm_Attribute')
    .attrs('ID')
    .where('code', '=', 'emailAttachments') //set collection attribute code
    .selectScalar()
  const FileAttrID= UB.Repository('frm_Attribute')
    .attrs('ID')
    .where('code', '=', 'emailRawFile') //set file attribute code
    .selectScalar()
  const now = new Date();
  const isoString = now.toISOString();
  const ds = DataStore('dfx_DocumentItem')
  const newItemID = ds.generateID()
  const fieldList = ['ID']
  const execParams = {
    ID: newItemID,
    documentID: documentID,
    attrID: tableAttrID,
    attrValues : JSON.stringify({
      "emailSubject": message.subject, //subject -text
      "emailFrom": message.from, //from - text
      "receivedAt": isoString //date and time
    })
  }
  const ubq = {
    entity: 'dfx_DocumentItem',
    fieldList,
    execParams,
    __skipRls: true,
  }
  ds.run('insert', ubq)
  DataStore('dfx_Document').runWithResult('setRichText', {
    execParams: {
      documentID: documentID,
      documentItemID: newItemID,
      attrCode: 'emailBodyHtml', //rich text attribute code
      value: message.body
    },
    __skipRls: true,
    __skipOptimisticLock: true
  })
  const attachments= message.attachments

  if (attachments.length > 0) {
    for (const attach of attachments) {
      const ds1 = DataStore('dfx_DocumentAttachment')
      const attachmentID = ds1.generateID()
      ds1.insert({
        execParams: {
          ID: attachmentID,
          documentID: documentID,
          attrID: collectionAttrID,
          documentItemID: newItemID,
          original: JSON.stringify(
            App.blobStores.putContent({
              entity: 'dfx_DocumentAttachment',
              attribute: 'original',
              ID: attachmentID,
              fileName: attach.name
            }, attach.data)
          )
        }
      })
    } //end for
  } //end if
  const ds3 = DataStore('dfx_DocumentAttachment')
  const attachmentID = ds3.generateID()
  ds3.insert({
    execParams: {
      ID: attachmentID,
      documentID: documentID,
      attrID: FileAttrID,
      documentItemID: newItemID,
      attachment: JSON.stringify(
        App.blobStores.putContent({
          entity: 'dfx_DocumentAttachment',
          attribute: 'attachment',
          ID: attachmentID,
          fileName: `${messageID}.eml`
        }, message.rawContent)
      )
    }
  })

  /**
   * IMPORTANT: The following function extracts the document ID only from the HTML body of the email,
   * if it contains <span style="color:#ffffff">12345</span>.
   * This depends on the presence of exactly such an element and style (#ffffff).
   * If the email does not contain such a <span>, or the email client modified/removed the styles,
   * the function will return null and processing will be skipped.
   */
    const match =
      htmlContent.match(/<span[^>]*color:\s*#ffffff;?[^>]*>(\d+)<\/span>/i);
    return match ? parseInt(match[1]) : null;
  }

  function extractMessageId(emailContent) {
    const match = emailContent.match(/Message-ID:\s*<([^>]+)>/i);
    return match ? match[1] : null;
  }
}
}

2.10.3.3. View Received Messages​

In the Received Messages shortcut, you can view the original content of a message, its status, and the mail operations associated with it.

To view received messages:

  1. In the navigation panel, select the Studio 1 workspace.

  2. Select the Integration 2 shortcut group, then select the Mail Processing 3 shortcut group.

  3. Select the Received Messages 4 shortcut.

In this shortcut, you will see a list of all messages and their statuses:

  • Processed — a message that was successfully processed according to the configured processing rules.

  • Filtered — a message that was filtered by the configured filters, but no action was applied to it.

  • Error — a message that encountered an error during processing. This may be related to incorrect rule settings, issues with the message format, or technical failures.

  • Pending — a message is in the processing queue. This status appears for messages that have been received but have not yet gone through all processing stages.

  • Cancelled — processing of the message was cancelled manually.

  1. Select the required message to view its original content or the mail operations associated with it.

2.10.3.4. View Mail Operations Status​

  1. In the navigation panel, select the Studio 1 workspace.

  2. Select the Integration 2 shortcut group, then select the Mail Processing 3 shortcut group.

  3. Select the Mail Operations Log 4 shortcut.

The mail operations log displays all information about the email processing system, including successful operations, warnings, and errors.

2.10.3.5. Email Actions​

Email actions allow you to configure the execution of a user task using action buttons that you can integrate into an email message.

2.10.3.5.1. Configure Email Actions​

To configure email actions, follow these steps:

  1. Add an email source. After creating it, perform the following actions:

    1. In the toolbar, select the Activate 1 button.
    2. Select the Make action processing source 2 button.
    Note:

    Only one email source can be the action processing source. To check which source is the action processing source in your system: Administration 1 workspace > Settings 2 shortcut group > System Settings 3 shortcut > msg.execAction.replyToAdress 4 key

    Check the Value field.

  2. Create an email processing rule. When creating the rule, follow these conditions:

    1. In the Email source field, specify the same source you created in step 1.

    2. Go to the Actions 1 tab, then select Add action 2.

    3. In the Type 1 field, select Execute email action, then select Add 2.

    4. In the toolbar, select Save.

  3. Create task actions — create the actions you want to display on the email buttons. For example: "Approve" and "Reject".

  4. Create a task form. When creating the template, follow these conditions:

    1. In the Actions 1 tab, enable the same actions you created in step 3 2.

    2. In the toolbar, select Save 3.

  5. Create an email template. When creating the template, follow these conditions:

    1. In the Type field, select Process task notification.

    2. Above the Message body field, select + Action.

    3. Select the Task actions 1 folder to expand it.

    4. From the list, select the actions you enabled in step 4 2.

    Warning:
    • The actions in the message body must match the actions you enabled in the task form. If a button is added to the message body for an action that was not enabled in the task form, that button will not work.
    • Action buttons must be added separately for each language version of the template. If you created a new translation but did not add action buttons to it, that language version of the message will contain no buttons in any language.
    Note:

    The template locale affects the display language of action buttons in email messages. If the default language is set to English, the action buttons will be displayed in English. The user will receive the email in the language set in their profile, or in the default language if a translation for their language is not available.

  6. Link the email template to the user task.

    1. Open the required business process definition.

    2. Select the user task you want to use to send the email 1.

    3. In the task settings, select + in the Notifications 2 section.

    4. In the Assign from 1 field, select Email template.

    5. In the Email template 2 field, select from the list the template you created in step 5.

    6. In the toolbar, select Save.

  7. Link the task form to the user task.

    1. Select the same user task 1.

    2. In the task settings, expand the Form 2 section.

    3. Select the Task form 1 option.

    4. In the Task form 2 field, select from the list the form you created in step 4.

    5. In the toolbar, select Save.

Notes:

The action assigned to the button will be successfully executed under the following conditions:

  • There is a user in the system with the same email address as the sender of the message.
  • The task execution deadline has not expired.
  • The user who received the message with the action has one of the following roles within the task: Potential assignee, Assignee, Supervisor. An action performed by a user in the Observer role will not be processed.
  • The user task has the status Open.

2.10.3.5.2. Change the Expiry Time​

Change the expiry time for a specific action

To configure the expiry time for an action:

  1. Open the email template in which you configured the actions.

  2. In the Message body field, select the action button whose expiry time you want to change 1.

  3. In the top-right corner above the button, select Action: Action name 2.

  4. In the Expiry time (hours) 1 field, enter the required number of hours.

  5. In the toolbar, select Save 2.

Change the default expiry time for the entire platform

To change the expiry time at the platform level:

  1. In the navigation panel, select the Administration 1 workspace.

  2. Select the Settings 2 shortcut group, then select the System Settings 3 shortcut.

  3. Select the msg.execAction.defaultOTPExpireHours 4 key.

  4. In the Value 1 field, enter the desired number of hours, then select the 2 icon.

  5. In the language fields, enter the same value for each field 1, then select the Apply 2 button.

  6. In the toolbar, select Save.

2.10.3.5.3. Change the Button Design​

  1. Open the email template in which you configured the actions.

  2. In the Message body field, select the action button whose design you want to change.

  3. Select the Appearance 1 tab, then select Source code 2.

  4. In the Source code field, make the required changes to the CSS styles 1, then select the OK 2 button.