Guide til OpenDIMS scripting

Et script er et lille udtryk, der laver en værdi om undervejs. Du bruger det tre steder: i feltopsætningen på en integration, på en scriptknap, og i et beregnet felt. Sproget er det samme alle tre steder - kun de værdier, du kan nå, er forskellige.

Syntaks

Syntaksen ligner SQL, fordi funktionerne er skrevet med MySQL som forbillede.

• Funktionsnavne skrives altid med STORE BOGSTAVER.
• Du henter en værdi med $, som i PHP.
• Tekst sættes i anførselstegn: "fast tekst". Skriver du tekst uden funktion og uden $, bruges teksten, som den står.
• Funktioner kan ligge inde i hinanden, så dybt du har brug for.

Et eksempel, der sætter brugerens navn og e-mail sammen:

CONCAT(" ", @USER.NAME, CONCAT("", "<", @USER.EMAIL, ">"))

Det første argument til CONCAT er skilletegnet mellem de øvrige. Vil du sætte noget sammen uden mellemrum, giver du tom tekst: CONCAT("", …).

Værdier du kan hente

$VALUE

Værdien fra kilden på netop den linje, scriptet står på. I en integration er det den indkommende værdi, før den gemmes.

$Feltnavn

En anden værdi på samme emne - eller en anden linje i samme integration.

Navnet skrives uden mellemrum og uden æ, ø og å. Alt andet end bogstaver, tal, understreg og punktum fjernes fra navnet, før scriptet slår det op. Hedder feltet Mit eget varenummer, skriver du:

$Mitegetvarenummer

Og hedder feltet Vægt (BC), skriver du $VgtBC - æ og parenteser findes ikke i variabelnavne.

Vær opmærksom: skriver du $Mit eget varenummer med mellemrum, får du ingen fejl. Scriptet kan ikke læse det som en variabel, så teksten bliver i stedet gemt, som den står - du får altså $Mit eget varenummer ned i feltet. Ser du den slags i dine data, er det her, det kommer fra.

@USER

Den bruger, der kører scriptet. Findes overalt, men er mest brugt på knapper.

• @USER.NAME - navn
• @USER.EMAIL - e-mail
• @USER.PHONE - telefonnummer
• @USER.TITLE - titel
• @USER.LAST_LOGIN_AT - sidste login
• @USER.CREATED_AT - oprettet
• @USER.UPDATED_AT - sidst ændret

Betingelser

IF, AND og OR er de eneste funktioner, der ikke beregner alle deres argumenter - og det er hele pointen med dem. En betingelse skal kunne beskytte det, der står efter den.

• IF(betingelse, hvis sand, hvis falsk) - kun den gren, der vælges, beregnes. IF(EQUAL($Status, "Betalt"), $TransaktionNummer, "betales ved overførsel") er derfor sikker på en ordre, der endnu ikke har en transaktion: grenen, der nævner den, bliver aldrig beregnet.
• AND(a, b, …) - stopper ved det første argument, der er falsk.
• OR(a, b, …) - stopper ved det første argument, der er sandt.

En ukendt værdi i den gren, der bliver beregnet, fejler stadig. Dovenskaben beskytter den gren, der ikke vælges - den laver ikke en manglende værdi om til tavshed.

Funktioner

Sammenligning og logik

• EQUAL(a, b) - sand hvis a er lig med b
• NOT(a) - vender sandt og falsk om
• GREATER(a, b), GREATER_EQUAL(a, b) - større end, større end eller lig med
• LESS(a, b), LESS_EQUAL(a, b) - mindre end, mindre end eller lig med
• EMPTY(a) - sand hvis værdien er tom. Bemærk at både 0 og tom tekst regnes som tomt
• BOOLVAL(a) - sand ved 1, true, yes, active, open, sand, ja, aktiv, åben
• CONTAINS(tekst, søgeord) - sand hvis søgeordet findes i teksten, uanset store og små bogstaver. Er teksten en liste - et flervalgsfelt eller resultatet af JOIN - er den sand, hvis bare ét element passer
• STARTS_WITH(tekst, begyndelse), ENDS_WITH(tekst, slutning)

Tekst

