BESTILLING AV SKJEMA V2

Sist oppdatert 07.11.2020

Innholdsfortegnelse

Bestilling klient-side

Bestilling server-side

Feilsituasjoner

Mottak av status for bestillingen

“På vegne av”-funksjonalitet og personvern

API-kallet for bestilling av skjema er i v2 endret slik at man får respons med en gang, uten å vente på at bestillingen har gått igjennom til Helsenorge/Digipost. Når bestillingen er fullført (pasienten har fått beskjed og skjemaet ligger klart til utfylling) vil ePROM gjøre et kall mot Bestillersystemet med status for bestillingen. Bestillersystemet må implementere en service som mottar dette kallet.

Bestilling av skjema kan gjøres både fra server-side og fra klient-side. Ved kall fra server-side kan man benytte seg av et API utviklet av Hemit og distribuert som NuGet pakke for å forenkle oppkoblingen. Alle URL’ene som er oppgitt i dette dokumentet går mot integrasjonsmiljøet for ePROM

NB! I verson v2 av API’et skal ApiKey sendes som en Authorization parameter som del av HTTP header: headers: {"Authorization": "Basic " + apiKey}

Bestilling klient-side

Eksempelkode (javascript)

function placeFormOrderV2() {
    var url = 'https://proms2.hemit.org/PromsWebApi/api/v2/formorder'; // Demo server
    var apiKey = ""; // The ApiKey for your system
    var formId = "1bc5f9f0-2607-49eb-94f0-6af955bbd79a"; // RAND-12
    var nationalId = "26073941651"; // the national ID of the patient (Norsk fødselsnummer or D-nummer)
    var expiryDate = new Date(new Date().getTime() + (86400000 * 7)); // add 7 days
    var reminderDate = new Date(new Date().getTime() + (86400000 * 6)); // add 6 days
    var metadata = JSON.stringify({
        age: 76
    });
    var dontStoreCompletedFormInPha = false;
    var distributionRule = "Basic";
    var mustBeSigned = false;
    var signingText = null;
    var physicalAddress = null;
    var testMode = false;
    var onBehalfOfNationalId = null;

    $.ajax({
        url: url,
        type: "POST",
        contentType: "application/json;charset=utf-8",
        headers: {
            "Authorization": "Basic " + apiKey
        },
        data: JSON.stringify({
            formId,
            nationalId,
            expiryDate,
            reminderDate,
            metadata,
            dontStoreCompletedFormInPha,
            distributionRule,
            mustBeSigned,
            signingText,
            physicalAddress,
            testMode,
            onBehalfOfNationalId
        }),
        success: function(data) {
            alert("formOrderId: " + data.id + "\nsingleUseCode: " + data.singleUseCode + "\nloginUrl: " + data.loginUrl + "\npreferred notificationChannel: " + data.notificationChannel);
        },
        error: function() {
            alert("Error!");
        }
    });
}

URL for Web API kall

