1. Introduktion #

API adgang til KMD Nexus er et tilkøbsprodukt, som kræver noget teknisk opsætning. Yderligere har KMD i hvert fald tidligere, påkrævet at man skal have undervisning i at bruge APIet, før man kan få adgangen. Endvidere er det næsten umuligt at teste i sit Nexus-testmiljø, da denne ikke er retvisende for, hvordan tingene ser ud i live version. Så ønsker man at bruge API hertil, er det påkrævet at kunne teste i live-miljøet. Hertil kan man eventuelt lave et par fiktive patienter, man kan teste med. Vejledningen herunder beskæftiger sig ikke med den del, og tager udgangspunkt i, at alle disse ting allerede er på plads. Samtidigt er dette lavet fra en RPA-udviklers synspunkt. Der er derfor ikke meget hjælp at hente, i forhold til at få lavet visninger, og eventuelle andre ting som kræver en Nexus administrator adgang.

Vær opmærksom på, at nogle Powershell script udtræk nedenfor, har fået ændret id’er af hensyn til GDPR. Yderligere kan powershell scripts udtræk mangle nogle values, typisk under _links sektionen. Dette er gjort for at øge læsbarheden, der vil dog typisk være mange flere end vist på udtrækkene. 

Da vores scripts er lavet så dynamiske som muligt, burde andre kommuner kunne bruge disse også. Disse kan udleveres ved efterspørgsel, vi fraskriver os dog ansvaret for brug af disse, og eventuelt vedligehold der kan være behov for. Derfor vil det være vigtigt, at sætte sig ind i hvordan de virker, for selv at kunne bruge og vedligeholde dem. Kontakt eventuelt henrik.nielsen@rksk.dk for yderligere information.

1.1 Hvordan er Nexus skruet sammen #

For at få en forståelse for hvordan Nexus fungere, kan man tænke på Nexus som en stor relationsdatabase. Data er organiseret i mange forskellige tabeller, hvor der kan være mange relationer imellem disse. Meget af det der kan ses i UIet, er visninger med specifikt filtreret data, som kan laves af en Nexus administrator. Sagt på en anden måde, er der ikke nødvendigvis noget der er fast. Har man arbejdet med dataudtræk (sql eksempelvis), og Power BI eller lignende programmer til at vise data, er det meget lig sådan en arbejdsgang. Modsat en SQL-database eksempelvis, så er alt funktionalitet på Nexus bygget med links og API kald (POST, PUT, GET, DELETE). Sidstnævnte bliver gennemgået i afsnit 2. RPA-udvikling API.

Et konkret eksempel er vist herunder, hvor vi har fremkaldt et objekt med APIet, som i dette tilfælde er et forløb. Overordnet har denne en type, og det kan være ting såsom dokumenter, breve, organisationer, forløb m.m.. Samtidigt har vi et ID der referer specifikt til patientens forløb, og et til en skabelon, af mangel på bedre ord, som denne er lavet ud fra. Det vil sige en patient kan godt have mange af det samme forløb, hvor programPathwayId vil være 111555 hos alle men hvor patientPathwayId er unikt for hver af disse. Yderligere kan disse have underløb, breve, dokumenter, og andet tilknyttet, som man kan få at se i en visning.

En visning kan se således ud, hvor hver enkelt widget (kasse med indhold), indeholder filtreret data som en Nexus administrator har lavet. Disse kan vise eller frasortere data alt efter behov, og er en nem måde at trække data på for robotten. Dette gennemgås yderligere i afsnit 2.2. Eksempel på arbejdsgang.

Hvis man som et andet eksempel vil uploade et dokument, kan denne proces startes direkte fra patient-objektet, widget eller eventuelt fra et forløb. Læg mærke til at prototype (skabelon) og placement skifter, alt efter hvor uploaden starter fra. Hvis vi eksempelvis starter uploaden fra et forløb, vil dokumentet automatisk få et tilhørsforhold til denne. Hvis vi derimod gør det på patienten, vil dokumentet overordnet bare høre til denne. Man kan også fra de forskellige steder starte uploaden, og vælge hvor dokumentet skal gemmes. Det er dog mindre kompliceret, at navigere ind på hvor dokumentet skal ligge, og kalde linket herfra.

