E-mail notification in ScriptRunner

To be able to use e-mail notifications with ScriptRunner, the e-mail notification connector must be put into operation. The settings for this 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.

The module maps the following functional areas for the global settings:

• licensing
• Connections for license activation via Internet proxy
• Script Library Directory and Archive Function
• directly usable PowerShell modules
• SQL connection string to external reporting/auditing database
• ScriptRunner Service
• E-mail Notification Connector
• E-Mail Inbound Connector

All cmdlets can be queried using Get-Command modules ScriptRunnerSettings.

Preparations

ScriptRunner Service Host can send emails over an SMTP connection. The following information is required for configuration:

• Name of the SMTP server
• port
• Use of TLS yes/no
• Authentication: anonymous user or named user (username, password)
• E-Mail Sender Address
• CC Receiver Addresses

Query configuration

The basic settings of the E-Mail Notification Connector can be queried with the command Get-ASREMailNotificationConnector -verbose. After the setup some usual settings have already been made, which do not necessarily have to correspond with the situation in the environment!

Setting the E-Mail Notification Connector

The setting is done with the command Set-ASREMailNotificationConnector. 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 machine with the SMTP service.
• Port: Port of the SMTP service on the machine.
• UseTLS: use TLS 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
• UseMailboxAsSender: the mailbox of the user is used. Its e-mail address is used as the sender address. Sent e-mails are stored as sent e-mails in the mailbox (system-dependent).
• Sender: Sender e-mail address if UseMailboxSender=no
• CCSender: the e-mail is sent to the sender in CC.
• 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-ASREMailNotificationConnector -MailboxAccount MyAccount -Password $SecPwd

Example 1 – anonymous shipping

If the notifications are to be sent using the SMTP settings “Anonymous”, the ScriptRunner Host must be authorized as an anonymous sender in the mail system.

The following settings would have to be made for this:

• Host: MyMailserver.corp
• Port: 25 OR 587
• Use TLS: yes OR no (depending on port)
• Transmitter: ScriptRunner@corp.com
• CCSender: no (default) OR yes, if a mailbox for ScriptRunner exists on another mail system

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

Example 2 – Exchange

If the notifications are to be sent via Exchange Server, it must be possible to log on to an Exchange mailbox from the ScriptRunner host.

The following settings would have to be made for this:

• Host: MyExchangerServer
• Port: 587 OR 25
• Use TLS: yes OR no (depending on port)
• Mailbox account: User name for the Exchange mailbox
• Password: Password for the user as PowerShell Secure String OR
• ClearPassword: Password in plain text
• UseMailboxAsSender: yes

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

Example 3 – Office 365

If notifications are to be sent via Office 365 Exchange Online, it must be possible to log on to Exchange Online from the ScriptRunner host.

The following settings would have to be made for this:

• Host: smtp.office365.com
• Port: 587
• Use TLS: yes
• MailboxAccount: complete mail address of the Office365 user
• Password: Password for the user as PowerShell Secure String OR
• ClearPassword: Password in plain text
• UseMailboxAsSender: yes

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

Testing the E-Mail Notification Connector

The connector test only checks the settings and the logon to the SMTP service. No test mail will be sent.

The test is performed with the command Test-ASREMailNotificationConnector. 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

When testing Anonymous SMTP connections no password is required!

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.

Use e-mail notifications to actions

A notification in ScriptRunner is always assigned to a specific action and consists of four essential elements:

• Trigger for a Notification Message
• Contents of a Notification Message
• Receiver of a notification message
• Output channel of a message

For e-mail notifications, the output channel is the e-mail notification connector.

Alternative triggers for an e-mail notification message can be:

• The execution of the action generated an error.
• The execution of the action was successful.
• The action is complete, whether successful or with an error.

The receivers of a notification message can be defined for each action in the action wizard. To do this, select the action and click the EDIT button in the Action Bar (below). Then select the Wizard page Set Result Options & Notifications.

To test, execute the action and select and open the mail in the mailbox (please also check spam folder).

The e-mail contains a simple short report in the body and the PowerShell Report as an attachment.

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