diff --git a/README.md b/README.md index 18daa76..988374d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # Wat is Open Catalogi? -Open Catalogi is een standaard die eigenlijk bestaad uit een versameling van andere standaarden (o.a. [FSC](), [DCAT](), [APNL](), [MDTO](), [Publiccode](), [TOOI]()) de gemeenschappenlijk beschrijven hoe catalogusen kunnen worden vormgegeven op een manier waardoor ze gesamenlijk één virtuele catalogus vormen. Hierdoor blijdt de data bij de bron (organisatie) en zijn er geen landelijke indexen nodig. +Open Catalogi is een standaard die eigenlijk bestaad uit een versameling van andere standaarden (o.a.[NL Gog profile for cloud events](https://www.logius.nl/domeinen/gegevensuitwisseling/nl-gov-profile-cloudevents), [NL GOV profile for OAuth 2.0](https://www.forumstandaardisatie.nl/open-standaarden/nl-gov-assurance-profile-oauth-20) [FSC](), [DCAT](), [APNL](), [NL API strategie](), [MDTO](), [Publiccode](), [TOOI]()) de gemeenschappenlijk beschrijven hoe catalogusen kunnen worden vormgegeven op een manier waardoor ze gesamenlijk één virtuele catalogus vormen. Hierdoor blijdt de data bij de bron (organisatie) en zijn er geen landelijke indexen nodig. 1. Een API standaard voor het koppelen van catalogi 2. Een architectuur voor eht gedrag van catalogi @@ -30,84 +30,15 @@ Vanuit de gedachte van een federatief stelsel is iedere deelnemer verantwoornlij Wat OpenCatalogi uniek maakt, is dat de frontend serverless (via GitHub) kan draaien, waardoor deelnemende organisaties OpenCatalogi niet zelf hoeven te installeren om het te kunnen gebruiken. Zowel de frontend als de gegevens kunnen worden gehost op GitHub. -## Snelle Start - - - - - -Voor het beschikbaar stellen van publicaties of zelfs uw eigen catalogus heeft u geen eigen server nodig, maar wel een [GitHub-organisatie](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch) waarvan u de beheerder bent. - -**Om uw repository bekend te maken en vindbaar te maken:** - -De snelste manier is de URL van uw repository [hier](https://opencatalogi.nl/documentation/usage/) op te geven. Uw repository met uw componenten zijn dan (vrijwel) direct zichbaar. - -Wilt uw meer controle over het tonen van de componenten of extra informatie meegeven, dan is de de handmatige wijze is hieronder te volgen. - -1. Maak binnen uw repository een map met de naam `.github`, maak daarbinnen een map met de naam `workflows` aan en maak daarin een bestand met de naam `openCatalogi.yaml`. De volledige padnaam wordt dus `[uw repository naam]/.github/workflows/openCatalogi.yaml`. -3. Plaats de volgende YAML-code in het bestand `openCatalogi.yaml`: +## Varianten +Hoewel Open Catalogi zich in princiepe leent voor het publiceren van alles (het besschrijft immers alleen een stelsel van samenwerkende catalogi) zien we binnen het poject een aantal varianten naar voren komen: -```yaml -name: Mijn Open Catalogi Workflow +- **Software catalogus** Van oorsprong is het Open Catalogi als project begonnen om een alternatief te bieden voor de [commonground componenten vatalogus]() waarbij het niet langer noodzakenlijk is om infortmatie te brengen. In plaatsdaarvan wordt deze opgehaald aan de hand van een publiccode.yaml bestand. +- **OpenWoo.app** Het doorzoekbaar maken van data t.b.v. (WOO)[] +- **Datacatalogus** Het beschickbaar stellen van high value datasets voor de t.b.v. (WHO)[] -on: - workflow_dispatch: - push: - branches: - - main - -permissions: - contents: write - -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Create or Update publiccode.yaml - uses: OpenCatalogi/publiccode-action@1.1.1 - with: - opencatalogi: true - - name: Create een Productpagina - uses: OpenCatalogi/productpage-action@1.0.0 -```` - -4. Voor extra configuratieopties en stappen kunt u kijken naar de [Product Page](https://github.com/marketplace/actions/create-an-product-page) en [Publiccode](https://github.com/marketplace/actions/create-or-update-publiccode-yaml) acties op Github. - -**Om uw organisatie bekend te maken en uw eigen catalogus te starten:** - -1. Zorg ervoor dat uw organisatie een repository heeft met de naam `.github`. -2. Maak binnen deze repository een map met de naam `.github`, maak daarbinnen een map met de naam `workflows` aan en maak daarin een bestand met de naam `openCatalogi.yaml`. De volledige padnaam wordt dus `.github/.github/workflows/openCatalogi.yaml`. -3. Plaats de volgende YAML-code in het bestand `openCatalogi.yaml`: - -````yaml -name: My Open Catalogi Workflow - -on: - workflow_dispatch: - push: - branches: - - main - -permissions: - contents: write - -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Create or Update opencatalogi.yaml - uses: OpenCatalogi/publiccode-action@1.1.1 - with: - opencatalogi: true - - name: Create an Open Catalogi page - uses: OpenCatalogi/opencatalogi-action@1.1.1 -```` +## Snelle Start -4. Voor extra configuratieopties en stappen kunt u kijken naar de [Catalogi Page](https://github.com/marketplace/actions/create-an-open-catalogi-page) en [Publiccode](https://github.com/marketplace/actions/create-or-update-publiccode-yaml) acties op Github. -Voor meer details, het installeren van een eigen index en het afschermen van toegang zie [Installatie](/docs/handleidingen/Installatie.md). -## Meedoen aan Open Catalogi -Organisaties kunnen op verschillende manieren deelnemen aan het OpenCatalogi-project. Of u nu financieel wilt bijdragen aan de doorontwikkeling, deel wilt nemen aan de stuurgroep, of simpelweg de ontwikkelingen wilt volgen en feedback wilt geven, er is een vorm van deelname die bij uw organisatie past. Raadpleeg het gedeelte [Deelname aan het Open Catalogi Project](/docs/GOVERNANCE.md) - voor meer informatie over hoe u kunt aansluiten en bijdragen. diff --git a/docs/handleidingen/Architectuur.md b/docs/handleidingen/Architectuur.md index 0c20be0..a0b49b5 100644 --- a/docs/handleidingen/Architectuur.md +++ b/docs/handleidingen/Architectuur.md @@ -4,7 +4,6 @@ OpenCatalogi biedt een manier om meerdere catalogi samen te laten werken als é In de zin van GEMMA/NORA architectuur geeft OpenCatalogi hiermee invulling aan het concept generieke publicatievoorziening. - ![UML Diagram van OpenCatalogi](https://raw.githubusercontent.com/OpenCatalogi/.github/main/docs/handleidingen/components_simple.svg "UML Diagram van OpenCatalogi") Als we vervolgens inzoemen op een catalogus bestaad die feitenlijk uit vier functionele delen (Beheer UI, Gebruikers UI, Beheer API, Zoeken API) en 2 opslag componenten (Zoekindex en Oojecten opslag). Daarbij is het interactie vlak van de API's gedefineerd in de Open Catalogi standaard([OAS]()) en het gedrag in [architectuur](). @@ -34,6 +33,32 @@ Dan komen we tot de volgende architectuurplaat Het basisobject van OpenCatalogi is een catalogus. Elke catalogus is een verzameling publicaties. Publicaties vertegenwoordigen 'iets' dat moet worden gepubliceerd. Wat dat 'iets' is, wordt gedefinieerd door een metadatabeschrijving (gedefinieerd door een [schema.json](https://json-schema.org/)). Catalogi kunnen publicaties van verschillende typen bevatten (bijv. datasets van de [WHO](https://www.who.int/data/sets), verzoeken van de [WOO](https://www.rijksoverheid.nl/onderwerpen/wet-open-overheid-woo#:~:text=Is%20de%20informatie%20die%20je,dat%20aan%20je%20worden%20gemeld.), of repositories van [publiccode](https://docs.italia.it/italia/developers-italia/publiccodeyml-en/en/master/index.html)). Publicaties MOETEN bij ÉÉN catalogus horen, en elke catalogus MOET bij ÉÉN organisatie horen, wat betekent dat publicaties traceerbaar zijn naar organisaties via hun catalogus. +## API's +De API's van Open Catalogi zijn voor nu nog terug te vinden op https://conduction.stoplight.io/docs/open-catalogi. Het is een wens om deze in de zomer naar redocly te verplaatsen. + +## Codebases + +| Codebase | Rol | Organisatie | Licentie | +|----------|------------------------------| | | +| [Github](https://github.com/ConductionNL/web-app)| Publicatie Platform | Open Catalogi | | +| [Github](https://github.com/ConductionNL/opencatalogi)| Beheer API, Zoeken API, Beheer Interface | Open Catalogi | EUPL | +| [Github](https://github.com/maykinmedia/objects-api)| ORC (objecten opslag) | Maykin Media | EUPL | +| [Github](https://github.com/open-zaak/open-zaak) | DRC (documenten opslag) | Maykin Media | EUPL | +| [Github](https://github.com/elastic/elasticsearch) | Elastic Search | Elastic | SPL + EL | +| [Github](https://github.com/OpenCatalogi/OpenCatalogiBundle) | Synchronysatie Service | Conduction | EUPL | + + +Hierop zijn een paar opmerkingen te maken +- We hebben recentenlijk de keuze gemaakt om over te stappen op nextcloud, meer hierover kan je teruglezen op [https://documentatie.opencatalogi.nl/Handleidingen/Nextcloud/](https://documentatie.opencatalogi.nl/Handleidingen/Nextcloud/). +- Het inzetten van ORC, DRC en Elastic zijn vanuit Open Catalogi gezien (geadviseerde) keuzes. Het is ook mogenlijk om alles in een interne database of externe object store op te slaan. +- De Synchronysatie service draaid momenteel nog op het common gateway platform, er is echter voor gekozen om ook deze over te brengen naar nextcloud. +- Beheer API en Zoeken API worden samen met de beheer interface geleverd door één code base, een praktische inrichtingskeuze die we hebben overgenomen van Open Zaak. Voor organisaties die componenten graag splitsen in containers zijn ze echter ook los instaleerbaar. +- Het is ook mogenlijk om de zoeken API direct vanuit elastic search uit te leveren, dat heeft een aanzienlijk performance voordeel. Maar verhinderd ook het federatief zoeken. +- Voor het ORC en DRC zijn aanvullende compenten beschickbaar/benodigd (OTC, Notificaties etc) die laten we hier voor het overzicht even weg + +## Functionaliteit Beheer omgeving +Een flink stuk van de randvoorwaardenlijke functionaleit van Open Catlogi (zoals ADFS) wordt afgevangen in de Beheer interface. + ## Federatief zoeken Elke installatie van OpenCatalogi biedt een zoek-endpoint waarmee gezocht kan worden in de catalogi die bij die installatie horen, waardoor meerdere catalogi tegelijk doorzocht kunnen worden. Elke installatie van OpenCatalogi houdt ook andere OpenCatalogi-installaties bij en registreert deze in zijn `directory`. Dit biedt de basisvoorwaarden voor het federatief zoeken. diff --git a/docs/handleidingen/Nextcloud.md b/docs/handleidingen/Nextcloud.md index f66531a..64aca8e 100644 --- a/docs/handleidingen/Nextcloud.md +++ b/docs/handleidingen/Nextcloud.md @@ -1,6 +1,10 @@ -# Waarom Conduction Overstapt naar Nextcloud +# Waarom we overstappen naar Nextcloud -Bij Conduction hebben we na jaren van ontwikkeling op ons eigen API-platform geconcludeerd dat bepaalde elementen beter opgelost kunnen worden met een ander framework. Onze keuze viel op Nextcloud, een open source framework, dat perfect aansluit bij onze behoeften aan bestandsopslag, ADFS-authenticatie en beveiliging. +Alle eerste iteraties van Open Catalogi draaiden op het [https://api-platform.com/](api platform) freamework van [digital state](https://digitalstate.io/). Recentenlijk zijn we begonnen met de overstap naar [nextcloud](https://nextcloud.com/), waarom zou je dat in hemelsnaam doen? + +Wel innovatie betekend expirimenteren, 5 dingen proberen en er 4 loslaten. En hellaas is API platform voor ons een van de dingen die we los gaan laten. Niet omdat het een slecht framework is. In tegendeel, het is een technisch sterk framework voor register ontwikkeling. Maar het is ook abstract, technisch niet super makenlijk uit te rollen. + +Daarnaast zien we dat nextcloud (met europese steun) een sterke opmars maakt bij (buitenlandse) overheden ## Redenen voor de Overstap diff --git a/docs/handleidingen/Software.md b/docs/handleidingen/Software.md index 212180a..ed1a825 100644 --- a/docs/handleidingen/Software.md +++ b/docs/handleidingen/Software.md @@ -1,2 +1,78 @@ # Software Catalogus + +Voor het beschikbaar stellen van publicaties of zelfs uw eigen catalogus heeft u geen eigen server nodig, maar wel een [GitHub-organisatie](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch) waarvan u de beheerder bent. + +**Om uw repository bekend te maken en vindbaar te maken:** + +De snelste manier is de URL van uw repository [hier](https://opencatalogi.nl/documentation/usage/) op te geven. Uw repository met uw componenten zijn dan (vrijwel) direct zichbaar. + +Wilt uw meer controle over het tonen van de componenten of extra informatie meegeven, dan is de de handmatige wijze is hieronder te volgen. + +1. Maak binnen uw repository een map met de naam `.github`, maak daarbinnen een map met de naam `workflows` aan en maak daarin een bestand met de naam `openCatalogi.yaml`. De volledige padnaam wordt dus `[uw repository naam]/.github/workflows/openCatalogi.yaml`. +3. Plaats de volgende YAML-code in het bestand `openCatalogi.yaml`: + +```yaml +name: Mijn Open Catalogi Workflow + +on: + workflow_dispatch: + push: + branches: + - main + +permissions: + contents: write + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Create or Update publiccode.yaml + uses: OpenCatalogi/publiccode-action@1.1.1 + with: + opencatalogi: true + - name: Create een Productpagina + uses: OpenCatalogi/productpage-action@1.0.0 +```` + +4. Voor extra configuratieopties en stappen kunt u kijken naar de [Product Page](https://github.com/marketplace/actions/create-an-product-page) en [Publiccode](https://github.com/marketplace/actions/create-or-update-publiccode-yaml) acties op Github. + +**Om uw organisatie bekend te maken en uw eigen catalogus te starten:** + +1. Zorg ervoor dat uw organisatie een repository heeft met de naam `.github`. +2. Maak binnen deze repository een map met de naam `.github`, maak daarbinnen een map met de naam `workflows` aan en maak daarin een bestand met de naam `openCatalogi.yaml`. De volledige padnaam wordt dus `.github/.github/workflows/openCatalogi.yaml`. +3. Plaats de volgende YAML-code in het bestand `openCatalogi.yaml`: + +````yaml +name: My Open Catalogi Workflow + +on: + workflow_dispatch: + push: + branches: + - main + +permissions: + contents: write + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Create or Update opencatalogi.yaml + uses: OpenCatalogi/publiccode-action@1.1.1 + with: + opencatalogi: true + - name: Create an Open Catalogi page + uses: OpenCatalogi/opencatalogi-action@1.1.1 +```` + +4. Voor extra configuratieopties en stappen kunt u kijken naar de [Catalogi Page](https://github.com/marketplace/actions/create-an-open-catalogi-page) en [Publiccode](https://github.com/marketplace/actions/create-or-update-publiccode-yaml) acties op Github. + +Voor meer details, het installeren van een eigen index en het afschermen van toegang zie [Installatie](/docs/handleidingen/Installatie.md). + +## Meedoen aan Open Catalogi + +Organisaties kunnen op verschillende manieren deelnemen aan het OpenCatalogi-project. Of u nu financieel wilt bijdragen aan de doorontwikkeling, deel wilt nemen aan de stuurgroep, of simpelweg de ontwikkelingen wilt volgen en feedback wilt geven, er is een vorm van deelname die bij uw organisatie past. Raadpleeg het gedeelte [Deelname aan het Open Catalogi Project](/docs/GOVERNANCE.md) + voor meer informatie over hoe u kunt aansluiten en bijdragen. diff --git a/docs/handleidingen/components.svg b/docs/handleidingen/components.svg index f844687..c15f978 100644 --- a/docs/handleidingen/components.svg +++ b/docs/handleidingen/components.svg @@ -1 +1 @@ -ComponentsOpen CatalogiInternetFederatief netwerkCatalogiExterne ApplicatiesBronnenKubernetesLayer 5 (interaction)React NL DesignVue NL DesignLayer 4 (Logic)Layer 2 (API)Next Cloud frameworkSearch APICRUD APILayer 1 (data)SearchObject StoreDMSBurgerMedewerkerBeheerderExterne CatalogusZaaksysteemEtc.User InterfaceAdmin InterfaceSynchronysationsOpen IndexOpen RegistersElastic SearchORCDRCBrowser ANONIEMBrowser ANONIEMBrowser JWT tokenOpzoekenOpslaanData opslaanDocumenten opslaanOpzoekenUpdatenUpdatenDirectory uitwisselenOpzoekenSynchronyserenSynchronyserenOpen Catalogi | Components \ No newline at end of file +ComponentsOpen CatalogiInternetFederatief netwerkCatalogiExterne ApplicatiesBronnenKubernetesLayer 5 (interactie)Publicatie platformBeheer InterfaceLayer 4 (logica)Layer 2 (API)Next Cloud frameworkZoeken APIBeheer APILayer 1 (data)SearchObject StoreDMSBurgerMedewerkerBeheerderExterne CatalogusZaaksysteemEtc.React NL DesignVue NL DesignSynchronysationsOpen IndexOpen RegistersElastic SearchORCDRCBrowser ANONIEMBrowser ANONIEMBrowser JWT tokenOpzoekenOpslaanData opslaanDocumenten opslaanOpzoekenUpdatenUpdatenDirectory uitwisselenOpzoekenSynchronyserenSynchronyserenOpen Catalogi | Components \ No newline at end of file diff --git a/docs/handleidingen/components_commonground.svg b/docs/handleidingen/components_commonground.svg new file mode 100644 index 0000000..d9cf707 --- /dev/null +++ b/docs/handleidingen/components_commonground.svg @@ -0,0 +1 @@ +MatrixOpen CatalogiLayer 5 (interactie)Layer 2 (api)Layer 1 (data)Beheer InterfacePublicatie platformGebruikers APIZoeken APISearch indexObjecten opslagOpslaanOpzoekenOpslaanZoekenUpdatenOpen Catalogi | Components \ No newline at end of file diff --git a/docs/handleidingen/components_matrix.svg b/docs/handleidingen/components_matrix.svg index 5c23419..a26993d 100644 --- a/docs/handleidingen/components_matrix.svg +++ b/docs/handleidingen/components_matrix.svg @@ -1 +1 @@ -MatrixOpen CatalogiAdmin InterfaceUser InterfaceCRUD APISearch APISearch indexObjecten opslagOpslaanOpzoekenOpslaanZoekenUpdatenOpen Catalogi | Components \ No newline at end of file +MatrixOpen CatalogiBeheer InterfacePublicatie platformGebruikers APIZoeken APISearch indexObjecten opslagOpslaanOpzoekenOpslaanZoekenUpdatenOpen Catalogi | Components \ No newline at end of file