SignalByMailReply

Owned by Betül Kara (Unlicensed)
Last updated: Jun 22, 2023
6 min read

Description

The SignalByMailReply timer checks mailboxes for e-mails and forwards instances if there are any e-mails that have to be answered in order for further instances to be generated. The timer has to be used in combination with a https://tim-doc.atlassian.net/wiki/spaces/eng/pages/228230616 at an activity if a decision has to be made after receiving a signal. The sender will be assigned as an actor to all tasks of the current activity once the signal has been transmitted successfully. Additionally, all incoming emails will be attached to activities as a note, as long as they can be matched to a given activity. RegExp will be used to select a part of a successful email, which will be included in the process as a variable (with the name given Nodename-answer_successful).

The corresponding process instance has to be referred to as:

-----(${SYS.PROCESSINSTANCE_ID})-----

in the text of the email. The answer can either be written in the first line or in the following form:

-----[Reply: ]-----

 

Webservice Name

ProcessInstanceManager

Webservice Method

 

Parameter

Parameter

Description

Valid examples

Parameter

Description

Valid examples

email

This entails the complete email address which will be used to generate further emails.

  • ${name_of_variable}

  • ${instanceName}

password

The password used to access the desired email account.

  • 123456

port

This provides information on the port corresponding to the email address and the host. Frequently used ports are 110 Pop 995 Pop including encryption 143 IMAP 993 IMAP with encryption.

  • 995

host

Host, e.g., pop3.gmail.com or imap.gmail.com (very often this will entail either pop or pop3 or IMAP. SMTP is far less common!). An IMAP mailbox will be necessary if moving all emails to other folders. The kind of protocol to use is dependent on the mail- box being employed. If both common protocols are supported by the webservice, then IMAP should be selected as preferred protocol.

If the user wants to move emails to other folders, an IMAP mailbox is required. Basically, the use of the protocol depends on the mailbox. If both protocols are supported, then IMAP is to be preferred.

It is highly recommended to use a separate mailbox for each timer and process definition.

moveFolder

This is not a mandatory field if activated. This is the name of the folder into which successfully processed emails for signaling should be moved.

  • Processed

pDName

Name of the process definition.

  • MyProcessDefiniton

nodeNameRegExp

NodeNameRegExp is a regular expression that provides clues on how to find the name of an activity. The textual content of emails as well as corresponding subject headings will be scanned for this expression. e.g., ++(.+)++ The element which has to be searched would be the nodeName included in brackets.

signalSuccessMail

If the value is “true” then an email will also be sent to the sender as a reply confirming the successful receipt of a signal. The reply can be configured within the process by using variables.

  • true

  • false

processVariable

The value of a process variable will be set to the selected transition which then enables the https://tim-doc.atlassian.net/wiki/spaces/eng/pages/228230616 at the XOR gateway to make a decision.

  • nameOfVariable

leavingTransitions

How will the correct pathway for the process be found if multiple options exist after the current activity? Transitions will be included in the timer as parameters by mapping which exact terms are meant to be detected by this transition. At least one transition has to work properly, which in turn means that at least one of the correct terms has to be included in the text of an email. For example:

  • Approval:ok-O.K.-okay-yes-y-to-approve-approval-accepting-accept-adopting-all-right-alright-agreed-agreeing

  • Rejection:-not-okay-not-ok-not-O.K.-no-never-unacceptable

The transitions according to this are approval and rejection. To signal an approval a response to the e-mail might entail ok, okay, O.K. etc. Alternatively, to signal a rejection words would be used like “not okay”, no, never, etc.

  • Approval:ok-O.K.-okay

  • rejection:No-not

reasonRegExp

The decision contained in the email which signals that the process should be saved for access at a later stage of the process. At this point, the terms that should be used can be determined by searching the text of the email. If the decision is meant to provide a result extending over several rows the RegExp has to use the ending '?s', for example (.*?)Replies:?s

