Een functie uitvoeren

Doel

Iets laten gebeuren zonder dat iemand een record opslaat: een herinnering die elke nacht wordt verstuurd, een partij records die elk uur wordt opgeruimd, een lang werk dat u met de hand start en laat afmaken. En achteraf precies kunnen teruglezen wat elke uitvoering deed.

Waarom dit bestaat

Al het andere dat de scripts van een oplossing doen, begint met iemands opslag: een invoegtoepassingsstap draait binnen een schrijfactie, een aangepaste API wanneer een ander systeem haar aanroept. Maar sommig werk hoort bij geen enkele schrijfactie: het hangt af van een tijdstip, of van een partij die te groot is om op te wachten.

Een functie is een BS Lang-script dat de functieservice zelf uitvoert, in een eigen proces en zo lang als u toestaat. Ze is een onderdeel van uw oplossing, net als een formulier of script: geschreven in Dev en via het oplossingspakket naar Test en Production gebracht.

Voordat u begint

• Een oplossing, met een uitgever.
• De tabellen die uw functie leest en schrijft.
• Roept ze een externe dienst aan of verstuurt ze e-mail: de omgevingsvariabele die die dienst noemt — zie Een externe dienst aanroepen vanuit een script.

Stappen

1. Open uw oplossing, kies Functies in de linkerbalk en daarna Nieuw.
2. Schrijf op het tabblad Script wat de functie doet. Ze kan records en bestanden lezen en schrijven, externe diensten aanroepen en uw oplossingsscripts met import gebruiken — hetzelfde als een invoegtoepassingsstap. Het oog aan het eind van de tabbalk toont alles wat u kunt aanroepen.
3. Geef haar op het tabblad Instellingen een weergavenaam. De logische naam vult zichzelf in.
4. Bepaal wanneer ze draait. Elke functie kan met de hand draaien. Wilt u dat ze ook vanzelf draait, vink dan Draait volgens een planning aan en kies een interval — elke 15 minuten, elke 6 uur, elke dag. Bij een dagelijkse planning kunt u een tijdstip en de tijdzone daarvan vastleggen.
5. Stel de maximale looptijd in — hoe lang een uitvoering mag duren voordat ze wordt gestopt. Standaard 15 minuten, hoogstens een dag.
6. Kies Opslaan. Een script dat niet te parseren is, wordt meteen geweigerd, met de regel waarop het faalt.
7. Kies Nu uitvoeren. Het tabblad Uitvoeringen opent en volgt de uitvoering: In wachtrij, Bezig, en hoe ze afliep. Kies de uitvoering om het log te lezen.

Een log schrijven

Niemand kijkt mee terwijl een functie draait, dus het log is hoe u erachter komt wat ze deed.

var due = queryRecords('par_membership', 'par_reminder_state', 'due');
log('Reminders due: ' + toJson(due.length()));

for (var i: int = 0; i < due.length(); i++) {
  updateRecord('par_membership', due[i].id, { par_reminder_state: 'sent' });
  log(due[i]);
}

• Tekst wordt geschreven zoals hij is, een getal zoals u het zou schrijven en een record of lijst als JSON — log(due[i]) toont dus het hele record zoals de uitvoering het zag.
• Het tabblad Uitvoeringen toont de regels terwijl de uitvoering nog bezig is, enkele seconden later.
• Een uitvoering bewaart hoogstens 5.000 regels; de laatste bewaarde zegt dat het log vol is.
• Logregels bewaren op het tabblad Instellingen zet logging uit. log blijft werken en bewaart niets, dus u hoeft het script nooit aan te passen om het stil te zetten of weer aan te zetten.

Een uitvoering bewust beëindigen

stop('reason') beëindigt de uitvoering daar, als een succes dat zegt waarom:

if (due.length() == 0) {
  stop('Nobody is due a reminder tonight.');
}

Het resultaat van de uitvoering toont die zin. Dat is geen mislukking, en de lijst toont het ook niet zo.

Een functie starten vanuit een script

