Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc improvements #198

Closed
wants to merge 38 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
df941ca
INIT
lencodes Nov 27, 2023
5aea4b4
REVERT redundant changes
Nov 27, 2023
673db01
updated package.json
remko48 Nov 28, 2023
42fd9d2
updated env files
remko48 Nov 28, 2023
ef2dcf1
added category and municipality to table
remko48 Nov 28, 2023
734063c
FINALIZE availableThemes and its categories
Nov 28, 2023
6bff72c
UP version
lencodes Nov 28, 2023
cad9e99
REBUILD lock
lencodes Nov 28, 2023
9a1def0
WIP
remko48 Nov 28, 2023
ed3921a
REGEN lock
lencodes Nov 28, 2023
6db9667
UP conduction/components
lencodes Nov 28, 2023
28916b1
UP versions
lencodes Nov 28, 2023
d4ac3b6
UPDATE Dockerfile to include @parcel/watcher
lencodes Nov 28, 2023
2cb9a80
Merge pull request #190 from ConductionNL/fix/XW-122/grouped-select
lencodes Nov 28, 2023
4d74b5d
Merge remote-tracking branch 'origin/development' into Feature/XW-123…
remko48 Nov 28, 2023
84617e8
added category and municipality to card
remko48 Nov 28, 2023
7b3c561
cleanup
remko48 Nov 28, 2023
059eae2
cleanup
remko48 Nov 28, 2023
0fe23c5
cleanup
remko48 Nov 28, 2023
752e167
Merge pull request #191 from ConductionNL/Feature/XW-123/category-and…
remko48 Nov 28, 2023
1865d14
Merge branch 'development' into Feature/XW-127/api-changes
remko48 Nov 28, 2023
85df86e
added api changes
remko48 Nov 28, 2023
462f487
updated workflow
remko48 Nov 28, 2023
52da177
updated api url
remko48 Nov 28, 2023
dff8e21
added oidn numbers
remko48 Nov 29, 2023
cb0fb73
updated api changes
remko48 Nov 29, 2023
0e428a8
Merge pull request #192 from ConductionNL/Feature/XW-127/api-changes
remko48 Nov 29, 2023
2688dfe
Revert "Feature/XW-127/api-changes"
remko48 Nov 29, 2023
efab796
Merge pull request #193 from ConductionNL/revert-192-Feature/XW-127/a…
remko48 Nov 29, 2023
5edde4b
Revert "Revert "Feature/XW-127/api-changes""
remko48 Nov 29, 2023
9df1fa6
Merge pull request #194 from ConductionNL/revert-193-revert-192-Featu…
remko48 Nov 29, 2023
44da9b3
Merge branch 'development' into Feature/XW-127/api-changes
remko48 Nov 29, 2023
2a2529d
reload bug
remko48 Nov 29, 2023
2ab6d89
Merge pull request #195 from ConductionNL/Feature/XW-127/api-changes
remko48 Nov 29, 2023
339f49b
Update mapping table
bbrands02 Nov 30, 2023
9670f63
Merge branch 'docupdate-integratie' into fix/configuration-docs
bbrands02 Dec 1, 2023
e76238e
FAQ q&a added and a visual fix
bbrands02 Dec 1, 2023
425bc8b
Textual changes improvements
bbrands02 Dec 1, 2023
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions .github/workflows/woo-page-deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,18 @@ env: # Change these to your preferences any image url can also be a base encoded
GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
API_BASE_URL: "https://api.gateway.commonground.nu/api"
NL_DESIGN_THEME_CLASSNAME: "conduction-theme"
DEV_ENVIRONMENT: "true"
SHOW_CATEGORY: "true"
SHOW_ORGANIZATION: "true"
FAVICON_URL: "https://conduction.nl/wp-content/uploads/2021/07/cropped-favicon-32x32.png"
HEADER_LOGO_URL: "https://conduction.nl/wp-content/uploads/2021/07/cropped-conductionlogo-1.png"
ORGANISATION_NAME: "Conduction"
JUMBOTRON_IMAGE_URL: "https://www.conduction.nl/wp-content/uploads/2021/07/cropped-Conduction_HOME_0000_afb1-1.png"
FOOTER_LOGO_URL: "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBzdGFuZGFsb25lPSJubyI/Pgo8IURPQ1RZUEUgc3ZnIFBVQkxJQyAiLS8vVzNDLy9EVEQgU1ZHIDIwMDEwOTA0Ly9FTiIKICAgICJodHRwOi8vd3d3LnczLm9yZy9UUi8yMDAxL1JFQy1TVkctMjAwMTA5MDQvRFREL3N2ZzEwLmR0ZCI+CjxzdmcgdmVyc2lvbj0iMS4wIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciCiAgICAgd2lkdGg9IjcxLjAwMDAwMHB0IiBoZWlnaHQ9IjcwLjAwMDAwMHB0IiB2aWV3Qm94PSIwIDAgNzEuMDAwMDAwIDcwLjAwMDAwMCIKICAgICBwcmVzZXJ2ZUFzcGVjdFJhdGlvPSJ4TWlkWU1pZCBtZWV0Ij4KCiAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgwLjAwMDAwMCw3MC4wMDAwMDApIHNjYWxlKDAuMTAwMDAwLC0wLjEwMDAwMCkiCiAgICAgICBmaWxsPSIjNDM3NkZDIiBzdHJva2U9Im5vbmUiPgogICAgICAgIDxwYXRoIGQ9Ik0yMTggNTkyIGwtMTM3IC03NyAwIC0xNjUgMCAtMTY1IDEzMSAtNzQgYzcyIC00MSAxMzcgLTc0IDE0MyAtNzQgNgowIDcwIDMzIDE0MyA3NCBsMTMxIDc0IDEgMTY1IDAgMTY1IC02OCAzNyBjLTM3IDIxIC05OSA1NiAtMTM3IDc3IGwtNzEgNDAKLTEzNiAtNzd6IG0yOTUgLTg1IGw1NyAtMzIgMCAtMTI1IDAgLTEyNSAtMTA2IC02MCBjLTU4IC0zMyAtMTA4IC02MCAtMTExCi01OSAtMyAwIC01MiAyNyAtMTA5IDYwIGwtMTAzIDU5IDAgMTI1IDAgMTI1IDEwNyA2MSAxMDcgNjIgNTAgLTI5IGMyNyAtMTYKNzYgLTQ0IDEwOCAtNjJ6Ii8+CiAgICAgICAgPHBhdGggZD0iTTI3OCA0NzIgbC02OCAtMzcgMCAtODUgMCAtODUgNzMgLTM5IDczIC0zOSA2MiAzNCBjMzQgMTggNjIgMzcgNjIKNDEgMCA0IC0xNCAxNSAtMzEgMjMgLTI4IDE1IC0zMyAxNSAtNTQgMSAtMzEgLTIwIC00NiAtMjAgLTg0IDIgLTI3IDE1IC0zMQoyMiAtMzEgNjIgMCA0MCA0IDQ3IDMxIDYzIDM4IDIxIDUzIDIxIDg0IDEgMjEgLTE0IDI2IC0xNCA1NCAxIDE3IDggMzEgMTkgMzEKMjMgMCA4IC0xMTMgNzIgLTEyNiA3MiAtNSAwIC0zOSAtMTcgLTc2IC0zOHoiLz4KICAgIDwvZz4KPC9zdmc+Cg=="
FOOTER_LOGO_HREF: "https://conduction.nl/"
FOOTER_LOGO_HREF: "https://conduction.nl/",
FOOTER_CONTENT: "https://raw.githubusercontent.com/ConductionNL/woo-website-template/main/pwa/src/templates/templateParts/footer/FooterContent.json"
# OIDN_NUMBER: " "
ENV_VARS_SET: "true"

