HTTP Services og Actions

Owned by Blanketmotorens Produktteam
Last updated: Oct 13, 2022
6 min read

Integrationer i blanketterne styres som udgangspunkt via Orbeon Forms' HTTP Services og Actions, som du finder i fanen Advanced i Toolboxen. Hver integration består af en HTTP Service og en Action

HTTP Services

HTTP Services er den ene halvdel af de klassiske integrationer i Orbeon Forms og har ansvaret for at fortælle, hvor data skal hentes fra, samt styre formatet og sikkerheden omkring kaldet.

Foruden informationerne i de to faner beskrevet nedenfor, så er der i vinduet også en Test-knap, hvor du kan se om du kan forbinde til den ønskede service.

Definition

Under fanen Definition finder vi de mest basale oplysninger omkring den service vi gerne vil hente data fra

  • Service Name: Her skal du angive navnet på den service du er i færd med at oprette, et navn som egentligt kun skal bruges når du senere skal oprette den tilhørende action. Prøv som altid at give et meningsfuldt navn, så det er nemt at komme tilbage til senere.

  • Resource URL: Her angives adressen på den service, du ønsker at kalde. Hvis du bruger en af Blanketmotorens udstillede services så vil du i vores dokumentation af dem kunne se, hvad du skal skrive her.

  • Method: Her angives, hvilken type servicekald der skal foretages. Du vil med al sandsynlighed her enten skulle vælge GET eller POST, men det styres af den service du ønsker at kalde og du vil derfor skulle høre ejeren af servicen ad. For Blanketmotorens udstillede services kan du se hvilken metode du skal vælge for de enkelte services.

  • Serialization: Hvis du under Method har valgt enten POST eller PUT, så skal der her angives, hvordan input skal sendes til servicen. Du vil med al sandsynlighed her enten skulle vælge XML eller JSON. Hvis den service du kalder tillader brugen af XML, så er det at foretrække i Orbeon Forms, da systemet generelt er bygget op om XML strukturer

  • URL Parameters: Hvis du under Method har valgt enten GET eller DELETE, så kan de her tilføje én eller flere parametre, der bliver sendt med til servicen som input ved dataopslaget. Du kan samtidigt give dem en default værdi, som du så senere kan overskrive i den tilhørende action

  • Request Body: Hvis du under Method har valgt enten POST eller PUT, så vil du i stedet for URL Parameters skulle angive en request body enten i XML eller JSON afhængigt af, hvad du har valgt under Serialization.

Advanced

Under fanen Advanced finder du lidt yderligere muligheder for at tilpasse dit servicekald

  • HTTP Authentication: Her har du mulighed for at angive, om der skal bruges brugernavn og password for at tilgå servicen og i så fald angive disse værdier

  • SOAP Service: Hvis den service du prøver at kalde er en såkaldt SOAP Service, så vil du højst sandsynligt skulle markere denne tjekboks og i nogle tilfælde også skulle angive en SOAP Action. Dette vil stå i dokumentationen af den service du ønsker at kalde.

Actions

Hvor HTTP Services definerede, hvor og hvordan data skulle hentes, så har den tilhørende Action ansvaret for at styre, hvornår der skal laves et servicekald, samt hvad der skal bruges som input og hvad der skal gøres med det data, der kommer tilbage

General settings

Under fanen General settings er det primære formål at definere, hvornår der skal laves et servicekald, samt hvilken service der skal kaldes

  • Action Name: Ligesom for den tilhørende HTTP Service, så skal du give din action et navn, så du kan finde den igen i Toolboxen.

  • Condition: Her kan du vælge mellem Run in all modes og Run in “new” mode only, hvilket afgør i hvilke situationer du ønsker, at der laves et dataopslag. Hvis dataopslaget kun skal laves første gang brugeren tilgår blanketten, så bør du vælge New, mens du kan bruge Run in all modes, hvis det er fint, at opslaget kan laves senere uden at ændre på noget.
    BEMÆRK: Hvis du bruger New, så vil integrationen ikke virke i testvinduet i Form Builderen, men først når du publicere til test og tilgår blanketten der.

  • Run action when: Her kan du styre, hvad der skal udløse servicekaldet og det kan opdeles i to separate kategorier:

    • the control: Vælger du at servicekaldet skal følge et enkelt felt, så skal du angive, hvilket felt der skal lyttes på, samt hvad der skal udløse servicekaldet. Ofte vil det være en ændring i værdien der er interessant, men ved præudfyldte felter kan kombinationen af appears og changes it value være den rette løsning.
      Den sidste valgmulighed med is activated er primært rettet mod brugen af knapper i blanketter

    • the form loads: Du kan også vælge, at servicekaldet skal laves som en del af indlæsningen af blanketten for brugeren, således at data er klar så snart brugeren ser blanketten. Her vil du næsten altid skulle vælge after the controls are ready, men man kan nogle gange bruge after the data is ready til at få den rette timing på forskellige opslag

  • Service to call: Til sidst skal du angive, hvilken service der skal kaldes, hvor du kan vælge mellem dine opsatte HTTP Services som ikke allerede er tilknyttet en action

Service Request Actions

Hvis dit servicekald skal bruge data fra blanketten som input, så kan du styre dette under fanen Service Request Actions. Det kunne eksempelvis være et opslag på CVR-data for et indtastet CVR-nummer

Her kan du tilføje et til flere felter, hvis værdi skal indsættes i de input der sendes til servicen. Disse skal matche enten de URL Parameters eller den Request Body du har opsat i den tilhørende HTTP Service

  • Ved brug af URL Parameters, så angives de som på billedet ovenfor med parameterens navn med foranstillet /*/

  • Ved brug af Request Body, så mappes felterne til de respektive steder i XML’en via XPath udtryk.

Hvis du anvender en SOAP Service vil der ofte optræde de såkaldte namespaces i XML-strukturen, hvor knuderne hedder ting som a:felt. Dette håndteres i Blanketmotoren ved at bruge *: foran feltets navn, som illustreret nedenfor

Service Response Actions

Den sidste fane ved opsætning af en Action er måske den vigtigste og handler om, hvad der skal gøres med det data, der kommer tilbage fra servicekaldet.

 

Her er der tre mulige scenarier beskrevet nedenfor i rækkefølge af, hvilket du oftest ved bruge med den hyppigste først

  • Set Control Value: Denne model gør det muligt at udfylde værdien af et felt baseret på data i svaret fra servicekaldet og opsættes fuldstændig på samme måde som Service Request Actions.

  • Set Control Choices: Hvis din webservice returnerer data i listeform, så kan du bruge dette til at populere en static dropdown til senere brug i blanketten. Opsætningen af dette fungerer i høj grad som for dynamiske dropdowns og der henvises derfor til dokumentationen der.

  • Save to Dataset: Den sidste og sjældnest anvendte model er muligheden for at tage hele svaret og gemme det som en del af blankettens XML til senere brug. Det kan eksempelvis være, hvis data skal bruges flere steder senere og det fra start ikke er sikkert præcis, hvor mange steder det skal bruges.