From 70a64ae20e08bfe1dc5ee64727d33c5122ff191e Mon Sep 17 00:00:00 2001
From: Marco Holz <marco.holz@fitko.de>
Date: Sun, 31 Jul 2022 18:58:58 +0200
Subject: [PATCH] Add descripion of ARS and AGS
---
docs/details/ags.mdx | 7 +++++
docs/details/ars.mdx | 32 ++++++++++++++++++++
docs/details/authentication/scopes-sender.md | 14 +--------
docs/glossary.md | 2 ++
docs/responsibilities/get-destination.mdx | 2 +-
sidebar.js | 2 ++
6 files changed, 45 insertions(+), 14 deletions(-)
create mode 100644 docs/details/ags.mdx
create mode 100644 docs/details/ars.mdx
diff --git a/docs/details/ags.mdx b/docs/details/ags.mdx
new file mode 100644
index 000000000..1f4595bd7
--- /dev/null
+++ b/docs/details/ags.mdx
@@ -0,0 +1,7 @@
+---
+title: Amtlicher Gemeindeschlüssel (AGS)
+---
+
+Der achtstellige Amtliche Gemeindeschlüssel (AGS) ist Vorgänger des [Amtlichen Regionalschlüssels (ARS)](./ars.mdx) und beschreibt eine Systematik zur Identifizierung der sogenannten _verwaltungspolitischen Gebiete_ in Deutschland - also Gemeinden, Kreise, Regierungsbezirke und Bundesländer.
+
+Die netten Menschen von [Datenguide](https://datengui.de/) haben eine sehr schöne Darstellung und Beschreibung des Amtlichen Gemeindeschlüssels erstellt. Wir hätten es nicht besser erklären können und verweisen daher an dieser Stelle einfach auf den [Artikel zum AGS von Datenguide](https://datengui.de/statistik-erklaert/ags).
diff --git a/docs/details/ars.mdx b/docs/details/ars.mdx
new file mode 100644
index 000000000..c33d81926
--- /dev/null
+++ b/docs/details/ars.mdx
@@ -0,0 +1,32 @@
+---
+title: Amtlicher Regionalschlüssel (ARS)
+---
+
+Der zwölfstellige [Amtliche Regionalschlüssels (ARS)](https://de.wikipedia.org/wiki/Amtlicher_Gemeindeschl%C3%BCssel#Regionalschl%C3%BCssel) löst den [Amtlichen Gemeindeschlüssel (AGS)](./ags.mdx) ab und erweitert ihn um einen Verbandsschlüssel. Der ARS ist wie folgt aufgebaut:
+
+```
+1.–2. Stelle = Kennzahl des Bundeslandes
+3. Stelle = Kennzahl des Regierungsbezirks; wenn nicht vorhanden: 0
+4.–5. Stelle = Kennzahl des Landkreises oder der kreisfreien Stadt
+6.–9. Stelle = Verbandsschlüssel
+10.–12. Stelle = Gemeindekennzahl
+```
+
+Eine Liste der amtlichen Regionalschlüssel findet sich im [Gemeindeverzeichnis des Statistischen Bundesamtes](https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/_inhalt.html) sowie im [XRepository](https://www.xrepository.de/details/urn:de:bund:destatis:bevoelkerungsstatistik:schluessel:rs).
+
+:::tip Hinweis
+Eine interaktive Suche nach Amtlichen Regionalschlüsseln ermöglicht das [ARS-Tool](https://opengovtech.de/ars/) (Link geht zu externem Dienst).
+:::
+
+**Beispiel**: Mit der Angabe des zwölfstelligen ARS `081150045045` kann die Stadt Sindelfingen eindeutig adressiert werden:
+
+Werden nicht alle zwölf Stellen des ARS angegeben, sondern nur ein Prefix des ARS, so können statt einer spezifischen Gemeinde auch darüberliegende Kreise, Regierungsbezirke oder Bundesländer abgebildet werden.
+Wird ein solcher Prefix eines ARS angegeben, schließt dieser alle sich darin befindlichen Gliederungen mit ein.
+
+**Beispiel**: Der ARS `081` steht für den Regierungsbezirk Stuttgart und schließt den darunterliegenden Stadtkreis Stuttgart (`08111`) sowie weitere Landkreise, Städte und Gemeinden, wie z.B. die Stadt Böblingen (ARS: `081150003003`), im Regierungsbezirk mit ein.
+
+Eine Einschränkung auf konkrete Verwaltungsebenen ist durch das Auffüllen des ARS auf zwölf Stellen mit Nullen möglich.
+
+**Beispiel**: Der Schlüssel `081150000000` referenziert explizit nur den Kreis Böblingen, nicht jedoch beispielsweise die Stadt Leonberg (ARS: `081150028028`), die im Kreis Böblingen liegt.
+Hierdurch ist bei FIT-Connect eine Suche nach Zustellpunkten möglich, die von der Kreisverwaltung Böblingen betrieben werden, ohne gleichzeitig auch Zustellpunkte der Stadt Leonberg zu ermitteln.
+
diff --git a/docs/details/authentication/scopes-sender.md b/docs/details/authentication/scopes-sender.md
index 333ecc51e..2abe5c00d 100644
--- a/docs/details/authentication/scopes-sender.md
+++ b/docs/details/authentication/scopes-sender.md
@@ -51,19 +51,7 @@ Reine Leistungsscopes werden nicht vergeben sondern sind immer mit einer Region
### Einschränkung: Region
-Eine Einschränkung der Berechtigung für bestimmte Regionen erfolgt auf Basis des zwölfstelligen [Amtlichen Regionalschlüssels (ARS)](https://de.wikipedia.org/wiki/Amtlicher_Gemeindeschl%C3%BCssel#Regionalschl%C3%BCssel), vorangestellt mit `DE`:
-```
-1.-2. Stelle = DE
-3.–4. Stelle = Kennzahl des Bundeslandes
-5. Stelle = Kennzahl des Regierungsbezirks; wenn nicht vorhanden: 0
-6.–8. Stelle = Kennzahl des Landkreises oder der kreisfreien Stadt
-8.–11. Stelle = Verbandsschlüssel
-12.–14. Stelle = Gemeindekennzahl
-```
-
-Es ist je möglich nur einen Teil des ARS anzugeben, z.B. nur `DE` + Bundesland + Regierungsbezirk.
-
-Eine Liste der amtlichen Regionalschlüssel findet sich im [Gemeindeverzeichnis des Statistischen Bundesamtes](https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/_inhalt.html) sowie im [XRepository](https://www.xrepository.de/details/urn:de:bund:destatis:bevoelkerungsstatistik:schluessel:rs).
+Eine Einschränkung der Berechtigung für bestimmte Regionen erfolgt auf Basis des zwölfstelligen [Amtlichen Regionalschlüssels (ARS)](../ars.mdx), vorangestellt mit `DE`.
**Hinweis**: Ohne zusätzliche Einschränkung auf eine Leistung ist ein Zustellberechtigungs-Scope für alle Leistungen in der angegebenen Region gültig.
diff --git a/docs/glossary.md b/docs/glossary.md
index 854e3444f..821d893db 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -6,6 +6,8 @@ hide_table_of_contents: true
| Begriff | Beschreibung |
|---------|--------------|
| FIT-Connect Adressierungsinformationen | Für die Zuständigkeitsfindung im Portalverbund ist eine Hinterlegung von signierten Adressierungsinformationen in einem Landes-Redaktionssystem notwendig (siehe Artikel [Konfiguration des Antragsroutings](responsibilities/routing.mdx)). Die FIT-Connect-Adressierungsinformationen werden im Format XZuFi von den Landes-Redaktionssystemen an das Onlinegateway des Portalverbundes (PVOG) übermittelt und vom FIT-Connect Routingdienst in Kombination mit den im Deutschen Verwaltungsdiensteverzeichnis (DVDV) zur Zuständigkeitsfindung / technischen Adressierung von *Zustellpunkten* genutzt. |
+| Amtlicher Gemeindeschlüssel (AGS) | Schlüssel zur Identifizierung von verwaltungspolitischen Gebieten. Siehe [AGS](./details/ags.mdx) |
+| Amtlicher Regionalschlüssel (ARS) | Schlüssel zur Identifizierung von verwaltungspolitischen Gebieten. Nachfolger des AGS. Siehe [ARS](./details/ars.mdx) |
| Angekündige Anlage | Angabe gegenüber dem Zustelldienst, welche Anlagen übermittelt werden. Teilmenge der Angaben in der `contentStructure` im verschlüsselten Metadatensatz. |
| Anlage (attachment) | Einer Einreichung können optional Anlagen beigefügt werden. Diese sind nicht zwingend maschinenlesbar oder an Standards geknüpft. |
| Antragsteller:in (applicant) | Bezeichnung der Person (Verwaltungskund:in), die über ein sendendes System (z.B. Onlinedienst) einen Antrag stellt. |
diff --git a/docs/responsibilities/get-destination.mdx b/docs/responsibilities/get-destination.mdx
index b072fdb35..7efd2e0b6 100644
--- a/docs/responsibilities/get-destination.mdx
+++ b/docs/responsibilities/get-destination.mdx
@@ -24,7 +24,7 @@ Die Ermittlung der `destinationId` und die Ermittlung der technischen Parameter
Der Endpunkt erwartet genau zwei Parameter:
- Einen Identifikator einer Verwaltungsleistung. Als Identifikator der Verwaltungsleistung muss ein Leistungsschlüssel aus dem FIM-Baustein Leistungen (ehemals *LeiKa-Schlüssel*, siehe [Leistungskatalog im FIM-Portal](https://fimportal.de/kataloge#download-leistungen)) verwendet werden.
-- Einen Identifikator eines verwaltungspolitischen Gebietes. Für den Identifikator des verwaltungspolitischen Gebietes kann entweder der [amtliche Gemeindeschlüssel (AGS)](https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/Glossar/amtlicher-gemeindeschluessel.html), der [amtliche Regionalschlüssel (ARS)](https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/_FAQ/regionalschluessel.html) oder die [Id eines Gebietes](#verwaltungspolitische-gebiete-ermitteln) aus der Suche über den Endpunkt <ApiLink api="routing-api" to="/areas" /> verwendet werden.
+- Einen Identifikator eines verwaltungspolitischen Gebietes. Für den Identifikator des verwaltungspolitischen Gebietes kann entweder der [amtliche Gemeindeschlüssel (AGS)](../details/ags.mdx), der [amtliche Regionalschlüssel (ARS)](../details/ars.mdx) oder die [Id eines Gebietes](#verwaltungspolitische-gebiete-ermitteln) aus der Suche über den Endpunkt <ApiLink api="routing-api" to="/areas" /> verwendet werden.
Der Endpunkt <ApiLink api="routing-api" to="/routes" /> implementiert Pagination.
Das Ergebnis der Anfrage enthält daher neben der eigentlichen (Teil-)Ergebnismenge der Routing-Informationen (`routes`) auch Informationen wie Anzahl (`count`), Gesamtanzahl (`totalCount`) und Startpunkt der Ergebnismenge (`offset`).
diff --git a/sidebar.js b/sidebar.js
index b4feec7af..2de6f6803 100644
--- a/sidebar.js
+++ b/sidebar.js
@@ -77,6 +77,8 @@ module.exports = {
type: 'category',
label: 'Weiterführende Informationen',
items: [
+ 'details/ags',
+ 'details/ars',
'details/callbacks',
'details/crypto',
'details/jwk-creation',
--
GitLab