KWEEKERS Connect:

Mendix on top of AFAS

Inleiding

In deze interactieve workshop ga je een assetmanagement-applicatie ontwikkelen bovenop AFAS. Deze webapplicatie heeft als doel om bedrijfseigendommen als activa te registreren in AFAS zodat deze kunnen worden toegewezen aan medewerkers. De synchronisatie van data met het ERP-systeem van AFAS is van belang om de applicatie naadloos aan te laten sluiten op een vlekkeloze gebruikerservaring.

In deze workshop gebruiken we het Engelse woord voor technische termen die in Mendix Studio Pro gebruikt worden, om verwarring te voorkomen. Bijvoorbeeld: entity, attribute, domain model, decision.

Voorbereiding

Om je goed voor te bereiden op deze workshop, vragen we je om de volgende stappen te doorlopen:

  1. Maak een Mendix-account aan met je zakelijke e-mailadres:
    https://www.kweekers.nl/mendix/signup

  2. Download de starter-applicatie package:
    https://www.kweekers.nl/connect/mendix/install

  3. Download Mendix Studio Pro 9.24.2:
    https://www.kweekers.nl/connect/mendix/install

We gaan eerst het project aanmaken in het Mendix platform. Het low-code softwareplatform van Mendix voorziet niet alleen in de tooling om je applicatie mee te ontwerpen, maar ondersteunt ook alle processen rondom het ontwikkelproces. Denk hierbij aan backlog management, versiebeheer en een feedbackmodule.

  1. Open Mendix Studio Pro 9.24.2

  2. In het scherm “Select App”, kies voor “Import App Package” en selecteer de starter-applicatie package “KWEEKERS_Connect”

  3. In het scherm “Import App Package”, selecteer de optie “New Mendix Team Server” en geef je nieuwe project een naam

  4. Sla het project op een locatie op die niet met clouddiensten zoals OneDrive of Google Drive wordt gesynchroniseerd. Gebruik bijvoorbeeld als pad C:/Mendix/JouwProjectNaam

  5. Klik op OK om het project aan te maken en de basisapplicatie te uploaden naar de server van Mendix

Je bent nu klaar met de voorbereidingen voor de workshop.

Details

Tijdens de workshop heb je een aantal gegevens nodig, die vind je hier alvast:

  • EncryptionKey
    z9#XzQ**?}EXpcNrMSA!z;XpwJr-[6.r
  • AfasEnvironment
    83084
  • AfasEnvironmentType
    Test
  • AfasToken
    <token><version>1</version><data>D7A7D48A48C34F43AEB7C0309CBB2A60EF585F1E4EDE884C66089E9C4F0629CC</data></token>
  • ConnectorName
    Mx_KweekersConnect_Employees

Backlog vullen

Terwijl de applicatie aan de slag gaat met het aanmaken en uploaden van je project, kan je in de developer portal van Mendix alvast een aantal user stories in de backlog aanmaken. De user stories in de backlog gebruik je als takenlijst zodat het voor ontwikkelaars duidelijk is welke functionaliteit er in een bepaalde sprint ontwikkeld moet worden, in welke volgorde op basis van prioriteit.

  1. Open de Mendix Developer Portal:
    https://sprintr.home.mendix.com/link/myapps

  2. Open het project van de applicatie die je zojuist hebt aangemaakt

  3. Ga naar het tabblad “Epics”

  4. Klik rechtsboven in het planbord op Start Sprint

  5. Maak in de nieuwe sprint de volgende user stories in het bord “To Do” aan:

    1. Medewerkers beheren in Mendix

    2. Activa beheren in Mendix

    3. Medewerkers ophalen uit AFAS

    4. Afschrijvingsbedrag per jaar berekenen

    5. Activa aanmaken in AFAS

  6. Nadat je project succesvol is aangemaakt, ga naar Mendix Studio Pro en open de view “Stories” en klik op “Refresh” om de nieuwe user stories op te halen

Medewerkers beheren in Mendix

De eerste stap van onze applicatie is het beheren van medewerkers in Mendix. Dit maakt het straks mogelijk om bij het aanmaken van nieuwe activa in Mendix, de medewerker te koppelen aan wie dit bedrijfseigendom wordt uitgeleverd. We beginnen deze functionaliteit met het domain model.

Het domain model in Mendix is een vertoning van de entities die een rol spelen in jouw applicatie. Het domain model bevat entities, en instanties van die entities noemen we objects. Bijvoorbeeld; een docent is een entity, en meneer Jansen en mevrouw De Visser zijn objects. Op entities kunnen we attributes vastleggen. Een attribute kan van verschillende types zijn, bijvoorbeeld:

  • String; een tekstveld;

  • Decimal; een decimaal getal;

  • Integer; een geheel getal;

  • Date and time; een datum en/of tijd;

  • Boolean; een ja/nee-veld.

We gaan nu eerst de basis leggen voor je domain model. Later in de workshop gaan we dit aanvullen met informatie die we vanuit AFAS verkrijgen over de entities in je domain model.

  1. Open aan de linkerkant in de App Explorer van je project in Studio Pro het domain model van de module MainModule

  2. Maak een nieuwe entity “Employee” door van de rechterkant uit de Toolbox een entity naar je domain model te slepen. Dubbelklik vervolgens op de entity om de naam te wijzigen en geef het de volgende attributes:

    1. EmployeeId (String, 200) [let op; Mendix stelt automatisch een Autonumber in, maak hier een String van]

    2. Name (String, 200)

    3. ContractStart (DateTime, localized)

    4. JobTitle (String, 200)

    5. EmailAddress (String, 200)

  3. Schakel daarnaast op de entity “Employee” de volgende System members in zodat automatisch door Mendix wordt geregistreerd wanneer een object wordt aangemaakt en gewijzigd:

    1. createdDate

    2. changedDate

