Konfiguration¶

In diesem Kapitel geht es um die Konfiguration des Actions Servers. Wie alle unsere Produkte nutzt auch der Actions Server unser Konfigurationssystem. Im Kapitel Konfigurationssystem findest du alle Grundlagen dazu, wie die Konfigurationsdateien strukturiert sein müssen, wo die Anwendung sie sucht und viele weitere wichtige Begriffe und Themen.

Neben der Hauptkonfiguration im Application Modul benötigt der Server in der Regel auch die Konfiguration des SSL Modules für sichere Netzwerkverbindungen und die Konfiguration einer Log-Datei mit einem Log Modul. Details zu diesen beiden Modulen findest du in den Kapiteln Eigene SSL Zertifikate verwenden und Log-System.

Wenn du die Gruppen eines Benutzers auslesen möchtest, musst du die Erweiterung AdGroups aktivieren. Dazu erstellst du ein Konfigurationsmodul AdGroups. Alle Details dazu findest du im Kapitel Active Directory Gruppen.

Um unser Statistic System zur Auswertung der Benutzeraktionen zu nutzen, konfigurierst du das Modul StatisticSystem. Eine separate Dokumentation zu diesem System enthält alle Details zur Konfiguration.

Grundlegende Struktur¶

Das folgende Beispiel zeigt dir die grundlegende Struktur der Serverkonfiguration.

<?xml version="1.0" encoding="UTF-8" ?>
<Configuration
    version="1"
    xmlns="http://educateit.ch/software/BlueStone/Configuration/1">

    <Module name="Application">
        <!-- Die Hauptkonfiguration des Actions Servers -->
    </Module>

    <Module name="AdGroups">
        <!-- Die Konfiguration der AD Groups Erweiterung -->
    </Module>

    <Module name="StatisticSystem">
        <!-- Statistic System Konfiguration -->
    </Module>

    <Module name="SSL">
        <!-- SSL Profile -->
    </Module>

    <Module name="Log">
        <!-- Log Konfiguration -->
    </Module>

</Configuration>

Das Konfigurationsschema¶

Module

Application

Value

serverPort

Optional

Integer

Minimum value: 1024
Maximum value: 65564

Default Value:

12837

Value

sslProfile

String

Must not be empty.

Value

ignoreMissingSecret

Optional

Boolean

Default Value:

No

List

uiScriptDirectories

Optional

Value list definition

String

Must not be empty.
Must be an existing directory.

List

secrets

Complex list definition

Value

label

String

Must not be empty.

Value

key

String

Must not be empty.

Value

secret

Password

Must not be empty.

Value

authorizedNetworks

Optional

String

Value

writeStatisticIntoLog

Optional

Boolean

Default Value:

Yes

List

groupList

Complex list definition

Value

groupName

String

Must not be empty.

Value

startAsMember

Boolean

Must not be empty.

Value

includeUserNames

Optional

StringList

Value

includeUserGroups

Optional

StringList

Value

includeConnectionKeys

Optional

StringList

Value

excludeUserNames

Optional

StringList

Value

excludeUserGroups

Optional

StringList

Value

excludeConnectionKeys

Optional

StringList

List

actionList

Complex list definition

Value

actionName

String

Must not be empty.
Must match this regular expression: [-a-z0-9_.]+

Value

buttonLabel

String

Must not be empty.

Value

executeOnClient

Boolean

Value

program

String

Must not be empty.

Value

arguments

String

Value

programTimeout

Optional

String

Must match this regular expression: [1-9][0-9]{0,3}[smh]?

Default Value:

5m

Value

interface

Optional

String

Must not be empty.

Default Value:

none

Value

requiredGroups

StringList

Must not be empty.

Value

initialStateName

Optional

String

Must match this regular expression: [a-zA-Z0-9_]{1,64}
Minimum length: 1
Maximum length: 64

Default Value:

Unknown

List

stateRules

Optional

Complex list definition

Value

newState

String

Must match this regular expression: [a-zA-Z0-9_]{1,64}
Minimum length: 1
Maximum length: 64

Value

previousStates

StringList

Minimum Number of Elements: 1
Must match this regular expression: (?:!?[a-zA-Z0-9_]{1,64}|\*)

Value

event

String

Must be one of this: Output, Finished

Value

condition

String

Must not be empty.

Value

profileScript

Optional

String

Value

startScript

Optional

String

Value

sendStatisticEntry

Optional

Boolean

Default Value:

No

List

statisticEntryValues

Optional

Complex list definition

Value

name

String

Must be one of this: taskName, targetType, targetUserName, targetHost, targetDomain, targetValue, targetDetail

Value

contentType

Optional

String

Must be one of this: Text, Script

Default Value:

Text

Value

value

String

List

profileList

Complex list definition

Value

profileName

String

Must not be empty.

Value

windowTitle

String

Must not be empty.
Must match this regular expression: [^\p{Zl}\p{Zp}\pC]{1,120}

Value

description

String

Value

actions

StringList

Value

color

Optional

String

Must be one of this: default, white, yellow, orange, red, violet, blue, green

Default Value:

default

Value

autoClose

Optional

String

Must be one of this: default, long, hour, never

Default Value:

default

List

sectionList

Optional

Complex list definition

Value

title

String

Maximum length: 120
Must match this regular expression: [^\p{Zl}\p{Zp}\pC]{1,120}

Value

actions

StringList

Must not be empty.

Value

color

Optional

String

Must be one of this: default, white, yellow, orange, red, violet, blue, green

Default Value:

default

Der Wert `serverPort`¶

Mit dem Wert serverPort konfigurierst du den Port, an dem der Server auf neue Verbindungen von Clients wartet. Du musst denselben Port in der Konfiguration des Clients angeben. Die Portnummer ist ein positiver 16-Bit-Integer-Wert und darf nicht null sein. Dies begrenzt den Wert auf den Bereich von 1 bis 65565. Auf einigen Betriebssystemen benötigst du spezielle Berechtigungen, um Ports unter 1024 zu öffnen.

Standardmäßig verwendet das System die Portnummer 12837, die keine besondere Bedeutung hat und nicht in der IANA-Datenbank registriert ist. Du solltest deine Netzwerkkonfiguration auf mögliche Konflikte mit anderen Anwendungen überprüfen, bevor du diesen Port in einer produktiven Umgebung nutzt.

<Module name="Application">
    <Value name="serverPort">12837</Value>
    ...
</Module>

Der Wert `sslProfile`¶

Neu in Version 3.20.

Mit dem Wert sslProfile legst du das SSL-Profil fest, das zur Verbindung mit dem Actions Server verwendet wird. Dieses Profil muss im SSL Modul konfiguriert sein. Du kannst den speziellen Wert legacy verwenden, um die eingebauten älteren Zertifikate zu nutzen. Alle Details über die SSL Profile findest du im Kapitel Eigene SSL Zertifikate verwenden.

<Module name="Application">
    <Value name="serverPort">12837</Value>
    <Value name="sslProfile">server</Value>
    ...
</Module>

Der Wert `ignoreMissingSecret`¶

Neu in Version 3.21.

Mit dem Wert ignoreMissingSecret kannst du während einer Systemmigration ein fehlendes Authentifizierungsschlüsselpaar ignorieren. Setzt du diesen Wert auf Yes, gilt ein Client auch dann als authentifiziert, falls er kein Schlüsselpaar an den Server sendet.

Wird ein fehlendes Schlüsselpaar ignoriert, sind die Verbindungen nur durch die Zertifikate abgesichert. Du solltest das Actions System nicht lange in dieser Konfiguration betreiben. Lösche diesen Konfigurationswert schnellstmöglich nach der Migration, damit wieder der Standardwert No verwendet wird.

Selbst wenn du diesen Wert auf Yes gesetzt hast, werden Verbindungen mit falschen Schlüsselpaaren abgelehnt.

<Module name="Application">
    ...
    <Value name="ignoreMissingSecret">Yes</Value>
    ...
</Module>

Die Liste `uiScriptDirectories`¶

Neu in Version 3.21.

Mit der Liste uiScriptDirectories legst du die Verzeichnisse fest, in denen nach den Definitionen und Skripten für das Benutzerinterface gesucht wird. Jeder Eintrag in dieser Liste muss der absolute Pfad zu einem existierenden Verzeichnis sein.

Ein Skript oder die Definition eines Benutzerinterfaces, das du im Wert interface angibst (siehe Der Wert interface), wird in all diesen Verzeichnissen gesucht.

Wenn du deine Dateien wie in älteren Versionen in einem Unterverzeichnis des Programmverzeichnisses gespeichert hast, kannst du den Platzhalter ●applicationDirectory● des Konfigurationssystems verwenden, wie im folgenden Beispiel gezeigt.

<Module name="Application">
    ...
    <List name="uiScriptDirectories">
        <Value>●applicationDirectory●\ui_scripts</Value>
        <Value>\\example\actions\ui_scripts</Value>
    </List>
    ...
</Module>

Die Liste `secrets`¶

Neu in Version 3.21.