[https://proms2.hemit.org/PromsWebApi/api/v2/formorder]

Parametere - Inn

{
    fullName: "Test Testesen",
    addressLine1: "Testeveien 1",
    postalCode: "1234",
    postalPlace: "Testestad"
}

Parametere – Ut

I tillegg til alle inn-parametre:

Metode

POST

Bestilling server-side

API

Tilgjenglig som NuGet pakke

NuGet repository: https://hemit.pkgs.visualstudio.com/a7f87e1f-3406-4ac2-a2d4-18e789c37706/_packaging/Hemit_public_packages%40Local/nuget/v3/index.json

Navn: Hemit.Proms.Integration
Version: 3.0

Eksempelkode (C#)

[HttpPost]
public async Task<JsonResult> OrderPromsFormV2Async(Guid formId) {
    var form = _context.FormService.GetForm(formId);
    var patient = _context.PatientInRegistryService.GetByFormGuid(formId);

    var promsFormId = _formTypeToPromsFormIdMapping[(FormType) form.FormTypeId];

    var result = await Api.CreateFormOrderV2Async(
        ConfigurationManager.AppSettings["PromsApiBaseUrl"],
        ConfigurationManager.AppSettings["PromsApiKey"],
        promsFormId,
        patient.DecryptedPID,
        DateTime.Now.AddDays(7),
        DateTime.Now.AddDays(6),
        GetMetadata(promsFormId, form, patient) false,
        DistributionRule.AllowUnsecure,
        false,
        null,
        null,
        false,
        null);

    if (result.HasErrors) {
        Response.StatusCode = result.ErrorStatusCode.Value;
        Response.Write(result.ErrorJson);
        return null;
    }

    _promsFormOrderService.Add(result.Data.Id, form.Id, form.ReshId);

    return Json(new {
        loginUrl = result.Data.LoginUrl,
        singleUseCode = result.Data.SingleUseCode,
        notificationChannel = result.Data.NotificationChannel.ToString()
    });
}

Parametere - Inn

promsApiBaseUrl skal være https://proms2.hemit.org/PromsWebApi

Parametere – Ut

Feilsituasjoner

Hvis responsen resulterer i “id”: “00000000-0000-0000-0000-000000000000” er det ikke generert noe bestilling. Dette skjer hvis fødselsnummeret ikke eksisterer. Ellers kan følgende feilsituasjoner oppstå:

Mottak av status for bestillingen

API-kallet for bestilling av skjema er i v2 endret slik at man får respons med en gang, uten å vente på at bestillingen har gått igjennom til Helsenorge/Digipost. Når bestillingen er fullført (pasienten har fått beskjed og skjemaet ligger klart til utfylling) vil ePROM gjøre et kall mot Bestillersystemet med status for bestillingen. Bestillersystemet må implementere en service som mottar dette kallet.

URL for Web API kall

ApiBaseUrl for web API registreres i ePROM Selvbetjeningsmodul under Bestillersystem: https://proms2.hemit.org/PromsAdministration/

Web API må være tilgjenglig på URL: https:// <ApiBaseUrl> /api/PromsFormOrder

F.eks: https://mrsdev.helsemn.no/PromsTestregisterServices/api/PromsFormOrder/

Parametere - Inn

Parametere - Ut

For parameter inn og ut kan NuGet pakken Hemit.Proms.Integration benyttes. Bruk da Hemit.Proms.Integration.PromsFormOrderRequest for parameter inn og Hemit.Proms.Integration.PromsFormOrderResponse for parameter ut

Metode

PUT

Eksempel request fra Proms (JSON)

{
    "apiKey" : "",
    "formOrderId" : "184738d0-3c39-e611-9c2a-34e6d72e03c7",
    "notificationChannel" : "Helsenorge",
    "formOrderStatus" : "Ordered"
}

“På vegne av”-funksjonalitet og personvern

For at mottaker av bestillingen skal kunne vite hvem skjemaet besvares på vegne av vises som default en informasjonstekst, både i notifikasjonen som sendes og i selve skjemaet, som viser fullt navn til den som skjemaet besvares på vegne av. Det er derfor svært viktig å sikre at selve bestillingen går til rett fødselsnummer slik at sensitive opplysninger ikke havner på avveie. Dette er bestillersystemet sitt ansvar å sikre, ePROM gjør ingen validering av relasjon mellom fødselsnummer til mottaker og den skjemaet besvares på vegne av.

Det er mulig å endre informasjonsteksten om “på vegne av” slik at den ikke angir den som skjemaet besvares på vegne av. Dette gjøres ved å overstyre default “På vegne av info” i PROMs selvbetjeningsmodul -> Skjemainformasjon. Eksempel på slik anonym tekst kan være: “Skjemaet skal fylles ut sammen med pasienten.”. Det er da viktig å tenke på at mottaker ikke nødvendigvis kan forstå nøyaktig hvem skjemaet faktisk gjelder.