E-Mail Inbound Connector

Bestehende Systeme und Applikationen können nicht immer über Web Services mit SOAP oder REST kommunizieren. Das erschwert die Automation von Abläufen mitunter erheblich oder verhindert diese sogar. Statt dessen können derartige Systeme in der Regel automatisiert E-Mails versenden und die Inhalte lassen sich mit Templates und Variablen steuern.

Es ist deshalb erforderlich und hilfreich, eine Automation von Aufgaben und Vorgängen mittels E-Mail sicher zu stellen. Ein wichtiger Baustein dafür ist der ScriptRunner E-Mail Inbound Connector. Die Arbeitsweise ist in der Abbildung schematisch dargestellt.

 

Für die Automation mit dem E-Mail Inbound Connector ist eine separate Lizenz pro externer Inbound Connection (Senderadresse) notwendig.

Um E-Mail Inbound Connector mit ScriptRunner nutzen zu können, muss sowohl eine separate Mailbox für ScriptRunner als auch der E-Mail Inbound Connector in Betrieb genommen werden.

Die Mailbox und deren Einstellungen sind am E-Mail Server sowie mit Hilfe eines E-Mail Programmes (z.B. Microsoft Outlook) zu konfigurieren.

Die Einstellungen für den Connector 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

Auf dem Mail Server der Organisation muss ein Postfach für ScriptRunner angelegt werden. Das Postfach muss IMAP kompatibel sein und IMAP muss für dieses Postfach aktiviert sein. Sinnvoll ist auch die Mailbox-Einstellung für den Message Body „plain-text“.

 

In der Mailbox sollten unterhalb des Folders Inbox bzw. Posteingang zwei Subfolder angelegt werden:

  • IN-Folder: dieser Folder wird vom ScriptRunner E-Mail Inbound regelmäßig überprüft. Alle E-Mails aus dem Posteingang, welche durch ScriptRunner noch zu bearbeiten sind, müssen per Postfachregel in diesen Folder verschoben werden.
  • DONE-Folder: in diesen Folder werden alle E-Mail verschoben, welche bereits von ScriptRunner verarbeitet wurden

 

Der ScriptRunner E-Mail Inbound Connector stellt die Verbindung zur Mailbox her. Für die Konfiguration werden folgende Informationen benötigt:

  • Name des IMAP Servers
  • Port
  • Verwendung von SSL ja/nein
  • Mailboxauthentifizierung mit Account Name und Passwort
  • IMAP Options
  • IN-Folder
  • DONE-Folder
  • Action Name in Subject
  • String für Subject Präfix

 

Konfiguration abfragen

Die Grundeinstellungen des E-Mail Inbound Connectors können mit dem Kommando
Get-ASREMailInboundConnector -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 !

 

IMAP Settings für E-Mail Inbound Connector einstellen

Die Einstellung erfolgt mit dem Kommando Set-ASREMailInboundConnector. 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 des Mail(box) Servers mit dem IMAP Service
  • Port: Port des IMAP Service auf dem Host
  • UseSSL: zur Kommunikation SSL 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
  • UseIdle: schaltet die IMAP IDLE Option ein/aus
  • UseInFolder: Subfolders SRIn unterhalb von Posteingang, in welchen der Connector nach neuen Inbound Messages sucht, benutzen ja/nein
  • UseDoneFolder: Subfolders SRDone unterhalb von Posteingang, in welchen der Connector bereits verarbeitetet E-Mails verschiebt, benutzen ja/nein
  • ActionFromSubject: der Name der aufzurufenden Aktion wird in der Subject-Zeile übergeben. Standardeinstellung ist nein.
  • SubjectPrefix: Nur inbound Messages, welche diesen Prefix in der Subject-Zeile haben, werden verarbeitet
  • 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-ASREMailInboundConnector -MailboxAccount MyAccount -Password $SecPwd

Beispiel – IMAP Settings zu einer Exchange Mailbox auf Office 365 einrichten

Sollen Inbound Messages aus einer Exchange Mailbox verarbeitet, so muss eine Anmeldung auf die Exchange Mailbox vom ScriptRunner Host aus möglich sein. Zudem muss die Mailbox für IMAP freigeschalten sein.

 

Im Beispiel werden die beiden Ordner SRIn und SRDone unterhalb der Inbox verwendet. Die aufzurufende Aktion wird als Parameter im Message Body übergeben.

 

Folgende Einstellungen wären dafür vorzunehmen:

  • Host: MyIMAPHost
  • Port: 993
  • UseSSL: yes
  • MailboxAccount: Benutzername für die Exchange Mailbox
  • Password: Passwort für den Benutzer als PowerShell Secure String ODER
  • ClearPassword: Passwort im Klartext
  • UseInFolder: SRIn
  • UseDoneFolder: SRDone

 

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

