Funktionaler Anforderungsrahmen

Der Anforderungsrahmen der funktionalen Architektur ist von den zu Abläufen vorgegeben. Diese sind High Level in folgenden Business-Szenarien (business scenario) organisiert:

• Verfügbarkeit Produkte und Termine

• Neubereitstellung
• Abrechnung
• Kündigung
• Änderung
• Entstörung/Problembehebung
• Vorabstimmung

Diese Business-Szenarien (business scenario) strukturieren und kategorisieren die zu unterstützenden Prozesse (process) (siehe 1. Scope).

In einer High Level Analyse sind die fachlichen Fähigkeiten (business capabilities) der funktionalen Architektur, und somit die benötigten API Domänen , im Kontext der Business-Szenarien (business scenario) identifiziert (siehe Business Szenarien maps Open API). 

In der detaillierten Analyse sind die Interaktionen zwischen Auftraggeber und Leistungserbringer im Rahmen konkreter Anwendungsfälle (use case) erfasst und das Design der einzelnen APIs erstellt (siehe 4. API Design)

Die Übersicht des Vorgehensmodells ist auf der Seite Vorgehensmodell dokumentiert 

High Level Prinzipien

Datenzentrische Prozesse 

Das Konzept der datenzentrische Prozesse ermöglicht dynamische, flexible Abläufe auf Basis klar definierter und abgegrenzter Verantwortungsbereiche (API Domäne).

Beispielhafte Darstellung:

Folgende Eigenschaften sind hervorzuheben:

• Jede API Domäne hat, bezogen auf das Datenmodell, einen definierten Verantwortungsrahmen an verwalteten Daten (API Resources).

• Der Bezug auf Daten (API Resources) aus anderen Domänen ist, als Beziehung definiert und somit ohne Datenredundanz realisiert.

• Die an den Datenbereichen unterstützten Fähigkeiten sind in den jeweiligen API Domänen gekapselt
• Alle relevanten Ergebnisse sind an den API Resources dokumentiert und somit auch ohne Kenntnis der vorherigen Arbeitsschritte nachvollziehbar (stateless)
• Die Daten der jeweiligen API Domänen bilden somit den "Referenzpunkt der Wahrheit" (Single Source of Truth)

Status und Lifecycle

• Daten in den API Domänen unterstützen langläufige Prozesse und haben somit einen Lifecycle.
• Zu jedem Zeitpunkt im Lifecycle ist der Zustand der API Resource in der Zustandseigenschaft (state) festgehalten und somit nachvollziehbar
• Alle mögliche Zustandsübergange werden im Lifecycle Model der API Resources definiert

Beispiel Trouble Ticket Lifecycle (TMF621):

Normalisierte Lifecycle, sind zusätzlich zum Open API Datenmodell, ein wichtiges Werkzeug der API Standardisierung, da diese die Client relevanten Stände und Übergänge der gekapselte Business Logik fest definiert. 

Langläufige Prozesse

Lifecycle der API Resources bzw. Prozesse welche auf diese Daten aufbauen sind typischerweise langläufig. Der Auftraggeber (Client) kann diese Prozesse, mit dem Anlegen einer API Resource, anstoßen (zB. Auftrag anlegen). Während der Ausführung des Prozesses, im Rahmen des Lifecycle der API Resource, sind auch weitere Interaktionen zwischen Auftraggeber (Client) und Leistungserbringer (Provider) zu unterstützen:

• Leistungserbringer (Provider) → Auftraggeber (Client): Leistungserbringer (Provider) dokumentiert alle relevante Ereignisse an der API Resource und meldet diese an den Auftraggeber (Client)
• Auftraggeber (Client) → Leistungserbringer (Provider): Der Auftraggeber (Client) kann auf den laufenden Prozess, anhand vordefinierter Task Resources, einwirken

Meldungen

Meldungen werden für folgende Ereignistypen generiert:

• Anlegen und Löschen einer API Resource (CreateEvent & DeleteEvent)
• Zustandsänderung der API Resource (StateChangeEvent)
• Inhaltliche Änderung einer API Resource Eigenschaften (AttributeValueChangeEvent)
• Anfrage an den Client zur weiteren Verarbeitung (InformationrequiredEvent). Typischerweise antwortet der Client hier anhand einer Task Resource

Um robuste Prozesse zu implementieren, werden alle Ereignisse an der API Resource dokumentiert. Somit kann sich der Auftraggeber mit einem Aufruf der API Resource (GET) auch ohne Kenntnis der Historie, synchronisieren 

Meldungen werden vom Leistungserbringer an einen definierten Endpunkt des Auftraggebers versendet (POST Event)

Bemerkung: Für das erste FIT Release werden die Listener der Auftraggeber fest vordefiniert. Somit ist keine Anmeldung (POST Hub) notwendig.

Task Resources

Um die möglichen Eingriffe des Auftraggebers auf laufenden Prozess des Leistungserbringers, in einem kontrollierten Rahmen zu ermöglichen, werden fest definierte Task Resources unterstützt.

