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

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: Sommige API-keys en Secrets die KISS nodig heeft om externe registers te bevragen moeten minimaal 16 karakters lang zijn.

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
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.
KLANTEN_BASE_URL URL van de Klanten API van het gebruikte klantenregister
Meer informatie Bijvoorbeeld https://klantenregister.mijngemeente.nl/klanten
KLANTEN_CLIENT_ID ClientId voor de Klanten API van het gebruikte klantenregister
KLANTEN_CLIENT_SECRET Secret voor de Klanten API
(min. 16 karakters)
NIETNATUURLIJKPERSOONIDENTIFIER Identifier voor 'niet natuurlijke personen'
(rsin of kvkNummer)
Meer informatie Afhankelijk van de gebruikte bron (bijvoorbeeld Open Klant of de e-Suite) kan je hiermee aangeven welk gegeven gebruikt wordt om KvK-gegevens van niet natuurlijke persoonen aan klanten in het klantregister te koppelen. 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 met de spelling van het property in de KvK-API's
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. 16 karakters)
ZAKEN_BASE_URL URL van de ZGW API's
Meer informatie Bijvoorbeeld: https://zaaksysteem.mijngemeente.nl
ZAKEN_API_CLIENT_ID ClientId voor de ZGW API's
ZAKEN_API_KEY API Key voor de ZGW API's
(min. 16 karakters)
ZAAKSYSTEEM_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_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_DEEPLINK_PROPERTY Property om naar een zaak te kunnen deeplinken (optioneel)
Meer informatie Deze variabele moet altijd gebruikt worden in combinatie met ZAAKSYSTEEM_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
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
(niet te gebruiken met CLIENT_SECRET en CLIENT_ID)
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!
INTERNE_TAAK_CLIENT_SECRET Client Secret voor de Interne Taken API
(niet te gebruiken in combinatie met INTERNE_TAAK_TOKEN)
INTERNE_TAAK_CLIENT_ID Client ID voor de Interne Taken API
(niet te gebruiken in combinatie met INTERNE_TAAK_TOKEN)

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
(niet te gebruiken i.c.m. CLIENT_SECRET en CLIENT_ID)
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!
MEDEWERKER_OBJECTEN_CLIENT_ID Client ID voor de Objecten API voor medewerkers
(niet te gebruiken i.c.m. TOKEN)
MEDEWERKER_OBJECTEN_CLIENT_SECRET Client Secret voor de Objecten API voor medewerkers
(niet te gebruiken i.c.m. TOKEN)
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_OBJECTEN_TOKEN Token voor de Objecten API voor VAC's
VAC_OBJECT_TYPE_URL URL van het Objecttype VAC
Meer informatie Bijvoorbeeld https://objecttypenregister.mijngemeente.nl/api/v2/objecttypes/f83fdc48-5ddb-4b1a-a347-e20092031399
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

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