Automation with the E-Mail Inbound Connector

Author: | Category: Automation | Reading time: 5 minutes

Automation E-Mail Inbound Connector, ScriptRunner, PowerShell

This article has been translated automatically.

Existing systems and applications cannot always communicate with SOAP or REST via Web Services. This makes the automation of processes sometimes considerably more difficult or even prevents it. Instead, such systems can usually send automated e-mails and the content can be controlled with templates and variables.

It is therefore necessary and helpful to ensure the automation of tasks and processes via e-mail. An important building block for this is the ScriptRunner E-Mail Inbound Connector. The working method is shown schematically in the figure.

For automation with the e-mail inbound connector, a separate license is required for each external inbound connection (sender address).

In order to use E-Mail Inbound Connector with ScriptRunner, both a separate mailbox for ScriptRunner and the E-Mail Inbound Connector must be put into operation.

The mailbox and its settings can be configured on the e-mail server and with the help of an e-mail program (e.g. Microsoft Outlook).

The connector settings fall under the global configuration of the ScriptRunner Service Host and are made using the PowerShell ScriptRunnerSettings module. The user of the module must have appropriate access and system rights for the operating system on the ScriptRunner Service Host. These rights are independent of the membership in the role ScriptRunner Administrators.

Preparations

A mailbox for ScriptRunner must be created on the mail server of the organization. The mailbox must be IMAP compatible and IMAP must be enabled for that mailbox. The mailbox setting for the message body “plain-text” is also useful.

In the mailbox, two subfolders should be created below the Inbox or Inbox folder:

  • IN-Folder: this folder is checked regularly by the ScriptRunner E-Mail Inbound. All e-mails from the inbox, which are still to be processed by ScriptRunner, must be moved to this folder by mailbox rule.
  • DONE-Folder: in this folder all emails will be moved which have already been processed by ScriptRunner.

The ScriptRunner E-Mail Inbound Connector establishes the connection to the mailbox. The following information is required for configuration:

  • Name of the IMAP server
  • port
  • Use of SSL yes/no
  • Mailbox authentication with account name and password
  • IMAP Options
  • IN folder
  • DONE folder
  • Action Name in Subject
  • String for Subject Prefix

Querying the Configuration of the Connector

The basic settings of the e-mail inbound connector can be queried using the Get-ASREMailInboundConnector -verbose command. After the setup some usual settings have already been made, which do not necessarily have to correspond with the situation in the environment!

Setting IMAP Settings for E-Mail Inbound Connector

The setting is made with the command Set-ASREMailInboundConnector. The following parameters are important and can also be used individually with the command:

  • On: switches the connector ON
  • Off: switches the connector OFF
  • Host: the FQDN or the IP address of the mail(box) server with the IMAP service
  • Port: Port of the IMAP service on the host.
  • UseSSL: use SSL for communication yes/no
  • Mailbox account: Username, which may send via SMTP
  • Password: Password for the user name as PowerShell Secure String OR
  • ClearPassword: Password as plain text
  • UseIdle: switches the IMAP IDLE option on/off.
  • UseInFolder: Use subfolders SRIn below the inbox in which the connector searches for new inbound messages yes/no
  • UseDoneFolder: Subfolders SRDone below inbox, where the connector is already moving processed emails, use yes/no
  • ActionFromSubject: the name of the action to be called is passed in the subject line. The default setting is no.
  • SubjectPrefix: Only inbound messages that have this prefix in the subject line are processed.
  • Restart: Restart the ScriptRunner service to make the configuration effective.

Creating and Applying a Secure String for Password

Enter the following command in the PowerShell ISE:

C:users…>$SecPwd = ConvertTo-SecureString -String ‘mypassword’ -AsPlainText -Force

The $SecPwd variable then contains the password. This can now be used within the session in (any) command line.

C:users…>Set-ASREMailInboundConnector -MailboxAccount MyAccount -Password $SecPwd

Example – Setting up IMAP Settings for an Exchange Mailbox on Office 365

