PKIsigning – AFAS Widget integratie [Handleiding]

Versie maart 2023

Deze handleiding beschrijft de opzet en installatie van de widget integratie tussen PKIsigning en AFAS.

Belangrijk! PKIsigning biedt geen (inhoudelijke) ondersteuning bij het gebruik en het toepassen van de AFAS integratie.

Toelichting integratie

Deze integratie is gemaakt om via een AFAS dossieritem in combinatie met een workflow documenten (PDF en of XBRL) ter ondertekening, accordering of download bij CRM relaties uit AFAS aan te bieden. Het voordeel hiervan is dat je via de workflow de status van het proces in PKIsigning kunt volgen. Daarnaast wordt geautomatiseerd het ondertekende document teruggeplaatst in het dossieritem. Deze integratie werkt rechtstreeks via de API van PKIsigning. In AFAS wordt de integratie opgezet door het instellen van één appconnector met get- en update connectoren.

Wat wordt er ondersteund

Om via AFAS documenten naar PKIsigning te sturen zijn er een aantal scenario’s mogelijk. De volgende functionaliteiten worden in de integratie ondersteund:

• Ondertekening en aflevering van PDF documenten (1 document ondertekenen en PDF bijlages mogelijk)

Specifiek voor de accountancy:

• SBR Publicatiestukken accordering.

• SBR Publicatiestukken i.c.m. één PDF ter ondertekening en accordering.

• SBR Assurance ondertekening accountant en accordering door klant.

• SBR Nexus met en zonder assurance.

Toepassing en randvoorwaarden

De toepassing van de AFAS widget integratie is gericht op het aanbieden van documenten via een dossieritem in een workflow. Er zijn tal van scenario’s denkbaar voor het toepassen van de integratie binnen je processen. Je bent vrij om maximaal gebruik te maken van de integratiemogelijkheid. Let hierbij op de volgende voorwaarden:

• PKIsigning is niet verantwoordelijk voor de inrichting van jullie bedrijfsprocessen / workflows.

• PKIsinging is niet verantwoordelijk voor het feit als iets niet werkt indien er is afgeweken van de in de handleiding beschreven connectoren.

• In één PDF welke ondertekend moet worden is minimaal een placeholder (ondertekentag) aanwezig 

• Naam, e-mail adres en mobiel nummer zijn gevuld bij de CRM relatie.

Voorbeeld scenario’s:

• Aanbieden van offertes, overeenkomsten etc bij contactpersonen van verkooprelaties.

• Het laten ondertekenen van een geheimhoudingsverklaring door derden die worden ingehuurd.

• Het ondertekenen van inkoopcontracten.

• Het ondertekenen van arbeidscontracten en andere HR gerelateerde documenten van sollicitanten of medewerkers.