Mit der Liste secrets legst du fest, wer auf den Actions Server zugreifen kann. Dafür generierst du mit dem EducateIT Secret Generator Schlüsselpaare, die für den Zugriff auf eine Schnittstelle oder Funktion benötigt werden.

Das Schlüsselpaar wird mit dem Secret Generator erstellt. Weitere Informationen dazu findest du im Kapitel Das Secret System. Der Client ist dabei immer die Software, die auf die Daten zugreifen möchte, beispielsweise der Actions Client. Der Server ist die Software, die die Daten bereitstellt, also der Actions Server.

Erstelle für jede Benutzergruppe, die Aktionen auf dem Actions Server ausführt, ein eigenes Schlüsselpaar. Es ist sinnvoll, den Wert apiSecret auf der Client-Seite zusätzlich zu kodieren, da dieser Wert wie ein Passwort ist und daher entsprechend geschützt werden sollte. Siehe dazu Kapitel Kodieren von Passwörtern.

Zusätzlich zum Schlüsselpaar kannst du den Zugriff mit einer Netzwerkliste einschränken. Wenn du also weißt, dass ein Client sich immer aus dem Netzwerk 10.0.0.0/24 mit dem Server verbindet, kannst du diese Einschränkung mit dem Wert authorizedNetworks konfigurieren. Wir empfehlen, solche Einschränkungen zu definieren, wenn dies möglich ist.

Den Wert key kannst du zusätzlich mit includeConnectionKeys und excludeConnectionKeys verwenden, um Gruppen je nach Verbindung zu definieren.

Das folgende Beispiel zeigt, wie eine solche secrets Liste aussehen kann. Die dabei verwendeten Werte bei key und secret sind bewusst fiktive Werte und funktionieren nicht.

<Module name="Application">
    ...
    <List name="secrets">
        <ListEntry>
            <Value name="label">support-connection</Value>
            <Value name="key">[key]</Value>
            <Value name="secret">[secret]</Value>
            <Value name="authorizedNetworks">10.90.18.0/24</Value>
        </ListEntry>
        <ListEntry>
            <Value name="label">admin-connection</Value>
            <Value name="key">[key]</Value>
            <Value name="secret">[secret]</Value>
            <Value name="authorizedNetworks">10.70.24.0/24</Value>
        </ListEntry>
    </List>
    ...
</Module>

Der Actions Server hat keine zusätzlichen Werte ausser label, key, secret und authorizedNetworks. Die genaue Bedeutung dieser Werte wird im Kapitel Konfiguration erklärt.

Die Liste `groupList`¶

Die Liste groupList definiert eine Reihe von lokalen Gruppen, die dazu dienen, den Zugriff auf die verschiedenen Aktionen zu steuern. Lies den Abschnitt Zugriffsverwaltung, um das Zugriffskonzept zu verstehen, bevor du die folgenden Abschnitte liest.

Jeder Listeneintrag definiert eine lokale Gruppe und die Ein- und Ausschlussregeln dieser Gruppe.

<Module name="Application">
    ...
    <List name="groupList">
        <ListEntry>
            <Value name="groupName">educateit-employees</Value>
            <Value name="startAsMember">No</Value>
            <Value name="includeUserGroups">EducateIT</Value>
        </ListEntry>
        <ListEntry>
            <Value name="groupName">support</Value>
            <Value name="startAsMember">Yes</Value>
            <Value name="excludeUserNames">exampleUser1 exampleUser2</Value>
            <Value name="excludeUserGroups">adminGroup</Value>
        </ListEntry>
        <ListEntry>
            <Value name="groupName">admin</Value>
            <Value name="startAsMember">No</Value>
            <Value name="includeConnectionKeys">[key]</Value>
        </ListEntry>
    </List>
    ...
</Module>

Der Wert `groupName`¶

Mit dem Wert groupName legst du einen eindeutigen Bezeichner für die lokale Gruppe fest. Dieser Bezeichner wird im Aktions-Eintrag verwendet, um die entsprechende Aktion für den gegebenen Benutzer im Profil freizuschalten. Der Bezeichner darf nicht „any“ sein, zudem wird die Groß- und Kleinschreibung unterschieden.

<List name="groupList">
    <ListEntry>
        <Value name="groupName">educateit-employees</Value>
        <Value name="startAsMember">No</Value>
        <Value name="includeUserGroups">EducateIT</Value>
    </ListEntry>
    ...
</List>

Der Wert `startAsMember`¶

Der boolesche Wert startAsMember legt fest, ob ein Benutzer standardmäßig Mitglied dieser lokalen Gruppe ist oder nicht.

Ist der Wert No, gehört ein Benutzer standardmäßig nicht zur Gruppe. Ausnahmen sind Benutzer, die in includeUserNames aufgeführt sind, Benutzer, deren Gruppen in includeUserGroups aufgeführt sind, oder Benutzer, deren Verbindungsschlüssel in includeConnectionKeys aufgeführt ist.
Ist der Wert Yes, gehört ein Benutzer standardmäßig zur Gruppe. Ausnahmen sind Benutzer, die in excludeUserNames aufgeführt sind, Benutzer, deren Gruppen in excludeUserGroups aufgeführt sind, oder Benutzer, deren Verbindungsschlüssel in excludeConnectionKeys aufgeführt ist.

Die genaue Reihenfolge wie die include... und exclude... Werte angewendet werden findest du im Kapiel Zugriffsverwaltung.

<List name="groupList">
    <ListEntry>
        <Value name="groupName">educateit-employees</Value>
        <Value name="startAsMember">No</Value>
        <Value name="includeUserGroups">EducateIT</Value>
    </ListEntry>
    ...
</List>

Der Wert `includeUserNames`¶

Der Wert includeUserNames ist eine durch Leerzeichen getrennte Liste von Benutzernamen, die mit dem vom Client kommenden Benutzernamen abgeglichen werden. Wenn einer dieser Benutzernamen mit dem Benutzernamen vom Client übereinstimmt, wird der Benutzer Mitglied dieser lokalen Gruppe. Der Vergleich erfolgt unabhängig von Groß- und Kleinschreibung.

<List name="groupList">
    <ListEntry>
        <Value name="groupName">admins</Value>
        <Value name="startAsMember">No</Value>
        <Value name="includeUserGroups">Administrator</Value>
    </ListEntry>
    ...
</List>

Der Wert `includeUserGroups`¶

Der Wert includeUserGroups ist eine durch Leerzeichen getrennte Liste von Gruppennamen, die mit den Gruppennamen abgeglichen werden, die von einem Zugriffs-Plugin kommen. Wenn eine der vom Zugriffs-Plugin zurückgegebenen Gruppen mit einer der Gruppen in dieser Liste übereinstimmt, wird der Benutzer Mitglied dieser Gruppe. Der Vergleich erfolgt unabhängig von Groß- und Kleinschreibung.

<List name="groupList">
    <ListEntry>
        <Value name="groupName">educateit-employees</Value>
        <Value name="startAsMember">No</Value>
        <Value name="includeUserGroups">EducateIT</Value>
    </ListEntry>
    ...
</List>

Der Wert `includeConnectionKeys`¶

Neu in Version 3.21.

Der Wert includeConnectionKeys ist eine Liste von Verbindungsschlüsseln, die in diese Gruppe aufgenommen werden sollen. Wenn der für die Verbindung verwendete Schlüssel in dieser Liste enthalten ist, wird der Benutzer Mitglied dieser Gruppe.

<List name="groupList">
    <ListEntry>
        <Value name="groupName">support</Value>
        <Value name="startAsMember">No</Value>
        <Value name="includeConnectionKeys">
            jgvuv!4,OZH83@ZdTsDviQ_aNzYXm;8MzqY0v//J4i9^RI^Z11@-ZQ7E7-NY{7RA
        </Value>
    </ListEntry>
    ...
</List>

Der Wert `excludeUserNames`¶

Der Wert excludeUserNames funktioniert ähnlich wie includeUserNames, aber wenn ein Benutzername übereinstimmt, wird der Benutzer aus dieser Gruppe ausgeschlossen. Die Ausschlussparameter haben immer Vorrang vor den Einbeziehungsparametern.

<List name="groupList">
    <ListEntry>
        <Value name="groupName">not-admins</Value>
        <Value name="startAsMember">Yes</Value>
        <Value name="excludeUserNames">Administrator</Value>
    </ListEntry>
    ...
</List>

Der Wert `excludeUserGroups`¶

Der Wert excludeUserGroups funktioniert ähnlich wie includeUserGroups, aber wenn eine Gruppe übereinstimmt, wird der Benutzer aus dieser Gruppe ausgeschlossen. Die Ausschlussparameter haben immer Vorrang vor den Einbeziehungsparametern.

<List name="groupList">
    <ListEntry>
        <Value name="groupName">extern-workers</Value>
        <Value name="startAsMember">Yes</Value>
        <Value name="excludeUserGroups">EducateIT</Value>
    </ListEntry>
    ...
</List>

Der Wert `excludeConnectionKeys`¶

Neu in Version 3.21.