If inbound messages are to be processed from an Exchange mailbox, it must be possible to log on to the Exchange mailbox from the ScriptRunner host. The mailbox must also be enabled for IMAP.

In the example, the two folders SRIn and SRDone are used below the inbox. The action to be called is passed as a parameter in the message body.

The following settings would have to be made for this:

  • Host: MyIMAPHost
  • Port: 993
  • UseSSL: yes
  • Mailbox account: User name for the Exchange mailbox
  • Password: Password for the user as PowerShell Secure String OR
  • ClearPassword: Password in plain text
  • UseInFolder: SRIn
  • UseDoneFolder: SRDone

Then use the options -On and -Restart as well as -Verbose to activate it.

Then switch on the two folders that have been set up.

ATTENTION: ScriptRunner now checks the subfolder for incoming messages. Please check the inbox rules for messages in the mailbox. E-mails from the source systems or applications must usually be moved or copied to the SRIn folder!

The connector now reacts to ALL messages in the subfolder SRIn. Messages with insufficient parameters are not processed.

Example – Only process messages with prefix in the subject line in ScriptRunner

In the example only messages of ScriptRunner are to be processed which contain the prefix “#ASR#” in the subject line.

The following setting would have to be made for this:

  • SubjectPrefix: ‘#ASR#’

Now the connector reacts to all messages with the subject prefix #ASR# in the subfolder SRIn. Other messages without a prefix or with other prefixes are ignored.

Example – Processing the Name of the Action in the Subject Line in ScriptRunner

In the example, the messages in the subject line contain the name of the action to be called in ScriptRunner.

The following setting would have to be made for this:

  • ActionFromSubject = yes

The connector now reacts to all messages in the subfolder SRIn and interprets the subject line as the name for the action to be called.

Check connector settings in the ScriptRunner Admin App

The settings for the E-Mail Notification Connector can be viewed with the ScriptRunner Admin App. Changes can be made with the PowerShell module ScriptRunnerSettings.

If changes made are not yet visible in the admin app, the ScriptRunner service on the host should be restarted with the Restart-ASRService command.

Testing the connection with the ScriptRunner mailbox

The test to connect to the ScriptRunner mailbox only checks the settings and the login to the IMAP service. No test mail is sent or received.

The test is performed with the command Test-ASREMailInboundConnector. The password has to be entered. The following variants can be used with the command:

  • Password: Password for the user name as PowerShell Secure String OR
  • ClearPassword: Password as plain text

Set Up E-Mail Inbound Connection

For the practical use of the connector, it is now necessary to set up corresponding e-mail inbound connections.

An inbound connection includes:

  • Name of the respective connection
  • Sender Address of the sending system or sending application
  • Optional: Authorization account (e.g. ScriptRunner mailbox user) for the assigned actions

The following step only has to be carried out once:

  • Recording an AD group or AD user

The first inbound connection can then be configured and used under Connectors and clicking the CREATE button.

Structure of an Inbound E-Mail in ScriptRunner

For a test it is recommended to use the action “Local: Add two values” and “PS Remoting: Add two values” already delivered with the installation.

The script “sum2values.ps1”, which is used in both actions, adds two numbers or strings and writes them into the variable SRXEnv.ResultMessage and also returns this variable into the PowerShell output stream.

<#

SYNOPSIS.

Add two values – since we don’t specify a type, it allows numbers as well as strings.

PARAMETER ValueA.

First value to add

PARAMETER ValueB.

Second value to add

#>

param

(

[Parameter(Mandatory=$true)]

[ValidateSet(17, “Script”, “Two parts o”)]

$ValueA,

[Parameter(Mandatory=$true)]

[ValidateSet(5, “Runner”, “f a sentence”)]

$ValueB

)

# add the two values, and print the result as a nice string to the report.

$result = $ValueA + $ValueB

$SRXEnv.ResultMessage = “” + $ValueA + ” + ” + $ValueB + ” = ” + $result

# add the result to PowerShell output stream

$SRXEnv.ResultMessage

The action and the script have some features that are important for automation with inbound e-mails. The action has the name “Local: Add two values” or “PS Remoting: Add two values”. This name must be passed to ScriptRunner in the inbound email.

