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

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 zyklisch alle registrierten Apps im Benutzerkontext 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:

JSON Response 
   {
  "_links" : {
	...
    "configfeatures" : {
        "href" : "/<app name>/configfeatures"
    }, 
	...
  },
  ...
}


Wenn eine solche Linkrelation vorhanden ist, wird die darunter angegebene URI 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:

JSON Response 
   {
  "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>,
		...
      ]
    },
	<second configuration option>,
	...
  ]
}
ParameterBeschreibung
appNameName der App, welche die Konfigurationsoptionen bereitstellt
customHeadlines

Liste aller Konfigurationsoptionen, die eine App bereitstellt

Parameter und Beschreibung

caption: Überschrift der Konfigurationsoption, unter welcher die Menüpunkte aufgelistet werden. Diese 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. Diese 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

0: Die Konfiguration ist vollständig.
1: Die Konfiguration ist unvollständig und sollte vervollständigt werden.


Im Folgenden sind Beispiele für die verschiedenen DTOs aufgelistet, die den Aufbau eines configfeatures beschreiben. Die Beispiele sind in C# geschrieben.

ConfigFeatureDto 
   public class ConfigFeatureDto
{
    public string AppName { get; set; }
    public List<CustomHeadlineDto> CustomHeadlines { get; set; }
 
    public ConfigFeatureDto()
    {
        CustomHeadlines = new List<CustomHeadlineDto>();
    }
}
CustomHeadlineDto 
   public class CustomHeadlineDto
{
    public string Caption { get; set; }
    public string Description { get; set; }
    public List<MenuItemDto> MenuItems { get; set; }
 
    public CustomHeadlineDto()
    {
        MenuItems = new List<MenuItemDto>();
    }
}
MenuItemDto 
   public class MenuItemDto
{
    public string Caption { get; set; }
    public string Description { get; set; }
    public string Href { get; set; }
    public List<string> Keywords { get; set; }
    public ConfigurationStateDto ConfigurationState { get; set; }
 
    public MenuItemDto()
    {
        Keywords = new List<string>();
    }
}
ConfigurationStateDto 
   public enum ConfigurationStateDto
{
    Complete = 0,
    Incomplete = 1
}

Anzeigen von Konfigurationsoptionen

Freigegeben: HTML-Seite

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.

Request 
   GET /config
Accept: application/hal+json
Response 
   {
	_links: {
		configfeatures: {
			href: "/config/features{?appname}",
			templated: true
		}
	}
}

Angeben von verhaltenssteuernden Parametern

Das Verhalten beim Anzeigen der Konfigurationsoptionen steuerst du mit folgenden Parametern:

ParameterBeschreibung

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.

Aufrufen der URL für die Konfigurationsoptionen

Wenn du eine URL erzeugt hast, dann kannst du die Ergebnisse wie folgt aufrufen:

Request 
   GET /config/features?appname=identityprovider
Accept: text/html

Als Ergebnis werden dann alle Konfigurationsoptionen von der Identity Provider-App angezeigt.