Eine Task Resource qualifiziert genau einen Task welche der Auftraggeber an der API Resource ausführen möchte, wie zB. CancelProductOrder um einen Auftrag zu stornieren. Diese Task Resource muss vom Auftraggeber angelegt werden, um den Task anzustoßen. 

source

Eine Task Resource ist auch eine Resource ist, die abgefragt werden kann und der Payload der Task Resource steht in der Resource. Jeder Typ von Task hat somit seine eigene Resource.

High Level Information Model

Übersicht

• Party (AG): Endkundeninformationen sind für Bereitstellungen und Entstörungen notwendig (zB. Technikertermine). Diese können als Werte mitgeliefert werden. API ist somit für die Prozess-Unterstützung nicht zwingend notwendig.
• Party (LE): Kunden und Vertragsinformationen sind für Bereitstellungen und Entstörungen notwendig, eine Referenz ist aber in der Regel ausreichend (fachlicher Schlüssel oder Resource.id). API ist somit für die Prozess-Unterstützung nicht zwingend notwendig. 
• Agreement: siehe oben
• Product Catalog: Für dieses FIT Release wurde entschieden die notwendigen Produktstrukturen, als Schema in den APIs zu definieren. Die vorab abgestimmten Produktangebote können dann als Referenzen mit den Aufträgen mitgeliefert werden. Somit ist eine aktive Abfrage des Produktkataloges nicht zwingend notwendig. Die FIT API Spezifikationen unterstützen aber den katalogbasierten Ansatz und dieser kann, ohne weitere Anpassung der APIs eingeführt werden. 
• Service: Die Referenz des Services ist notwendig um den Service-Test und die Service-Aktivierung anstoßen zu können, Einen aktive Abfrage des Service Bestandes ist aber nicht im Rahmen der analysierten Prozesse notwendig,
• Resource: Referenzen auf Resources wie HomeId, ONT, Leistungsübergabepunkt können Aufträge notwendig sein. Falls eine einfache Referenz nicht ausreichend ist, können Informationen auch als Werte mitgeliefert werden. Ausnahme = Leistungsübergabepunkt (ServiceAccessPoint) welcher im Rahmen der Verfügbarkeit

Grundstruktur einer API Resource

API Resources (in der Abblidung als <Entity> dargestellt) bauen auf übergreifende Patterns auf

Das Resource Model definiert den Verantwortungsbereich der API und die Beziehungen auf Resources anderer APIs.

Abbildung der Produkte

Einer der Grundprinzipien der TMF API Ressource Modelle ist eine generische und produktagnostische Grundstruktur anzubieten, auf welcher die produktspezifische Informationen ergänzt werden können. Diese Trennung der generischen und portfolioagnostischen Grundstrukturen vs. der portfoliospezifische Informationen wird über die Nutzung der Portfolio Entitäten "Product" - "Service" - "Resource" erreicht - primär über die "Product" Entität, da die Interaktionen im Anforderungsrahmen sich primär auf Produkte beziehen.

TMF API Modelle stellen zwei Möglichkeiten zur Verfügung, um portfoliospezifische Informationen abzubilden:

• Characteristics
• Strongly-typed extensions

Portfoliospezifische Informationen als Characteristics

Produkt-Eigenschaften werden anhand von Characteristics (name-value pairs) abgebildet. Die Bildungsregeln dieser Eigenschaften werden über die Characteristic Spezifikationen im Katalog gesteuert (ProductSpecificationCharacteristic). Diese Struktur ist sehr generisch und flexible, bedingt aber, dass die Characteristic Spezifikationen im Katalog aufrufbar sind (TMF620 Product Catalog für ProductSpecification) 

Portfoliospezifische Informationen als strongly-typed extensions

Produkt-Eigenschaften werden als zuzätzliche Properties an der Product Entitäten abgebildet. Diese Properties werden als Erweiterung, in einem spezifischen Schema festgehalten.  Dieses Schema bzw. diese Schemas für mehrere Produkte, können bestandteil der OAS (Open API Specification) sein oder separat aufrufbar (Schema Location) zur Verfügung gestellt werden.

Ansatz FIT APIs

In der Abbildung der FIT APIs, wurde der Ansatz gewählt, Produkt-Eigenschaften als strongly-typed extensions abzubilden und die Erweiterungs-Schemas in den OAS mit zu liefern. Dennoch werden auch alle Katalog-orienterte Entitäten parallel mitunterstützt, um den Parteien die Möglichkeit offenzulassen, bilateral einen katalogbasierten Ansatz zu implementieren.

API Domains

Folgende Darstellung gibt einen Überblick der Informationsbereiche und der API Domänen welche diese Informationsbereiche verantworten.

Die Anwendung der APIs im Kontext der verschiedenen Business Szenarien ist auf der dedizierten Seite (Business Szenarien maps Open API) zu finden