Nu dat we de basis van ons domain model hebben gemaakt gaan we werken aan het visualiseren van de informatie die in het domain model geborgd wordt. Daarvoor gaan we Mendix automatisch overzichtspagina’s laten genereren.

  1. Klik aan de linkerkant in de App Explorer met de rechter muisknop op de module MainModule en kies voor “Generate overview pages”

  2. Selecteer de entiteit Employee en kies bij “Content layout” voor de lay-out “KWEEKERS_TopBar”

  3. Klik op OK om de overzichtspagina’s te genereren

De volgende stap is om de nieuwe overzichtspagina’s toe te voegen aan de menubalk van de applicatie. Zo kan de gebruiker ook daadwerkelijk op onze nieuwe pagina’s komen.

  1. Ga naar App Explorer / App / Navigation

  2. Maak onderaan het scherm met de optie “New item” een nieuw menu-item genaamd “Beheer” en voeg met de actieknop “New subitem” een menu-item eronder toe met de naam “Medewerkers”. Kies voor “Show a page” bij de “On click” gebeurtenis en selecteer de pagina MainModule / OverviewPages / Employee_Overview

Laten we de applicatie eens starten om te zien wat we zojuist gecreëerd hebben in Mendix.

  1. Kies in de menubalk van Studio Pro voor Run / Run locally (F5)

  2. Kies in de menubalk voor Run / Responsive Web (F9)

  3. De applicatie zou nu geopend moeten worden in de browser

  1. Kies in het menu van je applicatie voor Beheer / Medewerkers

  2. Klik op New om een nieuwe medewerker toe te voegen

  3. Vul de gegevens in en klik op Save

Gefeliciteerd! Je hebt het nu mogelijk gemaakt om medewerkers te beheren in Mendix. Dit is de eerste stap richting onze activa-beheersysteem. Natuurlijk willen we niet een dubbele administratie voeren van medewerkers in zowel AFAS als Mendix. We willen juist dat de medewerkers uit AFAS automatisch worden gesynchroniseerd met Mendix. De synchronisatie met medewerkers in AFAS gaan we in een latere stap mogelijk maken. We gaan nu eerst een onderhoudsfunctie ontwikkelen voor het beheren van activa in Mendix.

Activa beheren in Mendix

Het essentiële stuk functionaliteit van jouw applicatie is het kunnen aanmaken van activa, waarna ze ook automatisch worden aangemaakt in AFAS. Daarmee kan je bedrijfseigendommen registreren van jouw Mendix-webapplicatie, die bijvoorbeeld ook op je smartphone of tablet vanuit de browser te benaderen is.

We zullen in dit hoofdstuk ontwikkelen dat je een actief kunt aanmaken in Mendix en kunt koppelen met een medewerker. Later in de workshop maken we het mogelijk dat de activa ook worden aangemaakt in AFAS.

  1. Maak in het domain model van MainModule een nieuwe entity en noem het Asset

  2. Voeg de volgende attributes toe:

    1. Description (String, 200)

    2. DatePurchased (Date and Time, localized)

    3. Reference (String, 200)

    4. PurchasePrice (Decimal)

  3. Creëer een association tussen Asset en Employee op zo’n manier dat één Employee kan zijn geassocieerd met meerdere Assets. We willen tenslotte dat een medewerker meerdere bedrijfseigendommen kan hebben, maar dat een bedrijfseigendom altijd bij maximaal één medewerker hoort. Je creëert een association door van de rand van het kader van de ene entity naar de andere entity een lijn te trekken

Nu gaan we een pagina maken met een formulier waarmee de gebruiker van jouw applicatie een nieuw bedrijfseigendom kan vastleggen.

  1. Maak een nieuwe folder in MainModule genaamd “AssetManagement”

  2. Maak in die folder een nieuwe pagina

    1. Selecteer de lay-out Forms / Form Centered

    2. Noem de pagina Asset_NewEdit

    3. Selecteer de navigation layout KWEEKERS_Topbar (KWEEKERS_core)

  3. Klik op OK om op te slaan

  1. Pas de header en subtitel van de pagina aan:
    Create asset
    Use this form to create a new asset and associate it with an employee

Vervolgens gaan we het formulier toevoegen aan de pagina. Mendix gebruikt data container widgets om data te tonen op pagina’s. Die widgets vind je wederom aan de rechterkant in de Toolbox in Studio Pro.

Op de pagina die we hebben gemaakt vind je al een Data view widget. Die stelt ons in staat om een individueel object te tonen, en de onderliggende attributes als velden in de widget te tonen of invulbaar te maken. De data view toont nu nog (Unknown) als entity, omdat er nog geen entity geselecteerd is.

  1. Open de eigenschappen van de Data view widget

  2. Bij Data source / Entity selecteer je de optie Context en daarna zoek je de Asset entity uit het domain model van MainModule

  3. Klik op OK om op te slaan

  4. Bevestig de vraag met No, want we willen alle velden handmatig toevoegen aan de pagina zodat we ze direct een goed plekje kunnen geven

  5. Verwijder het veld Bio van de pagina

  6. Pas de velden in de pagina aan door erop te dubbelklikken en een andere attribute te selecteren, voor de volgende velden:

    1. First name > Description

    2. Last name > Reference

    3. Email > Purchase price

  7. Selecteer rechts in de Toolbox de Date picker widget en sleep deze op de pagina, onder het veld van de Purchase price

  8. Koppel deze widget aan de attribute DatePurchased

