G: Web Service-oppslag fra InfoPath

Dette vedlegget inneholder en beskrivelse av hvordan man kan gjøre web service-oppslag fra et InfoPath-skjema.

På denne siden:

Web service-oppslag vil være i kjernen i hvordan registeroppslag fungerer. Dette vil fungere på den måten at skjemaet vil kontakte registeret med predefinerte parametere og deretter få et svar som man kan behandle i skjema. Denne veiledningen vil derfor beskrive en generell fremgangsmåte for hvordan gjøre et web service-oppslag i InfoPath-skjema. Eksempeldataene benyttet i fremgangsmåten tilhører Hent arkivreferanse. P.t. er det ikke andre skjemaspesifikke tjenester tilgjengelig.

Hvordan kalle en WebService fra et InfoPath skjema

Legg til en datatilkobling ved å tab’en som heter Data i InfoPath. Velg deretter Datatilkoblinger og deretter Legg til…

Man må så velge å opprette en ny tilkobling for å motta data, og dette via en webtjeneste.

Adressen som angis for webtjenesten vil kunne variere iht hvilket oppslag som skal gjøres, for eksempel vil adressen for å hente arkivreferanse være
https://infopathservices.altinn.no:87/ServiceEngine/ReporteeElementListInfoPath.svc?WSDL

Når denne adressen er angitt, vil InfoPath forsøke å kontakte tjensten for å hente en liste over operasjoner. Antall operasjoner og navn vil variere med tjenesten. Velg deretter operasjonen du ønsker å benytte.

Husk å fjern avkryssning for om data skal hentes når skjema åpnes hvis data ikke skal hentes før man trykker på en knapp i skjemaet.

Akkurat samme måte benyttes for å koble innsynstjenester mot operasjoner i mappere.

Adressen for å koble seg mot en gitt mapper vil være:

http://mapperservices.altinn.no:87/ServiceEngine/Mappers/<tjenesteeierkode>/X.svc?WSDL

Der <tjenesteeierkode> er tjenesteeierkode (SKD/NAV/etc) og X styres av tjenesteeier selv.

Nå er datastrukturen fra oppslaget tilgjengelig som en sekundær datakilde og kan derfor benyttes i skjema. Det er verdt å merke seg at for de fleste spesifikke Altinn registeroppslagene vil man måtte autentisere seg, og at enhetstest i InfoPath derfor vil være vanskelig. Se neste kapittel for kode som må legges inn for spesifikke oppslag.

Resultatet fra oppslaget kan vises i skjemaet på mange måter. Et eksempel er en repeterende tabell som populeres på bakgrunn av klikk på knappen Hent arkivreferanser.

For å angi registeroppslaget skal utføres eller den eksterne tjensten skal kalles ved trykk på knappen, må det lages en regel på knappen som skal brukes til å kalle Web servicen. Dette gjøres ved å høyreklikke på knappen og velge Egenskaper for knapp… og deretter klikke på Regler… og velge Legg til… Man må nå angi et navn på regelen. Dette navnet kan være selvvalgt. Velg Legg til handling… og velg Spørring ved hjelp av datatilkobling i nedtrekkslisten for Handling. Nå må den sekundære tilkoblingen velges.

Nå vil oppslaget utføres ved klikk på knappen.

Som nevnt tidligere vil enkelte mapper/registeroppslag kreve ekstra informasjon fra skjemaet for å kunne autentisere seg, samt vite hvilke brukerspesifikke data som skal hentes ut.

Neste kapittel vil vise dette for Altinn spesifikke oppslag.

Sjekkpunkter for InfoPath skjemaer for innsynstjenester

Forutsetninger for data hentes når skjema åpnes

Verdiene for alle sekundære datakilder som benyttes for Web/Utskrift/Signatur visninger, må kopieres til deres tilsvarende motparter i skjemaets hoveddatakilden. Dette må og gjøres for egendefinerte felter som benyttes som presentasjonsfelt. Alternativt kan verdiene fra felter i sekundære data kilder overføres til felter i skjemaet som allerede ligger i hoveddatakilden.

