Digitale Verwaltung as a Service

# Anleitung

# Minimale Konfiguration

Die minimale Konfiguration eines Dienstes wird in dem folgenden Codeausschnitt dargestellt.







 
 


 
 



<!DOCTYPE html>
<html lang="de">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Beispiel ABH Webauftritt</title>
	<link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/tf-blue.css">
	<script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js" charset="UTF-8"></script>
</head>
<body style="margin-top: 4rem;">
	<dienst-name ags="ags-wert"></dienst-name>
	<script src="https://api.service-digitale-verwaltung.de/embed/dienst-name/dienst-name.js" charset="UTF-8"></script>
</body>
</html>

Wichtig: Es handelt sich um ein allgemeines Beispiel, um einen bestimmten Dienst einzubinden, muss der dienst-name und ags-wert aus dem Ausschnitt entsprechend angepasst werden.

Es stehen die folgenden Dienste zur Verfügung:

Ausländerwesen Personenstandswesen eWaffe
at-ausbildung pw-anmeldung-eheschliessung ewaffe-anzeige-unbrauchbarmachung
at-erwerbstaetigkeit pw-eheurkunde ewaffe-anzeige-verlust
at-fachkraefteverfahren pw-geburtsanzeige ewaffe-ausnahme-mindestalter-schiessstaetten
at-familiennachzug pw-geburtsanzeige-eltern ewaffe-bescheid-widerspruch
at-germany-for-ukraine pw-geburtsurkunde ewaffe-blockiersystem-erbwaffen
at-nebenbestimmungen pw-lebenspartnerschaftsurkunde ewaffe-editing-tool
at-niederlassungserlaubnis pw-sterbefallanzeige ewaffe-eu-feuerwaffenpass-ausstellung
aw-aufenthaltskarte pw-sterbeurkunde ewaffe-eu-feuerwaffenpass-verlaengerung
aw-beschaeftigungserlaubnis ewaffe-gelbe-wbk-sportschuetze-erteilung
aw-einbuergerung ewaffe-gruene-wbk-person-erteilung
aw-buendelungskomponente ewaffe-kleiner-waffenschein-erteilung
ewaffe-mitnahme-erteilung
ewaffe-mitnahme-verlaengerung
ewaffe-rote-wbk-erteilung
ewaffe-schiesserlaubnis-erteilung
ewaffe-verbringung-erteilung
ewaffe-waffenschein-erteilung
ewaffe-waffenschein-verlaengerung
ewaffe-wbk-austragung-ueberlassung
ewaffe-wbk-eintragung-erwerb
ewaffe-wbk-erbfall
ewaffe-wbk-voreintrag
ewaffe-wbk-vereine-erteilung
Zulassungswesen Wahlschein Kita
ikfz-service ws-briefwahlantrag kita-anmeldung
ikfz-kennzeichenreservierung ws-briefwahlantrag-qr
zw-online-auskunft-fahrzeugbriefe
Fahrtenschreiberkarte Führerscheinweisen Einwohnerwesen
fs-fahrerkarte fw-umtausch-altfahrerlaubnis ew-abmeldung-ausland
fs-unternehmenskarte fw-internationaler-fuehrerschein ew-meldebescheinigung
fs-werkstattkarte fw-fahrerqualifizierungsnachweis ew-selbstauskunft
fw-fahrerlaubnis-ersterteilung ew-statusabfrage-ausweis
fw-fahrerlaubnis-erweiterung ew-uebermittlungssperren
fw-fahrerlaubnis-verlaengerung ew-wohnsitzanmeldung
ew-wohnungsgeberbestaetigung
Finanzwesen
fin-wasserzaehlerablesung

Die minimale Konfiguration eines tatsächlichen Dienstes mit AGS wird im folgenden Codeausschnitt dargestellt.







 
 


 
 



<!DOCTYPE html>
<html lang="de">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Beispiel ABH Webauftritt</title>
	<link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/tf-blue.css">
	<script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js"></script>
</head>
<body style="margin-top: 4rem;">
	<at-erwerbstaetigkeit ags="09000001"></at-erwerbstaetigkeit>
	<script src="https://api.service-digitale-verwaltung.de/embed/at-erwerbstaetigkeit/at-erwerbstaetigkeit.js" charset="UTF-8"></script>
</body>
</html>

Wichtig: In diesem Beispiel wurde der Dienst at-erwerbstaetigkeit für die Gemeinde mit dem AGS 09000001 eingebunden. Der AGS muss durch den Betreiber des Dienstes für Ihre Domain freigegeben werden.