Het laatste dat we nog aan deze pagina willen toevoegen is een selectiemogelijkheid van medewerkers.

  1. Selecteer in de Toolbox de Reference selector widget en sleep deze op de pagina, onder het veld van de Date purchased

  2. Open de eigenschappen van de widget en selecteer bij Attribute (path) onder Data source het volgende pad: Asset / Asset_Employee / Employee / Name

Als het goed is, zou je pagina er nu als volgt uit moeten zien:

We gaan het nu mogelijk maken dat gebruikers deze pagina openen.

  1. Ga naar de pagina Home_Web in MainModule

  2. Verander de titel van de button “Start” naar “New asset”

  3. Verander de On click action van de button naar het aanroepen van een nieuwe microflow die we ACT_Asset_New noemen

  4. Klik met de rechtermuisknop op de button en kies voor “Go to on click microflow” om de microflow eenvoudig te openen

  5. Voeg de volgende acties toe aan de microflow:

    1. Create object: Asset

    2. Show page: Asset_NewEdit (Object to pass: NewAsset)

We hebben nu een microflow gemaakt die een nieuw leeg Asset object aanmaakt en daarna deze doorgeeft aan de Asset_NewEdit pagina. Op die pagina kan de gebruiker het object nu bewerken. Omdat we de actie “Commit” niet uitvoeren bij de Create object microflow activity, wordt het object alleen aangemaakt in het (tijdelijke) geheugen en niet direct in de database. Pas zodra de gebruiker op de Save button klikt op de Asset_NewEdit pagina dan wordt het object definitief weggeschreven naar de database.

De gebruiker kan nu nieuwe activa aanmaken in Mendix. Start je applicatie maar eens opnieuw op via het menu Run / Run locally (F5) en bekijk het resultaat in de browser.

De volgende functionaliteit die we aan de applicatie toe willen voegen is een overzicht van alle activa die in Mendix aangemaakt zijn.

  1. Maak in MainModule / AssetManagement een nieuwe pagina

    1. Layout: Lists / List

    2. Page name: Asset_Overview

    3. Navigation layout: KWEEKERS_TopBar (KWEEKERS_core)

  2. Verander de titel en subtitel van de pagina

  3. Pas de List view widget aan en selecteer de data source Database / MainModule.Asset

  4. Klik op OK en sla de wijzigingen aan de widget op

  5. Als Mendix vraagt om automatisch de velden in de widget in te vullen, klik dan op Yes om te bevestigen

  6. Voeg onder de subtitel een Button toe die de microflow ACT_Asset_New aanroept

  7. Pas de Appearance van de button aan conform onderstaand screenshot zodat deze er wat beter uit gaat zien

We hebben zojuist een pagina aangemaakt waarmee je alle bedrijfseigendommen kunt zien die in Mendix zijn aangemaakt. Voeg deze pagina toe aan de Navigation van je applicatie en start de applicatie opnieuw op om het resultaat te ervaren.

Je zult ervaren dat de list view die je op de Asset_Overview pagina hebt toegevoegd, nog wat liefde verdient voor de uitlijning van de velden. Probeer maar eens te ontdekken of je de uitlijning van de velden verder kunt optimaliseren.

Een logische stap op dit moment in je ontwikkelproces is om de wijzigingen in je model naar de versiebeheer-server te uploaden en je backlog bij te werken.

  1. In de menubalk van Studio Pro, klik op Version Control / Commit

  2. Selecteer de user stories “Medewerkers beheren in Mendix” en “Activa beheren in Mendix” en geef bij Message een beschrijving van de wijzigingen die je zojuist gemaakt hebt

  3. Klik op OK om je wijzigingen naar de server van Mendix te uploaden

  4. In de view Stories, klik achter de geselecteerde user stories twee keer op de status “To-do”, zodat deze naar Running gaat en daarna naar Done

Validatie van gegevens

Bij het ontwikkelen van applicaties is het belangrijk dat data correct en betrouwbaar is. Gebruikers kunnen soms onvoorspelbaar zijn en maken menselijke fouten. Daarom wil je logica kunnen ontwikkelen die de ingevoerde informatie in het formulier valideert en gebruikers informeert als er iets niet in orde is. Dit kan een simpele validatie zijn, bijvoorbeeld of een bepaald veld niet leeg is, of een complexere vorm, bijvoorbeeld een validatie die een berekening doet over meerdere velden tegelijk.

Validaties maken vaak gebruik van expressions om een bepaalde condition te controleren. Een handige functie in Studio Pro bij expressions is de sneltoets Ctrl + Spatiebalk. Daarmee krijg je in de Mendix expression editor een lijst van alle elements en variables waar je op dat moment in de microflow beschikking over hebt.

De volgende soorten elements bestaan in Mendix:

  • Functions: Er zijn veel functions beschikbaar waarmee je informatie uit waardes kunt veranderen, vergelijken of extraheren. Een volledige lijst kan je vinden in Microflow Expressions in de Mendix Docs. Functions gebruiken altijd haakjes () om een functie aan te roepen. Binnen die haakjes plaats je de ingrediënten die nodig zijn om de function te laten werken. Een voorbeeld zou dus kunnen zijn addDays($StartDate, 7)

  • Variables: Een variable is een object, een lijst van objects of een individuele waarde. Een variable start altijd met een dollarteken ($), gevolgd door de naam van de variable. Elk stukje informatie in een microflow is opgeslagen in een variable en heeft een unieke naam. Bijvoorbeeld een object van de Trainee entity is opgeslagen in de $Trainee variable. Attributes van dat object kan je ophalen via een slash achter de variable name, bijvoorbeeld $Trainee/EmailAddress

  • Tokens: Met tokens kan je systeemwaarden uitlezen die bijvoorbeeld te maken met de huidige datum/tijd of ingelogde gebruiker. Deze tokens beginnen en eindigen met een blokhaak []. Een voorbeeld is [%CurrentDateTime%] voor de huidige datum en tijd

