Periodieken - macro editor

Project bevindt zich in pilotfase. In deze documentatie wordt de eerste versie van de functionaliteit beschreven. - 17-11-2023

Met behulp van deze macro editor is het mogelijk om een macro te maken die je vervolgens kan instellen zodat wordt gesignaleerd op een datum waarop er een periodiek is. Een macro kan uit een of meerdere regels bestaan, waarbij elke regel een conditie en resultaat heeft. Zo kun je verschillende omstandigheden signaleren, bijvoorbeeld jeugdschalen of functieperiodieken, beloningen bij een bepaalde periode in dienst, etc.

De macro editor bestaat uit twee delen, het eerste deel is de conditie, en de tweede het resultaat. De naam die je aan de macro regel geeft wordt op het bijbehorende overzicht getoond. Een regel komt op het overzicht als er aan de conditie wordt voldaan, en het resultaat (een datum) binnen het bereik van je overzicht valt. De macro’s zijn hoofdlettergevoelig, maar witregels mogen vrij worden geplaatst om de macro leesbaarder te maken.

Op deze pagina staat de technische toelichting.

Conditie

In de conditie sectie van de macro editor kan aan de hand van bijvoorbeeld verschillende functies, variabelen, rekenkundige operaties worden bepaald wanneer de macro precies moet worden uitgevoerd. De conditie moet daarom altijd aan ‘true’ of ‘false’ waarde teruggeven als resultaat.

Bijvoorbeeld, de macro in onderstaand screenshot is alleen actief voor de flexwerker als zijn leeftijd 20 jaar of jonger is.

De conditie is optioneel. Wanneer deze niet is ingevuld, dan komt er altijd een datum uit deze regel (het resultaat).

Indien de ingevoerde conditie code-technisch niet voldoet, wordt in de enkele regel eronder aangegeven wat er onjuist is.

Resultaat

De resultaten sectie van de editor heeft als doel om de specifieke datum waarop gesignaleerd moet worden te bepalen. De resultaten sectie moet daarom dus altijd een datum als uiteindelijke resultaat teruggeven. Deze kan bijvoorbeeld bepaald worden aan de hand van verschillende functies, variabelen, rekenkundige operaties.

Op de datum die hier uit komt wordt gesignaleerd.

Als het resultaatveld bijvoorbeeld dagmaand_volgende(1, 5) bevat, krijg je op iedere 1 mei een signalering.

Indien het ingevoerde resultaat code-technisch niet voldoet, wordt in de enkele regel eronder aangegeven wat er onjuist is.

Waardes

Waardes in de macro editor kunnen een bepaald aantal types zijn. Er wordt gerefereerd naar deze types.

• int: Een geheel getal, bijv 5, 7, 12, 365

• number: een decimaal getal, bijv 5.0, 6.4, 14.44

• bool: een Boolean, een waarde die altijd true of false is, waar of niet waar. Afvinkvelden zijn bijvoorbeeld booleans, of condities (5 > 2 geeft ‘true’, meer hierover bij ‘Vergelijken’ en ‘Logische operaties’)

• string: een tekst, bijv "hallo wereld". Om een string te maken gebruik je de dubbele aanhalingstekens: "

• date: een datum, bijv datum(1, 1, 2023)

Hoe gebruik ik de functiedocumentatie?

Hieronder vind je een aantal functies en waardes die je kan gebruiken om zelf signaleringen samen te stellen. Functies geven aan wat voor soort waardes er in de invoer mogen komen, en wat de uitvoer is.

Functies hebben een bepaalde invoer, de variabelen (zie ‘Standaard variabelen’) hebben alleen een uitvoer. De types die je hebt staan hierboven beschreven onder ‘Waardes’. Als er in de documentatie naar een date wordt gerefereerd, dan gaat het om een datum-waarde.

De documentatie geeft functies als functie(invoertype, invoertype, ...) -> uitvoertype, en variabelen als VARIABELE -> uitvoertype.