• Het ondertekenen / aanbieden van documenten binnen een jaarrekeningproces (Opdrachtacceptatie, LOR, aanbiedingsbrief, conceptjaarrekening, definitieve jaarrekening, notulen AvA, publicatiecijfers en bankenrapportages.

Hoe het werkt

Hieronder staan kort de stappen beschreven van de werking van de widget integratie:

1. Stuur een dossieritem in AFAS op een CRM bestemming met contacten

2. Voeg de te ondertekenen bijlagen toe PDF of XBRL bestand. Let op bij een PDF dat deze voorzien is van een ondertekentag (tekstlabel dat aanduidt waar de handtekening in het document moet komen)

3. Doorloop de workflow tot de workflowstatus is PKI

4. Log in op de PKIsigning widget via de integratiepagina die is opgenomen op de tonenpagina van het dossieritem

5. Voegt de ondertekenaars dan wel de ontvangers toe

6. Controleer hierbij altijd de contactgegevens (e-mail en mobiel).

7. Klik op verzenden

8. Het document wordt nu op het platform geplaatst en de workflow wordt door PKIsigning op de status PKI processing gezet.

9. Zodra alle acties (ondertekeningen) op het dossier in PKIsigning zijn afgewikkeld wordt de workflow door PKIsigning op de status PKIsigned gezet.  

10.           PKIsigning vervangt tevens het ingestuurde document met het ondertekende document

11.           PKIsigning plaatst gedurende het (onderteken)proces reacties bij het dossieritem rondom de gebeurtenissen.

De configuratie

Vrije tabel workflow statussen aanpassen

Voeg aan de vrije tabel workflow statussen de volgende statussen toe:

De code van de workflows status mag anders zijn. PKIsigning matcht / zoekt op basis van de omschrijving naar de status van de workflow.  

• Ga naar: Algemeen / Inrichting / Vrije tabel.

• Selecteer de vrije tabel met de workflow statussen.

• Dubbelklik op de naam van de tabel.

• Kies voor nieuw en voeg de workflow statussen ten behoeve van PKIsigning toe.

Tip! Voeg ook de kleuren aan de statussen toe dat smoelt mooi in de workflow. 

Importeer de GetConnectoren.

De Widget integratie maakt gebruik van de volgende GetConnectoren

•  PKIsigning_Subject (voor het ophalen van de dossieritems, de bestemming bij de dossieritems en de workflow status)

• PKI_Subject_Attachments (voor het ophalen van de bijlagen bij het dossieritem)

• PKIsigning_Workflowactions (voor het ophalen van de workflowacties bij het dossieritem)

• PKIsigning_Employees (voor het ophalen van de gegevens van de intern ondertekenaars)

• PKIsigning_Contacts (voor het ophalen van de extern ondertekenaars dit zijn de contacten bij de bestemming)

De Getconnectoren zijn beschikbaar via het onderstaande zipbestand.

• Ga naar Algemeen / Uitvoer / Beheer / Getconnector.

• Kies Importeren, selecteer de bestanden en importeer via Voltooien.

• De geïmporteerde GetConnectoren beginnen met “PKIsigning”.

• Open en controleer één voor één de connectoren. 

• Kies hierbij na het openen voor volgende en klik vervolgens op gegevens.

• Controleer de veldmapping (indien er velden in uw inrichting ontbreken, komt dit in beeld) en verifieer eventueel in het laatste scherm de waarden via ‘Voorbeeld’.

• Let op bij de filtering van de GetConnectoren. De filtering is in de connectoren toegelicht, echter kan dit per organisatie en afhankelijk van wensen verschillen.

Configureer de App connector

• Ga naar Algemeen / Beheer / App connector.

• Kies nieuw en geef een duidelijke omschrijving.

• Selecteer een gebruikersgroep met gebruikers die rechten hebben tot de connectoren (Connector Users).

• Ga naar het tabblad GetConnectoren en voeg via nieuw de zojuist geïmporteerde connectoren toe.

• Ga naar het tabblad Updateconnectoren en voeg via Nieuw de volgende Updateconnectoren toe:.

• Dossier (KnSubject) en.

• Workflow reactie (KnSubjectWorkflowReaction).

• Reactie bij dossieritem (KnSubjectReaction).

• Ga naar het tabblad Connectoren en voeg via Nieuw AppConnectorSubject toe.

• Ga naar het tabblad Gebruikerstoken en maak via Nieuw een nieuwe token aan. Kopieer deze token en sla deze op. Koppel deze aan een specifieke gebruiker (indien er geen gebruikers in de rechtengroep actief zijn dien je deze eerst nog aan te maken!) en geef een duidelijke omschrijving.

Configureer de AFAS integratie in PKIsigning

• Ga nu naar PKIsigning en log in.

• Kies via de avatar rechtsboven voor “Instellingen”.

• Kies voor het tabblad Integraties
  Hier staan de parameters voor AFAS.

• Plak de volledige token in het bovenste veld.

• Geef de URL in zoals in het voorbeeld hiernonder. Vervang het nummer 12345 door het eigen omgevingsnummer.

LET OP!  In het voorbeeld wordt gebruik gemaakt van een AFAS acceptatieomgeving. Hier vind je een overzicht van (productie) URL’s.

Integratiepagina aanmaken en opnemen

• Maak een integratiepagina aan voor InSite (doorloop deze stappen uit de AFAS help) en geef als URL https://afasbridge.PKIsigning.io/v2 in.

• Autoriseer de integratiepagina voor de groepen / rollen in jou organisatie die een ondertekenverzoek naar PKIsigning mogen versturen.

• TIP: meestal zijn dit alle medewerkers die toegang hebben tot de type dossieritems die je digitaal wil laten ondertekenen.

• Ga naar de tonen pagina’s van de type dossieritems die je digitaal wil kunnen ondertekenen met PKISigning en open SiteBeheer

• Kies Bewerken en kies Indeling

• Kies Nieuw en Onderdeel uit bestaande pagina

• Selecteer de zojuist aangemaakte integratiepagina en geef als titel bijvoorbeeld op “PKIsigning”. Kies aanmaken. Stel in dit pagina onderdeel de vaste hoogte in op 1000px. TIP: Zet dit integratiepagina onderaan de pagina over de volledige breedte in 1 sectie.

• Publiceer de site.

Pas workflows aan of richt een nieuwe in.

• Open het dossieritem en de bijbehorende workflow die je wil gebruiken voor het digitaal ondertekenen middels PKISigning. Indien nieuwe workflow kies voor nieuw.

• Geef de workflow een naam, bijv. gekwalificeerd ondertekenen.

• Configureer de workflow zoals gewenst, maar zorg minimaal voor de volgende taken, acties en statussen:

• Een workflow actie met bijv. de omschrijving “Verzoek voorbereid” (status PKI). 

• Vervolgens een taak met bijv. de omschrijving “Verzoek naar PKIsigning verzenden”. Deze taak moet bestemd zijn voor de gebruikersgroep waar de appconnector rechten op heeft. Voeg de actie “in behandeling bij PKIsigning” (status PKI processing). 

• Als laatste voeg je een taak met bijv. de omschrijving “Afwikkelen verzoek door PKIsigning toe” voeg hierbij twee acties toe. Afhandeling door PKIsigning (status PKIsigned) en Afwijzing door PKIsigning (status PKI unsigned).

Toelichtingen

Het ondertekenproces met AFAS en de PKIsigning widget

• Stuur het dossieritem in dat je wil ondertekenen op een relatie met een contact.

• Doorloop de workflow stappen.

Je kunt je ten alle tijden inloggen op de PKIsigning widget. Je moet hiervoor wel een gebruiker zijn binnen het platform PKIsigning. Zie hieronder de login pagina.

Echter als de workflow niet de juiste status heeft (PKI)  zal de widget na aanmelden de melding geven dat de Plugin niet actief is (zie hierboven).  De widget wordt dus pas geactiveerd als de workflowstatus PKI is.

• Het gebruik van de widget.

Onderstaand een voorbeeld van de widget.

Dossiernaam: De dossiernaam is aanpasbaar naar eigen wens maar krijgt altijd het voorstel van het eerste document (bijlage bij het dossieritem in AFAS) dat PKIsigning herkent.

Werkgroep: PKIsigning kent werkgroepen. De functie werkgroepen is gemaakt om het beheer van een dossier te delen met de werkgroepleden. Wanneer je rechten hebt op een van de werkgroepen kun je die hier selecteren. Meer informatie over de werkgroepen functionaliteit vind je hier Dossiers delen met je werkgroep - PKIsigning kennisbank - Confluence (atlassian.net)

Clearance: Wanneer je een werkgroep heb geselecteerd kun je een Clearance level toekennen. Er zijn 5 niveaus en men heeft toegang tot dossiers met je ingestelde niveau en lager. 5 heeft dus toegang tot 1 2 3 4 en 5. Niveau 1 heeft alleen toegang tot niveau 1 dossiers. Advies is om standaard met niveau 1 te werken.

Ondertekenaars: Hier voeg je de ondertekenaars toe. Dus diegene die daadwerkelijk een ondertekenactie hebben op het document. Je kunt tevens een opmerking voor de ondertekenaars meegeven. Dit wordt in het e-mail verzoek ook mee gestuurd. Let op! Dit is max 500 tekens.

Onder intern (ondertekenaar / ontvanger) kun je kiezen uit de medewerkers. Dit zijn de gegevens die mee komen in de GetConnector: PKIsigning_Employee
Onder extern (ondertekenaar / ontvanger) kun je de contacten bij de bestemming van het dossieritem toevoegen. Hier toont de widget de gegevens die mee komen uit de getconnector PKIsigning_Contacts.

TIP: je vindt het snelste de juiste persoon door de eerste 3 tekens van de voor- of achternaam te typen in de zoekvelden. De widget laat ook meteen zien naar welk e-mail adres en mobiel nummer het verzoek verstuurd gaat worden.

Ontvangers: Hier voeg je de ontvangers van het verzoek toe. Dit zijn diegene die het document (naast de ondertekenaars) ontvangen nadat het verzoek door iedereen is ondertekend. Dit werkt op dezelfde manier als het toevoegen van ondertekenaars.

• Verzoek versturen

Nadat je alle ondertekenaars / ontvangers hebt geselecteerd / toegevoegd kun je het verzoek gaan versturen. Hiervoor kun je nog een aantal acties uitvoeren.

Vervolgens kun je indien gewenst nog een aantal zaken aanpassen.

Taal: keuze uit nl (Nederlands) of en (Engels) dit is de taal van de e-mail van het verzoek. Deze staat standaard op Nederlands. Wanneer bij het contact in AFAS de taal (ISO code) is ingesteld in een andere taal dan Nederlands wordt hier en gevuld.

Placeholder: Controleer je of de juiste ondertekenposities/tags zijn ingevuld welke moeten corresponderen met de ondertekenpositie in het document. De widget stelt standaard Ondertekenaar1, Ondertekenaar2, Onderteknaar3 enz. voor. 

Deadline: De deadline wordt standard ingesteld op vandaag + 14 weken voor de eerste ondertekenaar en de volgende ondertekenaar schuift steeds 1 dag op.

Validatie: Hier kun je aangeven of je een IDIN-verificatie wil afdwingen.

: Door hierop te klikken verwijder je de toegevoegde persoon in het verzoek.

De volgorde om het verzoek af te wikkelen bepaal je door de volgorde van toevoegen. Dus de eerste persoon die je toevoegt krijgt de eerste actie en de tweede de tweede actie enzovoorts. Verwijder je tussentijds een persoon en voeg je diegene weer toe wordt dat de weer de volgende actiehouder. PKIsigning sorteert de volgorde in eerste instantie op basis van deadlines.

Klik vervolgens op de knop Verzoek versturen. Na het succesvol versturen veranderd de knop in de tekst Je document is verstuurd ter ondertekening.  

De workflow

Hieronder tref je een voorbeeld workflow aan om zodoende een volledig ondertekenproces af te kunnen wikkelen. Uiteraard kun je het proces naar eigen wens inrichten. Je kan deze workflowtaken en acties ook prima integreren in bestaande processen. De namen van de taken en acties kun je geheel naar eigen wens bepalen. LET OP! De workflow statussen moeten wel  overeenkomen met de acties die PKIsigning moet uitvoeren.  

1. Voorbereiden documenten

Je kunt bij het aanmaken van het dossieritem al een bijlage toevoegen maar meestal is het toch handig om nog een taak te hebben om de documenten aan te passen of misschien wel te laten beoordelen. De actie hierbij is: Verzoek voorbereid. Hierna is de status van de workflow PKI. Deze actie voor je zelf handmatig uit.

Deze taak kan bestemd zijn voor iedereen. En er hoeft verder niets zijn ingesteld. De toelichting bij de taak kan zijn: “Bereid de documenten ten behoeve van het onderteken- of accorderingsverzoek voor.”

2. Verzoek naar PKIsigning verzenden

In deze taak kun je inloggen op de widget die is opgenomen op de tonen pagina bij het dossieritem en kun je het verzoek via de widget verzenden naar PKIsigning. Wanneer het verzoek succesvol verzonden is ververs dan de browser met F5 en je zult zien dat PKIsigning automatisch de actie: In behandeling bij PKIsigning heeft uitgevoerd. De status van de worfklow zal nu zijn PKI processing.

Deze taak moet bestemd zijn voor diegene die het verzoek klaar kan zetten en voor de gebruikersgroep

waaraan de appconnector PKIsigning is gekoppeld. Vervolgens moeten de vinkjes uit de printscreen aan staan.

De toelichting bij de taak kan zijn: “Het verzoek wordt automatisch verzonden naar PKIsigning zodra je in de widget op de knop versturen klikt. PKIsigning voert automatisch de workflowactie: In behandeling bij PKIsigning uit. Hierna kun je de status van het verzoek kunt volgen in AFAS. Ververs (F5) na het versturen deze pagina zodat je kunt zien dat de workflow een stapje verder is gezet. Klik dus vooral niet zelf op de workflow actie”

3. Afwikkelen verzoek door PKIsigning

In deze taak hoef je als gebruiker geen actie te ondernemen. Nadat een verzoek succesvol is afgerond zal PKIsigning automatisch de workflowactie: Afhandeling door PKIsigning uitvoeren. Waarna de status van de workflow PKI signed zal zijn. Gaat het niet goed binnen PKIsigning dan zal PKIsigning de workflowactie: Afwijzing door PKIsigning uitvoeren, waarna de status PKI unsigned zal zijn. Deze taak moet bestemd zijn voor de gebruikersgroep waaraan de appconnector PKIsigning is gekoppeld (je kan uiteraard ook andere gebruikers rechten geven op deze taak.. Vervolgens moeten de vinkjes uit de bovenstaande printscreen aan staan. De toelichting bij de taak kan zijn: “PKIsigning voert automatisch de workflowactie afhandeling of afwijzing uit afhankelijk van de status van het verzoek in PKIsigning.”

4. Het verzoek is in PKIsigning afgewezen.

Deze taak geeft je als instuurder of eigenaar van het verzoek inzicht in waarom het is afgewezen. Dit omdat:

• De ondertekenaar het verzoek heeft afgewezen.

• Er is technisch iets fout gegaan bij PKIsigning of het ondertekenen

• Een verzoek is verlopen  

Je vindt in de reacties terug wat de reden is waarom de status van de workflow PKI unisgned is. Aan deze taak kun je vervolgens acties koppelen om een verzoek opnieuw aan te bieden. Let er dan wel op dat je de bijlage van het verzoek verwijderd. Het is namelijk niet verstandig om een document dat al een keer is aangeboden via PKIsigning nog een keer aan te bieden. Andere acties kunnen zijn het verzoek is in het platform verlengd of annuleren.

De workflow statussen

PKIsigning kijkt naar de workflow statussen als het gaat om het uitvoeren van acties in de workflow, het plaatsen van reacties en het activeren van de widget. Let er bij de instellingen in de workflow op dat de statussen zowel intern als extern zijn gevuld en de zichtbaarheid voor de actie ingesteld is op zowel voor extern als intern.

De reacties bij het dossieritem.

PKIsigning plaatst zoveel mogelijk reacties bij het dossieritem om een goed beeld te geven van de logging van acties en gebeurtenissen binnen het platform PKIsigning. Hieronder een voorbeeld van de workflow reacties. De instuurder van de reacties is de gebruiker die gekoppeld is aan de appconnector. Dit is ook de gebruiker die de workflow acties uitvoert.

• Workflow-actie uitgevoerd door PKIsigning.

• Het dossier is verstuurd naar Mitchel Klaassen om te ondertekenen voor 3/29/2023 12:19:29 PM.

• Het dossier is ondertekend door Mitchel Klaassen. Het dossier is verstuurd naar Mitchel van Klaassen om te ondertekenen voor 3/30/2023 12:19:38 PM.

• Het dossier is ondertekend door Mitchel van Klaassen. Het dossier is verstuurd naar Mitchel van Klaassen om te accorderen voor 3/30/2023 12:19:38 PM.

• Het dossier is geaccordeerd door Mitchel van Klaassen.

• Alle acties op het dossier binnen PKIsigning zijn afgerond.

• Workflow-actie uitgevoerd door PKIsigning.

Opmaak van de tonen pagina van het dossieritem.

Hieronder een voorbeeld van een overzichtelijke opmaak van een tonen pagina voor een dossieritem waar een digitaal onderteken proces aan is gekoppeld.

TIP! Je kunt het beste de integratiepagina (widget) onderaan de pagina opnemen in een aparte sectie over de volledige breedte. Stel de hoogte van integratie pagina in op vaste hoogte 1000px

GetConnectoren:

Hieronder vind je een printscreen van de GetConnectoren met daarin de minimale velden en de veldnamen die PKIsigning nodig heeft. Deze namen mogen dus ook niet worden aangepast.

De connector PKIsigning_Subject wordt gebruikt om het dossieritem op te halen alsmede de status van de workflow.

PKI_Subject_Attachments wordt gebruikt om de bijlage bij het dossieritem uit PKIsigning_Tax_Subject op te halen. Dit is het PDF rapport van de aangifte en of akkoordverklaring.

PKIsigning_Workflowactions wordt gebruikt om vervolgtaak van de workflow te bepalen.

PKIsigning_Employees wordt gebruikt de gegevens van de intern ondertekenaars (medewerkers) op te halen en te kunnen selecteren in de widget.

PKIsigning_Contacts wordt gebruikt de gegevens van de extern ondertekenaars (contacten bij de bestemming van het dossieritem) op te halen en te kunnen selecteren in de widget.

Tips & Tricks

1. Filter in de GetConnectoren op het feit dat e-mail adressen en mobiel nummers niet leeg mogen zijn zowel bij PKIsigning_employees als PKIsigning_contacts.

2. Filter in de GetConnector PKIsigning_employees op alleen onderteken bevoegde medewerkers.

3. Maak een overzichtspagina op InSite met daarin alle dossieritems die je filtert op de statussen PKI, PKI processing, PKI signed en PKI unsigned. Zo kun je op AFAS InSite alles volgen wat er via AFAS naar PKIsigning wordt gestuurd.

Veel voorkomende fouten en vragen

1. Indien de widget geen tag voor de ondertekenpositie vindt kun je onderstaande foutmelding verwachten.

   

2. Indien het e-mail adres van een ondertekenaar of ontvanger niet is gevuld. Je krijgt dezelfde soort foutmelding bij mobiel nummer.

   

3. Ongeldig e-mail adres gebruikt.
   Het verzoek wordt wel naar PKIsigning verzonden maar dan wordt meteen het verzoek in het platform afgekeurd waardoor PKIsigning de workflow op de status PKIunisgned zet.

4. Contact of medewerker niet te selecteren in de widget.
   Dan is er waarschijnlijk gefilterd in de GetConnector PKI_contacts. Controleer dus deze GetConnector op de filters en de personen die hierin voorkomen. Voor de GetConnector PKI_Employees kan hetzelfde gelden.