Een functie heeft geen klok nodig. Een Custom API, een plugin-stap of een andere functie kan er een starten met startFunction, er een invoer aan meegeven en krijgt de id van de uitvoering meteen terug — het werk gebeurt daarna, in de Functions-service. Zo krijgt een verzoek dat een uur werk vraagt in een ogenblik antwoord.

// A Custom API: POST reports  { "period": "2026-10" }
var run = startFunction('par_sales_report', { period: getInput('period') });
setStatus(202);
setOutput('run', run);

// The function
var asked = functionInput();
// … the long work …
setResult({ period: asked.period, total: total });

// A second Custom API: GET reports/runs/{run}
var run = functionRun(getInput('run'));
if (run == null) { setStatus(404); } else { setOutput('status', run.status); setOutput('report', run.result); }

• startFunction(name, input) geeft de id van de uitvoering terug. De invoer — een record, een lijst, een waarde of null — is wat de functie leest met functionInput(). Een uitvoering die door haar planning of door Run now is gestart, heeft geen invoer en leest null.
• setResult(value) is wat de uitvoering teruggeeft. Alleen de laatste waarde wordt bewaard, en alleen als de uitvoering slaagt. Houd haar klein — een samenvatting, of de sleutel van een bestand — want ze wordt gelezen telkens wanneer iemand vraagt hoe de uitvoering ervoor staat.
• functionRun(id) geeft { id, function, status, outcome, result, queuedAt, startedAt, finishedAt } terug, of null als zo’n uitvoering niet bestaat.
• Vanuit een plugin-stap wordt de uitvoering binnen het schrijven gestart: wordt het schrijven geweigerd, dan start de uitvoering nooit.
• Uitvoeringen die een script start, zijn niet aan één tegelijk gebonden. Twee mensen die tegelijk vragen, krijgen twee uitvoeringen. De regel van één tegelijk geldt voor de planning en Run now.
• Op het tabblad Runs staat bij zo’n uitvoering Hoe hij startte: Een script, en als u hem selecteert, ziet u boven het logboek zijn Invoer en Resultaat.
• Bestaat de functie niet of staat ze uit, dan stopt startFunction het script met de reden — de aanroeper krijgt dus nooit te horen dat er werk is begonnen dat niet begonnen is.

Bericht krijgen als ze klaar is

Een aanroeper die niet steeds opnieuw wil vragen, kan bericht krijgen. startFunctionWithCallback is startFunction met één argument meer: de naam van een omgevingsvariabele die het adres bevat dat bericht moet krijgen. Als de uitvoering eindigt — hoe dan ook — wordt de uitkomst daar één keer naartoe gestuurd.

// A Custom API: POST totals
var run = startFunctionWithCallback('par_invoice_totals', null, 'par_totals_done');
setStatus(202);
setOutput('run', run);

Wat er aankomt:

{ "run": "…", "function": "par_invoice_totals", "status": "Succeeded",
  "outcome": null, "result": { "invoices": 3, "total": 165.5 }, "finishedAt": "…" }

• Nooit een URL in het script. Het derde argument noemt een omgevingsvariabele, net als bij callService; een beheerder bepaalt per omgeving waar die naar wijst. Een naam die de oplossing niet declareert, stopt het script voordat er iets begint.
• Eén keer verstuurd, niet herhaald. Op het tabblad Uitvoeringen toont de gekozen uitvoering haar Terugmelding en wat ervan terechtkwam — Delivered (HTTP 200), de status waarmee de dienst antwoordde, of waarom die niet bereikt kon worden. Wie het gemist heeft, kan de uitvoering nog altijd lezen met functionRun.
• De status van de uitvoering hangt er niet van af. Een uitvoering die haar werk heeft gedaan, slaagt ook als de dienst die bericht moest krijgen onbereikbaar is.

Een bestand schrijven

Een functie kan naar objectopslag schrijven met dezelfde aanroepen als een Custom API — putFile, putFileAs, getFile, listFiles en deleteFile —, ook al is er niemand aangemeld terwijl ze draait.