• CONCAT(skilletegn, a, b, …) - sætter sammen med skilletegnet imellem. En liste som argument foldes ud, så CONCAT("|", $tags) virker
• REPLACE(tekst, søg, erstat)
• SPLIT(skilletegn, tekst) - deler tekst op i en liste
• JOIN(a, b, …) - samler til en liste, fjerner tomme værdier og dubletter
• SUBSTRING_INDEX(tekst, skilletegn, antal) - som i MySQL. Et positivt antal giver alt til venstre for det antal skilletegn, et negativt antal alt til højre for det antal skilletegn talt fra slutningen. SUBSTRING_INDEX("www.mysql.com", ".", 2) giver www.mysql, og SUBSTRING_INDEX("Ulrich von Dahl", " ", -1) giver Dahl. Er der færre skilletegn end antallet, får du hele teksten; 0 giver tom tekst
• LOCATE(søgeord, tekst, start) - som i MySQL: pladsen for det første match, talt fra 1, eller 0 hvis det ikke findes. Store og små bogstaver er ens. start er valgfri og tælles også fra 1
• SUBSTRING(tekst, start, længde) - som i MySQL: stykket fra pladsen start, talt fra 1. Et negativt start tæller fra slutningen, og udelades længde, får du resten af teksten. SUBSTRING("Sakila", -3) giver ila. Alt efter første mellemrum: SUBSTRING($VALUE, ADDITION(LOCATE(" ", $VALUE), 1))
• UPPER(a), LOWER(a), TITLE(a) - store, små, Stort Begyndelsesbogstav
• SNAKE(a), CAMEL(a) - min_tekst og minTekst
• RENDER(a) - gør en værdi sikker at sætte ind i HTML. Bruges når du bygger tekst, der ender på en webshopside: et enkelt & i et leverandørnavn ødelægger ellers opmærkningen omkring det

Tal og datoer

• ADDITION(a, b, …), SUBTRACTION(a, b, …), MULTIPLY(a, b, …)
• DIVIDE(a, b) - giver tom tekst hvis der divideres med 0
• SUM(liste) - lægger alle tal i en liste sammen. ADDITION kan ikke bruges til det: den lægger sine argumenter sammen, så en liste bliver til 1
• ABS(a) - talværdi uden fortegn
• ROUND(værdi, trin) - runder til nærmeste trin
• INTVAL(a) - gør om til helt tal, så "12,7" bliver 12
• NUMBER_FORMAT(tal, decimaler, decimaltegn, tusindtalstegn)
• DATE_FORMAT(dato, format)

Rækker fra en relation

Kun i integrationer. Med dem kan en feltopsætning regne på tværs af de rækker, der hører til emnet - for eksempel linjerne i en stykliste.

• MAP_EACH(rækker, udtryk) - beregner udtrykket én gang pr. række og giver resultaterne som en liste. Rækken er $VALUE, og rækkens egne værdier er variabler undervejs
• GET_FROM(reference, "feltnøgle") - henter ét felt fra det emne, en værdi peger på. Reference er typisk varenummeret. Kender OpenDIMS ikke emnet, kommer der ingen værdi - ikke en fejl

Vægten på en pakke, lagt sammen ud fra styklisten, hvor antallet står på linjen og vægten hører til komponenten:

SUM(MAP_EACH($components, MULTIPLY($BOMLine.quantityPer, $BOMLine.component.BCField_42_NetWeight)))

Og de samme linjer som en tabel i en beskrivelse:

CONCAT("", MAP_EACH($components, CONCAT("", "<tr><td>", $BOMLine.quantityPer, "</td><td>", RENDER($BOMLine.description), "</td></tr>")))

JSON

• JSON_EXTRACT(json, sti) - henter en værdi ud af JSON-tekst med en JSONPath, for eksempel JSON_EXTRACT($VALUE, "$.title")

Pakning

• FILL_AREA(længde, bredde, emnelængde, emnebredde) - hvor mange emner der kan ligge på en flade i ét lag, med blandede retninger
• FILL_VOLUME(længde, bredde, højde, emnelængde, emnebredde, emnehøjde) - det samme stablet i højden

Hvor virker hvad

• Integrationer - alt. Skriver du bare en fast værdi i scriptet, sættes den værdi.
• Scriptknapper - alt undtagen rækker fra en relation. Ud over @USER kan du bruge de feltværdier, du vælger på feltopsætningen.
• Beregnede felter - alt undtagen MAP_EACH. Et beregnet felt regnes om, hver gang en af de værdier, det bygger på, gemmes, og det holder kun øje med værdier på emnet selv.

Henter et script feltværdier, beregnes det ikke, når emnet oprettes, men først når en af de værdier, scriptet bruger, gemmes eller ændres.

Når et script fejler

UNKNOWN VALUE betyder, at scriptet beder om en variabel, der ikke findes. Oftest er navnet stavet med mellemrum eller æøå - se afsnittet om feltnavne ovenfor - eller feltet er ikke med i integrationen.

UNKNOWN METHOD betyder, at funktionsnavnet ikke findes. Tjek at det er skrevet med store bogstaver, og at det står på listen her.

Fejlen skrives i hændelsesloggen sammen med det script, der fejlede, og de værdier, det blev kørt med, så du kan se præcis hvilken række der gik galt.