Dashboard app

Introduction

Change history

DateChanges
2023-08-01- The property settings.url and the method updateSettings are no longer supported.
- The property content_settings.url and the method setSettingsGetter have been added.

Limiting the number of calls

For all the interfaces, there are limits on the number of calls within specific time frames. If these limits are exceeded, the HTTP status code 429 (too many requests) is returned.

Registering a widget

A widget must be registered with an app session. The section Inter-app communication with app sessions for the identity provider app describes how to issue an app session.

warning: Authentication must take place with a bearer token in the authorization header. Authentication via cookie is not possible.

An app can register widgets only in the app’s own namespace.

You can introduce a new widget for your app as follows using the dashboard app.

Use an HTTP PATCH request for the path /dash/api/widget-registrations/<app-namespace>/<id>. Layout: [a-z-]/[a-z][a-z0-9]. The <id> part after the / must not exceed twelve characters. For example, acme-example/foobar.

Request

PATCH /dash/api/widget-registrations/<appname>/<widgetID>
Accept: application/json
Content-Type: application/merge-patch+json
Authorization: Bearer <AuthSessionId of an app session>

{
    "widget": {
        "type": "shortcut",
        "title": {
            "en": "My tasks",
            "de": "Meine Aufgaben"
        },
        "subtitle": {
            "en": "My open tasks",
            "de": "Meine offenen Aufgaben"
        },
        "icon": {
            "url": "https://example.com/tasks.svg"
        },
        "target": {
            "url": "/tasks/tasks?filter=foo"
        },
        "query": {
            "badge": {
              "url": "/tasks/tasks?type=badge"
            }
        }
    }
}

The dashboard app may return the following HTTP status codes:

Status codeNameMeaning
200OKRegistration or update of the widget was successful.
400Widget registration object is invalid
401Not authorizedAuthentication via app session is required
403ForbiddenA widget can be registered only within the internal widget namespace. Please ensure that the first part of the widget registration ID is the same as the app name.
429Too many requestsRate limit was reached.
5XXAn unexpected error occurred.

Properties of the widget registration object

PropertyTypeRequirementDescription
widgetObjectYesSee Widget types for the layout
permissionsObjectNoSee Permissions for the layout

Supported widget types

Shortcut

Use this widget to enable the user to navigate to your app.

Properties of the shortcut widget object
PropertyTypeRequirementDescription
typeStringYesValue for the “shortcut” navigation widget
titleObjectYesSee Language object
subtitleObjectNoSee Language object
icon.urlStringYesURL for an icon (SVG or PNG)
target.urlStringYesURL for the target address (if the target address is to be displayed with the old navigation behavior of d.ecs shell, specify the query parameter oldBehavior=true as well.)
query.badge.urlStringNoSee “Query badge”
override_home_app_feature_idStringNoIf there is already a home app feature for the widget, this field can be used to overwrite this feature with the widget. This way, only one widget is displayed in the catalog.
To do this, specify the ID of the home app feature. If an ID was specified when registering the home app feature, this can be used. Otherwise, the ID is made up of the URL that was specified in features[].url. All slashes are replaced by a minus sign. The ID is then composed as follows: <APP_NAME>-<URL>. For example, for the app foobar with the URL /target/url, the ID is foobar-target-url.
Layout of the query badge object

The following object must be delivered under the query.badge.url specified in the shortcut widget.

PropertyTypeRequirementDescription
badge.countIntegerYesIf the value is greater than 0, a badge is displayed on the widget. Values greater than 99 are displayed as “99+”.

List

Use this widget to display a list widget.

Properties of the list widget object
PropertyTypeRequirementDescription
typeStringYesValue for “list” list widget
titleObjectYesSee Language object
subtitleObjectNoSee Language object
icon.urlStringYesURL for an icon (SVG or PNG)
target.urlStringYesURL for the target address (if the target address is to be displayed in the old shell, specify the query parameter oldBehavior=true as well.)
query.content.urlStringYesSee List content
query.content.navigationStringNoNavigation adopts the values dapiNavigate, innerSupply or outerSupply. If a value is unknown or undefined, outerSupply is used as the fallback.
footer.urlStringNoURL that is opened in the outer supply of the shell.
footer.labelObjectNoSee Language object

IFrame

Use this widget to display external content via IFrame.