Onder rekenkundige operaties heb je bijvoorbeeld round(number) -> int. Dit betekent dat je een number (een decimaal getal) als invoer kan opgeven, en dit een int (een geheel getal) als resultaat geeft. Je gebruikt de functie dan bijvoorbeeld met round(4.15) voor een resultaat van 4 of round(19.97) voor een resultaat van 20.

De types moeten altijd aansluiten, maar je kan op plekken waar om een number gevraagd wordt ook een int gebruiken. Andersom kan dit niet. Heb je een number en wil je die op de plek van een int gebruiken, dan moet het getal afgerond worden met een van de rekenkundige operaties.

PEILDATUM is een veel gebruikte variabele waar een date uit komt. Dit is de peildatum van het overzicht “Macro’s cao-regelingen”. Omdat het resultaat van een signaleringsregel ook een date moet zijn, is PEILDATUM op zichzelf een geldig resultaat.

Je kan deze ook meegeven aan functies die een date verwachten. Onder ‘Datumfuncties’ vind je bijvoorbeeld einde_week(date) -> date. Dit betekent dat hier een date kan worden meegegeven, en er een nieuwe date uit komt - in dit geval het begin van de week van de meegegeven datum. Als je resultaat einde_week(PEILDATUM) is, krijg je hier de laatste dag van de week van de peildatum uit.

Je kan de uitvoer van functies ook gebruiken als invoer van andere functies. Stel dat je de laatste dag van de eerstvolgende week nodig hebt; je kan de peildatum in de volgende week krijgen met plus_dagen(PEILDATUM, 7). Hier komt ook een date uit, 7 dagen na de peildatum. Deze date is ook geldige invoer voor einde_week. Zo kun je met einde_week(plus_dagen(PEILDATUM, 7)) het einde van de volgende week krijgen.

Rekenkundige operaties

De volgende rekenkundige operaties worden ondersteund. Je kan int en number hier door elkaar gebruiken; als alle getallen int zijn dan is het resultaat ook int, anders wordt het number. Delen is hierop een uitzondering, hier komt altijd een number uit, zelfs als de uitkomst een heel getal is.

• Plus(+):  Tel twee getallen bij elkaar op, bijv 2 + 5 = 7

• Min(-): - Trek twee getallen van elkaar af, bijv 9 - 3 = 6

• Delen(/): Deel twee getallen door elkaar, bijv 8 / 2 = 4

• Maal(*): Vermenigvuldig twee cijfers met elkaar, bijv 3 * -2 = -6

• round(number) -> int: Rond getal af naar dichtstbijzijnde hele getal, bijv round(4.3) = 4

• round(number, int) -> number: Rondt getal af naar dichtstbijzijnde getal met een aantal cijfers achter de komma, bijv. round(4.5271, 2) = 4.53

• ceil(number) -> int: Rond getal af naar boven, bijv ceil(4.3) = 5

• floor(number) -> int: Rond getal af naar beneden, bijv floor(4.8) = 4

Men kan ook meerdere rekenkundige operaties achter elkaar gebruiken om zo moeilijkere berekeningen te doen. In dit geval wordt de standaard bewerkingsvolgorde toegepast voor de som. Dit is, eerst wat tussen haakjes staat, dan vermenigvuldigen/delen, en dan optellen/aftrekken.

Bijvoorbeeld: 5 + 7 * (2 + 2 * 4) / 2 geeft 40.

Vergelijken

Het is mogelijk om in de macro twee waardes te vergelijken, het resultaat is dan altijd een bool, dus true of false. De twee waardes die worden vergeleken moeten wel van hetzelfde type zijn, dus bijvoorbeeld int en int, string en string, of bool en bool. Een uitzondering hierop is dat een number en int wel met elkaar vergeleken kunnen worden. Let hierbij op dat het type string hoofdlettergevoelig is.

• Groter dan (>): Kijkt of de eerste waarde groter is dan de tweede, bijv 4.5 > 3 geeft true, datum(17, 8, 2023) > datum(17, 8, 2024) geeft false, en 7 > 7 geeft false.