Naast deze elementen in de expressies, kan je gebruikmaken van algemene operators:

Een aantal voorbeelden van expressions die je kunt gebruiken in microflows:

  • Gebruik de round() functie om een getal af te ronden. Als de waarde van variable $Number gelijk is aan 0.99 dan kan je met round($Number) het getal afronden naar 1;

  • Gebruik de toLowerCase() functie om een tekst te transformeren naar allemaal kleine letters. Bijvoorbeeld, als de variable $Name gelijk is aan 'BeStName3veR' dan kan je met toLowerCase($Name) de waarde laten transformeren naar 'bestname3ver'.

We gaan nu validatie toevoegen aan een microflow die we aanroepen vanaf de Asset_New pagina om te valideren of de input van de gebruiker volledig is. We gaan enkele validaties toevoegen. Als de uitkomst positief is dan gaan we verder in de microflow. Als de uitkomst negatief is dan tonen we een melding aan de gebruiker en stoppen we met de verdere uitvoering van de microflow.

  1. Ga naar de pagina Asset_NewEdit in MainModule

  2. Open de eigenschappen van de Save knop die onderaan de pagina staat

  3. Wijzig de actie van het on click event naar “Call a microflow” en maak een nieuwe microflow met de naam ACT_Asset_Save

  4. Open de microflow ACT_Asset_Save

Omdat deze microflow in de pagina Asset_NewEdit wordt aangeroepen vanuit een Data view context (Asset), krijgt onze nieuwe microflow automatisch een input parameter mee van het type Object, met een verwijzing naar Asset.

  1. Voeg aan het begin van de microflow een decision toe vanuit de Toolbox

  2. Schrijf in de decision de volgende expression door gebruik te maken van de Ctrl + Spatiebalk mogelijkheid: $Asset/Description != empty

  3. Geef de decision een logische en leesbare titel

Als de decision true (waar) is, dan mag de microflow verdergaan met de uitvoering van het opslaan en verwerken van de Asset. Als de decision false (onwaar) is dan moeten we feedback aan de gebruiker tonen over de onvolledige informatie.

  1. Klik met de rechter muisknop op de lijn van de decision naar de Commit object(s) microflow activity en selecteer Condition value / true

  1. Sleep de microflow activity Validation feedback vanuit de Toolbox onder de decision en verbind de decision met de Validation message activity. Mendix zou op deze lijn automatisch de false conditie moeten toewijzen

  2. Pas de Validation feedback activity aan zodat het op het attribute Description van de entity Asset een melding toont die de gebruiker vertelt dat een Description invullen verplicht is

  3. Voeg onder de Validation feedback activity een End event microflow activity toe om de microflow te instrueren om hier te stoppen met het uitvoeren van de microflow

Als we de applicatie weer opnieuw starten dan zou je een melding moeten krijgen als je het Description veld op de Asset leeg laat. Het voordeel van deze oplossing is dat je de melding kunt laten verschijnen bij het betreffende veld in de data view in de runtime van Mendix, in plaats van een algemene melding te tonen in een pop-up. Probeer het maar eens!

Breid de microflow verder nog uit met validatie op basis van:

  1. Het attribuut Reference mag niet leeg zijn

  2. Het attribuut PurchasePrice mag niet leeg zijn en moet groter zijn dan 0

  3. Het attribuut DatePurchased mag niet leeg en niet groter zijn dan de huidige datum en tijd

  4. Er moet altijd een selectie van een medewerker gemaakt zijn, oftewel de associatie van Asset naar Employee mag niet leeg zijn

Om extra informatie te raadplegen, ga je naar in de Mendix Docs. Gebruik deze informatie om je microflow verder uit te breiden.

Nu je de validatie van de data van het $Asset object hebt ingericht, kan je de “Commit” activiteit toevoegen aan het einde van de microflow. Daarmee zorg je ervoor dat als alle checks zijn gelukt, de data wordt weggeschreven naar de database in Mendix. Het tijdelijke object in het geheugen wordt daarmee definitief opgeslagen.

Tenslotte kan je nog een “Close page” activity toevoegen aan het einde van je microflow, zodat de gebruiker wordt teruggestuurd naar de pagina waar hij/zij zich op bevond voordat de Asset_NewEdit pagina werd geopend.

Dit is een goed moment om je recente wijzigingen te committen naar de version control server van Mendix.

AFAS-integratie inrichten

Nu we de entiteiten van medewerkers en activa een plekje hebben gegeven in de Mendix-applicatie, gaan we er voor zorgen dat de medewerkers automatisch geladen worden uit AFAS. Vanuit KWEEKERS hebben we de integratie tussen Mendix en AFAS gestandaardiseerd middels een gratis module in de Mendix Marketplace, zodat je hiermee snel aan de slag kunt. We beginnen dit hoofdstuk van de workshop met het inladen van een aantal essentiële modules vanuit de Mendix Marketplace.

  1. Open de Mendix Marketplace door rechts bovenin Studio Pro door op het icoontje van het winkelwagentje te klikken

  2. Zoek de volgende modules middels de zoekbalk en klik op Download om ze te importeren als een nieuwe module in je Mendix project:
    Als het systeem vraagt of je bepaalde bestanden wilt overschrijven, dan is dat geen probleem

    1. Community Commons

    2. Encryption (Created by Mendix)

    3. AFAS Profit connector

