Baggrund

Ideen med DRG er at hjælpe med at udbrede forståelse af hvad NSP komponenter kan og hvordan disse kan kaldes. DRG skal være tilgængelig for ikke-tekniske personer, der ønsker mere viden om NSP, men også brugbar af interessenter, der ønsker en hurtig måde at kalde og inspicere kald til NSP.

Målsætninger

Her følger nogle mål, som ønskes at blive opfyldt af løsningen:

  • Det skal være muligt at udvide funktionaliteten af DRG uden at nye releases af komponenten skal rulles ud.
  • DRG funktionaliteten skal være tilgængelig for alle (med passende akkreditiver) vha. en gængs Web browser.
  • DRG skal kunne komme til at kalde alle NSP komponenter. I første version begrænses dette dog til ID-kort baserede services.

Derudover findes der nogle sekundære mål:

  • Hjælpe NSP anvendere og NSP leverandører med at integrere med øvrige NSP komponenter.
  • Hjælpe med til aftestning af komponenter. Her tænkes specielt på let adgang til STS signerede ID-kort til brug i testrequests.

Løsningen

Med udgangspunkt i at DRG’s funktionalitet skal kunne udvides over tid, er løsningen baseret på et repository eller en folder i et filsystem med en række navngivne ressourcer. Dette kaldes for DRG data. Det vil være en fordel hvis DRG data blev underlagt revisionskontrol og at brugen heraf er specificeret. Se mere herom senere.

Requests

Den basale idé med DRG er at udforme requests mod en NSP komponent. I DRG data vil der være måder at gøre dette mod flere NSP komponenter. For hver udviklet request, vil der findes en måde at konstruere et signeret ID-kort vha. en rolle, samt en måde at stykke et request sammen med forskellige information, der normalt vil indgå i tilhørende requests.

DRG data giver ligeledes mulighed for at formidle ekstra information til brugeren, når brugeren udfylder requestet.

Brugeren skal vælge et request, (underneden et request-id), et miljø samt en passende rolle. Dernæst skal brugeren udfylde informationer som skal fyldes i en defineret skabelon. Herunder vil brugeren kunne få hjælpetekst præsenteret. Efter udfyldelsen kan brugeren vælge at få requestet præsenteret, dvs. det fulde request, som valgte NSP komponent vil modtage, eller brugere kan vælge blot at få udført requestet, hvorefter svaret præsenteres for brugeren.

Ressourcer

I det følgende vil de forskellige typer af ressourcer i DRG data blive beskrevet. Format og semantik vil dog blive mere detaljeret beskrevet senere.

  • /headers indeholder små .xml skabelonen, som kan tilføjes til requests som header (i modsætning til .request.xml, som tilføjer body).
  • environments.json indeholder hvilke NSP miljøer, som brugere kan vælge for at lave requests mod.
  • <request-id>.metadata.json indeholder meta information om det navngivne request.
  • <request-id>.request.json indeholder information om hvilke informationer et request kan udfyldes med.
  • <request-id>.request.xml indeholder et skabelon for det navngivne request.
  • <role-id>.role.json indeholder en rolle beskrivelse.

Udover disse type af ressourcer vil der ligeledes være certifikater at finde. Disse burde placeres i en underfolder navngivet certificates.

Metadata

Denne type filer indeholder et JSON object, som skal består af følgende felter:

  • id - den identifikation, som også findes i filnavnet.
  • name - navnet der præsenteres i klienten.
  • path - den sti NSP komponenten kaldes på.
  • soap-action - den SOAP Action header, requests udfyldes med.
  • authentication - et JSON array af tags til hjælp af valg af rolle. Her kunne f.eks. stå ["VOCES"], hvormed kun rolle, som også har VOCES benyttes.
  • parents - et JSON array. Bruges til præsentation i klient for at konstruere et træ af grupperede requests.
  • environments - hvilke testmiljøer, som servicen kan kaldes på
  • headers - navn på .xml filer i data/headers, som tilføjes til requestet som header (eksempelvis HSUID Header)
  • audience - intended audience til den givne service, som bliver brugt i tilfælde, hvor rollen er POCES

Et eksempel på en .metadata.json-fil:

foo.bar.metadata.json 
{
    "id": "foo.bar",
    "name": "FooBar",
    "path": "foo-bar-ws/service/change-weather",
    "soap-action": "vendVinden",
    "authentication": ["MOCES", "POCES"],
    "parents": ["FBS (Foo Bar Service)", "Vejr-skifter", "Use cases", "Vind-vender"],
	"environments": ["test1 cNSP"]
  	"headers": ["hsuidHeader"],
	"audience": "https://audience.nspop.dk/foobar"
  }


Request JSON

Dette er en beskrivelse af hvilke informationer, der kommer med i requestet, og indeholder desuden ekstra information til anvendere i forbindelse med udfyldelse.

Overordnet indeholder filer af denne type et JSON object, hvori der kun findes en indgang, fields, som er et JSON array, med forskellige typer af objekter, men her har de alle til fælles at have et id og en type. Førstnævnte er navnet på den information/variable, som bruges til videre udfyldelse af selve requestet.