Properties of the IFrame widget object
PropertyTypeRequirementDescription
typeStringYesValue for the "iframe" IFrame widget
titleObjectYesSee Language object
subtitleObjectNoSee Language object
icon.urlStringYesURL for an icon (SVG or PNG)
target.urlStringYesURL for the target address (if the target address is to be displayed in the old shell, specify the query parameter oldBehavior=true as well.)
size.min_wIntegerNoMinimum width of the widget. Permitted values: 2 ≤ x ≤ 18
size.min_hIntegerNoMinimum height of the widget. Permitted values: 2 ≤ x ≤ 16
source.urlStringYesURL for the HTML resource to be embedded in the IFrame. The URL must be an absolute path reference; that is, it must start with a leading slash / (for example, “/foobar/ressource.html” and not “foobar”)/ressource.html).
content_settings.urlStringNoURL for a configuration page for the IFrame content of the widget. The settings are saved for each widget instance. The URL must be an absolute path preference; that is, it must start with a leading slash / (for example, “/foobar/ressource.html” and not “foobar”/ressource.html).
For more information about widget settings, see Widgeteinstellungen Javascript-API.
settings.urlStringNoDEPRECATED: This property is obsolete. Instead, please use the property content_settings.url.
URL for a configuration page for the widget. The URL must be an absolute path reference; that is, it must start with a leading slash / (for example, “/foobar/ressource.html” and not “foobar”)/ressource.html).

Properties of the language object

PropertyTypeRequirementDescription
Language tagStringSpecify at least one language.

List content

Your app must return the following JSON object under the URL specified for query.content.url.

For better time formatting a request to the url specified in query.content.url will contain a custom header x-dv-timezone-offset. The value is the offset for the clients timezone relative to UTC in minutes, e.g. -60 for german daylight saving time.

PropertyTypeRequirementDescription
entriesArrayYesContains all the list entries. An entry object is specified for each entry.
line_variantStringNoDefines the number of lines per element. If no value is defined, one line is displayed. For two lines, specify the value twoline.
leading_element_typeStringNoDefines the type of the leading element. You can choose between icon or image. If no value is specified, no element is displayed.
trailing_element_typeStringNoDefines the type of the trailing element. You can choose between icon or caption. If no value is specified, no element is displayed.

Entry object

