Config-App

Config API

Introduction

This chapter contains basic information on the Config API.

About the Config app

The Config app collects configuration options from other d.velop apps and provides them in a unified interface. User-specific as well as administrative configuration options are displayed. Configuration options must be provided by other apps so they can be queried by the Config app.

Scope of function of the Config app

The config app is the central interface to the following functionalities regarding the configuration of other apps:

  • Displaying unconfigured configuration options
  • Displaying all configuration options

Using the API functions

The Config app asks other apps for an interface with which the respective configuration options can be queried. 

The structure of this interface is described under Providing a configuration option.

You can also provide your own entry point to the Config app. 

This is described under (Deprecated) Displaying configuration options.

Providing a configuration option

This function allows you to provide configuration options which can be displayed by the config app in a unified interface. 

To provide configuration options, you must provide a configfeatures link relation.


Determining the configuration options:

The config app queries all registered apps. Afterwards, every registered app is queried with the request /<app name>/ on the base address (i.e.: https://<your base address>/<app name>/) and the request header "Accept: application/hal+json". This searches for the configfeatures link relation. In order for the link relation to be found, the JSON must be structured as follows:

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


If such a link relation exists, the URI specified in the user context under it is invoked with the request method GET and the request header "Accept: application/hal+json" and the included JSON is interpreted. The JSON that apps must provide in order to offer one or more configuration options must be structured according to the following schema:

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>,
		...
      ], 
	  "categories":[{
		  "id": "<id of your first category>", 
		  "caption": "<caption of your first category>"
	    }, 
		<second category>, 
		...
	  ]
    },
	<second configuration option>,
	...
  ]
}
ParameterDescription
appNameName of the app that provides the configuration options.
customHeadlines

List of all configuration options provided by an app

Parameters and description

caption: Caption of the configuration option under which the menu options are listed. This option describes what the configuration affects. As a rule, this corresponds to the subject matter of the app as a noun, i.e. "Document", "Inbox message", "Outlook Mail", etc.

description: Description of the configuration option. This text is currently not displayed, but it is used for the search. 

menuItems: List of all menu items under a configuration option.

caption: Caption of the menu item. This caption describes what is configured, i.e. "Database", "Users and Groups", "Filter rules", etc.

description: Description of the menu item.

href: Link to the configuration behind the menu item.

Keywords: List of keywords describing the menu item to enable searching for the menu item.

configurationState: Status of the configuration.
0: The configuration is complete.
1: The configuration is incomplete and should be completed.

categories: List of all categories of the configuration option. The category is used for filtering the apps. You can choose categories from the following table or your own categories.

id: ID of the category. Enter the ID of the category from the table below or, in case of a self-selected category, a unique ID. 

caption: Label of the category. Specify the display name of the category in the correct language. You can find the English and German translations in the following table. There is no translation within d.ecs config. 


The following table describes the categories that can be assigned to an app. 

ID:Caption (EN)Caption (DE)
7b73531b-9d81-4891-adf2-857af768f1f3Common settingsAllgemeine Einstellungen
0a3c33eb-2f70-45de-a4f1-093f509eea15Tasks and processesAufgaben und Prozesse
b404c8f8-8d56-4861-b847-fcfc7eec0ba2Document managementDokumentenverwaltung
81cf6d2c-8991-4ada-ad38-de0974bf3a25Incoming mailEingehende Post
eb30082b-f4bf-4c13-8a5e-84cad916561eE-mail managementE-Mail-Verwaltung
892dd782-7a40-465b-a0eb-6f6e185f34c6Business applicationsGeschäftsanwendungen
c1fd1fa0-b7f4-49dc-abc2-f11b6e9578f1Connectors and adaptersKonnektoren und Adapter
ed7ef2a1-f1c0-4896-97a6-db1f693d128aMonitor for system processesMonitor für Systemprozesse
147d1539-e6c1-4828-8380-0673f3e59067SearchSuche
4fd6f25d-8ed0-4bc9-9c22-0719b557be22Cases and contractsVorgänge und Verträge
5fa644aa-2600-4f78-b5a9-da3b6b313a57Additional functions for Microsoft OfficeZusatzfunktionen für Microsoft Office
9a64b476-dc7c-4c8b-b555-6d03caf64131Without categoryOhne Kategorie


The code below lists examples for the different DTOs, describing the structure of a configfeature. The examples are written in C#.

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 List<CategoryDto> Categories { get; set; }
 
    public CustomHeadlineDto()
    {
        MenuItems = new List<MenuItemDto>();
        Categories = new List<CategoryDto>();
    }
}
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>();
    }
}
CategoryDto
public class CategoryDto
{
    public string Id { get; set; }
    public string Caption { get; set; }
}
ConfigurationStateDto
public enum ConfigurationStateDto
{
    Complete = 0,
    Incomplete = 1
}

(Deprecated) Displaying configuration options

This function is deprecated and should no longer be used.

Released: HTML page

With this function, you can provide an entry point to the Config app. 

Determining the link relation for displaying the configuration options

The URL for a repository is available as a link relation in the response of the HTTP GET request.

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

Specifying behavior-controlling parameters

You can use the following parameters to control the behavior for displaying the configuration options:

ParameterDescription

appname

Restricts the configuration options to a specific app. The technical app name (e.g. identityprovider instead of d.ecs identity provider) must be used.

Calling the URL for the configuration options

When you have created a URL, you can call the results as follows:

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

As a result, all configuration options of the identity provider app are then displayed.

Notifying changes to the status

You can update your configuration options using your configuration interface.

Suppose your configuration option is in an invalid state, for example because the connection information is wrong. In this case, the administrator uses the Config app to navigate to the configuration interface. After correcting the connection information, you want to refresh your configuration options.

Refreshing your configuration options - This is how it works

  1. Send a ResourceEvent via the API of the Shell app.
  2. Enter changed at Eventname. The URI must correspond to the currently displayed configuration option.

For more information about sending ResourceEvents, see the API documentation of the Shell app.

Your configuration options will be refreshed by the Config app.