Een externe service aanroepen vanuit een script

Doel

Laat een serverscript iets buiten het platform aanroepen — een betaling innen, een ander systeem laten weten dat een record is gewijzigd, iemand een e-mail sturen — en zorg dat het adres dat het aanroept een instelling is die een beheerder bepaalt, in plaats van een regel in je script.

De twee functies

Beide zijn beschikbaar in een serverplug-instap en in een aangepaste API.

var answer = callService('par_payment_service', '{"reference":"ORD-1","amount":25}');

var sent = sendEmail('par_mail_service', { to: 'buyer@example.test', subject: 'Your order is paid', body: 'Thank you.' });

De body kan tekst zijn, zoals hierboven, of een object of lijst, die als JSON wordt verstuurd: callService('par_payment_service', { reference: 'ORD-1', amount: 25 }) verstuurt hetzelfde.

callService antwoordt met een object:

Eigenschap	Wat het is
status	De HTTP-status waarmee de service antwoordde
ok	true voor 200–299, zodat het gewone geval één eigenschap is in plaats van rekenwerk
body	Wat hij antwoordde, als tekst
truncated	true als het antwoord te groot was om volledig te lezen

Het eerste argument is een servicenaam, geen adres

Dit is het deel dat mensen verrast, en het is het hele ontwerp.

'par_payment_service' is de logische naam van een omgevingsvariabele. Je declareert die in je oplossing; een beheerder stelt de waarde ervan — het endpoint — in elke omgeving in. Dus:

• je script zegt wat het aanroept, nooit waar;
• Ontwikkeling wijst naar een sandbox en Productie naar de echte provider, zonder dat de oplossing verandert;
• een omgeving die niets heeft geconfigureerd, bereikt niets.

Er is bewust geen functie die een URL aanneemt. Zo'n functie zou elk script in elke tenant een verbinding naar waar dan ook laten openen, en geen enkele hoeveelheid achteraf beoordelen van oplossingen zou dat terugdraaien.

Het instellen

1. Declareer de service. Open in het Beheercentrum Omgevingsvariabelen en maak er een — par_payment_service, type Tekst. Geef haar een beschrijving die zegt waarvoor ze dient; wie haar in Productie instelt, ben misschien niet jij.
2. Voeg haar toe aan je oplossing, zodat ze meereist. De declaratie van een variabele reist mee; de waarde niet, en dat houdt de instellingen van Ontwikkeling uit Productie.
3. Stel de waarde in voor deze omgeving — het endpoint, een absoluut adres met http:// of https://.
4. Schrijf de stap. Roep in je plug-instap of aangepaste API callService aan met die naam.

Aan welke kant van het opslaan je aanroept

Een serverplug-instap draait vóór het record wordt geschreven of erna, en uitgaande aanroepen horen aan verschillende kanten, afhankelijk van wat ze zijn:

Aanroep	Fase	Waarom
Een betaling innen, voorraad reserveren in een ander systeem	PreOperation	Het gebeurt binnen de transactie van het opslaan, dus als het record daarna niet kan worden opgeslagen, blijft er niets achter dat beweert dat er geld is ingehouden
Een bevestiging sturen, een ander systeem op de hoogte brengen	PostOperation	Het record bestaat dan al, dus een mailservice die plat ligt, vertraagt een bericht in plaats van het record ongedaan te maken

Een aanroep vóór het opslaan krijgt tien seconden. Die houdt het opslaan open terwijl hij wacht, en er zit iemand naar een draaiend wieltje te kijken. Heeft de service die je aanroept meer tijd nodig, maak de stap dan Asynchroon — hij draait dan na het opslaan, zelfstandig, en mag zo lang duren als nodig is.

Wat telt als mislukking

Dit onderscheid is het waard om één keer te leren, want het bepaalt hoeveel van je script je moet schrijven:

• Een status die de service zelf koos, is een antwoord. Een 402 van een betaalprovider betekent dat de kaart is geweigerd — een gewone uitkomst waar jij over beslist. Je script krijgt hem in answer.status en gaat door.
• Helemaal geen antwoord is een mislukking, en die stopt de stap vanzelf: geen service met die naam, geen endpoint ingesteld in deze omgeving, een endpoint dat geen webadres is, of de service heeft nooit geantwoord. Aan geen van die dingen kan een script iets doen, en doorgaan zou betekenen dat je doet alsof je met iets hebt geïntegreerd.

De vorm van de meeste stappen is dus:

var answer = callService('par_payment_service', body);
if (answer.ok) {
  setValue('par_payment_reference', answer.body);
} else {
  throwValidationError(`The payment service refused this order (${answer.status}).`);
}

E-mail versturen

sendEmail neemt de naam van de service en een bericht, en post het naar die service. Het bericht is van het platform, zodat een installatie één mailadapter configureert in plaats van één per script dat ooit een bericht verstuurt.

In het bericht	Wat het is
to	Naar wie het gaat. Eén adres, meerdere gescheiden door komma's of puntkomma's, of een lijst
cc	Wie een kopie krijgt, op dezelfde manier. Optioneel
replyTo	Waar een antwoord naartoe gaat, zodat een klant de persoon antwoordt die schreef in plaats van een no-reply-adres. Optioneel
subject	De onderwerpregel
body	Wat erin staat
html	true als de body HTML is. Optioneel; anders platte tekst

sendEmail stopt je script nooit. Het antwoordt { ok, error }. Is de e-mail niet verstuurd — omdat niemand hier een mailservice heeft ingericht, het adres werd geweigerd of de mailservice plat lag — dan is ok false en zegt error waarom, in woorden die zeggen wie het kan oplossen. Zo kan een script de mislukking vastleggen en het later opnieuw proberen; zo markeert Parsware Sales een e-mail als Mislukt. Moet het opslaan in plaats daarvan stoppen, zeg dat dan:

if (!sent.ok) { throwValidationError(sent.error); }

Een script dat eerder is geschreven, gaf vier argumenten door (sendEmail(service, to, subject, body)). Dat heeft de berichtvorm hierboven nodig.

Het platform spreekt geen SMTP. Het post naar wat de omgeving noemt, en dat biedt elke mailprovider; een installatie waarvan de enige route een SMTP-relay is, zet daar een klein HTTP-endpoint voor.

Probeer het

Importeer de voorbeeldoplossing business-rules-outbound-calls. Die heeft een tabel Orders, twee services die als omgevingsvariabelen zijn gedeclareerd zonder dat er iets is ingesteld, en twee stappen — een die vóór het opslaan de betaling int en een die daarna de bevestiging mailt. De README loopt erdoorheen: de services naar een endpoint laten wijzen dat 200 antwoordt, daarna naar een dat 402 antwoordt, en zien hoe het opslaan wordt geweigerd zonder dat er iets wordt opgeslagen.

Zie ook

• Een bestand naar opslag schrijven vanuit een script — het andere wat een script buiten de database kan bereiken.
• Een aangepaste API publiceren — het contract waarmee een extern systeem jou aanroept.