Met de Encryption module maken we het in de AFAS module mogelijk om de token van jouw AppConnector veilig op te slaan in de database van Mendix.

  1. Configureer de Encryption module door in de App Explorer te navigeren naar App / Marketplace modules / Encryption / Private – String en/de-cryption / Apis / EncryptionKey

  2. Vul in de eigenschappen van de Constant de volgende waarde in bij Default value:
    z9#XzQ**?}EXpcNrMSA!z;XpwJr-[6.r

De volgende stap is het configureren van de AFAS Profit connector module, zodat het mogelijk wordt dat Mendix data gaat uitwisselen met de webservices van AFAS.

  1. Ga naar App Explorer / App / Navigation

  2. Maak na het selecteren van het menu-item “Beheer” met de actieknop “New subitem” een menu-item aan met de naam “AFAS connector”. Kies voor “Show a page” bij de “On click” gebeurtenis en selecteer de pagina Marketplace modules / AfasConnector / _USE_ME / Pages / AfasConnector_Overview

  3. Start je Mendix-applicatie nogmaals met de menu-optie of de sneltoets F5 en open de applicatie nogmaals in de browser met de sneltoets F9

  4. Ga in je Mendix-applicatie via het menu naar Beheer / AFAS connector om de module in te richten

  5. Ga op de pagina naar het tabblad Environments en klik op de tegel van Test om deze omgeving in te richten

  6. Vul de volgende gegevens in:

    1. Member number
      83084

    2. Type
      Test

    3. Authorization token
      <token><version>1</version><data>D7A7D48A48C34F43AEB7C0309CBB2A60EF585F1E4EDE884C66089E9C4F0629CC</data></token>

  7. Klik op Make active om je gegevens op te slaan en direct deze omgeving als standaardomgeving te activeren

Bij het opslaan worden je gegevens direct gevalideerd door aan te melden bij de webservices van AFAS. Als alles gelukt is, dan zal op de pagina het onderdeel Active environment verschijnen waar meer informatie zichtbaar is over de gekoppelde AFAS-omgeving.

Medewerkers ophalen uit AFAS

Nu kunnen we aan de slag met het vertellen van Mendix hoe ze de data uit AFAS kan ophalen en hoe dit vertaald moet worden naar de datastructuur in Mendix. Daarvoor gaan we gebruikmaken van waardevolle functionaliteit in Mendix om automatisch datastructuren op elkaar te “mappen”, oftewel te koppelen.

Om data uit AFAS te halen maken we gebruik van zogenaamde GetConnectoren. Je kunt deze zelf in AFAS definiëren, zodat je altijd enkel de data uit het systeem haalt die je minstens nodig hebt; niet meer en niet minder. Wij hebben alvast een GetConnector voor je gedefinieerd in AFAS, die jij nu mag gaan aanroepen. De naam van die GetConnector is Mx_KweekersConnect_Employees.

De data uit die GetConnector is gestructureerd in een zogenaamd JSON-bestand. Dit is een uniforme wijze om gestructureerde data tussen systemen uit te wisselen. Met een tool zoals connect.afas.nl kan je inzicht krijgen in hoe de structuur van de data in een GetConnector er uit ziet. Ook kan je op de beheerpagina van de AFAS Connector module in jouw Mendix-applicatie gebruikmaken van de Connector tester om die structuur op te roepen. Voor nu maken we het je makkelijk en kunnen we je vertellen dat de structuur van de data er als volgt uit ziet:

Copy to Clipboard

Dit JSON-bestand gaan we inladen in Mendix, zodat Mendix voortaan weet welke data er uit de GetConnector zal komen.

  1. In Studio Pro, maak een nieuwe folder aan in de module MainModule door met de rechter muisknop te klikken op MainModule en te kiezen voor Add folder. Noem deze folder “Integration”

  2. Klik met de rechter muisknop op de nieuwe folder en kies voor Add other / JSON structure en noem dit bestand “JSON_Employees”

  3. Kopieer en plak het JSON-bestand uit de snippet hierboven naar Studio Pro en klik onder Structure op Refresh om te zien of het bestand goed kan worden ingeladen

  4. Klik op OK om op te slaan

Nu dat Mendix weet hoe de structuur van de data er uit komt te zien, gaan we vertellen hoe het die data moet verwerken richting het datamodel in Mendix, oftewel het domain model.

  1. Klik met de rechter muisknop op de folder “Integration” en kies voor Add other / Import mapping en noem dit bestand “IMM_Employees”

  2. In de nieuwe import mapping, klik bij Schema source op JSON structure en selecteer JSON_Employees

  3. Klik op Expand all en Check all, en schakel vervolgens het vinkje uit bij de eerste (Object) en de rows

  4. Klik op OK om op te slaan

Mendix heeft nu een JsonObject gemaakt dat de velden uit het JSON-bestand bevat. Nu gaan we vertellen waar de velden uit dat bestand naartoe mogen in het domain model.

  1. In de het rechter paneel in Studio Pro, klik op het tabblad Connector

  2. Zoek de entity Employee in MainModule en sleep die naar het vlak in de import mapping waar staat “Drag entity here”

  3. Verbind de reeds bekende velden met elkaar:

    1. EmId > EmployeeId

    2. Name > Name

    3. StartDateContract > ContractStart

    4. JobTitle > JobTitle

    5. Email > EmailAddress

  4. De nieuwe/onbekende velden EmployerId en EmployerName laten we leeg, daar gaan we in een volgende stap een oplossing voor vinden

