Kort presentasjon av volven webservice

 

Merk: Volven webservice skal utfases.

Helsedirektoratet tilbyr kodeverkene på nytt API. Ta kontakt på kodehjelp@helsedir.no for mer informasjon.

Webgrensesnitt for bruk av volven webservice finner en på: https://volven.no/tool

Mer utfyllende brukerdokumentasjon finner en på: https://volven.no/toolws/Brukerdokumentasjon - Webservices og webklient for kodeverk og kodeverifisering_v1.1.pdf

 

Dersom noen ønsker å benytte seg av webservicene direkte kan enkelt gjøre dette. Dette gjøres via en URI.

Oppbyggingen til en slik URI kan være:

Ved bruke av en parameter: https://volven.no/toolws/index.asmx/funksjon?parameter=verdi

Ved bruk av to parameter: https://volven.no/toolws/index.asmx/funksjon?parameter=verdi&parameter2=verdi2

 

 

Systemets funksjoner

Systemet tilbyr totalt et sett med 24 funksjoner. Flere av disse er underfunksjoner som behandler data til hovedfunksjonene. Det er kun de 8 hovedfunksjonene som er eksponert utad, og som vil bli beskrevet her.

 

Faste parametre oppgis med ”X” (Eksempelvis vil et firesifret kodeverk oppgis som XXXX)

Variable parametere oppgis med ”Y” (Eksempelvis vil en kodeverdi som kan ha variabel lengde oppgis med Y)

 

 

Telling av verdier

Navn

wsCountLegalValues

Beskrivelse

Teller antall koder i oppgitt kodeverk

URI

https://volven.no/toolws/index.asmx/wsCountValues?strKveKvid=XXXX

Parametre

Kodeverk i firesifret form

Datatype som returneres

Integer

Forventet lengde på svar

1-3 tegn

Merknad

Om en feil oppstår eller kodeverket ikke finnes/har noen koder returneres ’0’

 

Betegnelse på kodeverk

Navn

wsKveBeteg

Beskrivelse

Gir navnet til oppgitt kodeverk

URI

https://volven.no/toolws/index.asmx/wsKveBeteg?strKveKvid=XXXX

Parametre

Kodeverk i firesifret form

Datatype som returneres

String

Forventet lengde på svar

1-100 tegn. Forbehold om unntak bør tas

Merknad

Om kodeverket ikke finnes vil ’0’ returneres.

 

Merknad på kodeverk

Navn

wsKveMerknad

Beskrivelse

Gir eventuell merknad på oppgitt kodeverk

URI

https://volven.no/toolws/index.asmx/wsKveMerknad?strKveKvid=XXXX

Parametre

Kodeverk i firesifret form

Datatype som returneres

String

Forventet lengde på svar

0-1000 tegn. Svært lange stringer kan forekomme da det kan stå lange forklaringer i enkelte tilfeller.

Merknad

 

Utlisting av verdier (forenklet utlisting)

Navn

wsLegalValuesXML

Beskrivelse

Lister ut gyldige verdier for oppgitt kodeverk i XML-struktur

URI

https://volven.no/toolws/index.asmx/wsLegalValuesXML?strKveKvid=XXXX

Parametre

Kodeverk i firesifret form

Datatype som returneres

String i XML-format

Forventet lengde på svar

80-50000 tegn. Svært lange stringer kan forekomme ut fra hvor mange koder som finnes i kodeverket.

Merknad

Utlisting av dummy-kodeverket 1000 gir denne stringen:

<kodeverksutlisting>

<kodeverk>1000</kodeverk>

<kode>1</kode>

</kodeverksutlisting>

 

Utlisting av verdier (XML i SimpleType format)

Navn

wsSimpleTypeSchema

Beskrivelse

Lister ut gyldige verdier for oppgitt kodeverk i XML-struktur

URI

https://volven.no/toolws/index.asmx/wsSimpleTypeSchema?strKveKode=XXXX

Parametre

Kodeverk i firesifret form

Datatype som returneres

String i XML-format

Forventet lengde på svar

80-50000 tegn. Svært lange stringer kan forekomme ut fra hvor mange koder som finnes i kodeverket.

Merknad

Utlisting av det enkle kodeverket 1101 gir denne stringen:

<?xml version="1.0" encoding="utf-8"?>

<!--Automatisk generert utlisting av kodeverk fra Volven-->

<!--Utviklet av KITH AS-->

<simpleType name="ja_nei">

<restriction base="string">

<enumeration value="1"/>

<enumeration value="2"/>

</restriction>

</simpleType>

 

Utlisting av verdier (XML i Annotation format)

Navn

wsAppInfoSchema

Beskrivelse

Lister ut gyldige verdier for oppgitt kodeverk i XML-struktur

URI

https://volven.no/toolws/index.asmx/wsAppInfoSchema?strKveKode=XXXX

Parametre

Kodeverk i firesifret form

Datatype som returneres

String i XML-format

Forventet lengde på svar

80-50000 tegn. Svært lange stringer kan forekomme ut fra hvor mange koder som finnes i kodeverket.

Merknad

Utlisting av det enkle kodeverket 1101 gir denne stringen:

<?xml version="1.0" encoding="utf-8"?>

<!--Automatisk generert utlisting av kodeverk fra Volven-->

<!--Utviklet av KITH AS-->

<annotation>

<appinfo>

<codingScheme name="1101 Ja, nei"/>

<codingScheme OID="1101"/>

<codingScheme comment="Dette kodeverket inneholder koder for å angi svar på Ja og Nei."/>

<simpleType name="ja_nei"/>

<code value="1" text="Ja" comment="Ja" sorting_order="1"/>

<code value="2" text="Nei" comment="Nei" sorting_order="2"/>

</appinfo>

</annotation>

 

 

Validering av kodeverdi opp mot kodeverk (for applikasjoner)

Navn

wsValidateXML

Beskrivelse

Sjekker om oppgitt kodeverdi finnes i oppgitt kodeverk. Gir tilbakemelding om gyldige kodeverdier hvis kodeverdien ikke finnes og kodeverket er gyldig.

URI

https://volven.no/toolws/index.asmx/wsValidateXML?strKveKvid=XXXX&strKveKode=Y

Parametre

Kodeverk i firesifret form

Kodeverdi i variabel form

Datatype som returneres

String i XML-format

Forventet lengde på svar

80-50000 tegn. Svært lange stringer kan forekomme ut fra hvor mange og hvor lange koder som finnes i kodeverket.

Merknad

Validering av kode 1 mot dummy-kodeverk 1000 gir denne stringen:

<validering>

<kodeverk>1000</kodeverk>

<kode>1</kode>

<test>OK</test>

</validering>

 

Validering av kodeverdi opp mot kodeverk (for XSL/XML-dokumenter)

Navn

wsValidate

Beskrivelse

Sjekker om oppgitt kodeverdi finnes i oppgitt kodeverk. Gir tilbakemelding om gyldige kodeverdier hvis kodeverdien ikke finnes og kodeverket er gyldig.

URI

https://volven.no/toolws/index.asmx/wsValidate?strKveKvid=XXXX&strKveKode=Y

Parametre

Kodeverk i firesifret form

Kodeverdi i variabel form

Datatype som returneres

String i XML-format

Forventet lengde på svar

80-30000 tegn. Svært lange stringer kan forekomme ut fra hvor mange og hvor lange koder som finnes i kodeverket.

Forklaring for bruk av funksjonen i XSL-ark

Funksjonen tar kodeverdi og kodeverk (firesifret ID) som parameter og sjekker om koden ligger i kodeverket. Den sjekker også om kodeverket eksisterer og om kodeverket oppgis med rett syntaks. Hvis kodeverket eksisterer og koden finnes i kodeverket returneres en string til XSLT-dokumentet som gir brukeren beskjed om at koden er gyldig. Ellers vil brukeren få en feilmelding basert på hva feilen er. Slike feil vil typisk være:

  • Verdi for kode og/eller kodeverk er ikke oppgitt
  • Kodeverket finnes ikke
  • Kodeverket er oppgitt med feil parameter (navn i stedet for ID, for lang/kort ID etc.)
  • Koden finnes ikke i kodeverket

Hvis kodeverket har færre enn 70 koder vil funksjonen liste ut gyldige koder for kodeverket. Dette vil presenteres for brukeren i XSLT/XML-dokumentet.

Svar fra funksjonen gis i en string med ”span-tags” for setting av farge på tekst (svart (tekst), rød (feilmelding) og blå (informasjon)). XSLT-arket må settes opp slik at denne strengen ikke parses, men presenteres som den er.

Følgende verdier må settes:

  • NAVN-PÅ-VARIABEL
  • KODEVERK (se kommentar over kodeverk for tips)
  • KODE (det samme gjelder her)
  • VERDI i utlistingen

 

Validering av kode opp mot kodeverk:

Deklarer en variabel for hver test:

<xsl:variable name="NAVN-PÅ-VARIABEL">

<xsl:text>https://volven.no/toolws/index.asmx/wsValidate?strKveKvid=</xsl:text>

<!-- Skriv inn kodeverket under i form av <xsl:value-of select=”@S”/> eller i ren tekst-->

<xsl:text>KODEVERK</xsl:text>

<xsl:text>&#38;strKveKode=</xsl:text>

<!-- Skriv inn koden under i form av <xsl:value-of select=”@V”/> eller i ren tekst-->

<xsl:value-of select="KODE"/>

</xsl:variable>

 

Der hvor resultatet skal vises settes denne:

<li>VERDI/@V <xsl:value-of disable-output-escaping="yes" select="document($teststring)"/></li>

 

Validering av gyldig kodeverk:

Deklarer en variabel for hver test:

<xsl:variable name=" NAVN-PÅ-VARIABEL ">

<xsl:text>http:// trubadur.kith.no /toolws/index.asmx/wsValidateKverk?strKveKvid=</xsl:text>

<!-- Angi navnet på @S-verdi -->

<xsl:value-of select="@S"/>

</xsl:variable>

 

Der hvor resultatet skal vises settes denne:

<li>VERDI/@S <xsl:value-of disable-output-escaping="yes" select="document($validerKveKvid)"/></li>