Scripts schrijven

Een script is logica in Python die op de server draait, binnen de app. Het is het juiste onderdeel voor alles wat geen scherm en geen eenvoudige query is: gegevens synchroniseren met een ander systeem, elke ochtend indicatoren herberekenen, een Excel genereren en per e-mail versturen, een bestand valideren dat via een API is geüpload.

Hetzelfde script kan op drie manieren worden gestart — en de code verandert niet:

Trigger	Hoe het gebeurt
Handmatig	De knop Nu uitvoeren in de editor, met optionele argumenten.
Cron	Een planning (hoofdstuk Planningen) — op vaste tijden, met intervallen, of in een bewakingsvenster.
API	Als stap van een API van de app — het script krijgt de argumenten van het verzoek en het resultaat van de vorige stap.

Op deze pagina gebruiken we het script atualizar_indicadores uit de app Klantenbeheer, dat elke ochtend de commerciële indicatoren van het CRM herberekent.

#Waar de scripts leven

Binnen de app hebben de scripts hun eigen sectie in de boomstructuur van de zijbalk — de groep Scripts. Elk script is een knoop in de boom: klikken op de naam opent de editor in een tabblad van de werkruimte, en de pijl links klapt de knoop uit om zijn Bestanden, zijn Afhankelijkheden en zijn Planningen te tonen (de volgende pagina's van dit hoofdstuk).

Er is ook een lijstweergave — de pagina Scripts — met één regel per script:

Kolom	Wat die toont
Naam	Naam en beschrijving van het script.
Runtime	De uitvoeringstaal (Python).
Status	Actief of Concept — alleen de actieve draaien volgens planning.
Planningen	Hoeveel planningen er bestaan, hoeveel er actief zijn, en Volgende: met de datum van de volgende geplande uitvoering.
Laatste uitvoering	De status (Succes, Fout, …) en het tijdstip van de meest recente uitvoering.

#Een script aanmaken

1. Ga in de boomstructuur van de zijbalk met de muis over de regel van de groep Scripts en klik op de knop + (Nieuw script).

2. Vul het venster Nieuw script in:

   Veld	Opmerkingen
   Naam	Verplicht. Bijv.: klanten-synchroniseren. Onder deze naam wordt het script aangehaald in de planningen en in de API's.
   Runtime	Vast: Python. Uitvoering op de server is alleen met Python.
   Beschrijving	Optioneel — "Wat doet dit script?" verschijnt in de lijst en in de boom.
   Tijdslimiet	30 seconden, 1 minuut, 2 minuten, 5 minuten of 10 minuten. Bij overschrijding wordt het proces beëindigd en wordt de uitvoering als time-out gemarkeerd.

3. Klik op Script aanmaken. Het script wordt geboren met de begincode (het contract in beeld, als commentaar) en de editor opent meteen in een tabblad.

#Het contract: main(input)

Elk script heeft een ingangsbestand, main.py, met een functie main. Het platform roept die bij elke uitvoering aan en de teruggegeven waarde is het resultaat van het script:

def main(input):
    return {"ok": True}

De parameter input brengt altijd drie sleutels mee:

Sleutel	Inhoud
input["args"]	Woordenboek met de argumenten van de uitvoering — die u in het venster Nu uitvoeren hebt getypt, die in de planning zijn vastgelegd, of die de API heeft doorgegeven. De waarden komen als tekst aan.
input["prev"]	Het resultaat van de vorige stap, wanneer het script binnen een API draait. Bij handmatige en geplande uitvoeringen is het None.
input["context"]	Metagegevens van de uitvoering: naam en identificatie van het script, de trigger ("manual", "cron", "api" of "catchup"), het nummer van de uitvoering, en wie hem heeft aangeroepen.

Regels voor het resultaat:

• Het moet serialiseerbaar in JSON zijn: woordenboeken, lijsten, teksten, getallen, booleaanse waarden of None. Objecten van andere types laten de uitvoering mislukken.
• De maximale omvang van het resultaat is 32 MB.
• Een niet-opgevangen uitzondering laat de uitvoering eindigen in Fout, met de volledige traceback in de logs.

Alles wat u afdrukt — met print of met de log(...) van de SDK — verschijnt regel voor regel in de logs van de uitvoering. Om bij gegevens, HTTP-aanroepen, geheimen, meldingen en meer te komen, gebruikt u de SDK api_manager, die beschreven wordt op de pagina De SDK van de scripts.

#De editor

De editor beslaat het tabblad van het script over de volle breedte. In de balk boven de code ziet u het pad van het actieve bestand (main.py in het begin) met een statuspunt ernaast — Opgeslagen of Niet-opgeslagen wijzigingen. Er is geen knop om de code op te slaan: de wijzigingen slaan zichzelf op, ongeveer een seconde nadat u stopt met typen.

Rechts in de balk staan de knoppen:

Knop	Wat die doet
Nu uitvoeren (▶)	Slaat alles op en opent het dialoogvenster voor handmatige uitvoering.
Uitvoeringen	Opent de geschiedenis van de uitvoeringen van het script.
Prompt voor LLM	Opent een kant-en-klare tekst om te kopiëren, met het volledige contract van de SDK, om het script aan een AI-assistent te vragen — zie De SDK van de scripts.
Editor maximaliseren	De editor beslaat voortaan het hele scherm; Esc of Editor minimaliseren brengen u terug naar normaal.

Terwijl u Python typt, doet de editor aan automatisch aanvullen: hij stelt de modules en functies van de SDK voor (db, http, log, …), uw eigen bestanden en de pip-pakketten die in de omgeving van het script zijn geïnstalleerd, hij toont de signatuur van de parameters terwijl u een aanroep invult, en documentatie wanneer u boven een naam zweeft.

#Met de hand uitvoeren

1. Klik op Nu uitvoeren (▶). Wat nog niet is opgeslagen, wordt eerst opgeslagen.
2. Stel in het dialoogvenster de argumenten van deze uitvoering in (optioneel): klik op Argument toevoegen en vul Naam (bijv. clienteId) en Waarde in. De waarden komen als tekst bij het script aan, in input["args"].
3. Klik op Uitvoeren.

Het paneel Resultaat van de uitvoering, onder de editor, toont meteen:

• de status — Succes of Fout — en de duur in milliseconden;
• de door main teruggegeven waarde, opgemaakt als JSON;
• de Logs, met elke regel die door log(...) of print is geschreven.

Als de uitvoering mislukt, verschijnt de foutmelding op de plaats van het resultaat, en de volledige traceback blijft in de logs staan.

#De geschiedenis van de uitvoeringen

Klik op Uitvoeringen in de balk van de editor. Het venster somt alle uitvoeringen van het script op, met filters op status, oorsprong, duur en datum:

Kolom	Inhoud
Begin	Datum en tijdstip waarop de uitvoering is begonnen.
Oorsprong	Handmatig, Cron, API of Inhaalslag (uitvoering ingehaald van een planning die niet is gedraaid).
Status	Zie de tabel hieronder.
Duur	In milliseconden.

De mogelijke statussen:

Status	Betekent
Succes	main heeft zonder fout een resultaat teruggegeven.
Fout	Een niet-opgevangen uitzondering, of een niet-serialiseerbaar resultaat.
Wordt uitgevoerd	De uitvoering is nog niet geëindigd.
Time-out	Hij heeft de Tijdslimiet van het script overschreden en is beëindigd.
Afgebroken	Het proces is voor het einde beëindigd (bijv. bij het stoppen van de server).
Overgeslagen (overlap)	Een planning is afgegaan terwijl de vorige uitvoering nog bezig was — deze heeft niet gedraaid.

Klik op Details in een regel om die uit te klappen: u ziet de Argumenten waarmee hij heeft gedraaid, het teruggegeven Resultaat, de Fout (als die er was) en de volledige Logs.

#Actief of concept

In de kop van het paneel van het script staat een schakelaar Actief. Een script waarvan de schakelaar uit staat, blijft in Concept:

• het draait niet volgens planning — de geplande tijdstippen worden vastgelegd als Overgeslagen, met de notitie "Het script staat in concept";
• het kan wel met de hand in de editor worden uitgevoerd, zodat u het naar hartenlust kunt testen.

Zo ontwikkelt u rustig: schrijven, testen met Nu uitvoeren, en pas Actief aanzetten wanneer het script klaar is om zelfstandig te draaien.

#Instellingen van het script

Open de Instellingen van het script (in het actiemenu van het script in de boom, of via de kop van het paneel) om te wijzigen:

Veld	Opmerkingen
Naam	De naam waarmee planningen en API's ernaar verwijzen.
Versie	Wordt getoond waar dit script als afhankelijkheid van een ander wordt gebruikt (app/script@versie).
Beschrijving	Vrije tekst.
Tijdslimiet	Dezelfde opties als bij het aanmaken, van 30 seconden tot 10 minuten.

De runtime verschijnt niet om te bewerken — die wordt bij het aanmaken vastgelegd.

#Veelgestelde vragen

Waarom verschijnt de uitvoering als Time-out? Het script heeft langer geduurd dan de ingestelde Tijdslimiet. Verhoog de limiet in de Instellingen van het script (maximum: 10 minuten) of verdeel het werk — verwerk bijvoorbeeld kleinere batches per uitvoering.

Ik heb in de editor getypt en meteen uitgevoerd — heeft de oude versie gedraaid? Nee. Nu uitvoeren slaat eerst alles op wat nog niet is opgeslagen; de uitvoering gebruikt altijd wat op het scherm staat.

Het resultaat komt goed terug, maar de argumenten komen "verkeerd" aan? De argumenten komen altijd als tekst aan. Een argument limite = 10 komt aan als "10" — converteer het in de code: int(input["args"].get("limite", 0)).

Kan ik status tussen uitvoeringen bewaren? Elke uitvoering is een geïsoleerd proces — variabelen overleven niet van de ene naar de andere. Om iets te bewaren schrijft u een bestand in de map van het script (zie Afhankelijkheden en bestanden) of slaat u de gegevens op in een datasource.