Automations- und Integrationsconnectoren

ScriptRunner Connectoren sind Schnittstellen, mit denen Sie Drittsysteme an den ScriptRunner Server anbinden können, um die ScriptRunner Plattform funktional zu erweitern.

Es wird zwischen Automationsconnectoren und Integrationsconnectoren unterschieden.

ScriptRunner Connectoren

Übersicht der ScriptRunner Connectoren


Automationsconnectoren

Automationsconnectoren werden eingesetzt, damit externe Systeme Aktionen in ScriptRunner starten und die Ergebnisse dieser Aktionen wieder empfangen können.
Folgende Connectoren sind Automationsconnectoren:

  • Web Service Connector
  • Email Inbound Connector

Integrationsconnectoren

Integrationsconnectoren werden eingesetzt, damit ScriptRunner innerhalb von Aktionen auf externe Systeme und deren Ressourcen zugreifen, bzw. diese verändern kann.
Folgende Connectoren sind Integrationsconnectoren:

  • Password Server Connector
  • Report/Audit DB Connector
  • Email Notification Connector

Web Service Connector

Der Web Service Connector ermöglicht Verbindungen zur ScriptRunner Instanz durch eine REST API. Über diese Schnittstelle können externe Systemen auf ScriptRunner zugreifen und definierte Aktionen in ScriptRunner aufrufen.

Hinweis: Für die Nutzung des Web Service Connectors muss eine zusätzliche Lizenz erworben und eingespielt sein.

Funktionsweise des Web Service Connectors

Funktionsweise des Web Service Connectors

Funktionsweise

Funktionsweise des Web Service Connectors

Funktionsweise des Web Service Connectors

  • Eine per Web Service Connector gestartete Action läuft in ScriptRunner wie eine manuell gestartete.
  • Nach Ende der gestarteten Action wird das Resultat protokolliert und ist in der Admin App im Dashboard als Report aufgelistet.
  • Ablauf:
    1. Ein POST Request wird vom Drittsystem versendet
      Hinweis: Der Web Service Connector ist ein OData REST Web Service. SOAP oder WSDL werden nicht unterstützt.
    2. Der ScriptRunner Web Service Connector wartet auf Requests
      • Die Daten der POST Pakete sind im JSON Format
      • Unterstützt wird die allgemeine Formatregel von OData v4
    3. Request kommt an
      • Die Gültigkeit der IP-Adresse wird überprüft
      • Autorisierung des Absenders wird geprüft
      • JSON Paket wird ausgewertet
      • Parameterübergabe an die Action erfolgt
    4. Action wird gestartet
    5. Ergebnis kommt zurück
  • Report in ScriptRunner:
    • Reason: Entsprechender Web Service Connector und die übergebene Reason
    • Started By: Benutzer, unter dem der Web-Request verschickt wurde

Webhooks

Webhooks sind ein verbreitetes Mittel für die Kommunikation zwischen Servern. Damit wird dem Nachrichtenempfänger mitgeteilt, dass ein bestimmtes Ereignis eingetreten ist.

Das Grundkonzept ist, dass auf dem Quellsystem eine Payload-URL registriert wird, welche bei einem bestimmten Event aufgerufen werden soll. Für die Authentifizierung am Web Service Connector durch den Aufrufer kann NTLM oder Kerberos, notfalls auch Basic Auth verwendet werden.

Der ScriptRunner Web Service Connector unterstützt auch den Aufruf und das Starten von ScriptRunner Actions über registrierte Webhooks. Am Connector kann eine Payload-URl am Webhook registriert werden.

Action-ID & Payload-URL für Webhooks

Action-ID & Payload-URL für Webhooks

Die zu registrierende Webhook-URL auf dem Quellsystem wird im folgenden Format angegeben