Neben der Einbindung mit der minimalen Konfiguration eines Dienstes haben Sie noch weitere Konfigurationsmöglichkeiten (z. B. Theme, Sprache). Diese werden in den folgenden Absätzen erläutert.

# Maximale Konfiguration

Maximale Konfiguration am Beispiel at-erwerbstaetigkeit mit dem AGS 12345678.







 
 


 
 














<html lang="de">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Antrag für einen Aufenthaltstitel zur Erwerbstätigkeit</title>
        <link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/tf-blue.css">
        <script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js"></script>
    </head>
    <body style="margin-top: 4rem;">
        <noscript>
            Für die Verwendung dieses Dienstes ist JavaScript erforderlich.
                Bitte aktivieren Sie diese Funktion in Ihren Browsereinstellungen oder verwenden Sie einen anderen Web-Browser mit aktiviertem JavaScript.
        </noscript>
        <at-erwerbstaetigkeit
            ags="12345678"
            language-selection
            excluded-languages="ru, tr"
            hide-login="false"
            plz-check
            hide-page-nav="true"
            page-nav-position="left"
        ></at-erwerbstaetigkeit>
        <script src="https://api.service-digitale-verwaltung.de/embed/at-erwerbstaetigkeit/at-erwerbstaetigkeit.js" charset="UTF-8"></script>
    </body>
</html>
  • hide-login wird nur bei at-germany-for-ukraine und at-erwerbstaetigkeit (Default: true) unterstützt (s. auch Kapitel Attribute).
  • Wenn hide-page-nav="true", dann ist page-nav-position="left" obsolet. Es wurde trotzdem beides aufgeführt um alle Konfigurationsmöglichkeiten aufzuzeigen.
  • excluded-languages wird nur in Diensten des Ausländerwesens (at-*, aw-*) unterstützt. (Außer aw-einbuergerung.)

Maximale Konfiguration am Beispiel ewaffe-gruene-wbk-person-erteilung mit dem AGS 12345678.







 
 


 
 














<html lang="de">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Erteilung grüne Waffenbesitzkarte für einzelne Person</title>
        <link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/tf-blue.css">
        <script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js"></script>
    </head>
    <body style="margin-top: 4rem;">
        <noscript>
            Für die Verwendung dieses Dienstes ist JavaScript erforderlich.
                Bitte aktivieren Sie diese Funktion in Ihren Browsereinstellungen oder verwenden Sie einen anderen Web-Browser mit aktiviertem JavaScript.
        </noscript>
        <ewaffe-gruene-wbk-person-erteilung
            ags="12345678"
            language-selection
            hide-login="false"
            plz-check
            hide-page-nav="true"
            page-nav-position="left"
        ></ewaffe-gruene-wbk-person-erteilung>
        <script src="https://api.service-digitale-verwaltung.de/embed/ewaffe-gruene-wbk-person-erteilung/ewaffe-gruene-wbk-person-erteilung.js" charset="UTF-8"></script>
    </body>
</html>

# Test-Umgebung

In den Code-Beispielen wird die Produktiv-Umgebung (api.service-digitale-verwaltung.de) verwendet.

Zum Testen steht Ihnen auch unsere Pre-Produktiv-Umgebung unter api.pre-service-digitale-verwaltung.de zur Verfügung. Bitte beachten Sie hierbei jedoch, dass es sich um ein Test-System handelt, auf dem eine neuere Version also auf der Produktiv-Umgebung installiert sein kann. Außerdem kann es hier gelegentlich zu kürzeren Wartungsarbeiten kommen, währenddessen das System nicht wie gewohnt reagiert.







 
 


 
 



<!DOCTYPE html>
<html lang="de">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Testumgebung - Beispiel ABH Webauftritt</title>
	<link rel="stylesheet" href="https://api.pre-service-digitale-verwaltung.de/embed/themes/tf-blue.css">
	<script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js"></script>
</head>
<body style="margin-top: 4rem;">
	<at-erwerbstaetigkeit ags="09000001"></at-erwerbstaetigkeit>
	<script src="https://api.pre-service-digitale-verwaltung.de/embed/at-erwerbstaetigkeit/at-erwerbstaetigkeit.js" charset="UTF-8"></script>
</body>
</html>

Wichtig: Dieses Beispiel zeigt, wie ein Dienst von der Pre-Produktiv-Umgebung eingebunden werden kann. Der AGS muss durch den Betreiber des Dienstes für Ihre Domain auf der Pre-Produktiv-Umgebung unabhängig von der Produktiv-Umgebung freigegeben werden.

