From 861250f7e5052ea3f0527d366f9dd27b9ca4481b Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 16:49:18 +0100 Subject: [PATCH 01/30] Moved architectuur to folder --- docs/{ => architectuur}/Architectuur.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) rename docs/{ => architectuur}/Architectuur.md (98%) diff --git a/docs/Architectuur.md b/docs/architectuur/Architectuur.md similarity index 98% rename from docs/Architectuur.md rename to docs/architectuur/Architectuur.md index b9ef645..80b9a1e 100644 --- a/docs/Architectuur.md +++ b/docs/architectuur/Architectuur.md @@ -1,5 +1,5 @@ -# Architectuur - - - -_Klik op de afbeelding om een grotere versie te zien._ +# Architectuur + + + +_Klik op de afbeelding om een grotere versie te zien._ From e3ad92299793db603e0ff265e4ea449ce697a6ae Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 17:02:34 +0100 Subject: [PATCH 02/30] Moved and renamed decision-record, changed to rst --- .../decision-record/decision-record.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{DECISION-RECORD.md => architectuur/decision-record/decision-record.rst} (100%) diff --git a/docs/DECISION-RECORD.md b/docs/architectuur/decision-record/decision-record.rst similarity index 100% rename from docs/DECISION-RECORD.md rename to docs/architectuur/decision-record/decision-record.rst From 49f872de9dca37fc6442961d83bba760e3a0b468 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 17:06:56 +0100 Subject: [PATCH 03/30] update contents to rst --- .../decision-record/decision-record.rst | 165 ++---------------- 1 file changed, 16 insertions(+), 149 deletions(-) diff --git a/docs/architectuur/decision-record/decision-record.rst b/docs/architectuur/decision-record/decision-record.rst index 7b06b1e..a427a72 100644 --- a/docs/architectuur/decision-record/decision-record.rst +++ b/docs/architectuur/decision-record/decision-record.rst @@ -1,149 +1,16 @@ - -# Ontwerpbeslissingen. -KISS is ontwikkeld met een eindgebruikersgroep van Klantcontactmedewerkers (KCMs) van verschillende gemeenten. Uitgangspunt bij de ontwikkeling van KISS was om de beschikbare standaarden uit de Common Ground te gebruiken. Daar waar er vanuit de gebruikersgroep een informatiebehoefte was, maar waar nog geen (plek binnen de) standaard voor was, is een ontwerpbeslissing genomen wat hiermee te doen (zie ook [20230616-PodiumD-flow-afwijkingen-standaarden.pdf](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/files/20230616-PodiumD-flow-afwijkingen-standaarden.pdf)). Op het moment dat er een gegevensbehoefte is binnen de applicatie, waarvoor nog geen (volledige) gegevensstandaard beschikbaar is, is de eerste vervolgvraag of deze gegevens ook beschikaar moeten zijn voor ándere applicaties binnen het landschap. Als dat niet het geval is, dan kunnen de gegevens binnen de applicatie zelf worden opgeslagen. Moeten de gegevens ook beschikbaar zijn voor andere applicaties, dan kiezen we ervoor om op basis van een gegevensontwerp een Objecttype aan te maken in de Objectenregistratie. - -## Contactmomenten -### Contactmomentdetails - -Voor de onderstaande gegevens is tijdens fase 1C deze afweging gemaakt, en besloten de gegevens op te slaan binnen KISS zelf. Het gaat om gegevens van een contactoment die niet in het Contactmomentenregister passen. Deze gegevens leveren managementinformatie over de werkzaamheden van het KCC. Zie ook de issues [#21](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/issues/21), [#111](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/issues/111), [#610](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/issues/610), [#611](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/issues/611). -Ze worden opgeslagen binnen KISS, en zijn op te vragen via de Contactmomentdetails API. Zie de [Handleiding beheer KISS, hoofdstuk managementinformatie](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/MANUAL.md#management-informatie) voor informatie over het gebruik van deze API. - - -| Property | Type | Toelichting | -|--------|--------|--------| -| `vraag` | string (uri) | De URL's van geraadpleegde bronnen
(Kennisbankartikelen / productpagina's, Vraag-
Antwoord Combinaties (VAC) en
nieuws/werkinstructies) slaan we op in het property
`onderwerpLinks`. Voor Managementinformatie is dit
niet specifiek genoeg. Daarom kan een KCM één van de
bronnen selecteren bij "Vraag". De titel van deze
bron wordt opgeslagen in `vraag`.
Bij VAC's is dit de vraag. Bij Kennisartikelen /
productpagina's is dit de titel van het artikel plus
één van de geraadpleegde subonderdelen binnen het
artikel. Deze wordt in KISS ook gebruikt in de weergave
van Contactmomenten: hiermee kan een KCM zien wat
de vraag van de klant was. | -| `specifiekeVraag` | string | In het afhandelscherm kan een KCM de eigenlijke
klantvraag invullen. Bijvoorbeeld omdat de `vraag` de
eigenlijke vraag niet echt dekt. Of omdat het een nieuwe
vraag is, die nog niet in de bron is verwerkt (sticker in je
paspoort). Ook deze informatie is in te zien door de
KCM bij het bekijken van Contactmomenten. | -| `gespreksresultaat` | string | Hierin slaan we het gespreksresultaat van het
contactmoment op, bijvoorbeeld 'Doorverbonden' of
'Zelfstandig afgehandeld'. | -| `startdatum` | string (date-time) | De tijd waar op het Contactmoment is gestart. Samen
met `einddatum` bepaaalt dit de gespreksduur. | -| `einddatum` | string (date-time) | De tijd waarop het Contactmoment is beëindigd.
Samen met `startdatum` bepaaalt dit de gespreksduur. | -| `verantwoordelijkeAfdeling` | string | Dit is de afdeling voor wie het contactmoment is
afgehandeld. Deze moet de KCM kiezen in het
afhandelscherm. Waar mogelijk wordt deze
vooringevuld vanuit de gekozen bron bij `vraag`. | -| `gespreksId` | string (uuid) | Een klant kan meerdere vragen stellen binnen één
interactie met een Klantcontactmedewerker (KCM).
Voor iedere vraag wordt een contactmoment
aangemaakt. We hebben het property `gespreksId`
toegevoegd. In het geval van 2 of meer vragen binnen één
interactie, worden de vragen aan elkaar verbonden,
doordat al deze contactmomenten hetzelfde `gespreksId`
krijgen. | - -## Contactverzoeken - -### Contactverzoek als interneTaak -Voor Contactverzoeken is nog niet een éénduidige standaard. Sommige gemeenten zien een contactverzoek (terugbelverzoek) als een Zaak. Voor meerdere gemeenten binnen de projectgroep van KISS is dat geen optie. Binnen de [nieuwe standaard Klantinteracties](https://vng-realisatie.github.io/klantinteracties/) is het concept Interne taak geïntroduceerd dat ingezet kan worden voor het Contactverzoek (zie bv. [C9167 - Klant belt KCC met een vraag die niet direct beantwoord kan worden en maakt een terugbelverzoek](https://vng-realisatie.github.io/klantinteracties/achtergronddocumentatie/artefacten/9167.html)). - -Vooruitlopend op deze standaard is voor KISS een nieuw objecttype voor de interne taak ingericht. Omdat een contactverzoek in zijn geheel afhankelijk is van meerdere nieuwe objecten (betrokkene, actor) die nog niet uitgewerkt zijn als standaard (op moment van ontwikkelen, mei-juni 2023), is er voor gekozen om deze objecten als subobject op te nemen in het objecttype interne taak. Dit objecttype is als community concept beschikbaar bij [de Community concepts binnen Objecttypes, bij Open Objecten](https://github.com/open-objecten/objecttypes/tree/main/community-concepts). - -### Afdelingen en groepen -Een Contactverzoek moet binnen de eigen organisatie worden opgepakt. Binnen Klantinteracties is hiervoor het Actor-object beschikbaar, die van het soort `medewerker`, `organisatorische eenheid` of `geautomatiseerde actor` kan zijn (zie [Gegevenswoordenboek Klantinteracties, 2023-10-19T10:33:57.000+02:00](https://vng-realisatie.github.io/klantinteracties/informatiemodel/gegevenswoordenboek)). KISS maakt gebruik van de eerste twee soorten. Binnen de gebruikersgroep was de behoefte om bij `organisatorische eenheid` onderscheid te kunnen maken tussen Afdeling of Groep. Daarom zijn er ook twee objecttypen hiervoor gemaakt: afdeling en groep. Ook deze objecttypen staan bij [de Community concepts](https://github.com/open-objecten/objecttypes/tree/main/community-concepts). - -Bij de opzet van deze objecten zijn we uitgegaan van een hierarchische relatie tussen Afdeling, Groep en Medewerker. Bij de integratie van KISS met de e-Suite (in gebruikt bij Dimpact-gemeenten), in januari-februari 2024, blijkt dat de hierarchische relatie tussen afdelingen en groepen niet altijd bestaat. Groepen zijn daar een ander soort verzameling van medewerkers. Daarom is er een aanpassing gedaan in het groep-object, om te zorgen dat het `afdelingId` niet verplicht is (zie [PR 13](https://github.com/open-objecten/objecttypes/pull/13)). - -Op plekken waar we naar afdelingen zoeken (bv. afdeling bij kennisartikelen, of bij medewerker) is de afdeling/groepsnaam gekozen als zoeksleutel. Dit is gedaan op basis van de toen beschikbare (test)data. Daarin was alleen naam altijd aanwezig, identificatie niet altijd. - - -### Medewerkers en smoelenboek -Een KCM wil kunnen zoeken in bronnen met informatie, maar ook kunnen zoeken naar informatie over collega’s [#96](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/issues/96). Ook hier is nog geen standaard voor. In KISS Fase 1B is een voorzet gedaan voor een Medewerker API (gebaseerd op de [HR-JSON-standaarden van HR Open Standards](https://www.hropenstandards.org/)). In KISS Fase 1C is deze verplaatst naar de Objecten API ( zie [de Community concepts](https://github.com/open-objecten/objecttypes/tree/main/community-concepts).) De objecten van het smoelenboek zijn geindexeerd in Elastic. Bij het doorzetten van een contactverzoek naar een medewerker, gebruiken we de gegevens uit Elastic. - -Bij de integratie van KISS met de e-Suite (in gebruikt bij Dimpact-gemeenten), blijkt dat de naam van een medewerker niet altijd beschikbaar is in de onderdelen `voornaam`, `voorvoegselAchternaam` en `achternaam`. Daarom zijn de properties `voornaam` en `achternaam` niet langer verplicht, en is het property `volledigeNaam` toegevoegd. (zie [PR 13](https://github.com/open-objecten/objecttypes/pull/13)) - -## Zoeken in bronnen -### Kennisartikelen / productpagina's (PDC) en VAC's -Een KCM wil kunnen zoeken in bronnen om de vraag van een klant te kunnen beantwoorden (zie [#22](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/issues/22)). Voor Kennisartikelen / productpagina's en VAC's zijn ook nog geen defintieve standaarden. Binnen KISS Fase 1C hebben we voor deze twee bronnen objectdefinties gemaakt, gebaseerd op standaarden in wording in overleg met architecten van Dimpact. - -- Het object PDC - Kennisartikel is gebaseerd op de API voor [de SDG-invoervoorziening](https://github.com/maykinmedia/sdg-invoervoorziening) ([versie 1.7.2](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/maykinmedia/sdg-invoervoorziening/1.7.2/src/openapi.yaml&nocors)). Daar zijn properties aan toegevoegd t.b.v. de behoeften van een KCM (interne informatie, informatie over contact opnemen, informatie over bijzonderheden, trefwoorden en verantwoordelijke afdeling). -- Het object VAC is gebaseerd op een vergelijking van PDC - Kennisartikel, met de structuur van VAC's in SDU-catalogus. - -Beide objecten staan bij [de Community concepts](https://github.com/open-objecten/objecttypes/tree/main/community-concepts). - - -## Contactmoment: de uitgebreide POST -KISS schrijft Contactmomenten weg m.b.v. de VNG Contactmomenten API zoals deze is geïmplementeerd in Open Klant v0.5-pre. In een eerdere versie van KISS waren de gegevens die nu in Contactmomentdetails zitten, onderdeel van het uitgebreide Contactmoment. Omdat in KISS 1C de weg is gekozen om bestaande standaarden niet uit te breiden, zijn deze gegevens verplaatst naar Contactmomentdetails. Maar: ze zijn nog steeds onderdeel van de POST die KISS doet op de Contactmomenten API. het ontvangende register negeeert deze onderdelen, en registreert alleen het object zoals gedefinieerde in de Contactmomenten API. - -Bij de integratie met de e-Suite (in gebruikt bij Dimpact-gemeenten), in januari-februari 2024, is een additionele [uitbreiding gedaan van de POST-data in contactmoment](POST-contactmoment.md). - -## Zaken: het zaakdetailscherm -In onderstaande afbeelding is gedocumenteerd welke gegevens uit de verschillen ZGW-objecten worden gebruikt in het Zaak-detailscherm. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/add-decision-record/docs/images/MappingZaakDetail.png) - -## Logging voor verwerking -Omdat er nog geen definitieve standaard voor logging voor verwerking was in KISS Fase 1C, is er een voorbereiding gedaan t.b.v. een API voor verwerkingslogging, om de algemene werking alvast op te zetten totdat er een standaard beschikbaar is. Elke keer dat er een api call wordt gedaan naar externe systemen, loggen we UserID, datum/tijd, het api-endpoint dat werd aangeroepen, en de methode waarmee het endpoint werd aangeroepen. Deze logging staat los van de errorlogging. Er is een zeer basaal API-endpoint voor ingericht. - -## Autorisatie -KISS is ontwikkeld met het oog op gebruik van een aantal api's (Klanten API, Contactmomenten, ZGW API's, Objecten API en Objecttypen API). Deze API's gaan ervan uit dat de autorisatie door de aanroepende applicatie wordt gefaciliteert en niet door het register zelf. Daarom gebeurt het inrichten van de autorisatie op applicatieniveau en niet op gebruikersniveau. En daarom worden er géén user tokens meegestuurd vanuit KISS naar de onderliggende registers, tenzij dat vereist wordt om specifieke redenen zoals bv. logging. - -Bij de eerste implementatie van KISS binnen een gemeente, moet KISS koppelen met een ouder register, de e-Suite. Deze kan de autorisatie (wat een gebruiker mag zien en doen) doen op gebruikerniveau. Als KISS op de e-Suite koppelt met gebruikmaking van de bestaande 'autorisatie-op-applicatieniveau', dan kan een KISS-gebruiker zaken en contacten zien, die deze gebruiker in de e-Suite niet mag zien. Om dat te voorkomen moet KISS dus een fijnmaziger autorisatie op gebruikersniveau mogelijk kunnen maken bij aansluiting op een onderliggend register. Hierdoor is de noodzaak onstaan om wél bij elk request userid mee te kunnen sturen in een JWT-token. - -Hierop is de koppeling met Overige Objecten aangepast: met moet namelijk, afhankelijk van configuratie per objecttype, mogelijk zijn om de calls naar het onderliggende register ófwel te voorzien van een token, ófwel van een token met user-id. - - -## Klantinteracties en OpenKlant -Bij het koppelen van KISS aan de Klanteracties-API's zoals die in Open Klant 2 zijn geimplementeerd, hebben we een aantal keuzes gemaakt bij de inrichting van de gegevens, die in Klantinteracties door de VNG zijn beschreven als items op een Referentielijst. - -### Partij-identificatoren - -We gebruiken de volgende codes in partij-identificatoren - -**Natuurlijke persoon**
-- codeObjecttype: "inp" > natuurlijke persoon -- codeSoortObjectId: "bsn" > BSN van de natuurlijke persoon - - -**Vestiging**
-- codeObjecttype: "vst" > Vestiging uit het Handelsregister -- codeSoortObjectId: "vtn" > Vestigingsnummer van de vestiging in het Handelsregister - -**Niet natuurlijke persoon (rechtspersoon zonder vestigingsnummer)** -- codeObjecttype: "nnp" > Niet-natuurlijke persoon uit het Handelsregister -- codeSoortObjectId: "rsin" > RSIN van de Niet-natuurlijke persoon in het Handelsregister - -**KvK-nummer**
-Bij Partijen van het type Organisatie, die we uit het handelsregister ophalen slaan we altijd ook een tweede partij-identificator op, met daarin het KvKnummer: -- codeObjecttype: "nnp" > Niet-natuurlijke persoon uit het Handelsregister -- codeSoortObjectId: "kvk" > Het KvK-nummer van de vestiging of Niet-natuurlijke persoon in het Handelsregister - -**Registers** -- codeRegister: "brp" > register waar het BSN van de natuurlijke persoon te vinden is -- codeRegister: "hr" > verwijzing naar het handelsregister (voor vestigingsnummer,KvK-nummer en RSIN) -- codeRegister: "msei" > verwijzing naar Microsoft EntraId, waar gegevens van de ingelogde gebruiker in staan. - -### Digitale adressen -Bij het ophalen en opslaan van telefoonnummers en e-maiadressen, gebruiken we bij `soortDigitaalAdres`de waarde van de Code uit een voorzet van referentielijsten. Bij Omschrijving gebruiken we de waarde van Naam uit die referentielijst, tenzij een andere naam is ingegeven. Bijvoorbeeld: - -``` -{ -"adres": "0622022020", -"soortDigitaalAdres": "telnr", -"omschrijving": "telefoonnummer" -}, -{ -"adres": "icatttest+rachid@gmail.com", -"soortDigitaalAdres": "email", -"omschrijving": "e-mailadres" -} -``` - - -### Actor-identificator - -De Actor die we opslaan bij het Klantcontact, vullen we op basis van de gegevens van de ingelogde gebruiker, waarbij we er in eerste instantie vanuit gaan dat dit altijd is o.b.v. e-mailadres: - -- codeObjecttype= mdw (Documenteren) -- codeRegister=msei (Documenteren) -- codeSoortObjectId=email (Documenteren) - -Van de Actor die we opslaan bij een interne taak hebben we geen gegevens uit EntraID / OIDC maar alleen uit Objectenregister. Dus voorlopig slaan we bij deze Actoren ook vast in de code de Actor-identificator properties op, die verwijzen naar het Objectenregister: - -Actor identificator als medewerker -- codeObjecttype= mdw -- codeRegister=obj -- codeSoortObjectId=idf -- objectId=(waarde van identificatie uit het medewerkerobject) - -Actor identificator als AFDELING of GROEP -- codeObjecttype= afd OF: codeObjecttype= grp -- codeRegister=obj -- codeSoortObjectId=idf -- objectId=(waarde van identificatie uit het afdeling-object of het groep object) - -### Klantcontact -De volgende properties uit het Klantcontact vullen we hard in met de volgende waarden: -- `indicatieContactGelukt`: altijd true -- `taal`: altijd nld -- `vertrouwelijk`: altijd false -- `plaatsgevondenOp`: altijd de datum van registratie van het klantcontact. - - +Ontwerpbeslissingen +=================== +KISS is ontwikkeld met een eindgebruikersgroep van Klantcontactmedewerkers (KCMs) van verschillende gemeenten. Uitgangspunt bij de ontwikkeling van KISS was om de beschikbare standaarden uit de Common Ground te gebruiken. Daar waar er vanuit de gebruikersgroep een informatiebehoefte was, maar waar nog geen (plek binnen de) standaard voor was, is een ontwerpbeslissing genomen wat hiermee te doen (zie ook `20230616-PodiumD-flow-afwijkingen-standaarden.pdf `__). Op het moment dat er een gegevensbehoefte is binnen de applicatie, waarvoor nog geen (volledige) gegevensstandaard beschikbaar is, is de eerste vervolgvraag of deze gegevens ook beschikaar moeten zijn voor ándere applicaties binnen het landschap. Als dat niet het geval is, dan kunnen de gegevens binnen de applicatie zelf worden opgeslagen. Moeten de gegevens ook beschikbaar zijn voor andere applicaties, dan kiezen we ervoor om op basis van een gegevensontwerp een Objecttype aan te maken in de Objectenregistratie. + +.. toctree:: + :maxdepth: 2 + :hidden: + + contactmomenten.md + contactverzoeken.md + zoeken-in-bronnen.md + contactmoment-post.md + zaken.md + logging-voor-verwerking.md + autorisatie.md + klantinteracties-openklant.md From 4437f70988df050d9036f17c6afb7e4e32348d76 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 17:08:17 +0100 Subject: [PATCH 04/30] moved to the right folder (silly) --- docs/{architectuur => }/decision-record/decision-record.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{architectuur => }/decision-record/decision-record.rst (100%) diff --git a/docs/architectuur/decision-record/decision-record.rst b/docs/decision-record/decision-record.rst similarity index 100% rename from docs/architectuur/decision-record/decision-record.rst rename to docs/decision-record/decision-record.rst From 9ccc93328240d50ba31742aa9b77e21a4b7e6d1f Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 17:28:15 +0100 Subject: [PATCH 05/30] Decision Record opgeknipt --- .../POST-contactmoment.md | 0 docs/decision-record/autorisatie.md | 6 ++ docs/decision-record/contactmoment-post.md | 6 ++ docs/decision-record/contactmomenten.md | 16 ++++ docs/decision-record/contactverzoeken.md | 19 +++++ .../klantinteracties-openklant.md | 77 +++++++++++++++++++ .../logging-voor-verwerking.md | 2 + docs/decision-record/zaken.md | 5 ++ docs/decision-record/zoeken-in-bronnen.md | 9 +++ 9 files changed, 140 insertions(+) rename docs/{ => decision-record}/POST-contactmoment.md (100%) create mode 100644 docs/decision-record/autorisatie.md create mode 100644 docs/decision-record/contactmoment-post.md create mode 100644 docs/decision-record/contactmomenten.md create mode 100644 docs/decision-record/contactverzoeken.md create mode 100644 docs/decision-record/klantinteracties-openklant.md create mode 100644 docs/decision-record/logging-voor-verwerking.md create mode 100644 docs/decision-record/zaken.md create mode 100644 docs/decision-record/zoeken-in-bronnen.md diff --git a/docs/POST-contactmoment.md b/docs/decision-record/POST-contactmoment.md similarity index 100% rename from docs/POST-contactmoment.md rename to docs/decision-record/POST-contactmoment.md diff --git a/docs/decision-record/autorisatie.md b/docs/decision-record/autorisatie.md new file mode 100644 index 0000000..da17ecc --- /dev/null +++ b/docs/decision-record/autorisatie.md @@ -0,0 +1,6 @@ +# Autorisatie +KISS is ontwikkeld met het oog op gebruik van een aantal api's (Klanten API, Contactmomenten, ZGW API's, Objecten API en Objecttypen API). Deze API's gaan ervan uit dat de autorisatie door de aanroepende applicatie wordt gefaciliteert en niet door het register zelf. Daarom gebeurt het inrichten van de autorisatie op applicatieniveau en niet op gebruikersniveau. En daarom worden er géén user tokens meegestuurd vanuit KISS naar de onderliggende registers, tenzij dat vereist wordt om specifieke redenen zoals bv. logging. + +Bij de eerste implementatie van KISS binnen een gemeente, moet KISS koppelen met een ouder register, de e-Suite. Deze kan de autorisatie (wat een gebruiker mag zien en doen) doen op gebruikerniveau. Als KISS op de e-Suite koppelt met gebruikmaking van de bestaande 'autorisatie-op-applicatieniveau', dan kan een KISS-gebruiker zaken en contacten zien, die deze gebruiker in de e-Suite niet mag zien. Om dat te voorkomen moet KISS dus een fijnmaziger autorisatie op gebruikersniveau mogelijk kunnen maken bij aansluiting op een onderliggend register. Hierdoor is de noodzaak onstaan om wél bij elk request userid mee te kunnen sturen in een JWT-token. + +Hierop is de koppeling met Overige Objecten aangepast: met moet namelijk, afhankelijk van configuratie per objecttype, mogelijk zijn om de calls naar het onderliggende register ófwel te voorzien van een token, ófwel van een token met user-id. diff --git a/docs/decision-record/contactmoment-post.md b/docs/decision-record/contactmoment-post.md new file mode 100644 index 0000000..a644a8b --- /dev/null +++ b/docs/decision-record/contactmoment-post.md @@ -0,0 +1,6 @@ +# Contactmoment: de uitgebreide POST +KISS schrijft Contactmomenten weg m.b.v. de VNG Contactmomenten API zoals deze is geïmplementeerd in Open Klant v0.5-pre. In een eerdere versie van KISS waren de gegevens die nu in Contactmomentdetails zitten, onderdeel van het uitgebreide Contactmoment. Omdat in KISS 1C de weg is gekozen om bestaande standaarden niet uit te breiden, zijn deze gegevens verplaatst naar Contactmomentdetails. Maar: ze zijn nog steeds onderdeel van de POST die KISS doet op de Contactmomenten API. het ontvangende register negeeert deze onderdelen, en registreert alleen het object zoals gedefinieerde in de Contactmomenten API. + +Bij de integratie met de e-Suite (in gebruikt bij Dimpact-gemeenten), in januari-februari 2024, is een additionele [uitbreiding gedaan van de POST-data in contactmoment](POST-contactmoment.md). + + diff --git a/docs/decision-record/contactmomenten.md b/docs/decision-record/contactmomenten.md new file mode 100644 index 0000000..bafeb39 --- /dev/null +++ b/docs/decision-record/contactmomenten.md @@ -0,0 +1,16 @@ +# Contactmomenten +## Contactmomentdetails + +Voor de onderstaande gegevens is tijdens fase 1C deze afweging gemaakt, en besloten de gegevens op te slaan binnen KISS zelf. Het gaat om gegevens van een contactoment die niet in het Contactmomentenregister passen. Deze gegevens leveren managementinformatie over de werkzaamheden van het KCC. Zie ook de issues [#21](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/issues/21), [#111](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/issues/111), [#610](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/issues/610), [#611](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/issues/611). +Ze worden opgeslagen binnen KISS, en zijn op te vragen via de Contactmomentdetails API. Zie de [Handleiding beheer KISS, hoofdstuk managementinformatie](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/MANUAL.md#management-informatie) voor informatie over het gebruik van deze API. + + +| Property | Type | Toelichting | +|--------|--------|--------| +| `vraag` | string (uri) | De URL's van geraadpleegde bronnen
(Kennisbankartikelen / productpagina's, Vraag-
Antwoord Combinaties (VAC) en
nieuws/werkinstructies) slaan we op in het property
`onderwerpLinks`. Voor Managementinformatie is dit
niet specifiek genoeg. Daarom kan een KCM één van de
bronnen selecteren bij "Vraag". De titel van deze
bron wordt opgeslagen in `vraag`.
Bij VAC's is dit de vraag. Bij Kennisartikelen /
productpagina's is dit de titel van het artikel plus
één van de geraadpleegde subonderdelen binnen het
artikel. Deze wordt in KISS ook gebruikt in de weergave
van Contactmomenten: hiermee kan een KCM zien wat
de vraag van de klant was. | +| `specifiekeVraag` | string | In het afhandelscherm kan een KCM de eigenlijke
klantvraag invullen. Bijvoorbeeld omdat de `vraag` de
eigenlijke vraag niet echt dekt. Of omdat het een nieuwe
vraag is, die nog niet in de bron is verwerkt (sticker in je
paspoort). Ook deze informatie is in te zien door de
KCM bij het bekijken van Contactmomenten. | +| `gespreksresultaat` | string | Hierin slaan we het gespreksresultaat van het
contactmoment op, bijvoorbeeld 'Doorverbonden' of
'Zelfstandig afgehandeld'. | +| `startdatum` | string (date-time) | De tijd waar op het Contactmoment is gestart. Samen
met `einddatum` bepaaalt dit de gespreksduur. | +| `einddatum` | string (date-time) | De tijd waarop het Contactmoment is beëindigd.
Samen met `startdatum` bepaaalt dit de gespreksduur. | +| `verantwoordelijkeAfdeling` | string | Dit is de afdeling voor wie het contactmoment is
afgehandeld. Deze moet de KCM kiezen in het
afhandelscherm. Waar mogelijk wordt deze
vooringevuld vanuit de gekozen bron bij `vraag`. | +| `gespreksId` | string (uuid) | Een klant kan meerdere vragen stellen binnen één
interactie met een Klantcontactmedewerker (KCM).
Voor iedere vraag wordt een contactmoment
aangemaakt. We hebben het property `gespreksId`
toegevoegd. In het geval van 2 of meer vragen binnen één
interactie, worden de vragen aan elkaar verbonden,
doordat al deze contactmomenten hetzelfde `gespreksId`
krijgen. | diff --git a/docs/decision-record/contactverzoeken.md b/docs/decision-record/contactverzoeken.md new file mode 100644 index 0000000..0e1a4a4 --- /dev/null +++ b/docs/decision-record/contactverzoeken.md @@ -0,0 +1,19 @@ +# Contactverzoeken + +## Contactverzoek als interneTaak +Voor Contactverzoeken is nog niet een éénduidige standaard. Sommige gemeenten zien een contactverzoek (terugbelverzoek) als een Zaak. Voor meerdere gemeenten binnen de projectgroep van KISS is dat geen optie. Binnen de [nieuwe standaard Klantinteracties](https://vng-realisatie.github.io/klantinteracties/) is het concept Interne taak geïntroduceerd dat ingezet kan worden voor het Contactverzoek (zie bv. [C9167 - Klant belt KCC met een vraag die niet direct beantwoord kan worden en maakt een terugbelverzoek](https://vng-realisatie.github.io/klantinteracties/achtergronddocumentatie/artefacten/9167.html)). + +Vooruitlopend op deze standaard is voor KISS een nieuw objecttype voor de interne taak ingericht. Omdat een contactverzoek in zijn geheel afhankelijk is van meerdere nieuwe objecten (betrokkene, actor) die nog niet uitgewerkt zijn als standaard (op moment van ontwikkelen, mei-juni 2023), is er voor gekozen om deze objecten als subobject op te nemen in het objecttype interne taak. Dit objecttype is als community concept beschikbaar bij [de Community concepts binnen Objecttypes, bij Open Objecten](https://github.com/open-objecten/objecttypes/tree/main/community-concepts). + +## Afdelingen en groepen +Een Contactverzoek moet binnen de eigen organisatie worden opgepakt. Binnen Klantinteracties is hiervoor het Actor-object beschikbaar, die van het soort `medewerker`, `organisatorische eenheid` of `geautomatiseerde actor` kan zijn (zie [Gegevenswoordenboek Klantinteracties, 2023-10-19T10:33:57.000+02:00](https://vng-realisatie.github.io/klantinteracties/informatiemodel/gegevenswoordenboek)). KISS maakt gebruik van de eerste twee soorten. Binnen de gebruikersgroep was de behoefte om bij `organisatorische eenheid` onderscheid te kunnen maken tussen Afdeling of Groep. Daarom zijn er ook twee objecttypen hiervoor gemaakt: afdeling en groep. Ook deze objecttypen staan bij [de Community concepts](https://github.com/open-objecten/objecttypes/tree/main/community-concepts). + +Bij de opzet van deze objecten zijn we uitgegaan van een hierarchische relatie tussen Afdeling, Groep en Medewerker. Bij de integratie van KISS met de e-Suite (in gebruikt bij Dimpact-gemeenten), in januari-februari 2024, blijkt dat de hierarchische relatie tussen afdelingen en groepen niet altijd bestaat. Groepen zijn daar een ander soort verzameling van medewerkers. Daarom is er een aanpassing gedaan in het groep-object, om te zorgen dat het `afdelingId` niet verplicht is (zie [PR 13](https://github.com/open-objecten/objecttypes/pull/13)). + +Op plekken waar we naar afdelingen zoeken (bv. afdeling bij kennisartikelen, of bij medewerker) is de afdeling/groepsnaam gekozen als zoeksleutel. Dit is gedaan op basis van de toen beschikbare (test)data. Daarin was alleen naam altijd aanwezig, identificatie niet altijd. + + +## Medewerkers en smoelenboek +Een KCM wil kunnen zoeken in bronnen met informatie, maar ook kunnen zoeken naar informatie over collega’s [#96](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/issues/96). Ook hier is nog geen standaard voor. In KISS Fase 1B is een voorzet gedaan voor een Medewerker API (gebaseerd op de [HR-JSON-standaarden van HR Open Standards](https://www.hropenstandards.org/)). In KISS Fase 1C is deze verplaatst naar de Objecten API ( zie [de Community concepts](https://github.com/open-objecten/objecttypes/tree/main/community-concepts).) De objecten van het smoelenboek zijn geindexeerd in Elastic. Bij het doorzetten van een contactverzoek naar een medewerker, gebruiken we de gegevens uit Elastic. + +Bij de integratie van KISS met de e-Suite (in gebruikt bij Dimpact-gemeenten), blijkt dat de naam van een medewerker niet altijd beschikbaar is in de onderdelen `voornaam`, `voorvoegselAchternaam` en `achternaam`. Daarom zijn de properties `voornaam` en `achternaam` niet langer verplicht, en is het property `volledigeNaam` toegevoegd. (zie [PR 13](https://github.com/open-objecten/objecttypes/pull/13)) diff --git a/docs/decision-record/klantinteracties-openklant.md b/docs/decision-record/klantinteracties-openklant.md new file mode 100644 index 0000000..d837699 --- /dev/null +++ b/docs/decision-record/klantinteracties-openklant.md @@ -0,0 +1,77 @@ +# Klantinteracties en OpenKlant +Bij het koppelen van KISS aan de Klanteracties-API's zoals die in Open Klant 2 zijn geimplementeerd, hebben we een aantal keuzes gemaakt bij de inrichting van de gegevens, die in Klantinteracties door de VNG zijn beschreven als items op een Referentielijst. + +## Partij-identificatoren + +We gebruiken de volgende codes in partij-identificatoren + +**Natuurlijke persoon**
+- codeObjecttype: "inp" > natuurlijke persoon +- codeSoortObjectId: "bsn" > BSN van de natuurlijke persoon + + +**Vestiging**
+- codeObjecttype: "vst" > Vestiging uit het Handelsregister +- codeSoortObjectId: "vtn" > Vestigingsnummer van de vestiging in het Handelsregister + +**Niet natuurlijke persoon (rechtspersoon zonder vestigingsnummer)** +- codeObjecttype: "nnp" > Niet-natuurlijke persoon uit het Handelsregister +- codeSoortObjectId: "rsin" > RSIN van de Niet-natuurlijke persoon in het Handelsregister + +**KvK-nummer**
+Bij Partijen van het type Organisatie, die we uit het handelsregister ophalen slaan we altijd ook een tweede partij-identificator op, met daarin het KvKnummer: +- codeObjecttype: "nnp" > Niet-natuurlijke persoon uit het Handelsregister +- codeSoortObjectId: "kvk" > Het KvK-nummer van de vestiging of Niet-natuurlijke persoon in het Handelsregister + +**Registers** +- codeRegister: "brp" > register waar het BSN van de natuurlijke persoon te vinden is +- codeRegister: "hr" > verwijzing naar het handelsregister (voor vestigingsnummer,KvK-nummer en RSIN) +- codeRegister: "msei" > verwijzing naar Microsoft EntraId, waar gegevens van de ingelogde gebruiker in staan. + +### Digitale adressen +Bij het ophalen en opslaan van telefoonnummers en e-maiadressen, gebruiken we bij `soortDigitaalAdres`de waarde van de Code uit een voorzet van referentielijsten. Bij Omschrijving gebruiken we de waarde van Naam uit die referentielijst, tenzij een andere naam is ingegeven. Bijvoorbeeld: + +``` +{ +"adres": "0622022020", +"soortDigitaalAdres": "telnr", +"omschrijving": "telefoonnummer" +}, +{ +"adres": "icatttest+rachid@gmail.com", +"soortDigitaalAdres": "email", +"omschrijving": "e-mailadres" +} +``` + + +## Actor-identificator + +De Actor die we opslaan bij het Klantcontact, vullen we op basis van de gegevens van de ingelogde gebruiker, waarbij we er in eerste instantie vanuit gaan dat dit altijd is o.b.v. e-mailadres: + +- codeObjecttype= mdw (Documenteren) +- codeRegister=msei (Documenteren) +- codeSoortObjectId=email (Documenteren) + +Van de Actor die we opslaan bij een interne taak hebben we geen gegevens uit EntraID / OIDC maar alleen uit Objectenregister. Dus voorlopig slaan we bij deze Actoren ook vast in de code de Actor-identificator properties op, die verwijzen naar het Objectenregister: + +Actor identificator als medewerker +- codeObjecttype= mdw +- codeRegister=obj +- codeSoortObjectId=idf +- objectId=(waarde van identificatie uit het medewerkerobject) + +Actor identificator als AFDELING of GROEP +- codeObjecttype= afd OF: codeObjecttype= grp +- codeRegister=obj +- codeSoortObjectId=idf +- objectId=(waarde van identificatie uit het afdeling-object of het groep object) + +## Klantcontact +De volgende properties uit het Klantcontact vullen we hard in met de volgende waarden: +- `indicatieContactGelukt`: altijd true +- `taal`: altijd nld +- `vertrouwelijk`: altijd false +- `plaatsgevondenOp`: altijd de datum van registratie van het klantcontact. + + diff --git a/docs/decision-record/logging-voor-verwerking.md b/docs/decision-record/logging-voor-verwerking.md new file mode 100644 index 0000000..52147b3 --- /dev/null +++ b/docs/decision-record/logging-voor-verwerking.md @@ -0,0 +1,2 @@ +## Logging voor verwerking +Omdat er nog geen definitieve standaard voor logging voor verwerking was in KISS Fase 1C, is er een voorbereiding gedaan t.b.v. een API voor verwerkingslogging, om de algemene werking alvast op te zetten totdat er een standaard beschikbaar is. Elke keer dat er een api call wordt gedaan naar externe systemen, loggen we UserID, datum/tijd, het api-endpoint dat werd aangeroepen, en de methode waarmee het endpoint werd aangeroepen. Deze logging staat los van de errorlogging. Er is een zeer basaal API-endpoint voor ingericht. diff --git a/docs/decision-record/zaken.md b/docs/decision-record/zaken.md new file mode 100644 index 0000000..8236716 --- /dev/null +++ b/docs/decision-record/zaken.md @@ -0,0 +1,5 @@ + +# Zaken: het zaakdetailscherm +In onderstaande afbeelding is gedocumenteerd welke gegevens uit de verschillen ZGW-objecten worden gebruikt in het Zaak-detailscherm. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/add-decision-record/docs/images/MappingZaakDetail.png) diff --git a/docs/decision-record/zoeken-in-bronnen.md b/docs/decision-record/zoeken-in-bronnen.md new file mode 100644 index 0000000..b8da681 --- /dev/null +++ b/docs/decision-record/zoeken-in-bronnen.md @@ -0,0 +1,9 @@ +## Zoeken in bronnen +### Kennisartikelen / productpagina's (PDC) en VAC's +Een KCM wil kunnen zoeken in bronnen om de vraag van een klant te kunnen beantwoorden (zie [#22](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/issues/22)). Voor Kennisartikelen / productpagina's en VAC's zijn ook nog geen defintieve standaarden. Binnen KISS Fase 1C hebben we voor deze twee bronnen objectdefinties gemaakt, gebaseerd op standaarden in wording in overleg met architecten van Dimpact. + +- Het object PDC - Kennisartikel is gebaseerd op de API voor [de SDG-invoervoorziening](https://github.com/maykinmedia/sdg-invoervoorziening) ([versie 1.7.2](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/maykinmedia/sdg-invoervoorziening/1.7.2/src/openapi.yaml&nocors)). Daar zijn properties aan toegevoegd t.b.v. de behoeften van een KCM (interne informatie, informatie over contact opnemen, informatie over bijzonderheden, trefwoorden en verantwoordelijke afdeling). +- Het object VAC is gebaseerd op een vergelijking van PDC - Kennisartikel, met de structuur van VAC's in SDU-catalogus. + +Beide objecten staan bij [de Community concepts](https://github.com/open-objecten/objecttypes/tree/main/community-concepts). + From bf382df4272183b0e819cb9e498e5caa068f399a Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 21:07:01 +0100 Subject: [PATCH 06/30] dod and start of installation --- docs/INSTALLATION.md | 234 ------------------ .../definition-of-done.md} | 98 ++++---- docs/installation/installation.rst | 12 + 3 files changed, 61 insertions(+), 283 deletions(-) delete mode 100644 docs/INSTALLATION.md rename docs/{DEFINITIONOFDONE.md => definition-of-done/definition-of-done.md} (98%) create mode 100644 docs/installation/installation.rst diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md deleted file mode 100644 index 91e8825..0000000 --- a/docs/INSTALLATION.md +++ /dev/null @@ -1,234 +0,0 @@ -# Klantinteractie Servicesysteem (KISS) Installatie Handleiding - -## Inhoudsopgave - -- [Klantinteractie Servicesysteem (KISS) Installatie Handleiding](#klantinteractie-servicesysteem-kiss-installatie-handleiding) - - [Inhoudsopgave](#inhoudsopgave) - - [Inleiding](#inleiding) - - [Voorbereidingen](#voorbereidingen) - - [Domein](#domein) - - [Tools](#tools) - - [Haven](#haven) - - [Authenticatie](#authenticatie) - - [Configuratie: Environment Variabelen](#configuratie-environment-variabelen) - - [Authenticatie](#authenticatie-1) - - [Database](#database) - - [Organisatie RSIN](#organisatie-rsin) - - [Feedback op Kennisartikelen](#feedback-op-kennisartikelen) - - [Gekoppelde Bronnen](#gekoppelde-bronnen) - - [KISS-frontend](#kiss-frontend) - - [KISS-Elastic-Sync](#kiss-elastic-sync) - - [Installatie](#installatie) - - [Placeholders](#placeholders) - - [Uitvoeren](#uitvoeren) - - [KISS-Elastic-Sync](#kiss-elastic-sync-1) - - [KISS-Elastic-Sync-Cronjobs](#cronjobs) - ---- - -## Inleiding - -KISS draait in een Kubernetes cluster. Deze handleiding is gebaseerd op Azure Kubernetes, maar ondersteunt ook andere haven-compliant providers. De handleiding is bedoeld voor Kubernetes beheerders om KISS handmatig op een nieuw cluster te installeren. - -## Voorbereidingen - -### Domein - -Bij gebruik van Helm-Charts: zorg voor een domeinnaam met wild-card certificaat. Gebruik `.crt` en `.key` bestanden zoals hieronder: - -> `-----BEGIN CERTIFICATE-----`
-> inhoud public certificate
-> `-----END CERTIFICATE-----`
->
-> `-----BEGIN CERTIFICATE-----`
-> inhoud intermediate certificaten mits aanwezig
-> `-----END CERTIFICATE-----`
->
-> `-----BEGIN CERTIFICATE-----`
-> inhoud certificate authority certificate
-> `-----END CERTIFICATE-----` - -Het private certificate dient los als .key bestand opgeslagen te worden. - -### Tools - -Installeer de volgende tools: - -- [kubectl](https://kubernetes.io/docs/tasks/tools/) -- [Helm](https://helm.sh/docs/intro/install/) -- [Haven](https://haven.commonground.nl/techniek/compliancy-checker) -- [Powershell](https://learn.microsoft.com/en-us/powershell/) - -### Haven - -KISS kan op een haven-compliant cluster geïnstallleerd worden. Referentie-implementaties van haven-compliant clusters zijn te vinden op de [Haven](https://haven.commonground.nl/techniek/aan-de-slag) site. - -Bij het volgen van de [Azure](https://haven.commonground.nl/techniek/aan-de-slag/azure) referentie moet men rekening houden met de volgende extra zaken: - -- Minimaal 3 nodes -- High availability aanzetten -- Local logins met RBAC gebruiken, GEEN Azure Active Directory! - - -### Authenticatie - -De authenticatie van gebruikers binnen KISS gebeurt m.b.v. een OIDC koppeling met bijvoorbeeld Azure Active Directory. - -## Configuratie: Environment Variabelen - -Hieronder staan de benodigde environment variabelen per onderdeel van KISS. - -### Authenticatie - -| Variabele | Uitleg | -| ---------------------------------------- | --------------------------------------------------------- | -| `OIDC_AUTHORITY` | URL van de OpenID Connect Identity Provider | -| `OIDC_CLIENT_ID` | Voor toegang tot de OpenID Connect Identity Provider | -| `OIDC_CLIENT_SECRET` | Secret voor de OpenID Connect Identity Provider | -| `OIDC_MEDEWERKER_IDENTIFICATIE_CLAIM` | Identificatie van de medewerker in registers
(default waarde is `email`)
Meer informatie Bij het wegschrijven van gegevens naar bv. Open Klant of Open Zaak is een `medewerkerIdentificatie.identificatie` verplicht. Verschillende gemeenten gebruiken hier verschillende waardes voor. Bij een koppeling met bv. de e-Suite is het van belang dat hier de e-Suite gebruikersnaam in staat van de ingelogde KCM.
| -| `OIDC_MEDEWERKER_IDENTIFICATIE_TRUNCATE` | Optioneel afkappen van de claim
(bijv. `24`)
Meer informatie Binnen ZGW mag een `medewerkerIdentificatie.identificatie` niet langer zijn dan 24 karakters. Met deze variabele kun je ervoor zorgen dat de uiteindelijk waarde wordt afgekapt na 24 tekens.
| -| `MANAGEMENTINFORMATIE_API_KEY` | Secret dat KISS gebruikt om het JWT Token
te valideren bij het opvragen van
contactmomentdetails
Meer informatie Zie de [Handleiding beheer KISS, hoofdstuk
managementinformatie](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/MANUAL.md#management-informatie) voor informatie over
het gebruik van deze API.
| -| | | - -### Database - -| Variabele | Uitleg | -| ------------------ | ------------------------------------- | -| `POSTGRES_DB` | Naam van de database bij KISS | -| `POSTGRES_USER` | Gebruikersnaam voor toegang van KISS tot de DB | -| `POSTGRES_PASSWORD` | Wachtwoord van de postgresUser | -| | | - -### Organisatie RSIN - -| Variabele | Uitleg | -| ----------------- | ---------------------------------------------------------------- | -| `ORGANISATIE_IDS` | RSIN van de organisatie die de
Contactmomenten registreert
Meer informatie Verschillende ZGW APIs, waaronder de Klant en Contactmoment APIs, vragen om een identificatienummer, RSIN, van de eigen organisatie. Dit RSIN moet worden meegegeven bij registratie van specifieke objecten.
| -| | | - -### Feedback op Kennisartikelen -
Meer informatie Vanuit KISS kan een KCM feedback geven op een kennisartikel. Deze informatie wordt gemaild naar één centraal e-mailadres. Dit configureer je met onderstaande variabelen.
- -| Variabele | Uitleg | -| --------------------- | --------------------------------------- | -| `FEEDBACK_EMAIL_FROM` | Afzenderadres van de feedbackmail | -| `FEEDBACK_EMAIL_TO` | Adres waar de feedbackmail naartoe moet | -| `EMAIL_ENABLE_SSL` | Gebruik van SSL (true/false) | -| `EMAIL_HOST` | Adres van de mailserver | -| `EMAIL_PORT` | Poortnummer van de mailverbinding | -| `EMAIL_USERNAME` | Gebruikersnaam voor de mailserver | -| `EMAIL_PASSWORD` | Wachtwoord voor de mailserver | -| | | - -### Gekoppelde Bronnen - -Er zijn diverse API's die vanuit KISS bevraagd worden. Hieronder staan de environment variabelen per gekoppelde bron. -**Let op**: -1. Sommige API-keys en Secrets die KISS nodig heeft om externe registers te bevragen moeten **minimaal 32 karakters** lang zijn. -2. Voor variabelen met `__0__` als tussenvoegsel geldt dat er een lijst opgebouwd kan worden. Het eerste item van de lijst heeft `__0__` als tussenvoegsel, het tweede item `__1__`, en zo verder. - -
Meer informatie Er zijn diverse bronnen die vanuit KISS via API's bevraagd worden. Sommige worden alleen geraadpleegd, zoals de KvK-API en de API voor Haal Centraal BRP Personen bevragen, en de Objecten API voor het ophalen van Afdelingen, Groepen en Medewerkers. Andere registraties worden niet alleen geraadpleegd, maar er worden ook gegevens in weggeschreven. Dit zijn in ieder geval een Klanten- en Contactmomentenregister, zoals Open Klant, het Objecten Register zoals Open Objecten, en een Zaaksysteem (m.b.v. ZGW API's) zoals Open Zaak. - -Daarnaast zijn er bronnen die binnen KISS doorzocht moeten worden. - -- KISS gebruikt de Objecten API om Kennisartikelen (PDC-producten) mee op te halen, en naar Elastic te pushen. -- KISS gebruikt op dit moment de Objecten API om de Medewerkers in het Smoelenboek op te halen en naar Elastic te pushen. -- KISS gebruikt op dit moment de Objecten API om de Vraag Antwoord Combinaties (VAC) op te halen en naar Elastic te pushen.
- - -#### KISS-frontend - -| Variabele | Uitleg | -| --------------------------------- | -------------------------------------------------------------------------------------------- | -| `HAAL_CENTRAAL_BASE_URL` | URL van de Haal Centraal API
Meer informatie Bijvoorbeeld: `https://proefomgeving.haalcentraal.nl/haalcentraal/api`
| -| `HAAL_CENTRAAL_API_KEY` | Key voor de Haal Centraal API | -| `KVK_BASE_URL` | URL van de KvK-API
Meer informatie URL van de KvK-API om het Handelsregister te bevragen. Dit is het pad voorafgaand aan het versienummer, bijvoorbeeld `https://api.kvk.nl/test/api`
| -| `KVK_API_KEY` | Key voor de KvK-API | -| `ELASTIC_BASE_URL` | De URL voor Elasticsearch
Meer informatie Bijvoorbeeld: `https://kiss-es-http:9200`
| -| `ELASTIC_USERNAME` | Username om in te loggen op Elasticsearch
Meer informatie Dit kan de default root user `elastic` zijn, maar ook de username van een gebruiker die je zelf hebt aangemaakt.
| -| `ELASTIC_PASSWORD` | Wachtwoord voor de bovenstaande user
Meer informatie Als je gebruik maakt van [ECK](https://www.elastic.co/guide/en/cloud-on-k8s/2.8/k8s-overview.html), dan kun je het wachtwoord van de default user vinden, m.b.v. het commando `kubectl get secret kiss-es-elastic-user -o go-template='{{.data.elastic | base64decode}}'`
| -| `ENTERPRISE_SEARCH_BASE_URL` | URL van de API waarop KISS de elastic instantie kan bevragen
Meer informatie Bijvoorbeeld `https://kiss-ent-http:3002`
| -| `ENTERPRISE_SEARCH_PUBLIC_API_KEY` | Public API key voor Elastic API | -| `ENTERPRISE_SEARCH_PRIVATE_API_KEY` | Private API key voor Elastic API
Meer informatie De API key die nodig is om de `engine`s bij te werken
| -| `ENTERPRISE_SEARCH_ENGINE` | De naam van de `meta-engine` engine die KISS gebruikt. Dit moet zijn: `KISS-engine`
Meer informatie De KISS-Elastic-Sync maakt deze engine aan, als deze nog niet bestaat.
| -| `USE_KLANTINTERACTIES` | Deze variabele bepaalt of er gebruik wordt gemaakt van OpenKlant 2.0 (klantinteractieregister).
Meer informatie Als deze variabele op `true` staat, wordt OpenKlant 2.0 gebruikt. Hiervoor zijn de variabelen `KLANTINTERACTIES_BASE_URL` en `KLANTINTERACTIES_TOKEN` nodig. Standaard is deze waarde `false`, in dat geval worden de oude Contactmomenten API en Klanten API gebruikt, voor communicatie met de e-Suite. In dat geval zijn de variabelen `KLANTEN_BASE_URL`, `KLANTEN_CLIENT_ID` en `KLANTEN_CLIENT_SECRET` nodig.
| -| `KLANTINTERACTIES_BASE_URL` | URL van de Klantinteractie API van het gebruikte klantinteractieregister (bijvoorbeeld Open Klant 2)
Meer informatie Bijvoorbeeld `https://klantinteractieregister.mijngemeente.nl/klantinteracties`
| -| `KLANTINTERACTIES_TOKEN` | Token voor de Klantinteractie API van het gebruikte klantinteractieregister | -| `KLANTEN_BASE_URL` | URL van de Klanten API van het gebruikte klantenregister, noodzakelijk als `USE_KLANTINTERACTIES` op false staat of niet gedefinieerd is.
Meer informatie Bijvoorbeeld `https://klantenregister.mijngemeente.nl/klanten`
| -| `KLANTEN_CLIENT_ID` | ClientId voor de Klanten API van het gebruikte klantenregister, , noodzakelijk als `USE_KLANTINTERACTIES` op false staat of niet gedefinieerd is. | -| `KLANTEN_CLIENT_SECRET` | Secret voor de Klanten API
**(min. 32 karakters)** | -| `CONTACTMOMENTEN_BASE_URL` | URL van de Contactmomenten API
Meer informatie Bijvoorbeeld: `https://contactmomentenregister.mijngemeente.nl`
| -| `CONTACTMOMENTEN_API_CLIENT_ID` | ClientId voor de Contactmomenten API van het gebruikte Contactmomentenregister | -| `CONTACTMOMENTEN_API_KEY` | Key voor de Contactmomenten API
**(min. 32 karakters)** | -| `ZAAKSYSTEEM__0__BASE_URL` | URL van de ZGW API's
Meer informatie Bijvoorbeeld: `https://zaaksysteem.mijngemeente.nl`
| -| `ZAAKSYSTEEM__0__API_KEY` | API Key voor de ZGW API's
**(min. 32 karakters)** | -| `ZAAKSYSTEEM__0__API_CLIENT_ID` | ClientId voor de ZGW API's | -| `ZAAKSYSTEEM__0__DEEPLINK_URL` | Basisurl om te deeplinken naar een Zaak in het zaaksysteem (optioneel)
Meer informatie Bijvoorbeeld: `https://zaaksysteem.mijngemeente.nl/mp/zaak/`
Deze variabele **moet** altijd gebruikt worden **in combinatie met** `ZAAKSYSTEEM__0__DEEPLINK_PROPERTY`. Als deze variabelen beiden worden ingevuld, zal er in KISS een link in het zaakdetailscherm staan, waarmee de KCM de betreffende zaak direct in het zaaksysteem opent. LET OP: dit kan alleen bij zaaksystemen die een vaste url hebben voor zaakdetails, waarbij alleen één property van de zaak, bijv. het zaaknummer, áchter die URL geplaatst hoeft te worden.
| -| `ZAAKSYSTEEM__0__DEEPLINK_PROPERTY` | Property om naar een zaak te kunnen deeplinken (optioneel)
Meer informatie Deze variabele **moet** altijd gebruikt worden **in combinatie met** `ZAAKSYSTEEM__0__DEEPLINK_URL`. De waarde uit dit property van een specifieke zaak wordt achter `ZAAKSYSTEEM_DEEPLINK_URL` geplaatst om de link te laten werken. Bijvoorbeeld: `identificatie`
| -| `ZAAKSYSTEEM__0__NIETNATUURLIJKPERSOONIDENTIFIER` | Identifier voor 'niet natuurlijke personen'
(`rsin` of `kvkNummer`) voor dit zaaksysteem
Meer informatie Afhankelijk van de gebruikte bron (bijvoorbeeld Open Zaak of de e-Suite) kan je hiermee aangeven welk gegeven gebruikt wordt om zaken van een `niet natuurlijke persoon` op te zoeken in een zaaksysteem. Op dit moment kan je hiervoor het RSIN (`rsin`) of het KvK-nummer (`kvkNummer`) gebruiken. RSIN is de default: als deze variable leeg gelaten wordt of ontbreekt bij de installatie, zal `rsin` gebruikt worden. Als je de e-Suite als register gebruikt, moet je hier `kvkNummer` invullen. Let op, de spelling moet exact overeen komen.
| -| `AFDELINGEN_BASE_URL` | URL van de Objecten API voor afdelingen.
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `AFDELINGEN_OBJECT_TYPE_URL` | URL van het Objecttype Afdeling
Meer informatie Bijvoorbeeld: `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `AFDELINGEN_TOKEN` | Token voor Objecten API voor afdelingen | -| `GROEPEN_BASE_URL` | URL van de Objecten API voor groepen.
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `GROEPEN_OBJECT_TYPE_URL` | URL van het Objecttype Groep
Meer informatie Bijvoorbeeld: `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `GROEPEN_TOKEN` | Token van de Objecten API voor groepen | -| `INTERNE_TAAK_BASE_URL` | URL van de Objecten API voor Interne Taken
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `INTERNE_TAAK_OBJECT_TYPE_URL` | URL van het Objecttype Interne Taak
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `INTERNE_TAAK_TYPE_VERSION` | Versienummer van het Objecttype Interne Taak
Meer informatie Bijvoorbeeld `2`
KISS schrijft InterneTaken in het Objectenregister. Hierbij moet je altijd de versie van het objecttype meegeven. Omdat het per gemeente kan verschillen welke versie de meest recente is, moet je hier invullen welk versienummer KISS moet meegeven.
| -| `INTERNE_TAAK_TOKEN` | Token voor de Objecten API voor Interne Taken
**(Als deze variabele een waarde heeft, moeten `INTERNE_TAAK_CLIENT_SECRET` en `INTERNE_TAAK_CLIENT_ID` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| -| `INTERNE_TAAK_CLIENT_SECRET` | Client Secret voor de Interne Taken API
**(Als deze variabele een waarde heeft, moet `INTERNE_TAAK_TOKEN` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| -| `INTERNE_TAAK_CLIENT_ID` | Client ID voor de Interne Taken API
**(Als deze variabele een waarde heeft, moet `INTERNE_TAAK_TOKEN` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| -| `VAC_OBJECTEN_BASE_URL` | URL van de Objecten API voor VAC's
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `VAC_OBJECT_TYPE_URL` | URL van het Objecttype VAC
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `VAC_OBJECT_TYPE_VERSION` | Versienummer van het Objecttype VAC
Meer informatie Bijvoorbeeld `2`
KISS schrijft Vacs in het Objectenregister. Hierbij moet je altijd de versie van het objecttype meegeven. Omdat het per gemeente kan verschillen welke versie de meest recente is, moet je hier invullen welk versienummer KISS moet meegeven.
| -| `VAC_OBJECTEN_TOKEN` | Token voor de Objecten API voor VAC's
Meer informatie In het geval van Vacs identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`.
| -| `USE_VACS` | Deze variabele bepaalt of het navigatie-item voor het beheren van VAC's aanwezig is in de beheernavigatie.
Meer informatie Als deze variabele op `true` staat, is het Vacs-item zichtbaar en kunnen beheerders gebruikmaken van de functionaliteit. Als de variabele niet op true staat, of niet is ingesteld, zal het item niet aanwezig zijn in de beheernavigatie.
| -| `USE_MEDEWERKEREMAIL` | Deze variabele bepaalt of een contactverzoek voor een medewerker alléén op e-mailadres kan.
Meer informatie Als deze variabele op `true` staat, zal in het contactverzoek-formulier, onder de geselecteerde afdeling of groep, een veld staan om het emailadres van een medewerker in te voeren. Direct een contactverzoek voor een medewerker maken kan in deze situatie niet. Het veld e-mailadres is niet verplicht. Als de variabele niet op `true` staat, geen waarde heeft of afwezig is, heb je in KISS wel de mogelijkheid om een Contactverzoek voor een medewerker te maken, en kun je in KISS de medewerker uit een lijst kiezen op naam.
| - -#### KISS-Elastic-Sync -
Meer informatie KISS-Elastic-Sync is het component dat zorgt dat de gekoppelde bronnen die via Elasticsearch ontsloten worden in KISS, naar de juiste Indexen worden gepushed, met de benodigde gegevens hieraan toegevoegd. Onderstaande environment variabelen gaan over de bronnen die gekoppeld zijn aan de KISS-Elastic-Sync.
- - -| Variabele | Uitleg | -| -------------------------------------| -------------------------------------------------------------------------------------------------------- | -| `ENTERPRISE_SEARCH_BASE_URL` | URL van de API voor de elastic instantie | -| `ENTERPRISE_SEARCH_PRIVATE_API_KEY` | Private API key voor Elastic | -| `MEDEWERKER_OBJECTEN_BASE_URL` | URL van de Objecten API voor medewerkers
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `MEDEWERKER_OBJECTEN_TOKEN` | Token voor de Objecten API voor medewerkers
**(Als deze variabele een waarde heeft, moeten MEDEWERKER_OBJECTEN_CLIENT_SECRET en MEDEWERKER_OBJECTEN_CLIENT_ID leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| -| `MEDEWERKER_OBJECTEN_CLIENT_ID` | Client ID voor de Objecten API voor medewerkers
**(Als deze variabele een waarde heeft, moet MEDEWERKER_OBJECTEN_TOKEN leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| -| `MEDEWERKER_OBJECTEN_CLIENT_SECRET` | Client Secret voor de Objecten API voor medewerkers
**(Als deze een waarde heeft, deze variabele MEDEWERKER_OBJECTEN_TOKEN leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| -| `MEDEWERKER_OBJECT_TYPE_URL` | URL van het Objecttype Medewerker
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `VAC_OBJECTEN_BASE_URL` | URL van de Objecten API voor VAC's
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `VAC_OBJECT_TYPE_URL` | URL van het Objecttype VAC
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `VAC_OBJECTEN_TOKEN` | Token voor de Objecten API voor VAC's
Meer informatie In het geval van Vacs identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`.
| -| `SDG_BASE_URL` | URL van de API voor Kennisartikelen
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `SDG_OBJECTEN_TOKEN` | Key voor de API voor Kennisartikelen | -| `SDG_OBJECT_TYPE_URL` | URL van het Objecttype Kennisartikel
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| - -## Installatie - -### Placeholders - -De yaml-voorbeeldbestanden staan [hier](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/blob/main/helm/kiss-frontend/kiss.template.yaml). - -### Uitvoeren - -De installatie kan uitgevoerd worden middels het PowerShell script. Handmatig uitvoeren kan ook. - -[install_kiss.ps1](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/scripts/install_kiss.ps1) - -**LET OP** -- Voordat een ingelogde gebruiker kan werken met KISS, moet deze gebruiker de juiste rol hebben in de gekoppelde Identity provider. Zie voor meer informatie het onderdeel [Configuratie van uw Identity Provider in de configuratie-handleiding](CONFIGURATIE.md#configuratie-van-uw-identity-provider). -- Om een betere indruk te krijgen van hoe KISS werkt, is het mogelijk om **voorbeeldata (demodata)** te laden. Zie hiervoor [de uitleg bij de Beheerhandleiding](MANUAL.md#kiss-beheer-vullen-met-voorbeelddata). - -#### KISS-Elastic-Sync -KISS-Elastic-Sync is het component dat zorgt voor het creëren van de benodigde engines in een Elasticsearch-installatie, zodat gekoppelde bronnen eenvoudig door KISS doorzoekbaar zijn. Het ondersteunt zowel websites als gestructureerde bronnen door respectievelijk een crawler en een index te gebruiken. - -Meer informatie over de KISS-Elastic-Sync tool en hoe deze te installeren, is te vinden op de volgende URL: -[KISS-Elastic-Sync](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/README.md) - -##### Cronjobs -Naast de sync tool zijn er ook cronjobs die ingesteld moeten worden voor het regelmatig synchroniseren van data. - -Meer informatie over de benodigde cronjobs en hoe deze in te stellen, is te vinden op de volgende URL: -[KISS-Elastic-Sync Cronjobs](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/deploy/README.md) diff --git a/docs/DEFINITIONOFDONE.md b/docs/definition-of-done/definition-of-done.md similarity index 98% rename from docs/DEFINITIONOFDONE.md rename to docs/definition-of-done/definition-of-done.md index bc0f06b..380224c 100644 --- a/docs/DEFINITIONOFDONE.md +++ b/docs/definition-of-done/definition-of-done.md @@ -1,49 +1,49 @@ -# Definition of Done - -De aanpassingen staan op een devevelopmentomgeving [https://dev.kiss-demo.nl/](https://dev.kiss-demo.nl/) en productieomgeving [https://prod.kiss-demo.nl/](https://prod.kiss-demo.nl/) en voldoen aan alle acceptatiecriteria. - -### De applicatie voldoet aan de ontwerpprincipes van Gebruiker Centraal -De eindgebruiker is gedurende het hele project betrokken bij ontwerp en specificatie. De applicatie wordt regelmatig getest door de gebruikers. - -### De applicatie voldoet aan de AVG -Er is een DPIA opgesteld voor de applicatie. Deze kunt u [hier inzien](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/files/ICATT-KISS-Data-Processing-Impact-Assessment-(DPIA).pdf). - -### Code is gereviewd door een andere developer -Er wordt ontwikkeld in feature branches en gedeployed vanaf de main branch. Zodoende is inzichtelijk wie aan een story gewerkt heeft en wie een pull request approved heeft. - -### Automatische tests -Alle Automatische tests zijn uitgevoerd en geslaagd (zichtbaar als badges op de README) - -- Snyk (vulnerability en OWASP scanning) -- Dependabot (security issues in packages) -- Super-linter (code volgens afspraak geformatteerd) -- Unit tests (in ontwikkeling) - -### Unit tests -Nieuwe unit tests worden toegevoegd: - -- voor code die, wanneer niet correct geïmplementeerd, kan leiden tot kritieke fouten die moeilijk te detecteren zijn -- voor code die moeilijk te begrijpen is zonder uitvoerbare voorbeelden -- voor code die breed hergebruikt wordt binnen de applicatie - -### Handmatige tests -- Alle handmatige tests zijn aantoonbaar uitgevoerd op basis van een testscipt per userstory -- Bij oplevering wordt een integratietest doorlopen op basis van een testscript -- WCAG wordt handmatig gecontroleerd m.b.v. lighthouse. De resultaten van deze test vindt u [hier](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/files/WCAG-Lighthouse-Report-20231010.pdf) - -### Pentest -Pentests (frontend en backend) worden wekelijks uitgevoerd. Een voorbeeld van een rapport uit juli 2024 staat [hier](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/files/WebsiteScanner_30077801_771804-20240711-2302_0.pdf). - -### Error logging -Error logging is ingeregeld - -### Documentatie -Documentatie is compleet en actueel: - -- Documentatie voor ontwikkelaars staat in de code -- Voor overige documentatie zie [Readthedocs](https://kiss-klantinteractie-servicesysteem.readthedocs.io/) - -### CI/CD -- Er is een werkende CI/CD straat -- De applicatie kan draaien in een Haven Compliant Cluster, conform de checks zoals beschreven op [https://haven.commonground.nl/techniek/compliancy-checker](https://haven.commonground.nl/techniek/compliancy-checker) - +# Definition of Done + +De aanpassingen staan op een devevelopmentomgeving [https://dev.kiss-demo.nl/](https://dev.kiss-demo.nl/) en productieomgeving [https://prod.kiss-demo.nl/](https://prod.kiss-demo.nl/) en voldoen aan alle acceptatiecriteria. + +### De applicatie voldoet aan de ontwerpprincipes van Gebruiker Centraal +De eindgebruiker is gedurende het hele project betrokken bij ontwerp en specificatie. De applicatie wordt regelmatig getest door de gebruikers. + +### De applicatie voldoet aan de AVG +Er is een DPIA opgesteld voor de applicatie. Deze kunt u [hier inzien](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/files/ICATT-KISS-Data-Processing-Impact-Assessment-(DPIA).pdf). + +### Code is gereviewd door een andere developer +Er wordt ontwikkeld in feature branches en gedeployed vanaf de main branch. Zodoende is inzichtelijk wie aan een story gewerkt heeft en wie een pull request approved heeft. + +### Automatische tests +Alle Automatische tests zijn uitgevoerd en geslaagd (zichtbaar als badges op de README) + +- Snyk (vulnerability en OWASP scanning) +- Dependabot (security issues in packages) +- Super-linter (code volgens afspraak geformatteerd) +- Unit tests (in ontwikkeling) + +### Unit tests +Nieuwe unit tests worden toegevoegd: + +- voor code die, wanneer niet correct geïmplementeerd, kan leiden tot kritieke fouten die moeilijk te detecteren zijn +- voor code die moeilijk te begrijpen is zonder uitvoerbare voorbeelden +- voor code die breed hergebruikt wordt binnen de applicatie + +### Handmatige tests +- Alle handmatige tests zijn aantoonbaar uitgevoerd op basis van een testscipt per userstory +- Bij oplevering wordt een integratietest doorlopen op basis van een testscript +- WCAG wordt handmatig gecontroleerd m.b.v. lighthouse. De resultaten van deze test vindt u [hier](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/files/WCAG-Lighthouse-Report-20231010.pdf) + +### Pentest +Pentests (frontend en backend) worden wekelijks uitgevoerd. Een voorbeeld van een rapport uit juli 2024 staat [hier](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/files/WebsiteScanner_30077801_771804-20240711-2302_0.pdf). + +### Error logging +Error logging is ingeregeld + +### Documentatie +Documentatie is compleet en actueel: + +- Documentatie voor ontwikkelaars staat in de code +- Voor overige documentatie zie [Readthedocs](https://kiss-klantinteractie-servicesysteem.readthedocs.io/) + +### CI/CD +- Er is een werkende CI/CD straat +- De applicatie kan draaien in een Haven Compliant Cluster, conform de checks zoals beschreven op [https://haven.commonground.nl/techniek/compliancy-checker](https://haven.commonground.nl/techniek/compliancy-checker) + diff --git a/docs/installation/installation.rst b/docs/installation/installation.rst new file mode 100644 index 0000000..639cb12 --- /dev/null +++ b/docs/installation/installation.rst @@ -0,0 +1,12 @@ +Installatie +============================================================= + +KISS draait in een Kubernetes cluster. Deze handleiding is gebaseerd op Azure Kubernetes, maar ondersteunt ook andere haven-compliant providers. De handleiding is bedoeld voor Kubernetes beheerders om KISS handmatig op een nieuw cluster te installeren. + +.. toctree:: + :maxdepth: 2 + :hidden: + + voorbereidingen.md + configuratie.md + installatie.md From eabc58b05cb1cfd5e929528b5a29b3be6f12a335 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 21:11:10 +0100 Subject: [PATCH 07/30] restore old installationmd --- docs/INSTALLATION.md | 234 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 docs/INSTALLATION.md diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md new file mode 100644 index 0000000..be631bd --- /dev/null +++ b/docs/INSTALLATION.md @@ -0,0 +1,234 @@ +# Klantinteractie Servicesysteem (KISS) Installatie Handleiding + +## Inhoudsopgave + +- [Klantinteractie Servicesysteem (KISS) Installatie Handleiding](#klantinteractie-servicesysteem-kiss-installatie-handleiding) + - [Inhoudsopgave](#inhoudsopgave) + - [Inleiding](#inleiding) + - [Voorbereidingen](#voorbereidingen) + - [Domein](#domein) + - [Tools](#tools) + - [Haven](#haven) + - [Authenticatie](#authenticatie) + - [Configuratie: Environment Variabelen](#configuratie-environment-variabelen) + - [Authenticatie](#authenticatie-1) + - [Database](#database) + - [Organisatie RSIN](#organisatie-rsin) + - [Feedback op Kennisartikelen](#feedback-op-kennisartikelen) + - [Gekoppelde Bronnen](#gekoppelde-bronnen) + - [KISS-frontend](#kiss-frontend) + - [KISS-Elastic-Sync](#kiss-elastic-sync) + - [Installatie](#installatie) + - [Placeholders](#placeholders) + - [Uitvoeren](#uitvoeren) + - [KISS-Elastic-Sync](#kiss-elastic-sync-1) + - [KISS-Elastic-Sync-Cronjobs](#cronjobs) + +--- + +## Inleiding + +KISS draait in een Kubernetes cluster. Deze handleiding is gebaseerd op Azure Kubernetes, maar ondersteunt ook andere haven-compliant providers. De handleiding is bedoeld voor Kubernetes beheerders om KISS handmatig op een nieuw cluster te installeren. + +## Voorbereidingen + +### Domein + +Bij gebruik van Helm-Charts: zorg voor een domeinnaam met wild-card certificaat. Gebruik `.crt` en `.key` bestanden zoals hieronder: + +> `-----BEGIN CERTIFICATE-----`
+> inhoud public certificate
+> `-----END CERTIFICATE-----`
+>
+> `-----BEGIN CERTIFICATE-----`
+> inhoud intermediate certificaten mits aanwezig
+> `-----END CERTIFICATE-----`
+>
+> `-----BEGIN CERTIFICATE-----`
+> inhoud certificate authority certificate
+> `-----END CERTIFICATE-----` + +Het private certificate dient los als .key bestand opgeslagen te worden. + +### Tools + +Installeer de volgende tools: + +- [kubectl](https://kubernetes.io/docs/tasks/tools/) +- [Helm](https://helm.sh/docs/intro/install/) +- [Haven](https://haven.commonground.nl/techniek/compliancy-checker) +- [Powershell](https://learn.microsoft.com/en-us/powershell/) + +### Haven + +KISS kan op een haven-compliant cluster geïnstallleerd worden. Referentie-implementaties van haven-compliant clusters zijn te vinden op de [Haven](https://haven.commonground.nl/techniek/aan-de-slag) site. + +Bij het volgen van de [Azure](https://haven.commonground.nl/techniek/aan-de-slag/azure) referentie moet men rekening houden met de volgende extra zaken: + +- Minimaal 3 nodes +- High availability aanzetten +- Local logins met RBAC gebruiken, GEEN Azure Active Directory! + + +### Authenticatie + +De authenticatie van gebruikers binnen KISS gebeurt m.b.v. een OIDC koppeling met bijvoorbeeld Azure Active Directory. + +## Configuratie: Environment Variabelen + +Hieronder staan de benodigde environment variabelen per onderdeel van KISS. + +### Authenticatie + +| Variabele | Uitleg | +| ---------------------------------------- | --------------------------------------------------------- | +| `OIDC_AUTHORITY` | URL van de OpenID Connect Identity Provider | +| `OIDC_CLIENT_ID` | Voor toegang tot de OpenID Connect Identity Provider | +| `OIDC_CLIENT_SECRET` | Secret voor de OpenID Connect Identity Provider | +| `OIDC_MEDEWERKER_IDENTIFICATIE_CLAIM` | Identificatie van de medewerker in registers
(default waarde is `email`)
Meer informatie Bij het wegschrijven van gegevens naar bv. Open Klant of Open Zaak is een `medewerkerIdentificatie.identificatie` verplicht. Verschillende gemeenten gebruiken hier verschillende waardes voor. Bij een koppeling met bv. de e-Suite is het van belang dat hier de e-Suite gebruikersnaam in staat van de ingelogde KCM.
| +| `OIDC_MEDEWERKER_IDENTIFICATIE_TRUNCATE` | Optioneel afkappen van de claim
(bijv. `24`)
Meer informatie Binnen ZGW mag een `medewerkerIdentificatie.identificatie` niet langer zijn dan 24 karakters. Met deze variabele kun je ervoor zorgen dat de uiteindelijk waarde wordt afgekapt na 24 tekens.
| +| `MANAGEMENTINFORMATIE_API_KEY` | Secret dat KISS gebruikt om het JWT Token
te valideren bij het opvragen van
contactmomentdetails
Meer informatie Zie de [Handleiding beheer KISS, hoofdstuk
managementinformatie](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/MANUAL.md#management-informatie) voor informatie over
het gebruik van deze API.
| +| | | + +### Database + +| Variabele | Uitleg | +| ------------------ | ------------------------------------- | +| `POSTGRES_DB` | Naam van de database bij KISS | +| `POSTGRES_USER` | Gebruikersnaam voor toegang van KISS tot de DB | +| `POSTGRES_PASSWORD` | Wachtwoord van de postgresUser | +| | | + +### Organisatie RSIN + +| Variabele | Uitleg | +| ----------------- | ---------------------------------------------------------------- | +| `ORGANISATIE_IDS` | RSIN van de organisatie die de
Contactmomenten registreert
Meer informatie Verschillende ZGW APIs, waaronder de Klant en Contactmoment APIs, vragen om een identificatienummer, RSIN, van de eigen organisatie. Dit RSIN moet worden meegegeven bij registratie van specifieke objecten.
| +| | | + +### Feedback op Kennisartikelen +
Meer informatie Vanuit KISS kan een KCM feedback geven op een kennisartikel. Deze informatie wordt gemaild naar één centraal e-mailadres. Dit configureer je met onderstaande variabelen.
+ +| Variabele | Uitleg | +| --------------------- | --------------------------------------- | +| `FEEDBACK_EMAIL_FROM` | Afzenderadres van de feedbackmail | +| `FEEDBACK_EMAIL_TO` | Adres waar de feedbackmail naartoe moet | +| `EMAIL_ENABLE_SSL` | Gebruik van SSL (true/false) | +| `EMAIL_HOST` | Adres van de mailserver | +| `EMAIL_PORT` | Poortnummer van de mailverbinding | +| `EMAIL_USERNAME` | Gebruikersnaam voor de mailserver | +| `EMAIL_PASSWORD` | Wachtwoord voor de mailserver | +| | | + +### Gekoppelde Bronnen + +Er zijn diverse API's die vanuit KISS bevraagd worden. Hieronder staan de environment variabelen per gekoppelde bron. +**Let op**: +1. Sommige API-keys en Secrets die KISS nodig heeft om externe registers te bevragen moeten **minimaal 32 karakters** lang zijn. +2. Voor variabelen met `__0__` als tussenvoegsel geldt dat er een lijst opgebouwd kan worden. Het eerste item van de lijst heeft `__0__` als tussenvoegsel, het tweede item `__1__`, en zo verder. + +
Meer informatie Er zijn diverse bronnen die vanuit KISS via API's bevraagd worden. Sommige worden alleen geraadpleegd, zoals de KvK-API en de API voor Haal Centraal BRP Personen bevragen, en de Objecten API voor het ophalen van Afdelingen, Groepen en Medewerkers. Andere registraties worden niet alleen geraadpleegd, maar er worden ook gegevens in weggeschreven. Dit zijn in ieder geval een Klanten- en Contactmomentenregister, zoals Open Klant, het Objecten Register zoals Open Objecten, en een Zaaksysteem (m.b.v. ZGW API's) zoals Open Zaak. + +Daarnaast zijn er bronnen die binnen KISS doorzocht moeten worden. + +- KISS gebruikt de Objecten API om Kennisartikelen (PDC-producten) mee op te halen, en naar Elastic te pushen. +- KISS gebruikt op dit moment de Objecten API om de Medewerkers in het Smoelenboek op te halen en naar Elastic te pushen. +- KISS gebruikt op dit moment de Objecten API om de Vraag Antwoord Combinaties (VAC) op te halen en naar Elastic te pushen.
+ + +#### KISS-frontend + +| Variabele | Uitleg | +| --------------------------------- | -------------------------------------------------------------------------------------------- | +| `HAAL_CENTRAAL_BASE_URL` | URL van de Haal Centraal API
Meer informatie Bijvoorbeeld: `https://proefomgeving.haalcentraal.nl/haalcentraal/api`
| +| `HAAL_CENTRAAL_API_KEY` | Key voor de Haal Centraal API | +| `KVK_BASE_URL` | URL van de KvK-API
Meer informatie URL van de KvK-API om het Handelsregister te bevragen. Dit is het pad voorafgaand aan het versienummer, bijvoorbeeld `https://api.kvk.nl/test/api`
| +| `KVK_API_KEY` | Key voor de KvK-API | +| `ELASTIC_BASE_URL` | De URL voor Elasticsearch
Meer informatie Bijvoorbeeld: `https://kiss-es-http:9200`
| +| `ELASTIC_USERNAME` | Username om in te loggen op Elasticsearch
Meer informatie Dit kan de default root user `elastic` zijn, maar ook de username van een gebruiker die je zelf hebt aangemaakt.
| +| `ELASTIC_PASSWORD` | Wachtwoord voor de bovenstaande user
Meer informatie Als je gebruik maakt van [ECK](https://www.elastic.co/guide/en/cloud-on-k8s/2.8/k8s-overview.html), dan kun je het wachtwoord van de default user vinden, m.b.v. het commando `kubectl get secret kiss-es-elastic-user -o go-template='{{.data.elastic | base64decode}}'`
| +| `ENTERPRISE_SEARCH_BASE_URL` | URL van de API waarop KISS de elastic instantie kan bevragen
Meer informatie Bijvoorbeeld `https://kiss-ent-http:3002`
| +| `ENTERPRISE_SEARCH_PUBLIC_API_KEY` | Public API key voor Elastic API | +| `ENTERPRISE_SEARCH_PRIVATE_API_KEY` | Private API key voor Elastic API
Meer informatie De API key die nodig is om de `engine`s bij te werken
| +| `ENTERPRISE_SEARCH_ENGINE` | De naam van de `meta-engine` engine die KISS gebruikt. Dit moet zijn: `KISS-engine`
Meer informatie De KISS-Elastic-Sync maakt deze engine aan, als deze nog niet bestaat.
| +| `USE_KLANTINTERACTIES` | Deze variabele bepaalt of er gebruik wordt gemaakt van OpenKlant 2.0 (klantinteractieregister).
Meer informatie Als deze variabele op `true` staat, wordt OpenKlant 2.0 gebruikt. Hiervoor zijn de variabelen `KLANTINTERACTIES_BASE_URL` en `KLANTINTERACTIES_TOKEN` nodig. Standaard is deze waarde `false`, in dat geval worden de oude Contactmomenten API en Klanten API gebruikt, voor communicatie met de e-Suite. In dat geval zijn de variabelen `KLANTEN_BASE_URL`, `KLANTEN_CLIENT_ID` en `KLANTEN_CLIENT_SECRET` nodig.
| +| `KLANTINTERACTIES_BASE_URL` | URL van de Klantinteractie API van het gebruikte klantinteractieregister (bijvoorbeeld Open Klant 2)
Meer informatie Bijvoorbeeld `https://klantinteractieregister.mijngemeente.nl/klantinteracties`
| +| `KLANTINTERACTIES_TOKEN` | Token voor de Klantinteractie API van het gebruikte klantinteractieregister | +| `KLANTEN_BASE_URL` | URL van de Klanten API van het gebruikte klantenregister, noodzakelijk als `USE_KLANTINTERACTIES` op false staat of niet gedefinieerd is.
Meer informatie Bijvoorbeeld `https://klantenregister.mijngemeente.nl/klanten`
| +| `KLANTEN_CLIENT_ID` | ClientId voor de Klanten API van het gebruikte klantenregister, , noodzakelijk als `USE_KLANTINTERACTIES` op false staat of niet gedefinieerd is. | +| `KLANTEN_CLIENT_SECRET` | Secret voor de Klanten API
**(min. 32 karakters)** | +| `CONTACTMOMENTEN_BASE_URL` | URL van de Contactmomenten API
Meer informatie Bijvoorbeeld: `https://contactmomentenregister.mijngemeente.nl`
| +| `CONTACTMOMENTEN_API_CLIENT_ID` | ClientId voor de Contactmomenten API van het gebruikte Contactmomentenregister | +| `CONTACTMOMENTEN_API_KEY` | Key voor de Contactmomenten API
**(min. 32 karakters)** | +| `ZAAKSYSTEEM__0__BASE_URL` | URL van de ZGW API's
Meer informatie Bijvoorbeeld: `https://zaaksysteem.mijngemeente.nl`
| +| `ZAAKSYSTEEM__0__API_KEY` | API Key voor de ZGW API's
**(min. 32 karakters)** | +| `ZAAKSYSTEEM__0__API_CLIENT_ID` | ClientId voor de ZGW API's | +| `ZAAKSYSTEEM__0__DEEPLINK_URL` | Basisurl om te deeplinken naar een Zaak in het zaaksysteem (optioneel)
Meer informatie Bijvoorbeeld: `https://zaaksysteem.mijngemeente.nl/mp/zaak/`
Deze variabele **moet** altijd gebruikt worden **in combinatie met** `ZAAKSYSTEEM__0__DEEPLINK_PROPERTY`. Als deze variabelen beiden worden ingevuld, zal er in KISS een link in het zaakdetailscherm staan, waarmee de KCM de betreffende zaak direct in het zaaksysteem opent. LET OP: dit kan alleen bij zaaksystemen die een vaste url hebben voor zaakdetails, waarbij alleen één property van de zaak, bijv. het zaaknummer, áchter die URL geplaatst hoeft te worden.
| +| `ZAAKSYSTEEM__0__DEEPLINK_PROPERTY` | Property om naar een zaak te kunnen deeplinken (optioneel)
Meer informatie Deze variabele **moet** altijd gebruikt worden **in combinatie met** `ZAAKSYSTEEM__0__DEEPLINK_URL`. De waarde uit dit property van een specifieke zaak wordt achter `ZAAKSYSTEEM_DEEPLINK_URL` geplaatst om de link te laten werken. Bijvoorbeeld: `identificatie`
| +| `ZAAKSYSTEEM__0__NIETNATUURLIJKPERSOONIDENTIFIER` | Identifier voor 'niet natuurlijke personen'
(`rsin` of `kvkNummer`) voor dit zaaksysteem
Meer informatie Afhankelijk van de gebruikte bron (bijvoorbeeld Open Zaak of de e-Suite) kan je hiermee aangeven welk gegeven gebruikt wordt om zaken van een `niet natuurlijke persoon` op te zoeken in een zaaksysteem. Op dit moment kan je hiervoor het RSIN (`rsin`) of het KvK-nummer (`kvkNummer`) gebruiken. RSIN is de default: als deze variable leeg gelaten wordt of ontbreekt bij de installatie, zal `rsin` gebruikt worden. Als je de e-Suite als register gebruikt, moet je hier `kvkNummer` invullen. Let op, de spelling moet exact overeen komen.
| +| `AFDELINGEN_BASE_URL` | URL van de Objecten API voor afdelingen.
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `AFDELINGEN_OBJECT_TYPE_URL` | URL van het Objecttype Afdeling
Meer informatie Bijvoorbeeld: `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `AFDELINGEN_TOKEN` | Token voor Objecten API voor afdelingen | +| `GROEPEN_BASE_URL` | URL van de Objecten API voor groepen.
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `GROEPEN_OBJECT_TYPE_URL` | URL van het Objecttype Groep
Meer informatie Bijvoorbeeld: `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `GROEPEN_TOKEN` | Token van de Objecten API voor groepen | +| `INTERNE_TAAK_BASE_URL` | URL van de Objecten API voor Interne Taken
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `INTERNE_TAAK_OBJECT_TYPE_URL` | URL van het Objecttype Interne Taak
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `INTERNE_TAAK_TYPE_VERSION` | Versienummer van het Objecttype Interne Taak
Meer informatie Bijvoorbeeld `2`
KISS schrijft InterneTaken in het Objectenregister. Hierbij moet je altijd de versie van het objecttype meegeven. Omdat het per gemeente kan verschillen welke versie de meest recente is, moet je hier invullen welk versienummer KISS moet meegeven.
| +| `INTERNE_TAAK_TOKEN` | Token voor de Objecten API voor Interne Taken
**(Als deze variabele een waarde heeft, moeten `INTERNE_TAAK_CLIENT_SECRET` en `INTERNE_TAAK_CLIENT_ID` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| +| `INTERNE_TAAK_CLIENT_SECRET` | Client Secret voor de Interne Taken API
**(Als deze variabele een waarde heeft, moet `INTERNE_TAAK_TOKEN` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| +| `INTERNE_TAAK_CLIENT_ID` | Client ID voor de Interne Taken API
**(Als deze variabele een waarde heeft, moet `INTERNE_TAAK_TOKEN` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| +| `VAC_OBJECTEN_BASE_URL` | URL van de Objecten API voor VAC's
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `VAC_OBJECT_TYPE_URL` | URL van het Objecttype VAC
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `VAC_OBJECT_TYPE_VERSION` | Versienummer van het Objecttype VAC
Meer informatie Bijvoorbeeld `2`
KISS schrijft Vacs in het Objectenregister. Hierbij moet je altijd de versie van het objecttype meegeven. Omdat het per gemeente kan verschillen welke versie de meest recente is, moet je hier invullen welk versienummer KISS moet meegeven.
| +| `VAC_OBJECTEN_TOKEN` | Token voor de Objecten API voor VAC's
Meer informatie In het geval van Vacs identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`.
| +| `USE_VACS` | Deze variabele bepaalt of het navigatie-item voor het beheren van VAC's aanwezig is in de beheernavigatie.
Meer informatie Als deze variabele op `true` staat, is het Vacs-item zichtbaar en kunnen beheerders gebruikmaken van de functionaliteit. Als de variabele niet op true staat, of niet is ingesteld, zal het item niet aanwezig zijn in de beheernavigatie.
| +| `USE_MEDEWERKEREMAIL` | Deze variabele bepaalt of een contactverzoek voor een medewerker alléén op e-mailadres kan.
Meer informatie Als deze variabele op `true` staat, zal in het contactverzoek-formulier, onder de geselecteerde afdeling of groep, een veld staan om het emailadres van een medewerker in te voeren. Direct een contactverzoek voor een medewerker maken kan in deze situatie niet. Het veld e-mailadres is niet verplicht. Als de variabele niet op `true` staat, geen waarde heeft of afwezig is, heb je in KISS wel de mogelijkheid om een Contactverzoek voor een medewerker te maken, en kun je in KISS de medewerker uit een lijst kiezen op naam.
| + +#### KISS-Elastic-Sync +
Meer informatie KISS-Elastic-Sync is het component dat zorgt dat de gekoppelde bronnen die via Elasticsearch ontsloten worden in KISS, naar de juiste Indexen worden gepushed, met de benodigde gegevens hieraan toegevoegd. Onderstaande environment variabelen gaan over de bronnen die gekoppeld zijn aan de KISS-Elastic-Sync.
+ + +| Variabele | Uitleg | +| -------------------------------------| -------------------------------------------------------------------------------------------------------- | +| `ENTERPRISE_SEARCH_BASE_URL` | URL van de API voor de elastic instantie | +| `ENTERPRISE_SEARCH_PRIVATE_API_KEY` | Private API key voor Elastic | +| `MEDEWERKER_OBJECTEN_BASE_URL` | URL van de Objecten API voor medewerkers
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `MEDEWERKER_OBJECTEN_TOKEN` | Token voor de Objecten API voor medewerkers
**(Als deze variabele een waarde heeft, moeten MEDEWERKER_OBJECTEN_CLIENT_SECRET en MEDEWERKER_OBJECTEN_CLIENT_ID leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| +| `MEDEWERKER_OBJECTEN_CLIENT_ID` | Client ID voor de Objecten API voor medewerkers
**(Als deze variabele een waarde heeft, moet MEDEWERKER_OBJECTEN_TOKEN leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| +| `MEDEWERKER_OBJECTEN_CLIENT_SECRET` | Client Secret voor de Objecten API voor medewerkers
**(Als deze een waarde heeft, deze variabele MEDEWERKER_OBJECTEN_TOKEN leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| +| `MEDEWERKER_OBJECT_TYPE_URL` | URL van het Objecttype Medewerker
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `VAC_OBJECTEN_BASE_URL` | URL van de Objecten API voor VAC's
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `VAC_OBJECT_TYPE_URL` | URL van het Objecttype VAC
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `VAC_OBJECTEN_TOKEN` | Token voor de Objecten API voor VAC's
Meer informatie In het geval van Vacs identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`.
| +| `SDG_BASE_URL` | URL van de API voor Kennisartikelen
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `SDG_OBJECTEN_TOKEN` | Key voor de API voor Kennisartikelen | +| `SDG_OBJECT_TYPE_URL` | URL van het Objecttype Kennisartikel
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| + +## Installatie + +### Placeholders + +De yaml-voorbeeldbestanden staan [hier](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/blob/main/helm/kiss-frontend/kiss.template.yaml). + +### Uitvoeren + +De installatie kan uitgevoerd worden middels het PowerShell script. Handmatig uitvoeren kan ook. + +[install_kiss.ps1](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/scripts/install_kiss.ps1) + +**LET OP** +- Voordat een ingelogde gebruiker kan werken met KISS, moet deze gebruiker de juiste rol hebben in de gekoppelde Identity provider. Zie voor meer informatie het onderdeel [Configuratie van uw Identity Provider in de configuratie-handleiding](CONFIGURATIE.md#configuratie-van-uw-identity-provider). +- Om een betere indruk te krijgen van hoe KISS werkt, is het mogelijk om **voorbeeldata (demodata)** te laden. Zie hiervoor [de uitleg bij de Beheerhandleiding](MANUAL.md#kiss-beheer-vullen-met-voorbeelddata). + +#### KISS-Elastic-Sync +KISS-Elastic-Sync is het component dat zorgt voor het creëren van de benodigde engines in een Elasticsearch-installatie, zodat gekoppelde bronnen eenvoudig door KISS doorzoekbaar zijn. Het ondersteunt zowel websites als gestructureerde bronnen door respectievelijk een crawler en een index te gebruiken. + +Meer informatie over de KISS-Elastic-Sync tool en hoe deze te installeren, is te vinden op de volgende URL: +[KISS-Elastic-Sync](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/README.md) + +##### Cronjobs +Naast de sync tool zijn er ook cronjobs die ingesteld moeten worden voor het regelmatig synchroniseren van data. + +Meer informatie over de benodigde cronjobs en hoe deze in te stellen, is te vinden op de volgende URL: +[KISS-Elastic-Sync Cronjobs](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/deploy/README.md) From 1909b54bd00725c93e8b2b1ebd6e2c3f3800c3fa Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 21:12:57 +0100 Subject: [PATCH 08/30] delet installation rst --- docs/installation/installation.rst | 12 ------------ 1 file changed, 12 deletions(-) delete mode 100644 docs/installation/installation.rst diff --git a/docs/installation/installation.rst b/docs/installation/installation.rst deleted file mode 100644 index 639cb12..0000000 --- a/docs/installation/installation.rst +++ /dev/null @@ -1,12 +0,0 @@ -Installatie -============================================================= - -KISS draait in een Kubernetes cluster. Deze handleiding is gebaseerd op Azure Kubernetes, maar ondersteunt ook andere haven-compliant providers. De handleiding is bedoeld voor Kubernetes beheerders om KISS handmatig op een nieuw cluster te installeren. - -.. toctree:: - :maxdepth: 2 - :hidden: - - voorbereidingen.md - configuratie.md - installatie.md From 3fedcc31424385511c9f924bd5969dcf033ab566 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 21:13:25 +0100 Subject: [PATCH 09/30] move restored installation --- docs/{ => installation}/INSTALLATION.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{ => installation}/INSTALLATION.md (100%) diff --git a/docs/INSTALLATION.md b/docs/installation/INSTALLATION.md similarity index 100% rename from docs/INSTALLATION.md rename to docs/installation/INSTALLATION.md From fdd3c7ac57d7e708e9ce0fe79ff08ea85e708f4b Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 21:15:15 +0100 Subject: [PATCH 10/30] rename installation --- docs/installation/{INSTALLATION.md => installation.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/installation/{INSTALLATION.md => installation.rst} (100%) diff --git a/docs/installation/INSTALLATION.md b/docs/installation/installation.rst similarity index 100% rename from docs/installation/INSTALLATION.md rename to docs/installation/installation.rst From 28be3f122a5df576bff73aec13b5516ae2201834 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 21:25:10 +0100 Subject: [PATCH 11/30] Add configuratie.md --- docs/installation/configuratie.md | 131 ++++++++++++++++ docs/installation/installation.rst | 238 +---------------------------- 2 files changed, 139 insertions(+), 230 deletions(-) create mode 100644 docs/installation/configuratie.md diff --git a/docs/installation/configuratie.md b/docs/installation/configuratie.md new file mode 100644 index 0000000..6b6093b --- /dev/null +++ b/docs/installation/configuratie.md @@ -0,0 +1,131 @@ +# Configuratie: Environment Variabelen + +Hieronder staan de benodigde environment variabelen per onderdeel van KISS. + +## Authenticatie + +| Variabele | Uitleg | +| ---------------------------------------- | --------------------------------------------------------- | +| `OIDC_AUTHORITY` | URL van de OpenID Connect Identity Provider | +| `OIDC_CLIENT_ID` | Voor toegang tot de OpenID Connect Identity Provider | +| `OIDC_CLIENT_SECRET` | Secret voor de OpenID Connect Identity Provider | +| `OIDC_MEDEWERKER_IDENTIFICATIE_CLAIM` | Identificatie van de medewerker in registers
(default waarde is `email`)
Meer informatie Bij het wegschrijven van gegevens naar bv. Open Klant of Open Zaak is een `medewerkerIdentificatie.identificatie` verplicht. Verschillende gemeenten gebruiken hier verschillende waardes voor. Bij een koppeling met bv. de e-Suite is het van belang dat hier de e-Suite gebruikersnaam in staat van de ingelogde KCM.
| +| `OIDC_MEDEWERKER_IDENTIFICATIE_TRUNCATE` | Optioneel afkappen van de claim
(bijv. `24`)
Meer informatie Binnen ZGW mag een `medewerkerIdentificatie.identificatie` niet langer zijn dan 24 karakters. Met deze variabele kun je ervoor zorgen dat de uiteindelijk waarde wordt afgekapt na 24 tekens.
| +| `MANAGEMENTINFORMATIE_API_KEY` | Secret dat KISS gebruikt om het JWT Token
te valideren bij het opvragen van
contactmomentdetails
Meer informatie Zie de [Handleiding beheer KISS, hoofdstuk
managementinformatie](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/MANUAL.md#management-informatie) voor informatie over
het gebruik van deze API.
| +| | | + +## Database + +| Variabele | Uitleg | +| ------------------ | ------------------------------------- | +| `POSTGRES_DB` | Naam van de database bij KISS | +| `POSTGRES_USER` | Gebruikersnaam voor toegang van KISS tot de DB | +| `POSTGRES_PASSWORD` | Wachtwoord van de postgresUser | +| | | + +## Organisatie RSIN + +| Variabele | Uitleg | +| ----------------- | ---------------------------------------------------------------- | +| `ORGANISATIE_IDS` | RSIN van de organisatie die de
Contactmomenten registreert
Meer informatie Verschillende ZGW APIs, waaronder de Klant en Contactmoment APIs, vragen om een identificatienummer, RSIN, van de eigen organisatie. Dit RSIN moet worden meegegeven bij registratie van specifieke objecten.
| +| | | + +## Feedback op Kennisartikelen +
Meer informatie Vanuit KISS kan een KCM feedback geven op een kennisartikel. Deze informatie wordt gemaild naar één centraal e-mailadres. Dit configureer je met onderstaande variabelen.
+ +| Variabele | Uitleg | +| --------------------- | --------------------------------------- | +| `FEEDBACK_EMAIL_FROM` | Afzenderadres van de feedbackmail | +| `FEEDBACK_EMAIL_TO` | Adres waar de feedbackmail naartoe moet | +| `EMAIL_ENABLE_SSL` | Gebruik van SSL (true/false) | +| `EMAIL_HOST` | Adres van de mailserver | +| `EMAIL_PORT` | Poortnummer van de mailverbinding | +| `EMAIL_USERNAME` | Gebruikersnaam voor de mailserver | +| `EMAIL_PASSWORD` | Wachtwoord voor de mailserver | +| | | + +## Gekoppelde Bronnen + +Er zijn diverse API's die vanuit KISS bevraagd worden. Hieronder staan de environment variabelen per gekoppelde bron. +**Let op**: +1. Sommige API-keys en Secrets die KISS nodig heeft om externe registers te bevragen moeten **minimaal 32 karakters** lang zijn. +2. Voor variabelen met `__0__` als tussenvoegsel geldt dat er een lijst opgebouwd kan worden. Het eerste item van de lijst heeft `__0__` als tussenvoegsel, het tweede item `__1__`, en zo verder. + +
Meer informatie Er zijn diverse bronnen die vanuit KISS via API's bevraagd worden. Sommige worden alleen geraadpleegd, zoals de KvK-API en de API voor Haal Centraal BRP Personen bevragen, en de Objecten API voor het ophalen van Afdelingen, Groepen en Medewerkers. Andere registraties worden niet alleen geraadpleegd, maar er worden ook gegevens in weggeschreven. Dit zijn in ieder geval een Klanten- en Contactmomentenregister, zoals Open Klant, het Objecten Register zoals Open Objecten, en een Zaaksysteem (m.b.v. ZGW API's) zoals Open Zaak. + +Daarnaast zijn er bronnen die binnen KISS doorzocht moeten worden. + +- KISS gebruikt de Objecten API om Kennisartikelen (PDC-producten) mee op te halen, en naar Elastic te pushen. +- KISS gebruikt op dit moment de Objecten API om de Medewerkers in het Smoelenboek op te halen en naar Elastic te pushen. +- KISS gebruikt op dit moment de Objecten API om de Vraag Antwoord Combinaties (VAC) op te halen en naar Elastic te pushen.
+ + +### KISS-frontend + +| Variabele | Uitleg | +| --------------------------------- | -------------------------------------------------------------------------------------------- | +| `HAAL_CENTRAAL_BASE_URL` | URL van de Haal Centraal API
Meer informatie Bijvoorbeeld: `https://proefomgeving.haalcentraal.nl/haalcentraal/api`
| +| `HAAL_CENTRAAL_API_KEY` | Key voor de Haal Centraal API | +| `KVK_BASE_URL` | URL van de KvK-API
Meer informatie URL van de KvK-API om het Handelsregister te bevragen. Dit is het pad voorafgaand aan het versienummer, bijvoorbeeld `https://api.kvk.nl/test/api`
| +| `KVK_API_KEY` | Key voor de KvK-API | +| `ELASTIC_BASE_URL` | De URL voor Elasticsearch
Meer informatie Bijvoorbeeld: `https://kiss-es-http:9200`
| +| `ELASTIC_USERNAME` | Username om in te loggen op Elasticsearch
Meer informatie Dit kan de default root user `elastic` zijn, maar ook de username van een gebruiker die je zelf hebt aangemaakt.
| +| `ELASTIC_PASSWORD` | Wachtwoord voor de bovenstaande user
Meer informatie Als je gebruik maakt van [ECK](https://www.elastic.co/guide/en/cloud-on-k8s/2.8/k8s-overview.html), dan kun je het wachtwoord van de default user vinden, m.b.v. het commando `kubectl get secret kiss-es-elastic-user -o go-template='{{.data.elastic | base64decode}}'`
| +| `ENTERPRISE_SEARCH_BASE_URL` | URL van de API waarop KISS de elastic instantie kan bevragen
Meer informatie Bijvoorbeeld `https://kiss-ent-http:3002`
| +| `ENTERPRISE_SEARCH_PUBLIC_API_KEY` | Public API key voor Elastic API | +| `ENTERPRISE_SEARCH_PRIVATE_API_KEY` | Private API key voor Elastic API
Meer informatie De API key die nodig is om de `engine`s bij te werken
| +| `ENTERPRISE_SEARCH_ENGINE` | De naam van de `meta-engine` engine die KISS gebruikt. Dit moet zijn: `KISS-engine`
Meer informatie De KISS-Elastic-Sync maakt deze engine aan, als deze nog niet bestaat.
| +| `USE_KLANTINTERACTIES` | Deze variabele bepaalt of er gebruik wordt gemaakt van OpenKlant 2.0 (klantinteractieregister).
Meer informatie Als deze variabele op `true` staat, wordt OpenKlant 2.0 gebruikt. Hiervoor zijn de variabelen `KLANTINTERACTIES_BASE_URL` en `KLANTINTERACTIES_TOKEN` nodig. Standaard is deze waarde `false`, in dat geval worden de oude Contactmomenten API en Klanten API gebruikt, voor communicatie met de e-Suite. In dat geval zijn de variabelen `KLANTEN_BASE_URL`, `KLANTEN_CLIENT_ID` en `KLANTEN_CLIENT_SECRET` nodig.
| +| `KLANTINTERACTIES_BASE_URL` | URL van de Klantinteractie API van het gebruikte klantinteractieregister (bijvoorbeeld Open Klant 2)
Meer informatie Bijvoorbeeld `https://klantinteractieregister.mijngemeente.nl/klantinteracties`
| +| `KLANTINTERACTIES_TOKEN` | Token voor de Klantinteractie API van het gebruikte klantinteractieregister | +| `KLANTEN_BASE_URL` | URL van de Klanten API van het gebruikte klantenregister, noodzakelijk als `USE_KLANTINTERACTIES` op false staat of niet gedefinieerd is.
Meer informatie Bijvoorbeeld `https://klantenregister.mijngemeente.nl/klanten`
| +| `KLANTEN_CLIENT_ID` | ClientId voor de Klanten API van het gebruikte klantenregister, , noodzakelijk als `USE_KLANTINTERACTIES` op false staat of niet gedefinieerd is. | +| `KLANTEN_CLIENT_SECRET` | Secret voor de Klanten API
**(min. 32 karakters)** | +| `CONTACTMOMENTEN_BASE_URL` | URL van de Contactmomenten API
Meer informatie Bijvoorbeeld: `https://contactmomentenregister.mijngemeente.nl`
| +| `CONTACTMOMENTEN_API_CLIENT_ID` | ClientId voor de Contactmomenten API van het gebruikte Contactmomentenregister | +| `CONTACTMOMENTEN_API_KEY` | Key voor de Contactmomenten API
**(min. 32 karakters)** | +| `ZAAKSYSTEEM__0__BASE_URL` | URL van de ZGW API's
Meer informatie Bijvoorbeeld: `https://zaaksysteem.mijngemeente.nl`
| +| `ZAAKSYSTEEM__0__API_KEY` | API Key voor de ZGW API's
**(min. 32 karakters)** | +| `ZAAKSYSTEEM__0__API_CLIENT_ID` | ClientId voor de ZGW API's | +| `ZAAKSYSTEEM__0__DEEPLINK_URL` | Basisurl om te deeplinken naar een Zaak in het zaaksysteem (optioneel)
Meer informatie Bijvoorbeeld: `https://zaaksysteem.mijngemeente.nl/mp/zaak/`
Deze variabele **moet** altijd gebruikt worden **in combinatie met** `ZAAKSYSTEEM__0__DEEPLINK_PROPERTY`. Als deze variabelen beiden worden ingevuld, zal er in KISS een link in het zaakdetailscherm staan, waarmee de KCM de betreffende zaak direct in het zaaksysteem opent. LET OP: dit kan alleen bij zaaksystemen die een vaste url hebben voor zaakdetails, waarbij alleen één property van de zaak, bijv. het zaaknummer, áchter die URL geplaatst hoeft te worden.
| +| `ZAAKSYSTEEM__0__DEEPLINK_PROPERTY` | Property om naar een zaak te kunnen deeplinken (optioneel)
Meer informatie Deze variabele **moet** altijd gebruikt worden **in combinatie met** `ZAAKSYSTEEM__0__DEEPLINK_URL`. De waarde uit dit property van een specifieke zaak wordt achter `ZAAKSYSTEEM_DEEPLINK_URL` geplaatst om de link te laten werken. Bijvoorbeeld: `identificatie`
| +| `ZAAKSYSTEEM__0__NIETNATUURLIJKPERSOONIDENTIFIER` | Identifier voor 'niet natuurlijke personen'
(`rsin` of `kvkNummer`) voor dit zaaksysteem
Meer informatie Afhankelijk van de gebruikte bron (bijvoorbeeld Open Zaak of de e-Suite) kan je hiermee aangeven welk gegeven gebruikt wordt om zaken van een `niet natuurlijke persoon` op te zoeken in een zaaksysteem. Op dit moment kan je hiervoor het RSIN (`rsin`) of het KvK-nummer (`kvkNummer`) gebruiken. RSIN is de default: als deze variable leeg gelaten wordt of ontbreekt bij de installatie, zal `rsin` gebruikt worden. Als je de e-Suite als register gebruikt, moet je hier `kvkNummer` invullen. Let op, de spelling moet exact overeen komen.
| +| `AFDELINGEN_BASE_URL` | URL van de Objecten API voor afdelingen.
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `AFDELINGEN_OBJECT_TYPE_URL` | URL van het Objecttype Afdeling
Meer informatie Bijvoorbeeld: `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `AFDELINGEN_TOKEN` | Token voor Objecten API voor afdelingen | +| `GROEPEN_BASE_URL` | URL van de Objecten API voor groepen.
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `GROEPEN_OBJECT_TYPE_URL` | URL van het Objecttype Groep
Meer informatie Bijvoorbeeld: `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `GROEPEN_TOKEN` | Token van de Objecten API voor groepen | +| `INTERNE_TAAK_BASE_URL` | URL van de Objecten API voor Interne Taken
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `INTERNE_TAAK_OBJECT_TYPE_URL` | URL van het Objecttype Interne Taak
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `INTERNE_TAAK_TYPE_VERSION` | Versienummer van het Objecttype Interne Taak
Meer informatie Bijvoorbeeld `2`
KISS schrijft InterneTaken in het Objectenregister. Hierbij moet je altijd de versie van het objecttype meegeven. Omdat het per gemeente kan verschillen welke versie de meest recente is, moet je hier invullen welk versienummer KISS moet meegeven.
| +| `INTERNE_TAAK_TOKEN` | Token voor de Objecten API voor Interne Taken
**(Als deze variabele een waarde heeft, moeten `INTERNE_TAAK_CLIENT_SECRET` en `INTERNE_TAAK_CLIENT_ID` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| +| `INTERNE_TAAK_CLIENT_SECRET` | Client Secret voor de Interne Taken API
**(Als deze variabele een waarde heeft, moet `INTERNE_TAAK_TOKEN` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| +| `INTERNE_TAAK_CLIENT_ID` | Client ID voor de Interne Taken API
**(Als deze variabele een waarde heeft, moet `INTERNE_TAAK_TOKEN` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| +| `VAC_OBJECTEN_BASE_URL` | URL van de Objecten API voor VAC's
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `VAC_OBJECT_TYPE_URL` | URL van het Objecttype VAC
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `VAC_OBJECT_TYPE_VERSION` | Versienummer van het Objecttype VAC
Meer informatie Bijvoorbeeld `2`
KISS schrijft Vacs in het Objectenregister. Hierbij moet je altijd de versie van het objecttype meegeven. Omdat het per gemeente kan verschillen welke versie de meest recente is, moet je hier invullen welk versienummer KISS moet meegeven.
| +| `VAC_OBJECTEN_TOKEN` | Token voor de Objecten API voor VAC's
Meer informatie In het geval van Vacs identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`.
| +| `USE_VACS` | Deze variabele bepaalt of het navigatie-item voor het beheren van VAC's aanwezig is in de beheernavigatie.
Meer informatie Als deze variabele op `true` staat, is het Vacs-item zichtbaar en kunnen beheerders gebruikmaken van de functionaliteit. Als de variabele niet op true staat, of niet is ingesteld, zal het item niet aanwezig zijn in de beheernavigatie.
| +| `USE_MEDEWERKEREMAIL` | Deze variabele bepaalt of een contactverzoek voor een medewerker alléén op e-mailadres kan.
Meer informatie Als deze variabele op `true` staat, zal in het contactverzoek-formulier, onder de geselecteerde afdeling of groep, een veld staan om het emailadres van een medewerker in te voeren. Direct een contactverzoek voor een medewerker maken kan in deze situatie niet. Het veld e-mailadres is niet verplicht. Als de variabele niet op `true` staat, geen waarde heeft of afwezig is, heb je in KISS wel de mogelijkheid om een Contactverzoek voor een medewerker te maken, en kun je in KISS de medewerker uit een lijst kiezen op naam.
| + +### KISS-Elastic-Sync +
Meer informatie KISS-Elastic-Sync is het component dat zorgt dat de gekoppelde bronnen die via Elasticsearch ontsloten worden in KISS, naar de juiste Indexen worden gepushed, met de benodigde gegevens hieraan toegevoegd. Onderstaande environment variabelen gaan over de bronnen die gekoppeld zijn aan de KISS-Elastic-Sync.
+ + +| Variabele | Uitleg | +| -------------------------------------| -------------------------------------------------------------------------------------------------------- | +| `ENTERPRISE_SEARCH_BASE_URL` | URL van de API voor de elastic instantie | +| `ENTERPRISE_SEARCH_PRIVATE_API_KEY` | Private API key voor Elastic | +| `MEDEWERKER_OBJECTEN_BASE_URL` | URL van de Objecten API voor medewerkers
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `MEDEWERKER_OBJECTEN_TOKEN` | Token voor de Objecten API voor medewerkers
**(Als deze variabele een waarde heeft, moeten MEDEWERKER_OBJECTEN_CLIENT_SECRET en MEDEWERKER_OBJECTEN_CLIENT_ID leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| +| `MEDEWERKER_OBJECTEN_CLIENT_ID` | Client ID voor de Objecten API voor medewerkers
**(Als deze variabele een waarde heeft, moet MEDEWERKER_OBJECTEN_TOKEN leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| +| `MEDEWERKER_OBJECTEN_CLIENT_SECRET` | Client Secret voor de Objecten API voor medewerkers
**(Als deze een waarde heeft, deze variabele MEDEWERKER_OBJECTEN_TOKEN leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| +| `MEDEWERKER_OBJECT_TYPE_URL` | URL van het Objecttype Medewerker
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `VAC_OBJECTEN_BASE_URL` | URL van de Objecten API voor VAC's
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `VAC_OBJECT_TYPE_URL` | URL van het Objecttype VAC
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `VAC_OBJECTEN_TOKEN` | Token voor de Objecten API voor VAC's
Meer informatie In het geval van Vacs identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`.
| +| `SDG_BASE_URL` | URL van de API voor Kennisartikelen
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `SDG_OBJECTEN_TOKEN` | Key voor de API voor Kennisartikelen | +| `SDG_OBJECT_TYPE_URL` | URL van het Objecttype Kennisartikel
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| + diff --git a/docs/installation/installation.rst b/docs/installation/installation.rst index be631bd..639cb12 100644 --- a/docs/installation/installation.rst +++ b/docs/installation/installation.rst @@ -1,234 +1,12 @@ -# Klantinteractie Servicesysteem (KISS) Installatie Handleiding - -## Inhoudsopgave - -- [Klantinteractie Servicesysteem (KISS) Installatie Handleiding](#klantinteractie-servicesysteem-kiss-installatie-handleiding) - - [Inhoudsopgave](#inhoudsopgave) - - [Inleiding](#inleiding) - - [Voorbereidingen](#voorbereidingen) - - [Domein](#domein) - - [Tools](#tools) - - [Haven](#haven) - - [Authenticatie](#authenticatie) - - [Configuratie: Environment Variabelen](#configuratie-environment-variabelen) - - [Authenticatie](#authenticatie-1) - - [Database](#database) - - [Organisatie RSIN](#organisatie-rsin) - - [Feedback op Kennisartikelen](#feedback-op-kennisartikelen) - - [Gekoppelde Bronnen](#gekoppelde-bronnen) - - [KISS-frontend](#kiss-frontend) - - [KISS-Elastic-Sync](#kiss-elastic-sync) - - [Installatie](#installatie) - - [Placeholders](#placeholders) - - [Uitvoeren](#uitvoeren) - - [KISS-Elastic-Sync](#kiss-elastic-sync-1) - - [KISS-Elastic-Sync-Cronjobs](#cronjobs) - ---- - -## Inleiding +Installatie +============================================================= KISS draait in een Kubernetes cluster. Deze handleiding is gebaseerd op Azure Kubernetes, maar ondersteunt ook andere haven-compliant providers. De handleiding is bedoeld voor Kubernetes beheerders om KISS handmatig op een nieuw cluster te installeren. -## Voorbereidingen - -### Domein - -Bij gebruik van Helm-Charts: zorg voor een domeinnaam met wild-card certificaat. Gebruik `.crt` en `.key` bestanden zoals hieronder: - -> `-----BEGIN CERTIFICATE-----`
-> inhoud public certificate
-> `-----END CERTIFICATE-----`
->
-> `-----BEGIN CERTIFICATE-----`
-> inhoud intermediate certificaten mits aanwezig
-> `-----END CERTIFICATE-----`
->
-> `-----BEGIN CERTIFICATE-----`
-> inhoud certificate authority certificate
-> `-----END CERTIFICATE-----` - -Het private certificate dient los als .key bestand opgeslagen te worden. - -### Tools - -Installeer de volgende tools: - -- [kubectl](https://kubernetes.io/docs/tasks/tools/) -- [Helm](https://helm.sh/docs/intro/install/) -- [Haven](https://haven.commonground.nl/techniek/compliancy-checker) -- [Powershell](https://learn.microsoft.com/en-us/powershell/) - -### Haven - -KISS kan op een haven-compliant cluster geïnstallleerd worden. Referentie-implementaties van haven-compliant clusters zijn te vinden op de [Haven](https://haven.commonground.nl/techniek/aan-de-slag) site. - -Bij het volgen van de [Azure](https://haven.commonground.nl/techniek/aan-de-slag/azure) referentie moet men rekening houden met de volgende extra zaken: - -- Minimaal 3 nodes -- High availability aanzetten -- Local logins met RBAC gebruiken, GEEN Azure Active Directory! - - -### Authenticatie - -De authenticatie van gebruikers binnen KISS gebeurt m.b.v. een OIDC koppeling met bijvoorbeeld Azure Active Directory. - -## Configuratie: Environment Variabelen - -Hieronder staan de benodigde environment variabelen per onderdeel van KISS. - -### Authenticatie - -| Variabele | Uitleg | -| ---------------------------------------- | --------------------------------------------------------- | -| `OIDC_AUTHORITY` | URL van de OpenID Connect Identity Provider | -| `OIDC_CLIENT_ID` | Voor toegang tot de OpenID Connect Identity Provider | -| `OIDC_CLIENT_SECRET` | Secret voor de OpenID Connect Identity Provider | -| `OIDC_MEDEWERKER_IDENTIFICATIE_CLAIM` | Identificatie van de medewerker in registers
(default waarde is `email`)
Meer informatie Bij het wegschrijven van gegevens naar bv. Open Klant of Open Zaak is een `medewerkerIdentificatie.identificatie` verplicht. Verschillende gemeenten gebruiken hier verschillende waardes voor. Bij een koppeling met bv. de e-Suite is het van belang dat hier de e-Suite gebruikersnaam in staat van de ingelogde KCM.
| -| `OIDC_MEDEWERKER_IDENTIFICATIE_TRUNCATE` | Optioneel afkappen van de claim
(bijv. `24`)
Meer informatie Binnen ZGW mag een `medewerkerIdentificatie.identificatie` niet langer zijn dan 24 karakters. Met deze variabele kun je ervoor zorgen dat de uiteindelijk waarde wordt afgekapt na 24 tekens.
| -| `MANAGEMENTINFORMATIE_API_KEY` | Secret dat KISS gebruikt om het JWT Token
te valideren bij het opvragen van
contactmomentdetails
Meer informatie Zie de [Handleiding beheer KISS, hoofdstuk
managementinformatie](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/MANUAL.md#management-informatie) voor informatie over
het gebruik van deze API.
| -| | | - -### Database - -| Variabele | Uitleg | -| ------------------ | ------------------------------------- | -| `POSTGRES_DB` | Naam van de database bij KISS | -| `POSTGRES_USER` | Gebruikersnaam voor toegang van KISS tot de DB | -| `POSTGRES_PASSWORD` | Wachtwoord van de postgresUser | -| | | - -### Organisatie RSIN - -| Variabele | Uitleg | -| ----------------- | ---------------------------------------------------------------- | -| `ORGANISATIE_IDS` | RSIN van de organisatie die de
Contactmomenten registreert
Meer informatie Verschillende ZGW APIs, waaronder de Klant en Contactmoment APIs, vragen om een identificatienummer, RSIN, van de eigen organisatie. Dit RSIN moet worden meegegeven bij registratie van specifieke objecten.
| -| | | - -### Feedback op Kennisartikelen -
Meer informatie Vanuit KISS kan een KCM feedback geven op een kennisartikel. Deze informatie wordt gemaild naar één centraal e-mailadres. Dit configureer je met onderstaande variabelen.
- -| Variabele | Uitleg | -| --------------------- | --------------------------------------- | -| `FEEDBACK_EMAIL_FROM` | Afzenderadres van de feedbackmail | -| `FEEDBACK_EMAIL_TO` | Adres waar de feedbackmail naartoe moet | -| `EMAIL_ENABLE_SSL` | Gebruik van SSL (true/false) | -| `EMAIL_HOST` | Adres van de mailserver | -| `EMAIL_PORT` | Poortnummer van de mailverbinding | -| `EMAIL_USERNAME` | Gebruikersnaam voor de mailserver | -| `EMAIL_PASSWORD` | Wachtwoord voor de mailserver | -| | | - -### Gekoppelde Bronnen - -Er zijn diverse API's die vanuit KISS bevraagd worden. Hieronder staan de environment variabelen per gekoppelde bron. -**Let op**: -1. Sommige API-keys en Secrets die KISS nodig heeft om externe registers te bevragen moeten **minimaal 32 karakters** lang zijn. -2. Voor variabelen met `__0__` als tussenvoegsel geldt dat er een lijst opgebouwd kan worden. Het eerste item van de lijst heeft `__0__` als tussenvoegsel, het tweede item `__1__`, en zo verder. - -
Meer informatie Er zijn diverse bronnen die vanuit KISS via API's bevraagd worden. Sommige worden alleen geraadpleegd, zoals de KvK-API en de API voor Haal Centraal BRP Personen bevragen, en de Objecten API voor het ophalen van Afdelingen, Groepen en Medewerkers. Andere registraties worden niet alleen geraadpleegd, maar er worden ook gegevens in weggeschreven. Dit zijn in ieder geval een Klanten- en Contactmomentenregister, zoals Open Klant, het Objecten Register zoals Open Objecten, en een Zaaksysteem (m.b.v. ZGW API's) zoals Open Zaak. - -Daarnaast zijn er bronnen die binnen KISS doorzocht moeten worden. - -- KISS gebruikt de Objecten API om Kennisartikelen (PDC-producten) mee op te halen, en naar Elastic te pushen. -- KISS gebruikt op dit moment de Objecten API om de Medewerkers in het Smoelenboek op te halen en naar Elastic te pushen. -- KISS gebruikt op dit moment de Objecten API om de Vraag Antwoord Combinaties (VAC) op te halen en naar Elastic te pushen.
- - -#### KISS-frontend - -| Variabele | Uitleg | -| --------------------------------- | -------------------------------------------------------------------------------------------- | -| `HAAL_CENTRAAL_BASE_URL` | URL van de Haal Centraal API
Meer informatie Bijvoorbeeld: `https://proefomgeving.haalcentraal.nl/haalcentraal/api`
| -| `HAAL_CENTRAAL_API_KEY` | Key voor de Haal Centraal API | -| `KVK_BASE_URL` | URL van de KvK-API
Meer informatie URL van de KvK-API om het Handelsregister te bevragen. Dit is het pad voorafgaand aan het versienummer, bijvoorbeeld `https://api.kvk.nl/test/api`
| -| `KVK_API_KEY` | Key voor de KvK-API | -| `ELASTIC_BASE_URL` | De URL voor Elasticsearch
Meer informatie Bijvoorbeeld: `https://kiss-es-http:9200`
| -| `ELASTIC_USERNAME` | Username om in te loggen op Elasticsearch
Meer informatie Dit kan de default root user `elastic` zijn, maar ook de username van een gebruiker die je zelf hebt aangemaakt.
| -| `ELASTIC_PASSWORD` | Wachtwoord voor de bovenstaande user
Meer informatie Als je gebruik maakt van [ECK](https://www.elastic.co/guide/en/cloud-on-k8s/2.8/k8s-overview.html), dan kun je het wachtwoord van de default user vinden, m.b.v. het commando `kubectl get secret kiss-es-elastic-user -o go-template='{{.data.elastic | base64decode}}'`
| -| `ENTERPRISE_SEARCH_BASE_URL` | URL van de API waarop KISS de elastic instantie kan bevragen
Meer informatie Bijvoorbeeld `https://kiss-ent-http:3002`
| -| `ENTERPRISE_SEARCH_PUBLIC_API_KEY` | Public API key voor Elastic API | -| `ENTERPRISE_SEARCH_PRIVATE_API_KEY` | Private API key voor Elastic API
Meer informatie De API key die nodig is om de `engine`s bij te werken
| -| `ENTERPRISE_SEARCH_ENGINE` | De naam van de `meta-engine` engine die KISS gebruikt. Dit moet zijn: `KISS-engine`
Meer informatie De KISS-Elastic-Sync maakt deze engine aan, als deze nog niet bestaat.
| -| `USE_KLANTINTERACTIES` | Deze variabele bepaalt of er gebruik wordt gemaakt van OpenKlant 2.0 (klantinteractieregister).
Meer informatie Als deze variabele op `true` staat, wordt OpenKlant 2.0 gebruikt. Hiervoor zijn de variabelen `KLANTINTERACTIES_BASE_URL` en `KLANTINTERACTIES_TOKEN` nodig. Standaard is deze waarde `false`, in dat geval worden de oude Contactmomenten API en Klanten API gebruikt, voor communicatie met de e-Suite. In dat geval zijn de variabelen `KLANTEN_BASE_URL`, `KLANTEN_CLIENT_ID` en `KLANTEN_CLIENT_SECRET` nodig.
| -| `KLANTINTERACTIES_BASE_URL` | URL van de Klantinteractie API van het gebruikte klantinteractieregister (bijvoorbeeld Open Klant 2)
Meer informatie Bijvoorbeeld `https://klantinteractieregister.mijngemeente.nl/klantinteracties`
| -| `KLANTINTERACTIES_TOKEN` | Token voor de Klantinteractie API van het gebruikte klantinteractieregister | -| `KLANTEN_BASE_URL` | URL van de Klanten API van het gebruikte klantenregister, noodzakelijk als `USE_KLANTINTERACTIES` op false staat of niet gedefinieerd is.
Meer informatie Bijvoorbeeld `https://klantenregister.mijngemeente.nl/klanten`
| -| `KLANTEN_CLIENT_ID` | ClientId voor de Klanten API van het gebruikte klantenregister, , noodzakelijk als `USE_KLANTINTERACTIES` op false staat of niet gedefinieerd is. | -| `KLANTEN_CLIENT_SECRET` | Secret voor de Klanten API
**(min. 32 karakters)** | -| `CONTACTMOMENTEN_BASE_URL` | URL van de Contactmomenten API
Meer informatie Bijvoorbeeld: `https://contactmomentenregister.mijngemeente.nl`
| -| `CONTACTMOMENTEN_API_CLIENT_ID` | ClientId voor de Contactmomenten API van het gebruikte Contactmomentenregister | -| `CONTACTMOMENTEN_API_KEY` | Key voor de Contactmomenten API
**(min. 32 karakters)** | -| `ZAAKSYSTEEM__0__BASE_URL` | URL van de ZGW API's
Meer informatie Bijvoorbeeld: `https://zaaksysteem.mijngemeente.nl`
| -| `ZAAKSYSTEEM__0__API_KEY` | API Key voor de ZGW API's
**(min. 32 karakters)** | -| `ZAAKSYSTEEM__0__API_CLIENT_ID` | ClientId voor de ZGW API's | -| `ZAAKSYSTEEM__0__DEEPLINK_URL` | Basisurl om te deeplinken naar een Zaak in het zaaksysteem (optioneel)
Meer informatie Bijvoorbeeld: `https://zaaksysteem.mijngemeente.nl/mp/zaak/`
Deze variabele **moet** altijd gebruikt worden **in combinatie met** `ZAAKSYSTEEM__0__DEEPLINK_PROPERTY`. Als deze variabelen beiden worden ingevuld, zal er in KISS een link in het zaakdetailscherm staan, waarmee de KCM de betreffende zaak direct in het zaaksysteem opent. LET OP: dit kan alleen bij zaaksystemen die een vaste url hebben voor zaakdetails, waarbij alleen één property van de zaak, bijv. het zaaknummer, áchter die URL geplaatst hoeft te worden.
| -| `ZAAKSYSTEEM__0__DEEPLINK_PROPERTY` | Property om naar een zaak te kunnen deeplinken (optioneel)
Meer informatie Deze variabele **moet** altijd gebruikt worden **in combinatie met** `ZAAKSYSTEEM__0__DEEPLINK_URL`. De waarde uit dit property van een specifieke zaak wordt achter `ZAAKSYSTEEM_DEEPLINK_URL` geplaatst om de link te laten werken. Bijvoorbeeld: `identificatie`
| -| `ZAAKSYSTEEM__0__NIETNATUURLIJKPERSOONIDENTIFIER` | Identifier voor 'niet natuurlijke personen'
(`rsin` of `kvkNummer`) voor dit zaaksysteem
Meer informatie Afhankelijk van de gebruikte bron (bijvoorbeeld Open Zaak of de e-Suite) kan je hiermee aangeven welk gegeven gebruikt wordt om zaken van een `niet natuurlijke persoon` op te zoeken in een zaaksysteem. Op dit moment kan je hiervoor het RSIN (`rsin`) of het KvK-nummer (`kvkNummer`) gebruiken. RSIN is de default: als deze variable leeg gelaten wordt of ontbreekt bij de installatie, zal `rsin` gebruikt worden. Als je de e-Suite als register gebruikt, moet je hier `kvkNummer` invullen. Let op, de spelling moet exact overeen komen.
| -| `AFDELINGEN_BASE_URL` | URL van de Objecten API voor afdelingen.
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `AFDELINGEN_OBJECT_TYPE_URL` | URL van het Objecttype Afdeling
Meer informatie Bijvoorbeeld: `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `AFDELINGEN_TOKEN` | Token voor Objecten API voor afdelingen | -| `GROEPEN_BASE_URL` | URL van de Objecten API voor groepen.
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `GROEPEN_OBJECT_TYPE_URL` | URL van het Objecttype Groep
Meer informatie Bijvoorbeeld: `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `GROEPEN_TOKEN` | Token van de Objecten API voor groepen | -| `INTERNE_TAAK_BASE_URL` | URL van de Objecten API voor Interne Taken
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `INTERNE_TAAK_OBJECT_TYPE_URL` | URL van het Objecttype Interne Taak
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `INTERNE_TAAK_TYPE_VERSION` | Versienummer van het Objecttype Interne Taak
Meer informatie Bijvoorbeeld `2`
KISS schrijft InterneTaken in het Objectenregister. Hierbij moet je altijd de versie van het objecttype meegeven. Omdat het per gemeente kan verschillen welke versie de meest recente is, moet je hier invullen welk versienummer KISS moet meegeven.
| -| `INTERNE_TAAK_TOKEN` | Token voor de Objecten API voor Interne Taken
**(Als deze variabele een waarde heeft, moeten `INTERNE_TAAK_CLIENT_SECRET` en `INTERNE_TAAK_CLIENT_ID` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| -| `INTERNE_TAAK_CLIENT_SECRET` | Client Secret voor de Interne Taken API
**(Als deze variabele een waarde heeft, moet `INTERNE_TAAK_TOKEN` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| -| `INTERNE_TAAK_CLIENT_ID` | Client ID voor de Interne Taken API
**(Als deze variabele een waarde heeft, moet `INTERNE_TAAK_TOKEN` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| -| `VAC_OBJECTEN_BASE_URL` | URL van de Objecten API voor VAC's
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `VAC_OBJECT_TYPE_URL` | URL van het Objecttype VAC
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `VAC_OBJECT_TYPE_VERSION` | Versienummer van het Objecttype VAC
Meer informatie Bijvoorbeeld `2`
KISS schrijft Vacs in het Objectenregister. Hierbij moet je altijd de versie van het objecttype meegeven. Omdat het per gemeente kan verschillen welke versie de meest recente is, moet je hier invullen welk versienummer KISS moet meegeven.
| -| `VAC_OBJECTEN_TOKEN` | Token voor de Objecten API voor VAC's
Meer informatie In het geval van Vacs identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`.
| -| `USE_VACS` | Deze variabele bepaalt of het navigatie-item voor het beheren van VAC's aanwezig is in de beheernavigatie.
Meer informatie Als deze variabele op `true` staat, is het Vacs-item zichtbaar en kunnen beheerders gebruikmaken van de functionaliteit. Als de variabele niet op true staat, of niet is ingesteld, zal het item niet aanwezig zijn in de beheernavigatie.
| -| `USE_MEDEWERKEREMAIL` | Deze variabele bepaalt of een contactverzoek voor een medewerker alléén op e-mailadres kan.
Meer informatie Als deze variabele op `true` staat, zal in het contactverzoek-formulier, onder de geselecteerde afdeling of groep, een veld staan om het emailadres van een medewerker in te voeren. Direct een contactverzoek voor een medewerker maken kan in deze situatie niet. Het veld e-mailadres is niet verplicht. Als de variabele niet op `true` staat, geen waarde heeft of afwezig is, heb je in KISS wel de mogelijkheid om een Contactverzoek voor een medewerker te maken, en kun je in KISS de medewerker uit een lijst kiezen op naam.
| - -#### KISS-Elastic-Sync -
Meer informatie KISS-Elastic-Sync is het component dat zorgt dat de gekoppelde bronnen die via Elasticsearch ontsloten worden in KISS, naar de juiste Indexen worden gepushed, met de benodigde gegevens hieraan toegevoegd. Onderstaande environment variabelen gaan over de bronnen die gekoppeld zijn aan de KISS-Elastic-Sync.
- - -| Variabele | Uitleg | -| -------------------------------------| -------------------------------------------------------------------------------------------------------- | -| `ENTERPRISE_SEARCH_BASE_URL` | URL van de API voor de elastic instantie | -| `ENTERPRISE_SEARCH_PRIVATE_API_KEY` | Private API key voor Elastic | -| `MEDEWERKER_OBJECTEN_BASE_URL` | URL van de Objecten API voor medewerkers
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `MEDEWERKER_OBJECTEN_TOKEN` | Token voor de Objecten API voor medewerkers
**(Als deze variabele een waarde heeft, moeten MEDEWERKER_OBJECTEN_CLIENT_SECRET en MEDEWERKER_OBJECTEN_CLIENT_ID leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| -| `MEDEWERKER_OBJECTEN_CLIENT_ID` | Client ID voor de Objecten API voor medewerkers
**(Als deze variabele een waarde heeft, moet MEDEWERKER_OBJECTEN_TOKEN leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| -| `MEDEWERKER_OBJECTEN_CLIENT_SECRET` | Client Secret voor de Objecten API voor medewerkers
**(Als deze een waarde heeft, deze variabele MEDEWERKER_OBJECTEN_TOKEN leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| -| `MEDEWERKER_OBJECT_TYPE_URL` | URL van het Objecttype Medewerker
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `VAC_OBJECTEN_BASE_URL` | URL van de Objecten API voor VAC's
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `VAC_OBJECT_TYPE_URL` | URL van het Objecttype VAC
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `VAC_OBJECTEN_TOKEN` | Token voor de Objecten API voor VAC's
Meer informatie In het geval van Vacs identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`.
| -| `SDG_BASE_URL` | URL van de API voor Kennisartikelen
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `SDG_OBJECTEN_TOKEN` | Key voor de API voor Kennisartikelen | -| `SDG_OBJECT_TYPE_URL` | URL van het Objecttype Kennisartikel
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| - -## Installatie - -### Placeholders - -De yaml-voorbeeldbestanden staan [hier](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/blob/main/helm/kiss-frontend/kiss.template.yaml). - -### Uitvoeren - -De installatie kan uitgevoerd worden middels het PowerShell script. Handmatig uitvoeren kan ook. - -[install_kiss.ps1](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/scripts/install_kiss.ps1) - -**LET OP** -- Voordat een ingelogde gebruiker kan werken met KISS, moet deze gebruiker de juiste rol hebben in de gekoppelde Identity provider. Zie voor meer informatie het onderdeel [Configuratie van uw Identity Provider in de configuratie-handleiding](CONFIGURATIE.md#configuratie-van-uw-identity-provider). -- Om een betere indruk te krijgen van hoe KISS werkt, is het mogelijk om **voorbeeldata (demodata)** te laden. Zie hiervoor [de uitleg bij de Beheerhandleiding](MANUAL.md#kiss-beheer-vullen-met-voorbeelddata). - -#### KISS-Elastic-Sync -KISS-Elastic-Sync is het component dat zorgt voor het creëren van de benodigde engines in een Elasticsearch-installatie, zodat gekoppelde bronnen eenvoudig door KISS doorzoekbaar zijn. Het ondersteunt zowel websites als gestructureerde bronnen door respectievelijk een crawler en een index te gebruiken. - -Meer informatie over de KISS-Elastic-Sync tool en hoe deze te installeren, is te vinden op de volgende URL: -[KISS-Elastic-Sync](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/README.md) - -##### Cronjobs -Naast de sync tool zijn er ook cronjobs die ingesteld moeten worden voor het regelmatig synchroniseren van data. +.. toctree:: + :maxdepth: 2 + :hidden: -Meer informatie over de benodigde cronjobs en hoe deze in te stellen, is te vinden op de volgende URL: -[KISS-Elastic-Sync Cronjobs](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/deploy/README.md) + voorbereidingen.md + configuratie.md + installatie.md From a3434301898baa1ff120387e9b6f6ed3013a6cca Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 21:31:38 +0100 Subject: [PATCH 12/30] Installation 2 --- docs/installation/voorbereidingen.md | 43 ++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 docs/installation/voorbereidingen.md diff --git a/docs/installation/voorbereidingen.md b/docs/installation/voorbereidingen.md new file mode 100644 index 0000000..25d1e9a --- /dev/null +++ b/docs/installation/voorbereidingen.md @@ -0,0 +1,43 @@ +# Voorbereidingen + +## Domein + +Bij gebruik van Helm-Charts: zorg voor een domeinnaam met wild-card certificaat. Gebruik `.crt` en `.key` bestanden zoals hieronder: + +> `-----BEGIN CERTIFICATE-----`
+> inhoud public certificate
+> `-----END CERTIFICATE-----`
+>
+> `-----BEGIN CERTIFICATE-----`
+> inhoud intermediate certificaten mits aanwezig
+> `-----END CERTIFICATE-----`
+>
+> `-----BEGIN CERTIFICATE-----`
+> inhoud certificate authority certificate
+> `-----END CERTIFICATE-----` + +Het private certificate dient los als .key bestand opgeslagen te worden. + +## Tools + +Installeer de volgende tools: + +- [kubectl](https://kubernetes.io/docs/tasks/tools/) +- [Helm](https://helm.sh/docs/intro/install/) +- [Haven](https://haven.commonground.nl/techniek/compliancy-checker) +- [Powershell](https://learn.microsoft.com/en-us/powershell/) + +## Haven + +KISS kan op een haven-compliant cluster geïnstallleerd worden. Referentie-implementaties van haven-compliant clusters zijn te vinden op de [Haven](https://haven.commonground.nl/techniek/aan-de-slag) site. + +Bij het volgen van de [Azure](https://haven.commonground.nl/techniek/aan-de-slag/azure) referentie moet men rekening houden met de volgende extra zaken: + +- Minimaal 3 nodes +- High availability aanzetten +- Local logins met RBAC gebruiken, GEEN Azure Active Directory! + + +## Authenticatie + +De authenticatie van gebruikers binnen KISS gebeurt m.b.v. een OIDC koppeling met bijvoorbeeld Azure Active Directory. \ No newline at end of file From 6c42b0a3bf7b474bbe167c736521f66bdddce7a4 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 21:33:06 +0100 Subject: [PATCH 13/30] restore installationmd --- docs/INSTALLATION.md | 234 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 docs/INSTALLATION.md diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md new file mode 100644 index 0000000..be631bd --- /dev/null +++ b/docs/INSTALLATION.md @@ -0,0 +1,234 @@ +# Klantinteractie Servicesysteem (KISS) Installatie Handleiding + +## Inhoudsopgave + +- [Klantinteractie Servicesysteem (KISS) Installatie Handleiding](#klantinteractie-servicesysteem-kiss-installatie-handleiding) + - [Inhoudsopgave](#inhoudsopgave) + - [Inleiding](#inleiding) + - [Voorbereidingen](#voorbereidingen) + - [Domein](#domein) + - [Tools](#tools) + - [Haven](#haven) + - [Authenticatie](#authenticatie) + - [Configuratie: Environment Variabelen](#configuratie-environment-variabelen) + - [Authenticatie](#authenticatie-1) + - [Database](#database) + - [Organisatie RSIN](#organisatie-rsin) + - [Feedback op Kennisartikelen](#feedback-op-kennisartikelen) + - [Gekoppelde Bronnen](#gekoppelde-bronnen) + - [KISS-frontend](#kiss-frontend) + - [KISS-Elastic-Sync](#kiss-elastic-sync) + - [Installatie](#installatie) + - [Placeholders](#placeholders) + - [Uitvoeren](#uitvoeren) + - [KISS-Elastic-Sync](#kiss-elastic-sync-1) + - [KISS-Elastic-Sync-Cronjobs](#cronjobs) + +--- + +## Inleiding + +KISS draait in een Kubernetes cluster. Deze handleiding is gebaseerd op Azure Kubernetes, maar ondersteunt ook andere haven-compliant providers. De handleiding is bedoeld voor Kubernetes beheerders om KISS handmatig op een nieuw cluster te installeren. + +## Voorbereidingen + +### Domein + +Bij gebruik van Helm-Charts: zorg voor een domeinnaam met wild-card certificaat. Gebruik `.crt` en `.key` bestanden zoals hieronder: + +> `-----BEGIN CERTIFICATE-----`
+> inhoud public certificate
+> `-----END CERTIFICATE-----`
+>
+> `-----BEGIN CERTIFICATE-----`
+> inhoud intermediate certificaten mits aanwezig
+> `-----END CERTIFICATE-----`
+>
+> `-----BEGIN CERTIFICATE-----`
+> inhoud certificate authority certificate
+> `-----END CERTIFICATE-----` + +Het private certificate dient los als .key bestand opgeslagen te worden. + +### Tools + +Installeer de volgende tools: + +- [kubectl](https://kubernetes.io/docs/tasks/tools/) +- [Helm](https://helm.sh/docs/intro/install/) +- [Haven](https://haven.commonground.nl/techniek/compliancy-checker) +- [Powershell](https://learn.microsoft.com/en-us/powershell/) + +### Haven + +KISS kan op een haven-compliant cluster geïnstallleerd worden. Referentie-implementaties van haven-compliant clusters zijn te vinden op de [Haven](https://haven.commonground.nl/techniek/aan-de-slag) site. + +Bij het volgen van de [Azure](https://haven.commonground.nl/techniek/aan-de-slag/azure) referentie moet men rekening houden met de volgende extra zaken: + +- Minimaal 3 nodes +- High availability aanzetten +- Local logins met RBAC gebruiken, GEEN Azure Active Directory! + + +### Authenticatie + +De authenticatie van gebruikers binnen KISS gebeurt m.b.v. een OIDC koppeling met bijvoorbeeld Azure Active Directory. + +## Configuratie: Environment Variabelen + +Hieronder staan de benodigde environment variabelen per onderdeel van KISS. + +### Authenticatie + +| Variabele | Uitleg | +| ---------------------------------------- | --------------------------------------------------------- | +| `OIDC_AUTHORITY` | URL van de OpenID Connect Identity Provider | +| `OIDC_CLIENT_ID` | Voor toegang tot de OpenID Connect Identity Provider | +| `OIDC_CLIENT_SECRET` | Secret voor de OpenID Connect Identity Provider | +| `OIDC_MEDEWERKER_IDENTIFICATIE_CLAIM` | Identificatie van de medewerker in registers
(default waarde is `email`)
Meer informatie Bij het wegschrijven van gegevens naar bv. Open Klant of Open Zaak is een `medewerkerIdentificatie.identificatie` verplicht. Verschillende gemeenten gebruiken hier verschillende waardes voor. Bij een koppeling met bv. de e-Suite is het van belang dat hier de e-Suite gebruikersnaam in staat van de ingelogde KCM.
| +| `OIDC_MEDEWERKER_IDENTIFICATIE_TRUNCATE` | Optioneel afkappen van de claim
(bijv. `24`)
Meer informatie Binnen ZGW mag een `medewerkerIdentificatie.identificatie` niet langer zijn dan 24 karakters. Met deze variabele kun je ervoor zorgen dat de uiteindelijk waarde wordt afgekapt na 24 tekens.
| +| `MANAGEMENTINFORMATIE_API_KEY` | Secret dat KISS gebruikt om het JWT Token
te valideren bij het opvragen van
contactmomentdetails
Meer informatie Zie de [Handleiding beheer KISS, hoofdstuk
managementinformatie](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/MANUAL.md#management-informatie) voor informatie over
het gebruik van deze API.
| +| | | + +### Database + +| Variabele | Uitleg | +| ------------------ | ------------------------------------- | +| `POSTGRES_DB` | Naam van de database bij KISS | +| `POSTGRES_USER` | Gebruikersnaam voor toegang van KISS tot de DB | +| `POSTGRES_PASSWORD` | Wachtwoord van de postgresUser | +| | | + +### Organisatie RSIN + +| Variabele | Uitleg | +| ----------------- | ---------------------------------------------------------------- | +| `ORGANISATIE_IDS` | RSIN van de organisatie die de
Contactmomenten registreert
Meer informatie Verschillende ZGW APIs, waaronder de Klant en Contactmoment APIs, vragen om een identificatienummer, RSIN, van de eigen organisatie. Dit RSIN moet worden meegegeven bij registratie van specifieke objecten.
| +| | | + +### Feedback op Kennisartikelen +
Meer informatie Vanuit KISS kan een KCM feedback geven op een kennisartikel. Deze informatie wordt gemaild naar één centraal e-mailadres. Dit configureer je met onderstaande variabelen.
+ +| Variabele | Uitleg | +| --------------------- | --------------------------------------- | +| `FEEDBACK_EMAIL_FROM` | Afzenderadres van de feedbackmail | +| `FEEDBACK_EMAIL_TO` | Adres waar de feedbackmail naartoe moet | +| `EMAIL_ENABLE_SSL` | Gebruik van SSL (true/false) | +| `EMAIL_HOST` | Adres van de mailserver | +| `EMAIL_PORT` | Poortnummer van de mailverbinding | +| `EMAIL_USERNAME` | Gebruikersnaam voor de mailserver | +| `EMAIL_PASSWORD` | Wachtwoord voor de mailserver | +| | | + +### Gekoppelde Bronnen + +Er zijn diverse API's die vanuit KISS bevraagd worden. Hieronder staan de environment variabelen per gekoppelde bron. +**Let op**: +1. Sommige API-keys en Secrets die KISS nodig heeft om externe registers te bevragen moeten **minimaal 32 karakters** lang zijn. +2. Voor variabelen met `__0__` als tussenvoegsel geldt dat er een lijst opgebouwd kan worden. Het eerste item van de lijst heeft `__0__` als tussenvoegsel, het tweede item `__1__`, en zo verder. + +
Meer informatie Er zijn diverse bronnen die vanuit KISS via API's bevraagd worden. Sommige worden alleen geraadpleegd, zoals de KvK-API en de API voor Haal Centraal BRP Personen bevragen, en de Objecten API voor het ophalen van Afdelingen, Groepen en Medewerkers. Andere registraties worden niet alleen geraadpleegd, maar er worden ook gegevens in weggeschreven. Dit zijn in ieder geval een Klanten- en Contactmomentenregister, zoals Open Klant, het Objecten Register zoals Open Objecten, en een Zaaksysteem (m.b.v. ZGW API's) zoals Open Zaak. + +Daarnaast zijn er bronnen die binnen KISS doorzocht moeten worden. + +- KISS gebruikt de Objecten API om Kennisartikelen (PDC-producten) mee op te halen, en naar Elastic te pushen. +- KISS gebruikt op dit moment de Objecten API om de Medewerkers in het Smoelenboek op te halen en naar Elastic te pushen. +- KISS gebruikt op dit moment de Objecten API om de Vraag Antwoord Combinaties (VAC) op te halen en naar Elastic te pushen.
+ + +#### KISS-frontend + +| Variabele | Uitleg | +| --------------------------------- | -------------------------------------------------------------------------------------------- | +| `HAAL_CENTRAAL_BASE_URL` | URL van de Haal Centraal API
Meer informatie Bijvoorbeeld: `https://proefomgeving.haalcentraal.nl/haalcentraal/api`
| +| `HAAL_CENTRAAL_API_KEY` | Key voor de Haal Centraal API | +| `KVK_BASE_URL` | URL van de KvK-API
Meer informatie URL van de KvK-API om het Handelsregister te bevragen. Dit is het pad voorafgaand aan het versienummer, bijvoorbeeld `https://api.kvk.nl/test/api`
| +| `KVK_API_KEY` | Key voor de KvK-API | +| `ELASTIC_BASE_URL` | De URL voor Elasticsearch
Meer informatie Bijvoorbeeld: `https://kiss-es-http:9200`
| +| `ELASTIC_USERNAME` | Username om in te loggen op Elasticsearch
Meer informatie Dit kan de default root user `elastic` zijn, maar ook de username van een gebruiker die je zelf hebt aangemaakt.
| +| `ELASTIC_PASSWORD` | Wachtwoord voor de bovenstaande user
Meer informatie Als je gebruik maakt van [ECK](https://www.elastic.co/guide/en/cloud-on-k8s/2.8/k8s-overview.html), dan kun je het wachtwoord van de default user vinden, m.b.v. het commando `kubectl get secret kiss-es-elastic-user -o go-template='{{.data.elastic | base64decode}}'`
| +| `ENTERPRISE_SEARCH_BASE_URL` | URL van de API waarop KISS de elastic instantie kan bevragen
Meer informatie Bijvoorbeeld `https://kiss-ent-http:3002`
| +| `ENTERPRISE_SEARCH_PUBLIC_API_KEY` | Public API key voor Elastic API | +| `ENTERPRISE_SEARCH_PRIVATE_API_KEY` | Private API key voor Elastic API
Meer informatie De API key die nodig is om de `engine`s bij te werken
| +| `ENTERPRISE_SEARCH_ENGINE` | De naam van de `meta-engine` engine die KISS gebruikt. Dit moet zijn: `KISS-engine`
Meer informatie De KISS-Elastic-Sync maakt deze engine aan, als deze nog niet bestaat.
| +| `USE_KLANTINTERACTIES` | Deze variabele bepaalt of er gebruik wordt gemaakt van OpenKlant 2.0 (klantinteractieregister).
Meer informatie Als deze variabele op `true` staat, wordt OpenKlant 2.0 gebruikt. Hiervoor zijn de variabelen `KLANTINTERACTIES_BASE_URL` en `KLANTINTERACTIES_TOKEN` nodig. Standaard is deze waarde `false`, in dat geval worden de oude Contactmomenten API en Klanten API gebruikt, voor communicatie met de e-Suite. In dat geval zijn de variabelen `KLANTEN_BASE_URL`, `KLANTEN_CLIENT_ID` en `KLANTEN_CLIENT_SECRET` nodig.
| +| `KLANTINTERACTIES_BASE_URL` | URL van de Klantinteractie API van het gebruikte klantinteractieregister (bijvoorbeeld Open Klant 2)
Meer informatie Bijvoorbeeld `https://klantinteractieregister.mijngemeente.nl/klantinteracties`
| +| `KLANTINTERACTIES_TOKEN` | Token voor de Klantinteractie API van het gebruikte klantinteractieregister | +| `KLANTEN_BASE_URL` | URL van de Klanten API van het gebruikte klantenregister, noodzakelijk als `USE_KLANTINTERACTIES` op false staat of niet gedefinieerd is.
Meer informatie Bijvoorbeeld `https://klantenregister.mijngemeente.nl/klanten`
| +| `KLANTEN_CLIENT_ID` | ClientId voor de Klanten API van het gebruikte klantenregister, , noodzakelijk als `USE_KLANTINTERACTIES` op false staat of niet gedefinieerd is. | +| `KLANTEN_CLIENT_SECRET` | Secret voor de Klanten API
**(min. 32 karakters)** | +| `CONTACTMOMENTEN_BASE_URL` | URL van de Contactmomenten API
Meer informatie Bijvoorbeeld: `https://contactmomentenregister.mijngemeente.nl`
| +| `CONTACTMOMENTEN_API_CLIENT_ID` | ClientId voor de Contactmomenten API van het gebruikte Contactmomentenregister | +| `CONTACTMOMENTEN_API_KEY` | Key voor de Contactmomenten API
**(min. 32 karakters)** | +| `ZAAKSYSTEEM__0__BASE_URL` | URL van de ZGW API's
Meer informatie Bijvoorbeeld: `https://zaaksysteem.mijngemeente.nl`
| +| `ZAAKSYSTEEM__0__API_KEY` | API Key voor de ZGW API's
**(min. 32 karakters)** | +| `ZAAKSYSTEEM__0__API_CLIENT_ID` | ClientId voor de ZGW API's | +| `ZAAKSYSTEEM__0__DEEPLINK_URL` | Basisurl om te deeplinken naar een Zaak in het zaaksysteem (optioneel)
Meer informatie Bijvoorbeeld: `https://zaaksysteem.mijngemeente.nl/mp/zaak/`
Deze variabele **moet** altijd gebruikt worden **in combinatie met** `ZAAKSYSTEEM__0__DEEPLINK_PROPERTY`. Als deze variabelen beiden worden ingevuld, zal er in KISS een link in het zaakdetailscherm staan, waarmee de KCM de betreffende zaak direct in het zaaksysteem opent. LET OP: dit kan alleen bij zaaksystemen die een vaste url hebben voor zaakdetails, waarbij alleen één property van de zaak, bijv. het zaaknummer, áchter die URL geplaatst hoeft te worden.
| +| `ZAAKSYSTEEM__0__DEEPLINK_PROPERTY` | Property om naar een zaak te kunnen deeplinken (optioneel)
Meer informatie Deze variabele **moet** altijd gebruikt worden **in combinatie met** `ZAAKSYSTEEM__0__DEEPLINK_URL`. De waarde uit dit property van een specifieke zaak wordt achter `ZAAKSYSTEEM_DEEPLINK_URL` geplaatst om de link te laten werken. Bijvoorbeeld: `identificatie`
| +| `ZAAKSYSTEEM__0__NIETNATUURLIJKPERSOONIDENTIFIER` | Identifier voor 'niet natuurlijke personen'
(`rsin` of `kvkNummer`) voor dit zaaksysteem
Meer informatie Afhankelijk van de gebruikte bron (bijvoorbeeld Open Zaak of de e-Suite) kan je hiermee aangeven welk gegeven gebruikt wordt om zaken van een `niet natuurlijke persoon` op te zoeken in een zaaksysteem. Op dit moment kan je hiervoor het RSIN (`rsin`) of het KvK-nummer (`kvkNummer`) gebruiken. RSIN is de default: als deze variable leeg gelaten wordt of ontbreekt bij de installatie, zal `rsin` gebruikt worden. Als je de e-Suite als register gebruikt, moet je hier `kvkNummer` invullen. Let op, de spelling moet exact overeen komen.
| +| `AFDELINGEN_BASE_URL` | URL van de Objecten API voor afdelingen.
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `AFDELINGEN_OBJECT_TYPE_URL` | URL van het Objecttype Afdeling
Meer informatie Bijvoorbeeld: `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `AFDELINGEN_TOKEN` | Token voor Objecten API voor afdelingen | +| `GROEPEN_BASE_URL` | URL van de Objecten API voor groepen.
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `GROEPEN_OBJECT_TYPE_URL` | URL van het Objecttype Groep
Meer informatie Bijvoorbeeld: `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `GROEPEN_TOKEN` | Token van de Objecten API voor groepen | +| `INTERNE_TAAK_BASE_URL` | URL van de Objecten API voor Interne Taken
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `INTERNE_TAAK_OBJECT_TYPE_URL` | URL van het Objecttype Interne Taak
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `INTERNE_TAAK_TYPE_VERSION` | Versienummer van het Objecttype Interne Taak
Meer informatie Bijvoorbeeld `2`
KISS schrijft InterneTaken in het Objectenregister. Hierbij moet je altijd de versie van het objecttype meegeven. Omdat het per gemeente kan verschillen welke versie de meest recente is, moet je hier invullen welk versienummer KISS moet meegeven.
| +| `INTERNE_TAAK_TOKEN` | Token voor de Objecten API voor Interne Taken
**(Als deze variabele een waarde heeft, moeten `INTERNE_TAAK_CLIENT_SECRET` en `INTERNE_TAAK_CLIENT_ID` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| +| `INTERNE_TAAK_CLIENT_SECRET` | Client Secret voor de Interne Taken API
**(Als deze variabele een waarde heeft, moet `INTERNE_TAAK_TOKEN` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| +| `INTERNE_TAAK_CLIENT_ID` | Client ID voor de Interne Taken API
**(Als deze variabele een waarde heeft, moet `INTERNE_TAAK_TOKEN` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| +| `VAC_OBJECTEN_BASE_URL` | URL van de Objecten API voor VAC's
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `VAC_OBJECT_TYPE_URL` | URL van het Objecttype VAC
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `VAC_OBJECT_TYPE_VERSION` | Versienummer van het Objecttype VAC
Meer informatie Bijvoorbeeld `2`
KISS schrijft Vacs in het Objectenregister. Hierbij moet je altijd de versie van het objecttype meegeven. Omdat het per gemeente kan verschillen welke versie de meest recente is, moet je hier invullen welk versienummer KISS moet meegeven.
| +| `VAC_OBJECTEN_TOKEN` | Token voor de Objecten API voor VAC's
Meer informatie In het geval van Vacs identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`.
| +| `USE_VACS` | Deze variabele bepaalt of het navigatie-item voor het beheren van VAC's aanwezig is in de beheernavigatie.
Meer informatie Als deze variabele op `true` staat, is het Vacs-item zichtbaar en kunnen beheerders gebruikmaken van de functionaliteit. Als de variabele niet op true staat, of niet is ingesteld, zal het item niet aanwezig zijn in de beheernavigatie.
| +| `USE_MEDEWERKEREMAIL` | Deze variabele bepaalt of een contactverzoek voor een medewerker alléén op e-mailadres kan.
Meer informatie Als deze variabele op `true` staat, zal in het contactverzoek-formulier, onder de geselecteerde afdeling of groep, een veld staan om het emailadres van een medewerker in te voeren. Direct een contactverzoek voor een medewerker maken kan in deze situatie niet. Het veld e-mailadres is niet verplicht. Als de variabele niet op `true` staat, geen waarde heeft of afwezig is, heb je in KISS wel de mogelijkheid om een Contactverzoek voor een medewerker te maken, en kun je in KISS de medewerker uit een lijst kiezen op naam.
| + +#### KISS-Elastic-Sync +
Meer informatie KISS-Elastic-Sync is het component dat zorgt dat de gekoppelde bronnen die via Elasticsearch ontsloten worden in KISS, naar de juiste Indexen worden gepushed, met de benodigde gegevens hieraan toegevoegd. Onderstaande environment variabelen gaan over de bronnen die gekoppeld zijn aan de KISS-Elastic-Sync.
+ + +| Variabele | Uitleg | +| -------------------------------------| -------------------------------------------------------------------------------------------------------- | +| `ENTERPRISE_SEARCH_BASE_URL` | URL van de API voor de elastic instantie | +| `ENTERPRISE_SEARCH_PRIVATE_API_KEY` | Private API key voor Elastic | +| `MEDEWERKER_OBJECTEN_BASE_URL` | URL van de Objecten API voor medewerkers
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `MEDEWERKER_OBJECTEN_TOKEN` | Token voor de Objecten API voor medewerkers
**(Als deze variabele een waarde heeft, moeten MEDEWERKER_OBJECTEN_CLIENT_SECRET en MEDEWERKER_OBJECTEN_CLIENT_ID leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| +| `MEDEWERKER_OBJECTEN_CLIENT_ID` | Client ID voor de Objecten API voor medewerkers
**(Als deze variabele een waarde heeft, moet MEDEWERKER_OBJECTEN_TOKEN leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| +| `MEDEWERKER_OBJECTEN_CLIENT_SECRET` | Client Secret voor de Objecten API voor medewerkers
**(Als deze een waarde heeft, deze variabele MEDEWERKER_OBJECTEN_TOKEN leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| +| `MEDEWERKER_OBJECT_TYPE_URL` | URL van het Objecttype Medewerker
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `VAC_OBJECTEN_BASE_URL` | URL van de Objecten API voor VAC's
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `VAC_OBJECT_TYPE_URL` | URL van het Objecttype VAC
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| +| `VAC_OBJECTEN_TOKEN` | Token voor de Objecten API voor VAC's
Meer informatie In het geval van Vacs identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`.
| +| `SDG_BASE_URL` | URL van de API voor Kennisartikelen
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| +| `SDG_OBJECTEN_TOKEN` | Key voor de API voor Kennisartikelen | +| `SDG_OBJECT_TYPE_URL` | URL van het Objecttype Kennisartikel
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| + +## Installatie + +### Placeholders + +De yaml-voorbeeldbestanden staan [hier](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/blob/main/helm/kiss-frontend/kiss.template.yaml). + +### Uitvoeren + +De installatie kan uitgevoerd worden middels het PowerShell script. Handmatig uitvoeren kan ook. + +[install_kiss.ps1](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/scripts/install_kiss.ps1) + +**LET OP** +- Voordat een ingelogde gebruiker kan werken met KISS, moet deze gebruiker de juiste rol hebben in de gekoppelde Identity provider. Zie voor meer informatie het onderdeel [Configuratie van uw Identity Provider in de configuratie-handleiding](CONFIGURATIE.md#configuratie-van-uw-identity-provider). +- Om een betere indruk te krijgen van hoe KISS werkt, is het mogelijk om **voorbeeldata (demodata)** te laden. Zie hiervoor [de uitleg bij de Beheerhandleiding](MANUAL.md#kiss-beheer-vullen-met-voorbeelddata). + +#### KISS-Elastic-Sync +KISS-Elastic-Sync is het component dat zorgt voor het creëren van de benodigde engines in een Elasticsearch-installatie, zodat gekoppelde bronnen eenvoudig door KISS doorzoekbaar zijn. Het ondersteunt zowel websites als gestructureerde bronnen door respectievelijk een crawler en een index te gebruiken. + +Meer informatie over de KISS-Elastic-Sync tool en hoe deze te installeren, is te vinden op de volgende URL: +[KISS-Elastic-Sync](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/README.md) + +##### Cronjobs +Naast de sync tool zijn er ook cronjobs die ingesteld moeten worden voor het regelmatig synchroniseren van data. + +Meer informatie over de benodigde cronjobs en hoe deze in te stellen, is te vinden op de volgende URL: +[KISS-Elastic-Sync Cronjobs](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/deploy/README.md) From 04cc628bae5cc474151cdc26094725c3e3b66a71 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 21:33:44 +0100 Subject: [PATCH 14/30] move restored installation --- docs/{ => installation}/INSTALLATION.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{ => installation}/INSTALLATION.md (100%) diff --git a/docs/INSTALLATION.md b/docs/installation/INSTALLATION.md similarity index 100% rename from docs/INSTALLATION.md rename to docs/installation/INSTALLATION.md From c591bd88e3edd65fbc4ad78caa4226b6c841bc2d Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 21:34:37 +0100 Subject: [PATCH 15/30] rename installation --- docs/installation/{INSTALLATION.md => installatie.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/installation/{INSTALLATION.md => installatie.md} (100%) diff --git a/docs/installation/INSTALLATION.md b/docs/installation/installatie.md similarity index 100% rename from docs/installation/INSTALLATION.md rename to docs/installation/installatie.md From 4ea8e79b4550e392303ecd13302c69da610984fe Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Wed, 19 Feb 2025 21:35:19 +0100 Subject: [PATCH 16/30] replace content --- docs/installation/installatie.md | 217 +------------------------------ 1 file changed, 5 insertions(+), 212 deletions(-) diff --git a/docs/installation/installatie.md b/docs/installation/installatie.md index be631bd..acbc517 100644 --- a/docs/installation/installatie.md +++ b/docs/installation/installatie.md @@ -1,217 +1,10 @@ -# Klantinteractie Servicesysteem (KISS) Installatie Handleiding +# Installatie -## Inhoudsopgave - -- [Klantinteractie Servicesysteem (KISS) Installatie Handleiding](#klantinteractie-servicesysteem-kiss-installatie-handleiding) - - [Inhoudsopgave](#inhoudsopgave) - - [Inleiding](#inleiding) - - [Voorbereidingen](#voorbereidingen) - - [Domein](#domein) - - [Tools](#tools) - - [Haven](#haven) - - [Authenticatie](#authenticatie) - - [Configuratie: Environment Variabelen](#configuratie-environment-variabelen) - - [Authenticatie](#authenticatie-1) - - [Database](#database) - - [Organisatie RSIN](#organisatie-rsin) - - [Feedback op Kennisartikelen](#feedback-op-kennisartikelen) - - [Gekoppelde Bronnen](#gekoppelde-bronnen) - - [KISS-frontend](#kiss-frontend) - - [KISS-Elastic-Sync](#kiss-elastic-sync) - - [Installatie](#installatie) - - [Placeholders](#placeholders) - - [Uitvoeren](#uitvoeren) - - [KISS-Elastic-Sync](#kiss-elastic-sync-1) - - [KISS-Elastic-Sync-Cronjobs](#cronjobs) - ---- - -## Inleiding - -KISS draait in een Kubernetes cluster. Deze handleiding is gebaseerd op Azure Kubernetes, maar ondersteunt ook andere haven-compliant providers. De handleiding is bedoeld voor Kubernetes beheerders om KISS handmatig op een nieuw cluster te installeren. - -## Voorbereidingen - -### Domein - -Bij gebruik van Helm-Charts: zorg voor een domeinnaam met wild-card certificaat. Gebruik `.crt` en `.key` bestanden zoals hieronder: - -> `-----BEGIN CERTIFICATE-----`
-> inhoud public certificate
-> `-----END CERTIFICATE-----`
->
-> `-----BEGIN CERTIFICATE-----`
-> inhoud intermediate certificaten mits aanwezig
-> `-----END CERTIFICATE-----`
->
-> `-----BEGIN CERTIFICATE-----`
-> inhoud certificate authority certificate
-> `-----END CERTIFICATE-----` - -Het private certificate dient los als .key bestand opgeslagen te worden. - -### Tools - -Installeer de volgende tools: - -- [kubectl](https://kubernetes.io/docs/tasks/tools/) -- [Helm](https://helm.sh/docs/intro/install/) -- [Haven](https://haven.commonground.nl/techniek/compliancy-checker) -- [Powershell](https://learn.microsoft.com/en-us/powershell/) - -### Haven - -KISS kan op een haven-compliant cluster geïnstallleerd worden. Referentie-implementaties van haven-compliant clusters zijn te vinden op de [Haven](https://haven.commonground.nl/techniek/aan-de-slag) site. - -Bij het volgen van de [Azure](https://haven.commonground.nl/techniek/aan-de-slag/azure) referentie moet men rekening houden met de volgende extra zaken: - -- Minimaal 3 nodes -- High availability aanzetten -- Local logins met RBAC gebruiken, GEEN Azure Active Directory! - - -### Authenticatie - -De authenticatie van gebruikers binnen KISS gebeurt m.b.v. een OIDC koppeling met bijvoorbeeld Azure Active Directory. - -## Configuratie: Environment Variabelen - -Hieronder staan de benodigde environment variabelen per onderdeel van KISS. - -### Authenticatie - -| Variabele | Uitleg | -| ---------------------------------------- | --------------------------------------------------------- | -| `OIDC_AUTHORITY` | URL van de OpenID Connect Identity Provider | -| `OIDC_CLIENT_ID` | Voor toegang tot de OpenID Connect Identity Provider | -| `OIDC_CLIENT_SECRET` | Secret voor de OpenID Connect Identity Provider | -| `OIDC_MEDEWERKER_IDENTIFICATIE_CLAIM` | Identificatie van de medewerker in registers
(default waarde is `email`)
Meer informatie Bij het wegschrijven van gegevens naar bv. Open Klant of Open Zaak is een `medewerkerIdentificatie.identificatie` verplicht. Verschillende gemeenten gebruiken hier verschillende waardes voor. Bij een koppeling met bv. de e-Suite is het van belang dat hier de e-Suite gebruikersnaam in staat van de ingelogde KCM.
| -| `OIDC_MEDEWERKER_IDENTIFICATIE_TRUNCATE` | Optioneel afkappen van de claim
(bijv. `24`)
Meer informatie Binnen ZGW mag een `medewerkerIdentificatie.identificatie` niet langer zijn dan 24 karakters. Met deze variabele kun je ervoor zorgen dat de uiteindelijk waarde wordt afgekapt na 24 tekens.
| -| `MANAGEMENTINFORMATIE_API_KEY` | Secret dat KISS gebruikt om het JWT Token
te valideren bij het opvragen van
contactmomentdetails
Meer informatie Zie de [Handleiding beheer KISS, hoofdstuk
managementinformatie](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/MANUAL.md#management-informatie) voor informatie over
het gebruik van deze API.
| -| | | - -### Database - -| Variabele | Uitleg | -| ------------------ | ------------------------------------- | -| `POSTGRES_DB` | Naam van de database bij KISS | -| `POSTGRES_USER` | Gebruikersnaam voor toegang van KISS tot de DB | -| `POSTGRES_PASSWORD` | Wachtwoord van de postgresUser | -| | | - -### Organisatie RSIN - -| Variabele | Uitleg | -| ----------------- | ---------------------------------------------------------------- | -| `ORGANISATIE_IDS` | RSIN van de organisatie die de
Contactmomenten registreert
Meer informatie Verschillende ZGW APIs, waaronder de Klant en Contactmoment APIs, vragen om een identificatienummer, RSIN, van de eigen organisatie. Dit RSIN moet worden meegegeven bij registratie van specifieke objecten.
| -| | | - -### Feedback op Kennisartikelen -
Meer informatie Vanuit KISS kan een KCM feedback geven op een kennisartikel. Deze informatie wordt gemaild naar één centraal e-mailadres. Dit configureer je met onderstaande variabelen.
- -| Variabele | Uitleg | -| --------------------- | --------------------------------------- | -| `FEEDBACK_EMAIL_FROM` | Afzenderadres van de feedbackmail | -| `FEEDBACK_EMAIL_TO` | Adres waar de feedbackmail naartoe moet | -| `EMAIL_ENABLE_SSL` | Gebruik van SSL (true/false) | -| `EMAIL_HOST` | Adres van de mailserver | -| `EMAIL_PORT` | Poortnummer van de mailverbinding | -| `EMAIL_USERNAME` | Gebruikersnaam voor de mailserver | -| `EMAIL_PASSWORD` | Wachtwoord voor de mailserver | -| | | - -### Gekoppelde Bronnen - -Er zijn diverse API's die vanuit KISS bevraagd worden. Hieronder staan de environment variabelen per gekoppelde bron. -**Let op**: -1. Sommige API-keys en Secrets die KISS nodig heeft om externe registers te bevragen moeten **minimaal 32 karakters** lang zijn. -2. Voor variabelen met `__0__` als tussenvoegsel geldt dat er een lijst opgebouwd kan worden. Het eerste item van de lijst heeft `__0__` als tussenvoegsel, het tweede item `__1__`, en zo verder. - -
Meer informatie Er zijn diverse bronnen die vanuit KISS via API's bevraagd worden. Sommige worden alleen geraadpleegd, zoals de KvK-API en de API voor Haal Centraal BRP Personen bevragen, en de Objecten API voor het ophalen van Afdelingen, Groepen en Medewerkers. Andere registraties worden niet alleen geraadpleegd, maar er worden ook gegevens in weggeschreven. Dit zijn in ieder geval een Klanten- en Contactmomentenregister, zoals Open Klant, het Objecten Register zoals Open Objecten, en een Zaaksysteem (m.b.v. ZGW API's) zoals Open Zaak. - -Daarnaast zijn er bronnen die binnen KISS doorzocht moeten worden. - -- KISS gebruikt de Objecten API om Kennisartikelen (PDC-producten) mee op te halen, en naar Elastic te pushen. -- KISS gebruikt op dit moment de Objecten API om de Medewerkers in het Smoelenboek op te halen en naar Elastic te pushen. -- KISS gebruikt op dit moment de Objecten API om de Vraag Antwoord Combinaties (VAC) op te halen en naar Elastic te pushen.
- - -#### KISS-frontend - -| Variabele | Uitleg | -| --------------------------------- | -------------------------------------------------------------------------------------------- | -| `HAAL_CENTRAAL_BASE_URL` | URL van de Haal Centraal API
Meer informatie Bijvoorbeeld: `https://proefomgeving.haalcentraal.nl/haalcentraal/api`
| -| `HAAL_CENTRAAL_API_KEY` | Key voor de Haal Centraal API | -| `KVK_BASE_URL` | URL van de KvK-API
Meer informatie URL van de KvK-API om het Handelsregister te bevragen. Dit is het pad voorafgaand aan het versienummer, bijvoorbeeld `https://api.kvk.nl/test/api`
| -| `KVK_API_KEY` | Key voor de KvK-API | -| `ELASTIC_BASE_URL` | De URL voor Elasticsearch
Meer informatie Bijvoorbeeld: `https://kiss-es-http:9200`
| -| `ELASTIC_USERNAME` | Username om in te loggen op Elasticsearch
Meer informatie Dit kan de default root user `elastic` zijn, maar ook de username van een gebruiker die je zelf hebt aangemaakt.
| -| `ELASTIC_PASSWORD` | Wachtwoord voor de bovenstaande user
Meer informatie Als je gebruik maakt van [ECK](https://www.elastic.co/guide/en/cloud-on-k8s/2.8/k8s-overview.html), dan kun je het wachtwoord van de default user vinden, m.b.v. het commando `kubectl get secret kiss-es-elastic-user -o go-template='{{.data.elastic | base64decode}}'`
| -| `ENTERPRISE_SEARCH_BASE_URL` | URL van de API waarop KISS de elastic instantie kan bevragen
Meer informatie Bijvoorbeeld `https://kiss-ent-http:3002`
| -| `ENTERPRISE_SEARCH_PUBLIC_API_KEY` | Public API key voor Elastic API | -| `ENTERPRISE_SEARCH_PRIVATE_API_KEY` | Private API key voor Elastic API
Meer informatie De API key die nodig is om de `engine`s bij te werken
| -| `ENTERPRISE_SEARCH_ENGINE` | De naam van de `meta-engine` engine die KISS gebruikt. Dit moet zijn: `KISS-engine`
Meer informatie De KISS-Elastic-Sync maakt deze engine aan, als deze nog niet bestaat.
| -| `USE_KLANTINTERACTIES` | Deze variabele bepaalt of er gebruik wordt gemaakt van OpenKlant 2.0 (klantinteractieregister).
Meer informatie Als deze variabele op `true` staat, wordt OpenKlant 2.0 gebruikt. Hiervoor zijn de variabelen `KLANTINTERACTIES_BASE_URL` en `KLANTINTERACTIES_TOKEN` nodig. Standaard is deze waarde `false`, in dat geval worden de oude Contactmomenten API en Klanten API gebruikt, voor communicatie met de e-Suite. In dat geval zijn de variabelen `KLANTEN_BASE_URL`, `KLANTEN_CLIENT_ID` en `KLANTEN_CLIENT_SECRET` nodig.
| -| `KLANTINTERACTIES_BASE_URL` | URL van de Klantinteractie API van het gebruikte klantinteractieregister (bijvoorbeeld Open Klant 2)
Meer informatie Bijvoorbeeld `https://klantinteractieregister.mijngemeente.nl/klantinteracties`
| -| `KLANTINTERACTIES_TOKEN` | Token voor de Klantinteractie API van het gebruikte klantinteractieregister | -| `KLANTEN_BASE_URL` | URL van de Klanten API van het gebruikte klantenregister, noodzakelijk als `USE_KLANTINTERACTIES` op false staat of niet gedefinieerd is.
Meer informatie Bijvoorbeeld `https://klantenregister.mijngemeente.nl/klanten`
| -| `KLANTEN_CLIENT_ID` | ClientId voor de Klanten API van het gebruikte klantenregister, , noodzakelijk als `USE_KLANTINTERACTIES` op false staat of niet gedefinieerd is. | -| `KLANTEN_CLIENT_SECRET` | Secret voor de Klanten API
**(min. 32 karakters)** | -| `CONTACTMOMENTEN_BASE_URL` | URL van de Contactmomenten API
Meer informatie Bijvoorbeeld: `https://contactmomentenregister.mijngemeente.nl`
| -| `CONTACTMOMENTEN_API_CLIENT_ID` | ClientId voor de Contactmomenten API van het gebruikte Contactmomentenregister | -| `CONTACTMOMENTEN_API_KEY` | Key voor de Contactmomenten API
**(min. 32 karakters)** | -| `ZAAKSYSTEEM__0__BASE_URL` | URL van de ZGW API's
Meer informatie Bijvoorbeeld: `https://zaaksysteem.mijngemeente.nl`
| -| `ZAAKSYSTEEM__0__API_KEY` | API Key voor de ZGW API's
**(min. 32 karakters)** | -| `ZAAKSYSTEEM__0__API_CLIENT_ID` | ClientId voor de ZGW API's | -| `ZAAKSYSTEEM__0__DEEPLINK_URL` | Basisurl om te deeplinken naar een Zaak in het zaaksysteem (optioneel)
Meer informatie Bijvoorbeeld: `https://zaaksysteem.mijngemeente.nl/mp/zaak/`
Deze variabele **moet** altijd gebruikt worden **in combinatie met** `ZAAKSYSTEEM__0__DEEPLINK_PROPERTY`. Als deze variabelen beiden worden ingevuld, zal er in KISS een link in het zaakdetailscherm staan, waarmee de KCM de betreffende zaak direct in het zaaksysteem opent. LET OP: dit kan alleen bij zaaksystemen die een vaste url hebben voor zaakdetails, waarbij alleen één property van de zaak, bijv. het zaaknummer, áchter die URL geplaatst hoeft te worden.
| -| `ZAAKSYSTEEM__0__DEEPLINK_PROPERTY` | Property om naar een zaak te kunnen deeplinken (optioneel)
Meer informatie Deze variabele **moet** altijd gebruikt worden **in combinatie met** `ZAAKSYSTEEM__0__DEEPLINK_URL`. De waarde uit dit property van een specifieke zaak wordt achter `ZAAKSYSTEEM_DEEPLINK_URL` geplaatst om de link te laten werken. Bijvoorbeeld: `identificatie`
| -| `ZAAKSYSTEEM__0__NIETNATUURLIJKPERSOONIDENTIFIER` | Identifier voor 'niet natuurlijke personen'
(`rsin` of `kvkNummer`) voor dit zaaksysteem
Meer informatie Afhankelijk van de gebruikte bron (bijvoorbeeld Open Zaak of de e-Suite) kan je hiermee aangeven welk gegeven gebruikt wordt om zaken van een `niet natuurlijke persoon` op te zoeken in een zaaksysteem. Op dit moment kan je hiervoor het RSIN (`rsin`) of het KvK-nummer (`kvkNummer`) gebruiken. RSIN is de default: als deze variable leeg gelaten wordt of ontbreekt bij de installatie, zal `rsin` gebruikt worden. Als je de e-Suite als register gebruikt, moet je hier `kvkNummer` invullen. Let op, de spelling moet exact overeen komen.
| -| `AFDELINGEN_BASE_URL` | URL van de Objecten API voor afdelingen.
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `AFDELINGEN_OBJECT_TYPE_URL` | URL van het Objecttype Afdeling
Meer informatie Bijvoorbeeld: `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `AFDELINGEN_TOKEN` | Token voor Objecten API voor afdelingen | -| `GROEPEN_BASE_URL` | URL van de Objecten API voor groepen.
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `GROEPEN_OBJECT_TYPE_URL` | URL van het Objecttype Groep
Meer informatie Bijvoorbeeld: `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `GROEPEN_TOKEN` | Token van de Objecten API voor groepen | -| `INTERNE_TAAK_BASE_URL` | URL van de Objecten API voor Interne Taken
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `INTERNE_TAAK_OBJECT_TYPE_URL` | URL van het Objecttype Interne Taak
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `INTERNE_TAAK_TYPE_VERSION` | Versienummer van het Objecttype Interne Taak
Meer informatie Bijvoorbeeld `2`
KISS schrijft InterneTaken in het Objectenregister. Hierbij moet je altijd de versie van het objecttype meegeven. Omdat het per gemeente kan verschillen welke versie de meest recente is, moet je hier invullen welk versienummer KISS moet meegeven.
| -| `INTERNE_TAAK_TOKEN` | Token voor de Objecten API voor Interne Taken
**(Als deze variabele een waarde heeft, moeten `INTERNE_TAAK_CLIENT_SECRET` en `INTERNE_TAAK_CLIENT_ID` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| -| `INTERNE_TAAK_CLIENT_SECRET` | Client Secret voor de Interne Taken API
**(Als deze variabele een waarde heeft, moet `INTERNE_TAAK_TOKEN` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| -| `INTERNE_TAAK_CLIENT_ID` | Client ID voor de Interne Taken API
**(Als deze variabele een waarde heeft, moet `INTERNE_TAAK_TOKEN` leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** let op: alle 3 de variabelen moeten wel aanwezig zijn, je kunt ze niet weglaten.
| -| `VAC_OBJECTEN_BASE_URL` | URL van de Objecten API voor VAC's
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `VAC_OBJECT_TYPE_URL` | URL van het Objecttype VAC
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `VAC_OBJECT_TYPE_VERSION` | Versienummer van het Objecttype VAC
Meer informatie Bijvoorbeeld `2`
KISS schrijft Vacs in het Objectenregister. Hierbij moet je altijd de versie van het objecttype meegeven. Omdat het per gemeente kan verschillen welke versie de meest recente is, moet je hier invullen welk versienummer KISS moet meegeven.
| -| `VAC_OBJECTEN_TOKEN` | Token voor de Objecten API voor VAC's
Meer informatie In het geval van Vacs identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`.
| -| `USE_VACS` | Deze variabele bepaalt of het navigatie-item voor het beheren van VAC's aanwezig is in de beheernavigatie.
Meer informatie Als deze variabele op `true` staat, is het Vacs-item zichtbaar en kunnen beheerders gebruikmaken van de functionaliteit. Als de variabele niet op true staat, of niet is ingesteld, zal het item niet aanwezig zijn in de beheernavigatie.
| -| `USE_MEDEWERKEREMAIL` | Deze variabele bepaalt of een contactverzoek voor een medewerker alléén op e-mailadres kan.
Meer informatie Als deze variabele op `true` staat, zal in het contactverzoek-formulier, onder de geselecteerde afdeling of groep, een veld staan om het emailadres van een medewerker in te voeren. Direct een contactverzoek voor een medewerker maken kan in deze situatie niet. Het veld e-mailadres is niet verplicht. Als de variabele niet op `true` staat, geen waarde heeft of afwezig is, heb je in KISS wel de mogelijkheid om een Contactverzoek voor een medewerker te maken, en kun je in KISS de medewerker uit een lijst kiezen op naam.
| - -#### KISS-Elastic-Sync -
Meer informatie KISS-Elastic-Sync is het component dat zorgt dat de gekoppelde bronnen die via Elasticsearch ontsloten worden in KISS, naar de juiste Indexen worden gepushed, met de benodigde gegevens hieraan toegevoegd. Onderstaande environment variabelen gaan over de bronnen die gekoppeld zijn aan de KISS-Elastic-Sync.
- - -| Variabele | Uitleg | -| -------------------------------------| -------------------------------------------------------------------------------------------------------- | -| `ENTERPRISE_SEARCH_BASE_URL` | URL van de API voor de elastic instantie | -| `ENTERPRISE_SEARCH_PRIVATE_API_KEY` | Private API key voor Elastic | -| `MEDEWERKER_OBJECTEN_BASE_URL` | URL van de Objecten API voor medewerkers
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `MEDEWERKER_OBJECTEN_TOKEN` | Token voor de Objecten API voor medewerkers
**(Als deze variabele een waarde heeft, moeten MEDEWERKER_OBJECTEN_CLIENT_SECRET en MEDEWERKER_OBJECTEN_CLIENT_ID leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| -| `MEDEWERKER_OBJECTEN_CLIENT_ID` | Client ID voor de Objecten API voor medewerkers
**(Als deze variabele een waarde heeft, moet MEDEWERKER_OBJECTEN_TOKEN leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| -| `MEDEWERKER_OBJECTEN_CLIENT_SECRET` | Client Secret voor de Objecten API voor medewerkers
**(Als deze een waarde heeft, deze variabele MEDEWERKER_OBJECTEN_TOKEN leeg blijven)**
Meer informatie In de meeste gevallen identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een `client secret` en een `client id`. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** Let op: alle 3 de variabelen moeten wel aanwezig zijn.
| -| `MEDEWERKER_OBJECT_TYPE_URL` | URL van het Objecttype Medewerker
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `VAC_OBJECTEN_BASE_URL` | URL van de Objecten API voor VAC's
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `VAC_OBJECT_TYPE_URL` | URL van het Objecttype VAC
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| -| `VAC_OBJECTEN_TOKEN` | Token voor de Objecten API voor VAC's
Meer informatie In het geval van Vacs identificeert KISS zich bij een Objectenregistratie m.b.v. een `TOKEN`.
| -| `SDG_BASE_URL` | URL van de API voor Kennisartikelen
Meer informatie Bijvoorbeeld: `https://objectenregister.mijngemeente.nl`
| -| `SDG_OBJECTEN_TOKEN` | Key voor de API voor Kennisartikelen | -| `SDG_OBJECT_TYPE_URL` | URL van het Objecttype Kennisartikel
Meer informatie Bijvoorbeeld `https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399`
| - -## Installatie - -### Placeholders +## Placeholders De yaml-voorbeeldbestanden staan [hier](https://github.com/Klantinteractie-Servicesysteem/KISS-frontend/blob/main/helm/kiss-frontend/kiss.template.yaml). -### Uitvoeren +## Uitvoeren De installatie kan uitgevoerd worden middels het PowerShell script. Handmatig uitvoeren kan ook. @@ -221,13 +14,13 @@ De installatie kan uitgevoerd worden middels het PowerShell script. Handmatig ui - Voordat een ingelogde gebruiker kan werken met KISS, moet deze gebruiker de juiste rol hebben in de gekoppelde Identity provider. Zie voor meer informatie het onderdeel [Configuratie van uw Identity Provider in de configuratie-handleiding](CONFIGURATIE.md#configuratie-van-uw-identity-provider). - Om een betere indruk te krijgen van hoe KISS werkt, is het mogelijk om **voorbeeldata (demodata)** te laden. Zie hiervoor [de uitleg bij de Beheerhandleiding](MANUAL.md#kiss-beheer-vullen-met-voorbeelddata). -#### KISS-Elastic-Sync +### KISS-Elastic-Sync KISS-Elastic-Sync is het component dat zorgt voor het creëren van de benodigde engines in een Elasticsearch-installatie, zodat gekoppelde bronnen eenvoudig door KISS doorzoekbaar zijn. Het ondersteunt zowel websites als gestructureerde bronnen door respectievelijk een crawler en een index te gebruiken. Meer informatie over de KISS-Elastic-Sync tool en hoe deze te installeren, is te vinden op de volgende URL: [KISS-Elastic-Sync](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/README.md) -##### Cronjobs +#### Cronjobs Naast de sync tool zijn er ook cronjobs die ingesteld moeten worden voor het regelmatig synchroniseren van data. Meer informatie over de benodigde cronjobs en hoe deze in te stellen, is te vinden op de volgende URL: From 68bc211461f4696ff0bb7d9ed4de3fa166259b0f Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Thu, 20 Feb 2025 09:00:30 +0100 Subject: [PATCH 17/30] move and rename manualmd --- docs/{MANUAL.md => manual/nieuws.md} | 816 +++++++++++++-------------- 1 file changed, 408 insertions(+), 408 deletions(-) rename docs/{MANUAL.md => manual/nieuws.md} (98%) diff --git a/docs/MANUAL.md b/docs/manual/nieuws.md similarity index 98% rename from docs/MANUAL.md rename to docs/manual/nieuws.md index 924729f..489b68e 100644 --- a/docs/MANUAL.md +++ b/docs/manual/nieuws.md @@ -1,408 +1,408 @@ -# Handleiding beheer KISS - -Als beheerder van KISS kan je de volgende zaken beheren: -- Nieuws en werkinstructies -- Skills -- Links -- Gespreksresultaten -- Formulier contactverzoeken -- Kanalen - -Per onderwerp leggen wij uit wat de mogelijkheden zijn en hoe je de werkzaamheden uitvoert. Om deze taken te kunnen uitvoeren moet je de rol `Redacteur` hebben (zie ook [Configuratie](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/CONFIGURATIE.md)). - -### KISS beheer vullen met voorbeelddata -Als je KISS voor het eerst hebt geïnstalleerd, en er bij Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten nog geen items zijn toegevoegd, is het mogelijk om eenvoudig voorbeelddata voor deze onderdelen te laden. Die doe je m.b.v. de knop op de startpagina. Met een druk op die knop zal de database met voorbeelddata worden gevuld voor Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten. Zodra de voorbeelddata is geladen, verdwijnt de optie/knop om (nogmaals) te vullen. - -#### Let op -De optie is alléén beschikbaar als de lijsten van Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten echt leeg zijn. Een beheerder kan deze lijsten handmatig schonen, zodat ze weer leeg zijn. Skills vormen hierop een uitzondering: deze worden niet daadwerkelijk weggegooid, maar alleen verborgen voor de gebruiker. Dit om te voorkomen dat een Skill die al gekoppeld is aan een bericht, daarvan zal verdwijnen. Dit betekent dat verwijderde Skills nog onzichtbaar aanwezig zijn in de database, waardoor er geen initiële dataset geladen kan worden. Zodra je ee Skill hebt toegevoegd, is het dus niet meer mogelijk om voorbeelddata te laden. - - -## Nieuws en werkinstructies -Nieuwsberichten en werkinstructies zijn berichten die van belang kunnen zijn voor de klantcontactmedewerkers. Deze berichten komen voor de klantcontactmedewerkers op hun homepagina te staan. - -Op onderstaande afbeelding is de overzichtspagina van het beheer van nieuwsberichten en werkinstructies te zien. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-overzicht.jpg.jpg) - - -### Nieuwsbericht of werkinstructie toevoegen -Voeg een nieuwsbericht of werkinstructie toe door rechts bovenaan op de "Toevoegen" te drukken. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-toevoegen.jpg) - -Vervolgens kom je op onderstaand scherm. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-toevoegen-detail.jpg) - -Hieronder wordt elk invoerveld toegelicht. - - -**Het type:** Met het type kan je aangeven of je bericht een werkinstructie of nieuwsbericht is. - -**De titel:** Dit is de titel van je bericht. - -**Inhoud:** Hier plaats je de inhoud van je bericht. - -**Belangrijk:** Hiermee kan je aangeven of een bericht belangrijk is of niet. Handig voor dringende zaken bijvoorbeeld. Belangrijke berichten komen voor de klantcontactmedewerkers altijd bovenaan te staan, zodat de klantcontactmedewerker deze meteen zal zien staan. Ook vallen belangrijke berichten extra op. - -**Publicatiedatum:** Bij de publicatiedatum kan je de gewenste datum en tijd instellen waarop een bericht gepubliceerd moet worden. Dit kan handig zijn voor als je een bericht alvast wil schrijven, maar nog niet wil publiceren. Het bericht wordt dan automatisch aan de klantcontactmedewerkers gepubliceerd op de geselecteerde datum en tijd. - -**Publicatie-einddatum:** Dit is de einddatum van je bericht. Bij nieuwe berichten staat dit veld standaard ingevuld met een datum over één jaar, maar dit kan je aanpassen. Na deze datum zal het bericht verdwijnen uit het overzicht van de klantcontactmedewerkers. In de beheertabel blijft het bericht wel staan. - -**Skills:** Hiermee kan je het aangeven of jouw bericht bij een specifieke skill hoort, en zoja: welke. Je kan meerdere skills tegelijk selecteren. Dus als je bericht relevant is voor meerdere skills, kun je dat aangeven. Klantcontactmedewerkers kunnen op hun startpagina de berichten filteren op skills. Ze kunnen meerdere skills aanvinken, dan worden alle berichten getoond die bij één of meerdere skills horen. Als je een bericht niet aan een skill koppelt, is het bericht ook alleen zichtbaar voor de klantcontactmedewerkers die geen filter aan hebben staan. - - -### Nieuwsbericht of werkinstructie wijzigen -Een nieuwsbericht of werkinstructie kan je wijzigen door op het pijltje te klikken dat rechts in de tabel te zien is. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-wijzigen.jpg) - - -Vervolgens kom je op onderstaand scherm. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-wijzigen-detail.jpg) - - -Hieronder wordt elk invoerveld toegelicht. - -**Het type:** Met het type kan je aangeven of je bericht een werkinstructie of nieuwsbericht is. - -**De titel:** Dit is de titel van je bericht. - -**Inhoud:** Hier plaats je de inhoud van je bericht. - -**Belangrijk:** Hiermee kan je aangeven of een bericht belangrijk is of niet. Handig voor dringende zaken bijvoorbeeld. Belangrijke berichten komen voor de klantcontactmedewerkers altijd bovenaan te staan, zodat de klantcontactmedewerker deze meteen zal zien staan. Ook vallen belangrijke berichten extra op. - -**Publicatiedatum:** Bij de publicatiedatum kan je de gewenste datum en tijd instellen waarop een bericht gepubliceerd moet worden. Dit kan handig zijn voor als je een bericht alvast wil schrijven, maar nog niet wil publiceren. Het bericht wordt dan automatisch aan de klantcontactmedewerkers gepubliceerd op de geselecteerde datum en tijd. - -**Publicatie-einddatum:** Dit is de einddatum van je bericht. Na deze datum zal het bericht verdwijnen uit het overzicht van de klantcontactmedewerkers. In de beheertabel blijft het bericht wel staan. - -**Skills:** Hiermee kan je het aangeven of jouw bericht bij een specifieke skill hoort, en zoja: welke. Je kan meerdere skills tegelijk selecteren. Dus als je bericht relevant is voor meerdere skills, kun je dat aangeven. Klantcontactmedewerkers kunnen op hun startpagina de berichten filteren op skills. Ze kunnen meerdere skills aanvinken, dan worden alle berichten getoond die bij één of meerdere skills horen. Als je een bericht niet aan een skill koppelt, is het bericht ook alleen zichtbaar voor de klantcontactmedewerkers die geen filter aan hebben staan. - - - - -### Nieuwsbericht of werkinstructie verwijderen -Een nieuwsbericht of werkinstructie kan je verwijderen door op het prullenbak icoontje te klikken dat rechts in de tabel te zien is. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-verwijderen.jpg) - - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit bericht wilt verwijderen?". Hierbij klik je op 'ok'. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-verwijderen-popup.jpg) - -## Skills -Op de pagina 'Skills' kan je de skills beheren. Skills kunnen bijvoorbeeld de verschillende afdelingen binnen het klantcontactcentrum zijn, zoals 'burgerzaken' of 'werk en inkomen'. - -De skills die je hier aanmaakt kunnen vervolgens als filter gebruikt worden bij de nieuwsberichten en werkinstructies. - -Het kan zijn dat jouw gemeente niet werkt met skills. In dat geval hoef je hier niets te doen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-overzicht.jpg) - -### Skill toevoegen -Een skill voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-toevoegen.jpg) - -Vervolgens kom je op onderstaand scherm. Hier kan je de naam van de skill invullen. Druk op 'Opslaan' om de skill toe te voegen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-toevoegen-detail.jpg) - - -### Skill wijzigen -Een skill wijzig je door op de naam van de skill te klikken. - -![inage](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-wijzigen.jpg) - - -Vervolgens kom je op onderstaand scherm. Hier kan je de naam van de skill wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. Deze wijziging is meteen zichtbaar bij alle berichten waar deze skill aan is gekoppeld, en in het filtermenu. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-wijzigen-detail.jpg) - -### Skill verwijderen -Een skill kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van de skill staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-verwijderen.jpg) - - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit bericht wilt verwijderen?". Hierbij klik je op 'ok'. De skill verdwijnt uit het filtermenu en ook bij alle berichten waar het aan gekoppeld was. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-verwijderen-popup.jpg) - - -## Links -Op de pagina 'Links' kan je de lijst met veelgebruikte links beheren. Hier kan je alle links neerzetten die voor jouw klantcontactmedewerkers handig zijn om altijd snel bij de hand te kunnen hebben. Denk bijvoorbeeld aan links naar bepaalde systemen of formulieren. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-overzicht.jpg) - -### Links toevoegen -Een link voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-toevoegen.jpg) - -Vervolgens kom je op onderstaand scherm. Hier kan je de titel, URL en de categorie van de link toevoegen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-toevoegen-detail.jpg) - -**Titel:** De naam waarmee de link in de lijst komt te staan. - -**Url:** De link naar de website. Een geldige URL begint altijd met https:// - -**Categorie:** De categorie waarin de link hoort. Als de link bij een al bestaande categorie hoort, typ je de naam van die categorie in. zodra je begint met typen, verschijnen de categorieën die beginnen met de letters die je typt. Je kunt dan snel de zelfde categorie kiezen. -Als je een andere categorie typt, wordt er automatisch een nieuwe categorie aangemaakt waar deze link onder valt. - -Druk op 'Opslaan' om de link toe te voegen. - - -### Links wijzigen -Een link wijzig je door op de naam van de link te klikken. - -![9mage](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-wijzigen.jpg) - - -Vervolgens kom je op onderstaand scherm. Hier kan je de link wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-wijzigen-detail.jpg) - - -**Titel:** De naam waarmee de link in de lijst komt te staan. - -**Url:** De link naar de website. - -**Categorie:** De categorie waarin de link hoort. Als de link bij een al bestaande categorie hoort, typ je de naam van die categorie in. zodra je begint met typen, verschijnen de categorieën die beginnen met de letters die je typt. Je kunt dan snel de zelfde categorie kiezen. -Als je een andere categorie typt, wordt er automatisch een nieuwe categorie aangemaakt waar deze link onder valt. - -### Links verwijderen -Een link kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van de link staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-verwijderen.jpg) - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u deze link wilt verwijderen?". Hierbij klik je op 'ok'. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-verwijderen-popup.jpg) - -## Gespreksresultaten -Op de pagina 'Gespreksresultaten' kan je de lijst met gespreksresultaten beheren. Met deze gespreksresultaten kunnen klantcontactmedewerkers aan het einde van hun contactmoment aangeven wat er met het gesprek is gebeurd, bijvoorbeeld zelfstandig afgehandeld of doorverbonden. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer.jpg) - -### Gespreksresultaat toevoegen -Een gespreksresultaat voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-toevoegen.jpg) - -Vervolgens kom je op onderstaand scherm. Hier kan je de naam van het gespreksresultaat invullen. Druk op 'Opslaan' om het gespreksesultaat toe te voegen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-toevoegen-detail.jpg) - - -### Gespreksresultaat wijzigen -Een gespreksresultaat wijzig je door op de naam van het gespreksresultaat te klikken. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-wijzigen.jpg) - -Vervolgens kom je op onderstaand scherm. Hier kan je de naam van het gespreksresultaat wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-wijzigen-detail.jpg) - -### Gespreksresultaat verwijderen -Een gespreksresultaat kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van het gespreksresultaat staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-verwijderen.jpg) - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit gespreksresultaat wilt verwijderen?". Hierbij klik je op 'ok' - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-verwijderen-popup.jpg) - - -## Formulieren contactverzoeken voor afdelingen en groepen -Bij ‘Formulieren contactverzoek afdelingen’ en ‘Formulieren contactverzoek groepen’ kan een beheerder van KISS formuliertjes aanmaken, die kunnen worden gebruikt in Contactverzoeken voor afdelingen en groepen. Het zijn eenvoudige formuliertjes, die een aantal extra vragen bevatten, waarmee je de KCM ondersteunt om al zoveel mogelijk relevante informatie mee te geven met het Contactverzoek. Dit zijn dus aanvullende vragen, op de vaste Contactverzoek-velden. - -Met de Vaste Contactverzoek velden geeft een KCM aan: - -1. Voor wie het Contactverzoek is: een afdeling, een groep of een medewerker -2. Een omschrijving waarover het gaat: dit is een toelichtingenveld waar informatie in staat, die alléén voor de collega is. -3. Met wie men contact moet opnemen: naam en contactgegevens van degene die teruggebeld (of teruggemaild, etc.) moet worden. - -Met een Contactverzoekformuliertje (of Vragenset) kan een KCM door een onderwerp te kiezen meer vragen stellen aan de klant, en zo een completer Contactverzoek invullen. Bijvoorbeeld: gaat een contactverzoek over een Parkeerbon? Dan is het handig om het nummer van de parkeerbon ook mee te geven. De klant voor wie het Contactverzoek wordt gemaakt, heeft dat meestal al bij de hand als hij contact opneemt met de gemeente. - -Bij beheer kun je deze formuliertjes (vragensets) aanmaken en beheren. -Hieronder volgt de handleiding voor het beheren van formulieren voor contactverzoeken voor afdelingen. Het beheren van van formulieren voor contactverzoeken voor groepen werkt op precies dezelfde manier. - -In het overzicht zie je de titel van het Contactverzoek, en de afdeling voor wie dit contactverzoek zou zijn. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-01.png) - -### Formulier toevoegen -Voeg een nieuw formulier toe door rechts bovenaan op de "Toevoegen" te drukken. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-02.png) - -Je komt op onderstaand scherm - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-03.png) - -In dit scherm moet je de Titel van het formulier opgeven. Deze titel beschrijft het onderwerp van het contactverzoek. Bijvoorbeeld: WMO, of Vraag voor Werk en inkomen. -Daaronder selecteer je de afdeling die bij deze contactverzoeken hoort. Deze lijst afdelingen, is dezelfde lijst afdelingen die een KCM gebruikt om aan te geven welke afdeling een Contactverzoek moet oppakken. - -Om een vraag toe te voegen, kies je eerst het vraagtype. Er zijn vier soorten vraagtypes: - -| Vraagtype | Uitleg | Voorbeeld | -|---|---|---| -| Open vraag kort | Invoerveld over één regel | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-open-kort.png) | -| Open vraag lang | Invoerveld over meerdere regels | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-open-lang.png) | -| Dropdown | Keuzelijst, waarin de KCM
maar één optie kan kiezen | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-dropdown.png) | -| Checkbox | Keuzelijst waarin de KCM
één of meer opties kan kiezen | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-checkbox.png) | - -Door in het veld Vraag toevoegen te klikken, klapt er een keuzelijst uit. Door één van de vraagtypes te kiezen, wordt er een vraag van dat vraagtype toegevoegd. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-04.png) - -- Voor alle vraagtypes geldt dat je de vraagtekst moet invullen. Dit is de tekst die in het uiteindelijke formulier boven het invoerveld komt te staan. -- Voor de Dropdown en de Checkbox moet je daarnaast óók minimaal twee antwoordopties opgeven. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-05.png) - -Met de knop Antwoordoptie Toevoegen kun je nog een optie toevoegen. De antwoordopties komen in het formulier in dezelfde volgorde waarin je ze bij aanmaken invoert. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-06.png) - -Als je alle vragen hebt ingesteld, klik je op Opslaan om het formulier op te slaan. Het formulier is meteen zichtbaar voor de KCM bij het aanmaken van een Contactverzoek. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-07.png) - -### Formulier wijzigen -Je kunt een formuliertje wijzigen door op het pijltje te klikken dat rechts in de tabel te zien is. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-08.png) - -Je komt in bewerkscherm van het formulier. Hier kun je bestaande vraagteksten wijzigen, de tekst van antwoord opties wijzigen en nieuwe vragen toevoegen. Ook kun je vragen of antwoord opties verwijderen. -Als je bijvoorbeeld de volgorde van antwoordopties in een meerkeuzevraag (dropdown of checkbox) wilt wijzigen, kun je de bestaande tekstjes verplaatsen. - - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-09.png) - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-10.png) - -Een vraag verwijder je door met de muis náást de vraag op het prullenbakje te klikken. Deze verschijnt als je met je muis achter het veld gaat staan. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-11.png) - -Een antwoordoptie verwijder je weer, door met de muist náást de antwoordoptie op het prullenbakje te klikken. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-12.png) - -Sla je je wijzigingen op met de Opslaan knop onderaan het formulier. Je wijzigingen zijn meteen zichtbaar, voor de KCM die een nieuw contactverzoek gaat aanmaken. Als een KCM al bezig was om met dat formulier een Contactverzoek te maken, kan die dat nog wel afmaken. - -### Formulier verwijderen -Je kunt een formulier verwijderen door op het prullenbak icoontje te klikken dat rechts in de tabel te zien is. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-13.png) - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit contactformulier wilt verwijderen?". Hierbij klik je op 'ok' om het verwijderen te bevestigen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-14.png) - -Het formulier is niet meer beschikbaar voor de KCM die een nieuw Contactverzoek gaat maken. Als een KCM al bezig was om met dat formulier een Contactverzoek te maken, kan die dat nog wel afmaken. - -## Kanalen -Op de pagina 'kanalen' kan je de lijst met kanalen beheren. Met deze kanalen kunnen klantcontactmedewerkers aan het einde van hun contactmoment aangeven via welk kanaal het contact heeft plaatsgevonden, bijvoorbeeld telefonisch of via e-mail. - -KISS hanteert een standaardlijst Kanalen, waaruit je kunt kiezen bij het registreren van een Contactmoment. Als je zelf geen kanalen toevoegt of alle kanalen verwijdert, dan zal KISS automatisch deze standaardlijst gebruiken. Deze lijst bevat de volgende kanalen: - -- Telefoon -- E-mail -- Contactformulier -- Twitter -- Facebook -- LinkedIn -- Live chat -- Instagram -- WhatsApp - - -### Kanalen toevoegen, wijzigen en verwijderen -Het toevoegen, wijzigen of verwijderen van kanalen gaat op een gelijksoortige manier als het toevoegen, wijzigen of verwijderen van Skills of gespreksresultaten. - -Let op: als je KISS gebruikt in combinatie met een bronregister, waarin ook kanalen aanwezig zijn (geconfigureerd of een vaste lijst kanalen), let dan goed op of het van belang is dat de schrijfwijze van een kanaal in KISS exact moet overeenkomen met kanaal in het bronregister. In dat geval moet je ook letten op hoofdletters, kleine, spaties en streepjes. - -## Vacs -Op de pagina 'Vacs' kan je Vraag-Antwoord-Combinaties beheren die zijn opgeslagen in het bij de KISS-installatie geconfigureerde Objectenregister. De lijst op de Vac-overzichtspagina toont alle Vacs. Door middel van de toetsenbord combinatie `Ctrl + f` kun je in de lijst zoeken naar de vraag die bij de Vraag-Antwoord-Combinatie hoort. - -#### Let op -Deze optie is alleen beschikbaar, als deze is aangezet bij de installatie/configuratie van KISS. Dit gebeurt m.b.v. een Environment Variabele. Zie ook [de installatiehandleiding](INSTALLATION.md#kiss-frontend), bij USE_VACS - -### Vacs toevoegen, wijzigen en verwijderen -Het toevoegen, wijzigen of verwijderen van Vacs gaat op een gelijksoortige manier als het toevoegen, wijzigen of verwijderen van Skills of gespreksresultaten. - -## Zoeken in bronnen -Binnen KISS kan een Klantcontactmedewerker zoeken in verschillende bronnen. KISS ondersteund op dit moment de volgende bronnen: de gemeentelijke website, in het smoelenboek van de gemeente, kennisartikelen in een Product-format en in Vraag-AntwoordCombinaties (VAC's). Het koppelen van deze bronnen moet gedaan worden door een technisch beheerder, in het kubernetescluster. Als de standaard installatieprocedure gevolgd is, draait er elk uur een taak (job) waardoor de bronnen worden gesyncrhoniseerd in de zoekindex. Bij onverwachte resultaten of foutmeldingen kan je de beheerder van het kubernetescluster vragen om de logging in te zien van de laatste synchronisatiepoging (job) van de [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync). Daarin is terug te vinden hoe de synchronisatiepoging is verlopen. - -## Managementinformatie -Bij het opslaan van Contactmomenten worden enkele gegevens, die geen plek hebben in de standaarden rondom Klantinteracties, opgeslagen binnen KISS zelf. (zie ook het [onderdeel Contactmomentdetails in Decision Record](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/DECISION-RECORD.md#contactmomentdetails)). Deze gegevens leveren managementinformatie over de werkzaamheden van het KCC. - -Binnen KISS is een API endpoint beschikbaar waarmee deze gegevens opgevraagd kunnen worden. Dit endpoint is benaderbaar op: `https://www.kissbijdegemeente.nl/api/contactmomentendetails`. - -### Authenticatie - -De Contactmomentendetails API is beveiligd en vereist een JWT Bearer Token voor toegang. Dit token wordt gegenereerd op basis van een geheime sleutel (secret) die door KISS wordt verstrekt aan de externe systemen. Dit secret is configureerbaar via de environment variabele `MANAGEMENTINFORMATIE_API_KEY` (zie installatiehandleiding) - -#### Structuur van de JWT - -De JWT bestaat uit drie delen, gescheiden door punten: - -1. **Header**: Bevat informatie over het algoritme dat gebruikt wordt om het token te ondertekenen, in dit geval HS256. - ```json - { - "alg": "HS256", - "typ": "JWT" - } - ``` - -2. **Payload**: De gegevens van de gebruiker of het systeem dat toegang probeert te verkrijgen. De payload bevat het `iat` (issued at) veld met de timestamp van het moment waarop het token is aangemaakt, en het `exp` (expiration) veld om de geldigheidsduur van het token te beperken. - - ```json - { - "iat": 1728580531, - "exp": 1728666931 - } - ``` - - - `iat`: Tijdstip van aanmaak van het token (in UNIX-timestamp). - - `exp`: Verloopdatum van het token (in UNIX-timestamp), na welke het token niet meer geldig is. - -3. **Signature**: De handtekening, gegenereerd op basis van de header, payload, en een geheime sleutel (secret) die wij verstrekken. Dit zorgt ervoor dat het token niet kan worden gewijzigd door een derde partij. - -> **Opmerking:** Het is aan te raden om de `exp` waarde zo in te stellen dat het token slechts een beperkte tijd geldig is, om het risico op misbruik te verkleinen. - -#### Headers voor de API-aanroep - -Zorg ervoor dat je de volgende headers meestuurt met elke API-aanroep: - -```plaintext -Authorization: Bearer {JWT-Token} -Accept: */* -Cache-Control: no-cache -``` - -Vervang `{JWT-Token}` door het daadwerkelijke token dat je hebt gegenereerd. - -### Query Parameters - -| Parameter | Type | Verplicht? | Standaard | Omschrijving | -|------------|--------|------------|------------|------------------------------------------------------------| -| `from` | string | Ja | - | De startdatum in ISO 8601 formaat (bijv. `yyyy-MM-ddTHH:mm:ssZ`). | -| `to` | string | Ja | - | De einddatum in ISO 8601 formaat (bijv. `yyyy-MM-ddTHH:mm:ssZ`). | -| `pageSize` | int | Nee | 5000 | Het aantal resultaten per pagina, maximaal 5000. | -| `page` | int | Nee | 1 | De pagina van de resultaten die moet worden opgehaald. | - -### Voorbeeld Request - -``` -GET /api/contactmomentendetails?from=2024-10-01T00:00:00Z&to=2024-10-10T23:59:59Z&pageSize=100&page=1 -Authorization: Bearer {JWT-Token} -``` - -Let erop dat de `Authorization` header met de waarde `Bearer {JWT-Token}` wordt toegevoegd bij elk request. +# Handleiding beheer KISS + +Als beheerder van KISS kan je de volgende zaken beheren: +- Nieuws en werkinstructies +- Skills +- Links +- Gespreksresultaten +- Formulier contactverzoeken +- Kanalen + +Per onderwerp leggen wij uit wat de mogelijkheden zijn en hoe je de werkzaamheden uitvoert. Om deze taken te kunnen uitvoeren moet je de rol `Redacteur` hebben (zie ook [Configuratie](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/CONFIGURATIE.md)). + +### KISS beheer vullen met voorbeelddata +Als je KISS voor het eerst hebt geïnstalleerd, en er bij Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten nog geen items zijn toegevoegd, is het mogelijk om eenvoudig voorbeelddata voor deze onderdelen te laden. Die doe je m.b.v. de knop op de startpagina. Met een druk op die knop zal de database met voorbeelddata worden gevuld voor Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten. Zodra de voorbeelddata is geladen, verdwijnt de optie/knop om (nogmaals) te vullen. + +#### Let op +De optie is alléén beschikbaar als de lijsten van Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten echt leeg zijn. Een beheerder kan deze lijsten handmatig schonen, zodat ze weer leeg zijn. Skills vormen hierop een uitzondering: deze worden niet daadwerkelijk weggegooid, maar alleen verborgen voor de gebruiker. Dit om te voorkomen dat een Skill die al gekoppeld is aan een bericht, daarvan zal verdwijnen. Dit betekent dat verwijderde Skills nog onzichtbaar aanwezig zijn in de database, waardoor er geen initiële dataset geladen kan worden. Zodra je ee Skill hebt toegevoegd, is het dus niet meer mogelijk om voorbeelddata te laden. + + +## Nieuws en werkinstructies +Nieuwsberichten en werkinstructies zijn berichten die van belang kunnen zijn voor de klantcontactmedewerkers. Deze berichten komen voor de klantcontactmedewerkers op hun homepagina te staan. + +Op onderstaande afbeelding is de overzichtspagina van het beheer van nieuwsberichten en werkinstructies te zien. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-overzicht.jpg.jpg) + + +### Nieuwsbericht of werkinstructie toevoegen +Voeg een nieuwsbericht of werkinstructie toe door rechts bovenaan op de "Toevoegen" te drukken. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-toevoegen.jpg) + +Vervolgens kom je op onderstaand scherm. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-toevoegen-detail.jpg) + +Hieronder wordt elk invoerveld toegelicht. + + +**Het type:** Met het type kan je aangeven of je bericht een werkinstructie of nieuwsbericht is. + +**De titel:** Dit is de titel van je bericht. + +**Inhoud:** Hier plaats je de inhoud van je bericht. + +**Belangrijk:** Hiermee kan je aangeven of een bericht belangrijk is of niet. Handig voor dringende zaken bijvoorbeeld. Belangrijke berichten komen voor de klantcontactmedewerkers altijd bovenaan te staan, zodat de klantcontactmedewerker deze meteen zal zien staan. Ook vallen belangrijke berichten extra op. + +**Publicatiedatum:** Bij de publicatiedatum kan je de gewenste datum en tijd instellen waarop een bericht gepubliceerd moet worden. Dit kan handig zijn voor als je een bericht alvast wil schrijven, maar nog niet wil publiceren. Het bericht wordt dan automatisch aan de klantcontactmedewerkers gepubliceerd op de geselecteerde datum en tijd. + +**Publicatie-einddatum:** Dit is de einddatum van je bericht. Bij nieuwe berichten staat dit veld standaard ingevuld met een datum over één jaar, maar dit kan je aanpassen. Na deze datum zal het bericht verdwijnen uit het overzicht van de klantcontactmedewerkers. In de beheertabel blijft het bericht wel staan. + +**Skills:** Hiermee kan je het aangeven of jouw bericht bij een specifieke skill hoort, en zoja: welke. Je kan meerdere skills tegelijk selecteren. Dus als je bericht relevant is voor meerdere skills, kun je dat aangeven. Klantcontactmedewerkers kunnen op hun startpagina de berichten filteren op skills. Ze kunnen meerdere skills aanvinken, dan worden alle berichten getoond die bij één of meerdere skills horen. Als je een bericht niet aan een skill koppelt, is het bericht ook alleen zichtbaar voor de klantcontactmedewerkers die geen filter aan hebben staan. + + +### Nieuwsbericht of werkinstructie wijzigen +Een nieuwsbericht of werkinstructie kan je wijzigen door op het pijltje te klikken dat rechts in de tabel te zien is. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-wijzigen.jpg) + + +Vervolgens kom je op onderstaand scherm. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-wijzigen-detail.jpg) + + +Hieronder wordt elk invoerveld toegelicht. + +**Het type:** Met het type kan je aangeven of je bericht een werkinstructie of nieuwsbericht is. + +**De titel:** Dit is de titel van je bericht. + +**Inhoud:** Hier plaats je de inhoud van je bericht. + +**Belangrijk:** Hiermee kan je aangeven of een bericht belangrijk is of niet. Handig voor dringende zaken bijvoorbeeld. Belangrijke berichten komen voor de klantcontactmedewerkers altijd bovenaan te staan, zodat de klantcontactmedewerker deze meteen zal zien staan. Ook vallen belangrijke berichten extra op. + +**Publicatiedatum:** Bij de publicatiedatum kan je de gewenste datum en tijd instellen waarop een bericht gepubliceerd moet worden. Dit kan handig zijn voor als je een bericht alvast wil schrijven, maar nog niet wil publiceren. Het bericht wordt dan automatisch aan de klantcontactmedewerkers gepubliceerd op de geselecteerde datum en tijd. + +**Publicatie-einddatum:** Dit is de einddatum van je bericht. Na deze datum zal het bericht verdwijnen uit het overzicht van de klantcontactmedewerkers. In de beheertabel blijft het bericht wel staan. + +**Skills:** Hiermee kan je het aangeven of jouw bericht bij een specifieke skill hoort, en zoja: welke. Je kan meerdere skills tegelijk selecteren. Dus als je bericht relevant is voor meerdere skills, kun je dat aangeven. Klantcontactmedewerkers kunnen op hun startpagina de berichten filteren op skills. Ze kunnen meerdere skills aanvinken, dan worden alle berichten getoond die bij één of meerdere skills horen. Als je een bericht niet aan een skill koppelt, is het bericht ook alleen zichtbaar voor de klantcontactmedewerkers die geen filter aan hebben staan. + + + + +### Nieuwsbericht of werkinstructie verwijderen +Een nieuwsbericht of werkinstructie kan je verwijderen door op het prullenbak icoontje te klikken dat rechts in de tabel te zien is. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-verwijderen.jpg) + + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit bericht wilt verwijderen?". Hierbij klik je op 'ok'. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-verwijderen-popup.jpg) + +## Skills +Op de pagina 'Skills' kan je de skills beheren. Skills kunnen bijvoorbeeld de verschillende afdelingen binnen het klantcontactcentrum zijn, zoals 'burgerzaken' of 'werk en inkomen'. + +De skills die je hier aanmaakt kunnen vervolgens als filter gebruikt worden bij de nieuwsberichten en werkinstructies. + +Het kan zijn dat jouw gemeente niet werkt met skills. In dat geval hoef je hier niets te doen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-overzicht.jpg) + +### Skill toevoegen +Een skill voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-toevoegen.jpg) + +Vervolgens kom je op onderstaand scherm. Hier kan je de naam van de skill invullen. Druk op 'Opslaan' om de skill toe te voegen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-toevoegen-detail.jpg) + + +### Skill wijzigen +Een skill wijzig je door op de naam van de skill te klikken. + +![inage](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-wijzigen.jpg) + + +Vervolgens kom je op onderstaand scherm. Hier kan je de naam van de skill wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. Deze wijziging is meteen zichtbaar bij alle berichten waar deze skill aan is gekoppeld, en in het filtermenu. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-wijzigen-detail.jpg) + +### Skill verwijderen +Een skill kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van de skill staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-verwijderen.jpg) + + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit bericht wilt verwijderen?". Hierbij klik je op 'ok'. De skill verdwijnt uit het filtermenu en ook bij alle berichten waar het aan gekoppeld was. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-verwijderen-popup.jpg) + + +## Links +Op de pagina 'Links' kan je de lijst met veelgebruikte links beheren. Hier kan je alle links neerzetten die voor jouw klantcontactmedewerkers handig zijn om altijd snel bij de hand te kunnen hebben. Denk bijvoorbeeld aan links naar bepaalde systemen of formulieren. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-overzicht.jpg) + +### Links toevoegen +Een link voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-toevoegen.jpg) + +Vervolgens kom je op onderstaand scherm. Hier kan je de titel, URL en de categorie van de link toevoegen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-toevoegen-detail.jpg) + +**Titel:** De naam waarmee de link in de lijst komt te staan. + +**Url:** De link naar de website. Een geldige URL begint altijd met https:// + +**Categorie:** De categorie waarin de link hoort. Als de link bij een al bestaande categorie hoort, typ je de naam van die categorie in. zodra je begint met typen, verschijnen de categorieën die beginnen met de letters die je typt. Je kunt dan snel de zelfde categorie kiezen. +Als je een andere categorie typt, wordt er automatisch een nieuwe categorie aangemaakt waar deze link onder valt. + +Druk op 'Opslaan' om de link toe te voegen. + + +### Links wijzigen +Een link wijzig je door op de naam van de link te klikken. + +![9mage](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-wijzigen.jpg) + + +Vervolgens kom je op onderstaand scherm. Hier kan je de link wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-wijzigen-detail.jpg) + + +**Titel:** De naam waarmee de link in de lijst komt te staan. + +**Url:** De link naar de website. + +**Categorie:** De categorie waarin de link hoort. Als de link bij een al bestaande categorie hoort, typ je de naam van die categorie in. zodra je begint met typen, verschijnen de categorieën die beginnen met de letters die je typt. Je kunt dan snel de zelfde categorie kiezen. +Als je een andere categorie typt, wordt er automatisch een nieuwe categorie aangemaakt waar deze link onder valt. + +### Links verwijderen +Een link kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van de link staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-verwijderen.jpg) + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u deze link wilt verwijderen?". Hierbij klik je op 'ok'. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-verwijderen-popup.jpg) + +## Gespreksresultaten +Op de pagina 'Gespreksresultaten' kan je de lijst met gespreksresultaten beheren. Met deze gespreksresultaten kunnen klantcontactmedewerkers aan het einde van hun contactmoment aangeven wat er met het gesprek is gebeurd, bijvoorbeeld zelfstandig afgehandeld of doorverbonden. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer.jpg) + +### Gespreksresultaat toevoegen +Een gespreksresultaat voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-toevoegen.jpg) + +Vervolgens kom je op onderstaand scherm. Hier kan je de naam van het gespreksresultaat invullen. Druk op 'Opslaan' om het gespreksesultaat toe te voegen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-toevoegen-detail.jpg) + + +### Gespreksresultaat wijzigen +Een gespreksresultaat wijzig je door op de naam van het gespreksresultaat te klikken. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-wijzigen.jpg) + +Vervolgens kom je op onderstaand scherm. Hier kan je de naam van het gespreksresultaat wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-wijzigen-detail.jpg) + +### Gespreksresultaat verwijderen +Een gespreksresultaat kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van het gespreksresultaat staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-verwijderen.jpg) + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit gespreksresultaat wilt verwijderen?". Hierbij klik je op 'ok' + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-verwijderen-popup.jpg) + + +## Formulieren contactverzoeken voor afdelingen en groepen +Bij ‘Formulieren contactverzoek afdelingen’ en ‘Formulieren contactverzoek groepen’ kan een beheerder van KISS formuliertjes aanmaken, die kunnen worden gebruikt in Contactverzoeken voor afdelingen en groepen. Het zijn eenvoudige formuliertjes, die een aantal extra vragen bevatten, waarmee je de KCM ondersteunt om al zoveel mogelijk relevante informatie mee te geven met het Contactverzoek. Dit zijn dus aanvullende vragen, op de vaste Contactverzoek-velden. + +Met de Vaste Contactverzoek velden geeft een KCM aan: + +1. Voor wie het Contactverzoek is: een afdeling, een groep of een medewerker +2. Een omschrijving waarover het gaat: dit is een toelichtingenveld waar informatie in staat, die alléén voor de collega is. +3. Met wie men contact moet opnemen: naam en contactgegevens van degene die teruggebeld (of teruggemaild, etc.) moet worden. + +Met een Contactverzoekformuliertje (of Vragenset) kan een KCM door een onderwerp te kiezen meer vragen stellen aan de klant, en zo een completer Contactverzoek invullen. Bijvoorbeeld: gaat een contactverzoek over een Parkeerbon? Dan is het handig om het nummer van de parkeerbon ook mee te geven. De klant voor wie het Contactverzoek wordt gemaakt, heeft dat meestal al bij de hand als hij contact opneemt met de gemeente. + +Bij beheer kun je deze formuliertjes (vragensets) aanmaken en beheren. +Hieronder volgt de handleiding voor het beheren van formulieren voor contactverzoeken voor afdelingen. Het beheren van van formulieren voor contactverzoeken voor groepen werkt op precies dezelfde manier. + +In het overzicht zie je de titel van het Contactverzoek, en de afdeling voor wie dit contactverzoek zou zijn. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-01.png) + +### Formulier toevoegen +Voeg een nieuw formulier toe door rechts bovenaan op de "Toevoegen" te drukken. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-02.png) + +Je komt op onderstaand scherm + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-03.png) + +In dit scherm moet je de Titel van het formulier opgeven. Deze titel beschrijft het onderwerp van het contactverzoek. Bijvoorbeeld: WMO, of Vraag voor Werk en inkomen. +Daaronder selecteer je de afdeling die bij deze contactverzoeken hoort. Deze lijst afdelingen, is dezelfde lijst afdelingen die een KCM gebruikt om aan te geven welke afdeling een Contactverzoek moet oppakken. + +Om een vraag toe te voegen, kies je eerst het vraagtype. Er zijn vier soorten vraagtypes: + +| Vraagtype | Uitleg | Voorbeeld | +|---|---|---| +| Open vraag kort | Invoerveld over één regel | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-open-kort.png) | +| Open vraag lang | Invoerveld over meerdere regels | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-open-lang.png) | +| Dropdown | Keuzelijst, waarin de KCM
maar één optie kan kiezen | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-dropdown.png) | +| Checkbox | Keuzelijst waarin de KCM
één of meer opties kan kiezen | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-checkbox.png) | + +Door in het veld Vraag toevoegen te klikken, klapt er een keuzelijst uit. Door één van de vraagtypes te kiezen, wordt er een vraag van dat vraagtype toegevoegd. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-04.png) + +- Voor alle vraagtypes geldt dat je de vraagtekst moet invullen. Dit is de tekst die in het uiteindelijke formulier boven het invoerveld komt te staan. +- Voor de Dropdown en de Checkbox moet je daarnaast óók minimaal twee antwoordopties opgeven. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-05.png) + +Met de knop Antwoordoptie Toevoegen kun je nog een optie toevoegen. De antwoordopties komen in het formulier in dezelfde volgorde waarin je ze bij aanmaken invoert. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-06.png) + +Als je alle vragen hebt ingesteld, klik je op Opslaan om het formulier op te slaan. Het formulier is meteen zichtbaar voor de KCM bij het aanmaken van een Contactverzoek. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-07.png) + +### Formulier wijzigen +Je kunt een formuliertje wijzigen door op het pijltje te klikken dat rechts in de tabel te zien is. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-08.png) + +Je komt in bewerkscherm van het formulier. Hier kun je bestaande vraagteksten wijzigen, de tekst van antwoord opties wijzigen en nieuwe vragen toevoegen. Ook kun je vragen of antwoord opties verwijderen. +Als je bijvoorbeeld de volgorde van antwoordopties in een meerkeuzevraag (dropdown of checkbox) wilt wijzigen, kun je de bestaande tekstjes verplaatsen. + + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-09.png) + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-10.png) + +Een vraag verwijder je door met de muis náást de vraag op het prullenbakje te klikken. Deze verschijnt als je met je muis achter het veld gaat staan. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-11.png) + +Een antwoordoptie verwijder je weer, door met de muist náást de antwoordoptie op het prullenbakje te klikken. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-12.png) + +Sla je je wijzigingen op met de Opslaan knop onderaan het formulier. Je wijzigingen zijn meteen zichtbaar, voor de KCM die een nieuw contactverzoek gaat aanmaken. Als een KCM al bezig was om met dat formulier een Contactverzoek te maken, kan die dat nog wel afmaken. + +### Formulier verwijderen +Je kunt een formulier verwijderen door op het prullenbak icoontje te klikken dat rechts in de tabel te zien is. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-13.png) + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit contactformulier wilt verwijderen?". Hierbij klik je op 'ok' om het verwijderen te bevestigen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-14.png) + +Het formulier is niet meer beschikbaar voor de KCM die een nieuw Contactverzoek gaat maken. Als een KCM al bezig was om met dat formulier een Contactverzoek te maken, kan die dat nog wel afmaken. + +## Kanalen +Op de pagina 'kanalen' kan je de lijst met kanalen beheren. Met deze kanalen kunnen klantcontactmedewerkers aan het einde van hun contactmoment aangeven via welk kanaal het contact heeft plaatsgevonden, bijvoorbeeld telefonisch of via e-mail. + +KISS hanteert een standaardlijst Kanalen, waaruit je kunt kiezen bij het registreren van een Contactmoment. Als je zelf geen kanalen toevoegt of alle kanalen verwijdert, dan zal KISS automatisch deze standaardlijst gebruiken. Deze lijst bevat de volgende kanalen: + +- Telefoon +- E-mail +- Contactformulier +- Twitter +- Facebook +- LinkedIn +- Live chat +- Instagram +- WhatsApp + + +### Kanalen toevoegen, wijzigen en verwijderen +Het toevoegen, wijzigen of verwijderen van kanalen gaat op een gelijksoortige manier als het toevoegen, wijzigen of verwijderen van Skills of gespreksresultaten. + +Let op: als je KISS gebruikt in combinatie met een bronregister, waarin ook kanalen aanwezig zijn (geconfigureerd of een vaste lijst kanalen), let dan goed op of het van belang is dat de schrijfwijze van een kanaal in KISS exact moet overeenkomen met kanaal in het bronregister. In dat geval moet je ook letten op hoofdletters, kleine, spaties en streepjes. + +## Vacs +Op de pagina 'Vacs' kan je Vraag-Antwoord-Combinaties beheren die zijn opgeslagen in het bij de KISS-installatie geconfigureerde Objectenregister. De lijst op de Vac-overzichtspagina toont alle Vacs. Door middel van de toetsenbord combinatie `Ctrl + f` kun je in de lijst zoeken naar de vraag die bij de Vraag-Antwoord-Combinatie hoort. + +#### Let op +Deze optie is alleen beschikbaar, als deze is aangezet bij de installatie/configuratie van KISS. Dit gebeurt m.b.v. een Environment Variabele. Zie ook [de installatiehandleiding](INSTALLATION.md#kiss-frontend), bij USE_VACS + +### Vacs toevoegen, wijzigen en verwijderen +Het toevoegen, wijzigen of verwijderen van Vacs gaat op een gelijksoortige manier als het toevoegen, wijzigen of verwijderen van Skills of gespreksresultaten. + +## Zoeken in bronnen +Binnen KISS kan een Klantcontactmedewerker zoeken in verschillende bronnen. KISS ondersteund op dit moment de volgende bronnen: de gemeentelijke website, in het smoelenboek van de gemeente, kennisartikelen in een Product-format en in Vraag-AntwoordCombinaties (VAC's). Het koppelen van deze bronnen moet gedaan worden door een technisch beheerder, in het kubernetescluster. Als de standaard installatieprocedure gevolgd is, draait er elk uur een taak (job) waardoor de bronnen worden gesyncrhoniseerd in de zoekindex. Bij onverwachte resultaten of foutmeldingen kan je de beheerder van het kubernetescluster vragen om de logging in te zien van de laatste synchronisatiepoging (job) van de [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync). Daarin is terug te vinden hoe de synchronisatiepoging is verlopen. + +## Managementinformatie +Bij het opslaan van Contactmomenten worden enkele gegevens, die geen plek hebben in de standaarden rondom Klantinteracties, opgeslagen binnen KISS zelf. (zie ook het [onderdeel Contactmomentdetails in Decision Record](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/DECISION-RECORD.md#contactmomentdetails)). Deze gegevens leveren managementinformatie over de werkzaamheden van het KCC. + +Binnen KISS is een API endpoint beschikbaar waarmee deze gegevens opgevraagd kunnen worden. Dit endpoint is benaderbaar op: `https://www.kissbijdegemeente.nl/api/contactmomentendetails`. + +### Authenticatie + +De Contactmomentendetails API is beveiligd en vereist een JWT Bearer Token voor toegang. Dit token wordt gegenereerd op basis van een geheime sleutel (secret) die door KISS wordt verstrekt aan de externe systemen. Dit secret is configureerbaar via de environment variabele `MANAGEMENTINFORMATIE_API_KEY` (zie installatiehandleiding) + +#### Structuur van de JWT + +De JWT bestaat uit drie delen, gescheiden door punten: + +1. **Header**: Bevat informatie over het algoritme dat gebruikt wordt om het token te ondertekenen, in dit geval HS256. + ```json + { + "alg": "HS256", + "typ": "JWT" + } + ``` + +2. **Payload**: De gegevens van de gebruiker of het systeem dat toegang probeert te verkrijgen. De payload bevat het `iat` (issued at) veld met de timestamp van het moment waarop het token is aangemaakt, en het `exp` (expiration) veld om de geldigheidsduur van het token te beperken. + + ```json + { + "iat": 1728580531, + "exp": 1728666931 + } + ``` + + - `iat`: Tijdstip van aanmaak van het token (in UNIX-timestamp). + - `exp`: Verloopdatum van het token (in UNIX-timestamp), na welke het token niet meer geldig is. + +3. **Signature**: De handtekening, gegenereerd op basis van de header, payload, en een geheime sleutel (secret) die wij verstrekken. Dit zorgt ervoor dat het token niet kan worden gewijzigd door een derde partij. + +> **Opmerking:** Het is aan te raden om de `exp` waarde zo in te stellen dat het token slechts een beperkte tijd geldig is, om het risico op misbruik te verkleinen. + +#### Headers voor de API-aanroep + +Zorg ervoor dat je de volgende headers meestuurt met elke API-aanroep: + +```plaintext +Authorization: Bearer {JWT-Token} +Accept: */* +Cache-Control: no-cache +``` + +Vervang `{JWT-Token}` door het daadwerkelijke token dat je hebt gegenereerd. + +### Query Parameters + +| Parameter | Type | Verplicht? | Standaard | Omschrijving | +|------------|--------|------------|------------|------------------------------------------------------------| +| `from` | string | Ja | - | De startdatum in ISO 8601 formaat (bijv. `yyyy-MM-ddTHH:mm:ssZ`). | +| `to` | string | Ja | - | De einddatum in ISO 8601 formaat (bijv. `yyyy-MM-ddTHH:mm:ssZ`). | +| `pageSize` | int | Nee | 5000 | Het aantal resultaten per pagina, maximaal 5000. | +| `page` | int | Nee | 1 | De pagina van de resultaten die moet worden opgehaald. | + +### Voorbeeld Request + +``` +GET /api/contactmomentendetails?from=2024-10-01T00:00:00Z&to=2024-10-10T23:59:59Z&pageSize=100&page=1 +Authorization: Bearer {JWT-Token} +``` + +Let erop dat de `Authorization` header met de waarde `Bearer {JWT-Token}` wordt toegevoegd bij elk request. From c5f4cbf06c7ef1eb74e1b091621f8760b6156ad5 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Thu, 20 Feb 2025 09:19:34 +0100 Subject: [PATCH 18/30] completed folder manual --- docs/manual/formulieren.md | 89 ++++++ docs/manual/gespreksresultaten.md | 32 +++ docs/manual/kanalen.md | 20 ++ docs/manual/links.md | 50 ++++ docs/manual/managementinformatie.md | 66 +++++ docs/manual/manual.rst | 27 ++ docs/manual/nieuws.md | 344 +---------------------- docs/manual/skills.md | 38 +++ docs/manual/vacs.md | 9 + docs/manual/voorbeelddata.md | 8 + docs/manual/zoeken-in-bronnen.md | 2 + docs/manual/zztemp.md | 408 ++++++++++++++++++++++++++++ 12 files changed, 754 insertions(+), 339 deletions(-) create mode 100644 docs/manual/formulieren.md create mode 100644 docs/manual/gespreksresultaten.md create mode 100644 docs/manual/kanalen.md create mode 100644 docs/manual/links.md create mode 100644 docs/manual/managementinformatie.md create mode 100644 docs/manual/manual.rst create mode 100644 docs/manual/skills.md create mode 100644 docs/manual/vacs.md create mode 100644 docs/manual/voorbeelddata.md create mode 100644 docs/manual/zoeken-in-bronnen.md create mode 100644 docs/manual/zztemp.md diff --git a/docs/manual/formulieren.md b/docs/manual/formulieren.md new file mode 100644 index 0000000..38a0dde --- /dev/null +++ b/docs/manual/formulieren.md @@ -0,0 +1,89 @@ +# Formulieren contactverzoeken voor afdelingen en groepen +Bij ‘Formulieren contactverzoek afdelingen’ en ‘Formulieren contactverzoek groepen’ kan een beheerder van KISS formuliertjes aanmaken, die kunnen worden gebruikt in Contactverzoeken voor afdelingen en groepen. Het zijn eenvoudige formuliertjes, die een aantal extra vragen bevatten, waarmee je de KCM ondersteunt om al zoveel mogelijk relevante informatie mee te geven met het Contactverzoek. Dit zijn dus aanvullende vragen, op de vaste Contactverzoek-velden. + +Met de Vaste Contactverzoek velden geeft een KCM aan: + +1. Voor wie het Contactverzoek is: een afdeling, een groep of een medewerker +2. Een omschrijving waarover het gaat: dit is een toelichtingenveld waar informatie in staat, die alléén voor de collega is. +3. Met wie men contact moet opnemen: naam en contactgegevens van degene die teruggebeld (of teruggemaild, etc.) moet worden. + +Met een Contactverzoekformuliertje (of Vragenset) kan een KCM door een onderwerp te kiezen meer vragen stellen aan de klant, en zo een completer Contactverzoek invullen. Bijvoorbeeld: gaat een contactverzoek over een Parkeerbon? Dan is het handig om het nummer van de parkeerbon ook mee te geven. De klant voor wie het Contactverzoek wordt gemaakt, heeft dat meestal al bij de hand als hij contact opneemt met de gemeente. + +Bij beheer kun je deze formuliertjes (vragensets) aanmaken en beheren. Hieronder volgt de handleiding voor het beheren van formulieren voor contactverzoeken voor afdelingen. Het beheren van van formulieren voor contactverzoeken voor groepen werkt op precies dezelfde manier. + +In het overzicht zie je de titel van het Contactverzoek, en de afdeling voor wie dit contactverzoek zou zijn. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-01.png) + + +## Formulier toevoegen +Voeg een nieuw formulier toe door rechts bovenaan op de "Toevoegen" te drukken. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-02.png) + +Je komt op onderstaand scherm + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-03.png) + +In dit scherm moet je de Titel van het formulier opgeven. Deze titel beschrijft het onderwerp van het contactverzoek. Bijvoorbeeld: WMO, of Vraag voor Werk en inkomen. +Daaronder selecteer je de afdeling die bij deze contactverzoeken hoort. Deze lijst afdelingen, is dezelfde lijst afdelingen die een KCM gebruikt om aan te geven welke afdeling een Contactverzoek moet oppakken. + +Om een vraag toe te voegen, kies je eerst het vraagtype. Er zijn vier soorten vraagtypes: + +| Vraagtype | Uitleg | Voorbeeld | +|---|---|---| +| Open vraag kort | Invoerveld over één regel | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-open-kort.png) | +| Open vraag lang | Invoerveld over meerdere regels | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-open-lang.png) | +| Dropdown | Keuzelijst, waarin de KCM
maar één optie kan kiezen | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-dropdown.png) | +| Checkbox | Keuzelijst waarin de KCM
één of meer opties kan kiezen | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-checkbox.png) | + +Door in het veld Vraag toevoegen te klikken, klapt er een keuzelijst uit. Door één van de vraagtypes te kiezen, wordt er een vraag van dat vraagtype toegevoegd. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-04.png) + +- Voor alle vraagtypes geldt dat je de vraagtekst moet invullen. Dit is de tekst die in het uiteindelijke formulier boven het invoerveld komt te staan. +- Voor de Dropdown en de Checkbox moet je daarnaast óók minimaal twee antwoordopties opgeven. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-05.png) + +Met de knop Antwoordoptie Toevoegen kun je nog een optie toevoegen. De antwoordopties komen in het formulier in dezelfde volgorde waarin je ze bij aanmaken invoert. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-06.png) + +Als je alle vragen hebt ingesteld, klik je op Opslaan om het formulier op te slaan. Het formulier is meteen zichtbaar voor de KCM bij het aanmaken van een Contactverzoek. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-07.png) + +## Formulier wijzigen +Je kunt een formuliertje wijzigen door op het pijltje te klikken dat rechts in de tabel te zien is. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-08.png) + +Je komt in bewerkscherm van het formulier. Hier kun je bestaande vraagteksten wijzigen, de tekst van antwoord opties wijzigen en nieuwe vragen toevoegen. Ook kun je vragen of antwoord opties verwijderen. +Als je bijvoorbeeld de volgorde van antwoordopties in een meerkeuzevraag (dropdown of checkbox) wilt wijzigen, kun je de bestaande tekstjes verplaatsen. + + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-09.png) + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-10.png) + +Een vraag verwijder je door met de muis náást de vraag op het prullenbakje te klikken. Deze verschijnt als je met je muis achter het veld gaat staan. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-11.png) + +Een antwoordoptie verwijder je weer, door met de muist náást de antwoordoptie op het prullenbakje te klikken. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-12.png) + +Sla je je wijzigingen op met de Opslaan knop onderaan het formulier. Je wijzigingen zijn meteen zichtbaar, voor de KCM die een nieuw contactverzoek gaat aanmaken. Als een KCM al bezig was om met dat formulier een Contactverzoek te maken, kan die dat nog wel afmaken. + +## Formulier verwijderen +Je kunt een formulier verwijderen door op het prullenbak icoontje te klikken dat rechts in de tabel te zien is. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-13.png) + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit contactformulier wilt verwijderen?". Hierbij klik je op 'ok' om het verwijderen te bevestigen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-14.png) + +Het formulier is niet meer beschikbaar voor de KCM die een nieuw Contactverzoek gaat maken. Als een KCM al bezig was om met dat formulier een Contactverzoek te maken, kan die dat nog wel afmaken. \ No newline at end of file diff --git a/docs/manual/gespreksresultaten.md b/docs/manual/gespreksresultaten.md new file mode 100644 index 0000000..b8123ce --- /dev/null +++ b/docs/manual/gespreksresultaten.md @@ -0,0 +1,32 @@ +# Gespreksresultaten +Op de pagina 'Gespreksresultaten' kan je de lijst met gespreksresultaten beheren. Met deze gespreksresultaten kunnen klantcontactmedewerkers aan het einde van hun contactmoment aangeven wat er met het gesprek is gebeurd, bijvoorbeeld zelfstandig afgehandeld of doorverbonden. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer.jpg) + +## Gespreksresultaat toevoegen +Een gespreksresultaat voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-toevoegen.jpg) + +Vervolgens kom je op onderstaand scherm. Hier kan je de naam van het gespreksresultaat invullen. Druk op 'Opslaan' om het gespreksesultaat toe te voegen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-toevoegen-detail.jpg) + + +## Gespreksresultaat wijzigen +Een gespreksresultaat wijzig je door op de naam van het gespreksresultaat te klikken. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-wijzigen.jpg) + +Vervolgens kom je op onderstaand scherm. Hier kan je de naam van het gespreksresultaat wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-wijzigen-detail.jpg) + +## Gespreksresultaat verwijderen +Een gespreksresultaat kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van het gespreksresultaat staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-verwijderen.jpg) + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit gespreksresultaat wilt verwijderen?". Hierbij klik je op 'ok' + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-verwijderen-popup.jpg) \ No newline at end of file diff --git a/docs/manual/kanalen.md b/docs/manual/kanalen.md new file mode 100644 index 0000000..7db7eac --- /dev/null +++ b/docs/manual/kanalen.md @@ -0,0 +1,20 @@ +# Kanalen +Op de pagina 'kanalen' kan je de lijst met kanalen beheren. Met deze kanalen kunnen klantcontactmedewerkers aan het einde van hun contactmoment aangeven via welk kanaal het contact heeft plaatsgevonden, bijvoorbeeld telefonisch of via e-mail. + +KISS hanteert een standaardlijst Kanalen, waaruit je kunt kiezen bij het registreren van een Contactmoment. Als je zelf geen kanalen toevoegt of alle kanalen verwijdert, dan zal KISS automatisch deze standaardlijst gebruiken. Deze lijst bevat de volgende kanalen: + +- Telefoon +- E-mail +- Contactformulier +- Twitter +- Facebook +- LinkedIn +- Live chat +- Instagram +- WhatsApp + + +## Kanalen toevoegen, wijzigen en verwijderen +Het toevoegen, wijzigen of verwijderen van kanalen gaat op een gelijksoortige manier als het toevoegen, wijzigen of verwijderen van Skills of gespreksresultaten. + +Let op: als je KISS gebruikt in combinatie met een bronregister, waarin ook kanalen aanwezig zijn (geconfigureerd of een vaste lijst kanalen), let dan goed op of het van belang is dat de schrijfwijze van een kanaal in KISS exact moet overeenkomen met kanaal in het bronregister. In dat geval moet je ook letten op hoofdletters, kleine, spaties en streepjes. diff --git a/docs/manual/links.md b/docs/manual/links.md new file mode 100644 index 0000000..1cb2219 --- /dev/null +++ b/docs/manual/links.md @@ -0,0 +1,50 @@ +# Links +Op de pagina 'Links' kan je de lijst met veelgebruikte links beheren. Hier kan je alle links neerzetten die voor jouw klantcontactmedewerkers handig zijn om altijd snel bij de hand te kunnen hebben. Denk bijvoorbeeld aan links naar bepaalde systemen of formulieren. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-overzicht.jpg) + +## Links toevoegen +Een link voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-toevoegen.jpg) + +Vervolgens kom je op onderstaand scherm. Hier kan je de titel, URL en de categorie van de link toevoegen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-toevoegen-detail.jpg) + +**Titel:** De naam waarmee de link in de lijst komt te staan. + +**Url:** De link naar de website. Een geldige URL begint altijd met https:// + +**Categorie:** De categorie waarin de link hoort. Als de link bij een al bestaande categorie hoort, typ je de naam van die categorie in. zodra je begint met typen, verschijnen de categorieën die beginnen met de letters die je typt. Je kunt dan snel de zelfde categorie kiezen. +Als je een andere categorie typt, wordt er automatisch een nieuwe categorie aangemaakt waar deze link onder valt. + +Druk op 'Opslaan' om de link toe te voegen. + + +## Links wijzigen +Een link wijzig je door op de naam van de link te klikken. + +![9mage](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-wijzigen.jpg) + + +Vervolgens kom je op onderstaand scherm. Hier kan je de link wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-wijzigen-detail.jpg) + + +**Titel:** De naam waarmee de link in de lijst komt te staan. + +**Url:** De link naar de website. + +**Categorie:** De categorie waarin de link hoort. Als de link bij een al bestaande categorie hoort, typ je de naam van die categorie in. zodra je begint met typen, verschijnen de categorieën die beginnen met de letters die je typt. Je kunt dan snel de zelfde categorie kiezen. +Als je een andere categorie typt, wordt er automatisch een nieuwe categorie aangemaakt waar deze link onder valt. + +## Links verwijderen +Een link kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van de link staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-verwijderen.jpg) + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u deze link wilt verwijderen?". Hierbij klik je op 'ok'. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-verwijderen-popup.jpg) \ No newline at end of file diff --git a/docs/manual/managementinformatie.md b/docs/manual/managementinformatie.md new file mode 100644 index 0000000..487f53f --- /dev/null +++ b/docs/manual/managementinformatie.md @@ -0,0 +1,66 @@ +# Managementinformatie +Bij het opslaan van Contactmomenten worden enkele gegevens, die geen plek hebben in de standaarden rondom Klantinteracties, opgeslagen binnen KISS zelf. (zie ook het [onderdeel Contactmomentdetails in Decision Record](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/DECISION-RECORD.md#contactmomentdetails)). Deze gegevens leveren managementinformatie over de werkzaamheden van het KCC. + +Binnen KISS is een API endpoint beschikbaar waarmee deze gegevens opgevraagd kunnen worden. Dit endpoint is benaderbaar op: `https://www.kissbijdegemeente.nl/api/contactmomentendetails`. + +## Authenticatie + +De Contactmomentendetails API is beveiligd en vereist een JWT Bearer Token voor toegang. Dit token wordt gegenereerd op basis van een geheime sleutel (secret) die door KISS wordt verstrekt aan de externe systemen. Dit secret is configureerbaar via de environment variabele `MANAGEMENTINFORMATIE_API_KEY` (zie installatiehandleiding) + +### Structuur van de JWT + +De JWT bestaat uit drie delen, gescheiden door punten: + +1. **Header**: Bevat informatie over het algoritme dat gebruikt wordt om het token te ondertekenen, in dit geval HS256. + ```json + { + "alg": "HS256", + "typ": "JWT" + } + ``` + +2. **Payload**: De gegevens van de gebruiker of het systeem dat toegang probeert te verkrijgen. De payload bevat het `iat` (issued at) veld met de timestamp van het moment waarop het token is aangemaakt, en het `exp` (expiration) veld om de geldigheidsduur van het token te beperken. + + ```json + { + "iat": 1728580531, + "exp": 1728666931 + } + ``` + + - `iat`: Tijdstip van aanmaak van het token (in UNIX-timestamp). + - `exp`: Verloopdatum van het token (in UNIX-timestamp), na welke het token niet meer geldig is. + +3. **Signature**: De handtekening, gegenereerd op basis van de header, payload, en een geheime sleutel (secret) die wij verstrekken. Dit zorgt ervoor dat het token niet kan worden gewijzigd door een derde partij. + +> **Opmerking:** Het is aan te raden om de `exp` waarde zo in te stellen dat het token slechts een beperkte tijd geldig is, om het risico op misbruik te verkleinen. + +### Headers voor de API-aanroep + +Zorg ervoor dat je de volgende headers meestuurt met elke API-aanroep: + +```plaintext +Authorization: Bearer {JWT-Token} +Accept: */* +Cache-Control: no-cache +``` + +Vervang `{JWT-Token}` door het daadwerkelijke token dat je hebt gegenereerd. + +## Query Parameters + +| Parameter | Type | Verplicht? | Standaard | Omschrijving | +|------------|--------|------------|------------|------------------------------------------------------------| +| `from` | string | Ja | - | De startdatum in ISO 8601 formaat (bijv. `yyyy-MM-ddTHH:mm:ssZ`). | +| `to` | string | Ja | - | De einddatum in ISO 8601 formaat (bijv. `yyyy-MM-ddTHH:mm:ssZ`). | +| `pageSize` | int | Nee | 5000 | Het aantal resultaten per pagina, maximaal 5000. | +| `page` | int | Nee | 1 | De pagina van de resultaten die moet worden opgehaald. | + +## Voorbeeld Request + +``` +GET /api/contactmomentendetails?from=2024-10-01T00:00:00Z&to=2024-10-10T23:59:59Z&pageSize=100&page=1 +Authorization: Bearer {JWT-Token} +``` + +Let erop dat de `Authorization` header met de waarde `Bearer {JWT-Token}` wordt toegevoegd bij elk request. diff --git a/docs/manual/manual.rst b/docs/manual/manual.rst new file mode 100644 index 0000000..43baa54 --- /dev/null +++ b/docs/manual/manual.rst @@ -0,0 +1,27 @@ +Handleiding beheer +======================= + +Als beheerder van KISS kan je de volgende zaken beheren: +- Nieuws en werkinstructies +- Skills +- Links +- Gespreksresultaten +- Formulier contactverzoeken +- Kanalen + +Per onderwerp leggen wij uit wat de mogelijkheden zijn en hoe je de werkzaamheden uitvoert. Om deze taken te kunnen uitvoeren moet je de rol `Redacteur` hebben (zie ook `Configuratie `__). + +.. toctree:: + :maxdepth: 2 + :hidden: + + voorbeelddata.md + nieuws.md + skills.md + links.md + gespreksresultaten.md + formulieren.md + kanalen.md + vacs.md + zoeken-in-bronnen.md + managementinformatie.md diff --git a/docs/manual/nieuws.md b/docs/manual/nieuws.md index 489b68e..80ec580 100644 --- a/docs/manual/nieuws.md +++ b/docs/manual/nieuws.md @@ -1,23 +1,4 @@ -# Handleiding beheer KISS - -Als beheerder van KISS kan je de volgende zaken beheren: -- Nieuws en werkinstructies -- Skills -- Links -- Gespreksresultaten -- Formulier contactverzoeken -- Kanalen - -Per onderwerp leggen wij uit wat de mogelijkheden zijn en hoe je de werkzaamheden uitvoert. Om deze taken te kunnen uitvoeren moet je de rol `Redacteur` hebben (zie ook [Configuratie](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/CONFIGURATIE.md)). - -### KISS beheer vullen met voorbeelddata -Als je KISS voor het eerst hebt geïnstalleerd, en er bij Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten nog geen items zijn toegevoegd, is het mogelijk om eenvoudig voorbeelddata voor deze onderdelen te laden. Die doe je m.b.v. de knop op de startpagina. Met een druk op die knop zal de database met voorbeelddata worden gevuld voor Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten. Zodra de voorbeelddata is geladen, verdwijnt de optie/knop om (nogmaals) te vullen. - -#### Let op -De optie is alléén beschikbaar als de lijsten van Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten echt leeg zijn. Een beheerder kan deze lijsten handmatig schonen, zodat ze weer leeg zijn. Skills vormen hierop een uitzondering: deze worden niet daadwerkelijk weggegooid, maar alleen verborgen voor de gebruiker. Dit om te voorkomen dat een Skill die al gekoppeld is aan een bericht, daarvan zal verdwijnen. Dit betekent dat verwijderde Skills nog onzichtbaar aanwezig zijn in de database, waardoor er geen initiële dataset geladen kan worden. Zodra je ee Skill hebt toegevoegd, is het dus niet meer mogelijk om voorbeelddata te laden. - - -## Nieuws en werkinstructies +# Nieuws en werkinstructies Nieuwsberichten en werkinstructies zijn berichten die van belang kunnen zijn voor de klantcontactmedewerkers. Deze berichten komen voor de klantcontactmedewerkers op hun homepagina te staan. Op onderstaande afbeelding is de overzichtspagina van het beheer van nieuwsberichten en werkinstructies te zien. @@ -25,7 +6,7 @@ Op onderstaande afbeelding is de overzichtspagina van het beheer van nieuwsberic ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-overzicht.jpg.jpg) -### Nieuwsbericht of werkinstructie toevoegen +## Nieuwsbericht of werkinstructie toevoegen Voeg een nieuwsbericht of werkinstructie toe door rechts bovenaan op de "Toevoegen" te drukken. ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-toevoegen.jpg) @@ -52,7 +33,7 @@ Hieronder wordt elk invoerveld toegelicht. **Skills:** Hiermee kan je het aangeven of jouw bericht bij een specifieke skill hoort, en zoja: welke. Je kan meerdere skills tegelijk selecteren. Dus als je bericht relevant is voor meerdere skills, kun je dat aangeven. Klantcontactmedewerkers kunnen op hun startpagina de berichten filteren op skills. Ze kunnen meerdere skills aanvinken, dan worden alle berichten getoond die bij één of meerdere skills horen. Als je een bericht niet aan een skill koppelt, is het bericht ook alleen zichtbaar voor de klantcontactmedewerkers die geen filter aan hebben staan. -### Nieuwsbericht of werkinstructie wijzigen +## Nieuwsbericht of werkinstructie wijzigen Een nieuwsbericht of werkinstructie kan je wijzigen door op het pijltje te klikken dat rechts in de tabel te zien is. ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-wijzigen.jpg) @@ -82,7 +63,7 @@ Hieronder wordt elk invoerveld toegelicht. -### Nieuwsbericht of werkinstructie verwijderen +## Nieuwsbericht of werkinstructie verwijderen Een nieuwsbericht of werkinstructie kan je verwijderen door op het prullenbak icoontje te klikken dat rechts in de tabel te zien is. ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-verwijderen.jpg) @@ -90,319 +71,4 @@ Een nieuwsbericht of werkinstructie kan je verwijderen door op het prullenbak ic Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit bericht wilt verwijderen?". Hierbij klik je op 'ok'. -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-verwijderen-popup.jpg) - -## Skills -Op de pagina 'Skills' kan je de skills beheren. Skills kunnen bijvoorbeeld de verschillende afdelingen binnen het klantcontactcentrum zijn, zoals 'burgerzaken' of 'werk en inkomen'. - -De skills die je hier aanmaakt kunnen vervolgens als filter gebruikt worden bij de nieuwsberichten en werkinstructies. - -Het kan zijn dat jouw gemeente niet werkt met skills. In dat geval hoef je hier niets te doen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-overzicht.jpg) - -### Skill toevoegen -Een skill voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-toevoegen.jpg) - -Vervolgens kom je op onderstaand scherm. Hier kan je de naam van de skill invullen. Druk op 'Opslaan' om de skill toe te voegen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-toevoegen-detail.jpg) - - -### Skill wijzigen -Een skill wijzig je door op de naam van de skill te klikken. - -![inage](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-wijzigen.jpg) - - -Vervolgens kom je op onderstaand scherm. Hier kan je de naam van de skill wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. Deze wijziging is meteen zichtbaar bij alle berichten waar deze skill aan is gekoppeld, en in het filtermenu. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-wijzigen-detail.jpg) - -### Skill verwijderen -Een skill kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van de skill staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-verwijderen.jpg) - - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit bericht wilt verwijderen?". Hierbij klik je op 'ok'. De skill verdwijnt uit het filtermenu en ook bij alle berichten waar het aan gekoppeld was. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-verwijderen-popup.jpg) - - -## Links -Op de pagina 'Links' kan je de lijst met veelgebruikte links beheren. Hier kan je alle links neerzetten die voor jouw klantcontactmedewerkers handig zijn om altijd snel bij de hand te kunnen hebben. Denk bijvoorbeeld aan links naar bepaalde systemen of formulieren. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-overzicht.jpg) - -### Links toevoegen -Een link voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-toevoegen.jpg) - -Vervolgens kom je op onderstaand scherm. Hier kan je de titel, URL en de categorie van de link toevoegen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-toevoegen-detail.jpg) - -**Titel:** De naam waarmee de link in de lijst komt te staan. - -**Url:** De link naar de website. Een geldige URL begint altijd met https:// - -**Categorie:** De categorie waarin de link hoort. Als de link bij een al bestaande categorie hoort, typ je de naam van die categorie in. zodra je begint met typen, verschijnen de categorieën die beginnen met de letters die je typt. Je kunt dan snel de zelfde categorie kiezen. -Als je een andere categorie typt, wordt er automatisch een nieuwe categorie aangemaakt waar deze link onder valt. - -Druk op 'Opslaan' om de link toe te voegen. - - -### Links wijzigen -Een link wijzig je door op de naam van de link te klikken. - -![9mage](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-wijzigen.jpg) - - -Vervolgens kom je op onderstaand scherm. Hier kan je de link wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-wijzigen-detail.jpg) - - -**Titel:** De naam waarmee de link in de lijst komt te staan. - -**Url:** De link naar de website. - -**Categorie:** De categorie waarin de link hoort. Als de link bij een al bestaande categorie hoort, typ je de naam van die categorie in. zodra je begint met typen, verschijnen de categorieën die beginnen met de letters die je typt. Je kunt dan snel de zelfde categorie kiezen. -Als je een andere categorie typt, wordt er automatisch een nieuwe categorie aangemaakt waar deze link onder valt. - -### Links verwijderen -Een link kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van de link staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-verwijderen.jpg) - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u deze link wilt verwijderen?". Hierbij klik je op 'ok'. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-verwijderen-popup.jpg) - -## Gespreksresultaten -Op de pagina 'Gespreksresultaten' kan je de lijst met gespreksresultaten beheren. Met deze gespreksresultaten kunnen klantcontactmedewerkers aan het einde van hun contactmoment aangeven wat er met het gesprek is gebeurd, bijvoorbeeld zelfstandig afgehandeld of doorverbonden. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer.jpg) - -### Gespreksresultaat toevoegen -Een gespreksresultaat voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-toevoegen.jpg) - -Vervolgens kom je op onderstaand scherm. Hier kan je de naam van het gespreksresultaat invullen. Druk op 'Opslaan' om het gespreksesultaat toe te voegen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-toevoegen-detail.jpg) - - -### Gespreksresultaat wijzigen -Een gespreksresultaat wijzig je door op de naam van het gespreksresultaat te klikken. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-wijzigen.jpg) - -Vervolgens kom je op onderstaand scherm. Hier kan je de naam van het gespreksresultaat wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-wijzigen-detail.jpg) - -### Gespreksresultaat verwijderen -Een gespreksresultaat kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van het gespreksresultaat staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-verwijderen.jpg) - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit gespreksresultaat wilt verwijderen?". Hierbij klik je op 'ok' - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-verwijderen-popup.jpg) - - -## Formulieren contactverzoeken voor afdelingen en groepen -Bij ‘Formulieren contactverzoek afdelingen’ en ‘Formulieren contactverzoek groepen’ kan een beheerder van KISS formuliertjes aanmaken, die kunnen worden gebruikt in Contactverzoeken voor afdelingen en groepen. Het zijn eenvoudige formuliertjes, die een aantal extra vragen bevatten, waarmee je de KCM ondersteunt om al zoveel mogelijk relevante informatie mee te geven met het Contactverzoek. Dit zijn dus aanvullende vragen, op de vaste Contactverzoek-velden. - -Met de Vaste Contactverzoek velden geeft een KCM aan: - -1. Voor wie het Contactverzoek is: een afdeling, een groep of een medewerker -2. Een omschrijving waarover het gaat: dit is een toelichtingenveld waar informatie in staat, die alléén voor de collega is. -3. Met wie men contact moet opnemen: naam en contactgegevens van degene die teruggebeld (of teruggemaild, etc.) moet worden. - -Met een Contactverzoekformuliertje (of Vragenset) kan een KCM door een onderwerp te kiezen meer vragen stellen aan de klant, en zo een completer Contactverzoek invullen. Bijvoorbeeld: gaat een contactverzoek over een Parkeerbon? Dan is het handig om het nummer van de parkeerbon ook mee te geven. De klant voor wie het Contactverzoek wordt gemaakt, heeft dat meestal al bij de hand als hij contact opneemt met de gemeente. - -Bij beheer kun je deze formuliertjes (vragensets) aanmaken en beheren. -Hieronder volgt de handleiding voor het beheren van formulieren voor contactverzoeken voor afdelingen. Het beheren van van formulieren voor contactverzoeken voor groepen werkt op precies dezelfde manier. - -In het overzicht zie je de titel van het Contactverzoek, en de afdeling voor wie dit contactverzoek zou zijn. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-01.png) - -### Formulier toevoegen -Voeg een nieuw formulier toe door rechts bovenaan op de "Toevoegen" te drukken. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-02.png) - -Je komt op onderstaand scherm - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-03.png) - -In dit scherm moet je de Titel van het formulier opgeven. Deze titel beschrijft het onderwerp van het contactverzoek. Bijvoorbeeld: WMO, of Vraag voor Werk en inkomen. -Daaronder selecteer je de afdeling die bij deze contactverzoeken hoort. Deze lijst afdelingen, is dezelfde lijst afdelingen die een KCM gebruikt om aan te geven welke afdeling een Contactverzoek moet oppakken. - -Om een vraag toe te voegen, kies je eerst het vraagtype. Er zijn vier soorten vraagtypes: - -| Vraagtype | Uitleg | Voorbeeld | -|---|---|---| -| Open vraag kort | Invoerveld over één regel | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-open-kort.png) | -| Open vraag lang | Invoerveld over meerdere regels | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-open-lang.png) | -| Dropdown | Keuzelijst, waarin de KCM
maar één optie kan kiezen | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-dropdown.png) | -| Checkbox | Keuzelijst waarin de KCM
één of meer opties kan kiezen | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-checkbox.png) | - -Door in het veld Vraag toevoegen te klikken, klapt er een keuzelijst uit. Door één van de vraagtypes te kiezen, wordt er een vraag van dat vraagtype toegevoegd. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-04.png) - -- Voor alle vraagtypes geldt dat je de vraagtekst moet invullen. Dit is de tekst die in het uiteindelijke formulier boven het invoerveld komt te staan. -- Voor de Dropdown en de Checkbox moet je daarnaast óók minimaal twee antwoordopties opgeven. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-05.png) - -Met de knop Antwoordoptie Toevoegen kun je nog een optie toevoegen. De antwoordopties komen in het formulier in dezelfde volgorde waarin je ze bij aanmaken invoert. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-06.png) - -Als je alle vragen hebt ingesteld, klik je op Opslaan om het formulier op te slaan. Het formulier is meteen zichtbaar voor de KCM bij het aanmaken van een Contactverzoek. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-07.png) - -### Formulier wijzigen -Je kunt een formuliertje wijzigen door op het pijltje te klikken dat rechts in de tabel te zien is. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-08.png) - -Je komt in bewerkscherm van het formulier. Hier kun je bestaande vraagteksten wijzigen, de tekst van antwoord opties wijzigen en nieuwe vragen toevoegen. Ook kun je vragen of antwoord opties verwijderen. -Als je bijvoorbeeld de volgorde van antwoordopties in een meerkeuzevraag (dropdown of checkbox) wilt wijzigen, kun je de bestaande tekstjes verplaatsen. - - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-09.png) - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-10.png) - -Een vraag verwijder je door met de muis náást de vraag op het prullenbakje te klikken. Deze verschijnt als je met je muis achter het veld gaat staan. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-11.png) - -Een antwoordoptie verwijder je weer, door met de muist náást de antwoordoptie op het prullenbakje te klikken. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-12.png) - -Sla je je wijzigingen op met de Opslaan knop onderaan het formulier. Je wijzigingen zijn meteen zichtbaar, voor de KCM die een nieuw contactverzoek gaat aanmaken. Als een KCM al bezig was om met dat formulier een Contactverzoek te maken, kan die dat nog wel afmaken. - -### Formulier verwijderen -Je kunt een formulier verwijderen door op het prullenbak icoontje te klikken dat rechts in de tabel te zien is. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-13.png) - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit contactformulier wilt verwijderen?". Hierbij klik je op 'ok' om het verwijderen te bevestigen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-14.png) - -Het formulier is niet meer beschikbaar voor de KCM die een nieuw Contactverzoek gaat maken. Als een KCM al bezig was om met dat formulier een Contactverzoek te maken, kan die dat nog wel afmaken. - -## Kanalen -Op de pagina 'kanalen' kan je de lijst met kanalen beheren. Met deze kanalen kunnen klantcontactmedewerkers aan het einde van hun contactmoment aangeven via welk kanaal het contact heeft plaatsgevonden, bijvoorbeeld telefonisch of via e-mail. - -KISS hanteert een standaardlijst Kanalen, waaruit je kunt kiezen bij het registreren van een Contactmoment. Als je zelf geen kanalen toevoegt of alle kanalen verwijdert, dan zal KISS automatisch deze standaardlijst gebruiken. Deze lijst bevat de volgende kanalen: - -- Telefoon -- E-mail -- Contactformulier -- Twitter -- Facebook -- LinkedIn -- Live chat -- Instagram -- WhatsApp - - -### Kanalen toevoegen, wijzigen en verwijderen -Het toevoegen, wijzigen of verwijderen van kanalen gaat op een gelijksoortige manier als het toevoegen, wijzigen of verwijderen van Skills of gespreksresultaten. - -Let op: als je KISS gebruikt in combinatie met een bronregister, waarin ook kanalen aanwezig zijn (geconfigureerd of een vaste lijst kanalen), let dan goed op of het van belang is dat de schrijfwijze van een kanaal in KISS exact moet overeenkomen met kanaal in het bronregister. In dat geval moet je ook letten op hoofdletters, kleine, spaties en streepjes. - -## Vacs -Op de pagina 'Vacs' kan je Vraag-Antwoord-Combinaties beheren die zijn opgeslagen in het bij de KISS-installatie geconfigureerde Objectenregister. De lijst op de Vac-overzichtspagina toont alle Vacs. Door middel van de toetsenbord combinatie `Ctrl + f` kun je in de lijst zoeken naar de vraag die bij de Vraag-Antwoord-Combinatie hoort. - -#### Let op -Deze optie is alleen beschikbaar, als deze is aangezet bij de installatie/configuratie van KISS. Dit gebeurt m.b.v. een Environment Variabele. Zie ook [de installatiehandleiding](INSTALLATION.md#kiss-frontend), bij USE_VACS - -### Vacs toevoegen, wijzigen en verwijderen -Het toevoegen, wijzigen of verwijderen van Vacs gaat op een gelijksoortige manier als het toevoegen, wijzigen of verwijderen van Skills of gespreksresultaten. - -## Zoeken in bronnen -Binnen KISS kan een Klantcontactmedewerker zoeken in verschillende bronnen. KISS ondersteund op dit moment de volgende bronnen: de gemeentelijke website, in het smoelenboek van de gemeente, kennisartikelen in een Product-format en in Vraag-AntwoordCombinaties (VAC's). Het koppelen van deze bronnen moet gedaan worden door een technisch beheerder, in het kubernetescluster. Als de standaard installatieprocedure gevolgd is, draait er elk uur een taak (job) waardoor de bronnen worden gesyncrhoniseerd in de zoekindex. Bij onverwachte resultaten of foutmeldingen kan je de beheerder van het kubernetescluster vragen om de logging in te zien van de laatste synchronisatiepoging (job) van de [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync). Daarin is terug te vinden hoe de synchronisatiepoging is verlopen. - -## Managementinformatie -Bij het opslaan van Contactmomenten worden enkele gegevens, die geen plek hebben in de standaarden rondom Klantinteracties, opgeslagen binnen KISS zelf. (zie ook het [onderdeel Contactmomentdetails in Decision Record](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/DECISION-RECORD.md#contactmomentdetails)). Deze gegevens leveren managementinformatie over de werkzaamheden van het KCC. - -Binnen KISS is een API endpoint beschikbaar waarmee deze gegevens opgevraagd kunnen worden. Dit endpoint is benaderbaar op: `https://www.kissbijdegemeente.nl/api/contactmomentendetails`. - -### Authenticatie - -De Contactmomentendetails API is beveiligd en vereist een JWT Bearer Token voor toegang. Dit token wordt gegenereerd op basis van een geheime sleutel (secret) die door KISS wordt verstrekt aan de externe systemen. Dit secret is configureerbaar via de environment variabele `MANAGEMENTINFORMATIE_API_KEY` (zie installatiehandleiding) - -#### Structuur van de JWT - -De JWT bestaat uit drie delen, gescheiden door punten: - -1. **Header**: Bevat informatie over het algoritme dat gebruikt wordt om het token te ondertekenen, in dit geval HS256. - ```json - { - "alg": "HS256", - "typ": "JWT" - } - ``` - -2. **Payload**: De gegevens van de gebruiker of het systeem dat toegang probeert te verkrijgen. De payload bevat het `iat` (issued at) veld met de timestamp van het moment waarop het token is aangemaakt, en het `exp` (expiration) veld om de geldigheidsduur van het token te beperken. - - ```json - { - "iat": 1728580531, - "exp": 1728666931 - } - ``` - - - `iat`: Tijdstip van aanmaak van het token (in UNIX-timestamp). - - `exp`: Verloopdatum van het token (in UNIX-timestamp), na welke het token niet meer geldig is. - -3. **Signature**: De handtekening, gegenereerd op basis van de header, payload, en een geheime sleutel (secret) die wij verstrekken. Dit zorgt ervoor dat het token niet kan worden gewijzigd door een derde partij. - -> **Opmerking:** Het is aan te raden om de `exp` waarde zo in te stellen dat het token slechts een beperkte tijd geldig is, om het risico op misbruik te verkleinen. - -#### Headers voor de API-aanroep - -Zorg ervoor dat je de volgende headers meestuurt met elke API-aanroep: - -```plaintext -Authorization: Bearer {JWT-Token} -Accept: */* -Cache-Control: no-cache -``` - -Vervang `{JWT-Token}` door het daadwerkelijke token dat je hebt gegenereerd. - -### Query Parameters - -| Parameter | Type | Verplicht? | Standaard | Omschrijving | -|------------|--------|------------|------------|------------------------------------------------------------| -| `from` | string | Ja | - | De startdatum in ISO 8601 formaat (bijv. `yyyy-MM-ddTHH:mm:ssZ`). | -| `to` | string | Ja | - | De einddatum in ISO 8601 formaat (bijv. `yyyy-MM-ddTHH:mm:ssZ`). | -| `pageSize` | int | Nee | 5000 | Het aantal resultaten per pagina, maximaal 5000. | -| `page` | int | Nee | 1 | De pagina van de resultaten die moet worden opgehaald. | - -### Voorbeeld Request - -``` -GET /api/contactmomentendetails?from=2024-10-01T00:00:00Z&to=2024-10-10T23:59:59Z&pageSize=100&page=1 -Authorization: Bearer {JWT-Token} -``` - -Let erop dat de `Authorization` header met de waarde `Bearer {JWT-Token}` wordt toegevoegd bij elk request. +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-verwijderen-popup.jpg) \ No newline at end of file diff --git a/docs/manual/skills.md b/docs/manual/skills.md new file mode 100644 index 0000000..96a6a7d --- /dev/null +++ b/docs/manual/skills.md @@ -0,0 +1,38 @@ +# Skills +Op de pagina 'Skills' kan je de skills beheren. Skills kunnen bijvoorbeeld de verschillende afdelingen binnen het klantcontactcentrum zijn, zoals 'burgerzaken' of 'werk en inkomen'. + +De skills die je hier aanmaakt kunnen vervolgens als filter gebruikt worden bij de nieuwsberichten en werkinstructies. + +Het kan zijn dat jouw gemeente niet werkt met skills. In dat geval hoef je hier niets te doen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-overzicht.jpg) + +## Skill toevoegen +Een skill voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-toevoegen.jpg) + +Vervolgens kom je op onderstaand scherm. Hier kan je de naam van de skill invullen. Druk op 'Opslaan' om de skill toe te voegen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-toevoegen-detail.jpg) + + +## Skill wijzigen +Een skill wijzig je door op de naam van de skill te klikken. + +![inage](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-wijzigen.jpg) + + +Vervolgens kom je op onderstaand scherm. Hier kan je de naam van de skill wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. Deze wijziging is meteen zichtbaar bij alle berichten waar deze skill aan is gekoppeld, en in het filtermenu. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-wijzigen-detail.jpg) + +## Skill verwijderen +Een skill kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van de skill staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-verwijderen.jpg) + + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit bericht wilt verwijderen?". Hierbij klik je op 'ok'. De skill verdwijnt uit het filtermenu en ook bij alle berichten waar het aan gekoppeld was. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-verwijderen-popup.jpg) \ No newline at end of file diff --git a/docs/manual/vacs.md b/docs/manual/vacs.md new file mode 100644 index 0000000..68b0d1b --- /dev/null +++ b/docs/manual/vacs.md @@ -0,0 +1,9 @@ +# Vacs +Op de pagina 'Vacs' kan je Vraag-Antwoord-Combinaties beheren die zijn opgeslagen in het bij de KISS-installatie geconfigureerde Objectenregister. De lijst op de Vac-overzichtspagina toont alle Vacs. Door middel van de toetsenbord combinatie `Ctrl + f` kun je in de lijst zoeken naar de vraag die bij de Vraag-Antwoord-Combinatie hoort. + +### Let op +Deze optie is alleen beschikbaar, als deze is aangezet bij de installatie/configuratie van KISS. Dit gebeurt m.b.v. een Environment Variabele. Zie ook [de installatiehandleiding](INSTALLATION.md#kiss-frontend), bij USE_VACS + +## Vacs toevoegen, wijzigen en verwijderen +Het toevoegen, wijzigen of verwijderen van Vacs gaat op een gelijksoortige manier als het toevoegen, wijzigen of verwijderen van Skills of gespreksresultaten. + diff --git a/docs/manual/voorbeelddata.md b/docs/manual/voorbeelddata.md new file mode 100644 index 0000000..fd29e4c --- /dev/null +++ b/docs/manual/voorbeelddata.md @@ -0,0 +1,8 @@ +# KISS beheer vullen met voorbeelddata + +Als je KISS voor het eerst hebt geïnstalleerd, en er bij Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten nog geen items zijn toegevoegd, is het mogelijk om eenvoudig voorbeelddata voor deze onderdelen te laden. Die doe je m.b.v. de knop op de startpagina. Met een druk op die knop zal de database met voorbeelddata worden gevuld voor Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten. Zodra de voorbeelddata is geladen, verdwijnt de optie/knop om (nogmaals) te vullen. + +## Let op + + +De optie is alléén beschikbaar als de lijsten van Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten echt leeg zijn. Een beheerder kan deze lijsten handmatig schonen, zodat ze weer leeg zijn. Skills vormen hierop een uitzondering: deze worden niet daadwerkelijk weggegooid, maar alleen verborgen voor de gebruiker. Dit om te voorkomen dat een Skill die al gekoppeld is aan een bericht, daarvan zal verdwijnen. Dit betekent dat verwijderde Skills nog onzichtbaar aanwezig zijn in de database, waardoor er geen initiële dataset geladen kan worden. Zodra je ee Skill hebt toegevoegd, is het dus niet meer mogelijk om voorbeelddata te laden. diff --git a/docs/manual/zoeken-in-bronnen.md b/docs/manual/zoeken-in-bronnen.md new file mode 100644 index 0000000..9d78e6a --- /dev/null +++ b/docs/manual/zoeken-in-bronnen.md @@ -0,0 +1,2 @@ +# Zoeken in bronnen +Binnen KISS kan een Klantcontactmedewerker zoeken in verschillende bronnen. KISS ondersteund op dit moment de volgende bronnen: de gemeentelijke website, in het smoelenboek van de gemeente, kennisartikelen in een Product-format en in Vraag-AntwoordCombinaties (VAC's). Het koppelen van deze bronnen moet gedaan worden door een technisch beheerder, in het kubernetescluster. Als de standaard installatieprocedure gevolgd is, draait er elk uur een taak (job) waardoor de bronnen worden gesyncrhoniseerd in de zoekindex. Bij onverwachte resultaten of foutmeldingen kan je de beheerder van het kubernetescluster vragen om de logging in te zien van de laatste synchronisatiepoging (job) van de [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync). Daarin is terug te vinden hoe de synchronisatiepoging is verlopen. diff --git a/docs/manual/zztemp.md b/docs/manual/zztemp.md new file mode 100644 index 0000000..489b68e --- /dev/null +++ b/docs/manual/zztemp.md @@ -0,0 +1,408 @@ +# Handleiding beheer KISS + +Als beheerder van KISS kan je de volgende zaken beheren: +- Nieuws en werkinstructies +- Skills +- Links +- Gespreksresultaten +- Formulier contactverzoeken +- Kanalen + +Per onderwerp leggen wij uit wat de mogelijkheden zijn en hoe je de werkzaamheden uitvoert. Om deze taken te kunnen uitvoeren moet je de rol `Redacteur` hebben (zie ook [Configuratie](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/CONFIGURATIE.md)). + +### KISS beheer vullen met voorbeelddata +Als je KISS voor het eerst hebt geïnstalleerd, en er bij Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten nog geen items zijn toegevoegd, is het mogelijk om eenvoudig voorbeelddata voor deze onderdelen te laden. Die doe je m.b.v. de knop op de startpagina. Met een druk op die knop zal de database met voorbeelddata worden gevuld voor Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten. Zodra de voorbeelddata is geladen, verdwijnt de optie/knop om (nogmaals) te vullen. + +#### Let op +De optie is alléén beschikbaar als de lijsten van Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten echt leeg zijn. Een beheerder kan deze lijsten handmatig schonen, zodat ze weer leeg zijn. Skills vormen hierop een uitzondering: deze worden niet daadwerkelijk weggegooid, maar alleen verborgen voor de gebruiker. Dit om te voorkomen dat een Skill die al gekoppeld is aan een bericht, daarvan zal verdwijnen. Dit betekent dat verwijderde Skills nog onzichtbaar aanwezig zijn in de database, waardoor er geen initiële dataset geladen kan worden. Zodra je ee Skill hebt toegevoegd, is het dus niet meer mogelijk om voorbeelddata te laden. + + +## Nieuws en werkinstructies +Nieuwsberichten en werkinstructies zijn berichten die van belang kunnen zijn voor de klantcontactmedewerkers. Deze berichten komen voor de klantcontactmedewerkers op hun homepagina te staan. + +Op onderstaande afbeelding is de overzichtspagina van het beheer van nieuwsberichten en werkinstructies te zien. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-overzicht.jpg.jpg) + + +### Nieuwsbericht of werkinstructie toevoegen +Voeg een nieuwsbericht of werkinstructie toe door rechts bovenaan op de "Toevoegen" te drukken. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-toevoegen.jpg) + +Vervolgens kom je op onderstaand scherm. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-toevoegen-detail.jpg) + +Hieronder wordt elk invoerveld toegelicht. + + +**Het type:** Met het type kan je aangeven of je bericht een werkinstructie of nieuwsbericht is. + +**De titel:** Dit is de titel van je bericht. + +**Inhoud:** Hier plaats je de inhoud van je bericht. + +**Belangrijk:** Hiermee kan je aangeven of een bericht belangrijk is of niet. Handig voor dringende zaken bijvoorbeeld. Belangrijke berichten komen voor de klantcontactmedewerkers altijd bovenaan te staan, zodat de klantcontactmedewerker deze meteen zal zien staan. Ook vallen belangrijke berichten extra op. + +**Publicatiedatum:** Bij de publicatiedatum kan je de gewenste datum en tijd instellen waarop een bericht gepubliceerd moet worden. Dit kan handig zijn voor als je een bericht alvast wil schrijven, maar nog niet wil publiceren. Het bericht wordt dan automatisch aan de klantcontactmedewerkers gepubliceerd op de geselecteerde datum en tijd. + +**Publicatie-einddatum:** Dit is de einddatum van je bericht. Bij nieuwe berichten staat dit veld standaard ingevuld met een datum over één jaar, maar dit kan je aanpassen. Na deze datum zal het bericht verdwijnen uit het overzicht van de klantcontactmedewerkers. In de beheertabel blijft het bericht wel staan. + +**Skills:** Hiermee kan je het aangeven of jouw bericht bij een specifieke skill hoort, en zoja: welke. Je kan meerdere skills tegelijk selecteren. Dus als je bericht relevant is voor meerdere skills, kun je dat aangeven. Klantcontactmedewerkers kunnen op hun startpagina de berichten filteren op skills. Ze kunnen meerdere skills aanvinken, dan worden alle berichten getoond die bij één of meerdere skills horen. Als je een bericht niet aan een skill koppelt, is het bericht ook alleen zichtbaar voor de klantcontactmedewerkers die geen filter aan hebben staan. + + +### Nieuwsbericht of werkinstructie wijzigen +Een nieuwsbericht of werkinstructie kan je wijzigen door op het pijltje te klikken dat rechts in de tabel te zien is. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-wijzigen.jpg) + + +Vervolgens kom je op onderstaand scherm. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-wijzigen-detail.jpg) + + +Hieronder wordt elk invoerveld toegelicht. + +**Het type:** Met het type kan je aangeven of je bericht een werkinstructie of nieuwsbericht is. + +**De titel:** Dit is de titel van je bericht. + +**Inhoud:** Hier plaats je de inhoud van je bericht. + +**Belangrijk:** Hiermee kan je aangeven of een bericht belangrijk is of niet. Handig voor dringende zaken bijvoorbeeld. Belangrijke berichten komen voor de klantcontactmedewerkers altijd bovenaan te staan, zodat de klantcontactmedewerker deze meteen zal zien staan. Ook vallen belangrijke berichten extra op. + +**Publicatiedatum:** Bij de publicatiedatum kan je de gewenste datum en tijd instellen waarop een bericht gepubliceerd moet worden. Dit kan handig zijn voor als je een bericht alvast wil schrijven, maar nog niet wil publiceren. Het bericht wordt dan automatisch aan de klantcontactmedewerkers gepubliceerd op de geselecteerde datum en tijd. + +**Publicatie-einddatum:** Dit is de einddatum van je bericht. Na deze datum zal het bericht verdwijnen uit het overzicht van de klantcontactmedewerkers. In de beheertabel blijft het bericht wel staan. + +**Skills:** Hiermee kan je het aangeven of jouw bericht bij een specifieke skill hoort, en zoja: welke. Je kan meerdere skills tegelijk selecteren. Dus als je bericht relevant is voor meerdere skills, kun je dat aangeven. Klantcontactmedewerkers kunnen op hun startpagina de berichten filteren op skills. Ze kunnen meerdere skills aanvinken, dan worden alle berichten getoond die bij één of meerdere skills horen. Als je een bericht niet aan een skill koppelt, is het bericht ook alleen zichtbaar voor de klantcontactmedewerkers die geen filter aan hebben staan. + + + + +### Nieuwsbericht of werkinstructie verwijderen +Een nieuwsbericht of werkinstructie kan je verwijderen door op het prullenbak icoontje te klikken dat rechts in de tabel te zien is. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-verwijderen.jpg) + + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit bericht wilt verwijderen?". Hierbij klik je op 'ok'. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-verwijderen-popup.jpg) + +## Skills +Op de pagina 'Skills' kan je de skills beheren. Skills kunnen bijvoorbeeld de verschillende afdelingen binnen het klantcontactcentrum zijn, zoals 'burgerzaken' of 'werk en inkomen'. + +De skills die je hier aanmaakt kunnen vervolgens als filter gebruikt worden bij de nieuwsberichten en werkinstructies. + +Het kan zijn dat jouw gemeente niet werkt met skills. In dat geval hoef je hier niets te doen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-overzicht.jpg) + +### Skill toevoegen +Een skill voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-toevoegen.jpg) + +Vervolgens kom je op onderstaand scherm. Hier kan je de naam van de skill invullen. Druk op 'Opslaan' om de skill toe te voegen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-toevoegen-detail.jpg) + + +### Skill wijzigen +Een skill wijzig je door op de naam van de skill te klikken. + +![inage](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-wijzigen.jpg) + + +Vervolgens kom je op onderstaand scherm. Hier kan je de naam van de skill wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. Deze wijziging is meteen zichtbaar bij alle berichten waar deze skill aan is gekoppeld, en in het filtermenu. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-wijzigen-detail.jpg) + +### Skill verwijderen +Een skill kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van de skill staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-verwijderen.jpg) + + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit bericht wilt verwijderen?". Hierbij klik je op 'ok'. De skill verdwijnt uit het filtermenu en ook bij alle berichten waar het aan gekoppeld was. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-verwijderen-popup.jpg) + + +## Links +Op de pagina 'Links' kan je de lijst met veelgebruikte links beheren. Hier kan je alle links neerzetten die voor jouw klantcontactmedewerkers handig zijn om altijd snel bij de hand te kunnen hebben. Denk bijvoorbeeld aan links naar bepaalde systemen of formulieren. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-overzicht.jpg) + +### Links toevoegen +Een link voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-toevoegen.jpg) + +Vervolgens kom je op onderstaand scherm. Hier kan je de titel, URL en de categorie van de link toevoegen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-toevoegen-detail.jpg) + +**Titel:** De naam waarmee de link in de lijst komt te staan. + +**Url:** De link naar de website. Een geldige URL begint altijd met https:// + +**Categorie:** De categorie waarin de link hoort. Als de link bij een al bestaande categorie hoort, typ je de naam van die categorie in. zodra je begint met typen, verschijnen de categorieën die beginnen met de letters die je typt. Je kunt dan snel de zelfde categorie kiezen. +Als je een andere categorie typt, wordt er automatisch een nieuwe categorie aangemaakt waar deze link onder valt. + +Druk op 'Opslaan' om de link toe te voegen. + + +### Links wijzigen +Een link wijzig je door op de naam van de link te klikken. + +![9mage](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-wijzigen.jpg) + + +Vervolgens kom je op onderstaand scherm. Hier kan je de link wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-wijzigen-detail.jpg) + + +**Titel:** De naam waarmee de link in de lijst komt te staan. + +**Url:** De link naar de website. + +**Categorie:** De categorie waarin de link hoort. Als de link bij een al bestaande categorie hoort, typ je de naam van die categorie in. zodra je begint met typen, verschijnen de categorieën die beginnen met de letters die je typt. Je kunt dan snel de zelfde categorie kiezen. +Als je een andere categorie typt, wordt er automatisch een nieuwe categorie aangemaakt waar deze link onder valt. + +### Links verwijderen +Een link kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van de link staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-verwijderen.jpg) + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u deze link wilt verwijderen?". Hierbij klik je op 'ok'. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-verwijderen-popup.jpg) + +## Gespreksresultaten +Op de pagina 'Gespreksresultaten' kan je de lijst met gespreksresultaten beheren. Met deze gespreksresultaten kunnen klantcontactmedewerkers aan het einde van hun contactmoment aangeven wat er met het gesprek is gebeurd, bijvoorbeeld zelfstandig afgehandeld of doorverbonden. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer.jpg) + +### Gespreksresultaat toevoegen +Een gespreksresultaat voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-toevoegen.jpg) + +Vervolgens kom je op onderstaand scherm. Hier kan je de naam van het gespreksresultaat invullen. Druk op 'Opslaan' om het gespreksesultaat toe te voegen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-toevoegen-detail.jpg) + + +### Gespreksresultaat wijzigen +Een gespreksresultaat wijzig je door op de naam van het gespreksresultaat te klikken. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-wijzigen.jpg) + +Vervolgens kom je op onderstaand scherm. Hier kan je de naam van het gespreksresultaat wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-wijzigen-detail.jpg) + +### Gespreksresultaat verwijderen +Een gespreksresultaat kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van het gespreksresultaat staat. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-verwijderen.jpg) + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit gespreksresultaat wilt verwijderen?". Hierbij klik je op 'ok' + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-verwijderen-popup.jpg) + + +## Formulieren contactverzoeken voor afdelingen en groepen +Bij ‘Formulieren contactverzoek afdelingen’ en ‘Formulieren contactverzoek groepen’ kan een beheerder van KISS formuliertjes aanmaken, die kunnen worden gebruikt in Contactverzoeken voor afdelingen en groepen. Het zijn eenvoudige formuliertjes, die een aantal extra vragen bevatten, waarmee je de KCM ondersteunt om al zoveel mogelijk relevante informatie mee te geven met het Contactverzoek. Dit zijn dus aanvullende vragen, op de vaste Contactverzoek-velden. + +Met de Vaste Contactverzoek velden geeft een KCM aan: + +1. Voor wie het Contactverzoek is: een afdeling, een groep of een medewerker +2. Een omschrijving waarover het gaat: dit is een toelichtingenveld waar informatie in staat, die alléén voor de collega is. +3. Met wie men contact moet opnemen: naam en contactgegevens van degene die teruggebeld (of teruggemaild, etc.) moet worden. + +Met een Contactverzoekformuliertje (of Vragenset) kan een KCM door een onderwerp te kiezen meer vragen stellen aan de klant, en zo een completer Contactverzoek invullen. Bijvoorbeeld: gaat een contactverzoek over een Parkeerbon? Dan is het handig om het nummer van de parkeerbon ook mee te geven. De klant voor wie het Contactverzoek wordt gemaakt, heeft dat meestal al bij de hand als hij contact opneemt met de gemeente. + +Bij beheer kun je deze formuliertjes (vragensets) aanmaken en beheren. +Hieronder volgt de handleiding voor het beheren van formulieren voor contactverzoeken voor afdelingen. Het beheren van van formulieren voor contactverzoeken voor groepen werkt op precies dezelfde manier. + +In het overzicht zie je de titel van het Contactverzoek, en de afdeling voor wie dit contactverzoek zou zijn. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-01.png) + +### Formulier toevoegen +Voeg een nieuw formulier toe door rechts bovenaan op de "Toevoegen" te drukken. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-02.png) + +Je komt op onderstaand scherm + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-03.png) + +In dit scherm moet je de Titel van het formulier opgeven. Deze titel beschrijft het onderwerp van het contactverzoek. Bijvoorbeeld: WMO, of Vraag voor Werk en inkomen. +Daaronder selecteer je de afdeling die bij deze contactverzoeken hoort. Deze lijst afdelingen, is dezelfde lijst afdelingen die een KCM gebruikt om aan te geven welke afdeling een Contactverzoek moet oppakken. + +Om een vraag toe te voegen, kies je eerst het vraagtype. Er zijn vier soorten vraagtypes: + +| Vraagtype | Uitleg | Voorbeeld | +|---|---|---| +| Open vraag kort | Invoerveld over één regel | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-open-kort.png) | +| Open vraag lang | Invoerveld over meerdere regels | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-open-lang.png) | +| Dropdown | Keuzelijst, waarin de KCM
maar één optie kan kiezen | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-dropdown.png) | +| Checkbox | Keuzelijst waarin de KCM
één of meer opties kan kiezen | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-checkbox.png) | + +Door in het veld Vraag toevoegen te klikken, klapt er een keuzelijst uit. Door één van de vraagtypes te kiezen, wordt er een vraag van dat vraagtype toegevoegd. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-04.png) + +- Voor alle vraagtypes geldt dat je de vraagtekst moet invullen. Dit is de tekst die in het uiteindelijke formulier boven het invoerveld komt te staan. +- Voor de Dropdown en de Checkbox moet je daarnaast óók minimaal twee antwoordopties opgeven. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-05.png) + +Met de knop Antwoordoptie Toevoegen kun je nog een optie toevoegen. De antwoordopties komen in het formulier in dezelfde volgorde waarin je ze bij aanmaken invoert. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-06.png) + +Als je alle vragen hebt ingesteld, klik je op Opslaan om het formulier op te slaan. Het formulier is meteen zichtbaar voor de KCM bij het aanmaken van een Contactverzoek. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-07.png) + +### Formulier wijzigen +Je kunt een formuliertje wijzigen door op het pijltje te klikken dat rechts in de tabel te zien is. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-08.png) + +Je komt in bewerkscherm van het formulier. Hier kun je bestaande vraagteksten wijzigen, de tekst van antwoord opties wijzigen en nieuwe vragen toevoegen. Ook kun je vragen of antwoord opties verwijderen. +Als je bijvoorbeeld de volgorde van antwoordopties in een meerkeuzevraag (dropdown of checkbox) wilt wijzigen, kun je de bestaande tekstjes verplaatsen. + + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-09.png) + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-10.png) + +Een vraag verwijder je door met de muis náást de vraag op het prullenbakje te klikken. Deze verschijnt als je met je muis achter het veld gaat staan. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-11.png) + +Een antwoordoptie verwijder je weer, door met de muist náást de antwoordoptie op het prullenbakje te klikken. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-12.png) + +Sla je je wijzigingen op met de Opslaan knop onderaan het formulier. Je wijzigingen zijn meteen zichtbaar, voor de KCM die een nieuw contactverzoek gaat aanmaken. Als een KCM al bezig was om met dat formulier een Contactverzoek te maken, kan die dat nog wel afmaken. + +### Formulier verwijderen +Je kunt een formulier verwijderen door op het prullenbak icoontje te klikken dat rechts in de tabel te zien is. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-13.png) + +Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit contactformulier wilt verwijderen?". Hierbij klik je op 'ok' om het verwijderen te bevestigen. + +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-14.png) + +Het formulier is niet meer beschikbaar voor de KCM die een nieuw Contactverzoek gaat maken. Als een KCM al bezig was om met dat formulier een Contactverzoek te maken, kan die dat nog wel afmaken. + +## Kanalen +Op de pagina 'kanalen' kan je de lijst met kanalen beheren. Met deze kanalen kunnen klantcontactmedewerkers aan het einde van hun contactmoment aangeven via welk kanaal het contact heeft plaatsgevonden, bijvoorbeeld telefonisch of via e-mail. + +KISS hanteert een standaardlijst Kanalen, waaruit je kunt kiezen bij het registreren van een Contactmoment. Als je zelf geen kanalen toevoegt of alle kanalen verwijdert, dan zal KISS automatisch deze standaardlijst gebruiken. Deze lijst bevat de volgende kanalen: + +- Telefoon +- E-mail +- Contactformulier +- Twitter +- Facebook +- LinkedIn +- Live chat +- Instagram +- WhatsApp + + +### Kanalen toevoegen, wijzigen en verwijderen +Het toevoegen, wijzigen of verwijderen van kanalen gaat op een gelijksoortige manier als het toevoegen, wijzigen of verwijderen van Skills of gespreksresultaten. + +Let op: als je KISS gebruikt in combinatie met een bronregister, waarin ook kanalen aanwezig zijn (geconfigureerd of een vaste lijst kanalen), let dan goed op of het van belang is dat de schrijfwijze van een kanaal in KISS exact moet overeenkomen met kanaal in het bronregister. In dat geval moet je ook letten op hoofdletters, kleine, spaties en streepjes. + +## Vacs +Op de pagina 'Vacs' kan je Vraag-Antwoord-Combinaties beheren die zijn opgeslagen in het bij de KISS-installatie geconfigureerde Objectenregister. De lijst op de Vac-overzichtspagina toont alle Vacs. Door middel van de toetsenbord combinatie `Ctrl + f` kun je in de lijst zoeken naar de vraag die bij de Vraag-Antwoord-Combinatie hoort. + +#### Let op +Deze optie is alleen beschikbaar, als deze is aangezet bij de installatie/configuratie van KISS. Dit gebeurt m.b.v. een Environment Variabele. Zie ook [de installatiehandleiding](INSTALLATION.md#kiss-frontend), bij USE_VACS + +### Vacs toevoegen, wijzigen en verwijderen +Het toevoegen, wijzigen of verwijderen van Vacs gaat op een gelijksoortige manier als het toevoegen, wijzigen of verwijderen van Skills of gespreksresultaten. + +## Zoeken in bronnen +Binnen KISS kan een Klantcontactmedewerker zoeken in verschillende bronnen. KISS ondersteund op dit moment de volgende bronnen: de gemeentelijke website, in het smoelenboek van de gemeente, kennisartikelen in een Product-format en in Vraag-AntwoordCombinaties (VAC's). Het koppelen van deze bronnen moet gedaan worden door een technisch beheerder, in het kubernetescluster. Als de standaard installatieprocedure gevolgd is, draait er elk uur een taak (job) waardoor de bronnen worden gesyncrhoniseerd in de zoekindex. Bij onverwachte resultaten of foutmeldingen kan je de beheerder van het kubernetescluster vragen om de logging in te zien van de laatste synchronisatiepoging (job) van de [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync). Daarin is terug te vinden hoe de synchronisatiepoging is verlopen. + +## Managementinformatie +Bij het opslaan van Contactmomenten worden enkele gegevens, die geen plek hebben in de standaarden rondom Klantinteracties, opgeslagen binnen KISS zelf. (zie ook het [onderdeel Contactmomentdetails in Decision Record](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/DECISION-RECORD.md#contactmomentdetails)). Deze gegevens leveren managementinformatie over de werkzaamheden van het KCC. + +Binnen KISS is een API endpoint beschikbaar waarmee deze gegevens opgevraagd kunnen worden. Dit endpoint is benaderbaar op: `https://www.kissbijdegemeente.nl/api/contactmomentendetails`. + +### Authenticatie + +De Contactmomentendetails API is beveiligd en vereist een JWT Bearer Token voor toegang. Dit token wordt gegenereerd op basis van een geheime sleutel (secret) die door KISS wordt verstrekt aan de externe systemen. Dit secret is configureerbaar via de environment variabele `MANAGEMENTINFORMATIE_API_KEY` (zie installatiehandleiding) + +#### Structuur van de JWT + +De JWT bestaat uit drie delen, gescheiden door punten: + +1. **Header**: Bevat informatie over het algoritme dat gebruikt wordt om het token te ondertekenen, in dit geval HS256. + ```json + { + "alg": "HS256", + "typ": "JWT" + } + ``` + +2. **Payload**: De gegevens van de gebruiker of het systeem dat toegang probeert te verkrijgen. De payload bevat het `iat` (issued at) veld met de timestamp van het moment waarop het token is aangemaakt, en het `exp` (expiration) veld om de geldigheidsduur van het token te beperken. + + ```json + { + "iat": 1728580531, + "exp": 1728666931 + } + ``` + + - `iat`: Tijdstip van aanmaak van het token (in UNIX-timestamp). + - `exp`: Verloopdatum van het token (in UNIX-timestamp), na welke het token niet meer geldig is. + +3. **Signature**: De handtekening, gegenereerd op basis van de header, payload, en een geheime sleutel (secret) die wij verstrekken. Dit zorgt ervoor dat het token niet kan worden gewijzigd door een derde partij. + +> **Opmerking:** Het is aan te raden om de `exp` waarde zo in te stellen dat het token slechts een beperkte tijd geldig is, om het risico op misbruik te verkleinen. + +#### Headers voor de API-aanroep + +Zorg ervoor dat je de volgende headers meestuurt met elke API-aanroep: + +```plaintext +Authorization: Bearer {JWT-Token} +Accept: */* +Cache-Control: no-cache +``` + +Vervang `{JWT-Token}` door het daadwerkelijke token dat je hebt gegenereerd. + +### Query Parameters + +| Parameter | Type | Verplicht? | Standaard | Omschrijving | +|------------|--------|------------|------------|------------------------------------------------------------| +| `from` | string | Ja | - | De startdatum in ISO 8601 formaat (bijv. `yyyy-MM-ddTHH:mm:ssZ`). | +| `to` | string | Ja | - | De einddatum in ISO 8601 formaat (bijv. `yyyy-MM-ddTHH:mm:ssZ`). | +| `pageSize` | int | Nee | 5000 | Het aantal resultaten per pagina, maximaal 5000. | +| `page` | int | Nee | 1 | De pagina van de resultaten die moet worden opgehaald. | + +### Voorbeeld Request + +``` +GET /api/contactmomentendetails?from=2024-10-01T00:00:00Z&to=2024-10-10T23:59:59Z&pageSize=100&page=1 +Authorization: Bearer {JWT-Token} +``` + +Let erop dat de `Authorization` header met de waarde `Bearer {JWT-Token}` wordt toegevoegd bij elk request. From 12767c69d7f4b888c8ba9e398ae1c4b8d2009c64 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Thu, 20 Feb 2025 09:22:57 +0100 Subject: [PATCH 19/30] add conf py, move rename configurationmd --- docs/conf.py | 114 +++++++++ .../objecten.md} | 232 +++++++++--------- 2 files changed, 230 insertions(+), 116 deletions(-) create mode 100644 docs/conf.py rename docs/{CONFIGURATIE.md => configuration/objecten.md} (98%) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..5e68c38 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,114 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- +import os +import sys + +# ONDERSTAANDE KOMT UIT openzaak +# maar het pad ../src gaat naar de source van heel openzaak. +# dus onderstaande gebruik ik maar niet. +# import django +# sys.path.insert(0, os.path.abspath("../src")) + +# onderstaande komt uit https://github.com/readthedocs/readthedocs.org/blob/main/docs/conf.py +# dus daarvan neem ik dan ook de map _ext over, met daarin alleen +# readthedocs.org/docs/_ext/djangodocs.py + +sys.path.append(os.path.abspath("_ext")) + + + + +# -- Project information ----------------------------------------------------- + +project = "KISS documentatie" +copyright = "2024" +# # author = objects.__author__ + +# The full version, including alpha/beta/rc tags +# # release = objects.__version__ + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +# Volgens mij heb ik iig nodig: sphinx_rtd_theme, én myst_parser (voor markdown) +# gekopieerd uit Openzaak: "sphinx.ext.todo","recommonmark","sphinx_markdown_tables","sphinx_tabs.tabs" + +extensions = [ + "sphinx_rtd_theme", + "myst_parser", + "sphinx.ext.todo", +] + + + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = "nl" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. + +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +source_suffix = ['.rst', '.md'] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_logo = "logo.png" +html_theme = "sphinx_rtd_theme" + +# onderstaande komt uit: +# https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html + +html_theme_options = { + 'logo_only': False, + 'prev_next_buttons_location': 'bottom', + 'style_external_links': True, + 'style_nav_header_background': '#2980b9', + 'flyout_display': 'attached', + 'version_selector': False, + 'language_selector': True, + # Toc options + 'collapse_navigation': False, + 'sticky_navigation': True, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': False +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". + + +# ik weet niet zo goed waar deze vandaan komt. En ik heb dus wel een theme_override.css +# Ik weet niet helemaal wat die doet, maar ik ga m toch gebruiken. +# ik zet deze comment boven html_static, omdat copilot dat suggereert. + +html_static_path = ["_static"] +html_css_files = [ + "theme_override.css", # override wide tables with word wrap +] + +# deze komt ook uit openzaak +# maar zij gebruiken gegenereerde content. dus deze gebruik ik ook niet +# +# todo_include_todos = True + diff --git a/docs/CONFIGURATIE.md b/docs/configuration/objecten.md similarity index 98% rename from docs/CONFIGURATIE.md rename to docs/configuration/objecten.md index e817c6c..4e87c13 100644 --- a/docs/CONFIGURATIE.md +++ b/docs/configuration/objecten.md @@ -1,116 +1,116 @@ -# Configuratie -Bij de installatie van KISS worden er een groot aantal dingen al geconfigureerd. Op deze pagina staan verschillende onderdelen van de configuratie toegelicht. - - -## Configuratie t.b.v. Objecten API -KISS maakt voor de koppeling met verschillende registraties gebruik van de Objecten API. Om objecten van een bepaald objecttype op te kunnen halen, moet het de URL weten van dat objecttype in de Objecttype API. Zie ook [de Installatiehandleiding](https://kiss-klantinteractie-servicesysteem.readthedocs.io/en/latest/INSTALLATION/) en de [documentatie bij KISS-Elastic-Sync](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/README.md) - -### Authenticatie bij de Objecten API -In de meeste gevallen identificeert KISS zich bij de Objectenregistratie m.b.v. een TOKEN. -In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een client secret en een client id. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** - -Dit heeft invloed op de volgende Environment Variabelen: - -- Bij gebruik in combinatie met OverigeObjecten met een in OverigeObjecten ingesteld token
-INTERNE_TAAK_TOKEN - -- Bij gebruik in combinatie met de e-suite, met een in de e-suite ingesteld secret en id
-INTERNE_TAAK_CLIENT_SECRET
-INTERNE_TAAK_CLIENT_ID - -- Bij gebruik in combinatie met OverigeObjecten met een in OverigeObjecten ingesteld token
-MEDEWERKER_OBJECTEN_TOKEN - -- Bij gebruik in combinatie met de e-suite, met een in de e-suite ingesteld secret en id -MEDEWERKER_OBJECTEN_CLIENT_SECRET
MEDEWERKER_OBJECTEN_CLIENT_ID - -### URL configureerbaar -Voor een aantal objecttypen kunt u de URL van het objecttype instellen m.b.v. environment variabelen. - -| Variabele | Toelichting | -|---|---| -| INTERNE_TAAK_OBJECT_TYPE_URL | De interne taak is onderdeel van een Contactverzoek | -| INTERNE_TAAK_TYPE_VERSION | De versie van het objecttype die gebruikt wordt in de API-aanroepen. Standaard ingesteld op `1`. | -| GROEPEN_OBJECT_TYPE_URL | Objecttype dat gebruikt wordt om Groepen op te halen
voor gebruik in Contactverzoeken | -| AFDELINGEN_OBJECT_TYPE_URL | Objecttype dat gebruikt wordt om Afdelingen op te halen
voor gebruik in Contactverzoeken, Formulieren
contactverzoek en registratie van Contactmomenten | -| SDG_OBJECT_TYPE_URL | Objecttype dat gebruikt wordt om Kennisartikelen op te halen;
dit objecttype is gebaseerd op het object `product`
in de SDG Invoervoorziening | - -### URL nog niet configureerbaar -Voor een aantal objecttype is de URL nog niet configureerbaar. In die gevallen zal KISS zelf de Objecttype API gaan bevragen om de URL op te halen. Hiervoor is het van belang dat de objecttypen in uw registratie de juiste naam hebben. - -| Naam Objecttype | Toelichting | -|---|---| -| VAC | Dit zijn de Vraag Antwoord Combinaties die via Elasticsearch ontsloten worden. | -| Medewerker | Dit zijn de medewerkers die via Elasticsearch ontsloten worden.
Deze medewerkers worden ook gebruikt in Contactverzoeken | - - -## Configuratie van uw Identity Provider -Bij de installatie van KISS regelt u de koppeling met uw OpenIDConnect Identity Provider. Daarnaast moet u in uw Identity Provider configureren dat gebruikers die in moeten kunnen loggen bij KISS in ieder geval een 'klantcontactmedewerker'-rol hebben. Een rol is in dit geval een claim van het type `role` of `roles` (beiden worden ondersteund). De waarde die correspondeert met een kiss-medewerker kunt u instellen tijdens de installatie. Standaard is dit `Klantcontactmedewerker`. Voor medewerkers die beheertaken op KISS uitvoeren, is een aparte rol ingeregeld. Ook de naam van deze rol kunt u instellen tijdens de installatie. Standaard is dit `Redacteur`. - -Als een ingelogde gebruiker wel de startpagina ziet, maar vervolgens alleen maar spinners blijft zien, dan heeft deze gebruiker niet de juiste rollen. - -### Claims uit uw Identity provider -KISS gebruikt de claims uit uw Identity Provider om de gegevens van de ingelogde Klantcontactmedewerker toe te voegen aan de Contactmomenten en Contactverzoeken die vanuit KISS worden geregistreerd. -Zie [de installatiehandleiding](INSTALLATION.md#Authenticatie) voor hoe u dit configureert. - -Er is in JWT geen standaard claim voor voorletters of voorvoegsel (tussenvoegsel). KISS gebruikt daarom deze mapping: -- Voorletters => given_name -- Achternaam => family_name indien beschikbaar, anders name indien beschikbaar, anders http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name -- Op dit moment doen we niets met Tussenvoegsel, omdat er geen voorvoegsel-claim bestaat. In de huidige implementatie komt tussenvoegsel alleen in het contactmoment, als het onderdeel is van de Achternaam. - - -### Voorbeeldinrichting in Azure Active Directory -Als u gebruik maakt van Azure Active Directory als Identity Provider, kunt u dit op de volgende manier inrichten. - -1. Bij de installatie van KISS heeft u een App Registration aangemaakt. Ga binnen Azure AD naar App registrations en klik op de applicatie. - - ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-01.png) - -1. Navigeer naar App roles, kies Create app role en vul de benodigde velden in. Belangrijk is dat u kiest voor Users/Groups bij Allowed member types en bij Value kiest voor de rol die u bij de installatie geconfigureerd hebt (standaard `Klantcontactmedewerker`). - - ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-02.png) - -1. Herhaal de vorige stap voor de rol die u tijdens de installatie heeft geconfigureerd voor medewerkers die beheertaken uitvoeren (standaard `Redacteur`) -1. Nu kunt u deze rollen toekennen aan gebruikers of groepen uit uw organisatie. Hiervoor moet u eerst terug naar Azure Active Directory. Navigeer daar naar Enterprise applications. - - ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-03.png) - -1. In dit scherm vindt u een applicatie met dezelfde naam als de App registration die u eerder heeft aangemaakt. Klik op de applicatie. - - ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-04.png) - -1. Navigeer naar Users and groups, en klik op Add user/group. - - ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-05.png) - -1. In dit scherm kunt u de rollen die u eerder gedefinieerd heeft, toekennen aan individuele gebruikers en - als uw licentie van Active Directory dit toestaat - groepen. - - -## Configuratie van Elasticsearch voor KISS -Met behulp van [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync) is het mogelijk om websites en een aantal gestructureerde bronnen doorzoekbaar te maken vanuit KISS. De eerste keer dat u deze tool gebruikt, wordt er een meta-engine aangemaakt met de naam `kiss-engine`. - -### Crawler -Het doorzoeken van een website binnen KISS wordt mogelijk door de website te crawlen vanuit Elastic Search. Hiervoor gebruikt u de [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync). Het is aan te raden om verder overleg te hebben met uw websitebeheerder, over het verdere finetunen van de crawler. Mogelijk zijn er aanpassingen nodig in uw robots.txt, is het raadzaam een KISS-specifieke sitemap.xml op te stellen of zijn er aanvullende filterinstellingen nodig. - -Op het moment dat de crawler de eerste keer gedraaid heeft, wordt het engine schema uitgebreid met de [velden die horen bij de crawler](https://www.elastic.co/guide/en/app-search/current/web-crawler-reference.html#web-crawler-reference-web-crawler-schema). - -### Syncen van bronnen -De eerste keer dat er via de synctool Kennisartikelen (PDC-producten), Medewerkers of VACs worden geindexeerd in Elastic, wordt het Engine Schema uitgebreid met een aantal velden. Dit zijn: -- `object_bron` - -- `object_meta` - -- De velden die bij de bron horen: voor elk property in het schema van de bron, wordt een property aangemaakt binnen de KISS-engine, voorafgegaan door de waarde van `objectbron`. - -### Relevance Tuning -Om de informatie uit de Kennisartikelen en websites doorzoekbaar te maken, moeten deze velden opgenomen zijn in het Engine Schema, en doorzoekbaar gezet in de Relevance tuning. Zijn er nieuwe velden toegevoegd aan het Engine Schema, bijvoorbeeld omdat er een nieuw type bron is toegevoegd? Dan moeten deze velden doorzoekbaar gemaakt worden, door op knop 'Update search settings' te klikken op de pagina Manage engine schema. U kunt ook op de pagina Relevance Tuning aangeven dat een schemaveld doorzoekbaar moet zijn. - -Om de zoekresultaten te beïnvloeden, moet u vervolgens de Relevance Tuning instellen. [Zie ook de documentatie van Elasticsearch](https://www.elastic.co/guide/en/app-search/current/relevance-tuning-guide.html) - -Elasticsearch zal binnen de meta-engine voor elk property van een object (een VAC, een medewerker of een Kennisartikel) een property aanmaken. Bijvoorbeeld `Kennisartikel.vertalingen.bezwaarEnBeroep` of `VAC.trefwoorden.trefwoord`. Elasticsearch zal ook zelf voor deze property's aangeven of ze doorzoekbaar moeten zijn of niet. Websitepagina's worden door de crawler aan de meta-engine toegevoegd, en zijn vindbaar via de velden van [het crawler-schema](https://www.elastic.co/guide/en/app-search/8.9/web-crawler-reference.html#web-crawler-reference-web-crawler-schema). - -Door vervolgens de relevantie van specifieke velden hoger te zetten, kunt u ervoor zorgen dat deze zwaarder meetellen in het zoekresultaat. Door de properties `VAC.trefwoorden.trefwoord` en `Kennisartikel.vertalingen.trefwoorden.trefwoord` hogere relevantiescore te geven, zullen de trefwoorden zwaarder meetellen. - -Doordat elke bron eigen properties krijgt in de meta-engine, kunt u specifieke bronnen zwaarder laten wegen. Als `VAC.trefwoorden.trefwoord` een hogere relevantiescore heeft dan `Kennisartikel.vertalingen.trefwoorden.trefwoord`, zullen de VAC's hoger in het zoekresultaat staan. - -Alle property's van het type text worden standaard doorzoekbaar gemaakt. Het is raadzaam deze standaard instellingen na te lopen. Vooral bij Kennisartikelen (waarvan het object gebaseerd is op de API van de SDG invoervoorziening) zijn er veel text property's, die niet relevant zijn voor de zoekresultaten. +# Configuratie +Bij de installatie van KISS worden er een groot aantal dingen al geconfigureerd. Op deze pagina staan verschillende onderdelen van de configuratie toegelicht. + + +## Configuratie t.b.v. Objecten API +KISS maakt voor de koppeling met verschillende registraties gebruik van de Objecten API. Om objecten van een bepaald objecttype op te kunnen halen, moet het de URL weten van dat objecttype in de Objecttype API. Zie ook [de Installatiehandleiding](https://kiss-klantinteractie-servicesysteem.readthedocs.io/en/latest/INSTALLATION/) en de [documentatie bij KISS-Elastic-Sync](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/README.md) + +### Authenticatie bij de Objecten API +In de meeste gevallen identificeert KISS zich bij de Objectenregistratie m.b.v. een TOKEN. +In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een client secret en een client id. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** + +Dit heeft invloed op de volgende Environment Variabelen: + +- Bij gebruik in combinatie met OverigeObjecten met een in OverigeObjecten ingesteld token
+INTERNE_TAAK_TOKEN + +- Bij gebruik in combinatie met de e-suite, met een in de e-suite ingesteld secret en id
+INTERNE_TAAK_CLIENT_SECRET
+INTERNE_TAAK_CLIENT_ID + +- Bij gebruik in combinatie met OverigeObjecten met een in OverigeObjecten ingesteld token
+MEDEWERKER_OBJECTEN_TOKEN + +- Bij gebruik in combinatie met de e-suite, met een in de e-suite ingesteld secret en id +MEDEWERKER_OBJECTEN_CLIENT_SECRET
MEDEWERKER_OBJECTEN_CLIENT_ID + +### URL configureerbaar +Voor een aantal objecttypen kunt u de URL van het objecttype instellen m.b.v. environment variabelen. + +| Variabele | Toelichting | +|---|---| +| INTERNE_TAAK_OBJECT_TYPE_URL | De interne taak is onderdeel van een Contactverzoek | +| INTERNE_TAAK_TYPE_VERSION | De versie van het objecttype die gebruikt wordt in de API-aanroepen. Standaard ingesteld op `1`. | +| GROEPEN_OBJECT_TYPE_URL | Objecttype dat gebruikt wordt om Groepen op te halen
voor gebruik in Contactverzoeken | +| AFDELINGEN_OBJECT_TYPE_URL | Objecttype dat gebruikt wordt om Afdelingen op te halen
voor gebruik in Contactverzoeken, Formulieren
contactverzoek en registratie van Contactmomenten | +| SDG_OBJECT_TYPE_URL | Objecttype dat gebruikt wordt om Kennisartikelen op te halen;
dit objecttype is gebaseerd op het object `product`
in de SDG Invoervoorziening | + +### URL nog niet configureerbaar +Voor een aantal objecttype is de URL nog niet configureerbaar. In die gevallen zal KISS zelf de Objecttype API gaan bevragen om de URL op te halen. Hiervoor is het van belang dat de objecttypen in uw registratie de juiste naam hebben. + +| Naam Objecttype | Toelichting | +|---|---| +| VAC | Dit zijn de Vraag Antwoord Combinaties die via Elasticsearch ontsloten worden. | +| Medewerker | Dit zijn de medewerkers die via Elasticsearch ontsloten worden.
Deze medewerkers worden ook gebruikt in Contactverzoeken | + + +## Configuratie van uw Identity Provider +Bij de installatie van KISS regelt u de koppeling met uw OpenIDConnect Identity Provider. Daarnaast moet u in uw Identity Provider configureren dat gebruikers die in moeten kunnen loggen bij KISS in ieder geval een 'klantcontactmedewerker'-rol hebben. Een rol is in dit geval een claim van het type `role` of `roles` (beiden worden ondersteund). De waarde die correspondeert met een kiss-medewerker kunt u instellen tijdens de installatie. Standaard is dit `Klantcontactmedewerker`. Voor medewerkers die beheertaken op KISS uitvoeren, is een aparte rol ingeregeld. Ook de naam van deze rol kunt u instellen tijdens de installatie. Standaard is dit `Redacteur`. + +Als een ingelogde gebruiker wel de startpagina ziet, maar vervolgens alleen maar spinners blijft zien, dan heeft deze gebruiker niet de juiste rollen. + +### Claims uit uw Identity provider +KISS gebruikt de claims uit uw Identity Provider om de gegevens van de ingelogde Klantcontactmedewerker toe te voegen aan de Contactmomenten en Contactverzoeken die vanuit KISS worden geregistreerd. +Zie [de installatiehandleiding](INSTALLATION.md#Authenticatie) voor hoe u dit configureert. + +Er is in JWT geen standaard claim voor voorletters of voorvoegsel (tussenvoegsel). KISS gebruikt daarom deze mapping: +- Voorletters => given_name +- Achternaam => family_name indien beschikbaar, anders name indien beschikbaar, anders http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name +- Op dit moment doen we niets met Tussenvoegsel, omdat er geen voorvoegsel-claim bestaat. In de huidige implementatie komt tussenvoegsel alleen in het contactmoment, als het onderdeel is van de Achternaam. + + +### Voorbeeldinrichting in Azure Active Directory +Als u gebruik maakt van Azure Active Directory als Identity Provider, kunt u dit op de volgende manier inrichten. + +1. Bij de installatie van KISS heeft u een App Registration aangemaakt. Ga binnen Azure AD naar App registrations en klik op de applicatie. + + ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-01.png) + +1. Navigeer naar App roles, kies Create app role en vul de benodigde velden in. Belangrijk is dat u kiest voor Users/Groups bij Allowed member types en bij Value kiest voor de rol die u bij de installatie geconfigureerd hebt (standaard `Klantcontactmedewerker`). + + ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-02.png) + +1. Herhaal de vorige stap voor de rol die u tijdens de installatie heeft geconfigureerd voor medewerkers die beheertaken uitvoeren (standaard `Redacteur`) +1. Nu kunt u deze rollen toekennen aan gebruikers of groepen uit uw organisatie. Hiervoor moet u eerst terug naar Azure Active Directory. Navigeer daar naar Enterprise applications. + + ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-03.png) + +1. In dit scherm vindt u een applicatie met dezelfde naam als de App registration die u eerder heeft aangemaakt. Klik op de applicatie. + + ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-04.png) + +1. Navigeer naar Users and groups, en klik op Add user/group. + + ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-05.png) + +1. In dit scherm kunt u de rollen die u eerder gedefinieerd heeft, toekennen aan individuele gebruikers en - als uw licentie van Active Directory dit toestaat - groepen. + + +## Configuratie van Elasticsearch voor KISS +Met behulp van [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync) is het mogelijk om websites en een aantal gestructureerde bronnen doorzoekbaar te maken vanuit KISS. De eerste keer dat u deze tool gebruikt, wordt er een meta-engine aangemaakt met de naam `kiss-engine`. + +### Crawler +Het doorzoeken van een website binnen KISS wordt mogelijk door de website te crawlen vanuit Elastic Search. Hiervoor gebruikt u de [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync). Het is aan te raden om verder overleg te hebben met uw websitebeheerder, over het verdere finetunen van de crawler. Mogelijk zijn er aanpassingen nodig in uw robots.txt, is het raadzaam een KISS-specifieke sitemap.xml op te stellen of zijn er aanvullende filterinstellingen nodig. + +Op het moment dat de crawler de eerste keer gedraaid heeft, wordt het engine schema uitgebreid met de [velden die horen bij de crawler](https://www.elastic.co/guide/en/app-search/current/web-crawler-reference.html#web-crawler-reference-web-crawler-schema). + +### Syncen van bronnen +De eerste keer dat er via de synctool Kennisartikelen (PDC-producten), Medewerkers of VACs worden geindexeerd in Elastic, wordt het Engine Schema uitgebreid met een aantal velden. Dit zijn: +- `object_bron` + +- `object_meta` + +- De velden die bij de bron horen: voor elk property in het schema van de bron, wordt een property aangemaakt binnen de KISS-engine, voorafgegaan door de waarde van `objectbron`. + +### Relevance Tuning +Om de informatie uit de Kennisartikelen en websites doorzoekbaar te maken, moeten deze velden opgenomen zijn in het Engine Schema, en doorzoekbaar gezet in de Relevance tuning. Zijn er nieuwe velden toegevoegd aan het Engine Schema, bijvoorbeeld omdat er een nieuw type bron is toegevoegd? Dan moeten deze velden doorzoekbaar gemaakt worden, door op knop 'Update search settings' te klikken op de pagina Manage engine schema. U kunt ook op de pagina Relevance Tuning aangeven dat een schemaveld doorzoekbaar moet zijn. + +Om de zoekresultaten te beïnvloeden, moet u vervolgens de Relevance Tuning instellen. [Zie ook de documentatie van Elasticsearch](https://www.elastic.co/guide/en/app-search/current/relevance-tuning-guide.html) + +Elasticsearch zal binnen de meta-engine voor elk property van een object (een VAC, een medewerker of een Kennisartikel) een property aanmaken. Bijvoorbeeld `Kennisartikel.vertalingen.bezwaarEnBeroep` of `VAC.trefwoorden.trefwoord`. Elasticsearch zal ook zelf voor deze property's aangeven of ze doorzoekbaar moeten zijn of niet. Websitepagina's worden door de crawler aan de meta-engine toegevoegd, en zijn vindbaar via de velden van [het crawler-schema](https://www.elastic.co/guide/en/app-search/8.9/web-crawler-reference.html#web-crawler-reference-web-crawler-schema). + +Door vervolgens de relevantie van specifieke velden hoger te zetten, kunt u ervoor zorgen dat deze zwaarder meetellen in het zoekresultaat. Door de properties `VAC.trefwoorden.trefwoord` en `Kennisartikel.vertalingen.trefwoorden.trefwoord` hogere relevantiescore te geven, zullen de trefwoorden zwaarder meetellen. + +Doordat elke bron eigen properties krijgt in de meta-engine, kunt u specifieke bronnen zwaarder laten wegen. Als `VAC.trefwoorden.trefwoord` een hogere relevantiescore heeft dan `Kennisartikel.vertalingen.trefwoorden.trefwoord`, zullen de VAC's hoger in het zoekresultaat staan. + +Alle property's van het type text worden standaard doorzoekbaar gemaakt. Het is raadzaam deze standaard instellingen na te lopen. Vooral bij Kennisartikelen (waarvan het object gebaseerd is op de API van de SDG invoervoorziening) zijn er veel text property's, die niet relevant zijn voor de zoekresultaten. From 5707112f9438d70a50ba39d24dccdd798b15d1c6 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Thu, 20 Feb 2025 09:31:11 +0100 Subject: [PATCH 20/30] folder configuration added --- docs/configuration/configuration.rst | 12 + docs/configuration/elastic.md | 28 ++ docs/configuration/identity-provider.md | 40 +++ docs/configuration/objecten.md | 86 +---- docs/manual/zztemp.md | 408 ------------------------ 5 files changed, 85 insertions(+), 489 deletions(-) create mode 100644 docs/configuration/configuration.rst create mode 100644 docs/configuration/elastic.md create mode 100644 docs/configuration/identity-provider.md delete mode 100644 docs/manual/zztemp.md diff --git a/docs/configuration/configuration.rst b/docs/configuration/configuration.rst new file mode 100644 index 0000000..5f7ba56 --- /dev/null +++ b/docs/configuration/configuration.rst @@ -0,0 +1,12 @@ +Configuratie +============ + +Bij de installatie van KISS worden er een groot aantal dingen al geconfigureerd. Op deze pagina staan verschillende onderdelen van de configuratie toegelicht. + +.. toctree:: + :maxdepth: 2 + :hidden: + + objecten.md + identity-provider.md + elastic.md diff --git a/docs/configuration/elastic.md b/docs/configuration/elastic.md new file mode 100644 index 0000000..22ad466 --- /dev/null +++ b/docs/configuration/elastic.md @@ -0,0 +1,28 @@ +# Configuratie van Elasticsearch voor KISS +Met behulp van [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync) is het mogelijk om websites en een aantal gestructureerde bronnen doorzoekbaar te maken vanuit KISS. De eerste keer dat u deze tool gebruikt, wordt er een meta-engine aangemaakt met de naam `kiss-engine`. + +## Crawler +Het doorzoeken van een website binnen KISS wordt mogelijk door de website te crawlen vanuit Elastic Search. Hiervoor gebruikt u de [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync). Het is aan te raden om verder overleg te hebben met uw websitebeheerder, over het verdere finetunen van de crawler. Mogelijk zijn er aanpassingen nodig in uw robots.txt, is het raadzaam een KISS-specifieke sitemap.xml op te stellen of zijn er aanvullende filterinstellingen nodig. + +Op het moment dat de crawler de eerste keer gedraaid heeft, wordt het engine schema uitgebreid met de [velden die horen bij de crawler](https://www.elastic.co/guide/en/app-search/current/web-crawler-reference.html#web-crawler-reference-web-crawler-schema). + +## Syncen van bronnen +De eerste keer dat er via de synctool Kennisartikelen (PDC-producten), Medewerkers of VACs worden geindexeerd in Elastic, wordt het Engine Schema uitgebreid met een aantal velden. Dit zijn: +- `object_bron` + +- `object_meta` + +- De velden die bij de bron horen: voor elk property in het schema van de bron, wordt een property aangemaakt binnen de KISS-engine, voorafgegaan door de waarde van `objectbron`. + +## Relevance Tuning +Om de informatie uit de Kennisartikelen en websites doorzoekbaar te maken, moeten deze velden opgenomen zijn in het Engine Schema, en doorzoekbaar gezet in de Relevance tuning. Zijn er nieuwe velden toegevoegd aan het Engine Schema, bijvoorbeeld omdat er een nieuw type bron is toegevoegd? Dan moeten deze velden doorzoekbaar gemaakt worden, door op knop 'Update search settings' te klikken op de pagina Manage engine schema. U kunt ook op de pagina Relevance Tuning aangeven dat een schemaveld doorzoekbaar moet zijn. + +Om de zoekresultaten te beïnvloeden, moet u vervolgens de Relevance Tuning instellen. [Zie ook de documentatie van Elasticsearch](https://www.elastic.co/guide/en/app-search/current/relevance-tuning-guide.html) + +Elasticsearch zal binnen de meta-engine voor elk property van een object (een VAC, een medewerker of een Kennisartikel) een property aanmaken. Bijvoorbeeld `Kennisartikel.vertalingen.bezwaarEnBeroep` of `VAC.trefwoorden.trefwoord`. Elasticsearch zal ook zelf voor deze property's aangeven of ze doorzoekbaar moeten zijn of niet. Websitepagina's worden door de crawler aan de meta-engine toegevoegd, en zijn vindbaar via de velden van [het crawler-schema](https://www.elastic.co/guide/en/app-search/8.9/web-crawler-reference.html#web-crawler-reference-web-crawler-schema). + +Door vervolgens de relevantie van specifieke velden hoger te zetten, kunt u ervoor zorgen dat deze zwaarder meetellen in het zoekresultaat. Door de properties `VAC.trefwoorden.trefwoord` en `Kennisartikel.vertalingen.trefwoorden.trefwoord` hogere relevantiescore te geven, zullen de trefwoorden zwaarder meetellen. + +Doordat elke bron eigen properties krijgt in de meta-engine, kunt u specifieke bronnen zwaarder laten wegen. Als `VAC.trefwoorden.trefwoord` een hogere relevantiescore heeft dan `Kennisartikel.vertalingen.trefwoorden.trefwoord`, zullen de VAC's hoger in het zoekresultaat staan. + +Alle property's van het type text worden standaard doorzoekbaar gemaakt. Het is raadzaam deze standaard instellingen na te lopen. Vooral bij Kennisartikelen (waarvan het object gebaseerd is op de API van de SDG invoervoorziening) zijn er veel text property's, die niet relevant zijn voor de zoekresultaten. diff --git a/docs/configuration/identity-provider.md b/docs/configuration/identity-provider.md new file mode 100644 index 0000000..22827e8 --- /dev/null +++ b/docs/configuration/identity-provider.md @@ -0,0 +1,40 @@ +# Configuratie van uw Identity Provider +Bij de installatie van KISS regelt u de koppeling met uw OpenIDConnect Identity Provider. Daarnaast moet u in uw Identity Provider configureren dat gebruikers die in moeten kunnen loggen bij KISS in ieder geval een 'klantcontactmedewerker'-rol hebben. Een rol is in dit geval een claim van het type `role` of `roles` (beiden worden ondersteund). De waarde die correspondeert met een kiss-medewerker kunt u instellen tijdens de installatie. Standaard is dit `Klantcontactmedewerker`. Voor medewerkers die beheertaken op KISS uitvoeren, is een aparte rol ingeregeld. Ook de naam van deze rol kunt u instellen tijdens de installatie. Standaard is dit `Redacteur`. + +Als een ingelogde gebruiker wel de startpagina ziet, maar vervolgens alleen maar spinners blijft zien, dan heeft deze gebruiker niet de juiste rollen. + +## Claims uit uw Identity provider +KISS gebruikt de claims uit uw Identity Provider om de gegevens van de ingelogde Klantcontactmedewerker toe te voegen aan de Contactmomenten en Contactverzoeken die vanuit KISS worden geregistreerd. +Zie [de installatiehandleiding](INSTALLATION.md#Authenticatie) voor hoe u dit configureert. + +Er is in JWT geen standaard claim voor voorletters of voorvoegsel (tussenvoegsel). KISS gebruikt daarom deze mapping: +- Voorletters => given_name +- Achternaam => family_name indien beschikbaar, anders name indien beschikbaar, anders http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name +- Op dit moment doen we niets met Tussenvoegsel, omdat er geen voorvoegsel-claim bestaat. In de huidige implementatie komt tussenvoegsel alleen in het contactmoment, als het onderdeel is van de Achternaam. + + +## Voorbeeldinrichting in Azure Active Directory +Als u gebruik maakt van Azure Active Directory als Identity Provider, kunt u dit op de volgende manier inrichten. + +1. Bij de installatie van KISS heeft u een App Registration aangemaakt. Ga binnen Azure AD naar App registrations en klik op de applicatie. + + ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-01.png) + +1. Navigeer naar App roles, kies Create app role en vul de benodigde velden in. Belangrijk is dat u kiest voor Users/Groups bij Allowed member types en bij Value kiest voor de rol die u bij de installatie geconfigureerd hebt (standaard `Klantcontactmedewerker`). + + ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-02.png) + +1. Herhaal de vorige stap voor de rol die u tijdens de installatie heeft geconfigureerd voor medewerkers die beheertaken uitvoeren (standaard `Redacteur`) +1. Nu kunt u deze rollen toekennen aan gebruikers of groepen uit uw organisatie. Hiervoor moet u eerst terug naar Azure Active Directory. Navigeer daar naar Enterprise applications. + + ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-03.png) + +1. In dit scherm vindt u een applicatie met dezelfde naam als de App registration die u eerder heeft aangemaakt. Klik op de applicatie. + + ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-04.png) + +1. Navigeer naar Users and groups, en klik op Add user/group. + + ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-05.png) + +1. In dit scherm kunt u de rollen die u eerder gedefinieerd heeft, toekennen aan individuele gebruikers en - als uw licentie van Active Directory dit toestaat - groepen. \ No newline at end of file diff --git a/docs/configuration/objecten.md b/docs/configuration/objecten.md index 4e87c13..000658d 100644 --- a/docs/configuration/objecten.md +++ b/docs/configuration/objecten.md @@ -1,11 +1,7 @@ -# Configuratie -Bij de installatie van KISS worden er een groot aantal dingen al geconfigureerd. Op deze pagina staan verschillende onderdelen van de configuratie toegelicht. - - -## Configuratie t.b.v. Objecten API +# Configuratie t.b.v. Objecten API KISS maakt voor de koppeling met verschillende registraties gebruik van de Objecten API. Om objecten van een bepaald objecttype op te kunnen halen, moet het de URL weten van dat objecttype in de Objecttype API. Zie ook [de Installatiehandleiding](https://kiss-klantinteractie-servicesysteem.readthedocs.io/en/latest/INSTALLATION/) en de [documentatie bij KISS-Elastic-Sync](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/README.md) -### Authenticatie bij de Objecten API +## Authenticatie bij de Objecten API In de meeste gevallen identificeert KISS zich bij de Objectenregistratie m.b.v. een TOKEN. In sommige gevallen is het nodig om de authenticatie in de Objecten API, voor Afdelingen, Groepen en Interne Taken, Medewerkers in te regelen m.b.v. een client secret en een client id. Dit is bv. het geval als je KISS gebruikt i.c.m. de e-Suite. Afhankelijk van de situatie moet je dus een Token inregelen, en in andere gevallen een id+secret. **NOOIT ALLEBEI!** @@ -24,7 +20,7 @@ MEDEWERKER_OBJECTEN_TOKEN - Bij gebruik in combinatie met de e-suite, met een in de e-suite ingesteld secret en id MEDEWERKER_OBJECTEN_CLIENT_SECRET
MEDEWERKER_OBJECTEN_CLIENT_ID -### URL configureerbaar +## URL configureerbaar Voor een aantal objecttypen kunt u de URL van het objecttype instellen m.b.v. environment variabelen. | Variabele | Toelichting | @@ -35,82 +31,10 @@ Voor een aantal objecttypen kunt u de URL van het objecttype instellen m.b.v. en | AFDELINGEN_OBJECT_TYPE_URL | Objecttype dat gebruikt wordt om Afdelingen op te halen
voor gebruik in Contactverzoeken, Formulieren
contactverzoek en registratie van Contactmomenten | | SDG_OBJECT_TYPE_URL | Objecttype dat gebruikt wordt om Kennisartikelen op te halen;
dit objecttype is gebaseerd op het object `product`
in de SDG Invoervoorziening | -### URL nog niet configureerbaar +## URL nog niet configureerbaar Voor een aantal objecttype is de URL nog niet configureerbaar. In die gevallen zal KISS zelf de Objecttype API gaan bevragen om de URL op te halen. Hiervoor is het van belang dat de objecttypen in uw registratie de juiste naam hebben. | Naam Objecttype | Toelichting | |---|---| | VAC | Dit zijn de Vraag Antwoord Combinaties die via Elasticsearch ontsloten worden. | -| Medewerker | Dit zijn de medewerkers die via Elasticsearch ontsloten worden.
Deze medewerkers worden ook gebruikt in Contactverzoeken | - - -## Configuratie van uw Identity Provider -Bij de installatie van KISS regelt u de koppeling met uw OpenIDConnect Identity Provider. Daarnaast moet u in uw Identity Provider configureren dat gebruikers die in moeten kunnen loggen bij KISS in ieder geval een 'klantcontactmedewerker'-rol hebben. Een rol is in dit geval een claim van het type `role` of `roles` (beiden worden ondersteund). De waarde die correspondeert met een kiss-medewerker kunt u instellen tijdens de installatie. Standaard is dit `Klantcontactmedewerker`. Voor medewerkers die beheertaken op KISS uitvoeren, is een aparte rol ingeregeld. Ook de naam van deze rol kunt u instellen tijdens de installatie. Standaard is dit `Redacteur`. - -Als een ingelogde gebruiker wel de startpagina ziet, maar vervolgens alleen maar spinners blijft zien, dan heeft deze gebruiker niet de juiste rollen. - -### Claims uit uw Identity provider -KISS gebruikt de claims uit uw Identity Provider om de gegevens van de ingelogde Klantcontactmedewerker toe te voegen aan de Contactmomenten en Contactverzoeken die vanuit KISS worden geregistreerd. -Zie [de installatiehandleiding](INSTALLATION.md#Authenticatie) voor hoe u dit configureert. - -Er is in JWT geen standaard claim voor voorletters of voorvoegsel (tussenvoegsel). KISS gebruikt daarom deze mapping: -- Voorletters => given_name -- Achternaam => family_name indien beschikbaar, anders name indien beschikbaar, anders http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name -- Op dit moment doen we niets met Tussenvoegsel, omdat er geen voorvoegsel-claim bestaat. In de huidige implementatie komt tussenvoegsel alleen in het contactmoment, als het onderdeel is van de Achternaam. - - -### Voorbeeldinrichting in Azure Active Directory -Als u gebruik maakt van Azure Active Directory als Identity Provider, kunt u dit op de volgende manier inrichten. - -1. Bij de installatie van KISS heeft u een App Registration aangemaakt. Ga binnen Azure AD naar App registrations en klik op de applicatie. - - ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-01.png) - -1. Navigeer naar App roles, kies Create app role en vul de benodigde velden in. Belangrijk is dat u kiest voor Users/Groups bij Allowed member types en bij Value kiest voor de rol die u bij de installatie geconfigureerd hebt (standaard `Klantcontactmedewerker`). - - ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-02.png) - -1. Herhaal de vorige stap voor de rol die u tijdens de installatie heeft geconfigureerd voor medewerkers die beheertaken uitvoeren (standaard `Redacteur`) -1. Nu kunt u deze rollen toekennen aan gebruikers of groepen uit uw organisatie. Hiervoor moet u eerst terug naar Azure Active Directory. Navigeer daar naar Enterprise applications. - - ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-03.png) - -1. In dit scherm vindt u een applicatie met dezelfde naam als de App registration die u eerder heeft aangemaakt. Klik op de applicatie. - - ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-04.png) - -1. Navigeer naar Users and groups, en klik op Add user/group. - - ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/AzureAD-05.png) - -1. In dit scherm kunt u de rollen die u eerder gedefinieerd heeft, toekennen aan individuele gebruikers en - als uw licentie van Active Directory dit toestaat - groepen. - - -## Configuratie van Elasticsearch voor KISS -Met behulp van [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync) is het mogelijk om websites en een aantal gestructureerde bronnen doorzoekbaar te maken vanuit KISS. De eerste keer dat u deze tool gebruikt, wordt er een meta-engine aangemaakt met de naam `kiss-engine`. - -### Crawler -Het doorzoeken van een website binnen KISS wordt mogelijk door de website te crawlen vanuit Elastic Search. Hiervoor gebruikt u de [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync). Het is aan te raden om verder overleg te hebben met uw websitebeheerder, over het verdere finetunen van de crawler. Mogelijk zijn er aanpassingen nodig in uw robots.txt, is het raadzaam een KISS-specifieke sitemap.xml op te stellen of zijn er aanvullende filterinstellingen nodig. - -Op het moment dat de crawler de eerste keer gedraaid heeft, wordt het engine schema uitgebreid met de [velden die horen bij de crawler](https://www.elastic.co/guide/en/app-search/current/web-crawler-reference.html#web-crawler-reference-web-crawler-schema). - -### Syncen van bronnen -De eerste keer dat er via de synctool Kennisartikelen (PDC-producten), Medewerkers of VACs worden geindexeerd in Elastic, wordt het Engine Schema uitgebreid met een aantal velden. Dit zijn: -- `object_bron` - -- `object_meta` - -- De velden die bij de bron horen: voor elk property in het schema van de bron, wordt een property aangemaakt binnen de KISS-engine, voorafgegaan door de waarde van `objectbron`. - -### Relevance Tuning -Om de informatie uit de Kennisartikelen en websites doorzoekbaar te maken, moeten deze velden opgenomen zijn in het Engine Schema, en doorzoekbaar gezet in de Relevance tuning. Zijn er nieuwe velden toegevoegd aan het Engine Schema, bijvoorbeeld omdat er een nieuw type bron is toegevoegd? Dan moeten deze velden doorzoekbaar gemaakt worden, door op knop 'Update search settings' te klikken op de pagina Manage engine schema. U kunt ook op de pagina Relevance Tuning aangeven dat een schemaveld doorzoekbaar moet zijn. - -Om de zoekresultaten te beïnvloeden, moet u vervolgens de Relevance Tuning instellen. [Zie ook de documentatie van Elasticsearch](https://www.elastic.co/guide/en/app-search/current/relevance-tuning-guide.html) - -Elasticsearch zal binnen de meta-engine voor elk property van een object (een VAC, een medewerker of een Kennisartikel) een property aanmaken. Bijvoorbeeld `Kennisartikel.vertalingen.bezwaarEnBeroep` of `VAC.trefwoorden.trefwoord`. Elasticsearch zal ook zelf voor deze property's aangeven of ze doorzoekbaar moeten zijn of niet. Websitepagina's worden door de crawler aan de meta-engine toegevoegd, en zijn vindbaar via de velden van [het crawler-schema](https://www.elastic.co/guide/en/app-search/8.9/web-crawler-reference.html#web-crawler-reference-web-crawler-schema). - -Door vervolgens de relevantie van specifieke velden hoger te zetten, kunt u ervoor zorgen dat deze zwaarder meetellen in het zoekresultaat. Door de properties `VAC.trefwoorden.trefwoord` en `Kennisartikel.vertalingen.trefwoorden.trefwoord` hogere relevantiescore te geven, zullen de trefwoorden zwaarder meetellen. - -Doordat elke bron eigen properties krijgt in de meta-engine, kunt u specifieke bronnen zwaarder laten wegen. Als `VAC.trefwoorden.trefwoord` een hogere relevantiescore heeft dan `Kennisartikel.vertalingen.trefwoorden.trefwoord`, zullen de VAC's hoger in het zoekresultaat staan. - -Alle property's van het type text worden standaard doorzoekbaar gemaakt. Het is raadzaam deze standaard instellingen na te lopen. Vooral bij Kennisartikelen (waarvan het object gebaseerd is op de API van de SDG invoervoorziening) zijn er veel text property's, die niet relevant zijn voor de zoekresultaten. +| Medewerker | Dit zijn de medewerkers die via Elasticsearch ontsloten worden.
Deze medewerkers worden ook gebruikt in Contactverzoeken | \ No newline at end of file diff --git a/docs/manual/zztemp.md b/docs/manual/zztemp.md deleted file mode 100644 index 489b68e..0000000 --- a/docs/manual/zztemp.md +++ /dev/null @@ -1,408 +0,0 @@ -# Handleiding beheer KISS - -Als beheerder van KISS kan je de volgende zaken beheren: -- Nieuws en werkinstructies -- Skills -- Links -- Gespreksresultaten -- Formulier contactverzoeken -- Kanalen - -Per onderwerp leggen wij uit wat de mogelijkheden zijn en hoe je de werkzaamheden uitvoert. Om deze taken te kunnen uitvoeren moet je de rol `Redacteur` hebben (zie ook [Configuratie](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/CONFIGURATIE.md)). - -### KISS beheer vullen met voorbeelddata -Als je KISS voor het eerst hebt geïnstalleerd, en er bij Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten nog geen items zijn toegevoegd, is het mogelijk om eenvoudig voorbeelddata voor deze onderdelen te laden. Die doe je m.b.v. de knop op de startpagina. Met een druk op die knop zal de database met voorbeelddata worden gevuld voor Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten. Zodra de voorbeelddata is geladen, verdwijnt de optie/knop om (nogmaals) te vullen. - -#### Let op -De optie is alléén beschikbaar als de lijsten van Nieuws en Werkinstructies, Skills, Links en Gespreksresultaten echt leeg zijn. Een beheerder kan deze lijsten handmatig schonen, zodat ze weer leeg zijn. Skills vormen hierop een uitzondering: deze worden niet daadwerkelijk weggegooid, maar alleen verborgen voor de gebruiker. Dit om te voorkomen dat een Skill die al gekoppeld is aan een bericht, daarvan zal verdwijnen. Dit betekent dat verwijderde Skills nog onzichtbaar aanwezig zijn in de database, waardoor er geen initiële dataset geladen kan worden. Zodra je ee Skill hebt toegevoegd, is het dus niet meer mogelijk om voorbeelddata te laden. - - -## Nieuws en werkinstructies -Nieuwsberichten en werkinstructies zijn berichten die van belang kunnen zijn voor de klantcontactmedewerkers. Deze berichten komen voor de klantcontactmedewerkers op hun homepagina te staan. - -Op onderstaande afbeelding is de overzichtspagina van het beheer van nieuwsberichten en werkinstructies te zien. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-overzicht.jpg.jpg) - - -### Nieuwsbericht of werkinstructie toevoegen -Voeg een nieuwsbericht of werkinstructie toe door rechts bovenaan op de "Toevoegen" te drukken. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-toevoegen.jpg) - -Vervolgens kom je op onderstaand scherm. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-toevoegen-detail.jpg) - -Hieronder wordt elk invoerveld toegelicht. - - -**Het type:** Met het type kan je aangeven of je bericht een werkinstructie of nieuwsbericht is. - -**De titel:** Dit is de titel van je bericht. - -**Inhoud:** Hier plaats je de inhoud van je bericht. - -**Belangrijk:** Hiermee kan je aangeven of een bericht belangrijk is of niet. Handig voor dringende zaken bijvoorbeeld. Belangrijke berichten komen voor de klantcontactmedewerkers altijd bovenaan te staan, zodat de klantcontactmedewerker deze meteen zal zien staan. Ook vallen belangrijke berichten extra op. - -**Publicatiedatum:** Bij de publicatiedatum kan je de gewenste datum en tijd instellen waarop een bericht gepubliceerd moet worden. Dit kan handig zijn voor als je een bericht alvast wil schrijven, maar nog niet wil publiceren. Het bericht wordt dan automatisch aan de klantcontactmedewerkers gepubliceerd op de geselecteerde datum en tijd. - -**Publicatie-einddatum:** Dit is de einddatum van je bericht. Bij nieuwe berichten staat dit veld standaard ingevuld met een datum over één jaar, maar dit kan je aanpassen. Na deze datum zal het bericht verdwijnen uit het overzicht van de klantcontactmedewerkers. In de beheertabel blijft het bericht wel staan. - -**Skills:** Hiermee kan je het aangeven of jouw bericht bij een specifieke skill hoort, en zoja: welke. Je kan meerdere skills tegelijk selecteren. Dus als je bericht relevant is voor meerdere skills, kun je dat aangeven. Klantcontactmedewerkers kunnen op hun startpagina de berichten filteren op skills. Ze kunnen meerdere skills aanvinken, dan worden alle berichten getoond die bij één of meerdere skills horen. Als je een bericht niet aan een skill koppelt, is het bericht ook alleen zichtbaar voor de klantcontactmedewerkers die geen filter aan hebben staan. - - -### Nieuwsbericht of werkinstructie wijzigen -Een nieuwsbericht of werkinstructie kan je wijzigen door op het pijltje te klikken dat rechts in de tabel te zien is. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-wijzigen.jpg) - - -Vervolgens kom je op onderstaand scherm. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-wijzigen-detail.jpg) - - -Hieronder wordt elk invoerveld toegelicht. - -**Het type:** Met het type kan je aangeven of je bericht een werkinstructie of nieuwsbericht is. - -**De titel:** Dit is de titel van je bericht. - -**Inhoud:** Hier plaats je de inhoud van je bericht. - -**Belangrijk:** Hiermee kan je aangeven of een bericht belangrijk is of niet. Handig voor dringende zaken bijvoorbeeld. Belangrijke berichten komen voor de klantcontactmedewerkers altijd bovenaan te staan, zodat de klantcontactmedewerker deze meteen zal zien staan. Ook vallen belangrijke berichten extra op. - -**Publicatiedatum:** Bij de publicatiedatum kan je de gewenste datum en tijd instellen waarop een bericht gepubliceerd moet worden. Dit kan handig zijn voor als je een bericht alvast wil schrijven, maar nog niet wil publiceren. Het bericht wordt dan automatisch aan de klantcontactmedewerkers gepubliceerd op de geselecteerde datum en tijd. - -**Publicatie-einddatum:** Dit is de einddatum van je bericht. Na deze datum zal het bericht verdwijnen uit het overzicht van de klantcontactmedewerkers. In de beheertabel blijft het bericht wel staan. - -**Skills:** Hiermee kan je het aangeven of jouw bericht bij een specifieke skill hoort, en zoja: welke. Je kan meerdere skills tegelijk selecteren. Dus als je bericht relevant is voor meerdere skills, kun je dat aangeven. Klantcontactmedewerkers kunnen op hun startpagina de berichten filteren op skills. Ze kunnen meerdere skills aanvinken, dan worden alle berichten getoond die bij één of meerdere skills horen. Als je een bericht niet aan een skill koppelt, is het bericht ook alleen zichtbaar voor de klantcontactmedewerkers die geen filter aan hebben staan. - - - - -### Nieuwsbericht of werkinstructie verwijderen -Een nieuwsbericht of werkinstructie kan je verwijderen door op het prullenbak icoontje te klikken dat rechts in de tabel te zien is. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-verwijderen.jpg) - - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit bericht wilt verwijderen?". Hierbij klik je op 'ok'. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Nieuws-en-werkinstructies-beheer-verwijderen-popup.jpg) - -## Skills -Op de pagina 'Skills' kan je de skills beheren. Skills kunnen bijvoorbeeld de verschillende afdelingen binnen het klantcontactcentrum zijn, zoals 'burgerzaken' of 'werk en inkomen'. - -De skills die je hier aanmaakt kunnen vervolgens als filter gebruikt worden bij de nieuwsberichten en werkinstructies. - -Het kan zijn dat jouw gemeente niet werkt met skills. In dat geval hoef je hier niets te doen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-overzicht.jpg) - -### Skill toevoegen -Een skill voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-toevoegen.jpg) - -Vervolgens kom je op onderstaand scherm. Hier kan je de naam van de skill invullen. Druk op 'Opslaan' om de skill toe te voegen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-toevoegen-detail.jpg) - - -### Skill wijzigen -Een skill wijzig je door op de naam van de skill te klikken. - -![inage](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-wijzigen.jpg) - - -Vervolgens kom je op onderstaand scherm. Hier kan je de naam van de skill wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. Deze wijziging is meteen zichtbaar bij alle berichten waar deze skill aan is gekoppeld, en in het filtermenu. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-wijzigen-detail.jpg) - -### Skill verwijderen -Een skill kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van de skill staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-verwijderen.jpg) - - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit bericht wilt verwijderen?". Hierbij klik je op 'ok'. De skill verdwijnt uit het filtermenu en ook bij alle berichten waar het aan gekoppeld was. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Skills-beheer-verwijderen-popup.jpg) - - -## Links -Op de pagina 'Links' kan je de lijst met veelgebruikte links beheren. Hier kan je alle links neerzetten die voor jouw klantcontactmedewerkers handig zijn om altijd snel bij de hand te kunnen hebben. Denk bijvoorbeeld aan links naar bepaalde systemen of formulieren. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-overzicht.jpg) - -### Links toevoegen -Een link voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-toevoegen.jpg) - -Vervolgens kom je op onderstaand scherm. Hier kan je de titel, URL en de categorie van de link toevoegen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-toevoegen-detail.jpg) - -**Titel:** De naam waarmee de link in de lijst komt te staan. - -**Url:** De link naar de website. Een geldige URL begint altijd met https:// - -**Categorie:** De categorie waarin de link hoort. Als de link bij een al bestaande categorie hoort, typ je de naam van die categorie in. zodra je begint met typen, verschijnen de categorieën die beginnen met de letters die je typt. Je kunt dan snel de zelfde categorie kiezen. -Als je een andere categorie typt, wordt er automatisch een nieuwe categorie aangemaakt waar deze link onder valt. - -Druk op 'Opslaan' om de link toe te voegen. - - -### Links wijzigen -Een link wijzig je door op de naam van de link te klikken. - -![9mage](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-wijzigen.jpg) - - -Vervolgens kom je op onderstaand scherm. Hier kan je de link wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-wijzigen-detail.jpg) - - -**Titel:** De naam waarmee de link in de lijst komt te staan. - -**Url:** De link naar de website. - -**Categorie:** De categorie waarin de link hoort. Als de link bij een al bestaande categorie hoort, typ je de naam van die categorie in. zodra je begint met typen, verschijnen de categorieën die beginnen met de letters die je typt. Je kunt dan snel de zelfde categorie kiezen. -Als je een andere categorie typt, wordt er automatisch een nieuwe categorie aangemaakt waar deze link onder valt. - -### Links verwijderen -Een link kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van de link staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-verwijderen.jpg) - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u deze link wilt verwijderen?". Hierbij klik je op 'ok'. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Links-beheer-verwijderen-popup.jpg) - -## Gespreksresultaten -Op de pagina 'Gespreksresultaten' kan je de lijst met gespreksresultaten beheren. Met deze gespreksresultaten kunnen klantcontactmedewerkers aan het einde van hun contactmoment aangeven wat er met het gesprek is gebeurd, bijvoorbeeld zelfstandig afgehandeld of doorverbonden. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer.jpg) - -### Gespreksresultaat toevoegen -Een gespreksresultaat voeg je toe door op het plusje te klikken dat rechts onder in beeld staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-toevoegen.jpg) - -Vervolgens kom je op onderstaand scherm. Hier kan je de naam van het gespreksresultaat invullen. Druk op 'Opslaan' om het gespreksesultaat toe te voegen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-toevoegen-detail.jpg) - - -### Gespreksresultaat wijzigen -Een gespreksresultaat wijzig je door op de naam van het gespreksresultaat te klikken. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-wijzigen.jpg) - -Vervolgens kom je op onderstaand scherm. Hier kan je de naam van het gespreksresultaat wijzigen. Klik op 'Opslaan' om de wijziging door te voeren. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-wijzigen-detail.jpg) - -### Gespreksresultaat verwijderen -Een gespreksresultaat kan je verwijderen door op het prullenbak icoontje te klikken dat rechts van het gespreksresultaat staat. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-verwijderen.jpg) - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit gespreksresultaat wilt verwijderen?". Hierbij klik je op 'ok' - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Gespreksresultaten-beheer-verwijderen-popup.jpg) - - -## Formulieren contactverzoeken voor afdelingen en groepen -Bij ‘Formulieren contactverzoek afdelingen’ en ‘Formulieren contactverzoek groepen’ kan een beheerder van KISS formuliertjes aanmaken, die kunnen worden gebruikt in Contactverzoeken voor afdelingen en groepen. Het zijn eenvoudige formuliertjes, die een aantal extra vragen bevatten, waarmee je de KCM ondersteunt om al zoveel mogelijk relevante informatie mee te geven met het Contactverzoek. Dit zijn dus aanvullende vragen, op de vaste Contactverzoek-velden. - -Met de Vaste Contactverzoek velden geeft een KCM aan: - -1. Voor wie het Contactverzoek is: een afdeling, een groep of een medewerker -2. Een omschrijving waarover het gaat: dit is een toelichtingenveld waar informatie in staat, die alléén voor de collega is. -3. Met wie men contact moet opnemen: naam en contactgegevens van degene die teruggebeld (of teruggemaild, etc.) moet worden. - -Met een Contactverzoekformuliertje (of Vragenset) kan een KCM door een onderwerp te kiezen meer vragen stellen aan de klant, en zo een completer Contactverzoek invullen. Bijvoorbeeld: gaat een contactverzoek over een Parkeerbon? Dan is het handig om het nummer van de parkeerbon ook mee te geven. De klant voor wie het Contactverzoek wordt gemaakt, heeft dat meestal al bij de hand als hij contact opneemt met de gemeente. - -Bij beheer kun je deze formuliertjes (vragensets) aanmaken en beheren. -Hieronder volgt de handleiding voor het beheren van formulieren voor contactverzoeken voor afdelingen. Het beheren van van formulieren voor contactverzoeken voor groepen werkt op precies dezelfde manier. - -In het overzicht zie je de titel van het Contactverzoek, en de afdeling voor wie dit contactverzoek zou zijn. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-01.png) - -### Formulier toevoegen -Voeg een nieuw formulier toe door rechts bovenaan op de "Toevoegen" te drukken. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-02.png) - -Je komt op onderstaand scherm - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-03.png) - -In dit scherm moet je de Titel van het formulier opgeven. Deze titel beschrijft het onderwerp van het contactverzoek. Bijvoorbeeld: WMO, of Vraag voor Werk en inkomen. -Daaronder selecteer je de afdeling die bij deze contactverzoeken hoort. Deze lijst afdelingen, is dezelfde lijst afdelingen die een KCM gebruikt om aan te geven welke afdeling een Contactverzoek moet oppakken. - -Om een vraag toe te voegen, kies je eerst het vraagtype. Er zijn vier soorten vraagtypes: - -| Vraagtype | Uitleg | Voorbeeld | -|---|---|---| -| Open vraag kort | Invoerveld over één regel | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-open-kort.png) | -| Open vraag lang | Invoerveld over meerdere regels | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-open-lang.png) | -| Dropdown | Keuzelijst, waarin de KCM
maar één optie kan kiezen | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-dropdown.png) | -| Checkbox | Keuzelijst waarin de KCM
één of meer opties kan kiezen | ![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-checkbox.png) | - -Door in het veld Vraag toevoegen te klikken, klapt er een keuzelijst uit. Door één van de vraagtypes te kiezen, wordt er een vraag van dat vraagtype toegevoegd. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-04.png) - -- Voor alle vraagtypes geldt dat je de vraagtekst moet invullen. Dit is de tekst die in het uiteindelijke formulier boven het invoerveld komt te staan. -- Voor de Dropdown en de Checkbox moet je daarnaast óók minimaal twee antwoordopties opgeven. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-05.png) - -Met de knop Antwoordoptie Toevoegen kun je nog een optie toevoegen. De antwoordopties komen in het formulier in dezelfde volgorde waarin je ze bij aanmaken invoert. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-06.png) - -Als je alle vragen hebt ingesteld, klik je op Opslaan om het formulier op te slaan. Het formulier is meteen zichtbaar voor de KCM bij het aanmaken van een Contactverzoek. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-07.png) - -### Formulier wijzigen -Je kunt een formuliertje wijzigen door op het pijltje te klikken dat rechts in de tabel te zien is. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-08.png) - -Je komt in bewerkscherm van het formulier. Hier kun je bestaande vraagteksten wijzigen, de tekst van antwoord opties wijzigen en nieuwe vragen toevoegen. Ook kun je vragen of antwoord opties verwijderen. -Als je bijvoorbeeld de volgorde van antwoordopties in een meerkeuzevraag (dropdown of checkbox) wilt wijzigen, kun je de bestaande tekstjes verplaatsen. - - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-09.png) - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-10.png) - -Een vraag verwijder je door met de muis náást de vraag op het prullenbakje te klikken. Deze verschijnt als je met je muis achter het veld gaat staan. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-11.png) - -Een antwoordoptie verwijder je weer, door met de muist náást de antwoordoptie op het prullenbakje te klikken. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-12.png) - -Sla je je wijzigingen op met de Opslaan knop onderaan het formulier. Je wijzigingen zijn meteen zichtbaar, voor de KCM die een nieuw contactverzoek gaat aanmaken. Als een KCM al bezig was om met dat formulier een Contactverzoek te maken, kan die dat nog wel afmaken. - -### Formulier verwijderen -Je kunt een formulier verwijderen door op het prullenbak icoontje te klikken dat rechts in de tabel te zien is. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-13.png) - -Vervolgens komt er een pop-up, met de vraag: "Weet u zeker dat u dit contactformulier wilt verwijderen?". Hierbij klik je op 'ok' om het verwijderen te bevestigen. - -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/main/docs/images/Contactverzoek-beheren-14.png) - -Het formulier is niet meer beschikbaar voor de KCM die een nieuw Contactverzoek gaat maken. Als een KCM al bezig was om met dat formulier een Contactverzoek te maken, kan die dat nog wel afmaken. - -## Kanalen -Op de pagina 'kanalen' kan je de lijst met kanalen beheren. Met deze kanalen kunnen klantcontactmedewerkers aan het einde van hun contactmoment aangeven via welk kanaal het contact heeft plaatsgevonden, bijvoorbeeld telefonisch of via e-mail. - -KISS hanteert een standaardlijst Kanalen, waaruit je kunt kiezen bij het registreren van een Contactmoment. Als je zelf geen kanalen toevoegt of alle kanalen verwijdert, dan zal KISS automatisch deze standaardlijst gebruiken. Deze lijst bevat de volgende kanalen: - -- Telefoon -- E-mail -- Contactformulier -- Twitter -- Facebook -- LinkedIn -- Live chat -- Instagram -- WhatsApp - - -### Kanalen toevoegen, wijzigen en verwijderen -Het toevoegen, wijzigen of verwijderen van kanalen gaat op een gelijksoortige manier als het toevoegen, wijzigen of verwijderen van Skills of gespreksresultaten. - -Let op: als je KISS gebruikt in combinatie met een bronregister, waarin ook kanalen aanwezig zijn (geconfigureerd of een vaste lijst kanalen), let dan goed op of het van belang is dat de schrijfwijze van een kanaal in KISS exact moet overeenkomen met kanaal in het bronregister. In dat geval moet je ook letten op hoofdletters, kleine, spaties en streepjes. - -## Vacs -Op de pagina 'Vacs' kan je Vraag-Antwoord-Combinaties beheren die zijn opgeslagen in het bij de KISS-installatie geconfigureerde Objectenregister. De lijst op de Vac-overzichtspagina toont alle Vacs. Door middel van de toetsenbord combinatie `Ctrl + f` kun je in de lijst zoeken naar de vraag die bij de Vraag-Antwoord-Combinatie hoort. - -#### Let op -Deze optie is alleen beschikbaar, als deze is aangezet bij de installatie/configuratie van KISS. Dit gebeurt m.b.v. een Environment Variabele. Zie ook [de installatiehandleiding](INSTALLATION.md#kiss-frontend), bij USE_VACS - -### Vacs toevoegen, wijzigen en verwijderen -Het toevoegen, wijzigen of verwijderen van Vacs gaat op een gelijksoortige manier als het toevoegen, wijzigen of verwijderen van Skills of gespreksresultaten. - -## Zoeken in bronnen -Binnen KISS kan een Klantcontactmedewerker zoeken in verschillende bronnen. KISS ondersteund op dit moment de volgende bronnen: de gemeentelijke website, in het smoelenboek van de gemeente, kennisartikelen in een Product-format en in Vraag-AntwoordCombinaties (VAC's). Het koppelen van deze bronnen moet gedaan worden door een technisch beheerder, in het kubernetescluster. Als de standaard installatieprocedure gevolgd is, draait er elk uur een taak (job) waardoor de bronnen worden gesyncrhoniseerd in de zoekindex. Bij onverwachte resultaten of foutmeldingen kan je de beheerder van het kubernetescluster vragen om de logging in te zien van de laatste synchronisatiepoging (job) van de [KISS-Elastic-Sync tool](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync). Daarin is terug te vinden hoe de synchronisatiepoging is verlopen. - -## Managementinformatie -Bij het opslaan van Contactmomenten worden enkele gegevens, die geen plek hebben in de standaarden rondom Klantinteracties, opgeslagen binnen KISS zelf. (zie ook het [onderdeel Contactmomentdetails in Decision Record](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/DECISION-RECORD.md#contactmomentdetails)). Deze gegevens leveren managementinformatie over de werkzaamheden van het KCC. - -Binnen KISS is een API endpoint beschikbaar waarmee deze gegevens opgevraagd kunnen worden. Dit endpoint is benaderbaar op: `https://www.kissbijdegemeente.nl/api/contactmomentendetails`. - -### Authenticatie - -De Contactmomentendetails API is beveiligd en vereist een JWT Bearer Token voor toegang. Dit token wordt gegenereerd op basis van een geheime sleutel (secret) die door KISS wordt verstrekt aan de externe systemen. Dit secret is configureerbaar via de environment variabele `MANAGEMENTINFORMATIE_API_KEY` (zie installatiehandleiding) - -#### Structuur van de JWT - -De JWT bestaat uit drie delen, gescheiden door punten: - -1. **Header**: Bevat informatie over het algoritme dat gebruikt wordt om het token te ondertekenen, in dit geval HS256. - ```json - { - "alg": "HS256", - "typ": "JWT" - } - ``` - -2. **Payload**: De gegevens van de gebruiker of het systeem dat toegang probeert te verkrijgen. De payload bevat het `iat` (issued at) veld met de timestamp van het moment waarop het token is aangemaakt, en het `exp` (expiration) veld om de geldigheidsduur van het token te beperken. - - ```json - { - "iat": 1728580531, - "exp": 1728666931 - } - ``` - - - `iat`: Tijdstip van aanmaak van het token (in UNIX-timestamp). - - `exp`: Verloopdatum van het token (in UNIX-timestamp), na welke het token niet meer geldig is. - -3. **Signature**: De handtekening, gegenereerd op basis van de header, payload, en een geheime sleutel (secret) die wij verstrekken. Dit zorgt ervoor dat het token niet kan worden gewijzigd door een derde partij. - -> **Opmerking:** Het is aan te raden om de `exp` waarde zo in te stellen dat het token slechts een beperkte tijd geldig is, om het risico op misbruik te verkleinen. - -#### Headers voor de API-aanroep - -Zorg ervoor dat je de volgende headers meestuurt met elke API-aanroep: - -```plaintext -Authorization: Bearer {JWT-Token} -Accept: */* -Cache-Control: no-cache -``` - -Vervang `{JWT-Token}` door het daadwerkelijke token dat je hebt gegenereerd. - -### Query Parameters - -| Parameter | Type | Verplicht? | Standaard | Omschrijving | -|------------|--------|------------|------------|------------------------------------------------------------| -| `from` | string | Ja | - | De startdatum in ISO 8601 formaat (bijv. `yyyy-MM-ddTHH:mm:ssZ`). | -| `to` | string | Ja | - | De einddatum in ISO 8601 formaat (bijv. `yyyy-MM-ddTHH:mm:ssZ`). | -| `pageSize` | int | Nee | 5000 | Het aantal resultaten per pagina, maximaal 5000. | -| `page` | int | Nee | 1 | De pagina van de resultaten die moet worden opgehaald. | - -### Voorbeeld Request - -``` -GET /api/contactmomentendetails?from=2024-10-01T00:00:00Z&to=2024-10-10T23:59:59Z&pageSize=100&page=1 -Authorization: Bearer {JWT-Token} -``` - -Let erop dat de `Authorization` header met de waarde `Bearer {JWT-Token}` wordt toegevoegd bij elk request. From 6fe30afba07075c13d2040c9c9e1c0ad6547ab2d Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Thu, 20 Feb 2025 09:34:03 +0100 Subject: [PATCH 21/30] folder security --- docs/{SECURITY.md => security/security.md} | 76 +++++++++++----------- 1 file changed, 38 insertions(+), 38 deletions(-) rename docs/{SECURITY.md => security/security.md} (99%) diff --git a/docs/SECURITY.md b/docs/security/security.md similarity index 99% rename from docs/SECURITY.md rename to docs/security/security.md index 47b1ae5..77c49df 100644 --- a/docs/SECURITY.md +++ b/docs/security/security.md @@ -1,38 +1,38 @@ -# Security considerations - -## Snyk -Snyk is configured to automatically check every Pull Request on new vulnerabilities. - -### Vulnerabilities -#### Anti-forgery token validation disabled -Details: https://app.snyk.io/org/klantinteractie-servicesysteem/project/9d7a9bac-d697-48c5-b542-03de24e608d1
Addendum: In razor these tokens are part of the framework, we use VueJs3
-Impact: Very low, we use Same-Site strict policy and this site is not exposed to the internet
- - -## OWASP Docker Top 10 -### Introduction -The 10 most common and exploited docker vulnerabilities are maintained by the OWASP Docker Top 10. The overview shows a quick summary of these including the title, description and how / if we have implemented this. - -Details need to be fleshed out in seperate md's in /security/docker/1-10 - -### Overview -| Title | Description | Implementation -| -- | -- | -- | -| D01 - Secure User Mapping | [Source](https://github.com/OWASP/Docker-Security/blob/main/D01%20-%20Secure%20User%20Mapping.md) Most often the application within the container runs with the default administrative privileges: root. This violates the least privilege principle and gives an attacker better chances further extending his activities if he manages to break out of the application into the container. From the host perspective the application should never run as root.
| [Details](\security\docker\D01 - Secure User Mapping.md) Check if dockerfile contains a user
Check if --privileged is not used.
Following documentation from .Net Core we make sure the application does not run as root user -| D02 - Patch Management Strategy | [Source](https://github.com/OWASP/Docker-Security/blob/main/D02%20-%20Patch%20Management%20Strategy.md) The host, the containment technology, the orchestration solution and the minimal operating system images in the container will have security bugs. Once publicly known it is vital for your security posture to address those bugs in a timely fashion. For all those components mentioned you need to decide when you apply regular and emergency patches before you put those into production. | We use Snyk with automated PR's for docker images, containers, Kubernetes and Host OS.

- Critical vulnerabilities need to be fixed within X days.
- High vulnerabilities need to be fixed within X days.
- Medium/low vulnerabilities need to be fixed within X days.
- Library package updates are updated automatically by Snyk and deployed and tested after:
1: During development of next new story. Or
2: Periodically every X months/weeks -| D03 - Network Segmentation and Firewalling | [Source](https://github.com/OWASP/Docker-Security/blob/main/D03%20-%20Network%20Segmentation%20and%20Firewalling.md) You properly need to design your network upfront. Management interfaces from the orchestration tool and especially network services from the host are crucial and need to be protected on a network level. Also make sure that all other network based microservices are only exposed to the legitimate consumer of this microservice and not to the whole network. | We use Azure kubernetes, we need to check how we can comply with this demand in our environment > Not relevant for the current project phase -| D04 - Secure Defaults and Hardening | [Source](https://github.com/OWASP/Docker-Security/blob/main/D04%20-%20Secure%20Defaults%20and%20Hardening.md) Depending on your choice of host and container operating system and orchestration tool you have to take care that no unneeded components are installed or started. Also all needed components need to be properly configured and locked down. | We have made list of the project OS, platform and libraries and there respective End-of-life-dates. See table beneath this page | -| D05 - Maintain Security Contexts | [Source](https://github.com/OWASP/Docker-Security/blob/main/D05%20-%20Maintain%20Security%20Contexts.md) Mixing production containers on one host with other stages of undefined or less secure containers may open a backdoor to your production. Also mixing e.g. frontend with backend services on one host may have negative security impacts. | We don't have multiple environments in 1 cluster, they are always seperated. -| D06 - Protect Secrets | [Source](https://github.com/OWASP/Docker-Security/blob/main/D06%20-%20Protect%20Secrets.md) Authentication and authorization of a microservice against a peer or a third party requires secrets to be provided. For an attacker those secrets potentially enable him to access more of your data or services. Thus any passwords, tokens, private keys or certificates need to be protected as good as possible. | Local variables at the moment, our production story contains a special section about implementing k8s secrets -| D07 - Resource Protection | [Source](https://github.com/OWASP/Docker-Security/blob/main/D07%20-%20Resource%20Protection.md) As all containers share the same physical CPU, disks, memory and networks. Those physical resources need to be protected so that a single container running out of control -- deliberately or not -- doesn't affect any other container's resources. | Resources are limited through the Helm configuration | -| D08 - Container Image Integrity and Origin | The minimal operating system in the container runs your code and needs to be trustworthy, starting from the origin up until the deployment. You need to make sure that all transfers and images at rest haven't been tampered with. | We use Snyk for scanning and also for base images checks. Depending on those results we will update this section. -| D09 - Follow Immutable Paradigm | Often container images don't need to write into their filesystem or a mounted filesystem, once set up and deployed. In those cases you have an extra security benefit if you start the containers in read-only mode. | Our BF front- and backend are stateless and can be considered to be marked readonly because we do not process any files at the moment. -| D10 - Logging | For your container image, orchestration tool and host you need to log all security relevant events on a system and API level. All logs should be remote, they should contain a common timestamp and they should be tamper proof. Your application should also provide remote logging. | We will be using Prometheus and Loki as our own logging stack. - -## D04 -| Product | Version | End-of-life | Link | -| -- | -- | -- | -- | -| Alpine Linux | 3.18 | May 9, 2025 | https://alpinelinux.org/releases/ | -| NodeJS | 18.16 | April 30, 2025 | https://nodejs.dev/en/about/releases/ | -| .Net Core | 6 | November 12, 2024 | https://learn.microsoft.com/en-us/lifecycle/products/microsoft-net-and-net-core | -| Kubernetes | 1.27 | July, 2024 | https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar | +# Security considerations + +## Snyk +Snyk is configured to automatically check every Pull Request on new vulnerabilities. + +### Vulnerabilities +#### Anti-forgery token validation disabled +Details: https://app.snyk.io/org/klantinteractie-servicesysteem/project/9d7a9bac-d697-48c5-b542-03de24e608d1
Addendum: In razor these tokens are part of the framework, we use VueJs3
+Impact: Very low, we use Same-Site strict policy and this site is not exposed to the internet
+ + +## OWASP Docker Top 10 +### Introduction +The 10 most common and exploited docker vulnerabilities are maintained by the OWASP Docker Top 10. The overview shows a quick summary of these including the title, description and how / if we have implemented this. + +Details need to be fleshed out in seperate md's in /security/docker/1-10 + +### Overview +| Title | Description | Implementation +| -- | -- | -- | +| D01 - Secure User Mapping | [Source](https://github.com/OWASP/Docker-Security/blob/main/D01%20-%20Secure%20User%20Mapping.md) Most often the application within the container runs with the default administrative privileges: root. This violates the least privilege principle and gives an attacker better chances further extending his activities if he manages to break out of the application into the container. From the host perspective the application should never run as root.
| [Details](\security\docker\D01 - Secure User Mapping.md) Check if dockerfile contains a user
Check if --privileged is not used.
Following documentation from .Net Core we make sure the application does not run as root user +| D02 - Patch Management Strategy | [Source](https://github.com/OWASP/Docker-Security/blob/main/D02%20-%20Patch%20Management%20Strategy.md) The host, the containment technology, the orchestration solution and the minimal operating system images in the container will have security bugs. Once publicly known it is vital for your security posture to address those bugs in a timely fashion. For all those components mentioned you need to decide when you apply regular and emergency patches before you put those into production. | We use Snyk with automated PR's for docker images, containers, Kubernetes and Host OS.

- Critical vulnerabilities need to be fixed within X days.
- High vulnerabilities need to be fixed within X days.
- Medium/low vulnerabilities need to be fixed within X days.
- Library package updates are updated automatically by Snyk and deployed and tested after:
1: During development of next new story. Or
2: Periodically every X months/weeks +| D03 - Network Segmentation and Firewalling | [Source](https://github.com/OWASP/Docker-Security/blob/main/D03%20-%20Network%20Segmentation%20and%20Firewalling.md) You properly need to design your network upfront. Management interfaces from the orchestration tool and especially network services from the host are crucial and need to be protected on a network level. Also make sure that all other network based microservices are only exposed to the legitimate consumer of this microservice and not to the whole network. | We use Azure kubernetes, we need to check how we can comply with this demand in our environment > Not relevant for the current project phase +| D04 - Secure Defaults and Hardening | [Source](https://github.com/OWASP/Docker-Security/blob/main/D04%20-%20Secure%20Defaults%20and%20Hardening.md) Depending on your choice of host and container operating system and orchestration tool you have to take care that no unneeded components are installed or started. Also all needed components need to be properly configured and locked down. | We have made list of the project OS, platform and libraries and there respective End-of-life-dates. See table beneath this page | +| D05 - Maintain Security Contexts | [Source](https://github.com/OWASP/Docker-Security/blob/main/D05%20-%20Maintain%20Security%20Contexts.md) Mixing production containers on one host with other stages of undefined or less secure containers may open a backdoor to your production. Also mixing e.g. frontend with backend services on one host may have negative security impacts. | We don't have multiple environments in 1 cluster, they are always seperated. +| D06 - Protect Secrets | [Source](https://github.com/OWASP/Docker-Security/blob/main/D06%20-%20Protect%20Secrets.md) Authentication and authorization of a microservice against a peer or a third party requires secrets to be provided. For an attacker those secrets potentially enable him to access more of your data or services. Thus any passwords, tokens, private keys or certificates need to be protected as good as possible. | Local variables at the moment, our production story contains a special section about implementing k8s secrets +| D07 - Resource Protection | [Source](https://github.com/OWASP/Docker-Security/blob/main/D07%20-%20Resource%20Protection.md) As all containers share the same physical CPU, disks, memory and networks. Those physical resources need to be protected so that a single container running out of control -- deliberately or not -- doesn't affect any other container's resources. | Resources are limited through the Helm configuration | +| D08 - Container Image Integrity and Origin | The minimal operating system in the container runs your code and needs to be trustworthy, starting from the origin up until the deployment. You need to make sure that all transfers and images at rest haven't been tampered with. | We use Snyk for scanning and also for base images checks. Depending on those results we will update this section. +| D09 - Follow Immutable Paradigm | Often container images don't need to write into their filesystem or a mounted filesystem, once set up and deployed. In those cases you have an extra security benefit if you start the containers in read-only mode. | Our BF front- and backend are stateless and can be considered to be marked readonly because we do not process any files at the moment. +| D10 - Logging | For your container image, orchestration tool and host you need to log all security relevant events on a system and API level. All logs should be remote, they should contain a common timestamp and they should be tamper proof. Your application should also provide remote logging. | We will be using Prometheus and Loki as our own logging stack. + +## D04 +| Product | Version | End-of-life | Link | +| -- | -- | -- | -- | +| Alpine Linux | 3.18 | May 9, 2025 | https://alpinelinux.org/releases/ | +| NodeJS | 18.16 | April 30, 2025 | https://nodejs.dev/en/about/releases/ | +| .Net Core | 6 | November 12, 2024 | https://learn.microsoft.com/en-us/lifecycle/products/microsoft-net-and-net-core | +| Kubernetes | 1.27 | July, 2024 | https://learn.microsoft.com/en-us/azure/aks/supported-kubernetes-versions?tabs=azure-cli#aks-kubernetes-release-calendar | From 6df38e9900d8ddf1cc9d81b1992782f4b52063c7 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Thu, 20 Feb 2025 09:38:08 +0100 Subject: [PATCH 22/30] Finalize move from mkdocs to sphinx --- .readthedocs.yml | 29 ++++-- docs/index.md | 14 --- docs/index.rst | 17 ++++ docs/makefile | 225 ++++++++++++++++++++++++++++++++++++++++++ docs/requirements.txt | 7 +- mkdocs.yml | 14 --- 6 files changed, 267 insertions(+), 39 deletions(-) delete mode 100644 docs/index.md create mode 100644 docs/index.rst create mode 100644 docs/makefile delete mode 100644 mkdocs.yml diff --git a/.readthedocs.yml b/.readthedocs.yml index c627e32..36da39c 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,18 +1,31 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +# onderstaande gevuld o.b.v. wat ik lees op: +# https://docs.readthedocs.io/en/stable/intro/sphinx.html - +# Required version: 2 -# Set the version of Python and other tools you might need +# Set the OS, Python version and other tools you might need build: - os: ubuntu-22.04 + os: ubuntu-24.04 tools: - python: "3.11" + python: "3.12" + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py -mkdocs: - configuration: mkdocs.yml - fail_on_warning: false +# met bovenstaande is mkdocs.yml niet meer nodig. Want die hoort bij +# mkdocs, en we doen nu dus sphinx +# overgenomen uit sphinx_rtd_theme/.readthedocs.yml -# Optionally declare the Python requirements required to build your docs python: install: - requirements: docs/requirements.txt diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 1209e44..0000000 --- a/docs/index.md +++ /dev/null @@ -1,14 +0,0 @@ -# KISS Documentatie -Het Klant Interactie Service Systeem (KISS) is een applicatie waarmee Klantcontactmedewerkers (KCM) optimaal worden ondersteund in hun werk: het informeren en helpen van burgers en ondernemers die contact opnemen met de gemeente. Doel van KISS is om alle informatie die een KCM nodig heeft voor die taak, zoveel mogelijk binnen KISS zelf te ontsluiten. Het is ontwikkeld als een Common Ground component in opdracht van [de gemeente Utrecht en Dimpact](https://www.dimpact.nl/klantinteractie-servicesysteem). - -## Documentatie - -- [Installatie](INSTALLATION.md) -- [Configuratie](CONFIGURATIE.md) -- [Handleiding beheer](MANUAL.md) -- [Architectuur](Architectuur.md) -- [Ontwerpbeslissingen](DECISION-RECORD.md) -- [Definition of Done](DEFINITIONOFDONE.md) -- [Security](SECURITY.md) - - diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..06af6e6 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,17 @@ +KISS Documentatie +================= + +Het Klant Interactie Service Systeem (KISS) is een applicatie waarmee Klantcontactmedewerkers (KCM) optimaal worden ondersteund in hun werk: het informeren en helpen van burgers en ondernemers die contact opnemen met de gemeente. Doel van KISS is om alle informatie die een KCM nodig heeft voor die taak, zoveel mogelijk binnen KISS zelf te ontsluiten. Het is ontwikkeld als een Common Ground component in opdracht van `de gemeente Utrecht en Dimpact `__. + +.. toctree:: + :caption: KISS Documentatie + :maxdepth: 2 + :hidden: + + installation/installation + configuration/configuration + manual/manual + architectuur/architectuur.md + decision-record/decision-record + definition-of-done/definition-of-done.md + security/security.md diff --git a/docs/makefile b/docs/makefile new file mode 100644 index 0000000..acacc74 --- /dev/null +++ b/docs/makefile @@ -0,0 +1,225 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " epub3 to make an epub3" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +.PHONY: qthelp +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxwithMarkdown.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxwithMarkdown.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxwithMarkdown" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxwithMarkdown" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: dummy +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." diff --git a/docs/requirements.txt b/docs/requirements.txt index b4727c4..c0ddbcd 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,7 @@ -jinja2==3.1.4 -mkdocs>=1.3.1 +sphinx>=7.1,<7.2 +sphinx_rtd_theme +myst-parser +jinja2==3.1.3 babel>=2.11.0 click>=7.0 Jinja2>=2.10.2 @@ -15,4 +17,3 @@ packaging>=20.5 mergedeep>=1.3.4 pygments>=2.12 pymdown-extensions -mkdocs-material diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index d21bf5a..0000000 --- a/mkdocs.yml +++ /dev/null @@ -1,14 +0,0 @@ -site_name: Klantinteractie Servicesysteem -site_url: https://readthedocs.org/projects/klantinteractie-servicesysteem/ - -nav: - - Home: index.md - - Installatie: INSTALLATION.md - - Configuratie: CONFIGURATIE.md - - Handleiding beheer: MANUAL.md - - Architectuur: Architectuur.md - - Ontwerpbeslissingen: DECISION-RECORD.md - - Definition of Done: DEFINITIONOFDONE.md - - Security: SECURITY.md - -theme: readthedocs From 9ab1bde00f89a1ae30d3cb756dab2e14c3508ffc Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Thu, 20 Feb 2025 09:55:34 +0100 Subject: [PATCH 23/30] added logo png --- docs/logo.png | Bin 0 -> 4406 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/logo.png diff --git a/docs/logo.png b/docs/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..dbbe3c09a40390c71555126e3a59fb840d075540 GIT binary patch literal 4406 zcmcIo`9Boi_eO}ZmO&`li5bEuB>OIFjIlNL>}20Z7_x^bdrTxIhHOKUiHeMEWX+m= z-`BxsdjAdI?+@qR`?~ks?L6l`=e%x$k%1NifD=GQM#i9{t!_f9fBq913R1}@FV{sz z#(b`$u3{RTzh2<&!4eYsgCXJB(>TYN9Y^vd`)_iPz+4}F)h4qpq4&Ca6czrdG!hw^ zww1qhzVez)a9^L$U0;EkCsbAp5_aupsgC#}2GAK_#;&}p5`UQmc>Z<{6xjSsC;vMr zPjZUb?hwsVo-tc%A)Ld}r_i=T3{jNe^ZBl%#DO?h=u?P{>;p#nKJZdwcDc7SLDrG~ z7Q@WCqb4!<1q!|&|@7!9l=ajGMUf`VB&+a zL&N#l(ozf!l7(5U748*2dh`KKu-Oc#E#34rw7`yR>{vqG@<8?HV)(tCgq{BW$>WY- zg?rhHA%oS+{xx2Gn~Az@eV0!+eVJBX6PU7@p;GM(Obl_G(*(^&T(kZ)iU>3PjmV<5 z#FCZpoMHxNwtotY`)R4MsPy=g2En}5=D6JP)41=8;asW!7656Vm@5dH$+q`u51n|A zF^g(iJ?w(|g6L&!S%`m-&kR#Ya!|L=>##hgTlX@rNGD)Q_-EZC9-amn&&k?&xMNzI ztJ*0!-pnGM7A1;6A4z%nK;B_8Xsgb41sMeDO`gC< z;vhwQ1wC>$9#%^UtIg-?a3m!)3p97hd+K=K63(<<3)FA9go(h#T|-@Si(NE({fdOj zGX7-z%w9Woa4jTV#}4oA;^D>6z*YIeTfk033paTiQMY+N2(WEN{fE1H+pnb(=!j<( za&Xv5fI)We%3r6J9Q8>bxPjB%BOZJ~Y_;u#Wvv-OCi_R%E9p&-D;?zp4ruteZZ4Z| zb zYqeMTa%Sm1E5gz;W<$POYuOy;CVnoG>lM1>AA^t&;K3^(DlxG5$&LKJ`p~#4F;GlRMO`Y zTaMgUxz-QC9qWUsQfZB4fo(=!S(oV9vmn>pol{Zm+-xrST^P2ad&NGcK-kS6G5aw& z*kirB6Vcrju(E1mEWs^iZe}(zTtw`ge!U{m7**2bIPv`ZVowr#&1Fh=xURnd`gU6> zo!!Da(ZsULidNKy@K!GWVS;U=_s$3rOX$?p;ud$5@-4j1aj~`WYdRpK(IA=_kIOf$ z_kSL-`8kv7!p(3=0Q+J3;;+O)e5dqQ(UI9ARw#d|pkMAo#jGu1j7b8fZ>D!!xM6=i zp1s0-&50Ya0Qc4F)qdG$BrDrLedgVk8RDb2UCxS|)*Riiazh-mH<(w?4;iyd<;)hh zT;)VKHcrUYc-`7vtReYh<5@*dOw6qxRxv+ltQ^TKCsON)$L0C_nY5eTopkfy@t4G4 zv}5$yMzzwLyqt7DAFYwD7{m!<2r5|x*``}IZMpeu;ao3pW4y_oA&}tNt!szC%kR~=(W~b>z&>BzHNNy_+y(99^v$@ zi{lKT#Zkz05}9;iuhR$KY@9iYGOBC1mHDV4dx~aRf1axtiJ2!#GF;8ewMuodO|~FC zS_9?JA%Bm?>6!S&L3U42$C9{qxQp6!rFhCtOfORmW$wl`Vdk4Evuz(xt1!<~ zs(a?MS=edt4+>J-_1-X+Mqkm8&hXqCmj&12n)k5&v#UMWJ#|kE=hf`@g)eTSo)h>) zKyqVd-`a)fqi3{*(44a1Xk137ja{z+1!##gDtM{zX-;CoQnm6H$Lm};v05UtyHHHdib??=4TPFj3_0TmB){Bx^wkC(SugSOiVzT>MLZg2g;X6*_mK=`|QC6 zmeo%O6~T42v@%xVbqga1e|j62B+ydSFJ5<)Khy8exa*PSNPK)cLh<<+=*AFFMw;0OPt z4i&`MuuZR$F;?4o_V-6^zE9hLpXJ`^pXsIrtS=Y^KnAL?&0XU3ax#RQohk#P^ybZT z-O*1k^RsE1xE`U5)64p5ZfLbD_HnI_Bs}Wvlr;%EpHC*ngo1C_J!HlI@w~^SpA%9m zVv4(vJ-MksGLaM_K9u){oernEq%#{EsXs~?SBMO*6^nE&Vll#HY)|>d{ow+>jGc7; zG?^$sQwpuT=3V!yCu;%KX;z#d?6EbzNTxHYCTT(&#x}Qw+{_4iR+?8o{8bjPdgSrA zEw$Fm!AW}&W;8xHSJB^mlm(3#4b-_nMO>~#r zN!AZHw)<^K@sULR{-xmZSR0kbnr_1Ko_ThAfX)hD^%YC>lr^7}(id{K6Twl4@0?|yh2$XTVUN-xWvWx}!2zkoAoJe9qF9;E6Ugf{oox zjaKI9DTn;30FZ`w9=oV$mU3_chl8SWRq3Qe@%?WxUz|dSFUL?5&2k~Q#)xDvAl(;x%XmLyd+hgn0Sg!d%cLh7~Co2fN-DUnZ0Nw z-Tu^Q-DwCn^sMkI@*uYdR~eR8cDuuQ#7*SWw$$zo+dKuUb&P=p9ny(qZW0kGDJa$K zuwVI<2fsdi$GsTiK?v9EeR9m)0af{K?2>-y1kBcVzJTDLmN4h#9T2{NLV{Rig02|< zhkK?^IAa-lf$By}X<k$q zX#rwSP4<$EoWN;G(HQMC7h#a}ui`Bl0fspX-v zwZl`vf#uffqgl6ee-^7!2XK;7tk+uwPtL90Cq2CEyM4zh1Uw#s?yY*_8VZw%lT zwoMl$*)`;jJI4aVO&BC>6?$m?FX>xQLYBC~oo3dn#bw7#GRp2yR-m&8M+%y9DY=37 zmsyvZFGXH1Y;W|>b~J?BEK?hLJOcvCcz<)bYJUCiq!7G{kqCRMm}(J zMf;MRm^%>htZ2s%4(=F2bnc95;>ZEe@~{pfxHC6Z1t_ZY)k(Y z(oyepf#-nio)KG12yn=on!p9rk7yNNb=~vA>r9o0Vw}Yha;KEFzcZPaYany&9r6Ty zR@+y3iNzQQg`4W8iSi%MsHmou%!!@wiKsWs`!JeoM*k0Tp+rV@d8u1@ Date: Fri, 21 Feb 2025 09:02:04 +0100 Subject: [PATCH 24/30] Removed link to non-exisiting page --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 06af6e6..732a91d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ KISS Documentatie ================= -Het Klant Interactie Service Systeem (KISS) is een applicatie waarmee Klantcontactmedewerkers (KCM) optimaal worden ondersteund in hun werk: het informeren en helpen van burgers en ondernemers die contact opnemen met de gemeente. Doel van KISS is om alle informatie die een KCM nodig heeft voor die taak, zoveel mogelijk binnen KISS zelf te ontsluiten. Het is ontwikkeld als een Common Ground component in opdracht van `de gemeente Utrecht en Dimpact `__. +Het Klant Interactie Service Systeem (KISS) is een applicatie waarmee Klantcontactmedewerkers (KCM) optimaal worden ondersteund in hun werk: het informeren en helpen van burgers en ondernemers die contact opnemen met de gemeente. Doel van KISS is om alle informatie die een KCM nodig heeft voor die taak, zoveel mogelijk binnen KISS zelf te ontsluiten. Het is ontwikkeld als een Common Ground component in opdracht van de gemeente Utrecht en Dimpact. .. toctree:: :caption: KISS Documentatie From 1063d759ff3ef9fc066d6a56acc136e973ca7f66 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Fri, 21 Feb 2025 09:14:33 +0100 Subject: [PATCH 25/30] changed reletative links to new structure, in installatiemd --- docs/installation/installatie.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/installation/installatie.md b/docs/installation/installatie.md index acbc517..580cbce 100644 --- a/docs/installation/installatie.md +++ b/docs/installation/installatie.md @@ -11,8 +11,8 @@ De installatie kan uitgevoerd worden middels het PowerShell script. Handmatig ui [install_kiss.ps1](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/scripts/install_kiss.ps1) **LET OP** -- Voordat een ingelogde gebruiker kan werken met KISS, moet deze gebruiker de juiste rol hebben in de gekoppelde Identity provider. Zie voor meer informatie het onderdeel [Configuratie van uw Identity Provider in de configuratie-handleiding](CONFIGURATIE.md#configuratie-van-uw-identity-provider). -- Om een betere indruk te krijgen van hoe KISS werkt, is het mogelijk om **voorbeeldata (demodata)** te laden. Zie hiervoor [de uitleg bij de Beheerhandleiding](MANUAL.md#kiss-beheer-vullen-met-voorbeelddata). +- Voordat een ingelogde gebruiker kan werken met KISS, moet deze gebruiker de juiste rol hebben in de gekoppelde Identity provider. Zie voor meer informatie het onderdeel [Configuratie van uw Identity Provider in de configuratie-handleiding](..\configuration\identity-provider.md). +- Om een betere indruk te krijgen van hoe KISS werkt, is het mogelijk om **voorbeeldata (demodata)** te laden. Zie hiervoor [de uitleg bij de Beheerhandleiding](..\manual\voorbeelddata.md). ### KISS-Elastic-Sync KISS-Elastic-Sync is het component dat zorgt voor het creëren van de benodigde engines in een Elasticsearch-installatie, zodat gekoppelde bronnen eenvoudig door KISS doorzoekbaar zijn. Het ondersteunt zowel websites als gestructureerde bronnen door respectievelijk een crawler en een index te gebruiken. From d79fa49272e46f43bb17d2676055e68e0c706eb7 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Fri, 21 Feb 2025 09:24:06 +0100 Subject: [PATCH 26/30] fix links --- docs/installation/installatie.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/installation/installatie.md b/docs/installation/installatie.md index 580cbce..2b3988e 100644 --- a/docs/installation/installatie.md +++ b/docs/installation/installatie.md @@ -11,8 +11,8 @@ De installatie kan uitgevoerd worden middels het PowerShell script. Handmatig ui [install_kiss.ps1](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/scripts/install_kiss.ps1) **LET OP** -- Voordat een ingelogde gebruiker kan werken met KISS, moet deze gebruiker de juiste rol hebben in de gekoppelde Identity provider. Zie voor meer informatie het onderdeel [Configuratie van uw Identity Provider in de configuratie-handleiding](..\configuration\identity-provider.md). -- Om een betere indruk te krijgen van hoe KISS werkt, is het mogelijk om **voorbeeldata (demodata)** te laden. Zie hiervoor [de uitleg bij de Beheerhandleiding](..\manual\voorbeelddata.md). +- Voordat een ingelogde gebruiker kan werken met KISS, moet deze gebruiker de juiste rol hebben in de gekoppelde Identity provider. Zie voor meer informatie het onderdeel [Configuratie van uw Identity Provider in de configuratie-handleiding](../configuration/identity-provider.md). +- Om een betere indruk te krijgen van hoe KISS werkt, is het mogelijk om **voorbeeldata (demodata)** te laden. Zie hiervoor [de uitleg bij de Beheerhandleiding](../manual/voorbeelddata.md). ### KISS-Elastic-Sync KISS-Elastic-Sync is het component dat zorgt voor het creëren van de benodigde engines in een Elasticsearch-installatie, zodat gekoppelde bronnen eenvoudig door KISS doorzoekbaar zijn. Het ondersteunt zowel websites als gestructureerde bronnen door respectievelijk een crawler en een index te gebruiken. From b1a98c387c115f2f3ac3d5d0af6d45844d9ca7b9 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Fri, 21 Feb 2025 09:54:18 +0100 Subject: [PATCH 27/30] Links updated in Configuration --- docs/configuration/configuration.rst | 2 +- docs/configuration/elastic.md | 2 +- docs/configuration/identity-provider.md | 2 +- docs/configuration/objecten.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/configuration/configuration.rst b/docs/configuration/configuration.rst index 5f7ba56..a5dfe62 100644 --- a/docs/configuration/configuration.rst +++ b/docs/configuration/configuration.rst @@ -1,7 +1,7 @@ Configuratie ============ -Bij de installatie van KISS worden er een groot aantal dingen al geconfigureerd. Op deze pagina staan verschillende onderdelen van de configuratie toegelicht. +Bij de installatie van KISS worden er een groot aantal dingen al geconfigureerd. Op deze pagina's staan verschillende onderdelen van de configuratie toegelicht. .. toctree:: :maxdepth: 2 diff --git a/docs/configuration/elastic.md b/docs/configuration/elastic.md index 22ad466..6d10238 100644 --- a/docs/configuration/elastic.md +++ b/docs/configuration/elastic.md @@ -15,7 +15,7 @@ De eerste keer dat er via de synctool Kennisartikelen (PDC-producten), Medewerke - De velden die bij de bron horen: voor elk property in het schema van de bron, wordt een property aangemaakt binnen de KISS-engine, voorafgegaan door de waarde van `objectbron`. ## Relevance Tuning -Om de informatie uit de Kennisartikelen en websites doorzoekbaar te maken, moeten deze velden opgenomen zijn in het Engine Schema, en doorzoekbaar gezet in de Relevance tuning. Zijn er nieuwe velden toegevoegd aan het Engine Schema, bijvoorbeeld omdat er een nieuw type bron is toegevoegd? Dan moeten deze velden doorzoekbaar gemaakt worden, door op knop 'Update search settings' te klikken op de pagina Manage engine schema. U kunt ook op de pagina Relevance Tuning aangeven dat een schemaveld doorzoekbaar moet zijn. +Om de informatie uit de Kennisartikelen en websites doorzoekbaar te maken, moeten deze velden opgenomen zijn in het Engine Schema, en doorzoekbaar gezet in de Relevance tuning. Om de instellingen voor relevance tuning aan te passen en de beheren, heb je toegang nodig tot de Kibana web interface van Elastic. Zijn er nieuwe velden toegevoegd aan het Engine Schema, bijvoorbeeld omdat er een nieuw type bron is toegevoegd? Dan moeten deze velden doorzoekbaar gemaakt worden, door op knop 'Update search settings' te klikken op de pagina Manage engine schema. U kunt ook op de pagina Relevance Tuning aangeven dat een schemaveld doorzoekbaar moet zijn. Om de zoekresultaten te beïnvloeden, moet u vervolgens de Relevance Tuning instellen. [Zie ook de documentatie van Elasticsearch](https://www.elastic.co/guide/en/app-search/current/relevance-tuning-guide.html) diff --git a/docs/configuration/identity-provider.md b/docs/configuration/identity-provider.md index 22827e8..dedaf8a 100644 --- a/docs/configuration/identity-provider.md +++ b/docs/configuration/identity-provider.md @@ -5,7 +5,7 @@ Als een ingelogde gebruiker wel de startpagina ziet, maar vervolgens alleen maar ## Claims uit uw Identity provider KISS gebruikt de claims uit uw Identity Provider om de gegevens van de ingelogde Klantcontactmedewerker toe te voegen aan de Contactmomenten en Contactverzoeken die vanuit KISS worden geregistreerd. -Zie [de installatiehandleiding](INSTALLATION.md#Authenticatie) voor hoe u dit configureert. +Zie [de installatiehandleiding](../installation/voorbereidingen.md#Authenticatie) voor hoe u dit configureert. Er is in JWT geen standaard claim voor voorletters of voorvoegsel (tussenvoegsel). KISS gebruikt daarom deze mapping: - Voorletters => given_name diff --git a/docs/configuration/objecten.md b/docs/configuration/objecten.md index 000658d..7053044 100644 --- a/docs/configuration/objecten.md +++ b/docs/configuration/objecten.md @@ -1,5 +1,5 @@ # Configuratie t.b.v. Objecten API -KISS maakt voor de koppeling met verschillende registraties gebruik van de Objecten API. Om objecten van een bepaald objecttype op te kunnen halen, moet het de URL weten van dat objecttype in de Objecttype API. Zie ook [de Installatiehandleiding](https://kiss-klantinteractie-servicesysteem.readthedocs.io/en/latest/INSTALLATION/) en de [documentatie bij KISS-Elastic-Sync](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/README.md) +KISS maakt voor de koppeling met verschillende registraties gebruik van de Objecten API. Om objecten van een bepaald objecttype op te kunnen halen, moet het de URL weten van dat objecttype in de Objecttype API. Zie ook [de Installatiehandleiding](../installation/configuratie.md) en de [documentatie bij KISS-Elastic-Sync](https://github.com/Klantinteractie-Servicesysteem/KISS-Elastic-Sync/blob/main/README.md) ## Authenticatie bij de Objecten API In de meeste gevallen identificeert KISS zich bij de Objectenregistratie m.b.v. een TOKEN. From 6874a4c8522d78ee7490a6fa5f61e019305b66de Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Fri, 21 Feb 2025 11:09:12 +0100 Subject: [PATCH 28/30] update links in manual --- docs/manual/managementinformatie.md | 2 +- docs/manual/manual.rst | 2 +- docs/manual/vacs.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/manual/managementinformatie.md b/docs/manual/managementinformatie.md index 487f53f..0b79353 100644 --- a/docs/manual/managementinformatie.md +++ b/docs/manual/managementinformatie.md @@ -1,5 +1,5 @@ # Managementinformatie -Bij het opslaan van Contactmomenten worden enkele gegevens, die geen plek hebben in de standaarden rondom Klantinteracties, opgeslagen binnen KISS zelf. (zie ook het [onderdeel Contactmomentdetails in Decision Record](https://github.com/Klantinteractie-Servicesysteem/.github/blob/main/docs/DECISION-RECORD.md#contactmomentdetails)). Deze gegevens leveren managementinformatie over de werkzaamheden van het KCC. +Bij het opslaan van Contactmomenten worden enkele gegevens, die geen plek hebben in de standaarden rondom Klantinteracties, opgeslagen binnen KISS zelf. (zie ook het [onderdeel Contactmomentdetails in Decision Record](../decision-record/contactmomenten.md#contactmomentdetails)). Deze gegevens leveren managementinformatie over de werkzaamheden van het KCC. Binnen KISS is een API endpoint beschikbaar waarmee deze gegevens opgevraagd kunnen worden. Dit endpoint is benaderbaar op: `https://www.kissbijdegemeente.nl/api/contactmomentendetails`. diff --git a/docs/manual/manual.rst b/docs/manual/manual.rst index 43baa54..0705cf8 100644 --- a/docs/manual/manual.rst +++ b/docs/manual/manual.rst @@ -9,7 +9,7 @@ Als beheerder van KISS kan je de volgende zaken beheren: - Formulier contactverzoeken - Kanalen -Per onderwerp leggen wij uit wat de mogelijkheden zijn en hoe je de werkzaamheden uitvoert. Om deze taken te kunnen uitvoeren moet je de rol `Redacteur` hebben (zie ook `Configuratie `__). +Per onderwerp leggen wij uit wat de mogelijkheden zijn en hoe je de werkzaamheden uitvoert. Om deze taken te kunnen uitvoeren moet je de rol `Redacteur` hebben (zie ook `Configuratie `__). .. toctree:: :maxdepth: 2 diff --git a/docs/manual/vacs.md b/docs/manual/vacs.md index 68b0d1b..a4b17c1 100644 --- a/docs/manual/vacs.md +++ b/docs/manual/vacs.md @@ -2,7 +2,7 @@ Op de pagina 'Vacs' kan je Vraag-Antwoord-Combinaties beheren die zijn opgeslagen in het bij de KISS-installatie geconfigureerde Objectenregister. De lijst op de Vac-overzichtspagina toont alle Vacs. Door middel van de toetsenbord combinatie `Ctrl + f` kun je in de lijst zoeken naar de vraag die bij de Vraag-Antwoord-Combinatie hoort. ### Let op -Deze optie is alleen beschikbaar, als deze is aangezet bij de installatie/configuratie van KISS. Dit gebeurt m.b.v. een Environment Variabele. Zie ook [de installatiehandleiding](INSTALLATION.md#kiss-frontend), bij USE_VACS +Deze optie is alleen beschikbaar, als deze is aangezet bij de installatie/configuratie van KISS. Dit gebeurt m.b.v. een Environment Variabele. Zie ook [de installatiehandleiding](../installation/configuratie.md#kiss-frontend), bij USE_VACS ## Vacs toevoegen, wijzigen en verwijderen Het toevoegen, wijzigen of verwijderen van Vacs gaat op een gelijksoortige manier als het toevoegen, wijzigen of verwijderen van Skills of gespreksresultaten. From 57458ede9b1035069d20a27332bd579396e8f661 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Fri, 21 Feb 2025 11:13:23 +0100 Subject: [PATCH 29/30] fix links in decision-record --- docs/decision-record/zaken.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decision-record/zaken.md b/docs/decision-record/zaken.md index 8236716..410e821 100644 --- a/docs/decision-record/zaken.md +++ b/docs/decision-record/zaken.md @@ -2,4 +2,4 @@ # Zaken: het zaakdetailscherm In onderstaande afbeelding is gedocumenteerd welke gegevens uit de verschillen ZGW-objecten worden gebruikt in het Zaak-detailscherm. -![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/add-decision-record/docs/images/MappingZaakDetail.png) +![image](https://raw.githubusercontent.com/Klantinteractie-Servicesysteem/.github/refs/heads/main/docs/images/MappingZaakDetail.png) From a551d667070fc04fe15376e2b07723466d5a0672 Mon Sep 17 00:00:00 2001 From: sytskevanhasselt Date: Fri, 21 Feb 2025 11:15:55 +0100 Subject: [PATCH 30/30] remove link from manualrst --- docs/manual/manual.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manual/manual.rst b/docs/manual/manual.rst index 0705cf8..18f4e3f 100644 --- a/docs/manual/manual.rst +++ b/docs/manual/manual.rst @@ -9,7 +9,7 @@ Als beheerder van KISS kan je de volgende zaken beheren: - Formulier contactverzoeken - Kanalen -Per onderwerp leggen wij uit wat de mogelijkheden zijn en hoe je de werkzaamheden uitvoert. Om deze taken te kunnen uitvoeren moet je de rol `Redacteur` hebben (zie ook `Configuratie `__). +Per onderwerp leggen wij uit wat de mogelijkheden zijn en hoe je de werkzaamheden uitvoert. Om deze taken te kunnen uitvoeren moet je de rol `Redacteur` hebben (zie ook Configuratie). .. toctree:: :maxdepth: 2