Konfigurieren des 5Minds Portals

In dieser Anleitung werden Ihnen die verschiedenen Möglichkeiten für die Konfiguration des 5Minds Portals vorgestellt.

Das 5Minds Portal wird als Docker-Image zur Verfügung gestellt und muss wie in der 5Minds-Portal-Installationsanleitung beschrieben installiert und gestartet werden.

Das 5Minds Portal startet mit vorkonfigurierten Standard-Werten. Wenn Sie eigens entwickelte Dialoge anstelle der Standarddialoge in Ihrem Prozess nutzen wollen, müssen Sie diese konfigurieren. Nachfolgend werden Ihnen die verschiedenen Konfigurationsmöglichkeiten und Konfigurationsparameter aufgezeigt.

Beispiel Konfiguration

Eine fertige Konfiguration kann z.B. folgendermaßen aussehen:

{
  "applicationBaseUrl": "http://localhost:13560",
  "port": 13560,
  "engineUrl": "http://localhost:10560",
  "useAuthority": false,
  "authorityConfiguration": {
    "clientId": "portal",
    "scope": "test_resource"
  },
  "customForms": {
    "test-3": {
      "url": "https://httpbin.org/post",
      "mode": "post"
    }
  },
  "processModels": {
    "include": ["Process_1", "Process_2"],
    "exclude": ["Process_3", "Process_4"],
    "settings": {
      "Process_1": {
        "title": "My customized Process title",
        "body": "A description for my process",
        "startButtonTitles": {
          "StartEvent_1": "Open dialog"
        },
        "groupId": "important"
      }
    }
  },
  "startDialogs": {
    "test-dialog-1": {
      "title": "Test dialog",
      "body": "Use this to test stuff",
      "url": "http://localhost:3000",
      "startButtonTitle": "Open dialog",
      "requiredClaims": ["Administrator"],
      "groupId": "test-group"
    }
  },
  "theme": "/path/to/theme.css",
  "assets": "/path/to/assets/folder",
  "translationFolder": "/path/to/translation/folder",
  "startablesOrder": ["test-dialog-1", "Process_3"],
  "startableGroups": [
    {
      "id": "important",
      "title": "Important processes"
    },
    {
      "id": "test-group",
      "title": "Test group"
    }
  ],
  "languages": {
    "de": "Deutsch",
    "en": "English",
    "fr": "Français"
  },
  "logging": {
    "minLogLevel": "debug"
  }
}

Konfigurationsmöglichkeiten

Sie können Ihr 5Minds Portal auf drei verschiedene Arten Konfigurieren, oder die Standardwerte verwenden. Daraus ergeben sich vier verschiedene Konfigurationsquellen, die nacheinander eingelesen werden. Eine später eingelesene Konfigurationquelle überschreibt die Vorhergehenden.

Standardwerte
JSON-Datei
Umgebungsvariablen
Kommandozeilenargumente

Konfiguration mit Hilfe einer Konfigurationsdatei

Sie können die im Abschnitt Konfigurationseigenschaften aufgeführten Konfigurationseigenschaften über eine JSON-Konfigurationsdatei in das 5Minds Portal laden. Dafür müssen Sie diese wie in der Installationsanleitung beschrieben an das 5Minds Portal übergeben.

Konfiguration mit Hilfe von Umgebungsvariablen

Sie können die im Abschnitt Konfigurationseigenschaften aufgeführten Konfigurationseigenschaften auch über Umgebungsvariablen definieren. Dabei werden die untergeordneten Objekte mit Unterstrichen (__) verbunden.

docker run --name 5MindsPortal --publish 13560:13560 5minds/portal --env applicationBaseUrl=http://localhost:13560 --env authorityConfiguration__clientId=portal --env customForms__<Ihr-CustomForm-Name>=http://localhost:3000

Wichtig: Wenn der CustomForm Name aus anderen Zeichen als Buchstaben, Zahlen und Unterstrichen besteht, können Fehler auftreten. Nutzen Sie in diesem Fall das Kommandozeilenargument --custom-forms und geben Sie als Wert ein stringifiziertes JSON Objekt als Konfiguration an.

Beispiel: --custom-forms='{"/^(?!confirm$).+$/": "http://localhost:3000"}'

Konfiguration mit Hilfe von Kommandozeilenargumenten

Alternativ können Sie die Konfigurationsparameter als Kommandozeilenargumente übergeben. Dabei werden die untergeordneten Objekte mit einem Doppelpunkt (:) verbunden.