There are two ways to do this:

  • In the subject line of the e-mail with or without prefix
  • As parameter “SRXAction = Action name” in the mail body

The two parameters “ValueA” and “ValueB” are mandatory parameters in the script. In addition, both parameters are each a Validate Set, i.e. they may only assume the intended values. And the parameters must be passed to ScriptRunner in the inbound email.

A simple possibility of direct value transfer was provided for this purpose:

  • ValueA = Value
  • ValueB = Value

ATTENTION: For dynamic use, use the possibilities of variables in the source system or in the source application BEFORE the e-mail is sent. This allows you to assign the two parameters ValueA and ValueB to system variables in a template, which are then replaced by the actual values at runtime.

With the ScriptRunner system parameter SRXReason additional information for reporting can be added. For example, the reasons for the call could be given.

The structure of the inbound e-mail can have the following structure as a result of the above points:

Variant 1:

Subject line of the inbound e-mail

  • Empty or any string

Body of the Inbound E-Mail

  • SRXAction = Local: Add two values
  • SRXReason = Test with name of action as parameter
  • ValueA = Script
  • ValueB = Runner

Variant 2:

Subject line of the inbound e-mail

  • Local: Add two values

Body of the Inbound E-Mail

  • SRXReason = test with name of action in subject
  • ValueA = 17
  • ValueB = 5

ATTENTION: for this variant the IMAP setting ActionFromSubject = yes must be configured. Configuration details above.

Variant 3:

Subject line of the inbound e-mail

  • #ASR# empty or string

Body of the Inbound E-Mail

  • SRXAction = Local: Add two values
  • SRXReason = test with name of action in subject
  • ValueA = 17
  • ValueB = 5

ATTENTION: for this variant the IMAP setting ActionFromSubject = no and SubjectPrefix = ‘#ASR#’ must be configured. Only inbound e-mails containing the prefix #ASR# in the subject line are processed. Configuration details above.

Variant 4:

Subject line of the inbound e-mail

  • #ASR# Local: Add two values

Body of the Inbound E-Mail

  • SRXReason = test with name of action in subject
  • ValueA = 17
  • ValueB = 5

ATTENTION: for this variant the IMAP setting ActionFromSubject = yes and SubjectPrefix = ‘#ASR#’ must be configured. Configuration details above.

Testing with Inbound E-Mails

In order to try out automation with inbound emails, it is a good idea to send test emails to the ScriptRunner mailbox using a mail client such as outlook and then check the reports in ScriptRunner.

Structure of the test e-mail in variant 1 without subject filter:

The following entry appears in the Event Log on the ScriptRunner Host:

In the ScriptRunner Reporting of the executed action there is now the following report:

Structure of test e-mail in variant 2 with action name in subject

ATTENTION: for this variant the IMAP setting ActionFromSubject = yes must be configured. Configuration details above.

Structure of test e-mail in variant 3 with action name in subject

ATTENTION: for this variant the IMAP setting ActionFromSubject = no and SubjectPrefix = ‘#ASR#’ must be configured. Only inbound e-mails containing the prefix #ASR# in the subject line are processed. Configuration details above.

Processing the Results of the Executed Action Further

If the results of the executed action are to be processed further, the following options are available:

  • In the script, a web service is called to which the results are transmitted in the necessary structure (meaning JSON). The script assumes the function of a Web Service Client.
  • The results are written into a file (CSV,XML ..) and stored on the file system or a share. The processing system collects the result file.
  • The results are written to the PowerShell output. A notification e-mail contains the output stream as TXT file. This can be parsed by the processing system.
  • The results are stored in a database. The script must then contain functions for database access.

If you have any questions about the E-Mail Inbound Connector or about ScriptRunner in general, you can contact us via our contact form or at info@scriptrunner.com.

You might also be interested in these posts:

Secure Password Server, PowerShell
ScriptRunner Server-Eye, Monitoring Automation, PowerShell Automation
Matrix42 und ScriptRunner, PowerShell Automation