Anschließend die beiden eingerichteten Folder einschalten.

ACHTUNG: ScriptRunner prüft nun den Subfolder auf eingehende Messages. Bitte prüfen Sie die Posteingangsregeln für Messages in der Mailbox. E-Mails von den Quellsystemen oder Applikationen müssen per Regel in den Ordner SRIn verschoben oder kopiert werden !!

 

Nun reagiert der Connector auf ALLE Messages im Subfolder SRIn. Messages mit nicht ausreichenden Parametern werden nicht verarbeitet.

Beispiel – Nur Messages mit Präfix in der Subject-Zeile in ScriptRunner verarbeiten

Im Beispiel sollen nun nur Messages von ScriptRunner verarbeitet werden, welche den Präfix „#ASR#“ in der Subject-Zeile enthalten.

 

Folgende Einstellung wären dafür vorzunehmen:

  • SubjectPrefix: ‚#ASR#‘

 

Nun reagiert der Connector auf alle Messages mit dem Subject Präfix #ASR#  im Subfolder SRIn. Andere Messages ohne Präfix oder mit anderen Präfixes werden ignoriert.

 

Beispiel – Name der Aktion in der Subject-Zeile in ScriptRunner verarbeiten

Im Beispiel enthalten die Messages in der Subject-Zeile den Namen der aufzurufende Aktion in ScriptRunner.

 

Folgende Einstellung wären dafür vorzunehmen:

  • ActionFromSubject = yes

Nun reagiert der Connector alle Messages im Subfolder SRIn und interpretiert die Subject-Zeile als Name für die aufzurufende Aktion.

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.

 

Verbindung mit der ScriptRunner Mailbox testen

Der Test zum Verbinden mit der ScriptRunner Mailbox prüft nur die Einstellungen und die Anmeldung am IMAP-Dienst. Es wird keine Testmail versendet oder empfangen.

 

Der Test erfolgt mit dem Kommando Test-ASREMailInboundConnector. 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

E-Mail Inbound Connection einrichten

Für die praktische Nutzung des Connectors ist nun notwendig, entsprechende E-Mail Inbound Connections einzurichten.

Eine Inbound Connection umfasst:

  • Name der jeweiligen Connection
  • Absender Adresse des sendenden Systems oder der sendenden Applikation
  • Optional: Autorisierungs-Account (z.B. ScriptRunner Mailbox User) für die zugeordneten Aktionen

 

Folgender Schritt muss nur einmalig vorgenommen werden:

  • Aufnehmen einer AD-Gruppe oder eines AD-Users

 

Anschließend kann unter Connectors  und Klicken des Buttons CREATE die erste Inbound Connection konfiguriert und verwendet werden.

 

Aufbau und Struktur für eine Inbound E-Mail in ScriptRunner

Es bietet sich an, für einen Test die bereits mit der Installation ausgelieferte Aktion „Local: Add two values“ und „PS Remoting: Add two values“ zu verwenden.

 

Das Script „sum2values.ps1“, welches in den beiden Aktionen verwendet wird, addiert zwei Zahlen bzw. Strings und schreibt diese in die Variable SRXEnv.ResultMessage und gibt diese Variable auch in den 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

 

 

Die Aktion und das Script haben einige Merkmale, welche für die Automation mit Inbound E-Mails von Bedeutung sind:

 

  1. Die Aktion hat den Namen „Local: Add two values“ bzw. „PS Remoting: Add two values“. Dieser Name muss in der Inbound E-Mail an ScriptRunner übergeben werden.

Dafür gibt es zwei Möglichkeiten:

  • In der Subject-Zeile der E-Mail mit oder ohne Präfix
  • Als Parameter „SRXAction = Aktionsname“ im Mail-Body

 

  1. Die beiden Parameter „ValueA“ und „ValueB“ sind im Script verbindliche (mandatory) Parameter. Außerdem sind beide Parameter jeweils ein Validate Set, d.h. sie dürfen jeweils nur die vorgesehenen Werte annehmen. Und die Parameter müssen in der Inbound E-Mail an ScriptRunner übergeben werden.
    Dafür wurde eine einfache Möglichkeit der direkten Wertübergabe vorgesehen:
  • ValueA = Wert
  • ValueB = Wert