Der Wert excludeConnectionKeys ist eine Liste von Verbindungsschlüsseln, die aus dieser Gruppe ausgeschlossen werden sollen. Wenn der für die Verbindung verwendete Schlüssel in dieser Liste enthalten ist, wird der Benutzer aus dieser Gruppe ausgeschlossen.

<List name="groupList">
    <ListEntry>
        <Value name="groupName">api-access</Value>
        <Value name="startAsMember">Yes</Value>
        <Value name="excludeConnectionKeys">
            jgvuv!4,OZH83@ZdTsDviQ_aNzYXm;8MzqY0v//J4i9^RI^Z11@-ZQ7E7-NY{7RA
        </Value>
    </ListEntry>
    ...
</List>

Die Liste `actionList`¶

Mit der Liste actionList legst du die Aktionen fest, die im Client angezeigt werden. Jeder Eintrag in dieser Liste definiert eine Aktion, die als Schaltfläche im Aktionsfenster dargestellt werden kann. Wichtig ist der Bezeichner, den du mit dem Wert actionName für jeden Eintrag festlegst. Mit diesem Bezeichner verweist du auf die Aktion aus einem Profil heraus.

Das folgende Beispiel zeigt eine Übersicht der gesamten Struktur. Die meisten Werte sind optional und können weggelassen werden:

Die komplette Struktur eines Aktions-Eintrags.¶

<List name="actions">
    <ListEntry>
        <Value name="actionName">...</Value>
        <Value name="buttonLabel">...</Value>
        <Value name="executeOnClient">...</Value>
        <Value name="program">...</Value>
        <Value name="programTimeout">...</Value>
        <Value name="arguments">...</Value>
        <Value name="interface">...</Value>
        <Value name="requiredGroups">...</Value>
        <Value name="initialStateName">...</Value>
        <List name="stateRules">
            <ListEntry>
                <Value name="newState">...</Value>
                <Value name="previousStates">...</Value>
                <Value name="event">...</Value>
                <Value name="condition">...</Value>
            </ListEntry>
            ...
        </List>
        <Value name="profileScript"><![CDATA[
            // script
        ]]></Value>
        <Value name="startScript"><![CDATA[
            // script
        ]]></Value>
        <Value name="sendStatisticEntry">...</Value>
        <List name="statisticEntryValues">
            <ListEntry>
                <Value name="name">...</Value>
                <Value name="contentType">...</Value>
                <Value name="value">...</Value>
            </ListEntry>
            ...
        </List>
    </ListEntry>
    ...
</List>

Ein minimaler Eintrag könnte folgendermaßen aussehen:

Ein minimaler Aktions-Eintrag, der den VNC-Viewer lokal öffnet.¶

<List name="actions">
    ...
    <ListEntry>
        <Value name="actionName">vnc</Value>
        <Value name="buttonLabel">VNC Thin Client</Value>
        <Value name="executeOnClient">Yes</Value>
        <Value name="program">vncviewer.exe</Value>
        <Value name="arguments">{arg:clientname}</Value>
        <Value name="interface">none</Value>
        <Value name="requiredGroups">any</Value>
        <Value name="initialStateName">Success</Value>
    </ListEntry>
    ...
</List>

Der Wert `actionName`¶

Mit dem Wert actionName definierst du einen eindeutigen Bezeichner für die Aktion. Dieser Bezeichner muss für die gesamte Konfiguration einzigartig sein. Es sollten nur Buchstaben und Zahlen verwendet werden, insbesondere sollten Leerzeichen im Namen vermieden werden. Andernfalls kannst du nicht von dem Profil auf diese Aktion verweisen.

<List name="actions">
    <ListEntry>
        <Value name="actionName">vnc</Value>
        <Value name="buttonLabel">VNC Thin Client</Value>
        <Value name="executeOnClient">Yes</Value>
        <Value name="program">vncviewer.exe</Value>
        <Value name="arguments">{arg:clientname}</Value>
        <Value name="interface">none</Value>
        <Value name="requiredGroups">any</Value>
        <Value name="initialStateName">Success</Value>
    </ListEntry>
    ...
</List>

Der Wert `buttonLabel`¶

Mit dem Wert buttonLabel setzt du den Text der auf der Schaltfläche im Client-Fenster angezeigt wird. Du kannst jedes Zeichen aus dem Unicode-Set verwenden, ausgenommen Steuerzeichen wie Zeilenumbruch.

../../_images/client-small.jpg — Wie die Aktionsschaltflächen im Client angezeigt werden.¶

In der Illustration oben, siehst du wie der Text auf der Schaltfläche angezeigt wird (markierung C).

Die Größe der Schaltfläche passt sich automatisch der Länge des Textes an. Versuche aber den Text so kurz wie möglich zu halten, da der Text sonst möglicherweise auf einem kleinen Bildschirm angeschnitten wird.

<List name="actions">
    <ListEntry>
        <Value name="actionName">vnc</Value>
        <Value name="buttonLabel">VNC Thin Client</Value>
        <Value name="executeOnClient">Yes</Value>
        <Value name="program">vncviewer.exe</Value>
        <Value name="arguments">{arg:clientname}</Value>
        <Value name="interface">none</Value>
        <Value name="requiredGroups">any</Value>
        <Value name="initialStateName">Success</Value>
    </ListEntry>
    ...
</List>

Der Wert `executeOnClient`¶

Mit dem Wert executeOnClient legst du fest, ob das Programm auf der Client- oder Serverseite ausgeführt wird. Der Wert Yes konfiguriert die Ausführung auf der Clientseite, der Wert No die Ausführung auf der Serverseite.

../../_images/program-execution-context.jpg

Ein Programm, das auf der Clientseite ausgeführt wird, wird mit denselben Berechtigungen ausgeführt wie der Client. Normalerweise sind dies die Berechtigungen des Benutzers, der den Client gestartet hat. Das auszuführende Programm muss auf jedem Client zugänglich sein, auf dem der Actions Client läuft. Es kann sich um eine Konsolenanwendung oder ein Programm mit einer Benutzeroberfläche handeln. Beachte, dass das Actions Client Fenster offen bleibt, bis das Programm beendet wurde.

Wenn du dich dafür entscheidest, das Programm auf der Serverseite auszuführen, wird es mit den Berechtigungen des Servers ausgeführt. Das Programm muss vom Actions Server aus zugänglich sein. Es ist nicht möglich, Programme auszuführen, die eine Benutzeroberfläche auf der Serverseite anzeigen.

<List name="actions">
    <ListEntry>
        <Value name="actionName">vnc</Value>
        <Value name="buttonLabel">VNC Thin Client</Value>
        <Value name="executeOnClient">Yes</Value>
        <Value name="program">vncviewer.exe</Value>
        <Value name="arguments">{arg:clientname}</Value>
        <Value name="interface">none</Value>
        <Value name="requiredGroups">any</Value>
        <Value name="initialStateName">Success</Value>
    </ListEntry>
    ...
</List>

Der Wert `program`¶

Mit dem Wert program gibst du den Namen und optional den Pfad zur ausführbaren Datei an. Wenn die ausführbare Datei in einem der Pfade in der PATH-Umgebungsvariable platziert ist, dann reicht der Name der ausführbaren Datei aus. Andernfalls musst du den absoluten Pfad angeben.

Du kannst in diesem Wert Platzhalter verwenden. Siehe Kapitel Platzhalter für Details über Platzhalter und wie man sie verwendet.

<List name="actions">
    <ListEntry>
        <Value name="actionName">vnc</Value>
        <Value name="buttonLabel">VNC Thin Client</Value>
        <Value name="executeOnClient">Yes</Value>
        <Value name="program">vncviewer.exe</Value>
        <Value name="arguments">{arg:clientname}</Value>
        <Value name="interface">none</Value>
        <Value name="requiredGroups">any</Value>
        <Value name="initialStateName">Success</Value>
    </ListEntry>
    ...
</List>

Der Wert `arguments`¶

Mit dem Wert arguments legst du die Argumente fest, die an das ausgeführte Programm übergeben werden sollen. Du kannst in diesem Wert Platzhalter verwenden. Siehe Kapitel Platzhalter für Details über Platzhalter und wie man sie verwendet.

Die Argumente werden an Leerzeichen getrennt. Du kannst doppelte Anführungszeichen verwenden, um Teile einzuschließen, die Leerzeichen enthalten können, die nicht getrennt werden sollen. Die doppelten Anführungszeichen werden für die endgültige Argumentliste entfernt. Siehe Nutzung von Anführungszeichen in Argumenten für Details.

<List name="actions">
    <ListEntry>
        <Value name="actionName">vnc</Value>
        <Value name="buttonLabel">VNC Thin Client</Value>
        <Value name="executeOnClient">Yes</Value>
        <Value name="program">vncviewer.exe</Value>
        <Value name="arguments">{arg:clientname}</Value>
        <Value name="interface">none</Value>
        <Value name="requiredGroups">any</Value>
        <Value name="initialStateName">Success</Value>
    </ListEntry>
    ...
</List>

Der Wert `programTimeout`¶

