Versie maart 2023Deze 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:
...
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:
...
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:
Stuur een dossieritem in AFAS op een CRM bestemming met contacten
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)
Doorloop de workflow tot de workflowstatus is PKI
Log in op de PKIsigning widget via de integratiepagina die is opgenomen op de tonenpagina van het dossieritem
Voegt de ondertekenaars dan wel de ontvangers toe
Controleer hierbij altijd de contactgegevens (e-mail en mobiel).
Klik op verzenden
Het document wordt nu op het platform geplaatst en de workflow wordt door PKIsigning op de status PKI processing gezet.
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 Widget integratie maakt gebruik van de volgende GetConnectoren
PKIsigning_Subject (voor het ophalen van https://pkisigning.atlassian.net/wiki/spaces/PKISUPPORT/pages/1047429240 (voor het ophalen van de dossieritems, de bestemming bij de dossieritems en de workflow status)
PKI_Subject_Attachments https://pkisigning.atlassian.net/wiki/spaces/PKISUPPORT/pages/1047101620 (voor het ophalen van de bijlagen bij het dossieritem)
PKIsigning_Workflowactions https://pkisigning.atlassian.net/wiki/spaces/PKISUPPORT/pages/1047101581 (voor het ophalen van de workflowacties bij het dossieritem)
PKIsigning_Employees https://pkisigning.atlassian.net/wiki/spaces/PKISUPPORT/pages/1047822345 (voor het ophalen van de gegevens van de intern ondertekenaars)
PKIsigning_Contacts https://pkisigning.atlassian.net/wiki/spaces/PKISUPPORT/pages/1047691302 (voor het ophalen van de extern ondertekenaars dit zijn de contacten bij de bestemming)
De Getconnectoren zijn beschikbaar via het onderstaande zipbestand.zipbestand.
Profit 2
| View file | ||
|---|---|---|
|
Profit 1
| View file | ||
|---|---|---|
|
Oud:
| View file | ||
|---|---|---|
|
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.
...
Onder intern (ondertekenaar / ontvanger) kun je kiezen uit de medewerkers. Dit zijn de gegevens die mee komen in de GetConnector: PKIsigning_Employee: https://pkisigning.atlassian.net/wiki/spaces/PKISUPPORT/pages/1047822345
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 https://pkisigning.atlassian.net/wiki/spaces/PKISUPPORT/pages/1047691302 .
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.
...
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.
...
De ondertekenaar het verzoek heeft afgewezen.
Er is technisch iets fout gegaan bij PKIsigning of het ondertekenen.
Een verzoek is verlopen dossier is verlopen. (niet een verzoek)
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.
Status workflow | Waarom |
PKI (kleur blauw) | In deze status is de widget actief en kun je het verzoek naar PKIsigning versturen |
PKI processing (kleur oranje of geel) | Nadat het verzoek verstuurd is kun uit deze status aflezen dat het verzoek nog in behandeling is bij PKIsigning en dat er dus nog acties moeten worden uitgevoerd. |
PKI signed (kleur groen) | Als het verzoek succesvol is afgewikkeld en alle onderteken of accordeer acties zijn afgerond krijgt het deze status |
PKI unsigned (kleur rood) | Als er iets fout is gegaan in het onderteken verzoek of het verzoek is afgewezen of verlopen dan krijgt het deze status. |
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 https://pkisigning.atlassian.net/wiki/spaces/PKISUPPORT/pages/1047429240 wordt gebruikt om het dossieritem op te halen alsmede de status van de workflow.
PKI_Subject_Attachments https://pkisigning.atlassian.net/wiki/spaces/PKISUPPORT/pages/1047101620 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.
...
...
https://pkisigning.atlassian.net/wiki/spaces/PKISUPPORT/pages/1047101581 wordt gebruikt om vervolgtaak van de workflow te bepalen.
...
PKIsigning_Employees https://pkisigning.atlassian.net/wiki/spaces/PKISUPPORT/pages/1047822345 wordt gebruikt de gegevens van de intern ondertekenaars (medewerkers) op te halen en te kunnen selecteren in de widget.
...
PKIsigning_Contacts https://pkisigning.atlassian.net/wiki/spaces/PKISUPPORT/pages/1047691302 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
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.
Filter in de GetConnector PKIsigning_employees op alleen onderteken bevoegde medewerkers.
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
Indien de widget geen tag voor de ondertekenpositie vindt kun je onderstaande foutmelding verwachten.
Indien het e-mail adres van een ondertekenaar of ontvanger niet is gevuld. Je krijgt dezelfde soort foutmelding bij mobiel nummer.
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.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.
...