• Kleiner dan (<): Kijkt of de eerste waarde kleiner is dan de tweede, bijv 9 < 5 geeft false, datum(17, 8, 2023) < datum(17, 8, 2024) geeft false, en 7 < 7 geeft false.

• Groter gelijk dan (>=): Kijkt of de eerste waarde groter is dan de tweede, bijv 4 >= 3 geeft true, datum(17, 8, 2023) >= datum(17, 8, 2024) geeft false, en 7 >= 7 geeft true.

• Kleiner gelijk dan (<=): Kijkt of de eerste waarde kleiner is dan de tweede, bijv 9 <= 5 geeft false, datum(17, 8, 2023) <= datum(17, 8, 2024) geeft false, en 7 <= 7 geeft true.

• Gelijk (==): Kijkt of twee waardes gelijk aan elkaar zijn, bijv 5 == 5 geeft true en datum(1, 1, 2000) == datum(1, 1, 2000) geeft true, en "ABC" == "DEF" geeft false.

• Niet gelijk (!=): Kijkt of twee waardes niet gelijk aan elkaar zijn, bijv 4.7 != 4.7 geeft false en datum(1, 1, 2020) !=  datum(1, 1, 2000) geeft true, en "ABC" != "DEF" geeft true.

Logische operaties

Operaties op boolean waardes die dan een nieuwe boolean als resultaat geeft. Je kan hier een onbeperkte hoeveelheid invoerwaardes aan meegeven.

• and: Geeft true als alle input waardes true zijn, bijv and(true, true) geeft true, and(true, false) geeft false.
  Dit kan gebruikt worden om te controleren of meerdere condities waar zijn, bijvoorbeeld and(LEEFTIJD_FW < 21, memo_fw_afvink(1234)) als je wil dat een bepaald memoveld (hierover later meer) voor de flexwerker is afgevinkt, en de flexwerker jonger dan 21 jaar is.

• or: Geeft true als één van de input waardes true is, bijv or(true, true) geeft true, or(true, false) geeft ook true en or(false, false) geeft false.
  Dit kan gebruikt worden om te controleren of minimaal 1 conditie waar is, bijvoorbeeld or(LEEFTIJD_FW < 21, memo_fw_afvink(1234)) als je wil dat de signalering zowel afgaat voor iedereen onder de 21 als iedereen met een bepaald afvinkveld.

Het kan voor jezelf overzichtelijker worden gemaakt door in geval van meerdere condities in één regel, de condities per lijn uit te werken. Dit kun je doen op de volgende manier.
Allereerst is het goed om te weten dat het dan nodig is om te werken met meerdere ‘haakjes’. Door middel van de haakjes wordt namelijk onderscheid gemaakt in de invoerwaardes. De ‘and’ of ‘or’ en het eerste haakje openen zet je op de eerste lijn, de eerste conditie op de tweede lijn, de tweede conditie op de derde lijn etc. Op de laatste lijn komt het haakje sluiten. Om het voorbeeld uit de ‘and’ (in de bullet) te gebruiken; dit is and(LEEFTIJD_FW < 21, memo_fw_afvink(1234)). Dit is als volgt te ‘ontleden’:
and(
LEEFTIJD_FW > 21,
memo_fw_afvink(1234)
)
Op de eerste lijn komt de operatie en het haakje openen. Op de tweede lijn komt de eerste conditie te staan die wordt beëindigd met een komma. De komma illustreert dat er een conditie volgt. Op de derde lijn volgt de tweede conditie; die krijgt geen komma, omdat er geen nieuwe conditie volgt. Wel zijn er haakjes nodig om de waarde van de memo te kunnen benoemen. Op de laatste lijn volgt het haakje sluiten. Dit haakje sluiten heeft betrekking op het haakje openen in de eerste lijn.
Als je een conditie wil toevoegen, dan kan die als tweede, derde of vierde lijn worden ingegeven. Bijvoorbeeld:
and(
LEEFTIJD_FW == 21,
memo_fw_afvink(1234),
memo_rl_getal(100)
)
Nu is aan het einde van de derde lijn een komma toegevoegd, omdat er een nieuwe conditie op volgt.