[http(s)://FQDN]/ScriptRunner/api2/PostWebhook/[ID]

Hinweis: [ID] steht dabei für die ID der Aktion. Diese wird ab Version 2020R1 auf der ersten Seite der Aktion im Wizard angezeigt.

Konfiguration

Der Web Service Connector empfängt vom registrierten Webhook POST Requests die Daten im JSON Format.

  1. Die JSON-Datenstruktur Pakets werden der Aktion als ein Parameter übergeben.
  2. Dazu ist im PowerShell-Script der Parameter [string] $bodyString im Paramblock zu definieren.
  3. Dieser enthält den JSON-Payload des Quellsystems
    • wird mit dem Cmdlet ConvertFrom-JSON geparst, zerlegt und die Einzelteile den verwendeten PowerShell-Parametern zugewiesen.
  4. Ergebnis: PS Custom Object in der Datenstruktur des JSON Objekts.

Konfiguration

  1. Öffnen Sie ScriptRunner und melden sich mit einem Benutzer, der von Ihnen hinterlegten Admingruppe, an.
    • Sie befinden sich im Dashboard.
  2. Wechseln Sie in den Abschnitt Automation.
  3. Klicken Sie in der unteren Navigationsbar auf Create.
  4. Der Assistent öffnet sich.
    • Select the type of Automation Connector to create: Wählen Sie „Web Service Connector“ aus.
      • Klicken Sie auf Next.
    • Web Service Connector Properties: Passen Sie die Konfigurationsseite gemäß Ihrer Umgebung an:
      • Setzen Sie den Hacken bei Enabled
      • Display Name: Vergeben Sie einen Anzeigenamen
      • Application Scenario: Die UI ändert sich entsprechend Ihrer Auswahl.
        1. System / Application Backend: (Default)
          • Die Eingabe einer festen IP Adresse ist erforderlich.
          • Die Anzahl der Actions ist unbegrenzt, kann aber durch Delegation eingegrenzt werden.
          • Kann an jede Gruppe delegiert werden.
            Hinweis: Falls Sie Basic Authentication nutzen, muss der Web Service Connector an eine Person und keine Gruppe delegiert werden.
        2. User Application / Computers directly:
          • Feld ist für die Eingabe gesperrt.
          • Kann von jeder IP-Adresse angesprochen werden.
          • Kann nur an SelfService-Anwender delegiert werden.
        3. MicroServices / Kubernetes: Erfordert spezielle Lizenz!
          • Feld ist für die Eingabe gesperrt.
          • Kann von jeder IP-Adresse angesprochen werden.
          • Kann an jede Gruppe oder Benutzer delegiert werden.

Testen

ScriptRunner enthält im Lieferumfang das Script CallASRWebSvcConnector.ps1 mit vollständigem Beispielcode für das Ansprechen des Web Service Connectors aus der PowerShell.  Zum initialen Aufsetzen, oder zum Testen nach Fehlern, wird dieses Script verwendet:

  1. Öffnen Sie auf der Maschine des Drittsystems die PowerShell.
  2. Öffnen Sie das Script CallASRWebSvcConnector.ps1 und passen den Parameter $server entsprechend des FQDN des ScriptRunner Servers an.
  3. Starten Sie das Script CallASRWebSvcConnector.ps1 mit den gleichen Parametern wie das Drittsystem.
  4. Bei erfolgreicher Ausführung kann der Web Service Connector ebenfalls vom Drittsystem genutzt werden.
Fehleranalyse
  • <200 success> erfolgreicher Abschluss der Action
  • <400 bad request> fehlerhafter Request
  • <401 unauthorized> Benutzer ist nicht autorisiert
  • <403 forbidden> Benutzer ist nicht berechtigt
  • <404 not found> fehlerhafte URI
Mögliche Fehlerursachen
  • Verbindung zum Drittsystem funktioniert nicht / wird geblockt (Firewall, Proxy, etc.)
  • Falsche IP-Adresse des Absenders wurde hinterlegt
  • Falscher Benutzername/Kennwort wurde beim Drittsystem hinterlegt
  • Action kann/darf nicht ausgeführt werden (fehlende Delegation, Benutzerrechte)

Hinweis: Für eine detaillierte Fehleranalyse können die ScriptRunner Logs unter <C:\ProgramData\ScriptRunner\Service\Local\Log> verwendet werden.

Authentifizierung

Standardmäßig wird die Windows-integrierte Authentifizierung für den Web Service Connector verwendet. Für Drittsysteme, die diese Authentifizierung nicht können, kann Basic Authentication konfiguriert werden.

Der POST Request startet die Ausführung einer Action und überträgt die benötigten Daten als JSON Body. Dabei erfolgt die Authentifizierung des sendenden Benutzers.

Der POST Request wird an eine feste URL an den ScriptRunner Server gesendet.

http(s)://<hostname>:<port>/ScriptRunner/ActionContextItem/StartASRNamedAction

Standardmäßig arbeitet ScriptRunner mit integrierter Windows-Authentifizierung. Diese wird mit den angelegten Delegationselementen abgeglichen und garantieren somit die Autorisierung des Aufrufers.

Wird ein Auftrag per PowerShell mit Invoke-WebRequest verschickt, wird die integrierte Windows-Authentifizierung durch den Parameter -UseDefaultCredentials aktiviert:

PowerShell:

Invoke-WebRequest -UseDefaultCredentials […]

C#:

HttpWebRequest request = […];
request.UseDefaultCredentials = true;

CURL:

curl --negotiate -u : <URL…> 

Basic Authentication

Falls ein Drittsystem nicht über Windows-integrierte Authentifizierung über NTLM oder Kerberos verfügt, lässt sich der ScriptRunner Web Service Connector mit Basic Authentication ansprechen 

Hinweis: Da Basic Authentication Benutzernamen und Passwort im Klartext überträgt, ist es als unsicher anzusehen und möglichst zu vermeiden.  

Die Absicherung der Klartext-Passwörter muss über https erfolgen, was ein Server-Zertifikat für den ScriptRunner Host erfordert. 

Voraussetzungen

  • Benutzerlizenz in ScriptRunner
  • Web Service Connector Lizenz
  • Benutzeraccount zum Delegieren und Ausführen (lokaler Account auf dem ScriptRunner Server oder ein AD Benutzer)
    Hinweise:
    – Der lokale Benutzer muss auf dem ScriptRunner Server eingerichtet sein.
    – Der AD Benutzer und der ScriptRunner Server müssen in der gleichen Domäne sein.
    – Kann nicht an Gruppen delegiert werden, da ScriptRunner bei jedem Request nur die Korrektheit des Accounts und nicht dessen Gruppenzugehörigkeiten im AD prüft.
  • Zugang über https: SSL-Server-Zertifikat im Windows-Zertifikatsspeicher

Konfiguration

Wichtige Hinweise vor der Konfiguration:

  • Ein paralleler Betrieb von Basic Authentication für den Web Service Connector mit anderen STS-Zugangsarten ist im STS-Zugangsport nicht möglich.
    Hinweis: Standardport: 8091; STS-Zugangsport für Basic Auth.: 8092
  • Da der ScriptRunner Service unter dem Maschinen-Account ausgeführt wird, ist das der Zertifikatsspeicher der Maschine.
  • Um den Thumbprint (Fingerabdurck) Ihres installierten Zertifikats zu bestimmen, geben Sie in einer administrativen PowerShell folgenden Befehl ein:
    dir Cert:\LocalMachine\My
    

    Hinweis: In der Console wird dieser Wert mit Leerzeichen angegeben. Die Leerzeichen müssen vor der Benutzung des Cmdlets entfernt werden.

  • Die Speicherung des Passworts innerhalb von ScriptRunner erfolgt nicht.
  • Für jeden Account ist bei Verwendung von Basic Authentication eine eigene ScriptRunner Benutzerlizenz erforderlich.
  • Empfohlen wird folgende Schreibweise: DOMAIN\username bzw. COMPUTERNAME\username-> wechselnde Schreibweise führt zu mehrfachen Lizenzeinträgen.

ScriptRunner

Im Folgenden wird die Konfiguration des Basic Authentication Connectors beschrieben. Erst in ScriptRunner, dann in PowerShell.

  1. Öffnen Sie ScriptRunner und melden sich mit einem Benutzer, der von Ihnen hinterlegten Admingruppe, an.
    • Sie befinden sich im Dashboard.
  2. Wechseln Sie in den Abschnitt Delegation und legen eine Delegation an.
    Hinweis: Delegieren Sie an eine Service Desk Users Gruppe und hinterlegen Sie den vorher bestimmten Benutzer.
    • Beim Anlegen der Delegation für Basic Authentication sind folgende Felder erforderlich: 
      • Authorization Method: Claim-based identity
      • Claim Type: ScriptRunner-WebServiceConnector-Claim
        Achtung! Tippen Sie den Claim Type manuell ein, beim Kopieren können Fehler (Bindestich als Sonderzeichen) entstehen.
      • Claim Value: Benutzerkonto des Benutzers. DEVSTAR\luke
        Hinweis: Domäne und Benutzername wie am Drittsystem (AD: DOMAIN\username; lokal: COMPUTERNAME\username)

      Konfigurierte Delegation

      Konfigurierte Delegation

    • Delegated Actions: Wählen Sie die zu delegierenden Actions aus; Local: Add two values

      Zu delegierende Action

      Zu delegierende Action

  3. Wechseln Sie in den Abschnitt Automation.
    • Erstellen Sie durch einen Klick auf Create einen neuen Web Service Connector.
    • Füllen Sie die Felder gemäß Ihrer Anforderungen aus.
    • Restrict this Connector to a certain Delegation: Wählen Sie Ihre soeben konfigurierte Delegation aus.
      Hinweis: Für eine Fehleranalyse kann diese Restriktion kurzzeitig aufgehoben werden.

      Konfigurierter Web Service Connector

      Konfigurierter Web Service Connector

PowerShell

  1. Öffnen Sie die Windows PowerShell (ISE) auf dem ScriptRunner Server mit Administrationsrechten.
  2. Führen Sie das Cmdlet Set-AsrSTSOptions mit folgenden Parametern aus: *AuthMode, *BasicLocalAccounts, *LocalPort, *SSLCertThumbprint, *Restart-AsrService
Set-AsrSTSOptions -AuthMode WINBasic -BasicLocalAccounts 1 -LocalPort 8092 -SSLCertThumbprint 'a909502dd82ae41433e6f83886b00d4277a32a7b' Restart-AsrService
    • BasicLocalAccounts gibt an, um welchen Typ von Benutzer es sich handelt; 0=AD Benutzer, 1=lokaler Benutzer
    • 8092 bezeichnet den IP Port, den das Drittsystem mit Basic Authentication anspricht
    • a909502dd82ae41433e6f83886b00d4277a32a7b ist der Thumbprint des Zertifikats 
  1. Der ScriptRunner Dienst wird neugestartet.
  2. Mit dem Cmdlet Get-AsrSTSOptions kann die Authentifizierungsmethode überprüft werden.

    Cmdlet: Get-AsrSTSOptions

    Cmdlet: Get-AsrSTSOptions

Testen

Im Folgenden ein Beispielscript zum Testen der Basic Auth. Verbindung.

[PowerShell]

$baseURI = 'https://FQDN:BackendPort:8092/ScriptRunner/JobControl/'
$user = "DEVSTAR\luke"
$pass = 'password'
$pair = "$($user):$($pass)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"
$Headers = @{
    Authorization = $basicAuthValue
}
Invoke-WebRequest -Uri $baseURI -Headers $Headers -UseBasicParsing  | Select-Object statuscode

Fehleranalyse

  • <200 success> erfolgreicher Abschluss der Action
  • <400 bad request> fehlerhafter Request
  • <401 unauthorized> Benutzer ist nicht autorisiert
  • <403 forbidden> Benutzer ist nicht berechtigt
  • <404 not found> fehlerhafte URI

Hinweis: Für eine detaillierte Fehleranalyse können die ScriptRunner Logs unter <C:\ProgramData\ScriptRunner\Service\Local\Log> verwendet werden.

Konfiguration zurückstellen

  1. Öffnen Sie die PowerShell (ISE) mit Administrationsrechten und geben folgenden Befehl ein
Set-AsrSTSOptions -AuthMode WIN
  1. Öffnen Sie ScriptRunner und melden sich mit einem Benutzer, der von Ihnen hinterlegten Admingruppe, an.
    • Sie befinden sich im Dashboard.
    • (Optional) Wechseln Sie in den Abschnitt Delegation und entfernen die Delegation.
    • (Optional) Entfernen Sie AD bzw. auf der Maschine den Benutzer.

POST Request

Datenstruktur des POST Requests:

  • ActionName (Datentyp: string):
    Name der Action
  • ParamNames (Datentyp: string[]):
    Liste der Parameternamen (ohne $)
  • ParamValues (Datentyp: string[]):
    Liste der Parameterwerte. In Reihenfolge der ParamNames.
  • Options (Datentyp: string[]):
    (Optional) Liste von Optionen. Nur zweiter Eintrag wird derzeit verwendet. Ursache für Report kann angegeben werden, z. B. Ticket-Nummer, Workflow Case, etc.
  • RunFlags (Datentyp: int[]):
    (Optional) Liste von Zahlen. Nur erster Eintrag wird derzeit verwendet. Wartezeit in Sekunden kann angegeben werden
    Hinweis: Der Web Service wartet bis Auslauf der konfigurierten Wartezeit, auf das Ergebnis des Threads. Das Ausführen von parallel laufenden Aufrufen sollte vermieden werden, diese blockieren die Ausführung von weiteren Threads.

Hinweis: Parameter, die in der Action vorbelegt sind, können im Request weggelassen werden.

POST Response

Datenstruktur der POST Response:

  • ID (Datentyp: int64):
    Die ID des Status-Objekts. Wird benötigt, um auf Running=FALSE zu warten. 
  • Running (Datentyp: boolean):
    Gibt an ob Skript noch läuft. Wenn TRUE, sind die nachfolgenden Felder noch nicht abschließend gefüllt. 
  • IsError (Datentyp: boolean):
    Gibt an, ob Script-Ausführung in PowerShell zu einem Fehler geführt hat. 
  • OutResultMessage (Datentyp: string):
    Das Ergebnis der Action, wie im Script an $SRXEnv.ResultMessage übergeben. 
  • OutReportString (Datentyp: string):
    Kompletter PowerShell-Bericht, wie in der Admin App. 
  • OutSerializedPSObjects (Datentyp: string):
    Das Ergebnis der Action, wie im Skript an $SRXEnv.ResultObjectJSON übergeben. 
  • OutNumErrors (Datentyp: int32):
    IsError=TRUE: Anzahl der PowerShell Fehler. 
  • OutErrorString (Datentyp: string):
    IsError=TRUE: Die PowerShell-Fehlermeldungen, wie im Report angezeigt. 

Für die Rückgabe von mehreren Daten, als JSON Objekt kann der Eintrag ResultObjectJSON der ScriptRunner Umgebungsvariable $SRXEnv genutzt werden.

Hinweis:
Mehr Informationen zur Umgebungsvariable finden Sie in unserer Knowledge Base.
Mehr Informationen zum Web Service Connector finden Sie in unserer Knowledge Base.

Anwendungsfälle

Im Folgenden sind diverse Anwendungsfälle bezüglich des Web Service Connectors erklärt.

PRTG Network Monitor

PRTG Network Monitor überwacht rund um die Uhr die Verfügbarkeit und die Performance der gesamten IT-Infrastruktur. Bei Ausfällen oder Fehlern sendet PRTG auf der Grundlage individuell konfigurierbarer Schwellenwerte entsprechende Warnungen an ScriptRunner.

Voraussetzungen

Um PRTG gemeinsam mit ScriptRunner nutzen zu können, benötigen Sie folgende Komponenten:

  • Bestehende ScriptRunner Instanz
  • Bestehende PRTG Instanz
  • Aktivierte WebService Connector Lizenz
  • Konfigurierte Inbound/Outbound Firewallregeln

Funktionsweise

Funktionsweise PRTG

Funktionsweise PRTG

  1. Sensor löst Notification aus.
  2. Die Notification startet das Script zur Kommunikation mit ScriptRunner, mit Parameterübergabe aus PRTG.
  3. Das Script löst einen WebService-POST-Aufruf an ScriptRunner aus.
  4. Der POST-Aufruf  startet auf dem ScriptRunner Backend die konfigurierte Aktion mit den notwendigen Parametern.
  5. Im Script kann das Ergebnis ans Monitoringsystem zurückgegeben werden, z. B. ein „Add Comment“-Funktionsaufruf und Übergabe von $SRXEnv.ResultMessage an das Monitoringsystem.

Konfiguration

Im Folgenden ist die Konfiguration von ScriptRunner und darauffolgend vom PRTG System beschrieben.

ScriptRunner

  1. Öffnen Sie die Admin Oberfläche in ScriptRunner
  2. Wechseln Sie in den Abschnitt Automation
  3. Legen Sie einen neuen Web Service Connector an; klicken Sie auf Weiter
    1. Aktivieren Sie den Connector
    2. Vergeben Sie einen Display name
    3. Wählen Sie das Application Scenario aus
    4. Geben Sie die IP Adresse des PRTG Systems an
    5. Optional: Richten Sie eine Delegation ein

      Konfiguration Web Service Connector

      Konfiguration Web Service Connector

  4. Wechseln Sie in den Bereich Action
  5. Legen Sie eine neue Action an
    1. Select a Script: Wählen Sie das Script CheckWebServiceConnector aus; klicken Sie auf Weiter
    2. Action Properties: (Optional) Bearbeiten Sie den Anzeigenamen, Tags und die Beschreibung; klicken Sie auf Weiter
    3. Select Targets: Wählen Sie das Zielsystem aus, Standardmäßig wird [LOCAL] Direct Service Execution ausgewählt; Bestätigen Sie Ihre Konfiguration mit OK

PRTG

  1. Kopieren Sie das Script Callasrwebsvcconnector.ps1 (ScriptRunner Server) aus C:\ProgramData\ScriptRunner\ScriptMgr\EXPL\Common und legen es auf dem PRTG Server unter C:\Program Files (x86)\PRTG Network Monitor\Notifications\EXE ab
    Hinweis: Das PRTG System überprüft ausschließlich diesen Ordner, um Scripte der Auswahl hinzuzufügen.
  2. Öffnen Sie das Script im Bearbeitungsmodus (z. B. PowerShell ISE)
    1. Passen Sie den Parameter $server an, geben Sie hierzu die IP Adresse oder FQDN des ScriptRunner Servers an; Speichern Sie das Script

      Anpassung des $server Parameters

      Anpassung des $server Parameters

  3. Öffnen Sie den Web-Browser und verbinden sich mit dem PRTG System
  4. Legen Sie eine neue Benachrichtigung an
    1. Wechseln Sie in den Bereich >Konfiguration >Kontoeinstellungen >Vorlage für Benachrichtigungen
    2. Fügen Sie eine Vorlage für Benachrichtigungen hinzu
    3. (Optional) Bearbeiten Sie den Anzeigenamen, Tags, Status, Zeitplan etc.
    4. Öffnen Sie in den Bereich Programm ausführen
    5. Wählen Sie die Datei Callasrwebsvcconnector.ps1 aus und füllen die restlichen Felder gemäß Ihrer Daten aus; Speichern Sie Ihre Einstellungen
      1. Programmdatei: Name des Caller-Scripts; Callasrwebsvcconnector.ps1
      2. Parameter: -ActionName Callasrwebsvcconnector.ps1 -ParamNames Param1,Param2,Param3 -ParamValues ‚eins‘,’2′,’drei‘
        Hinweis: Eine Übersicht der verfügbaren PRTG-Variablen finden Sie hier.
      3. Domäne oder Computername: Domäne des aufrufenden Benutzers; devstar.org
      4. Benutzername: Benutzername des aufrufenden Benutzers; ani
        Hinweis: Der angegebene Benutzer benötigt eine Lizenz in ScriptRunner
      5. Kennwort: Passwort des aufrufenden Benutzers
      6. Zeitüberschreitung: Time out für den Aufruf -> hier muss getestet werden, wie lange das Starten der Aktion in der jeweiligen Umgebung benötigt; 60 Sekunden

        Konfiguration in PRTG

        Konfiguration in PRTG

Testen

  1. Öffnen Sie den Web-Browser und verbinden Sie sich mit dem PRTG System
  2. Wechseln Sie in den Bereich >Konfiguration >Kontoeinstellungen >Vorlage für Benachrichtigungen
    1. Wählen Sie Ihre erstellte Benachrichtigung aus und klicken auf Testbenachrichtigung versenden

      Testbenachrichtigung versenden

      Testbenachrichtigung versenden

  3. Wechseln Sie in den Bereich >Protokoll >Systemereignisse >Benachrichtigungen betreffend, um den Status der verschickten Testbenachrichtigung zu erfassen
    1. Wenn die Benachrichtigung erfolgreich versendet wurde, finden Sie unter Nachricht die Meldung „Status beim Versenden von EXE:OK“
      Feedback der Testbenachrichtigung

      Feedback der Testbenachrichtigung


  4. Wechseln Sie auf den ScriptRunner Server und melden sich in der Admin UI an
    1. Neben der Action Check-WebServiceConnector finden Sie einen grünen Balken, dieser zeigt die erfolgreiche Ausführung der Action an.

      Feedback in ScriptRunner

      Feedback in ScriptRunner

    2. Ein roter Balken zeigt an, dass es zu einem Fehler bei der Ausführung der Action kam.
      Hinweis: Eine genaue Fehlerbeschreibung finden Sie im Windows Event Log.

Zusätzliche Informationen

Funktionsweise des Caller-Scripts
  • Input – AktionName = Name der Action in ScriptRunner, die aufgerufen werden soll; Callasrwebsvcconnector.ps1
  • Input – ParamNames = Parameternamen des Actionsscripts; Param1,Param2,Param3
  • Input  – ParamValues = Variableninhalte von PRTG; ‚eins‘,’2′,’drei‘
  • Output – Berichts-ID, ResultMessage und Bericht
Wichtige Hinweise
  • Name des Überwachungssensors muss für das Beispielscript dem Namen des überwachten Dienstes entsprechen.
  • Actionsname beim Aufruf des Callerscripts muss dem Actionsnamen in ScriptRunner entsprechen und auf beiden Seiten angepasst werden.
  • ParamNames und ParamValues bilden zusammengehörige Paare. Die Namen der Parameter in ParamNames müssen denen im Script entsprechen. Die übergebenen ParamValues können anschließend im Script weiter verarbeitet werden.

 

Informationen zu PRTG

Aufruf über Execute Command

https://www.paessler.com/manuals/prtg/notifications_settings#program

Notification konfigurieren

https://www.paessler.com/manuals/prtg/notifications_settings

https://www.paessler.com/manuals/prtg/sensor_notifications_settings

https://www.paessler.com/manuals/prtg/setting_up_a_notification_example

Verfügbare Variablen in PRTG

https://kb.paessler.com/en/topic/373-what-placeholders-can-i-use-with-prtg

 

Password Server Connector

Der Password Server Connector wird eingesetzt, um die sichere Verwaltung und Zentralisierung von Passwörtern zu gewährleisten. Dadurch kann ScriptRunner während der Ausführung von Aktionen automatisch auf die sicher verwahrten Passwörter zugreifen. Somit müssen keine Credentials innerhalb von PowerShell-Scripten oder auf dem ScriptRunner Server hinterlegt werden.

Credential Management mit Password Servern

Unterstütze Password Server:

  • Pleasant Password Server
  • Thycotic Secret Server
  • CyberArk Password Vault

Pleasant Password Server

Um den Pleasant Password Server anzubinden, benötigen Sie folgende Komponenten:

  • Lizenzierter ScriptRunner Password Server Connector
  • Lizenzierter Pleasant Password Server
  • Gültiges Zertifikat auf dem ScriptRunner Server, für die Einrichtung der https Verbindung
  • Konfigurierter Safe, mit einem hinterlegten Benutzerkonto, auf dem Pleasant Password Server

Hinweis: Weitere Informationen zur Einrichtung des Pleasant Connectors finden Sie in unserer Knowledge Base.

Funktionsweise

  • Action wird über die ScriptRunner-Webschnittstelle gestartet.
  • ScriptRunner erkennt, dass die Action von einem Konto ausgeführt wird, das von einem Password Server verwaltet wird, und fragt das Passwort vom Password Server ab.
  • Der Password Server übergibt das Passwort an ScriptRunner.
  • ScriptRunner führt die Action mit dem ermittelnden Benutzerkonto aus.

Hinweis: ScriptRunner Credentials vom Windows Credential Store können parallel zu den Credentials vom Password Server Connector verwaltet werden.

Best Practice
  • Erstellen Sie einen eigenen ScriptRunner Service Account mit Lesezugriff auf den Password Server.
  • Erstellen Sie einen eigenen Password Safe für die ScriptRunner Credentials.
  • Legen Sie in diesem Safe alle Service Accounts für ScriptRunner ab.

Konfiguration

Um den Password Server Connector einzurichten, führen Sie die folgenden Schritte aus:

  1. Gehen Sie auf den ScriptRunner Server
  2. Öffnen Sie die PowerShell (ISE) als Administrator
  3. Geben Sie folgenden Befehl ein:
Set-AsrPasswordServerConnector -API 'Pleasant Password Server (APIv4)' -Host $host -Port 10001 -User $userName -ClearPassword $password -UseSSL yes -On -Restart

Hinweis: Passen Sie die Parameter $host, $userName und $password (User mit Leserechten in Pleasant) entsprechend Ihrer Umgebung an. Eine Fehlermeldung erhalten Sie erst in ScriptRunner unter Settings und nicht in der Console.

Mit dem Befehl Get-AsrPasswordServerConnector können Sie prüfen, ob der Password Server Connector aktiviert ist.

  1. Öffnen Sie ScriptRunner und melden sich mit einem Benutzer, der von Ihnen hinterlegten Admingruppe, an.
    • Sie befinden sich im Dashboard.
  2. Klicken Sie in der linken Navigationsbar auf den Abschnitt Settings
    • Hier können Sie sehen, ob eine Verbindung zum Pleasant Server besteht.
Mögliche Fehlerursachen
  • Hostname ist nicht gültig, Pleasant Server kann nicht gefunden werden
  • Zertifikat ist nicht gültig bzw. abgelaufen
  • Zertifikat ist an falscher Stelle abgelegt (local machine\my)
  • Hinterlegter Benutzer hat keinen Zugriff auf den Password Safe
  • ID des Benutzers stimmt nicht überein
  • Fehlende Berechtigungen des ermittelten Benutzerkontos

Konfiguration des Credentials

  1. Öffnen Sie den Web-Browser und melden sich am Pleasant Server an
  2. Öffnen Sie die Credential Details des betreffenden Benutzers
  3. Unter Direct Link finden Sie die ID des Benutzers:

    Credential Details in Pleasant

    Credential Details in Pleasant

  4. Kopieren Sie die ID
  5. Öffnen Sie die ScriptRunner Admin App und melden Sie sich mit einem Benutzer, der von Ihnen hinterlegten Admingruppe, an.
    • Sie befinden sich im Dashboard
  6. Klicken Sie in der linken Navigationsbar auf den Abschnitt Credentials
  7. Klicken Sie auf Create
  8. Der Assistent öffnet sich:
    • Display name: Vergeben Sie einen Anzeigenamen
    • Retrieve Password from the Password server: Hinterlegen Sie hier die soeben kopierte ID des Benutzers

      Konfiguriertes Credential in ScriptRunner

      Konfiguriertes Credential in ScriptRunner

  9. Bestätigen Sie Ihre Eingaben mit OK
  10. In der Übersicht wird das Credential gekennzeichnet, wenn das Credential von einem Password Server Safe abgerufen wird.

    Kennzeichnung des Credentials

    Kennzeichnung des Credentials

 

 

Testen

Für diesen Test wird die Action Get-ADUser Properties mit dem dazugehörigen Target ADC remote verwendet.

  1. Öffnen Sie die ScriptRunner Admin App.
  2. Melden Sie sich mit einem Benutzer, der von Ihnen hinterlegten Admingruppe, an.
    • Sie befinden sich im Dashboard.
  3. Klicken Sie in der linken Navigationsbar auf den Abschnitt Targets.
  4. Wählen Sie das Target ADC remote aus und klicken in der unteren Toolbar auf Edit.
  5. Der Assistent öffnet sich.
    • Wählen Sie bei PS Remoting credential das eben erzeugte Admin Ani Credential aus.

      Target Konfiguration

      Target Konfiguration

    • Bestätigen Sie Ihre Auswahl mit OK.
  6. Wechseln Sie in den Abschnitt Actions
  7. Klicken Sie die auszuführende Action an; Get-ADUser Properties
    • Die Action ist so konfiguriert, dass sie auf dem Target ADC remote ausgeführt wird.
  8. Klicken Sie in der unteren Toolbar auf Run
  9. Führen Sie die Action aus
  10. Der grüne Balken neben der Action zeigt an, dass die Action erfolgreich ausgeführt wurde.
    Hinweis: Ein roter Balken gibt an, dass während der Ausführung der Action ein Fehler aufgetreten ist.
  11. Report / Bericht anzeigen: Klicken Sie auf den Balken neben der Action oder auf den Ticker unten rechts.
    • Das Ergebnis der Action wird angezeigt.
Credential als Scriptvariable

Im Folgenden ein Beispielscript, das zurückgibt, ob das Pleasant-Credential richtig ausgelesen wurde.

[PowerShell]

Param(

[pscredential] $cred

)

Write-Output $cred.username

SQL Connector

Der SQL Connector ermöglicht es Ihnen, alle Informationen der Actionsreports zusätzlich in eine externe SQL-Datenbank zu speichern. Durch diese Langzeitaufbewahrung können Sie sicherstellen, dass kein Report verloren geht und Sie den Erfordernissen von Governance und Compliance gerecht werden.

Voraussetzung

  • Bestehende ScriptRunner Instanz
  • SQL Connector Lizenz
  • Bestehende SQL Datenbank und Benutzerkonto für DB
    Hinweis: Informationen zur Einrichtung des Benutzerkontos finden Sie unter Konfiguration

Funktionsweise

Funktionsweise SQL Connector

  1. Eine Action wird in SR gestartet und ausgeführt
  2. Wenn die Action beendet wurde, wird ein XML-File unter C:\Program Data\ScriptRunner\Service\Settings\Queues generiert.
    • Im XML-File sind PoSH Report Daten der ausgeführten Action.
  3. Die XML-Files werden an die Datenbank übergeben.
    • Der ScriptRunner Service schreibt mit dem entsprechenden Benutzerkonto das erzeugte XML-File in die ScriptRunner Tabelle auf der Datenbank.
      Hinweis: Der Connector kann als SQL-Client gesehen werden.
  4. Wenn die Verbindung zur Datenbank unterbrochen wird, wird eine Fehlermeldung ins Windows Event Log geschrieben.
    • In diesem Fall werden weitere Reports auf dem SR Server unter C:\Program Data\ScriptRunner\Service\Settings\Queues zwischengespeichert und bei wieder bestehenden Verbindung automatisch vom Service in die Datenbank übertragen.
      Hinweis: Es können maximal 10.000 Einträge im Ordner gespeichert werden.

Best Practice

  • Datenbank Name: ScriptRunner
  • Benutzerkonto auf der DB als Windows-Authentifizierung
  • Dem Benutzerkonto nur read/write Rechte geben
  • Bei einem Versionsupdate von SR immer das ExtDb_UpdateTables.sql Script auf der Datenbank einspielen und ausführen
    Hinweise:
    – Die Update-Datei liegt unter C:\Program Files\ScriptRunner\Service\Support
    – Zum Ausführen des Updates, folgen Sie den Anweisungen unter Update.

Konfiguration

Im Folgenden wird die Konfiguration der Datenbank danach die von ScriptRunner beschrieben. Für Datenbankbenutzer mit Windows-Authentifizierung folgen Sie 4A, für die SQL Server Authentifizierung Benutzer befolgen Sie die Schritte unter 4B.

Datenbank

  1. Gehen Sie auf den ScriptRunner Server
    • Öffnen Sie den Windows Explorer und gehen zu C:\Program Files\ScriptRunner\Service\Support
    • Kopieren Sie die Scripte ExtDb_CreateTables.sql und ExtDb_UpdateTables.sql
    • Verbinden Sie sich auf den SQL Server
    • Legen Sie die kopierten Scripte auf dem Server ab
  2. Öffnen Sie das SQL Server Management Studio
  3. Legen Sie eine neue Datenbank an; ScriptRunner
    SR

    ScriptRunner Datenbank

  4. A: Benutzer mit Windows-Authentifizierung
    • Legen Sie einen neuen Benutzer an
    • Vergeben Sie einen Anmeldenamen und die Eigenschaft Windows-Authentifizierung

      Datenbankbenutzer mit Windows-Authentifizierung

    • Berechtigen Sie den Benutzer auf die entsprechende Datenbank; ScriptRunner
    • Vergeben Sie die Rechte db datareader und db datawriter

      Eigenschaften des Datenbankbenutzers

    • Bestätigen Sie die Konfiguration mit OK
  5. B: Benutzer mit SQL Server-Authentifizierung
    • Legen Sie einen neuen Benutzer an
    • Vergeben Sie einen Anmeldenamen und die Eigenschaft SQL Server-Authentifizierung

      Datenbankbenutzer mit SQL Server-Authentifizierung

    • Berechtigen Sie den Benutzer auf die entsprechende Datenbank; ScriptRunner
    • Vergeben Sie die Rechte db datareader und db datawriter

      Eigenschaften des Datenbankbenutzers

    • Bestätigen Sie die Konfiguration mit OK
  6. Navigieren Sie in der DB Menüleiste auf Ordner öffnen
    Hinweis: Stellen Sie vor der Ausführung sicher, dass die korrekte Datenbank ausgewählt wurde

    Kontroller der Datenbank

    • Wählen Sie das kopierte Script ExtDb_CreateTables.sql aus
    • Klicken Sie auf Öffnen

      Script öffnen: Create Tables

    • Klicken Sie auf Ausführen
    • In der Fußleiste des Management Studios erhalten Sie eine Rückmeldung („Die Abfrage wurde erfolgreich ausgeführt“).
    • In der Datenbank >ScriptRunner >Tabellen wurden zwei neue Tabellen angelegt; BaseEntities_AppConfigSet und BaseEntities_JobControlSet
      Hinweis:
      AppConfigSet: Zeigt die aktuelle Schema Version; JobControlSet: Reportdaten der ausgeführten Actions.

      Angelegte Tabellen: AppConfigSet & JobControlSet

  7. Navigieren Sie in der DB Menüleiste auf Ordner öffnen
    Hinweis: Stellen Sie vor der Ausführung sicher, dass die korrekte Datenbank ausgewählt wurde
    • Wählen Sie das kopierte Script ExtDb_UpdateTables.sql aus
    • Klicken Sie auf Öffnen

      Script öffnen: Update Tables

    • Klicken Sie auf Ausführen
    • In der Fußleiste des Management Studios erhalten Sie eine Rückmeldung („Die Abfrage wurde erfolgreich ausgeführt“).
    • Bei Abfrage der Tabelle dbo.BaseEntities_AppConfigSet kann die Schema Version eingesehen werden
      Hinweis: Die Schema Version kann vom Screenshot abweichen.

      AppConfigSet: Schema Version

ScriptRunner

  1. Gehen Sie auf den ScriptRunner Server und öffnen die PowerShell (ISE) mit Administrationsrechten
  2. Führen Sie das Cmdlet Set-AsrSQLConnector mit folgenden Parametern aus: *On, *ConnectionString, *UserName, *Password (Clearpassword), *Restart
    • On: Aktiviert den Connector
    • ConnectionString: Verbindung zum SQL-Server
      Data Source = FQDN des SQL-Servers;
      Initial Catalog = Name der Datenbank (ScriptRunner);
      4A: Bei Windows integriertem Benutzer : Integrated Security = true (läuft im Kontext des angegebenen AD-Benutzers);
      4B: Bei lokalem SQL-Benutzer: Integrated Security=false (SQL-Benutzer wird im Connection String verwendet);
      Hinweis: Weitere Informationen zum Connection String finden sie in den Microsoft Docs.
    • UserName: Benutzername des hinterlegten Benutzers in der DB; DEVSTAR\ani
    • Password: Passwort des hinterlegten Benutzers in der DB
    • Restart-AsrService: Startet den SR Dienst neu
    • Hinweis: Sofern der Standardport (1433) in Ihrer Infrastruktur abweicht, muss dieser ebenfalls mit einem Komma getrennt, angegeben werden. (Beispiel: <FQDN-DB-Server>,<PORT>)
  3. Überprüfung der Konfiguration:
    • Führen Sie das Cmdlet Get-AsrSqlConnector aus, um zu überprüfen, ob der Connector angeschaltet ist.
    • Öffnen Sie die Windows Event Logs
    • Öffnen Sie die SR Admin App und navigieren Sie in den Abschnitt Settings. Die konfigurierte Verbindung zum SQL-Server wird hier gekennzeichnet:
      ScriptRunner

      Settings: Konfigurierte Verbindung zum SQL-Server

      Hinweis: Klicken Sie auf >SQL Report/Audit Database, klicken Sie in der unteren Navigationsleiste auf >View um den Connection String einzusehen.

Testen

  1. Öffnen Sie ScriptRunner und melden sich mit einem Benutzer, der von Ihnen hinterlegten Admingruppe, an.
    • Sie befinden sich im Dashboard.
  2. Wechseln Sie in den Abschnitt Actions.
  3. Klicken Sie auf die Action >Get Process HTML
    • Klicken Sie auf >Run
    • Führen Sie die Action aus
    • Bei erfolgreicher Ausführung erscheint neben der Action ein grüner Balken
  4. Wechseln Sie auf den SQL-Server
    • Öffnen Sie das Microsoft SQL Server Management Studio
    • Navigieren Sie in die Datenbank ScriptRunner
    • Navigieren Sie in Tabellen
    • Fragen Sie die Obersten 1000 Zeilen der Tabelle BaseEntities_JobControlSet ab
    • Unter Ergebnisse, kann die erfolgreich ausgeführte Action eingesehen werden

      PowerShell Report der Action in der SQL Datenbank

Update

Achtung! Bevor Sie das Update starten, stellen Sie sicher, dass sie ein aktuelles Backup der Datenbank haben.
Hinweis: Bei einem ScriptRunner Datenbankupdate, muss das dazugehörige Datenbankschema aktualisiert werden.

  1. Gehen Sie auf den ScriptRunner Server
    • Öffnen Sie den Windows Explorer und gehen zu C:\Program Files\ScriptRunner\Service\Support
    • Kopieren Sie das Script ExtDb_UpdateTables.sql
    • Verbinden Sie sich auf den SQL Server
    • Legen Sie das kopierte Script auf dem Server ab
  2. Öffnen Sie das SQL Server Management Studio
  3. Navigieren Sie in der DB Menüleiste auf Ordner öffnen
    Hinweis: Stellen Sie vor der Ausführung sicher, dass die korrekte Datenbank ausgewählt wurde

    Kontroller der Datenbank

    • Wählen Sie das kopierte Script ExtDb_UpdateTables.sql aus
    • Klicken Sie auf Öffnen

      Script öffnen: Update Tables

    • Klicken Sie auf Ausführen
    • In der Fußleiste des Management Studios erhalten Sie eine Rückmeldung („Die Abfrage wurde erfolgreich ausgeführt“).
  4. Bei Abfrage der Tabelle dbo.BaseEntities_AppConfigSet kann die Schema Version eingesehen werden
    Hinweis: Die Schema Version kann vom Screenshot abweichen.

    AppConfigSet: Schema Version

Änderung vorschlagen