Der optionale Wert programTimeout ermöglicht es dir, ein Zeitlimit für das laufende Programm festzulegen. Sollte das Programm länger als die festgelegte Zeit in Betrieb sein, wird es automatisch gestoppt.

Es können Zahlen im Bereich von 1 bis 9999 verwendet werden. Lässt du ein Suffix aus, wird der Wert in Sekunden interpretiert. Benutze das Suffix „s“ für Sekunden, „m“ für Minuten und „h“ für Stunden.

<List name="actions">
    <ListEntry>
        <Value name="actionName">vnc</Value>
        <Value name="buttonLabel">VNC Thin Client</Value>
        <Value name="executeOnClient">Yes</Value>
        <Value name="program">vncviewer.exe</Value>
        <Value name="arguments">{arg:clientname}</Value>
        <Value name="programTimeout">5m</Value>
        <Value name="interface">none</Value>
        <Value name="requiredGroups">any</Value>
        <Value name="initialStateName">Success</Value>
    </ListEntry>
    ...
</List>

Im obigen Codeausschnitt wird zum Beispiel der programTimeout für den VNC Thin Client auf 5 Minuten gesetzt.

Der Wert `interface`¶

Mit dem Wert interface bestimmst du die Art der Rückmeldung, die dem Benutzer präsentiert wird. Die gebräuchlichsten Optionen sind none, was bedeutet, dass dem Benutzer kein Feedback angezeigt wird, und console, welche ein Konsolenfenster öffnet und die Ausgabe des Befehls anzeigt.

Es ist auch möglich, dem Benutzer eine interaktive Schnittstelle zu präsentieren, über die er zusätzliche Informationen eingeben oder detailliertere Statusinformationen zum Fortschritt des Befehls erhalten kann. Alle Einzelheiten zu diesem Wert findest du unter Schnittstellen.

<List name="actions">
    <ListEntry>
        <Value name="actionName">vnc</Value>
        <Value name="buttonLabel">VNC Thin Client</Value>
        <Value name="executeOnClient">Yes</Value>
        <Value name="program">vncviewer.exe</Value>
        <Value name="arguments">{arg:clientname}</Value>
        <Value name="programTimeout">5m</Value>
        <Value name="interface">none</Value>
        <Value name="requiredGroups">any</Value>
        <Value name="initialStateName">Success</Value>
    </ListEntry>
    ...
</List>

Im Beispiel oben wird kein Feedback angezeigt, da der VNC Thin Client ein eigenes Interface hat.

Der Wert `requiredGroups`¶

Mit dem Wert requiredGroups konfigurierst du eine durch Leerzeichen getrennte Liste von lokalen Gruppenkennungen. Ist der Benutzer Mitglied einer oder mehrerer aufgeführter lokaler Gruppen, wird die Aktion aktiviert und dem Benutzer angezeigt.

Es gibt eine spezielle Gruppe namens „any“, die auf jeden Benutzer zutrifft, auch wenn dieser keiner lokalen Gruppe angehört. Wenn du die spezielle Gruppe „any“ verwendest, muss dies die einzige Gruppe in diesem Wert sein.

<List name="actions">
    <ListEntry>
        <Value name="actionName">vnc</Value>
        <Value name="buttonLabel">VNC Thin Client</Value>
        <Value name="executeOnClient">Yes</Value>
        <Value name="program">vncviewer.exe</Value>
        <Value name="arguments">{arg:clientname}</Value>
        <Value name="programTimeout">5m</Value>
        <Value name="interface">none</Value>
        <Value name="requiredGroups">any</Value>
        <Value name="initialStateName">Success</Value>
    </ListEntry>
    ...
</List>

Im obigen Beispiel ist die Aktion für alle Benutzer sichtbar, da „any“ als Wert für requiredGroups eingestellt ist.

Der Wert `initialStateName`¶

Mit initialStateName legst du den Anfangszustand für den Prozess fest. Ein Zustandsname muss mit einem Buchstaben beginnen und kann Buchstaben, Zahlen und den Unterstrich enthalten. Die Länge eines Zustandsnamens ist auf 64 Zeichen beschränkt.

Aus Gründen der Rückwärtskompatibilität ist dieser Konfigurationswert optional. Wenn du diesen Wert weglässt, wird er auf „Unknown“ gesetzt.

Weitere Informationen zu den Prozesszuständen findest du im Kapitel Prozesszustände.

<List name="actions">
    <ListEntry>
        <Value name="actionName">vnc</Value>
        <Value name="buttonLabel">VNC Thin Client</Value>
        <Value name="executeOnClient">Yes</Value>
        <Value name="program">vncviewer.exe</Value>
        <Value name="arguments">{arg:clientname}</Value>
        <Value name="programTimeout">5m</Value>
        <Value name="interface">none</Value>
        <Value name="requiredGroups">any</Value>
        <Value name="initialStateName">Success</Value>
    </ListEntry>
    ...
</List>

Im obigen Beispiel wird der anfängliche Zustand der Aktion auf „Success“ gesetzt.

Die Liste `stateRules`¶

In dieser Liste können beliebig viele Zustandsregeln angegeben werden. Diese Regeln werden in der konfigurierten Reihenfolge verarbeitet.

<List name="actions">
    ...
    <ListEntry>
        <Value name="actionName">update_server</Value>
        <Value name="buttonLabel">Update Server</Value>
        <Value name="executeOnClient">false</Value>
        <Value name="program">python3.exe</Value>
        <Value name="arguments">\\example\scripts\manage.py update {arg:server}</Value>
        <Value name="interface">console</Value>
        <Value name="requiredGroups">admin-group power-user</Value>
        <Value name="initialStateName">Success</Value>
        <List name="stateRules">
            <ListEntry>
                <Value name="newState">Error</Value>
                <Value name="previousStates">Success</Value>
                <Value name="event">Output</Value>
                <Value name="condition">/Error/.test(line)</Value>
            </ListEntry>
            <ListEntry>
                <Value name="newState">Crashed</Value>
                <Value name="previousStates">*</Value>
                <Value name="event">Finished</Value>
                <Value name="condition">finishReason == FinishReason.Crash</Value>
            </ListEntry>
        </List>
    </ListEntry>
</List>

In dem Beispiel oben wird der Python Script manage.py ausgeführt. Initial ist der Status Success. Tritt in einer Zeile der Ausgabe der Text Error auf, dann wechselt der Status von Success zu Error. Crasht der Prozess, wechselt der Status in jedem Fall in den Crashed Zustand.

Der Wert `newState`¶

Mit dem Wert newState legst du den neuen Zustand fest, wenn die Regel zutrifft. Der Name muss mit einem Buchstaben beginnen und kann Buchstaben, Zahlen und den Unterstrich enthalten. Die Länge eines Zustandsnamens ist auf 64 Zeichen beschränkt.

<List name="actions">
    ...
    <ListEntry>
        ...
        <List name="stateRules">
            <ListEntry>
                <Value name="newState">Error</Value>
                ...
            </ListEntry>
            <ListEntry>
                <Value name="newState">Crashed</Value>
                ...
            </ListEntry>
        </List>
    </ListEntry>
</List>

Im obigen Beispiel werden zwei Zustände, Error und Crashed, verwendet, in die der Prozess wechseln kann, wenn bestimmte Regeln zutreffen.

Der Wert `previousStates`¶

Mit dem Wert previousStates konfigurierst du eine durch Leerzeichen getrennte Liste von vorherigen Zustandsnamen. Die Regel wird nur geprüft, wenn der aktuelle Zustandsname mit einem Zustandsnamen in dieser Liste übereinstimmt.

Du kannst auch den * Zeichen als Platzhalter verwenden, der jeden Zustand entspricht.

Wenn du einem Zustandsnamen das ! Zeichen voranstellst, wird die Regel nur geprüft, wenn der aktuelle Zustand nicht der angegebene ist. Dies hat Vorrang vor den gegebenen Zuständen und dem * Platzhalter.

Zum Beispiel würden die Werte !foo * so interpretiert: Überprüfe diese Regel, es sei denn, der aktuelle Zustand ist foo.

<List name="actions">
    ...
    <ListEntry>
        ...
        <List name="stateRules">
            <ListEntry>
                ...
                <Value name="previousStates">Success</Value>
                ...
            </ListEntry>
            <ListEntry>
                ...
                <Value name="previousStates">*</Value>
                ...
            </ListEntry>
        </List>
    </ListEntry>
</List>

Im obigen Beispiel wird die erste Regel nur geprüft, wenn der aktuelle Zustand „Success“ ist. Die zweite Regel wird immer geprüft, da der Platzhalter * verwendet wird.

Der Wert `event`¶

Mit dem Wert event legst du das Ereignis fest, bei dem die Bedingung geprüft wird. Es gibt nur zwei Ereignisse: Output und Finished. Wenn du Output angibst, wird die Regel für jede Ausgabezeile des laufenden Prozesses geprüft. Im Falle von Finished wird die Regel geprüft, wenn der Prozess endet (erfolgreich oder nicht).