$patient._links.documentPrototype.href – /api/document-microservice/rksk/documents/prototype?patientId=24325&placement=PATIENT

$widget.creatableObjects._links.documentPrototype.href – /api/document-microservice/rksk/documents/prototype/289671?patientId=24325&placement=PATHWAY

$pathway._links.documentPrototype.href – /api/document-microservice/rksk/documents/prototype/300367?patientId=24325&placement=PATHWAY

Yderligere kan man inspicere netværkstrafik, for at finde ud af hvor noget data stammer fra på siden. Højreklik på siden, og vælg Undersøg.

I det nye vindue under Network, kan man slå Fetch/XHR til, så man kun ser API kald. Refresh herefter siden, og kig kaldene igennem, for at matche data sammen. Finder man hvad man søger, kan man yderligere holde musen over objektet, da linket kan give en idé til hvor data ligger. I dette tilfælde ligger det under patient-objektet, og et link der hedder noget lignende medicationCardInformation.

Hvorimod linket ikke hedder nøjagtigt det samme, kan vi finde et som hedder medicationCardPatientInformation under patient._links. Denne trækker det samme data som der er i visningen.

2. RPA-udvikling API #

2.1 Introduktion #

Når der skal udvikles Powershell Script til at bruge Nexus APIet, er det absolut nemmest at bruge Powershell ISE. Heri kan vi skrive, og teste samtidigt. At navigere igennem API’et, er meget lig at klikke rundt på hjemmesiden. I stedet for at klikke på knapper/links, så benytter vi API kald. Alle objekter i Nexus har næsten altid en ._links, hvor man kan se hvor man kan videre hen, hvis det man søger ikke ligger på objektet allerede.

For at kunne lave scripts med APIet, skal man bruge en authentication token, som kan hentes direkte fra browseren efter login til Nexus. Denne skal opdateres hver 60 minutter for forsat at være gyldig. I tilfælde af scripts der har længe eksekveringstider, skal der tænkes en autorefresh metode ind disse. Den er er en lidt mere kompliceret at sætte sig ind i, vores genbrugelige script tager dog højde for dennes brug.

Nedenstående er et eksempel på, hvor man kan hente de organisationer, som patienten er tilknyttet ud fra. Fra patient-objektet selv, er der allerede et link, hvortil man kan hente alle tilmeldte organisationer ud som en liste. Vi kan åbne dette med en RestMethod GET som vist i gul markering, og navigering igennem Nexus APIet vil typisk se således ud. Var dette ikke tilfælde, kunne det tænkes at disse kunne findes på en visning, denne kunne eventuelt være filtreret specifikt til processens behov (eksempelvis kun at relevante organisationer vises, og andre frasorteres). Fra patient-objektet kan vi finde et Dashboard, også kendt som et Overblik. Først er vi nødt til at hente listen af alle mulige Overblik vi kan komme ind på ud, og herefter søge efter den specifikke vi leder efter. Yderligere for at være sikker på, at objektet er i det rigtige stadie, henter vi dens self-reference ud. På den måde er $Dashboard-variablen ikke længere bare et søgeresultat, med det indhold som denne nu viser, men reelt det pågældende dashboard og dets datasæt. Der kan være mange veje ind, til det samme data med andre ord.

2.2 Eksempel på arbejdsgang – Upload en formular #

Eksemplet her tager udgangspunkt i at udfylde og uploade en formular. På en visning til robotten, når vi denne Widget som har den funktionalitet.

Vi skal derfor åbne Overblik, finde det Dashboard som har den widget vi mangler, og herefter hive den ud. Der er snydt nedenfor, da vi har genbrugelige scripts der dynamisk, kan hjælpe os med at finde disse.

Som eksempel ser scriptet ud til at finde en widget således ud. Den er bygget med de parametre som skal bruges, hvis man ønsker at søge efter en widget. Yderligere er der bygget lidt fejlhåndtering ind, der kan give et fingerpeg, om hvad en eventuel fejl skyldes.