Standaard variabelen

De macro editor ondersteunt verschillende standaard variabelen, dit zijn waardes over een flexwerker die de macro kan gebruiken om berekeningen of bepalingen mee te doen. De variabelen zijn altijd volledig in hoofdletters. De standaard variabelen en de types daarvan zijn:

• STARTDATUM_PLAATSING -> date: De startdatum van de plaatsing waarvoor de macro wordt uitgevoerd.

• GEBOORTEDATUM_FW -> date: De geboortedatum van de flexwerker voor wie de macro wordt uitgevoerd.

• LEEFTIJD_FW -> int: De leeftijd van de flexwerker voor wie de macro wordt uitgevoerd, op de dag van de peildatum. Dit kan bijvoorbeeld worden gebruikt om te kijken of de flexwerker ouder is dan een bepaalde leeftijd, LEEFTIJD_FW >= 21

• VERJAARDAG_FW -> date: De eerstvolgende verjaardag van de flexwerker voor wie de macro wordt uitgevoerd.

• PEILDATUM -> date: De peildatum voor de macro. Dit kan je bijvoorbeeld gebruiken om te kijken of de dag waarom de macro wordt uitgevoerd na een bepaalde datum is, PEILDATUM>= datum(1,1,2023)

Functies

De macro editor biedt verschillende hulpfuncties. De invoer van de functies kunnen ook variabelen of andere functies zijn met het juiste uitvoertype.

Het formaat van de onderstaande functies is functie(invoertype, invoertype, ...) -> uitvoertype. Dit

De in- en uitvoer van deze functies moeten altijd van een bepaald type zijn. Hieronder staat bijvoorbeeld jaar_van(date) -> int. Dit betekent dat de invoer van de functie altijd een date is, en de uitvoer een int. Voor datum(int, int, int) -> date betekent dit 3 keer int als invoer, en een date als uitvoer. Wat deze types betekenen staat beschreven onder Waardes.

• datum(int, int int) -> date: Maakt een datum, in de volgorde dag, maand, jaar. datum(1, 5, 2023) betekent 1 mei 2023. datum(1, 5, jaar_van(PEILDATUM)) geeft bijvoorbeeld 1 mei in het jaar van de peildatum.

• dagen_verschil(date, date) -> int: Heeft als input twee datums, en berekend hoeveel dagen er tussen zitten, bijv dagen_verschil(datum(31, 7, 2023), datum(28, 8, 2023)) geeft 28 en dagen_verschil(datum(20, 1, 2022), datum(10, 1, 2022)) geeft -10.

• plus_dagen(date, int) -> date: Heeft als input een datum en een aantal dagen, en telt het aantal dagen de bij de datum op. Zowel plus_dagen(datum(01, 01, 2023), 2) als plus_dagen(datum(05, 01, 2023), -2) komen uit op 3 januari 2023. plus_dagen(PEILDATUM, 10) geeft 10 dagen na de peildatum.

• dagmaand_volgende(int, int) -> date: Heeft als input twee ints, waarvan de eerste de gewenste dag is en de tweede de maand, en geeft als resultaat de eerst volgende datum met de betreffende dag/maand combinatie, bijv dagmaand_volgende(10, 1) geeft de eerstvolgende keer wanneer het 10 januari is.

• gewerkte_uren_in(int)-> number: Het aantal gewerkte uren wat in tewerkgesteld/werkhistorie staat voor het ingegeven jaar, bijvoorbeeld gewerkte_uren_in(2023). Afgerond op 2 decimalen achter de komma.

• jaar_van(date) -> int: Geeft het jaar van een datum terug als int, bijvoorbeeld jaar_van( datum(1, 1, 2023) ) geeft 2023.