Voordat we de import mapping opslaan, gaan we Mendix vertellen hoe het moet omgaan met het ophalen of aanmaken van entiteiten in het domain model, elke keer dat het JSON-bestand wordt ingelezen. We willen natuurlijk niet dat een medewerker elke keer wordt aangemaakt als de import gedraaid wordt, als deze medewerker al bekend is in de database in Mendix.

  1. In het kader “Obtain Mendix Object” in de eigenschappen van de import mapping, kies voor Find an object (by key)

  2. Achter het veld “EmployeeId”, zet het vinkje aan bij Key

  3. Klik op OK om op te slaan

Zoals je ziet, zijn de laatste twee velden nog niet gekoppeld op je entity uit het domain model. Om dit op te lossen, zou je in principe terug moeten naar je domain model, de entity openen en de attributes handmatig toevoegen, inclusief de juiste veldtypes. Gelukkig zit Mendix boordevol slimmigheden om je werk leuker en efficiënter te maken, ook voor dit scenario. Laten we eens ontdekken hoe dat werkt.

  1. Klik linksboven in de import mapping op de knop “Map automatically”

  2. In de informatiemelding die volgt, klik op Details en scroll helemaal naar beneden

  3. De laatste twee regels zullen je vertellen hoe er automatisch nieuwe attributen zijn aangemaakt op de entity in je domain model

  4. Klik op Close om de melding te sluiten

  5. In de import mapping zul je nu zien dat ook de velden EmployerId en EmployerName zijn toegevoegd

We hebben het nu mogelijk gemaakt dat Mendix de datastructuur van AFAS begrijpt kan verwerken door deze te mappen op een entity in het domain model middels een import mapping. De volgende stap is het maken van een functie die uitgevoerd kan worden om alles bij elkaar te brengen. Die functie kan worden uitgevoerd bijvoorbeeld doordat een gebruiker op een knop klikt of doordat een geplande taak gestart wordt.

Functies en logica modelleer je in Mendix met microflows. Een microflow kan acties uitvoeren zoals objecten aanmaken of bijwerken, pagina’s tonen en beslisbomen afwerken. Het is een visuele manier om iets uit te drukken dat normaal gesproken in tekstuele programmacode wordt uitgedrukt. Voor meer informatie over microflows kan je je richten tot de Mendix documentatie:

Om onze medewerkers uit AFAS op te halen starten we met een simpel stukje logica. We gaan de gebruiker in staat stellen om op een knop te klikken en daarmee de microflow te starten. Later in deze casus kan je er bijvoorbeeld voor kiezen om de microflow te starten middels een geplande taak, of elke keer wanneer iemand de applicatie opstart.

  1. Klik in de App Explorer met de rechter muisknop op de folder “Integration” en kies voor Add microflow en noem dit bestand “ACT_Employees_Retrieve”

  2. Het canvas van Studio Pro zal nu de bewerkfunctie van microflows openen

Rechts van de microflow editor vind je de Toolbox. Daarin vind je alle activiteiten die je toe kunt voegen aan je microflow. Met de KWEEKERS AFAS connector module uit de Mendix Marketplace komen ook een aantal standaard activiteiten mee die je toe kunt voegen aan je microflow vanuit de Toolbox.

  1. Scroll door de toolbox of zoek in de zoekbalk naar de activiteit genaamd “GetConnector” en sleep deze op het lijntje van je microflow

Studio Pro zal nu in de view “Errors” 5 foutmeldingen tonen die we dienen op te lossen voordat we de applicatie opnieuw kunnen starten. Met die foutmeldingen valideert Mendix continu het model van jouw applicatie.

De activiteit die je in je microflow hebt gesleept noemen we een microflow call activity. Daarmee wordt een andere (standaard) microflow aangeroepen uit de KWEEKERS module die een stukje herbruikbare code beschikbaar stelt. In dit geval is dat het aanroepen van een GetConnector op één uniforme wijze. Het resultaat van de microflow die we hier aanroepen is een HttpResponse met als inhoud het antwoord van de AFAS GetConnector in JSON-formaat.

  1. Dubbelklik op de microflow activity om de eigenschappen van de aanroep te openen

  2. Vul de volgende parameters in:

    1. Connectorid: 'Mx_KweekersConnect_Employees'

    2. Take: 1000

    3. Skip: 0

    4. QueryString: ''

  3. Pas de Object name van de return variable aan van Variable naar HttpResponse

  4. Klik op OK om op te slaan

Het resultaat van de microflow activity heeft dus een return variable van het type System.HttpResponse met de naam HttpResponse. Deze variable kan je later in je microflow gebruiken als input voor andere microflow activities. Dat komt goed uit, want we gaan dit als input gebruiken bij het aanroepen van de import mapping die we eerder ontwikkeld hebben. De HttpResponse bevat tenslotte de JSON-data van het resultaat van de GetConnector van AFAS die we in de import mapping gebruiken om in te lezen op de entity in het domain model.

  1. Sleep uit de Toolbox de activity Import with mapping in je microflow, achter de microflow activity van het aanroepen van de GetConnector

  2. Open de eigenschappen van de microflow activity Import with mapping

  3. Kies de HttpResponse als input variable

  4. Selecteer jouw import mapping MainModule.IMM_Employees

  5. Selecteer No bij Commit

  6. Kies voor Yes bij Store in variable en noem de Variable name EmployeeList

  7. Klik op OK om op te slaan

  8. Sleep uit de Tooling de activity Commit object(s) in je microflow, achter de microflow activity die de import mapping uitvoert

  9. Open de eigenschappen van de microflow activity Commit object(s)

  10. Selecteer bij Object or List de EmployeeList van de voorgaande microflow activity

  11. Selecteer Yes bij de optie Refresh in client

  12. Klik op OK om op te slaan

  13. Klik met de rechter muisknop op je microflow activity van “Import with mapping” en kies voor “Set $EmployeeList as return variable”

