# 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-eheurkunde ewaffe-gruene-wbk-person-erteilung
at-erwerbstaetigkeit pw-geburtsurkunde ewaffe-rote-wbk-erteilung
at-familiennachzug pw-lebenspartnerschaftsurkunde ewaffe-gelbe-wbk-sportschuetze-erteilung
at-germany-for-ukraine pw-sterbeurkunde
at-nebenbestimmungen Führerscheinwesen
aw-aufenthaltskarte fw-umtausch-altfahrerlaubnis
aw-einbuergerung
aw-buendelungskomponente

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.

# 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. 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. Nein Sprachauswahl ausgeblendet
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 aw-einbuergerung und at-erwerbstaetigkeit verfügbar. Ist die aw-einbuergerung im Kommunalportal eingebunden, so wird die Anmelde-Funktion innerhalb der Applikation nicht angezeigt. Ansonsten wird sie standardmäßig angezeigt sofern hide-login nicht gesetzt wurde. Bei at-erwerbstaetigkeit wird die Anmelde-Funktion nur dann angezeigt wenn hide-login="false" angegeben wurde. Nein aw-einbuergerung: Anmelde-Funktion eingeschaltet, 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 ist derzeit nur beim Dienst aw-einbuergerung verfügbar. 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 standardmäßig verfügbaren 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 standardmäßig verfügbaren Dienste angezeigt werden. Beispiele: aw-aufenthaltskarte Nein Keine Zusatz-Dienste werden angezeigt
language-selection S. Kapitel Attribute s.o. s.o.
page-nav-position-services Ersetzt page-nav-position. Steuert, wo die Seitennavigation angezeigt werden soll. Bsp.: at-ausbildung:right,at-erwerbstaetigkeit:top Nein left für alle Dienste
plz-check-services Ersetzt plz-check. Steuert, ob der Verfügbarkeitscheck angezeigt werden soll. Format: Komma-getrennte Liste an Diensten, die den Verfügbarkeitscheck angezeigen sollen. Nein Verfügbarkeitscheck ausgeblendet für alle Dienste

# Beispiel Einbindung







 
 


 
 

...
    
<aw-buendelungskomponente 
    hide-services=""
    add-services="aw-aufenthaltskarte"
    page-nav-position-services="at-ausbildung:right"
    plz-check-services="at-ausbildung,at-erwerbstaetigkeit"
    ags="..."
    language-selection
></aw-buendelungskomponente>

...

# Kontakt

Bei Fragen, Problemen oder Rückmeldungen wenden Sie sich bitte an den folgenden Kontakt: rollout-dv@akdb.de