• kalenderjaar_van(date) -> int: Geeft het kalenderjaar van de week waarin een datum ligt terug als int, bijvoorbeeld kalenderjaar_van( datum(1, 1, 2023) ) geeft 2022 aangezien 1 januari 2023 nog in week 52 valt van 2022.

• ifelse(bool, any, any) -> any: Functie met 3 parameters, de eerste moet altijd een boolean zijn en de tweede en derde van hetzelfde type, indien de boolean true is, geeft deze de eerste waarde terug, anders de tweede.
  Bijvoorbeeld ifelse(5 > 2, "ja", "nee"), geeft “ja” terug en ifelse(5 < 2, datum(1, 1, 2023), PEILDATUM) geeft de peildatum terug.

Memofuncties

Je kan de invulling van memovelden bij de flexwerker, relatie of plaatsing ophalen om te gebruiken in je macro. Hiermee kun je in gegevens voorzien die niet op een andere plaats in Easyflex kunnen worden vastgelegd, zoals:
- (met het oog op het feit in de eerste versie alleen wordt gecontroleerd bij actieve plaatsingen) een eerste datum in dienst bij een relatie. Handig indien er meerdere plaatsingen zijn geweest, bijvoorbeeld vanwege verschillende kostenplaatsen)
- of de werknemer een BBL’er is
- het behalen van een diploma in de horeca die gevolgen heeft voor de loonschalen van de flexwerker

?? in onderstaande functies dient vervangen te worden met een van de types:

• fw voor het ophalen van flexwerker memovelden

• rl voor het ophalen van relatie memovelden

• job voor het ophalen van plaatsing memovelden

Bijvoorbeeld memo_job_datum voor een memo datumveld in de plaatsing, of memo_fw_afvink voor een afvinkveld bij de flexwerker.

De invoer voor alle functies is het referentienummer van het memoveld. Dit referentienummer kun je vinden onder beheer > memovelden, en staat bovenin na het selecteren van een gewenst memoveld. Als je een functie van een fout type gebruikt (bijvoorbeeld memo_tekst terwijl het referentienummer voor een datum invoerveld is) geeft dit een fout bij het uitvoeren van de macro en wordt het memoveld niet gevonden.

• memo_??_tekst(int) -> string: Geeft de invulling van een memo tekstveld terug. Als het veld niet gevuld is komt hier een lege stringuit, ""

• memo_??_datum(int) -> date: Geeft de invulling van een memo datumveld terug. Als het veld niet gevuld is geeft de macroregel een fout.

• memo_??_getal(int) -> int: Geeft de invulling van een memo getalveld terug. Als het veld niet gevuld is geeft de macroregel een fout.

• memo_??_bedrag(int) -> int: Geeft de invulling van een memo bedragveld terug. Als het veld niet gevuld is geeft de macroregel een fout.

• memo_??_keuze(int) -> string: Geeft de tekst van een memo keuzeveld terug. Als er geen keuze is gemaakt geeft de macroregel een fout.

• memo_??_afvink(int) -> bool: Geeft aan of een memo afvinkveld wel of niet is aangevinkt. Standaard is een veld niet aangevinkt en geeft dit false.

De ‘(int)’ is in dit geval het rubrieknummer dat te zien is bij de betreffende memo in ‘Beheer > Bedrijfsinstellingen > Ontwerp memobladen’.

Datumfuncties

Er zijn ook een aantal datumfuncties beschikbaar. Deze geven allemaal een date terug:

Commentaar

De macro’s kunnen worden voorzien van commentaar. Alles achter een # wordt gezien als commentaar, bijvoorbeeld 5 + 5 #Telt twee getallen bij elkaar op doet hetzelfde als 5 + 5. Hiermee kun je opmerkingen plaatsen om het onderhoud van de macro te verduidelijken. Alle tekst achter de hashtag (inclusief) wordt dus genegeerd. Het is daarbij van belang dat in geval van meerdere condities in een regel deze per lijn uitgewerkt worden.

--

→ Ga naar de voorbeeldregels voor de macro editor