Når vi har fundet den widget vi leder efter, er næste trin at finde ud af hvor linket til prototypen ligger. En prototype er en skabelon, i dette tilfælde til en formular, som ikke er udfyldt. Denne skal først trækkes ud, hvorefter vi kan ændre i den, og så sende den ind efterfølgende. Disse ligger typisk under en createableObjects, og som vist i udtrækket, kan vi allerede se der ligger en forms derunder.

I createableObjects kan vi se at der ligger en forms, som har titlen på  hvad vi leder efter. Herefter kan vi hoppe videre ned i forms og  _links, for at finde det fulde link til prototypen.

Herfra kan vi navigere helt ned til slutstien, hvor linket til prototypen ligger.

Nu kan vi hente prototypen fra tidligere i scriptet, og gemme den i en variabel.

Selve prototypen ser således ud, vi nedarver igen en masse data om patienten. Selve formularen med felterne gemmer sig under Items.

Hvis vi hiver vores items ud, er det relativt nemt at finde ud af hvad der er hvad. Hver enkelt har en label og id der er unikt på formularen, foruden et value felt vi selv kan udfylde med en string. Vær opmærksom på ved radiobutton delen, at vi også bliver fodret med possibleValues, hvor det er hele objektet som skal indsættes i value feltet.

Det kan være en fordel, at have et manuelt udfyldt eksempel, så man kan se hvordan tingene ser ud efterfølgende. Her kan vi sammenligne mellem prototypen, og en allerede udfyldt formular. Dette kan gøres ved, at hente allerede udfyldt formular ud fra den samme widget.

Alternativt kan man også hente en direkte fra Nexus, enten ved oprettelse / efter denne. Højreklik på siden, og vælg

I det nye vindue under Network, kan man slå Fetch/XHR til, så man kun ser API kald. Herefter kan man oprette/opdatere en formular, og efterfølgende finde den oversigten. Under preview kan man se indholdet, som blev sendt ind til Nexus. Ved sammenligning kan vi se, at items er alt der kommer efter Sagsåbning (VUM 2.0) afsnittet, hvor alle disse er samlet i et stort array. Samtidigt kan vi se at Placering ligger under pathwayAssociation.placement. Yderligere kan vi se at Tags ligger under tags, og at disse er gemt som et array.

Endvidere kan vi under Headers se hvilken metode der blev brugt til at lave kaldet, samt hvad indholdstypen er. Begge disse skal vi bruge, når vi selv vil sende vores prototype ind.

Billedet her burde være en POST, såfremt vi sendte en hel ny formular ind, her har vi dog kun opdateret, og derfor står der PUT.

Uden at gå for meget i dybden, så overskriver vi de values i vores prototype, som er påkrævet med egne inputs. Nogle inputs skal være objekter, objekter i et array, string eller andre mere specifikke data. Markeret i gul er datoer eksempelvis i yyyy-MM-dd format når de sendes ind, selvom de bliver vist i Nexus GUI’en som dd-MM-yyyy format. Vi kan også sende PAD variabler med eksempelvis, som markeret under datoen. Dette kan man se på den allerede udfyldte, med en .gettype() bagved de enkelte dele. Til sidst kan vi udfylde POST linket, med det data vi fandt tidligere i Headers under inspiceringen.

Eksempel her med en gettype() på tags, som viser at den modtager objekter i et array.

En nem måde at teste på, om det man sender ind er i korrekt format, er at bruge den udfyldte formular. Man overskriver data i denne, og sender en PUT med opdateringslinket ind, med dele af data. Lykkedes dette, burde det også virke med linket til POST.

3. Opslagsværk #

3.1 Hvor findes hvad – visuel reference på patient #

3.2 Patient objekt links – hvad ligger hvor? #

Yderligere ser vi heller ikke på prototyper, altså selve oprettelseslink til diverse. Tabellen hvis kun, hvad linket eller dets underlink viser af data.