Forutsetninger for at data hentes på forespørsel ved bruk av knapper

Disse må og følge forutsetnignene beskrevet ovenfor. Det et ønskelig at data hentes når knappen blir trykket på. Knappene som benyttes ha følgende instillinger:

Handling settes til “Regler og egendefinert kode”:

Etter at “Handling” er satt, må du skrive inn koden som er beskrevet nedenfor:

Vi må legge til en linje i koden for at knappen skal kommunisere med hovedsiden. Følgende kode må da legges til i formcode.cs:

C# kode for registeroppslag

Legg inn C# kode i Loading eventen til skjema. Koden skal hente ut portal parametre som skal benyttes i kallet til web servicen. Dette er data som hentes ut fra FormState under skjemautfylling i portalen.

Eksemplet under viser hvordan dette skal kodes, og legg merke til at det enkelte skjemaspesifikke verdier som må settes, bl.a. ekstern tjenestekode og ekstern utgavekode.

public void FormEvents_Loading(object sender, LoadingEventArgs e)
{
    string opensso = FormState["OpenSSOID"] as string;
    string userid = FormState["UserID"] as string;
    string reporteeElementID = FormState["ReporteeElementID"] as string;
    string reporteeID = FormState["ReporteeID"] as string;
    string language = FormState["Language"] as string;

    XPathNavigator secDS = this.DataSources["GetArchivedFormTaskList"].CreateNavigator();
    XPathNavigator node = secDS.SelectSingleNode( "/dfs:myFields/dfs:queryFields/tns:GetArchivedFormTaskList/tns:userID", NamespaceManager);

    if (node != null && userid != null)
    {
        node.SetValue(userid);
    }
    node = secDS.SelectSingleNode( "/dfs:myFields/dfs:queryFields/tns:GetArchivedFormTaskList/tns:reporteeID", NamespaceManager);

    if (node != null && reporteeID != null)
    {
        node.SetValue(reporteeID);
    }
    node = secDS.SelectSingleNode( "/dfs:myFields/dfs:queryFields/tns:GetArchivedFormTaskList/tns:serviceCode", NamespaceManager);

    if (node != null)
    {
        node.SetValue("132323"); //Legg inn serviceCode for det aktuelle skjemaet
    }
    node = secDS.SelectSingleNode( "/dfs:myFields/dfs:queryFields/tns:GetArchivedFormTaskList/tns:altinnIServiceCode", NamespaceManager);

    if (node != null)
    {
        node.SetValue("0"); //Legg inn altinnIServiceCode (OR form nummer) for det aktuelle skjemaet, 0 hvis ikke altinn1 skjema
    }
    node = secDS.SelectSingleNode( "/dfs:myFields/dfs:queryFields/tns:GetArchivedFormTaskList/tns:languageID", NamespaceManager);

    if (node != null && language != null)
    {
        node.SetValue(language);
    }
}

Dette er et kodeeksempel som er spesifikt for GetArchivedFormTaskList, for andre web service kall så vil navn på sekundær datakilde og Xpath uttrykk endres. For kall til andre (ikke Altinn) tjenester vil det ikke være nødvendig å hente ut parametre fra FormState.

Bruk av AltinnMapperContext

AltinnMapperContext er en kontekst XML som du kan bruke i InfoPath skjema og i mapper og som blant annet gir deg tilgang til UserID, Username, Firstname, ReporteeNumber, ServiceOwnerCode etc. I figuren nedenfor ser du alle elementene vi kan hente ut fra AltinnMapperContext

Du kan få tilgang til alle parametrene fra AltinnMapperContext direkte i skjema ved å bruke InfoPath regler i motsetning til ved bruk av FormState varibler der man må bruke C# kode for å hente ut opplysninger om innlogget bruker og avgiver.

