Den gode kodeliste
Kodeværdier anvendes på tværs af webservices som en delt nøgle med en entydig betydning. Kodeværdier inddeles i typer som udstilles via kodelister, en for hver type. Kodelisterne anvendes af serviceaftagerne, og beskriver det lovlige udfaldsrum for de pågældende kodetyper.
Kodelister kan være simple kode/værdi lister eller mere avancerede strukturer, som f.eks. hierarkier eller netværksstrukturer.
Koder samles i kodelister ud fra det forretningsområde og forretningsbegreb koden tilhører. Det er ikke altid simpelt at konstruere gode kodelister. Det bør tilstræbes at kodelisten kun indeholder en dimension i forhold til det forretningsbegreb, der forsøges beskrevet. En dimension kan f.eks. være kursustype en anden kan være myndighed.
Model for kodeliste
Følgende minimumsmodel anvendes for kodeværdier:
- Kode - Kodefelt indeholdende talværdi. For hver kodelistetype er kodeværdierne unikke, ikke to koder er ens
- Start- og slutdato - Alle kodeværdier har en start- og slutdato, hvor kodelisten kan bruges fra og med startdato og til slutdato (Lukket - åben interval).
- Startdato sættes altid til den dato, hvorfra kodelisteværdien skal kunne benyttes både i udviklingsøjemed og til test - dette vil typisk være før en lovmæssig ikrafttrædelsesdato og/eller en releasedato for kodelisteværdien.
- Slutdato sættes til en fremtidig dato, sålænge kodelisteværdien er gyldig og dermed stadig vil kunne oprettes. Når en kodelisteværdi ikke længere er gyldig og dermed ikke skal kunne oprettes mere, skal denne sættes til datoen for, hvornår kodelisten værdien ophører – dette gerne værende sig releasedatoen.
- Navn - Alle kodeværdier har et Navn, der er en kort tekstuel repræsentation af koden.
- (Optionel) Beskrivelse - Alle kodeværdier har en Beskrivelse, der er en lidt mere uddybende beskrivelse af koden, f.eks. med reference til lovgrundlag.
Både Navn og Beskrivelse skrives i et neutralt sprog og vil ikke indeholde brugergrænseflade eller applikationsspecifikke værdier. Målet er, at teksterne kan anvendes på tværs af sagsbehandler- og borgerrettede løsninger, og det anbefales aftagerne at aftage teksterne direkte, og kun supplere specifikke koder med egne beskrivelser, hvor det på kodelisten angivne Navn/Beskrivelse ikke kan anvendes.
En guide på hvor man opretter en kodeliste fra en teknisk synpunkt finder du på /wiki/spaces/CITY/pages/38666305.
Vedligehold af kodelister
Følgenden regler overholdes:
- Kodelisterne indeholder altid alle kodeværdier, både historiske, aktuelle og kommende
- Koder der udgår, markeres som udgået ved at sætte slutdato til den dato hvor koden er udgået.
- Betydningen af en kode må ikke ændres, ved ændret anvendelse markeres koden som udgået og en ny kode oprettes
- Koder slettes ikke, i stedet markeres koden som udgået
- Koder kan tilføjes, med aktuel eller fremtidig startdato
- Alle ændringer varsles
Anvendelse af kodelisteværdier
Aftagere DFDG webservices (og dermed kodelister) skal afhente kodelisterne dagligt og indlæse i eget system. Denne caching af listerne skal anvendes for ikke at belaste DFDG unødigt.
- Kun koder hvor forretningsdatoen (typisk d.d.) er inden for kodens start- og slutdato kan anvendes ved registrering
- Ved opdatering af historiske data kan udgåede koder fortsat anvendes
- Koder der er udgået kan fortsat optræde i historiske registreringer
Sikkerhed
Kodelisterne indeholder kun offentlige data. Alle må tilgå kodelisterne. Det anbefales at kodelister udstilles offentligt.
Webservices med kodelister
De fleste webservices anvender følgende struktur (OBS:enkelte kodeliste fraviger fra denne struktur):
| Element | Beskrivelse |
|---|---|
| Identifier | Identifier elementet, der angiver den id, der skal benyttes til servicen for dette kode liste element. Type: int |
| Name | Et sigende navn for kodeværdien. Min. Length: 1 Max. Length: 100 Type: string |
| Description | En kort beskrivelse af kodes betydning Min. Length: 1 Max. Length: 500 Type: string |
| StartDate | Dato som kodeværdien er gyldig fra Format: xsd:dateTime |
| EndDate | Dato for hvornår kodeværdien udløber Format:xsd:dateTime |
Se kodeliste webservices her: CodeListsService
Brug af kodelister i og på tværs forretningsdomæner
En kodeliste er som udgangspunkt kun ejet af et forretningsdomæne (se Webservice-struktur (TO-BE på moderniserende DFDG webservice)), hvorfra kodelisten udstilles til aftagere via forretningsdomænets webservice til afhentning af kodelister. Eksempelvis vil kodelisten til kontaktgrupper været ejet af forretningsdomænet DFDG Visitering og status.
Kodelister kan dog benyttes på tværs af forretningsdomæner, således at webservices i ét forretningsdomæne kan benytte og udstille kodeværdier fra kodelister, som er ejet af ét andet forretningsdomæne. Et tænkt eksempel kunne være, at en webservice i forretningsdomænet DFDG Borgerrettet indsats har behov for at benytte og/eller udstille kodeværdien for en kontaktgruppe.
Den nuværende webservicestruktur følger dog ikke overstående mønster, hvilket betyder, at de fleste kodelister i dag er udstillet fra DFDG på webservicen CodeListService. Fremadrettet er målet at følge ovenstående mønster, hvilket betyder, at forretningsdomæner begynder at udstille de kodelister, som de hver især ejer. Mønsteret benyttes også i forhold til de webservices, der udstilles af henholdsvis Jobnet og Vitas og som hver især har deres egen websevice indeholdende deres kodelister.
Den tekniske beskrivelse af, hvorledes kodelister benyttes på tværs af forretningsdomæner og systemsiloer (DFDG, Jobnet og Vitas) er beskrevet på DFDG Foundation, kodelister.