Klantinteractie Servicesysteem (KISS) Installatie Handleiding

Inhoudsopgave

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:

Haven

KISS kan op een haven-compliant cluster geïnstallleerd worden. Referentie-implementaties van haven-compliant clusters zijn te vinden op de Haven site.

Bij het volgen van de 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 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, 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 engines 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.

Uitvoeren

De installatie kan uitgevoerd worden middels het PowerShell script. Handmatig uitvoeren kan ook.

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. - 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.

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

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