Mappere som utvikles og deployes til SBL kan rent teknisk kalles av alle InfoPath-skjema i løsningen, også på tvers av tjenesteiere. Dette kan være en sikkerhetsrisiko. Ved å benytte seg av AltinnMapperContext i mapper kan man forsikre seg om at bare de som har authentisert seg og valgt riktig avgiver skal få gjort kall mot gitte eksterne ressurser gjennom mapperen.

For å bruke AltinnMapperContext i InfoPath skjema må du legge til fila AltinnMapperContext.xml som en sekundær datakilde. AltinnMapperContext ligger under TULShare her: \\alt-tul-db-c02\tulshare\InfoPath\Etater

For å legge til AltinnMapperContext som en sekundær datakilde i InfoPath skjema kan du gjøre følgende:

1. Åpne InfoPath skjema og gå inn på fanen Data
2. Gå inn på «Fra andre kilder» og velg «Fra XML fil»
3. Bla deg frem til AltinnMapperContext.xml på TULShare (se figur under) og trykk på neste
4. Det kommer da opp et vindu med en advarsel om at tilkoblinger til XML filer ikke søttes i en nettverksbane men denne meldingen kan man bare se bort fra og trykke på neste knappen. Dataen vil bli inkludert som en ressursfil i skjema.
5. Tilslutt kommer det opp at vindu der man kan endre navn på datatilkoblingen, vi anbefaler bare at navnet «AltinnMapperContext» bare står
6. Fjern haken for å hente data automatisk når skjemaet åpnes hvis man ikke har et absolutt behov for dette.
7. Åpner man vindu for datatilkoblingene til InfoPath skjema ser man nå at AltinnMapperContext er blitt lagt til som en sekundær datakilde i skjema.

For å teste ut at InfoPath skjema får tak i data fra AltinnMapperContext kan man bruke et felt i hoveddatakilden som skal vise verdien fra et felt i AltinnMapperContext.

Hvis man har behov for å enhetsteste AltinnMapperContext fra InfoPath kan man fylle XML fila med testdata. Det er først når man har migrert skjema til sluttbrukerløsningen at AltinnMapperContext blir fylt med reelle data.

For kommunikasjon med mappere så er det spesielt elementet AltinnMapperContext/ContextXml (en Base64 enkodet og signert representasjon av de samme dataene) som er interessant. Denne skal sendes med i forespørselen til mapperen på lik linje med andre funksjonelle felter.»

Tilgjengelige webtjenester og oppslag

Sluttbrukerløsningen tilbyr et sett med webtjenester og mapper-operasjoner som kan benyttes i InfoPath-skjema. Disse webtjenestene muliggjør oppslag i sluttbrukerløsningens register over personer og enheter, men også andre komponenter som liste over arbeidselementer til den enkelte avgiver.

Under følger en oversikt over webtjenestene. Mapper-implementasjonene utvikles av den enkelte tjenesteeier og listes derfor ikke her.
Se eksempel i C# kode for registeroppslag for hvordan parameterne skal settes.

GetArchivedFormTaskList

Henter en liste over arkiverte skjemasett/avgiverelementer basert på input parameterne.

Begge de valgfri parameterne er teknisk sett valgfrie, men minst en av de to parameterne må angis.

• Endepunkt: ServiceEngine.ReporteeElementList
• Returverdi: ArchivedFormTaskIPBEList

GetFormSetElements

Henter en liste som inneholder alle elementer i det gjeldende skjemasett/avgiverelement. Listen inneholder tre typer elementer: hovedskjema, vedleggskjema og binære vedlegg.

• Endepunkt: ServiceEngine.ReporteeElementList
• Returverdi: FormSetElementBEList

GetOrganizationRegisterData

Henter data om en organisasjon basert på organisasjonsnummer.

• Endepunkt: Register.RegisterER
• Returverdi: OrganizationRegisterBE

GetOrganizationRegisterDataV2