We hebben nu een microflow die:

  • Een submicroflow aanroept om de GetConnector van AFAS te raadplegen en het resultaat opslaat in een HttpResponse

  • Een import mapping aanroept met het resultaat van de GetConnector om de entiteiten uit het domain model aan te maken en dit teruggeeft als een lijst van objecten van de entiteit Employee

  • De lijst van Employees opslaat naar de database door middel van de Commit object(s) activity

  • Het resultaat van de import mapping (een lijst van objecten van het type Employee) teruggeeft, voor als jouw microflow in de toekomst als submicroflow in een andere bovenliggende microflow aangeroepen wordt

In dit specifieke geval hebben we er voor gekozen om het committen van de gegevens naar de database in een losse microflow activity te doen, in plaats van direct in de Import with mapping activity. De reden hiervan is dat dit ons in staat stelt om de actie “Refresh in client” uit te voeren. Dat zal er straks voor zorgen dat als jij op de knop klikt in de applicatie om de microflow te starten, je jouw resultaten direct zult zien verschijnen in het scherm zonder dat je de pagina hoeft te verversen.

De volgende stap is het toevoegen van een knop om de microflow aan te roepen vanuit jouw applicatie.

  1. In de App explorer, open de pagina MainModule / OverviewPages / Employee_Overview

  2. In de Toolbox, selecteer de widget Call microflow button en sleep deze ergens op de pagina

  3. Selecteer de microflow MainModule / Integration / ACT_Employees_Retrieve

  4. Hernoem de caption op de button naar “Retrieve employees” door te dubbelklikken op de button en daarmee het eigenschappenscherm van de widget te openen

Het is tijd om weer het resultaat van je applicatie te bekijken in de Mendix runtime.

  1. Start de applicatie door op F5 te drukken en open de applicatie met F9 in de browser zodra je lokale server gestart is

  2. Ga in de menubalk naar Beheer / Medewerkers

  3. Klik op de pagina op de button die je hebt toegevoegd

  4. Als alles goed gaat, zal je moeten zien dat er ongeveer 144 medewerkers worden opgehaald uit AFAS en getoond worden op de pagina die je voor je hebt

Gefeliciteerd! Je hebt zojuist je eerste integratie met AFAS gemaakt vanuit Mendix. In de volgende stappen zullen we steeds een stukje soepeler worden in de manier waarop we stapsgewijs de casus toelichten. Dat helpt je om beter te begrijpen waar je precies zit in Studio Pro en hoe bepaalde concepten met elkaar samenhangen.

Een logische stap op dit moment in je ontwikkelproces is om de wijzigingen in je model naar de versiebeheer-server te uploaden en je backlog bij te werken.

  1. In de menubalk van Studio Pro, klik op Version Control / Commit

  2. Selecteer de user story “Medewerkers ophalen uit AFAS” en geef bij Message een beschrijving van de wijzigingen die je zojuist gemaakt hebt

  3. Klik op OK om je wijzigingen naar de server van Mendix te uploaden

  4. In de view Stories, klik achter de user story “Medewerkers ophalen uit AFAS” twee keer op de status “To-do”, zodat deze naar Running en daarna naar Done gaat

Mendix heeft zojuist een nieuwe versie aangemaakt op de server op basis van jouw laatste wijzigingen. Als je zou samenwerken met meerdere ontwikkelaars op hetzelfde project, dan zou dit het moment zijn waarop je een andere collega in staat stelt om jouw laatste versie van de applicatie binnen te halen en samen te voegen met zijn/haar wijzigingen. Op die manier kan je zorgeloos lokaal verder ontwikkelen, en op gezette tijden verschillende versies met elkaar uitwisselen en samenvoegen.

Activa aanmaken in AFAS

We hebben het mogelijk gemaakt om bedrijfseigendommen aan te maken en in te zien in Mendix. In het verlengde daarvan gaan we het mogelijk maken om de bedrijfseigendommen in te schieten naar AFAS, om ze ook daar aan te maken.

Data bewerken in AFAS is mogelijk middels de zogenaamde UpdateConnectoren. Daarmee kan je via webservices data in de database van AFAS aanmaken, bewerken of verwijderen. Wij gaan gebruikmaken van de FiFixedAssets UpdateConnector. Voor meer informatie over de werking van die connector kun je je richten tot de AFAS Help of AFAS Connect. Omwille van de voortgang in deze workshop hebben we een aantal details alvast voor je uitgewerkt.

We maken in dit geval wederom gebruik van een JSON-bestand dat we middels de REST API van AFAS uitwisselen met het systeem. De structuur van dat bestand vind je in de specificatie hieronder:

Copy to Clipboard

We gaan de microflow ACT_Asset_Save achter de de Save button op de Asset_NewEdit pagina aanpassen zodat het een microflow aanroept in plaats van de gegevens direct op te slaan naar de database van Mendix.

Open de pagina MainModule.Asset_NewEdit

Klik met de rechter muisknop op de knop Save en kies voor Go to on click microflow (ACT_Asset_Save)

Zoek in de toolbox naar de microflow activity AFAS Connector UpdateConnector POST en voeg deze toe aan de microflow voor de “Commit changes” activity

  1. Connectorid: ‘FiFixedAssets’
  2. Request:
Copy to Clipboard

  1. Output object name: HttpResponse