# Themes

Ein Theme kontrolliert das Aussehen und die grafischen Eigenschaften der Seiten.

Es stehen die folgenden Themes zur Verfügung:

  • default.css: Die primären Farben des Layouts werden in einem grünlichen Ton gehalten
  • bb-red.css: Die primären Farben des Layouts werden in einem roten Ton gehalten
  • tf-blue.css: Die primären Farben des Layouts werden in einem blauen Ton gehalten

Für eine Anpassung des Themes muss der theme-name entsprechend geändert werden.


<link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/theme-name.css">

Beispiel: Nutzung des bb-red.css Themes.


<link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/bb-red.css">

# Browser-Kompatibilität

Die Datei polyfill.js lädt je nach Browser die entsprechenden Polyfills zur Erhöhung der Browser-Kompatibilität nach. Wichtig ist, dass diese Datei eingebunden wird bevor die Webkomponente geladen wird. Für den Internet Explorer 11 und den Edge Legacy ist der Dienst nicht mehr verfügbar. Stattdessen wird dem Nutzer eine entsprechende Meldung angezeigt.

Wie in obigen Code-Beispielen gezeigt, kann der Polyfill wie folgt eingebunden werden:


<script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js"></script>

# Spracheinstellung

Für die Steuerung der Sprache verwendet die Web-Komponente das lang Attribut aus dem html Element.

Steuerung der Sprache über das lang Attribut. In diesem Fall wird die englische Sprache verwendet.


<html lang="en">

Gesamtbeispiel für die Steuerung der Sprache. In diesem Beispiel wird der Dienst at-erwerbstaetigkeit unter dem AGS 09000001 in englischer Sprache verwendet.


 













<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Beispiel ABH Webauftritt</title>
	<link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/tf-blue.css">
	<script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js"></script>
</head>
<body style="margin-top: 4rem;">
	<at-erwerbstaetigkeit ags="09000001"></at-erwerbstaetigkeit>
	<script src="https://api.service-digitale-verwaltung.de/embed/at-erwerbstaetigkeit/at-erwerbstaetigkeit.js" charset="UTF-8"></script>
</body>
</html>

Sollte es nicht möglich sein, das lang Attribut auf dem html Element wie hier beschrieben zu setzen. Kann eine Sprachauswahl innerhalb des Dienstes bereitgestellt werden. Dies führt allerdings dazu, dass die Webseite und der eingebettete Dienst in unterschiedlichen Sprachen angezeigt werden und sollte deshalb vermieden werden.

Weitere Informationen dazu finden Sie im Abschnitt Attribute.

# JavaScript

Für die Einbindung und Funktionsweise der Dienste wird JavaScript benötigt.

Damit der Benutzer einen entsprechenden Hinweis bekommt, falls in seinem Browser JavaScript deaktiviert sein sollte, empfiehlt sich die Verwendung eines noscript Elementes.

Beispiel: Nutzung des noscript Elementes.







 
 
 
 




<!DOCTYPE html>
<html lang="de">
<head>
	<!-- ... -->
</head>
<body style="margin-top: 4rem;">
    <noscript>
        Für die Verwendung dieses Dienstes ist JavaScript erforderlich.
        Bitte aktivieren Sie diese Funktion in Ihren Browsereinstellungen oder verwenden Sie einen anderen Browser.
    </noscript>
    <!-- ... -->
</body>
</html>

# Seitenbreite

Damit die Komponenten auch auf Geräten mit geringer Breite (z. B. Smartphones) gut aussehen und ein positives Nutzererlebnis gewährleisten können, verhalten sich die Komponenten responsiv. Dies ist allerdings nur möglich, wenn auch die Seite sich responsiv verhält.

Steht also nur ein kleiner Container (<1080px) zur Verfügung, kann die Einbindung der Komponente mit folgenden Schritten optimiert werden:

  • Webseite so vorbereiten, sodass links und rechts der Komponente, wenn möglich keine anderen Elemente (z. B. Navigation, Widgets) vorhanden sind
  • Ausblenden der Störungsmeldung ("html.stoerungsmeldung": "$hidden")
  • Ausblenden der Seiten-Navigation (HTML-Attribut hide-page-nav, siehe Attribute)

# Attribute