docker run --name 5MindsPortal --publish 13560:13560 5minds/portal --applicationBaseUrl http://localhost:13560 --authorityConfiguration:clientId portal --customForms:<Ihr-CustomForm-Name> http://localhost:3000

Konfigurationseigenschaften

In den folgenden Tabellen werden Ihnen die Eigenschaften beschrieben, die Sie für das 5Minds Portal konfigurieren können.

Eigenschaft	Typ	Beschreibung	Erforderlich	Standardwert
applicationBaseUrl	string	Die URL, unter der das 5Minds Portal erreichbar sein soll, siehe auch Konfiguration Anwendungs URL	nein
assets	string	Pfad zu einem Ordner mit für das Theming relevanten Assets. Siehe auch Konfiguration der Assets	nein	`frontend/build/assets`
authorityConfiguration	authorityConfiguration	Enthält die Konfiguration der Verbindung zur 5Minds Authority	nein
customForms	customForms	Enthält eine Liste der Custom Forms	nein
customTranslations	customTranslations	Erlaubt das Überschreiben oder Hinzufügen einzelner Übersetzungen	nein	`{}`
engineUrl	string	Die URL, unter der die 5Minds Engine erreichbar ist, siehe auch Konfiguration der 5Minds Engine	nein	`http://localhost:10560`
extensionsDir	string	Pfad zu einem Ordner, der Extensions enthält, die vom Portal geladen werden sollen	nein	`$HOME/.atlas/portal/extensions`
favicon	string	Relative oder absolute URL zu einem Bild, welches als Favicon verwendet werden soll. Ein leerer String blendet das Favicon aus.	nein	`/assets/favicon.png`
languages	languages	Ein Objekt mit Key-Value Paaren (Key = CountryCode, Value = Sprache)	nein
logging	logging	Konfiguration des Loggers	nein	`{ minLogLevel: 'debug' }`
logo	string	Relative oder absolute URL zu einem Bild, welches als Logo für die Navbar verwendet werden soll. Ein leerer String blendet das Logo aus.	nein	`/assets/logo.png`
port	number	Der Port, unter welchem das 5Minds Portal erreichbar sein soll, siehe auch Konfiguration Anwendungs URL	nein
processModels	processModels	Enthält eine Liste der anzuzeigenden Prozesse. Standardmäßig werden alle auf der 5Minds Engine enthaltenen Prozesse angezeigt	nein
startableGroups	startableGroup[]	Eine Liste von Gruppen für Prozesmodelle und Startdialoge	nein
startablesOrder	string[]	Eine Liste von Prozessmodell- und Startdialog-IDs, welche die Sortierung der Prozessmodelle und Startdialoge bestimmt	nein
startDialogs	startDialogs	Enthält eine Liste der Start Dialoge	nein
theme	string	Pfad zur Theme-CSS-Datei, siehe auch Konfiguration des Designs	nein	`frontend/src/theme/default-theme.css`
translationFolder	string	Pfad zum Ordner, der die Übersetzungen enthält, siehe auch Konfiguration der Übersetzung	nein	`/frontend/public/translation`
useAuthority	boolean	Aktiviert die Authentifizierung mit Hilfe der 5Minds Authority, siehe auch Konfiguration der Authentifizierung	nein	false

Konfiguration Anwendungs URL

Sie können dem 5Minds Portal eine andere URL zuweisen. Dies kann für Sie interessant sein, wenn Sie einen anderen Port oder TLS-Verschlüsselung verwenden wollen.

Dazu gibt es zwei Möglichkeiten:

Per applicationBaseUrl

Wenn die Hostadresse den Port bereits beinhaltet, kann die Konfiguration ausschließlich über applicationBaseUrl erfolgen.

z.B.:

{
  "applicationBaseUrl": "http://localhost:12345"
}

Per applicationBaseUrl + port

Wenn die Hostadresse keinen Port beinhaltet, kann die Konfiguration über applicationBaseUrl und port erfolgen.

Der Port musss nur angegeben werden, wenn nicht der default Port des Portals verwendet werden soll.

z.B.:

{
  "applicationBaseUrl": "http://my-customized-portal.de",
  "port": 23123
}

Konfiguration der 5Minds Engine

Das 5Minds Portal erwartet standardmäßig eine erreichbare 5Minds Engine auf dem Port 10560 derselben Maschine. Die 5Minds Engine startet im Docker Container standardmäßig auf Port 10560. Sollte Ihre 5Minds Engine über eine andere Adresse erreichbar sein, können Sie die Adresse unter engineUrl angeben.

Konfiguration der Authentifizierung

Für die Benutzerauthentifizierung verwendet das 5Minds Portal dieselbe 5Minds Authority, die auch die 5Minds Engine benutzt. Entsprechend wird die Adresse der 5Minds Authority über die 5Minds Engine ermittelt. Um die Authentifizierung zu aktivieren, müssen Sie den Parameter useAuthority auf true setzen.

authorityConfiguration

Wenn Sie in Ihrer 5Minds Authority die Methode Client Authentication konfiguriert haben, können Sie unter dem Abschnitt authorityConfiguration die dafür notwendige clientId und die relevanten scopes eintragen.

Eigenschaft	Typ	Beschreibung	Erforderlich	Standardwert
clientId	string	Id unter der sich das 5Minds Portal bei der 5Minds Authority identifiziert	ja
clientSecret	string	Das Secret für den Client Credentials Flow	nein
grantType	string	Gibt an, welcher Authentication Flow genutzt werden soll. (implicit oder client_credentials)	nein	implicit
responseType	string	Response Typen, welche das 5Minds Portal von der Authority benötigt	nein	id_token token
scope	string	Scopes, welche das 5Minds Portal von der Authority benötigt	nein	openid profile email

processModels

Im Konfigurationsabschnitt processModels können Sie festlegen, welche auf der 5Minds Engine vorhandenen Prozesse im 5Minds Portal angezeigt werden sollen. Dies kann über einen "include", oder einen "exclude" Mechanismus erfolgen.

Zusätzlich ist es möglich für jeden Prozess individuelle Darstellungsoptionen festzulegen.

Eigenschaft	Typ	Beschreibung	Erforderlich
include	string[]	Eine Liste der Ids aller Prozesse, die im 5Minds Portal angezeigt werden sollen	nein
exclude	string[]	Eine Liste der Ids aller Prozesse, die im 5Minds Portal nicht angezeigt werden sollen	nein
settings	processModels.settings	Erlaubt es für jedes Prozessmodell individuelle Darstellungsoptionen zu konfigurieren	nein

Wenn sowohl include, als auch exclude konfiguriert wurden, dann werden nur die Prozessmodelle angezeigt, welche die Schnittmenge aus beiden Settings bilden.

Beispiel:

{
  "processModels": {
    "include": ["Process_1", "Process_2"],
    "exclude": ["Process_2", "Process_3"]
  }
}

Mit dieser Konfiguration würde ausschließlich der Prozess Process_1 im 5Minds Portal dargestellt werden.

processModels.settings

Über den settings Abschnitt können Sie die Bezeichnung der Prozesse, deren Beschreibung und die Beschriftung der Start-Buttons anpassen. Standardmäßig wird für die Anzeige als Prozessbezeichnung der Name des Prozesses aus dem BPMN-Diagramm verwendet. Der Text des Start-Buttons wird standardmäßig mit dem Namen des Start-Events belegt.

Dabei wird jede Konfiguration eines Prozesses in einem Objekt gespeichert, dessen Key der ID des Prozesses entspricht.

Folgende Einstellungen können für jeden Prozess vorgenommen werden:

Eigenschaft	Typ	Beschreibung	Erforderlich
title	string	Der Name unter welchem der Prozess angezeigt werden soll.	nein
body	string	Beschreibungstext des Prozesses	nein
startButtonTitles	object	Eine Sammlung von Key-Value Paaren, welche jeweils einer Start Event ID einen Anzeigetext zuweisen	nein
groupId	string	Die ID der Gruppe, der der Prozess zugordnet werden soll	nein

Beispielkonfiguration für einen Prozess mit ID Process_1, der über ein Start Event mit ID StartEvent_1 verfügt:

{
  "processModels": {
    "settings": {
      "Process_1": {
        "title": "My customized Process title",
        "body": "A description for my process",
        "startButtonTitles": {
          "StartEvent_1": "Start my Process"
        }
      }
    }
  }
}

customForms

Der Konfigurationsabschnitt customForms ist für die Registrierung einer oder mehrerer Custom Forms verantwortlich. In der customForms kann eine beliebige Anzahl von Custom Forms angeben werden.

Eigenschaft	Typ	Beschreibung	Erforderlich	Standardwert
Liste von customForm	customForm bzw. string	Bezeichnung der Custom Form als Identifier	nein

customForm

Eine Custom Form wird in dieser Liste aus der Zeichenkette customFormId und einem nachfolgenden Datenobjekt zusammengesetzt. Innerhalb des Datenobjekts wird die url der Custom Form und der Aufrufmodus angegeben. Der Aufrufmodus darf die Werte get, post, oder default (entspricht get) annehmen.

Eigenschaft	Typ	Beschreibung	Erforderlich	Standardwert
url	string	URL unter der die Custom Form erreichbar ist.	ja
mode	string	Modus in dem die Custom Form aufgerufen wird. Die möglichen Werte sind: `get`, `post`, `default` (entspricht get)	nein	default

Wenn Sie den Standardwert des Aufrufmodus nicht ändern wollen, können Sie die verkürzte Schreibweise bestehend aus dem Namen der Custom Form und der URL verwenden.

startDialogs

Sie können Start Dialoge nutzen, um vor dem Starten eines Prozesses einen benutzerdefinierten Dialog anzuzeigen. Die benutzerdefinierten Dialoge können auch dazu verwendet werden, mehrere Prozesse gleichzeitig zu starten.

Die Einstellungen für diese Dialoge können im Abschnitt startDialogs der Konfigurations-Datei festgelegt werden. Hierbei müssen Sie den Namen des Dialoges (z.B. start-dialog) als Objekt-Namen angeben. Im eigentlichen Dialog-Objekt müssen Sie dann den Titel, die Beschreibung, die URL unter welcher der Dialog erreichbar ist und eine Bezeichnung für den Button zum Öffnen des Dialogs angeben.

caution

Mit Startdialogen ist es möglich die prozessorientiere Entwicklung vollständig zu umgehen. Es sollte daher immer sorgfältig abgewogen werden, ob nicht eine CustomForm mit Prozess die bessere Lösung ist.

Eigenschaft	Typ	Beschreibung	Erforderlich	Standardwert
Liste von startDialog	startDialog	Bezeichnung der Start Dialoge als Identifier	nein

Beispiel für einen StartDialog mit ID test-dialog-1:

{
  "startDialogs": {
    "test-dialog-1": {
      "title": "Test dialog",
      "body": "Use this to test stuff",
      "url": "http://localhost:3000",
      "startButtonTitle": "Open dialog"
    }
  }
}

startDialog

Eigenschaft	Typ	Beschreibung	Erforderlich
title	string	Name des Start Dialogs	ja
body	string	Beschreibung des Start Dialogs	nein
url	string	URL unter welcher der Start Dialog erreichbar ist	ja
startButtonTitle	string	Name des Start Buttons des Start Dialogs	ja
requiredClaims	string[]	Eine Liste von Claims, von denen der Benutzer mindestens einen besitzen muss, damit der Startdialog angezeigt wird	nein
groupId	string	Die ID der Gruppe, der der Startdialog zugordnet werden soll	nein

startableGroup

Über diese Konfiguration kann eine neue Gruppe angelegt werden. Prozessmodelle und Startdialoge können der Gruppe anschließend zugewiesen werden, indem die Gruppen-ID über die Option groupId referenziert wird.

Siehe:

processModels.settings
startDialog

Eigenschaft	Typ	Beschreibung	Erforderlich	Standardwert
id	string	Eindeutige ID der Gruppe	ja
title	string	Titel der Gruppe	ja

Konfiguration des Designs

Für die Konfiguration von Farben und anderen Darstellungselementen des 5Minds Portals können Sie eine eigene CSS-Datei angeben. Wenn Sie Docker verwenden, muss die Datei im Dateisystem des Containers vorhanden sein (z.B. als Mount).

Konfiguration der Assets

Um ihr Theme mit Bildern, Styles oder ähnlichem anzureichern, können Sie über den assets Parameter einen Pfad zu einem Ordner angeben, der diese Dateien enthält.

Der Inhalt dieses Ordners wird vom Portal statisch gehostet und ist dann unter dem Pfad <applicationBaseUrl>/assets/<filename> erreichbar.

Beispiel: Angenommen Sie haben einen Ordner als asset angegeben, in welchem eine Datei logo.png liegt.

Dann wäre diese Datei unter dem Pfad <applicationBaseUrl>/assets/logo.png verfügbar.

Konfiguration der Übersetzung

Die Verwendung einer eigenen Übersetzung funktioniert ähnlich zur Verwendung eines eigenen Designs. Auch bei der Übersetzung werden, wenn Sie keine Übersetzungen im entsprechenden Ordner liegen haben, die Standard-Übersetzungen für Deutsch und Englisch in dem Ordner erstellt.

Übersetzen von Startable-Groups

Wenn Startable-Groups konfiguriert wurden, ist es möglich die Titel der Gruppen zu übersetzen. Dazu muss in der Übersetzungsdatei die Gruppen ID mit dem übersetzten Titel als Wert angegeben werden.

  ...
  "StartableGroups": {
    "<group-id>": "Übersetzung",
    "<group-id>": "Übersetzung"
  },

Übersetzen von Prozessen / Start Dialogen

Um Übersetzungen für Prozesse und Start Dialoge, nachfolgend Startables genannt, zu nutzen, muss in der Übersetzungsdatei das entsprechende Schema eingehalten werden. Für jedes Startable ist es möglich Titel, Body (Beschreibungstext) und Start-Button-Titel zu übersetzen.

  ...
  "Startables": {
    "<startdialog-oder-prozess-id>": {
      "Title": "Übersetzung",
      "Body": "Übersetzung",
      "StartButtonTitle": "Übersetzung"
    }
  }

Um mehrere Start Buttons zu übersetzen, muss ein StartButtonTitles Objekt wie folgt benutzt werden:

  ...
  "Startables": {
    "<startdialog-oder-prozess-id>": {
      "Title": "Übersetzung",
      "Body": "Übersetzung",
      "StartButtonTitles": {
        "<startevent-id>": "Übersetzung",
        "<startevent-id>": "Übersetzung"
      }
    }
  }

customTranslations

Mit der Option customTranslations können einzelne Sprachvariablen überschrieben oder Neue angelegt werden, ohne die jeweilige Übersetzungsdatei ersetzen zu müssen.

Eigenschaft	Typ	Beschreibung	Erforderlich	Standardwert
\<Ländercode>	customTranslation	Ländercode der Übersetzungen, die überschrieben werden sollen	ja

Beispiel:

{
  "customTranslations": {
    "de": {
      "ApplicationTitle": "Buchhandlung",
      "Header": {
        "Title": "Buchhandlung"
      }
    }
  }
}

customTranslation

Eigenschaft	Typ	Beschreibung	Erforderlich	Standardwert
\<Sprachvariable>	object oder string	Ein Objekt welches Strings bzw. weitere Objekte enthält. Die Schlüssel sind Sprachvariablen und die Werte die Übersetzungen.	ja

languages

Mit der Option languages können Sprachen konfiguriert werden, die für den Nutzer verfügbar sein sollen. Die Reihenfolge der Sprachen in der Benutzeroberfläche entspricht der Konfigurationsreihenfolge.

Beispiel:

{
  "languages": {
    "fr": "Français",
    "de": "Deutsch",
    "en": "English"
  }
}

Standardwert:

{
  "languages": {
    "de": "Deutsch",
    "en": "English"
  }
}

Konfiguration des Loggers

Für den Logger kann das minimale Log-Level angegeben werden.

Beispiel:

{
  "logging": {
    "minLogLevel": "error"
  }
}

Standardwert:

{
  "logging": {
    "minLogLevel": "debug"
  }
}

Konfigurieren des 5Minds Portals

Beispiel Konfiguration​

Konfigurationsmöglichkeiten​

Konfiguration mit Hilfe einer Konfigurationsdatei​

Konfiguration mit Hilfe von Umgebungsvariablen​

Konfiguration mit Hilfe von Kommandozeilenargumenten​

Konfigurationseigenschaften​

Konfiguration Anwendungs URL​

Per applicationBaseUrl​

Per applicationBaseUrl + port​

Konfiguration der 5Minds Engine​

Konfiguration der Authentifizierung​

authorityConfiguration​

processModels​

processModels.settings​

customForms​

customForm​

startDialogs​

startDialog​

startableGroup​

Konfiguration des Designs​

Konfiguration der Assets​

Konfiguration der Übersetzung​

Übersetzen von Startable-Groups​

Übersetzen von Prozessen / Start Dialogen​

customTranslations​

customTranslation​

languages​

Konfiguration des Loggers​

Beispiel Konfiguration

Konfigurationsmöglichkeiten

Konfiguration mit Hilfe einer Konfigurationsdatei

Konfiguration mit Hilfe von Umgebungsvariablen

Konfiguration mit Hilfe von Kommandozeilenargumenten

Konfigurationseigenschaften

Konfiguration Anwendungs URL

Per applicationBaseUrl

Per applicationBaseUrl + port

Konfiguration der 5Minds Engine

Konfiguration der Authentifizierung

authorityConfiguration

processModels

processModels.settings

customForms

customForm

startDialogs

startDialog

startableGroup

Konfiguration des Designs

Konfiguration der Assets

Konfiguration der Übersetzung

Übersetzen von Startable-Groups

Übersetzen von Prozessen / Start Dialogen

customTranslations

customTranslation

languages

Konfiguration des Loggers