<List name="actions">
    ...
    <ListEntry>
        ...
        <List name="stateRules">
            <ListEntry>
                ...
                <Value name="event">Output</Value>
                ...
            </ListEntry>
            <ListEntry>
                ...
                <Value name="event">Finished</Value>
                ...
            </ListEntry>
        </List>
    </ListEntry>
</List>

Im obigen Beispiel wird die erste Regel bei jeder Ausgabezeile geprüft, während die zweite Regel nur geprüft wird, wenn der Prozess endet.

Der Wert `condition`¶

Mit dem Wert condition legst du eine ECMA-Script-Ausdruck fest, der in true oder false ausgewertet wird. Es gibt drei globale Variablen: line, die im Falle des Ereignisses „Output“ eine Zeile der Prozessausgabe enthält, exitCode, die den Exit-Code des Prozesses enthält, und finishReason im Falle des Ereignisses „Finished“.

Die Bedingung ist ein ECMA-Script-Ausdruck, der einen nativen boolean-Wert zurückgeben muss. Wenn der Ausdruck true zurückgibt, wird der neue Zustand als aktueller Zustand verwendet. Wenn der Ausdruck false zurückgibt, wird die Regel übersprungen.

Es gibt drei globale Variablen, auf die du in deinem Ausdruck zugreifen kannst. Die folgende Tabelle erklärt die Bedeutung jeder Variablen:

Globale Variablen, die in einer Bedingung zugänglich sind¶
Variable	Beschreibung
`line`	Diese Variable enthält eine Ausgabenzeile des Prozesses im Ereignis „Output“.
`exitCode`	Im Ereignis „Finished“ enthält diese Variable den Exit-Code des Prozesses.
`finishReason`	Im Ereignis „Finished“ enthält diese Variable einen String mit dem Grund, warum der Prozess beendet wurde. Es gibt vordefinierte Strings im globalen Objekt „FinishReason“, die du zum Testen gegen diesen Wert verwenden kannst.

Um die Variable finishReason zu testen, gibt es ein globales Objekt „FinishReason“, das einen String für jeden Grund zum Testen enthält.

Die im Objekt `FinishReason` definierten Konstanten¶
Konstante	Beschreibung
`FinishReason.Success`	Nach erfolgreichem Ende des Prozesses.
`FinishReason.Crash`	Der Prozess ist abgestürzt.
`FinishReason.FailedToStart`	Der Prozess konnte nicht gestartet werden.

<List name="actions">
    ...
    <ListEntry>
        ...
        <List name="stateRules">
            <ListEntry>
                ...
                <Value name="condition">/Error/.test(line)</Value>
            </ListEntry>
            <ListEntry>
                ...
                <Value name="condition">finishReason == FinishReason.Crash</Value>
            </ListEntry>
        </List>
    </ListEntry>
</List>

Im Beispiel oben wird in der ersten Regel ein Regulärer Ausdruck auf die Variable line angewendet, um zu testen ob der Text Error in der Ausgabezeile vorhanden ist. In der zweiten Regel wird die Variable finishReason getestet, ob das gestartete Programm mit einem Crash beendet wurde.

Der Wert `profileScript`¶

Mit dem optionalen Wert profileScript definierst du ein ECMA-Script, das ausgeführt wird, bevor die Aktion zum aktuellen Profil hinzugefügt wird. In diesem Skript kannst du Parameter der Aktion selbst ändern, hast aber nur Lesezugriff auf die Argumente, die dem Client übergeben wurden.

Dieses Skript muss sehr klein sein und schnell ausgeführt werden, da es sonst den Server blockiert und zu Verzögerungen führt.

Es gibt eine Reihe von globalen Objekten, auf die du aus dem Skript zugreifen kannst. Die folgende Tabelle gibt Details dazu. Alle Parameter des Aktionsobjekts sind schreibbar und ändern das Verhalten der Aktion.

Globale Objekte, die vom Profilskript zugänglich sind¶
Variable	Beschreibung
`args`	Dieses Objekt enthält alle Parameter, die dem Client übergeben wurden. Änderungen an dem Parameter haben keinen Einfluss (nur lesbar).
`action.buttonLabel`	Das Label auf dem Button, das in der Client-Schnittstelle angezeigt wird.
`action.executeOnClient`	Ein boolescher Wert, ob das Programm auf der Clientseite ausgeführt werden soll. `true` bedeutet Ausführung auf der Clientseite, `false` bedeutet Ausführung auf der Serverseite.
`action.program`	Der Pfad zum Programm, das ausgeführt wird, wenn der Button angeklickt wird.
`action.arguments`	Die Programmargumente mit Platzhaltern.

Im folgenden Beispiel ändert sich der Text auf der Schaltfläche abhängig vom Argument server, das dem Client übergeben wird.

<List name="actions">
    ...
    <ListEntry>
        <Value name="actionName">merge-server</Value>
        <Value name="buttonLabel">Merge Server</Value>
        <Value name="executeOnClient">No</Value>
        <Value name="program">python3.exe</Value>
        <Value name="arguments">\\example\scripts\manage.py merge {arg:server}</Value>
        <Value name="interface">console</Value>
        <Value name="requiredGroups">any</Value>
        <Value name="profileScript"><![CDATA[
            action.buttonLabel = 'Merge Server ' + args.server;
        ]]></Value>
    </ListEntry>
    ...
</List>

Der Wert `startScript`¶

Mit dem optionalen Wert startScript kannst du ein ECMA-Script definieren, das unmittelbar vor der Ausführung der Aktion und dem Start des Programms ausgeführt wird. In diesem Skript hast du Schreibzugriff auf die Programmargumente, die über das globale Objekt args zugänglich sind. Es gibt eine Reihe von globalen Objekten, auf die du aus dem Skript zugreifen kannst. Siehe die folgende Tabelle für Details:

Globale Objekte, die vom Skript zugänglich sind¶
Variable	Beschreibung
`args`	Dieses Objekt enthält alle Parameter die dem Client übergeben wurden. Du kannst die Werte ändern oder neue hinzufügen. Die Platzhalter in den Werten von Programm und Argumenten werden nach erfolgreicher Ausführung des Skripts ersetzt.
`uiValues`	Dieses Objekt enthält alle Werte aus einer interaktiven Benutzeroberfläche. Änderungen an diesen Werten haben keinen Einfluss (nur lesbar).
`action.buttonLabel`	Das Label auf dem Button, das in der Client-Schnittstelle angezeigt wird (nur lesbar).
`action.executeOnClient`	Ein boolescher Wert, ob das Programm auf der Clientseite ausgeführt werden soll. `true` bedeutet Ausführung auf der Clientseite, `false` bedeutet Ausführung auf der Serverseite (nur lesbar).
`action.program`	Der Pfad zum Programm, das ausgeführt wird, wenn der Button angeklickt wird (nur lesbar).
`action.arguments`	Die Programmargumente mit Platzhaltern (nur lesbar).

Das Skript muss sehr klein sein und schnell ausgeführt werden, sonst blockiert es den Server und verursacht Verzögerungen.

Im folgenden Beispiel wird ein Präfix zum Argument server hinzugefügt. Dieses Argument wird als Platzhalter im Befehl der Aktion verwendet.

<List name="actions">
    ...
    <ListEntry>
        <Value name="actionName">merge-server</Value>
        <Value name="buttonLabel">Merge Server</Value>
        <Value name="executeOnClient">No</Value>
        <Value name="program">python3.exe</Value>
        <Value name="arguments">\\example\scripts\manage.py merge {arg:server}</Value>
        <Value name="interface">console</Value>
        <Value name="requiredGroups">any</Value>
        <Value name="startScript"><![CDATA[
            args.server = 'abc' + args.server;
        ]]></Value>
    </ListEntry>
    ...
</List>

Werte für das Statistiksystem¶

Es gibt eine Reihe von Konfigurationswerten, die sich auf das Statistiksystem beziehen. Diese sind nur relevant, wenn du das Statistiksystem aktivierst, wie das in der dazugehörigen Dokumentation erklärt wird.

Das Actions-System verfügt neben der neuen Schnittstelle noch über ein altes Verfahren um Statistiken zu erfassen. Dabei werden spezielle Einträge in die Log-Datei geschrieben. Ein spezielles Werkzeug extrahiert diese dann aus dem Log und bietet einige Analysen zu diesen Daten an. Dieses alte Verfahren solltest du aber nicht mehr verwenden.

Der Wert `writeStatisticIntoLog`¶