Door op deze wijze de UpdateConnector van AFAS aan te roepen, worden automatisch de velden van de activa in Mendix overgenomen naar de technische velden in de UpdateConnector in AFAS. Het fijne van de UpdateConnector van AFAS is dat we als antwoord op een succesvolle aanroep van de UpdateConnector mogen vernemen met welk nummer de activa zijn aangemaakt in AFAS. AFAS geeft daarvoor de volgende JSON-structuur terug:

Copy to Clipboard

Als we dit activanummer (SeNo) willen tonen aan de eindgebruiker van onze applicatie nadat de activa is aangemaakt in AFAS dan zullen we deze JSON-data weer moeten mappen op een (tijdelijke, non-persistable) entity in het domain model door middel van een import mapping. En ook willen we deze instelling opslaan op onze Asset entity in de database, zodat we in de toekomst kunnen herleiden vanuit Mendix welk ID de activa heeft gekregen in AFAS.

  1. Maak een nieuwe JSON-structure met bovenstaande JSON-bestand en noem deze JSON_FiFixedAssets_Response

  1. Maak een nieuwe import mapping op basis van de nieuwe JSON-structure en noem deze IMM_FiFixedAssets_Response

  2. Selecteer in die import mapping enkel het object FiFixedAssets en het onderliggende attribuut SeNo (zie screenshot)

  1. Maak automatisch een (tijdelijk, non-persistable) object in de database door in de import mapping op de knop Map automatically te klikken

We hebben zojuist een non-persistable entity laten aanmaken in het domain model. Zo’n entity bestaat te allen tijde alleen tijdelijk in het geheugen van de applicatie, in het kader van de sessie van de huidige gebruiker, en zal dus nooit in de database worden opgeslagen of uitgewisseld met andere gebruikers. Dat betekent dat als jij de browser sluit of de pagina ververst, het object automatisch uit het geheugen zal worden gewist. We gebruiken dit tijdelijke object FiFixedAssets om het antwoord van AFAS te verwerken op een logische entiteit in Mendix, waarna we het op het definitieve object van de entity Asset verwerken.

  1. Pas de entity Asset in het domain model van MainModule aan door er een String attribute met de naam AfasAssetId aan toe te voegen

We hebben nu een tijdelijk (non-persistable) object met het waarde van het antwoord van AFAS, en een permanent (persistable) object waar dit naar weggeschreven moet worden. We gaan nu de microflow ACT_Asset_Save aanpassen zodat het deze data netjes verwerkt.

  1. Voeg een microflow activity van type Import with mapping toe achter de microflow activity die de UpdateConnector aanroept. Map de HttpResponse middels de import mapping MainModule.IMM_FiFixedAssets_Response en sla het in de microflow op in een return variable genaamd FiFixedAssets

  2. Voeg een microflow activity van type Change object toe als laatste microflow activity en verander het attribuut AfasAssetId van het object Asset naar de SeNo van het tijdelijke object. Commit de wijzigingen direct naar de database en schakel de optie “Refresh in client” in

  3. Verwijder de Commit microflow activity die al onderdeel was van de microflow

  4. Voeg een Close page microflow activity toe

  5. Voeg een Show message microflow activity toe en toon een melding waarin het SeNo wordt getoond aan de gebruiker

Start je applicatie opnieuw middels de sneltoets F5 en F9 en controleer of alles werkt zoals verwacht. Houd er rekening mee dat het verwerken in AFAS enige tijd kan duren en dat het dus enkele seconden kan duren voordat je de melding met het activa ID in het scherm te zien krijgt.

Nice-to-haves

Gefeliciteerd! Je hebt de basis van de workshop succesvol doorlopen. Naast deze “Minimum Viable Product” (MVP) hebben onze gebruikers nog een aantal wensen die ze graag geïmplementeerd zouden zien. Gebruik het volgende hoofdstuk om de uitdaging aan te gaan en de vraagstukken naar eigen inzicht te implementeren.

  1. Page building

    1. Pas opmaak toe op de teksten in de List view widget op de Asset_Overview pagina

    2. Voeg conditional visibility toe op de Asset_NewEdit pagina

    3. Voeg een voortgangs-indicator toe zodra een gebruiker klikt op de Save button op de Asset_NewEdit pagina

    4. Verander de layout van de Asset_NewEdit pagina naar een popup-layout

  2. Microflows

    1. Trigger het verversen van alle medewerkers in Mendix zodra de ACT_Asset_New wordt aangeroepen, zodat je altijd de meest actuele set van medewerkers hebt als je nieuwe activa wilt aanmaken

    2. Verander de validatie in de ACT_Asset_Save microflow zodat alle validatie-teksten tegelijk getoond worden als er meerdere validaties afgekeurd worden

    3. Maak een scheduled event dat elke nacht draait en alle medewerkers uit AFAS opnieuw ophaalt

  3. Functionaliteit

    1. Bereken de afschrijvingskosten per jaar bij het aanmaken van nieuwe activa door het vastleggen van de aanschafprijs, restwaarde en afschrijfperiode in jaren

    2. Maak een lijst van uit te delen activa voor alle activa waarvan de gekoppelde medewerker een indienstdatum heeft die in de toekomst ligt

    3. Activeer security in je applicatie en richt de applicatie in zodat er gebruik wordt gemaakt van module roles en entity access

    4. Gebruik de workflowmodule van Mendix om een workflow te starten voor het goedkeuren van de toewijzing van bedrijfseigendommen aan medewerkers

    5. Verstuur een e-mail naar de gebruiker zodra er een nieuw bedrijfseigendom wordt toegewezen. Raadpleeg de documentatie voor meer informatie: