Config-App
Config API
Einleitung
In diesem Kapitel findest du grundlegende Informationen über die Config API.
Über die Config-App
Die Config-App sammelt Konfigurationsoptionen anderer d.velop-Apps und stellt diese gesammelt dar. Es werden sowohl benutzerspezifische, als auch administrative Konfigurationsoptionen angezeigt. Konfigurationsoptionen müssen von anderen Apps bereitgestellt werden, sodass diese von der Config-App abgefragt werden können.
Funktionsumfang der Config-App
Die Config-App ist die zentrale Schnittstelle zu folgenden Funktionalitäten zum Thema Konfiguration anderer Apps:
- Anzeigen von nicht konfigurierten Konfigurationsoptionen
- Anzeigen von allen Konfigurationsoptionen in zwei Kategorie-Ebenen
Verwenden der API-Funktionen
Die Config-App erfragt andere Apps nach einer Schnittstelle, mit welcher die jeweiligen Konfigurationsoptionen abgefragt werden können.
Wie diese Schnittstelle aufgebaut sein muss, wird unter Bereitstellen einer Konfigurationsoption beschrieben.
Des Weiteren kannst du einen eigenen Einsprungspunkt auf die Config-App anbieten.
Dies wird unter Anzeigen von Konfigurationsoptionen beschrieben.
Bereitstellen einer Konfigurationsoption
Mit dieser Funktion kannst du Konfigurationsoptionen bereitstellen, die durch die Config-App gesammelt dargestellt werden.
Damit du Konfigurationsoptionen bereitstellen kannst, musst du eine Linkrelation configfeatures bereitstellen.
Ermitteln der Konfigurationsoptionen:
Die Config-App fragt alle registrierten Apps ab. Anschließend wird jede registrierte App mit dem Aufruf /<app name>/ auf der Basisadresse (also: https://<your base address>/<app name>/) und dem Anforderungsheader "Accept: application/hal+json" abgefragt. Es wird nach der Linkrelation configfeatures gesucht. Damit die Linkrelation gefunden werden kann, muss das JSON wie folgt aufgebaut sein:
{
"_links" : {
...
"configfeatures" : {
"href" : "/<app name>/configfeatures"
},
...
},
...
}
Wenn eine solche Linkrelation vorhanden ist, wird die darunter angegebene URI im Benutzerkontext mit der Anforderungsmethode GET und dem Anforderungsheader "Accept: application/hal+json" aufgerufen und das erhaltene JSON ausgewertet. Das JSON, welche Apps bereitstellen müssen, um eine oder mehrere Konfigurationsoptionen anzubieten, muss entsprechend dem nachfolgenden Schema aufgebaut sein:
{
"appName": "<app name>",
"customHeadlines":[
{
"caption": "<caption of your configuration option>",
"description": "<description of your configuration option>",
"menuItems":[ {
"caption": "<caption of your first menu item>",
"description": "<description of your first menu item>",
"href": "<link to your configuration>",
"keywords":["<first key word>", "<second key word>", ...],
"configurationState": <state of your configuration>
},
<second menu item>,
...
],
"categories":[{
"id": "<id of your category>"
}
]
},
<second configuration option>,
...
]
}
Parameter | Beschreibung |
---|---|
appName | Name der App, welche die Konfigurationsoptionen bereitstellt |
customHeadlines | Liste aller Konfigurationsoptionen, die eine App bereitstellt Parameter und Beschreibung caption: Überschrift der Konfigurationsoption, unter der die Menüpunkte aufgelistet werden. Diese Option beschreibt, worauf sich die Konfiguration auswirkt. In der Regel entspricht dies der Fachlichkeit der App als Substantiv, etwa "Dokument", "Postkorbnachricht", "Outlook-Mail" etc. description: Beschreibung der Konfigurationsoption. Dieser Text wird aktuell nicht angezeigt, jedoch für die Suche verwendet. menuItems: Liste aller Menüpunkte unter einer Konfigurationsoption. caption: Überschrift des Menüpunktes. Die Überschrift beschreibt, was konfiguriert wird, etwa "Datenbank", "Benutzer und Gruppen", "Filterregeln" etc. description: Beschreibung des Menüpunktes. href: Link zu der Konfiguration hinter dem Menüpunkt. Keywords: Liste von Schlüsselwörtern, die den Menüpunkt beschreiben, um eine Suche nach dem Menüpunkt zu ermöglichen. configurationState: Status der Konfiguration. categories: Liste mit der Kategorie der Konfigurationsoption. Die Kategorie wird für die Filterung der Apps verwendet. Es kann eine Kategorie aus der nachfolgenden Tabelle gewählt werden. id: ID der Kategorie. Gib die ID der Kategorie aus der nachfolgenden Tabelle an. |
Die folgende Tabelle beschreibt die Kategorien, die einer App zugeordnet werden können.
ID | Kategorie - Ebene 1 (EN) | Kategorie - Ebene 2 (EN) | Kategorie - Ebene 1 (DE) | Kategorie - Ebene 2 (DE) |
---|---|---|---|---|
b404c8f8-8d56-4861-b847-fcfc7eec0ba2 | Document management | Administration | Dokumentenmanagement | Verwaltung |
81cf6d2c-8991-4ada-ad38-de0974bf3a25 | Document management | Import | Dokumentenmanagement | Import |
eb30082b-f4bf-4c13-8a5e-84cad916561e | Document management | E-mails | Dokumentenmanagement | E-Mails |
147d1539-e6c1-4828-8380-0673f3e59067 | Document management | Search | Dokumentenmanagement | Suche |
42bae7f1-2cbe-4ff2-a2ce-16d4bc1e4b41 | Document management | Export | Dokumentenmanagement | Export |
892dd782-7a40-465b-a0eb-6f6e185f34c6 | Invoice processing | Rechnungsverarbeitung | ||
0a3c33eb-2f70-45de-a4f1-093f509eea15 | Tasks and processes | Aufgaben und Prozesse | ||
4fd6f25d-8ed0-4bc9-9c22-0719b557be22 | Cases and contracts | Vorgänge und Verträge | ||
82bd9781-1b0b-4fc3-a546-e1a83f9a5a82 | Notifications | Benachrichtigungen | ||
5fa644aa-2600-4f78-b5a9-da3b6b313a57 | Integrations and interfaces | Integrationen und Schnittstellen | ||
9061048f-4165-4f12-94a3-606037864d49 | Digital signing | Digitales Unterschreiben | ||
ed7ef2a1-f1c0-4896-97a6-db1f693d128a | Infrastructure and security | Infrastruktur und Sicherheit | ||
0f4ffa80-3334-4b14-904e-6d1d13fe2038 | Appearance | Erscheinungsbild | ||
9a64b476-dc7c-4c8b-b555-6d03caf64131 | Miscellaneous | Sonstiges |
Im Folgenden sind Beispiele für die verschiedenen DTOs aufgelistet, die den Aufbau eines configfeatures beschreiben. Die Beispiele sind in C# geschrieben.
public class ConfigFeatureDto
{
public string AppName { get; set; }
public IList<CustomHeadlineDto> CustomHeadlines { get; set; }
public ConfigFeatureDto()
{
CustomHeadlines = new List<CustomHeadlineDto>();
}
}
public class CustomHeadlineDto
{
public string Caption { get; set; }
public string Description { get; set; }
public IList<MenuItemDto> MenuItems { get; set; }
public IList<CategoryDto> Categories { get; set; }
public CustomHeadlineDto()
{
MenuItems = new List<MenuItemDto>();
Categories = new List<CategoryDto>();
}
}
public class MenuItemDto
{
public string Caption { get; set; }
public string Description { get; set; }
public string Href { get; set; }
public IList<string> Keywords { get; set; }
public ConfigurationStateDto ConfigurationState { get; set; }
public MenuItemDto()
{
Keywords = new List<string>();
}
}
public class CategoryDto
{
public string Id { get; set; }
public string Caption { get; set; }
}
public enum ConfigurationStateDto
{
Complete = 0,
Incomplete = 1
}
Mitteilen von Änderungen des Status
Mit dieser Funktion kannst du - aus deiner Konfigurationsoberfläche heraus - deine Konfigurationsoptionen aktualisieren.
Angenommen deine Konfigurationsoption ist in einem fehlerhaften Status, da beispielsweise Verbindungsdaten nicht korrekt sind. In diesem Fall navigiert der Administrator mithilfe der Config-App zur Konfigurationsoberfläche. Nachdem du die Verbindungsdaten korrigiert hast, möchtest du, dass deine Konfigurationsoptionen neu geladen werden.
Neuladen der Konfigurationsoptionen - So geht's
- Versende ein ResourceEvent über die API der Shell-App.
- Gib unter Eventname "changed" an. Die übermittelte URI muss der aktuell angezeigten Konfigurationsoption entsprechen.
Informationen über das Senden von RessourceEvents findest du in der API-Dokumentation der Shell-App.
Deine Konfigurationsoptionen werden von der Config-App neu abgerufen.
Anzeigen von Konfigurationsoptionen
Mit dieser Funktion kannst du einen Einsprungspunkt auf die Config-App anbieten.
Ermitteln der Linkrelation zum Anzeigen der Konfigurationsoptionen
Die URL für ein Repository ist als Linkrelation in der Antwort (Response) der HTTP GET-Anforderung verfügbar.
GET /config/
Accept: application/hal+json
{
_links: {
configfeatures: {
href: "/config/features{?appname,category}",
templated: true
}
}
}
Angeben von verhaltenssteuernden Parametern
Das Verhalten beim Anzeigen der Konfigurationsoptionen steuerst du mit folgenden Parametern:
Parameter | Beschreibung |
---|---|
appname | Schränkt die Konfigurationsoptionen auf eine bestimmte App ein. Es muss der technische Appname (z.B. identityprovider statt d.ecs identity provider) verwendet werden. |
category | Schränkt die Konfigurationsoptionen auf eine Kategorie ein. Hierfür gibst du die ID der Kategorie an (etwa "0a3c33eb-2f70-45de-a4f1-093f509eea15" für die Kategorie "Aufgaben und Prozesse"). |
Aufrufen der URL für die Konfigurationsoptionen
Wenn du eine URL erzeugt hast, dann kannst du die Ergebnisse wie folgt aufrufen:
GET /config/features?appname=identityprovider
Accept: text/html
Als Ergebnis werden dann alle Konfigurationsoptionen von der Identity Provider-App angezeigt. Alle Konfigurationsoptionen der Kategorie "Aufgaben und Prozesse" kannst du folgendermaßen anzeigen lassen:
GET /config/features?category=0a3c33eb-2f70-45de-a4f1-093f509eea15
Accept: text/html