ACHTUNG: Nutzen Sie für die dynamische Nutzung die Möglichkeiten von variablen im Quellsystem bzw. in der Quellapplikation, BEVOR die E-Mail versendet wird. So könnten Sie den beiden Parameter ValueA und ValueB in einem Template Systemvariablen zuweisen, welche dann zur Laufzeit durch die tatsächlichen Werte ersetzt werden.

 

  1. Mit dem ScriptRunner-Systemparameter SRXReason können zusätzliche Informationen für das Reporting eingesteuert werden. So könnten beispielweise die Gründe für den Aufruf mitgegeben werden.

 

Der Aufbau der Inbound E-Mail kann als Ergebnis der obigen Punkte folgenden Aufbau haben:

 

Variante 1:

Subject-Zeile der Inbound E-Mail

  • Leer oder irgendein String

Body der Inbound E-Mail

  • SRXAction = Local: Add two values
  • SRXReason = Test mit Name der Aktion als Parameter
  • ValueA = Script
  • ValueB = Runner

 

Variante 2:

Subject-Zeile der Inbound E-Mail

  •  Local: Add two values

Body der Inbound E-Mail

  • SRXReason = Test mit Name der Aktion im Subject
  • ValueA = 17
  • ValueB = 5

ACHTUNG: für diese Variante muss das IMAP-Setting ActionFromSubject = yes konfiguriert sein. Details zur Konfiguration weiter oben.

 

Variante 3:

Subject-Zeile der Inbound E-Mail

  •  #ASR# leer oder String

Body der Inbound E-Mail

  • SRXAction = Local: Add two values
  • SRXReason = Test mit Name der Aktion im Subject
  • ValueA = 17
  • ValueB = 5

ACHTUNG: für diese Variante muss das IMAP-Setting ActionFromSubject = no und SubjectPrefix = ‚#ASR#‘ konfiguriert sein. Es werden nur Inbound E-Mails verarbeitet, welches das Präfix #ASR# in der Subject-Zeile enthalten. Details zur Konfiguration weiter oben.

 

Variante 4:

Subject-Zeile der Inbound E-Mail

  •  #ASR# Local: Add two values

Body der Inbound E-Mail

  • SRXReason = Test mit Name der Aktion im Subject
  • ValueA = 17
  • ValueB = 5

ACHTUNG: für diese Variante muss das IMAP-Setting ActionFromSubject = yes und SubjectPrefix = ‚#ASR#‘ konfiguriert sein. Details zur Konfiguration weiter oben.

 

 

Testen mit Inbound E-Mails

Um die Automation mit Inbound E-Mails auszuprobieren, bietet es sich an, entsprechende Test E-Mails mittels eines Mail-Clients wie outlook an das Postfach zu ScriptRunner Postfach zu senden und dann die Reports in ScriptRunner zu überprüfen.

Aufbau der Test E-Mail in Variante 1 ohne Subject Filter:

 

 

Im Event Log auf dem ScriptRunner Host erscheint folgender Eintrag:

Im ScriptRunner Reporting der ausgeführten Aktion gibt es nun folgenden Report:

Aufbau der Test E-Mail in Variante 2 mit Aktionsname im Subject

ACHTUNG: für diese Variante muss das IMAP-Setting ActionFromSubject = yes konfiguriert sein. Details zur Konfiguration weiter oben.

 

Aufbau der Test E-Mail in Variante 3 mit Aktionsname im Subject

ACHTUNG: für diese Variante muss das IMAP-Setting ActionFromSubject = no und SubjectPrefix = ‚#ASR#‘ konfiguriert sein. Es werden nur Inbound E-Mails verarbeitet, welches das Präfix #ASR# in der Subject-Zeile enthalten. Details zur Konfiguration weiter oben.

 

Ergebnisse der ausgeführten Aktion weiter verarbeiten

 

Sollen die Ergebnisse der ausgeführten Aktion weiterverarbeitet werden, so bieten sich hierfür folgende Möglichkeiten an:

  1. Im Script wird ein Web Service aufgerufen, an welchen die Ergebnisse in der notwendigen Struktur (meinst JSON)übermittelt werden. Das Script übernimmt dabei die Funktion eines Web Service Clients.
  2. Die Ergebnisse werden in ein File (CSV,XML ..) geschrieben und auf dem Dateisystem oder einem Share abgelegt. Das verarbeitende System holt sich das Ergebnisfile ab.
  3. Die Ergebnisse werden in den PowerShell output geschrieben. Eine Notification E-Mail enthält den output stream als TXT-File. Dieses kann vom verarbeitenden System geparst werden.
  4. Die Ergebnisse werden in einer Datenbank gespeichert. Im Script müssen dann Funktionen für den Datenbankzugriff enthalten sein.

 

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

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.