Skip to content

Commit

Permalink
Merge pull request #167 from nens/lexvand-docs
Browse files Browse the repository at this point in the history 
[Done] Improve docs
  • Loading branch information
@remcogerlich
remcogerlich authored Dec 18, 2024
2 parents fdd064d + 71c132f commit 6bf6666
Show file tree
Hide file tree
Showing 3 changed files with 20 additions and 19 deletions.
1 change: 1 addition & 0 deletions CHANGES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
- Add Events Endpoint
- Add Events Import
- Enhancement: Allow GLD-Addition date and resultTime to be unknown (IMBRO/A)
- Improve the docs


## 0.72 (2024-12-17)
Expand Down
20 changes: 10 additions & 10 deletions docs/docs/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ De browsable BROSTAR API is te vinden op [https://www.brostar.nl/api/](https://w

## API Keys

Voor elke request die op de API gedaan wordt, moet een API key gebruikt worden om de gebruiker te authenticeren. Een API key is gebruikersgebonden en kunnen momenteel alleen aangevraagd worden bij Nelen & Schuurmans. Het eigenhandig beheren van API keys in de Api en frontend zal spoedig worden ontwikkeld.
Voor elke request die op de API gedaan wordt, moet een API key gebruikt worden om de gebruiker te authenticeren. Een API key is gebruikersgebonden en kunnen momenteel alleen aangevraagd worden bij Nelen & Schuurmans. Het eigenhandig beheren van API keys in de API en frontend zal spoedig worden ontwikkeld.

Een request op de BROSTAR API, inclusief een API Key, ziet er als volgt uit:

Expand Down Expand Up @@ -89,14 +89,14 @@ Op het [https://www.brostar.nl/api/users/logged-in/](https://www.brostar.nl/api/

### Importtasks

Import taken zorgen ervoor dat de huidig aanwezige data in de BRO in de BROSTAR database belanden. Deze data is vervolgens in de specifieke endpoints op te vragen.
Importtaken zorgen ervoor dat de huidig aanwezige data in de BRO in de BROSTAR database belanden. Deze data is vervolgens in de specifieke endpoints op te vragen.

Import taken vinden plaats op basis van POST requests. In deze request wordt een combinatie van een BRO domein (GAR, GLD, GMW, GMN of FRD) en een kvk nummer meegegeven. Voordat de import start, wordt alle data voor dat domein in de BROSTAR verwijderd. Nadat een taak is geslaagd, is de data in de BROSTAR voor dat specifieke domein dus up-to-date met de BRO.
Importtaken vinden plaats op basis van POST requests. In deze request wordt een combinatie van een BRO domein (GAR, GLD, GMW, GMN of FRD) en een kvk nummer meegegeven. Voordat de import start, wordt alle data voor dat domein in de BROSTAR verwijderd. Nadat een taak is geslaagd, is de data in de BROSTAR voor dat specifieke domein dus up-to-date met de BRO.

De data die wordt geimporteerd is slechts de huidige versie van de metadata. Er wordt dus bijvoorbeeld geen geschiedenis van een GMW of de standen van een GLD geimporteerd. Hiervoor kan de BRO zelf bevraagd worden.

!!! note
De aanwezigheid van de data in de BROSTAR is essentieel voor de frontend om te bestaan. Het kan dus zijn dat je als scripter, die alleen bezig is met het aanleveren van data, geen gebruik maakt van dit endpoint. Toch kan het in sommige gevallen handig zijn. Voorbeelden hiervan zijn om een vertaling van een nitg code naar een BRO id te maken of te controleren of bepaalde objecten reeds aangeleverd zijn.
De aanwezigheid van de data in de BROSTAR is essentieel voor de frontend om te bestaan. Het kan dus zijn dat je als scripter, die alleen bezig is met het aanleveren van data, geen gebruik maakt van dit endpoint. Toch kan het in sommige gevallen handig zijn. Voorbeelden hiervan zijn om een vertaling van een NITG-code naar een BRO-id te maken of te controleren of bepaalde objecten reeds aangeleverd zijn.

Hieronder een voorbeeld van een POST request om een GMN import taak voor eigen organisatie te starten:

Expand All @@ -123,7 +123,7 @@ r = requests.post(url, auth=auth, payload=payload)

### Uploadtasks

Upload taken zijn dé kracht van de BROSTAR. Het idee achter dit endpoint is dat er slechts JSON opgesteld hoeft te worden om data aan te leveren. Om dit te visualiseren volgt hieronder een code snippet, waarmee een GMN aangemaakt kan worden in de BRO.
Uploadtaken zijn dé kracht van de BROSTAR. Het idee achter dit endpoint is dat er slechts JSON opgesteld hoeft te worden om data aan te leveren. Om dit te visualiseren volgt hieronder een code snippet, waarmee een GMN aangemaakt kan worden in de BRO.

```python
import requests
Expand Down Expand Up @@ -193,7 +193,7 @@ Het BRO project nummer is nodig om data bij de BRO aan te kunnen leveren. Deze k
Voor elk BRO domein zijn er verschillende type berichten mogelijk. Zo zijn er bijvoorbeeld voor de [GMN](https://www.bro-productomgeving.nl/bpo/latest/gmn-inname-voorbeeldberichten-in-xml) Startregistration, MeasuringPoint, en Closure als berichten mogelijk.

#### request_type
Elk registratie type kan op verschillende manieren aangeleverd worden. In principe is de registration de standaardoptie, maar als er data aangepast of verwijderd moet worden, dan zijn respectievelijk de replace en delete requests types beschikbaar. In de [BRO catalogus](https://www.bro-productomgeving.nl/bpo/latest/grondwatermonitoring) staan alle mogelijke combinaties. Dit zijn de beschikbare request types:
Elk registration type kan op verschillende manieren aangeleverd worden. In principe is de registration de standaardoptie, maar als er data aangepast of verwijderd moet worden, dan zijn respectievelijk de replace en delete requests types beschikbaar. In de [BRO catalogus](https://www.bro-productomgeving.nl/bpo/latest/grondwatermonitoring) staan alle mogelijke combinaties. Dit zijn de beschikbare request types:

- registration

Expand Down Expand Up @@ -719,14 +719,14 @@ Om meer inzicht te geven in de data die naar de BRO wordt gestuurd, is het mogel
!!! warning
Het bulk uploadtask endpoint is maatwerk. Contact [[email protected]](mailto:[email protected]?subject=Aanvraag maatwerk bulk upload BROSTAR ) om de mogelijkheden te verkennen om een specifieke bulk upload te realiseren.

Het bulk upload endpoint is gemaakt om eenvoudig een groot aantal leveringen te realiseren. Op het bulk endpoint is het mogelijk om csv/excel bestanden aan te levern. Achter de schermen wordt een taak gestart die deze bestanden opknippen in meerdere upload taken.
Het bulk upload endpoint is gemaakt om eenvoudig een groot aantal leveringen te realiseren. Op het bulk endpoint is het mogelijk om CSV/Excel bestanden aan te leveren. Achter de schermen wordt een taak gestart die deze bestanden opknipt in meerdere uploadtaken.

Het bulk upload endpoint is stukje maatwerk in de BROSTAR. Momenteel bestaat alleen de optie om een specifiek formaat van GAR csv bestanden aan te leveren. Deze zijn ontwikkeld voor Provincie Noord-Brabant, waarbij hun formaat van lab- en veldbestanden zijn gebruikt als input. Daardoor is het voor hen mogelijk om 2 bestanden in de frontend te slepen, wat metadata op te geven, en de bestanden naar de API te sturen. Hiermee wordt alle data dus vertaald naar upload taken, die vervolgens de data naar de BRO sturen.
Het bulk upload endpoint is een stukje maatwerk in de BROSTAR. Momenteel bestaat alleen de optie om een specifiek formaat van GAR CSV bestanden aan te leveren. Deze zijn ontwikkeld voor Provincie Noord-Brabant, waarbij hun formaat van lab- en veldbestanden zijn gebruikt als input. Daardoor is het voor hen mogelijk om 2 bestanden in de frontend te slepen, wat metadata op te geven, en de bestanden naar de API te sturen. Hiermee wordt alle data dus vertaald naar uploadtaken, die vervolgens de data naar de BRO sturen.

Hieronder staat een voorbeeld van hoe een bulk upload opgestuurd kan worden via een script.

!!! Wow
Dit stukje code, in combinatie met de xlsx bestanden, is dus alles wat nodig is om duizenden GAR berichten te registreren in de BRO!
Dit stukje code, in combinatie met de XLSX bestanden, is dus alles wat nodig is om duizenden GAR berichten te registreren in de BRO!

```python
import requests
Expand Down Expand Up @@ -795,4 +795,4 @@ De data endpoints zijn een tijdelijke opslag voor de data die volgt uit de impor

- `https://www.brostar.nl/api/frd/frds/`

Op deze endpoints zijn de lijsten van objecten te zien. Deze lijsten van de metadata van objecten bieden een mooi overzicht van alles wat er in de BRO aan data staat. Dit is een mooie vervanging voor de [uitgifteservice van de BRO](https://publiek.broservices.nl/gm/gmn/v1/swagger-ui/#/default/bro-ids), aangezien daar alleen request gedaan kunnen worden op basis van idividuele objecten. Deze endpoints kunnen dus helpen bij het scripten, maar dienen vooral voor de frontend om de data snel op te kunnen vragen om het vervolgens in de kaart en tabellen weer te geven.
Op deze endpoints zijn de lijsten van objecten te zien. Deze lijsten van de metadata van objecten bieden een mooi overzicht van alles wat er in de BRO aan data staat. Dit is een mooie vervanging voor de [uitgifteservice van de BRO](https://publiek.broservices.nl/gm/gmn/v1/swagger-ui/#/default/bro-ids), aangezien daar alleen requests gedaan kunnen worden op basis van individuele objecten. Deze endpoints kunnen dus helpen bij het scripten, maar dienen vooral voor de frontend om de data snel op te kunnen vragen om het vervolgens in de kaart en tabellen weer te geven.
18 changes: 9 additions & 9 deletions docs/docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

De BROSTAR is een applicatie die is ontwikkeld door [Nelen & Schuurmans](https://nelen-schuurmans.nl/) om het aanleverproces van data naar de [Basis Registratie Ondergrond (BRO)](https://basisregistratieondergrond.nl/) aanzienlijk makkelijker te maken.

Het aanleveren van data naar de BRO is een technisch process, waarbij kennis van o.a. XML bestanden, scripting en API's vereist is bij de leverancier. Daarom wordt dit proces vaak uitbesteed vanuit de brondhouders. In de praktijk bleek dat hierbij de mate van maatwerk enorm hoog was in verband met eigen manieren van dataopslag, datamodellen, applicaties en data governance. De BROSTAR is een applicatie die door elke organisatie op meerdere manieren ingezet kan worden.
Het aanleveren van data naar de BRO is een technisch proces, waarbij kennis van o.a. XML bestanden, scripting en API's vereist is bij de leverancier. Daarom wordt dit proces vaak uitbesteed door bronhouders. In de praktijk bleek dat hierbij de mate van maatwerk enorm hoog was in verband met eigen manieren van dataopslag, datamodellen, applicaties en data governance. De BROSTAR is een applicatie die door elke organisatie op meerdere manieren ingezet kan worden.

De BROSTAR bestaat uit een [open-source API](https://github.com/nens/brostar-api) en een [closed-source frontend](https://www.brostar.nl/).

Expand All @@ -20,16 +20,16 @@ De basis van de BROSTAR is de API. De API heeft 2 belangrijke hoofdfunctionalite

- **Import taken**:

Het is mogelijk om data vanuit de BRO te importeren in de database van de BROSTAR. Het gaat hierbij alleen om metadata van de objecten, en niet van de gehele geschiedenis. In de filosofie van de BROSTAR is de BRO zelf de waarheid en altijd het meest up-to-date. Na een import is het mogelijk om deze gegevens op te vragen en in te zien.
Importeer data vanuit de BRO in de database van de BROSTAR. Het gaat hierbij om actuele metadata van de objecten, en niet de gehele geschiedenis. In de filosofie van de BROSTAR is de BRO zelf de waarheid en altijd het meest up-to-date. Na een import is het mogelijk om deze gegevens op te vragen en in te zien.

!!! note
Het is mogelijk om openbare data van andere organisaties vanuit de BRO te importeren

- **Upload taken**:

Met behulp van upload taken kan data naar de BRO worden gestuurd. Alle mogelijke berichten worden ondersteund vanuit de API. Het idee van deze functionaliteit is dat je als scripter slechts 1 stap hoeft uit te voeren: het opstellen van een JSON met daarin alle relevante informatie voor het specifieke bericht dat opgestuurd moet worden. Nadat deze als request naar de BROSTAR wordt opgestuurd, wordt de rest afgehandeld. Dit omvat het opstellen van een XML bestand, de validatie, de daadwerkelijke levering, en de voortgang van de levering. De voortgang wordt als status bijgehouden, met eventueel belangrijke logging vanuit de BRO.
Stuur data naar het bronhouderportaal van de BRO. Alle mogelijke berichten worden ondersteund vanuit de API. Het idee van deze functionaliteit is dat je als scripter slechts 1 stap hoeft uit te voeren: het opstellen van een JSON met daarin alle relevante informatie voor het specifieke bericht dat opgestuurd moet worden. De BROSTAR handelt vervolgens de aanlevering naar de BRO API af. Dit omvat het opstellen van een XML bestand, de validatie, de daadwerkelijke levering, en de voortgang van de levering. De voortgang wordt als status bijgehouden, met eventueel belangrijke logging vanuit de BRO.

De API van de BROSTAR is dus een krachtig hulpmiddel bij zowel managen van bestaande data in de BRO als het aanleveren van de data. Door de BROSTAR te gebruiken wordt een groot deel van het aanleverprocess afgevangen en kan er relatief makkelijk een scripting connectie met de BRO gemaakt worden.
De API van de BROSTAR is dus een krachtig hulpmiddel bij zowel beheren van bestaande data in de BRO als het aanleveren van nieuwe data. Door de BROSTAR te gebruiken wordt een groot deel van het aanleverproces afgevangen en kan er relatief makkelijk een scripting connectie met de BRO gemaakt worden.


## Frontend
Expand All @@ -38,20 +38,20 @@ De API van de BROSTAR is dus een krachtig hulpmiddel bij zowel managen van besta
Klik [hier](frontend.md) voor een uitgebreidere functionele documentatie van de frontend.


De frontend is de visuele versie van de BROSTAR. Deze is ontwikkeld zodat ook personen zonder scripting ervaring laagdrempelig data kunnen aanleveren. Dit maakt het mogelijk voor bronhouders om het databeheer zelf in handen te houden.
De frontend is de visuele component van de BROSTAR. Deze is ontwikkeld zodat ook personen zonder scripting ervaring laagdrempelig data kunnen aanleveren. Dit maakt het mogelijk voor bronhouders om het databeheer zelf in handen te nemen.

Als organisatie heb je een eigen omgeving, en kun je eigen data importeren. Net zoals in de API is het ook mogelijk om data van andere organisaties te importeren. Deze data is op een kaart of in een tabel in te zien, en voor sommige type objecten zelfs al gemakkelijk aan te passen:
Als organisatie heb je een eigen omgeving, en kun je eigen data importeren. Net als in de API is het ook mogelijk om data van andere organisaties te importeren. Deze data is op een kaart of in een tabel in te zien, en voor sommige type objecten zelfs al gemakkelijk aan te passen:


![BROSTAR homepagina](assets/frontend_homepage.png)
*BROSTAR homepagina (voorbeeld: Provincie Gelderland)*

Het aanleveren van data via de frontend gebeurt achter de schermen via de API. Na het eenmalig instellen van aanlevertokens voor de BRO, is het als gebruiker is het mogelijk om gebruiksvriendelijke formulieren in te vullen of om Excel bestanden aan te leveren voor bulk uploads. Hieronder is een voorbeeld te zien waarin startregistratie van een GMN geregeld kan worden via een invulformulier. Als gebruiker kun je bovenin metadata van het GMN invullen. Onderin kunnen GMW's op de kaart geselecteerd worden, om vervolgens de relevante buizen te selecteren die als Meetpunt aangeleverd worden.
Het aanleveren van data via de frontend gebeurt achter de schermen via de API. Na het eenmalig instellen van API-tokens voor de BRO, kan de gebruiker databeheer doen middels gebruiksvriendelijke formulieren of bulk uploads doen met Excel bestanden. Hieronder is een voorbeeld te zien waarin de startregistratie van een GMN geregeld wordt via een invulformulier. Als gebruiker kun je bovenin metadata van het GMN invullen. Onderin kunnen GMW's op de kaart geselecteerd worden, om vervolgens de relevante filters te selecteren die als Meetpunt aangeleverd worden.

![GMN startregistratie](assets/frontend_create_gmn.png)
*GMN startregistratie invulformulier*

Nadat een levering is gedaan, is het mogelijk om de status ervan in te zien. Als een levering niet geslaagd is, kunnen de foutmeldingen vanuit de BRO ingezien worden, om vervolgens de levering aan te passen. Hiermee wordt de gebruiker terug gestuurd naar het ingevulde formulier, waardoor een aanpassing gemakkelijk gemaakt kan worden voordat een nieuwe poging tot levering gedaan kan worden:
De status van een levering wordt bijgehouden. Als een levering niet geslaagd is, kunnen de foutmeldingen vanuit de BRO ingezien worden, om vervolgens de levering te corrigeren. Hiermee wordt de gebruiker teruggestuurd naar het ingevulde formulier, waardoor een aanpassing gemakkelijk gemaakt kan worden voordat een nieuwe poging tot levering gedaan wordt:

![Upload taak tabel](assets/frontend_upload_task_table.png)
*Voorbeeld van de foutmeldingen bij een gefaalde taak. Op de achtergrond zijn succesvolle taken te zien.*
Expand All @@ -64,7 +64,7 @@ Nadat een levering is gedaan, is het mogelijk om de status ervan in te zien. Als

Net zoals de BRO zelf, heeft de BROSTAR een [productie](https://www.brostar.nl/) en een [staging](https://www.staging.brostar.nl/) omgeving. De productie van de BROSTAR is op de productie van de BRO gekoppeld en de staging is op de demo van de BRO gekoppeld.

Als je als organisatie een licensie op de BROSTAR neemt, krijg je een eigen omgeving op beide versies. Daarmee is het mogelijk om eerst te testen en te ontwikkelen met dummy data via de demo omgeving.
Met een licensie op de BROSTAR krijgt een organisatie een eigen omgeving op beide omgevingen. Daarmee is het mogelijk om eerst te testen en te ontwikkelen met dummy data via de demo omgeving.

## Interesse?

Expand Down

0 comments on commit 6bf6666

Please sign in to comment.