Her en beskrivelse af de forskellige typer:

  • enum, så indeholder objektet ligeledes et JSON-array med mulige værdier for udfyldning.
  • predicate, så indeholder objektet også en test indgang, som indeholder en Javascript-funktion (repræsenteret som en streng) til at afgøre om et yderligere antal indgang, nested skal udfyldes. Denne nested indgang kan indeholde samme type objekter som fields; dermed kan udfyldningen forgrenes. Funktionen tager et objekt, som parameter, som indeholder de aktuelle variable. Eksempel herpå er: (env) => env.method === 'nord'.
  • string betyder at brugeren kan indtaste en vilkårlig streng.
  • number betyder at brugeren kan indtaste et vilkårlig tal.
  • text indeholder en tekst, som vises til brugeren, hvis den er aktiv, hvilket vil sige er direkte i fields eller er aktiv i en forgrening.

Derudover kan objekter af typen, string og number, indeholde et JSON-array, validators, som er validator-funktioner (igen repræsenteret som en streng) til validering af indhold af feltet. En validator-funktion får en given værdi for et felt, og kan enten returnere null, hvis der validering er OK, eller et Javascript-objekt med et fejlnavn og en fejlbesked på formen { fooBar: { errorMessage: 'Indholdet skal være FooBar' } } . Eksempel herpå: (value) => { return 'FooBar' === value ? null : { fooBar: { errorMessage: 'Indholdet skal være FooBar' } }; }

Der findes prædefinerede validatorer, som kan bruges, i stedet for selv at angive en validator-funktion. De benyttes ved at angive deres navn i validators-arrayet. I øjeblikket findes der dog kun én:

  1. cprValidator - den validerer at et felt indeholder præcis 10 cifre.

Rækkefølgen i fields (og forgreninger) er vigtig, da dette anvendes til gradvis udfyldning af værdier i klienten.


Et eksempel på en .request.json-fil - med text, string, number, enum, predicate (med test og sub-predicates), og validators (både den prædefinerede cprValidator og en custom validator):

foo.bar.request.json 
{
  "fields": [
    {
      "id": "helpText1",
      "type": "text",
      "notes": "Her kan du vælge hvilken vej vinden vender for et givent personnummer"
    },
    {
      "id": "cprNumber",
      "type": "string",
      "notes": "Personnummer",
      "validators": ["cprValidator"]
    },
    {
      "id": "windSpeed",
      "type": "number",
      "notes": "Vindstyrke"
    },
    {
      "id": "direction",
      "type": "enum",
      "notes": "Vælg retning",
      "values": ["nord", "syd", "øst", "vest"]
    },
	{
	  "id": "feelsLike",
	  "type": "string",
	  "notes": "Hvordan føles vinden?",
	  "optional": "true"
	},
    {
      "id": "predicate1",
      "type": "predicate",
      "test": "(env) => { return env.direction=='nord'; }",
      "nested": [
        {
          "id": "helpText2",
          "type": "text",
          "notes": "Nordenvinden kan være ekstra kold med chill-faktor"
        },
        {
          "id": "chillFactor",
          "type": "number",
          "notes": "Chill-faktor",
          "validators": [
            "(value) => { return value >= 0 ? null : { chillFactor: { errorMessage: 'Chill-faktoren kan ikke være negativ' } }; }"
          ]
        },
        {
          "id": "subPredicate1",
          "type": "predicate",
          "test": "(env) => { return env.chillFactor > 10; }",
          "nested": [
            {
              "id": "helpText3",
              "type": "text",
              "notes": "Vær forsigtig med værdier over 10 - det kan være ulideligt koldt."
            }
          ]
        }
      ]
    }
  ]
}


Request XML

Ud fra en request JSON fremgår en række felter navngivet med deres id. Ikke alle er nødvendigvis aktive pga. forgrening. En fil af request xml type indeholder selv den SOAP body, der sendes til NSP komponenten. Den endelig body udfyldes dog med førnævnte variable ved hjælpe af Apache Velocity. Der er flere mekanismer i dette template sprog, der hjælper til at håndterer f.eks. forgrening.

Roller

Filer af denne type indehoder et JSON objekt med følgende indgange:

  • id - den identifikation, som også er indehold i filnavnet.
  • type - her angives enten "DGWS" eller "IDWS".
  • display-name - det som rollen benævnes i klienten.
  • credential-vault - et JSON objekt, der indeholder:
    • path - stien til den keystore, som skal bruges til udfyldes af ID kort.
    • password - kodeordet til det keystore, der peges på.
  • care-provider - et JSON objekt, der indeholder:
    • cvr - det CVR som skal benyttes i ID-kortet (burde matche med anvendte certifikat)
    • org - indeholder navnet på den anvendte organisation.
  • user-info - benyttes kun ved MOCES, men indeholde et JSON objekt med: cpr, first-name, last-name, email, title, role, authentication-code som direkte bruges i ID-kortet.
  • tags - som tidligere nævnt bruges disse til at matche med requests.
  • No labels