Version

1.0.0

Onlinedienst Links

Fachliche Kategorie	Technische Kategorie
Onlinedienst-bezogener Standardparameter	XZuFi-basierte Standard-Parameter mit direktem Onlinedienst-Bezug

Fachliche Bedeutung

Links, über die der Onlinedienst erreichbar ist, zusammen mit einigen Meta-Daten der Links

Wertemenge

Internationalisierte Datenstruktur OnlinedienstLink. Die Datenstruktur enthält die folgenden Elemente:

• typ: der Typ des Links codiert als Code der Code-Liste urn:xoev-de:fim:codeliste:onlinedienstlinktyp
• link: URL zum Onlinedienst inklusive der URL-Parameter. Vorhandene dynamische Parameter müssen zusätzlich hinzugefügt werden.
• dynamischeParameter: Parameter, welche während des Renderns der Links je nach Kontext dynamisch belegt werden. Sie enthalten jeweils ein Paar aus folgenden Elementen:
  • typ: Der Typ des dynamischen Parameters codiert als Code der Code-Liste urn:xoev-de:fim:codeliste:xzufi.onlinedienstdynamischerparametertyp
  • parameterName: Der Name des dynamischen Parameters
• titel: Titel der URI
• beschreibung: Beschreibung der URI, z.B. kurze Hinweise zur Zielseite
• positionDarstellung: Position in der gesamten Darstellung der Links

Als dynamische Parameter sind die folgenden Typen in der Code-Liste definiert:

Code	Beschreibung
001	Leistung
002	Gebiet
003	Organisationseinheit
004	LeiKa-Leistung
005	Formular
006	Sprache

Über den Mechanismus des Elements dynamischeParameter wird parametrisiert, wie der Onlinedienst aufgerufen werden muss. Ist z.B. ein OnlinedienstLink parametrisiert, bei dem link den Wert https://example.com/mein_online_dienst hat und dynamischeParameter ein Werte-Paar aus typ = 005 und parameterName = applicationform enthält, dann muss ein Aufrufer den Onlinedienst mit der URL https://example.com/mein_online_dienst?applicationform=PassierscheinA38 aufrufen, falls PassierscheinA38 das passende Formular (Code 005!) für den Anwendungsfall ist.

Die Datenstruktur lässt es über das Element positionDarstellung zu, mehrere fachlich unterscheidbare Links internationalisiert zu definieren. So ist es möglich z.B. vier Elemente anzugeben, bei denen die Werte von positionDarstellung und languageCode (i.e. das Internationalisierungs-Attribut von OnlinedienstLink) wie folgt belegt sind:

• Element 1: positionDarstellung = "1", languageCode = "de"
• Element 2: positionDarstellung = "2", languageCode = "de"
• Element 3: positionDarstellung = "1", languageCode = "en"
• Element 4: positionDarstellung = "2", languageCode = "en"

Elemente 1 und 3 bilden zusammen den ersten internationalisierten Link, der an erster Position in einer Liste dargestellt werden soll. Elemente 2 und 4 bilden hingegen einen zweiten internationalisierten Link, der an zweiter Position in der Liste angezeigt werden soll. Ist die Spracheinstellung aktuell "Englisch", soll der Onlinedienst in einer Liste zuerst Element 3 und dann Element 4 darstellen.

Verortung im Datenmodell

Die Onlinedienst Links werden in potenziell mehrfach vorhandenen Elementen link im Datenobjekt Onlinedienst abgelegt.

Codebeispiel XZuFi 2.2

info

• Das folgende Codebeispiel zeigt nicht alle Features des link-Elements
• Laut XZuFi 2.2 Spezifikation ist das Element beschreibung vom Datentyp xs:string und soll eine "Beschreibung der URI, z.B. kurze Hinweise zur Zielseite" enthalten. Die Spezifikation macht keine Aussage darüber, ob darin enthaltene HTML-Elemente korrekt verarbeitet werden.

<xzufi:onlinedienst xmlns:p3="http://www.w3.org/2001/XMLSchema-instance"
    p3:type="xzufi:OnlinedienstErweitert">
    
    <xzufi:link languageCode="de">
        <xzufi:typ listURI="urn:xoev-de:fim:codeliste:onlinedienstlinktyp" listVersionID="1">
            <code>01</code>
        </xzufi:typ>
        <xzufi:link>https://serviceportal.hamburg.de/HamburgGateway/Service/Entry/AFM-KitaG</xzufi:link>
        <xzufi:titel>Kita-Gutschein</xzufi:titel>
        <xzufi:beschreibung>Kita-Gutschein</xzufi:beschreibung>
    </xzufi:link>
    <xzufi:link languageCode="en">
        <xzufi:typ listURI="urn:xoev-de:fim:codeliste:onlinedienstlinktyp" listVersionID="1">
            <code>01</code>
        </xzufi:typ>
        <xzufi:link>https://serviceportal.hamburg.de/HamburgGateway/Service/Entry/AFM-KitaG</xzufi:link>
        <xzufi:beschreibung>Daycare voucher</xzufi:beschreibung>
    </xzufi:link>

</xzufi:onlinedienst>

Ermittlungsmöglichkeit PVOG API

Zunächst muss das zuständige Onlinedienst-Datenobjekt ermittelt werden. Siehe dazu Abschnitt Ermittlung eines zuständigen Onlinedienst-Datenobjektes mit Hilfe der PVOG-API.

Die Response, die der Endpunkt /v2/onlineservices/detail zurückgibt, enthält ein Element links[], das vereinfachte Abbildungen der XZuFi-Datenstruktur OnlinedienstLink enthält. Durch die Vereinfachung können die Informationen der Sprache nicht mehr ermittelt werden und die Information aus positionDarstellung kann ebenfalls nicht ermittelt werden.

Die Suchdienst-API unterstützt den "Accept-Language" HTTP-Header. Mit diesem kann man bei der Anfrage z.B. steuern, welche Links tatsächlich in der Response enthalten sind. Gibt man z.B. beim Request den HTTP-Header "Accept-Language: en" an, so gibt die API nur die Link-Elemente aus dem PVOG zurück, deren languageCode-Elemente den Wert "en" haben.

warnung

Die PVOG Suchdienst-API implementiert keinen Fallback-Mechanismus, der die deutschen OnlinedienstLink-Elemente liefert, wenn im Accept-Language-Header eine Sprache angegebenen ist, die nicht in den Elementen Onlinedienst.sprachversion verzeichnet ist. Es ist daher wichtig, dass diese Angabe nur solche Sprachen enthält, für die alle internationalisierten Elemente vollständig vorhanden sind.

Die Angabe der Position wird nicht mehr an den Onlinedienst weitergegeben, sondern nur intern als Diskriminator ausgewertet, um die verschiedenen Sprach-Versionen der Links einander korrekt zuordnen zu können.

Ermittlungsmöglichkeit FIT-Connect Routing API

(Der Parameter kann nicht über den FIT-Connect Routing-Dienst ermittelt werden)

Ermittlungsmöglichkeit DVDV API

(Der Parameter kann nicht über das DVDV-API ermittelt werden)

Best Practices

(keine Empfehlungen)