E-Mail Notification Connector

Es ist oftmals gewünscht, dass Administratoren oder auch andere Anwender über die Ausführung einer Automationsaufgabe informiert werden sollen. Dabei geht es neben der reinen Statusinformation auch um die Mitteilung von Ergebnissen oder Fehlern.

ScriptRunner Notifications können pro Aktion bei Erfolg, Fehler oder immer an einen definierten Personenkreis versendet werden. ScriptRunner bietet hierfür aktuell die Funktion der E-Mail Notification an. Die Arbeitsweise ist in der Abbildung schematisch dargestellt.

Um E-Mail Notifications mit ScriptRunner nutzen zu können, muss der E-Mail Notification Connector in Betrieb genommen werden. Die Einstellungen dafür fallen unter die globale Konfiguration des ScriptRunner Service Hosts und werden mit dem PowerShell Modul „ScriptRunnerSettings“ vorgenommen.

Der Benutzer des Moduls muss entsprechende Zugangs- und Systemrechte für das Betriebssystem auf dem ScriptRunner Service Host besitzen. Diese Rechte sind unabhängig von der Mitgliedschaft in der Rolle ScriptRunner Administratoren.

Das Modul bildet folgende Funktionsbereiche für die globalen Einstellungen ab:

  • Lizensierung
  • Verbindungen zur Lizenzaktivierung über Internet-Proxy
  • Script Library Verzeichnis und Archive Funktion
  • direkt verwendbare PowerShell Module
  • SQL Connection-String zur externen Reporting/Auditing Datenbank
  • ScriptRunner Service
  • E-Mail Notification Connector
  • E-Mail Inbound Connector

Alle Cmdlets können mit Get-Command -Module ScriptRunnerSettings abgefragt werden.

 

Vorbereitungen

ScriptRunner Service Host kann E-Mails über eine SMTP Verbindung versenden. Für die Konfiguration werden folgende Informationen benötigt:

  • Name des SMTP Servers
  • Port
  • Verwendung von TLS ja/nein
  • Authentifizierung: anonymous user oder named user (username, password)
  • E-Mail Sender Adresse
  • CC-Empfänger Adressen

Konfiguration abfragen

Die Grundeinstellungen des E-Mail Notification Connector können mit dem Kommando
Get-ASREMailNotificationConnector -verbose abgefragt werden. Nach dem Setup sind bereits einige übliche Einstellungen vorgenommen worden, welche jedoch nicht unbedingt mit der Situation in der Umgebung übereinstimmen müssen !

E-Mail Notification Connector einstellen

Die Einstellung erfolgt mit dem Kommando Set-ASREMailNotificationConnector. Folgende Parameter sind dabei von Bedeutung und können mit dem Kommando auch einzeln verwendet werden:

  • On: schaltet den Connector EIN
  • Off: schaltet den Connector AUS
  • Host: der FQDN oder die IP-Adresse der Maschine mit dem SMTP-Dienst
  • Port: Port des SMTP-Dienstes auf der Maschine
  • UseTLS: zur Kommunikation TLS verwenden ja/nein
  • MailboxAccount: Benutzername, welcher über SMTP versenden darf
  • Password: Passwort für den Benutzernamen als PowerShell Secure String ODER
  • ClearPassword: Passwort als Klartext
  • UseMailboxAsSender: die Mailbox des Benutzers wird verwendet. Dessen E-Mail-Adresse wird als Senderadresse verwendet. Versendete E-Mails werden als gesendete E-Mails in der Mailbox gespeichert (systemabhängig).
  • Sender: Absender-E-Mail-Adresse, wenn UseMailboxSender=no
  • CCSender: die E-Mail wird in CC an Sender verschickt
  • Restart: Durchstarten des ScriptRunner Service, um die Konfiguration wirksam werden zu lassen

Erstellen und Anwenden eines Secure String für „Password“

Dazu in der PowerShell ISE folgendes Kommando eingeben:

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

Die Variable $SecPwd enthält dann das Passwort. Diese kann nun innerhalb der Session in (jeder) Kommandozeile verwendet werden.

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

Beispiel 1 – anonymer Versand

Sollen die Notifications mittels der SMTP Einstellungen „Anonymous“ versendet werden, so muss der ScriptRunner Host als anonymer Absender im Mailsystem berechtigt sein.

Folgende Einstellungen wären dafür vorzunehmen:

  • Host: MyMailserver.corp
  • Port: 25 ODER 587
  • Use TLS: yes ODER no (abhängig von Port)
  • Sender: ScriptRunner@corp.com
  • CCSender: no (Standard) ODER yes, wenn es auf einem anderen Mailsystem eine Mailbox für ScriptRunner existiert

Zum Aktivieren dann die Optionen -On und -Restart sowie -Verbose verwenden.

Beispiel 2 – Exchange

Sollen die Notifications mittels Exchange Server versendet werden, so muss eine Anmeldung an eine Exchange Mailbox vom ScriptRunner Host aus möglich sein.

Folgende Einstellungen wären dafür vorzunehmen:

  • Host: MyExchangerServer
  • Port: 587 ODER 25
  • Use TLS: yes ODER no (abhängig von Port)
  • MailboxAccount: Benutzername für die Exchange Mailbox
  • Password: Passwort für den Benutzer als PowerShell Secure String ODER
  • ClearPassword: Passwort im Klartext
  • UseMailboxAsSender: yes

Zum Aktivieren dann die Optionen -On und -Restart sowie -Verbose verwenden.

Beispiel 3 – Office 365

Sollen die Notifications mittels Office 365 Exchange Online versendet werden, so muss eine Anmeldung an Exchange Online vom ScriptRunner Host aus möglich sein.

Folgende Einstellungen wären dafür vorzunehmen:

  • Host: smtp.office365.com
  • Port: 587
  • Use TLS: yes
  • MailboxAccount: vollständige Mailadresse des Office365 Benutzers
  • Password: Passwort für den Benutzer als PowerShell Secure String ODER
  • ClearPassword: Passwort im Klartext
  • UseMailboxAsSender: yes

Zum Aktivieren dann die Optionen -On und -Restart sowie -Verbose verwenden.

E-Mail-Notification Connector testen

Der Test des Connector prüft nur die Einstellungen und die Anmeldung am SMTP-Dienst. Es wird keine Testmail versendet.

Der Test erfolgt mit dem Kommando Test-ASREMailNotificationConnector. Es wird dazu die Eingabe des Passwortes benötigt. Folgende Varianten können mit dem Kommando verwendet werden:

  • Password: Passwort für den Benutzernamen als PowerShell Secure String ODER
  • ClearPassword: Passwort als Klartext

Beim Testen von Anonymous SMTP Verbindungen wird kein Passwort benötigt !

Einstellungen des Connectors in der ScriptRunner Admin App überprüfen

Die Einstellungen für den E-Mail Notification Connector können mit der ScriptRunner Admin App eingesehen werden. Änderungen können mit dem PowerShell Modul ScriptRunnerSettings vorgenommen werden.

 

Sollten vorgenommene Änderungen noch nicht in der Admin App sichtbar sein, so sollte der ScriptRunner Service auf dem Host mit dem Kommando Restart-ASRService durchgestartet werden.

E-Mail Notifications an Aktionen nutzen

Eine Notification in ScriptRunner ist immer einer bestimmten Aktion zugeordnet und besteht aus vier wesentlichen Elementen:

  • Auslöser für eine Notification Message
  • Inhalte einer Notification Message
  • Empfänger einer Notification Message
  • Ausgabekanal einer Message

Für E-Mail Notifications ist der Ausgabekanal der E-Mail Notification Connector.

Alternative Auslöser für einer E-Mail Notification Message können sein:

  • Die Ausführung der Aktion erzeugte einen Fehler
  • Die Ausführung der Aktion war erfolgreich
  • Die Aktion ist abgeschlossen, egal ob erfolgreich oder mit Fehler

Die Empfänger einer Notification Message können je Aktion im Action-Wizard festgelegt werden. Dazu die Aktion auswählen und in der Action Bar (unten) EDIT-Button klicken. Anschließend die Wizard-Seite Set Result Options & Notifications auswählen.

Zum Testen die Aktion ausführen und in der Mailbox (bitte auch Spam-Ordner prüfen) die Mail auswählen und öffnen.

Die E-Mail enthält im Body einen einfachen Kurzreport und als Anlage den PowerShell Report.

Wenn Sie Fragen zum E-Mail Notification Connector oder zu ScriptRunner allgemein haben können Sie uns über unser Kontaktformular oder unter scriptrunner@appsphere.com kontaktieren.

Frank Kresse

Frank Kresse

Head of Products Division bei ScriptRunner
Frank Kresse ist verantwortlich für die technische Entwicklung von ScriptRunner. Als Erfinder der Automations- und Delegationslösung für PowerShell berät er Kunden bei Use Case Szenarien und entwickelt Lösungen für die Automation und Digitalisierung ihrer Prozesse. Darüber hinaus engagiert er sich bei Tech-Startups.
Frank Kresse