Mit dem optionalen Wert writeStatisticIntoLog` kannst du steuern, ob Statistikeinträge in die Log-Datei geschrieben werden sollen, wie dies in älteren Versionen unserer Software üblich war. Wenn du diesen Wert weglässt, wird der Standardwert auf Yes gesetzt, was das Schreiben dieser Einträge in die Log-Datei ermöglicht.

Setze diesen Wert auf No, wenn du das neue Statistiksystem verwendest, um zu verhindern, dass die veralteten Statistikeinträge in die Log-Datei geschrieben werden.

<Module name="Application">
    ...
    <Value name="writeStatisticIntoLog">No</Value>
    ...
</Module>

Der Wert `sendStatisticEntry`¶

Mit dem Wert sendStatisticEntry steuerst du ob für die gegebene Aktion ein Statistikeintrag gesendet werden soll. Wenn du diesen Wert auf Yes setzt, wird für die Aktion ein Statistikeintrag gesendet. In diesem Fall musst du die Werte, die an den Server gesendet werden, mithilfe einer Liste statisticEntryValues definieren.

<List name="actions">
    ...
    <ListEntry>
        <Value name="actionName">run-task</Value>
        ...
        <Value name="sendStatisticEntry">Yes</Value>
        <List name="statisticEntryValues">
            <ListEntry>
                <Value name="name">taskName</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">Test</Value>
            </ListEntry>
            <ListEntry>
                <Value name="name">targetType</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">profile</Value>
            </ListEntry>
            <ListEntry>
                <Value name="name">targetUserName</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">User{arg:userName}</Value>
            </ListEntry>
        </List>
    </ListEntry>
    ...
</List>

Die Liste `statisticEntryValues`¶

In der Liste statisticEntryValues legst du die Werte fest, die an den Statistikserver gesendet werden. Für jeden zu erfassenden Statistikwert musst du einen Eintrag in dieser Liste erstellen.

Jeder Eintrag besteht aus drei Elementen: name, contentType und value. Mit name bestimmst du den Namen des Statistikwerts. contentType bestimmt, ob der Wert ein Text oder ein Skript ist. Zuletzt definierst du mit value den tatsächlichen Inhalt des Statistikwerts. Je nachdem, was du für contentType festgelegt hast, gibst du hier entweder den statischen Text ein - optional mit Platzhaltern - oder ein kleines ECMA-Skript, das den Wert berechnet.

Die genauen Details zu diesen Werten findest du in den folgenden Abschnitten.

<List name="actions">
    ...
    <ListEntry>
        <Value name="actionName">run-task</Value>
        ...
        <Value name="sendStatisticEntry">Yes</Value>
        <List name="statisticEntryValues">
            <ListEntry>
                <Value name="name">taskName</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">Test</Value>
            </ListEntry>
            <ListEntry>
                <Value name="name">targetType</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">profile</Value>
            </ListEntry>
            <ListEntry>
                <Value name="name">targetUserName</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">User{arg:userName}</Value>
            </ListEntry>
        </List>
    </ListEntry>
    ...
</List>

Der Wert `name`¶

Mit dem Wert name bestimmst du den Namen des Statistikwerts. Beachte dabei, dass der Name Groß- und Kleinschreibung beachtet und jeder Name nur einmal verwendet werden darf. Die folgenden Wertnamen sind möglich:

Die Namen der Werte für den Statistik-Eintrag¶
Variable	Beschreibung
`taskName` (erforderlich)	Ein Bezeichner der durchgeführten Aktion. Für eine korrekte Auswertung der Aktionen, muss dieser Bezeichner korrekt definiert werden. Die Dokumentation des Statistik Servers enthält Tabellen mit üblichen Aktionen und deren Bezeichner.
`targetType` (erforderlich)	Der Typ des Ziels des durchgeführten Aktion. Übliche Werte sind beispielsweise: `no_target`, `process`, `session`, `profile`, `user`, `computer`, `user_and_computer`, `repository_channel` und `user_message`. Je nach Typ den du hier definierst, werden bestimmte Angaben in den anderen `target...` Feldern erwartet. Die Dokumentation des Statistik Servers enthält Tabellen mit den definierten Typen und den dazu benötigten Werten.
`targetUserName`	In diesem Feld übergibst du den Benutzernamen, falls der gewählte Typ diesen erwartet.
`targetHost`	In diesem Feld übergibst du den Hostnamen oder die IP-Adresse, falls der gewählte Typ diese erwartet.
`targetDomain`	In diesem Feld übergibst du die Domäne des Benutzers oder des Hosts, falls der gewählte Typ diese erwartet.
`targetValue`	In diesem Feld übergibst du einen bestimmten Wert, abhängig vom konfigurierten Typ.
`targetDetail`	In diesem Feld übergibst du weitere Details zu den Informationen in den anderen Feldern, abhängig vom konfigurierten Typ.

Die Bedeutung dieser Werte findest du in der Dokumentation zum Statistiksystems.

<List name="actions">
    ...
    <ListEntry>
        <Value name="actionName">run-task</Value>
        ...
        <Value name="sendStatisticEntry">Yes</Value>
        <List name="statisticEntryValues">
            <ListEntry>
                <Value name="name">taskName</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">Test</Value>
            </ListEntry>
            <ListEntry>
                <Value name="name">targetType</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">profile</Value>
            </ListEntry>
            <ListEntry>
                <Value name="name">targetUserName</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">User{arg:userName}</Value>
            </ListEntry>
        </List>
    </ListEntry>
    ...
</List>

Der Wert `contentType`¶

Mit dem Wert contentType legst du das Format des Inhalts des Wertes fest. Dabei gibt es zwei Möglichkeiten:

Text: Hierbei handelt es sich um statischen Text. Du kannst auch Platzhalter verwenden, die dann durch entsprechende Werte ersetzt werden.
Script: Bei dieser Option definierst du ein kleines ECMA-Skript, das den tatsächlichen Wert berechnet.

Das gewählte Format wirkt sich darauf aus, wie der Inhalt in der Konfiguration value angegeben wird.

<List name="actions">
    ...
    <ListEntry>
        <Value name="actionName">run-task</Value>
        ...
        <Value name="sendStatisticEntry">Yes</Value>
        <List name="statisticEntryValues">
            <ListEntry>
                <Value name="name">taskName</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">Test</Value>
            </ListEntry>
            <ListEntry>
                <Value name="name">targetType</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">profile</Value>
            </ListEntry>
            <ListEntry>
                <Value name="name">targetUserName</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">User{arg:userName}</Value>
            </ListEntry>
            <ListEntry>
                <Value name="name">targetDetail</Value>
                <Value name="contentType">Script</Value>
                <Value name="value">'Used server argument: "' + args.server + '"'</Value>
            </ListEntry>
        </List>
    </ListEntry>
    ...
</List>

Der Wert `value`¶

Mit value definierst du den eigentlichen Inhalt des Statistikwerts, der an den Server gesendet wird. Der Inhalt, den du hier angibst, hängt von dem in contentType festgelegten Format ab.

Wenn contentType als Text konfiguriert ist wird dieses Feld als statischen Text interpretiert. Du kannst auch Platzhalter verwenden, um Text aus Argumenten, Benutzeroberflächeneingaben und Umgebungsvariablen in die Felder einzufügen. Siehe dazu den Eintrag targetUserName im Beispiel für die Verwendung von Platzhaltern. Weitere Details zu Platzhaltern findest du im Kapitel Platzhalter.

Falls contentType auf Script gesetzt ist, konfigurierst du hier ein kleines ECMA-Skript, das einen String für den Wert zurückgibt. Dabei hast du ähnlich wie beim Wert profileScript Lesezugriff auf das Objekt args.

<List name="actions">
    ...
    <ListEntry>
        <Value name="actionName">run-task</Value>
        ...
        <Value name="sendStatisticEntry">Yes</Value>
        <List name="statisticEntryValues">
            <ListEntry>
                <Value name="name">taskName</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">Test</Value>
            </ListEntry>
            <ListEntry>
                <Value name="name">targetType</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">profile</Value>
            </ListEntry>
            <ListEntry>
                <Value name="name">targetUserName</Value>
                <Value name="contentType">Text</Value>
                <Value name="value">User{arg:userName}</Value>
            </ListEntry>
            <ListEntry>
                <Value name="name">targetDetail</Value>
                <Value name="contentType">Script</Value>
                <Value name="value">'Used server argument: "' + args.server + '"'</Value>
            </ListEntry>
        </List>
    </ListEntry>
    ...
</List>

Die Liste `profileList`¶

Mit der Liste profileList definierst du verschiedene Profile welche im Client angezeigt werden. Jedes Profil zeigt dem Benutzer ein Fenster mit einem Titel, einer Beschreibung und einer Auswahl an Aktionen. Die Aktionen können wiederum in einzelne Abschnitte gegliedert werden.

Das folgende Beispiel zeigt die vollständige Struktur eines Profils. Viele der Werte sind optional, siehe die folgenden Abschnitte für Details.

<Module name="Application">
    ...
    <List name="profileList">
        <ListEntry>
            <Value name="profileName">...</Value>
            <Value name="windowTitle">...</Value>
            <Value name="description">...</Value>
            <Value name="actions">...</Value>
            <Value name="color">...</Value>
            <Value name="autoClose">...</Value>
            <List name="sectionList">
                <ListEntry>
                    <Value name="title">...</Value>
                    <Value name="actions">...</Value>
                    <Value name="color">...</Value>
                </ListEntry>
                ...
            </List>
        </ListEntry>
        ...
    </List>
    ...
</Module>

Der Wert `profileName`¶

Mit profileName legst du den eindeutigen Bezeichner des Profils fest. Du solltest nur Buchstaben und Zahlen, aber keine Leerzeichen verwenden. Es ist zudem ratsam, diesen Bezeichner kurz zu halten.

Dieser Name wird mit dem Parameter --profile=(name) im Client verwendet, um das Profil auszuwählen.

<List name="profileList">
    <ListEntry>
        <Value name="profileName">session</Value>
        <Value name="windowTitle">Session Aktionen</Value>
        <Value name="description">Wähle einen der Befehle aus, um diese Sitzung zu bearbeiten oder zu nutzen.</Value>
        <Value name="actions">vnc logoff shadow</Value>
    </ListEntry>
    ...
</List>

Der Wert `windowTitle`¶

Mit windowTitle definierst du den Text, der im Fenstertitel des Client Fensters angezeigt wird. Siehe A in der folgenden Abbildung, wo der Titel im Client-Fenster dargestellt wird.

<List name="profileList">
    <ListEntry>
        <Value name="profileName">session</Value>
        <Value name="windowTitle">Session Aktionen</Value>
        <Value name="description">Wähle einen der Befehle aus, um diese Sitzung zu bearbeiten oder zu nutzen.</Value>
        <Value name="actions">vnc logoff shadow</Value>
    </ListEntry>
    ...
</List>

Der Wert `description`¶

Mit description legst du die Beschreibung fest, die im oberen Bereich des angezeigten Fensters dargestellt wird. Siehe B in der Abbildung oben, wo die Beschreibung im Client-Fenster platziert ist. Du kannst einfache HTML-Tags in der Beschreibung verwenden, um Titel, Listen und fett oder kursiv geschriebene Texte zu erstellen. Die folgende Tabelle enthält eine Auswahl von HTML Tags welche für die Formatierung unterstützt werden.

Tag	Beschreibung	Details
`a`	Link	Unterstützt das `href` und `name` Attribut.
`address`	Adresse
`b`/`strong`	Fetter Text
`big`	Grösserer Text
`blockquote`	Eingerückter Abschnitt
`br`	Zeilenumbruch
`center`	Zentrierter Abschnitt
`div`	Dokument Block	Definiert einen Block im Dokument. Akzeptiert die typischen Blockattribute.
`dl`/`dt`/`dd`	Definitionsliste
`font`	Definiert den Font	Unterstützt die Attribute: `size`, `face`, und `color`.
`h1`-`h6`	Überschrift
`hr`	Horizontale Linie	Unterstützt das `width` Attribut.
`i`/`em` `cite` `var`/`dfn`	Kursive Schrift
`kbd`	Benutzereingabe
`nobr`	Text ohne Zeilenumbruch
`ol`/`li`	Nummerierte Liste
`p`	Abschnitt
`pre`	Formatierter Text
`s`	Durchgestrichener Text
`small`	Kleinere Schrift
`span`	Formatierter Bereich
`sub`	Subscript
`sup`	Superscript
`table` `tr`/`td`/`th` `tbody`/`thead` `tfoot`	Tabelle	Unterstützt die folgenden Attribute: `border`, `bgcolor`, `cellspacing`, `cellpadding`, `width`, und `height`.
`tt`/`code` `samp`	Blockschrift
`u`	Unterstrichener Text
`ul`	Unsortierte Liste

Du kannst die Beschreibung auch in mehrere Zeilen mit Überschriften und Absatz-Tags strukturieren. Bilder sind auch möglich, allerdings musst du einen absoluten Pfad (nutze eine file:/// URL) zu dem Bild angeben, der auf jedem Computer, der den Client startet, zugänglich ist.

Bitte beachte, dass du alle HTML-Tags in der XML-Konfigurationsdatei codieren musst. Eine einfache Lösung ist die Verwendung eines <![CDATA[ Blocks. Siehe das folgende Beispiel, um zu verstehen, wie du eine Beschreibung definierst, die HTML-Formatierung verwendet.

<List name="profileList">
    <ListEntry>
        <Value name="profileName">destruct</Value>
        <Value name="windowTitle">Destruktive Aktionen</Value>
        <Value name="description"><![CDATA[
            <h2>Destruktive Aktionen</h2>
            <p><font color="red">Achtung!</font> Die folgenden Aktionen löschen dauerhaft Ressourcen.
                Diese Aktionen können nicht rückgängig gemacht werden. Nutze sie mit Vorsicht.</p>
        ]]></Value>
        <Value name="actions">delete-server remove-server shutdown-server</Value>
    </ListEntry>
    ...
</List>

Der Wert `actions`¶

Mit actions legst du eine durch Leerzeichen getrennte Liste der Aktions-Identifikatoren fest, die im Fenster angezeigt werden sollen. Diese Liste bestimmt, welche Aktionen angezeigt werden und in welcher Reihenfolge. Die Schaltflächen der Aktionen werden immer in der Reihenfolge der Identifikatoren angezeigt, von links nach rechts, von oben nach unten in zwei oder mehr Spalten.

Dieser Wert definiert die Aktionen, die direkt unter der Beschreibung im Fenster angezeigt werden, außerhalb jeder Sektion.

Beachte bitte, dass eine Aktion im Fenster verborgen bleibt, wenn ein Benutzer keinen Zugriff darauf hat.

<List name="profileList">
    <ListEntry>
        <Value name="profileName">session</Value>
        <Value name="windowTitle">Session Aktionen</Value>
        <Value name="description">Wähle einen der Befehle aus, um diese Sitzung zu bearbeiten oder zu nutzen.</Value>
        <Value name="actions">vnc logoff shadow</Value>
    </ListEntry>
    ...
</List>

Der Wert `color`¶

Neu in Version 3.20.

Mit dem optionalen Wert color kannst du eine Hintergrundfarbe für das Client-Fenster festlegen. Dabei kannst du einen der folgenden Werte verwenden:

default
red
orange
yellow
green
blue
violet

Wenn du diesen Wert weglässt, wird default verwendet.

Die folgende Abbildung zeigt, wie die verschiedenen Hintergrundfarben im Client-Fenster aussehen. Je nach Betriebssystem können die Farben leicht variieren.

../../_images/background-colors.jpg — Die verschiedenen Hintergrundfarben des Client-Fensters.¶

<List name="profileList">
    <ListEntry>
        <Value name="profileName">session</Value>
        <Value name="windowTitle">Session Aktionen</Value>
        <Value name="description">Wähle einen der Befehle aus, um diese Sitzung zu bearbeiten oder zu nutzen.</Value>
        <Value name="actions">vnc logoff shadow</Value>
        <Value name="color">red</Value>
    </ListEntry>
    ...
</List>

Der Wert `autoClose`¶

Neu in Version 3.20.

Mit dem Wert autoClose legst du fest, nach welcher Zeit der Inaktivität das Client-Fenster automatisch geschlossen wird. Du hast dabei die Wahl zwischen folgenden Werten:

Die verschiedenen Werte von `autoClose`¶
Konstante	Beschreibung
`default`	Schließt das Fenster nach einer Minute Inaktivität.
`long`	Schließt das Fenster nach zehn Minuten Inaktivität.
`hour`	Schließt das Fenster nach einer Stunde Inaktivität.
`never`	Schließt das Fenster nie automatisch.

Wir raten von der Einstellung never ab, da das Aktionsfenster oft vom Benutzer vergessen wird. Dabei kann es passieren, dass eine Aktion auf das falsche Objekt angewendet wird.

<List name="profileList">
    <ListEntry>
        <Value name="profileName">session</Value>
        <Value name="windowTitle">Session Aktionen</Value>
        <Value name="description">Wähle einen der Befehle aus, um diese Sitzung zu bearbeiten oder zu nutzen.</Value>
        <Value name="actions">vnc logoff shadow</Value>
        <Value name="autoClose">long</Value>
    </ListEntry>
    ...
</List>

Die Liste `sectionList`¶

Neu in Version 3.20.

Mit der optionalen Liste sectionList fügst du eine oder mehrere Abschnitte zu dem Client-Fenster hinzu. Jeder Abschnitt hat dabei einen Titel, und darunter einen oder mehrere Schaltflächen mit Aktionen. Zudem kannst du einem Abschnitt eine individuelle Farbe geben, um in hervorzuheben.

Hat ein Benutzer keinen Zugriff auf die Aktionen eines Abschnitts, dann wird dieser Abschnitt weggelassen.

../../_images/client-large.jpg — Ein Client-Fenster mit mehreren Abschnitten¶

<List name="profileList">
    <ListEntry>
        <Value name="profileName">user</Value>
        <Value name="windowTitle">Benutzer Aktionen</Value>
        <Value name="description"></Value>
        <Value name="actions"></Value>
        <List name="sectionList">
            <ListEntry>
                <Value name="title">Hauptaktionen</Value>
                <Value name="actions">logoff-user create-user cleanup-profile</Value>
            </ListEntry>
            <ListEntry>
                <Value name="title">Destruktive Aktionen</Value>
                <Value name="color">red</Value>
                <Value name="actions">delete-profile</Value>
            </ListEntry>
        </Value>
    </ListEntry>
    ...
</List>

Der Wert `title`¶

Mit dem Wert title definierst du den Titel eines Abschnitts. In der Abbildung oben siehst du den Titel mit D makiert. Für den Titel sind alle Zeichen, ausser Kontrollzeichen und Zeilenumbrüche erlaubt.

<List name="profileList">
    <ListEntry>
        <Value name="profileName">user</Value>
        <Value name="windowTitle">Benutzer Aktionen</Value>
        <Value name="description"></Value>
        <Value name="actions"></Value>
        <List name="sectionList">
            <ListEntry>
                <Value name="title">Hauptaktionen</Value>
                <Value name="actions">logoff-user create-user cleanup-profile</Value>
            </ListEntry>
            <ListEntry>
                <Value name="title">Destruktive Aktionen</Value>
                <Value name="color">red</Value>
                <Value name="actions">delete-profile</Value>
            </ListEntry>
        </Value>
    </ListEntry>
    ...
</List>

Der Wert `actions`¶

Mit dem Wert actions definierst welche Aktionen in dem Abschnitt angezeigt werden. Dabei gibst du eine durch Leerzeichen getrennte Liste der Aktions-Identifikatoren an. Die Aktionen werden in der von dir Konfigurierten Reihenfolge angezeigt.

Beachte bitte, dass eine Aktion im Fenster verborgen bleibt, wenn ein Benutzer keinen Zugriff darauf hat. Sind in einem Abschnitt für den Benutzer gar keine Aktionen zugänglich, wird der ganze Abschnitt ausgeblendet.

<List name="profileList">
    <ListEntry>
        <Value name="profileName">user</Value>
        <Value name="windowTitle">Benutzer Aktionen</Value>
        <Value name="description"></Value>
        <Value name="actions"></Value>
        <List name="sectionList">
            <ListEntry>
                <Value name="title">Hauptaktionen</Value>
                <Value name="actions">logoff-user create-user cleanup-profile</Value>
            </ListEntry>
            <ListEntry>
                <Value name="title">Destruktive Aktionen</Value>
                <Value name="color">red</Value>
                <Value name="actions">delete-profile</Value>
            </ListEntry>
        </Value>
    </ListEntry>
    ...
</List>

Der Wert `color`¶

Mit dem optionalen Wert color kannst du einen Abschnitt einfärben, damit er für die Benutzer leicht zu erkennen ist. Dabei hast du folgende Werte zur Auswahl:

default
red
orange
yellow
green
blue
violet

Wenn du diesen Wert weglässt, wird default verwendet. In diesem Fall wird der Abschnitt nicht eingefärbt und übernimmt die Hintergrundfarbe.

In def folgenden Abbildung siehst du alle Abschnittsfarben:

Beispielkonfiguration¶

<?xml version="1.0" encoding="UTF-8" ?>
<Configuration
    version="1"
    xmlns="http://educateit.ch/software/BlueStone/Configuration/1">

    <Module name="Application">

        <Value name="serverPort">12837</Value>
        <Value name="sslProfile">server</Value>

        <List name="secrets">
            <ListEntry>
                <Value name="label">Example</Value>
                <Value name="key">[key]</Value>
                <Value name="secret">[secret]</Value>
            </ListEntry>
        </List>

        <List name="uiScriptDirectories">
            <Value>●applicationDirectory●\uiscripts</Value>
        </List>

        <List name="groupList">
            <ListEntry>
                <Value name="groupName">group1</Value>
                <Value name="startAsMember">true</Value>
                <Value name="includeUserNames">[user names]</Value>
                <Value name="includeUserGroups">[user groups]</Value>
                <Value name="includeConnectionKeys">[connection keys]</Value>
                <Value name="excludeUserNames">[user names]</Value>
                <Value name="excludeUserGroups">[user groups]</Value>
                <Value name="excludeConnectionKeys">[connection keys]</Value>
            </ListEntry>
            <!-- ... -->
        </List>

        <List name="actionList">
            <ListEntry>
                <Value name="actionName">example</Value>
                <Value name="buttonLabel">Example</Value>
                <Value name="executeOnClient">true</Value>
                <Value name="program">Logoff.exe</Value>
                <Value name="arguments">/Server:{arg:servername}</Value>
                <Value name="interface">none</Value>
                <Value name="requiredGroups">any</Value>
            </ListEntry>
            <!-- ... -->
        </List>

        <List name="profileList">
            <ListEntry>
                <Value name="profileName">example</Value>
                <Value name="windowTitle">Example Actions</Value>
                <Value name="description">This is a short description in front of the action buttons.</Value>
                <Value name="actions">example</Value>
                <List name="sections">
                    <ListEntry>
                        <Value name="title">Section</Value>
                        <Value name="actions">example</Value>
                    </ListEntry>
                </List>
            </ListEntry>
            <!-- ... -->
        </List>
    </Module>

    <Module name="SSL">
        <List name="profiles">
            <ListEntry>
                <Value name="identifier">server</Value>
                <Value name="key">[key path to PEM file]</Value>
                <Value name="caCertificates">[ca path to PEM file]</Value>
                <Value name="localCertificateChain">[path to certificate PEM file]</Value>
                <Value name="peerVerificationEnabled">Yes</Value>
            </ListEntry>
        </List>
    </Module>

    <Module name="AdGroups">
        <List name="server">
            <ListEntry>
                <Value name="domainList">*</Value>
                <Value name="host">[AD Server]</Value>
                <Value name="username">[AD User]</Value>
                <Value name="password">[AD PW]</Value>
            </ListEntry>
        </List>
    </Module>

    <Module name="Log">
        <List name="FileWriter">
            <ListEntry>
                <Value name="LogFilePath">c:/Logs/Actions_Server.log</Value>
            </ListEntry>
        </List>
    </Module>

</Configuration>

Konfiguration¶

Grundlegende Struktur¶

Das Konfigurationsschema¶

Der Wert serverPort¶

Der Wert sslProfile¶

Der Wert ignoreMissingSecret¶

Die Liste uiScriptDirectories¶

Die Liste secrets¶

Die Liste groupList¶

Der Wert groupName¶

Der Wert startAsMember¶

Der Wert includeUserNames¶

Der Wert includeUserGroups¶

Der Wert includeConnectionKeys¶

Der Wert excludeUserNames¶

Der Wert excludeUserGroups¶

Der Wert excludeConnectionKeys¶

Die Liste actionList¶

Der Wert actionName¶

Der Wert buttonLabel¶

Der Wert executeOnClient¶

Der Wert program¶

Der Wert arguments¶

Der Wert programTimeout¶

Der Wert interface¶

Der Wert requiredGroups¶

Der Wert initialStateName¶

Die Liste stateRules¶

Der Wert newState¶

Der Wert previousStates¶

Der Wert event¶

Der Wert condition¶

Der Wert profileScript¶

Der Wert startScript¶

Werte für das Statistiksystem¶

Der Wert writeStatisticIntoLog¶

Der Wert sendStatisticEntry¶

Die Liste statisticEntryValues¶

Der Wert name¶

Der Wert contentType¶

Der Wert value¶

Die Liste profileList¶

Der Wert profileName¶

Der Wert windowTitle¶

Der Wert description¶

Der Wert actions¶

Der Wert color¶

Der Wert autoClose¶

Die Liste sectionList¶

Der Wert title¶

Der Wert actions¶

Der Wert color¶

Beispielkonfiguration¶

Der Wert `serverPort`¶

Der Wert `sslProfile`¶

Der Wert `ignoreMissingSecret`¶

Die Liste `uiScriptDirectories`¶

Die Liste `secrets`¶

Die Liste `groupList`¶

Der Wert `groupName`¶

Der Wert `startAsMember`¶

Der Wert `includeUserNames`¶

Der Wert `includeUserGroups`¶

Der Wert `includeConnectionKeys`¶

Der Wert `excludeUserNames`¶

Der Wert `excludeUserGroups`¶

Der Wert `excludeConnectionKeys`¶

Die Liste `actionList`¶

Der Wert `actionName`¶

Der Wert `buttonLabel`¶

Der Wert `executeOnClient`¶

Der Wert `program`¶

Der Wert `arguments`¶

Der Wert `programTimeout`¶

Der Wert `interface`¶

Der Wert `requiredGroups`¶

Der Wert `initialStateName`¶

Die Liste `stateRules`¶

Der Wert `newState`¶

Der Wert `previousStates`¶

Der Wert `event`¶

Der Wert `condition`¶

Der Wert `profileScript`¶

Der Wert `startScript`¶

Der Wert `writeStatisticIntoLog`¶

Der Wert `sendStatisticEntry`¶

Die Liste `statisticEntryValues`¶

Der Wert `name`¶

Der Wert `contentType`¶

Der Wert `value`¶

Die Liste `profileList`¶

Der Wert `profileName`¶

Der Wert `windowTitle`¶

Der Wert `description`¶

Der Wert `actions`¶

Der Wert `color`¶

Der Wert `autoClose`¶

Die Liste `sectionList`¶

Der Wert `title`¶

Der Wert `actions`¶

Der Wert `color`¶