old version: email,password,port,host,limit,moveFolder,piIdRegExp,pDName,NodeNameRegExp,firstline,box,decisionRegExp,signalSuccessMail,processVariable,transitions
new version: username,password,port,host,moveFolder,pDName,NodeNameRegExp,signalSuccessMail,processVariable,transitions,decisionRegExp

 

Procedure

First, the mailbox specified by the timer will be opened to receive incoming emails. As a default setting the folder Inbox will be retrieved. This setting can be changed by configuring loom.properties with the parameter inbox-name-signal-by-mail-reply.
In the second step the first five emails to be found will be processed. This number of emails can be adapted by configuring loom.properties with the parameter inbox-name-signal-by-mail-reply. With each email, a search will be conducted to find a text according to the form of —–(1234)—– at first in the textual content and then in the subject heading. This text represents the identification number (ID) of the systems process instance.
The message will be ignored if neither an ID nor a corresponding process instance can be found within the system.
In the next step a user will be sought while sending an email. The sender will receive an email if no user can be identified.
In the following stage the name of an activity will be searched for in the content as well as in the subject heading of the email by using NodeNameRegExp parameter. In case a name is found, an examination will be conducted to check if this process instance is pertaining to the provided process definition parameter. If this is not the case, then this email is not supposed to be assigned to this timer. This email would then also be ignored and no email would be sent as a reply.
If this timer is the proper one pertaining to this particular email, an examination will be started to ensure that the process is also focused on the correct activity. If this is the case the email will be attached as a notice to an activity. In addition, the sender will receive a corresponding message.
Now the user who sent the email will be examined to ensure if he/she is responsible at least for one of the tasks related to the current activity. This user will then in turn be informed if this is not the case.
Next, a check for follow-up activities takes place. If there is only one existing activity the user will be assigned the status of an actor who is responsible for all tasks. There are several possibilities to continue with the process and to check if the mail entails a corresponding decision.
Afterwards, the user will receive the status of an actor assigned to the task. Process variables will then be generated and the process forwarded. An e-mail will also be sent if desired.
All emails that had been answered will be moved to the folder errorMessages if this folder already exists. The initial email which forwarded the whole process will be moved to the configurated folder.

 

Variables

The replies to invalid messages can be setup either by using a variable or the file loom.properties:

  • no-system-user-found-for-signal-by-mail-reply

  • user-not-actor-for-signal-by-mail-reply

  • found-no-transition-for-signal-by-mail-reply

  • found-no-node-for-signal-by-mail-reply

  • signal-done-for-signal-by-mail-reply

  • found-no-process-instance-for-signal-by-mail-reply

Only the configuration using loom.properties would be possible in this case.

The correct answer has to be configured in the following way:

  • signal-successful-signal-by-mail-reply

The name of the folder which has to be accessed can also be configured by using loom.properties via inbox-name-signal-by-mail-reply.

Depending on the exact stage of the procedure the following variables can be implemented:

  • emailFrom indicates the sender

  • userNameLast shows the surname of the system user

  • userNameFirst represents the given name of the current system user

  • nodeName represents the name of the node that should be signaled is provided in this section

  • nodeEndDate displays the date when this node was terminated. This variable is meant to be used only after termination of a node when trying to signal. The server's default timezone is used.
    Format: dd.MM.yyyy

  • nodeEndTime indicates the point in time when this node was terminated. This variable is intended to be used only after termination of a node when trying to signal. The server´s default timezone is used.
    Format: HH:mm

  • lastUserNameLast shows the surname of the user who terminated the node. This is supposed to be used only when trying to signal after termination of a node

  • lastUserNameFirst displays the given name of the user who terminated the node. This is this meant to be used for signalling only after the termination of a node

After sending the signal, the following variables are also available: 

 

Example

Parameters:

 This process is provided as an example:

The following is a simple example for the text of an email:

 

 

© TIM Solutions GmbH | AGB | Datenschutz | Impressum