on:
push:
Expand All @@ -41,13 +46,18 @@ jobs:
envkey_USE_GITHUB_REPOSITORY_NAME_AS_PATH_PREFIX: ${{ env.USE_GITHUB_REPOSITORY_NAME_AS_PATH_PREFIX }}
envkey_GATSBY_API_BASE_URL: ${{ env.API_BASE_URL }}
envkey_GATSBY_NL_DESIGN_THEME_CLASSNAME: ${{ env.NL_DESIGN_THEME_CLASSNAME }}
envkey_GATSBY_DEV_ENVIRONMENT: ${{ env.DEV_ENVIRONMENT }}
envkey_GATSBY_SHOW_CATEGORY: ${{ env.SHOW_CATEGORY }}
envkey_GATSBY_SHOW_ORGANIZATION: ${{ env.SHOW_ORGANIZATION }}
envkey_GATSBY_FAVICON_URL: ${{ env.FAVICON_URL }}
envkey_GATSBY_HEADER_LOGO_URL: ${{ env.HEADER_LOGO_URL }}
envkey_GATSBY_ORGANISATION_NAME: ${{ env.ORGANISATION_NAME }}
envkey_GATSBY_JUMBOTRON_IMAGE_URL: ${{ env.JUMBOTRON_IMAGE_URL }}
envkey_GATSBY_FOOTER_LOGO_URL: ${{ env.FOOTER_LOGO_URL }}
envkey_GATSBY_FOOTER_LOGO_HREF: ${{ env.FOOTER_LOGO_HREF }}
envkey_GATSBY_FOOTER_CONTENT: ${{ env.FOOTER_CONTENT }}
# envkey_GATSBY_OIDN_NUMBER: ${{ env.OIDN_NUMBER }}
envkey_GATSBY_ENV_VARS_SET: ${{ env.ENV_VARS_SET }}
directory: pwa/static
file_name: .env.production
fail_on_empty: true
Expand All @@ -56,11 +66,14 @@ jobs:
- name: Set up Node.js
uses: actions/setup-node@v2
with:
node-version: 14
node-version: 18

