Limitieren von Aufrufzahlen

Für alle Schnittstellen gelten Begrenzungen hinsichtlich der Aufrufzahlen innerhalb von bestimmten Zeitbereichen. Beim Überschreiten dieser Begrenzungen wird der HTTP-Status-Code 429 (too many requests) zurückgegeben.

 Registrieren eines Widgets

Die Registrierung eines Widgets muss mit einer App-Session erfolgen. Wie du eine App-Session ausstellen kannst, ist im Abschnitt Inter-App-Kommunikation mit App-Sessions der Identityprovider-App beschrieben.

Eine App kann Widgets nur im eigenen Namensraum der App registrieren.

Du kannst ein neues Widget für deine App wie folgt mit der Dashboard-App bekannt machen.

Verwende eine HTTP-PATCH-Anforderung an den Pfad /dash/api/widget-registrations/<app-namespace>/<id>. Aufbau: [a-z-]/[a-z][a-z0-9]. Der <id> Teil nach dem / darf max zwölf Zeichen lang sein. Zum Beispiel 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"
            }
        }
    }
}

Folgende HTTP-Statuscodes können von der Dashboard-App zurückgegeben werden:

 Eigenschaften des Widget-Registrations-Objekt

 Unterstützte Widgetarten

 Shortcut

Nutze dieses Widget, um dem Anwender einen Absprung in deine App zu ermöglichen.

 Eigenschaften des Shortcut-Widget-Objekts

 Aufbau des Query-Badge-Objekts

Folgendes Objekt muss unter der im Shortcut-Widget angegebenen query.badge.url ausgeliefert werden.

 List

Nutze dieses Widget, um ein Listenwidget anzuzeigen.

 Eigenschaften des List-Widget-Objekts

 IFrame

Nutze dieses Widget, um externe Inhalte per IFrame anzuzeigen.

 Eigenschaften des Iframe-Widget-Objekts

 Eigenschaften des Sprachenobjekts

 Listeninhalt

Deine App muss unter der bei query.content.url angegeben URL folgendes JSON-Objekt zurückliefern.

 Eintragobjekt

 Berechtigungen

Optional kannst du Berechtigungen für das Widget mitgeben. Ohne Angabe von Berechtigungen sind Widgets für alle authentifizierten Anwender sichtbar, ausgeschloßen sind externe Anwender.

Ob ein Anwender das Widget sehen darf, wird durch eine ODER-Verknüpfung geprüft, d.h. zur Laufzeit wird geprüft, ob der Anwender in "Gruppe A" ODER "Gruppe B" ODER "Gruppe C" ist.

 Aufbau

Gruppenobjekt

Beispiel

{
    // ... 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>.

 Navigieren

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 aufgerufen, wenn du die Methode updateSettings der Widgeteinstellungen-API ausführst.

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)

 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>.

 Aktualisieren der Einstellungen

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

window.dashboard.WidgetSettingsAPI.updateSettings(data)