var key = 'orders/' + today() + '.csv';
putFileAs('par-order-exports', key, csv, 'text/csv');
setResult({ bucket: 'par-order-exports', key: key, rows: orders.length() });

• Het bestand komt in de opslag van uw organisatie en telt mee voor haar opslagtegoed. Een schrijfactie die over het tegoed heen zou gaan, laat de uitvoering mislukken.
• In Beheer → Opslag staat als uploader function:<name> — de functie heeft het geschreven, niet wie op Nu uitvoeren drukte.
• Zo geeft een functie meer terug dan een samenvatting: schrijf de gegevens naar een bestand en zet de sleutel van dat bestand in het resultaat.
• Niets verwijdert oude bestanden voor u. Een functie die er elke nacht een schrijft, hoort de bestanden die ze niet meer nodig heeft te verwijderen, zoals het voorbeeld functions-nightly-export-to-storage doet.

Hoe een uitvoering eindigt

Status	Wat er gebeurde
Geslaagd	Het script liep af, of stopte zichzelf met stop(...)
Mislukt	Het script gaf een fout, een schrijfactie werd geweigerd, de maximale looptijd werd overschreden of de dienst stopte tijdens de uitvoering. Het resultaat zegt welke
Geannuleerd	Iemand koos Uitvoering annuleren

Een mislukte uitvoering wordt nooit voor u herhaald. Een functie kan lang draaien, en negenentwintig minuten werk buiten uw medeweten overdoen zou erger zijn dan stoppen. Lees waarom ze mislukte, herstel wat nodig is en kies Nu uitvoeren.

Controleren of het werkte

• De uitvoering is Geslaagd en het log zegt wat u verwachtte.
• Open een record dat de functie wijzigde en bekijk de auditgeschiedenis: de wijziging staat op naam van de functie, niet van een persoon. Een functie draait als het platform, zonder iemand erachter.
• Bij een geplande functie is Volgende uitvoering op het tabblad Instellingen het volgende moment waarop ze vanzelf draait.

Goed om te weten

• Eén uitvoering tegelijk. Zolang er een wacht of bezig is, wordt ‘Nu uitvoeren’ geweigerd en wordt een planning die afloopt overgeslagen tot de volgende keer. Een nachtelijke run die uitliep, start nooit twee keer over dezelfde records.
• ‘Nu uitvoeren’ voert uit wat is opgeslagen en is niet beschikbaar zolang er niet-opgeslagen wijzigingen zijn.
• Uit is uit. Een uitgeschakelde functie draait niet volgens planning en niet met de hand.
• Het script wijzigen verschuift de planning niet; de planning wijzigen wel.
• Uitvoering annuleren stopt een script binnen enkele seconden — ook een lus die geen record aanraakt.
• Elke functie bewaart haar 200 meest recente uitvoeringen.

Problemen oplossen

Symptoom	Waarschijnlijke oorzaak	Oplossing
Nu uitvoeren is grijs	Niet-opgeslagen wijzigingen, of de functie staat uit	Opslaan; inschakelen
Die functie draait al	Er wacht of loopt een uitvoering	Wachten, of haar kiezen en Uitvoering annuleren
Mislukt: Stopped after … minutes	Maximale looptijd overschreden	Maximale looptijd verhogen, of elke uitvoering minder laten doen
Mislukt omdat de dienst stopte tijdens de uitvoering	De dienst werd herstart	Opnieuw uitvoeren
Het log is leeg	Logregels bewaren staat uit, of het script roept nergens log aan	Inschakelen; log(...) toevoegen
De uitvoering is mislukt: There is not enough storage left	Het opslagtegoed van de organisatie is op	Verwijder bestanden die u niet meer nodig hebt, of kies een groter abonnement
De uitvoering is mislukt: Object storage is not configured for the Functions service	De installatie heeft de Functions-service geen opslaginstellingen gegeven	Vraag het uw beheerder

Zie ook

• Een externe dienst aanroepen vanuit een script
• Een oplossingsscript schrijven
• Een aangepaste API publiceren