Henter data om en organisasjon basert på organisasjonsnummer. Støtter enhetsnavn på mer en 35 tegn.

• Endepunkt: Register.RegisterER
• Returverdi: OrganizationRegisterBE

GetOrganizationsOfferingRole

Henter liste som inneholder juridiske underenheter av en organisasjon basert på organisasjonsnummer.

• Endepunkt: Register.RegisterER
• Returverdi: OrganizationBEList

ValidateEmailAddress

Validerer epostadresse.

• Endepunkt: ServiceEngine.FormsEngineInfoPathCodeLibrary
• Returverdi: bool (true/false)

ValidateModulus11OrgNumber

Validerer organisasjonsnummeret.

• Endepunkt: ServiceEngine.FormsEngineInfoPathCodeLibrary
• Returverdi: bool (true/false)

ValidateModulus11Fnumber

Validerer fødselsnummeret.

• Endepunkt: ServiceEngine.FormsEngineInfoPathCodeLibrary
• Returverdi: bool (true/false)

ValidateModulus11BankAccount

Validerer kontonummeret.

• Endepunkt: ServiceEngine.FormsEngineInfoPathCodeLibrary
• Returverdi: bool (true/false)

GetPersonRegisterData

Henter data om en person, basert på både fødselsnummer og etternavn. Begge parametere må stemme overens for at data skal returneres om en person. Dette er en mekanisme som sørger for at man bare kan hente data for personer som man vet både fødselsnummer og navn på.

• Endepunkt: Register.RegisterDSF
• Returverdi: PersonRegisterBE

GetPersonRegisterDataV2

Henter data om en person, basert på både fødselsnummer og etternavn. Begge parametere må stemme overens for at data skal returneres om en person. Dette er en mekanisme som sørger for at man bare kan hente data for personer som man vet både fødselsnummer og navn på.

Denne metoden er utgått og vil bli fjernet fra fremtidige leveranser av SBL og må derfor omgående byttes ut med GetPersonRegisterDataV3.

• Endepunkt: Register.RegisterDSF
• Returverdi: PersonRegisterV2BE

GetPersonRegisterDataV3

Henter data om en person, basert på både fødselsnummer og etternavn. Begge parametere må stemme overens for at data skal returneres om en person. Dette er en mekanisme som sørger for at man bare kan hente data for personer som man vet både fødselsnummer og navn på.

• Endepunkt: Register.RegisterDSF
• Returverdi: PersonRegisterV2BE

GetFamily

Henter resten av familien basert på et fødselsnummer etter de prinsipper som gjelder i dagens flyttemelding:

• Dersom et familioverhode(far eller mor) oppgis, hentes andre familioverhoder og deres barn.
• Dersom et barn i en familie oppgis, så hentes bare dette barnet.
• Døde familiemedlem returneres ikke.

• Endepunkt: Register.RegisterDSF
• Returverdi: PersonRegisterBEList

GetCompleteFamily

Henter resten av familien basert på et fødselsnummer uavhengig av brukerens rolle i familien. Døde familiemedlem returneres ikke.

• Endepunkt: Register.RegisterDSF
• Returverdi: PersonRegisterBEList

GetStreetNames

Henter en liste med gatenavn som passer med søkeparameterne.

• Endepunkt: Register.RegisterCommon
• Returverdi: StreetBEList

GetProperty

Henter en liste over eiendommer som passer med søkekriteriene som er angitt som innparametere.

• Endepunkt: Register.RegisterCommon
• Returverdi: PropertyBEList

GetApartmentNumbersForPropertyAddress

Henter en liste over bolignummer som er tilgjengelig på en addresse.

• Endepunkt: Register.RegisterCommon
• Returverdi: ApartmentNumberBEList

GetApartmentNumbersForStreetAddress

Henter en liste over bolignummer som er tilgjengelig på en addresse.

• Endepunkt: Register.RegisterCommon
• Returverdi: ApartmentNumberBEList

Returverdier