- name: Install dependencies
run: cd pwa && npm install

- name: Install parcel/watcher
run: cd pwa && npm install @parcel/watcher

- name: Remove old Gatsby cache
run: rm -rf pwa/.cache

Expand Down
127 changes: 57 additions & 70 deletions docs/Configuratie.md

Large diffs are not rendered by default.

14 changes: 9 additions & 5 deletions docs/FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,30 @@

Dit zijn de algemene veelgestelde vragen over het gebruik en de configuratie van het OpenWoo platform. Mocht u een vraag hebben die hier niet beantwoord wordt, of wilt u een vraag toegevoegd zien aan deze lijst, dan nodigen we u uit om een issue aan te maken op onze [GitHub-pagina](https://github.com/ConductionNL/woo-website-template/issues).

**Q. Wanneer kan ik gebruik maken van OpenWoo.app?**

A. Als je bijvoorbeeld een user interface hebt of wilt bouwen om publicaties op te tonen, zou de OpenWoo.app de oplossing zijn.

**Q. Heb ik WordPress nodig om de OpenWoo.app te gebruiken?**

A. Nee, het enige wat je nodig hebt, is een bron. Dit zal veelal je zaaksysteem zijn, maar zou zelfs een Excel-lijst kunnen zijn.

*Q. Heb ik Haven nodig?*
**Q. Heb ik Haven nodig?**

A. Nee, Haven is een compliancy-standaard van de VNG. Het is ook mogelijk om de OpenWoo.app te koppelen aan een zaaksysteem zonder Haven.

*Q. Moet ik de website zelf hosten?*
**Q. Moet ik de website zelf hosten?**

A. Nee, de website kan rechtstreeks vanaf GitHub worden gehost. Het is ook mogelijk om de website op een eigen omgeving te hosten of gebruik te maken van de Open Woo-plugin voor WordPress sites.

*Q. Heb ik een ZGW-ondersteundend zaaksysteem nodig?*
**Q. Heb ik een ZGW-ondersteundend zaaksysteem nodig?**

A. Het is wel mogelijk om de OpenWoo.app te koppelen aan een zaaksysteem zonder ZGW. Het kan dus, maar de StuF en ZDS-koppelingen zijn nog niet beproefd in de praktijk.

*Q. Wat als ik een bron wilt toevoegen die nog niet wordt ondersteund?*
**Q. Wat als ik een bron wilt toevoegen die nog niet wordt ondersteund?**

A. Voor nieuwe bronnen, of gewenste features kunt u een issue aanmaken op onze [GitHub-pagina](https://github.com/ConductionNL/woo-website-template/issues). Deze worden dan gereviewd door de stuurgroep en indien mogelijk toegevoegd aan de roadmap. Voor meer informatie over de stuurgroep, zie [Governance](./Governance.md).

*Q. Kan ik worden ontzorgd?*
**Q. Kan ik worden ontzorgd?**

A. Ja, dat is mogelijk. Er zijn leveranciers voor zowel SAAS als Service Level Agreement(SLA) beschikbaar Zie [Kosten](./Kosten.md) voor meer informatie.
50 changes: 31 additions & 19 deletions docs/Integratie.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,39 @@
# Integratie

OpenWoo.app is essentie een koppelvlak waar aan de bovenkant meerdere weergaven of user interfaces op kunnen worden gekoppeld en aan de onderkant meerdere bronnen ontsloten.
Deze pagina is bedoeld voor developers die meer info proberen op tehalen over de OpenWoo.app koppeling of hier al mee aan de slag willen.

Als er tijdens of na het lezen zijn nog vragen zijn, neem een kijkje op de [FAQ](./FAQ.md).

## Wat is OpenWoo.app

OpenWoo.app is in essentie een API koppelvlak waar aan de bovenkant meerdere weergaven of user interfaces (front-ends) op kunnen worden gekoppeld en aan de onderkant meerdere bronnen ontsloten. Als u meer wilt weten over OpenWoo.app kunt u meer lezen op [https://openwoo.app](https://openwoo.app).

> **Hulp nodig?**
>
> Hiervoor hebben we een appart [slack kanaal](https://samenorganiseren.slack.com/archives/C067Q3UE9F0) binnen commonground. We helpen je daar graag verder.

## Het koppelen van een user interface

Als u als organisatie of leverancier OpenWoo.app wilt koppelen aan een huidige interface (bijvoorbeeld door de resultaten uit uw gemeente in uw website te integereren) and kunt u daarvoor gebruikmaken van de OpenWoo.app API.
Als u als organisatie of leverancier OpenWoo.app wilt koppelen aan een huidige interface (bijvoorbeeld door de resultaten uit uw gemeente in uw website te integereren) dan kunt u daarvoor gebruikmaken van de OpenWoo.app API. Wij kunnen de bron synchroniseren naar ons koppelvlak en dan zal via de API uw resultaten zichtbaar zijn die u dan via uw user interface zou kunnen bevragen en gebruiken.

### Locatie en Authenticatie

U vindt de API op [https://api.gateway.commonground.nu/api/publicaties](https://api.gateway.commonground.nu/api/publicaties). Voor het stellen van zoekvragen is géén authenticatie vereist (het doel van OpenWOO.app is immers het verspreiden van openbare informatie). Er is echter wel sprake van throttling op response tijden (de API reageert langzamer) en rate-limiting (het aantal bevragingen per minuut en uur zijn beperkt) zonder authenticatie. Ook zijn alleen de GET (ophalen) acties toegestaan zonder authenticatie.
De API staat online en is beschikbaar op [https://api.gateway.commonground.nu/api/publicaties](https://api.gateway.commonground.nu/api/publicaties). Voor het stellen van zoekvragen is géén authenticatie vereist (het doel van OpenWOO.app is immers het verspreiden van openbare informatie). Er is echter wel sprake van throttling op response tijden (de API reageert langzamer) en rate-limiting (het aantal bevragingen per minuut en uur zijn beperkt) zonder authenticatie. Ook zijn alleen de GET (ophalen) acties toegestaan zonder authenticatie.

Als u vanuit uw casus een API nodig heeft zonder throttling, ratelimit of namens een organisatie wijzigingen wilt doen (POST,PUT,DELETE) dan kunt u een mail sturen naar <[email protected]>.
Als u vanuit uw casus een API nodig heeft zonder throttling, ratelimit of namens een organisatie wijzigingen wilt doen (en POST, PUT, DELETE API requests wilt maken) dan kunt u een mail sturen naar <[email protected]>.

### Documentatie

Voor de API is een [redoc documentatie](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ConductionNL/woo-website-template/main/docs/oas.yaml) beschikbaar met voorbeelden van de verschillende API endpoints, calls en resultaten. Omdat de API daarnaast kan worden gebruikt zonder authenticatie is deze ook goed te beproeven via onze [Postman collectie](). We raden developers van ook van harte aan om aan de hand van deze collectie te spelen en ontwikkelen.
Voor de API is een [redoc documentatie](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/ConductionNL/woo-website-template/main/docs/oas.yaml) beschikbaar met voorbeelden van de verschillende API endpoints, calls en resultaten. Omdat de API daarnaast kan worden gebruikt zonder authenticatie is deze ook goed te beproeven via onze [Postman collectie](). We raden developers van ook van harte aan om aan de hand van deze collectie te spelen en te ontwikkelen.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is die Postman collectie er al?


### Voorbeelden

In het merendeel van de gevallen zult u een zoekvraag willen uitvoeren binnen de Woo publicaties van OpenWoo.app, het endpoint daarvoor is: <https://api.gateway.commonground.nu/api/publicaties>. Er zijn 4 voor de hand liggende zoekparameters waarmee gezocht wordt (overige opties vind u terug in de [Redoc documentatie]()).
In het merendeel van de gevallen zult u een zoekvraag willen uitvoeren binnen de Woo publicaties van OpenWoo.app, het endpoint daarvoor is: <https://api.gateway.commonground.nu/api/publicaties>. Er zijn 4 voor de hand liggende zoek query parameters waarmee gezocht wordt (overige opties vind u terug in de [Redoc documentatie]()).

1. Op een of meerdere zoek woorden, b.v. `_search=test`
2. Op organisatie, dit gaat aan de hand van OIN (de volledige OIN lijst vind u [hier](https://oinregister.logius.nl/oin-register)) b.v. `oin=00000001001299992000`
3. Op categorie, `categorie=Convenant`
4. Op datum, Hierbij kunt u een begin en eindatum opgeven om een periode (bijvoorbeeld jaar) te doorzoeken publicatiedatum[after]=2022-12-31T23:59:59Z&publicatiedatum[before]=2024-01-01T00:00:00Z&
1. Op een of meerdere zoek woorden, b.v. `?_search=test`
2. Op organisatie, dit gaat aan de hand van OIN (de volledige OIN lijst vind u [hier](https://oinregister.logius.nl/oin-register)) b.v. `?organisatie.in=00000001001299992000`
3. Op categorie, `?categorie=Convenant`
4. Op datum, Hierbij kunt u een begin en eindatum opgeven om een periode (bijvoorbeeld jaar) te doorzoeken `?publicatiedatum[after]=2022-12-31T23:59:59Z&publicatiedatum[before]=2024-01-01T00:00:00Z&`

````cli
GET 'https://api.gateway.commonground.nu/api/publicaties?extend[]=all&_search=Afvalwaterakkoord&_order[publicatiedatum]=desc&_limit=12&_page=1'
Expand Down Expand Up @@ -137,28 +143,34 @@ Response
````

### Metadata
De kern gegevens van een WOO publicatie zitten in het metadata object, de inhoud van dit object is 'semi' vrij, hij kan per publicatie `categorie` verschillen. Daarnaast zijn er een paar algemene properties die altijd kunnen voorkomen in de metadata
De kern gegevens van een Woo publicatie zitten in het metadata object, de inhoud van dit object is 'semi' vrij, hij kan per publicatie `categorie` verschillen. Daarnaast zijn er een paar algemene properties die altijd kunnen voorkomen in de metadata

#### Algemene properties

| Property | Verplicht | Gebruik | Toegestane waardes |
|---------------------|-----------|---------------------------------------------------------------------------------------------------------|--------------------|
| Property | Verplicht | Gebruik | Toegestane waardes |
|-----------------------|---------------|--------------|-----------------------|
| besluitdatum | Nee | Detailpagina | String in date format |
| ontvangstdatum | Nee | Detailpagina | String in date format |
| informatieverzoek | Nee | Detailpagina | Bijlage object |
| besluit | Nee | Detailpagina | Bijlage object |
| inventarisatielijst | Nee | Detailpagina | Bijlage object |
| termijnoverschrijding | Nee | Detailpagina | String |


#### Convenanten

| Property | Verplicht | Gebruik | Toegestane waardes |
|---------------------|-----------|---------------------------------------------------------------------------------------------------------|--------------------|
| Property | Verplicht | Gebruik | Toegestane waardes |
|-----------------------|---------------|--------------|-----------------------|

#### Woo verzoeken

| Property | Verplicht | Gebruik | Toegestane waardes |
|---------------------|-----------|---------------------------------------------------------------------------------------------------------|--------------------|
| Property | Verplicht | Gebruik | Toegestane waardes |
|-----------------------|---------------|--------------|-----------------------|

#### Klachten

| Property | Verplicht | Gebruik | Toegestane waardes |
|---------------------|-----------|---------------------------------------------------------------------------------------------------------|--------------------|
| Property | Verplicht | Gebruik | Toegestane waardes |
|-----------------------|---------------|--------------|-----------------------|

### Spelregels

Expand Down
2 changes: 2 additions & 0 deletions pwa/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ COPY package.json package-lock.json ./
# install node modules and build assets
RUN npm install

RUN npm install @parcel/watcher

COPY . .

RUN npm run build
Expand Down
Loading
Loading