PropertyTypeRequirementDescription
title.textStringYesContains the title of the entry.
title.colorStringNoDefines the color of the title. Please specify the color as a hexadecimal value (for example, #112233).
subtitle.textStringNoContains the subtitle of the entry.
subtitle.colorStringNoDefines the color of the subtitle. Please specify the color as a hexadecimal value (for example, #112233).
fontModeStringNoDefines the font for the text. You can choose between bold or crossed-out.
lead_element.material_iconStringNoDefines the leading icon. The value must be a valid material icon. To use a material icon, set leading_element_type to icon.
lead_element.icon_colorStringNoDefines the color of the leading icon. Please specify the color as a hexadecimal value (for example, #112233).
lead_element.image_urlStringNoURL for an image (SVG or PNG). To use an image, set leading_element_type to image.
lead_element.image_sizeStringNoDefines the size of the image. You can choose between icon, avatar, medium or large.
trail_element.material_iconStringNoDefines the trailing icon. The value must be a valid material icon. To use an image, set trailing_element_type to icon.
trail_element.icon_colorStringNoDefines the color of the trailing icon. Please specify the color as a hexadecimal value (for example, #112233).
trail_element.captionStringNoContains the text to be displayed at the end of the entry. To use a caption, set trailing_element_type to caption.
trail_element.caption_colorStringNoDefines the color of the caption. Please specify the color as a hexadecimal value (for example, #112233).
target.urlStringNoURL that the entry forwards you to when clicked.

Permissions

You also have the option of specifying permissions for the widget. If you do not specify permissions, widgets are visible to all authenticated users. External users are excluded.

An OR link is used to check whether a user is permitted to view the widget; that is, at runtime, the system checks whether the user is in “group A” OR “group B” OR “group C”.

Layout

PropertyTypeRequirementDescription
groupsArrayList of group objects

Group object

PropertyTypeRequirementDescription
valueStringYesUUID (case-insensitive)

Example

{
    "widget": {
        //... Widget data
    },
    "permissions": {
        "groups": [
            {
                "value": "3E093BE5-CCCE-435D-99F8-544656B98681"
            }
        ]
    }
}

Dashboard Javascript-API

Einbinden der Dashboard Javascript-API

Du kannst die Dashboard Javascript-API wie folgt in deine Seite einbinden.

Erstelle ein Script Tag, füge das Attribut type="module" hinzu und verwende als Quelle die Url "/dash/api/dashboard_api_v1.js".

<script type="module" src="/dash/api/dashboard_api_v1.js"></script>

IFrame-Widget Javascript-API

Verfügbare Methoden

Die Methoden der IFrame-Widget API erreichst du unter window.dashboard.WidgetAPI.<Methode>.

Wenn du zu einer anderen Seite navigieren möchtest, verwende die Methode navigateTo(userEvent, url). Um sicherzustellen, dass die Navigation von einem Anwender ausgelöst wurde, musst du das entsprechende Event (z.B. das Klickevent) angeben.

window.dashboard.WidgetAPI.navigateTo(userEvent, url)

Outer Supply

Mit der Methode openOuterSupply(userEvent, url) kannst du eine Ressource im Outer Supply öffnen. Um sicherzustellen, dass das Öffnen des Outer Supplies von einem Anwender ausgelöst wurde, musst du das entsprechende Event (z.B. das Klick-Event) angeben.

window.dashboard.WidgetAPI.openOuterSupply(userEvent, url)

Widget-Einstellungen Callback

Über den Widgeteinstellungen-IFrame kann das Widget aktualisiert werden. Hierfür musst du eine Callback-Funktion mithilfe der Methode setUpdateSettingsCallback(callback) registrieren. Die Callback-Funktion wird beim Klick des Anwendenden auf Speichern aufgerufen.

function callback(data: unknown) {
    console.log(data)
}

window.dashboard.WidgetAPI.setUpdateSettingsCallback(callback)

Öffnen der Einstellungen

Die Widgeteinstellungen kannst du über das Dreipunktesymbol am Widget öffnen. Zusätzlich kannst du die Einstellungen aber auch mit der Methode openSettings(userEvent) öffnen. Auch hier muss das Event, das durch den Anwender ausgelöst wurde, angeben.

window.dashboard.WidgetAPI.openSettings(userEvent)

Speichern der Einstellungen

Mithilfe der Methode saveSettings(data) kannst du Einstellungen für ein Widget speichern. Diese Einstellungen werden durch die Dashboard-App pro Widgetinstanz gespeichert. Die Einstellungen müssen nach JSON konvertierbar sein und das JSON-Objekt darf nicht größer als 1kB sein.

window.dashboard.WidgetAPI.saveSettings(data)

Abrufen der gespeicherten Einstellungen

Die gespeicherten Einstellungen einer Widgetinstanz kannst du mit der Methode getSettings() abrufen. Die Methode gibt ein Promise für die Einstellungen zurück.

const data = await window.dashboard.WidgetAPI.getSettings()

Widgeteinstellungen Javascript-API

Die Widgeteinstellungen werden im Navigation Drawer in einem IFrame angezeigt. Die URL für diesen IFrame wird bei der Registrierung angegeben.

Verfügbare Methoden

Die Methoden der Widgeteinstellungen-API erreicht du unter window.dashboard.WidgetSettingsAPI.<Methode>.

Abrufen der gespeicherten Einstellungen

Die gespeicherten Einstellungen einer Widgetinstanz kannst du wie bei der IFrame-Widget API ebenfalls mithilfe der Widgeteinstellungen-API abrufen.

const data = await window.dashboard.WidgetAPI.getSettings()

Getter-Funktion für Widget-Einstellungen

Damit die Einstellungen des IFrame-Widgets gespeichert werden können, musst du eine Getter-Funktion für die Einstellungen festlegen. Verwende hierfür die Methode setSettingsGetter(getter). Die Getter-Funktion muss die Einstellungen des Widgets zurückgeben. Die Einstellungen müssen nach JSON konvertierbar sein und das JSON-Objekt darf nicht größer als 1kB sein.

function getSettings(): unknown {
    return {
        sort: "desc"
    }
}

window.dashboard.WidgetAPI.setSettingsGetter(getSettings)

Aktualisieren der Einstellungen

warning: Deprecated: Du kannst die Methode updateSettings nur verwenden, wenn du die obsolete Eigenschaft settings.url bei der Registrierung verwendet hast. Wenn du die Eigenschaft content_settings.url verwendet hast, wird die Methode automatisch beim Klick auf Speichern ausgeführt.

Die aktualisierten Einstellungen kannst du dem IFrame-Widget mit der Methode updateSettings(data) mitteilen.

window.dashboard.WidgetSettingsAPI.updateSettings(data)