Name Beschreibung Pflichtangabe Standardwert
ags Der Allgemeine Gemeindeschlüssel der Kommune Ja
page-nav-position Steuert, wo die Seitennavigation angezeigt werden soll. Mögliche Werte: left, right oder top. Diese Option muss bei Verwendung von aw-einbuergerung auf top-progress gesetzt werden. Nein left
hide-page-nav Steuert, ob die Seitennavigation ausgeblendet werden soll. Mögliche Werte: true oder false. Nein false
language-selection Steuert, ob die Sprachauswahl angezeigt werden soll. Parameter ohne Wert (Beispiel-Verwendung: <at-erwerbstaetigkeit language-selection>). Die Vorauswahl der Sprache kann, wie im Kapitel Spracheinstellung beschrieben, bestimmt werden. (Außer aw-einbuergerung.) Nein Sprachauswahl ausgeblendet
excluded-languages Steuert, welche Sprachen in der Sprachauswahl nicht angezeigt werden sollen. Beispiel-Verwendung: <at-erwerbstaetigkeit excluded-languages="ru,tr" />. Nein Keine Sprache ist ausgeschlossen
plz-check Steuert, ob der Verfügbarkeitscheck angezeigt werden soll. Parameter ohne Wert (Beispiel-Verwendung: <at-erwerbstaetigkeit plz-check>). Nein Verfügbarkeitscheck ausgeblendet
hide-login Steuert, ob die Anmelde-Funktion angezeigt wird, falls der Dienst diese unterstützt. Diese Option ist derzeit nur bei den Diensten at-germany-for-ukraine und at-erwerbstaetigkeit verfügbar. Bei at-erwerbstaetigkeit wird die Anmelde-Funktion nur dann angezeigt wenn hide-login="false" angegeben wurde. Nein at-erwerbstaetigkeit: Anmelde-Funktion ausgeschaltet
kommunalportal Steuert, ob der Dienst innerhalb des Kommunalportals betrieben wird. Bei dem Wert auto wird geprüft, ob die Domain der einbindenden Seite auf .kommunalportal.nrw endet. Mögliche Werte: true, false oder auto. Diese Option ist derzeit nur beim Dienst aw-einbuergerung verfügbar. Nein auto
feature-set Steuert, ob zukünftige Funktionen aktiviert werden sollen. Mögliche Werte: stable (Nur veröffentlichte funktionen), next (Änderungen die für einen der nächsten Releases vorgesehen sind) oder future (Änderungen, die zeitlich noch nicht eingeplant sind). Diese Option muss bei Verwendung von aw-einbuergerung außerhalb des Kommunalportals auf next gesetzt werden. Nein stable

# Bündelungskomponente (aw-buendelungskomponente)

Die Bündelungskomponente ist eine Übersichtsseite mit mehreren Diensten, auf der der Benutzer den gewünschten Dienst auswählt. Sie erleichtert das Einbinden für Kommunen, da nicht mehr jeder Dienst einzeln eingebunden werden muss. Stattdessen wird nur die Bündelungskomponente eingebunden und dabei konfiguriert, welche Dienste sichtbar sind.
Die Bündelungskomponente unterstützt zurzeit nur die Dienste des Ausländerwesens (at-*, aw-*).

  • Normalerweise wird ein Dienst direkt über die Bündelungskomponte eingebunden
  • Es ist aber auch möglich, jedoch nicht notwendig, den gleichen Dienst einmal direkt und einmal über die Bündelungskomponente einzubinden.

Hinweis zur Migration: Kommunen die schon einen oder mehrere Dienste eingebunden haben, können die Seiten parallel betreiben. Es ist aber auch möglich die bisherigen Seiten komplett durch die Bündelungskomponenten zu ersetzen. Die Texte der Dienste bleiben bestehen und sind bei jeder Variante gleich.

# Standard-Dienste

Folgende Dienste werden automatisch eingebunden (sofern nicht anders konfiguriert, s. Attribut hide-services):

  • at-ausbildung
  • at-erwerbstaetigkeit
  • at-familiennachzug
  • at-nebenbestimmungen

# Sprachen & Texte

Es stehen alle Sprachen zur Verfügung, die auch für die Standard-Dienste zur Verfügung stehen.

Die Texte der Bündelungskomponente selbst können wie gewohnt über das "OZG Service Management" gepflegt werden.

# Attribute (Bündelungskomponente)

Neben den Standardatttributen hat die Bündelungskomponente einige spezielle Attribute:

Name Beschreibung Pflichtangabe Standardwert
ags S. Kapitel Attribute s.o. s.o.
hide-services Steuert, welche der Standard-Dienste nicht angezeigt werden. Mögliche Werte (Standard-Dienste): at-ausbildung, at-erwerbstaetigkeit, at-familiennachzug, at-nebenbestimmungen Nein Alle Standard-Dienste werden angezeigt
add-services Steuert, welche Dienste zusätzlich zu den Standard-Diensten angezeigt werden. Bsp.: aw-aufenthaltskarte,at-fachkraefteverfahren,... Nein Keine Zusatz-Dienste werden angezeigt
hide-login-services Steuert, bei welchen Diensten die Anmeldung nicht möglich ist. Bsp.: at-familiennachzug,at-nebenbestimmungen,... Nein In allen Diensten ist die Login-Funktion verfügbar
language-selection-services Steuert, für welche Dienste die Sprachauswahl angezeigt wird. Bsp.: at-ausbildung,at-nebenbestimmungen,... Nein Keine Dienste können Sprachen auswählen
language-selection Steuert, ob die Sprachauswahl in der Bündelungskomponente angezeigt wird. s.o. s.o.
excluded-languages Steuert, welche Sprachen in der Sprachauswahl nicht angezeigt werden sollen. Beispiel-Verwendung: <at-erwerbstaetigkeit excluded-languages="ru, tr" />. Nein Keine Sprache ist ausgeschlossen
hide-page-nav-services Steuert, für welche der verfügbaren Dienste die Seitennavigation nicht angezeigt wird. Bsp.: at-ausbildung,at-erwerbstaetigkeit,... Nein In allen Diensten wird die Navigation angezeigt
page-nav-position-services Steuert, pro Dienst, an welcher Position die Seitennavigation angezeigt wird. Bsp.: at-ausbildung:right,at-erwerbstaetigkeit:top,.... Nein left für alle Dienste
plz-check-services Steuert, für welche Dienste der Verfügbarkeitscheck angezeigt wird. Bsp.: at-ausbildung,at-nebenbestimmungen,... Nein Verfügbarkeitscheck ausgeblendet für alle Dienste

# Beispiel Einbindung







 
 


 
 





...
    
<aw-buendelungskomponente 
    hide-services=""
    hide-login-services=""
    language-selection-services="at-ausbildung,at-erwerbstaetigkeit,at-fachkraefteverfahren,at-familiennachzug,at-germany-for-ukraine,at-nebenbestimmungen,at-niederlassungserlaubnis,aw-aufenthaltskarte,aw-beschaeftigungserlaubnis"
    hide-page-nav-services=""
    add-services="aw-aufenthaltskarte"
    page-nav-position-services="at-ausbildung:right"
    plz-check-services="at-ausbildung,at-erwerbstaetigkeit"
    ags="..."
    language-selection
    excluded-languages="ru, tr"
></aw-buendelungskomponente>

...

# Sicherheit

Sie können folgende Header auf der Website verwenden, in die Sie Webkomponenten einbetten. Ersetzen Sie digitale-verwaltung-as-a-service.de durch Ihren tatsächlichen Domainnamen.

Name Wert
Referrer-Policy strict-origin-when-cross-origin
X-Content-Type-Options nosniff
X-Frame-Options sameorigin
X-XSS-Protection 1; mode=block
Content-Security-Policy default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' digitale-verwaltung-as-a-service.de api.pre-service-digitale-verwaltung.de api.service-digitale-verwaltung.de; style-src 'self' 'unsafe-inline' digitale-verwaltung-as-a-service.de api.pre-service-digitale-verwaltung.de api.service-digitale-verwaltung.de; img-src 'self' blob: digitale-verwaltung-as-a-service.de data: digitale-verwaltung-as-a-service.de api.pre-service-digitale-verwaltung.de api.service-digitale-verwaltung.de; form-action *; connect-src 'self' blob: digitale-verwaltung-as-a-service.de api.pre-service-digitale-verwaltung.de api.service-digitale-verwaltung.de; upgrade-insecure-requests; block-all-mixed-content
Feature-Policy accelerometer 'none'; battery 'none'; display-capture 'none'; geolocation 'none'; gyroscope 'none'; microphone 'none'; web-share 'none'; payment 'self'
Permissions-Policy accelerometer 'none'; battery 'none'; display-capture 'none'; geolocation 'none'; gyroscope 'none'; microphone 'none'; web-share 'none'; payment 'self'

Jeder Dienst kann zusätzliche Anforderungen an die Security-Header haben, die über dieses empfohlene Minimum hinausgehen. Es ist anzumerken, dass die Anforderungen jedes erforderlichen Dienstes die Sicherheitsanforderungen stark verändern können.

# Kontakt

Bei Fragen, Problemen oder Rückmeldungen wenden Sie sich bitte an den folgenden Kontakt: