Varsling

Hvordan ta i bruk varsling ved instansiering

Dette dokumentet beskriver sending av varsler til instanseier når en instans opprettes. Her er en oversikt over funksjonaliteten og hvordan du kan prøve den ut.

Hva er nytt?

Det er lagt til et nytt felt, notification, i request-bodyen til POST /instances/create og POST /instances (multipart). Dette feltet lar deg spesifisere hvilken kanal varselet skal sendes på, eventuelt egendefinerte tekster, planlagt sendetid og påminnelser.

Slik fungerer det

Felter i notification-objektet

InstantiationNotification

customSms

OBS! Dersom avsendernavnet senderName er (eller i fremtiden blir) beskyttet med tredjepartsprodukter som SenderID, må du sørge for å godkjenne Altinn/Digitaliseringsdirektoratet som meldingsprodusent.

customEmail

CustomText

reminders (liste av påminnelsesobjekter)

Hvert objekt i reminders-listen kan inneholde følgende felter:

Hvis verken requestedSendTime eller sendAfterDays er satt, sendes påminnelsen så snart som mulig etter at hovedvarselet er behandlet.

Hvis ingen egendefinerte tekster er oppgitt på påminnelsen, arves tekstene fra hovedvarselet.

Kanalvalg (notificationChannel)

Merk at notificationChannel er en integer-enum, ikke en streng. Gyldige verdier er:

Språk

For privatpersoner hentes språket automatisk fra profilen deres i Altinn. For organisasjoner brukes språket oppgitt i instansieringsforespørselen (language-feltet i notification-objektet), med norsk bokmål som fallback.

Sendetidspunkt

Som standard sendes varsler kun i arbeidstiden. Hvis du ønsker å tillate utsending når som helst på døgnet, kan du sette allowSendingAfterWorkHours til true. Dette gjelder både e-post og SMS.

Planlagt sendetid

Hvis requestedSendTime er satt, vil varselet ikke sendes før dette tidspunktet. I tillegg vil Altinn Notifications kalle tilbake til appen rett før utsending for å bekrefte at varselet fortsatt er relevant. Appen kan da avvise utsendingen dersom tilstanden har endret seg — for eksempel hvis instansen allerede er innsendt.

Hvis requestedSendTime ikke er satt, sendes varselet så snart som mulig (typisk innen noen minutter).

Egendefinert avbestillingslogikk

Når requestedSendTime er satt, vil Altinn Notifications kalle tilbake til appen før hvert varsel og hver påminnelse sendes. Som standard sendes varselet kun hvis prosessen ikke er avsluttet — det vil si at instansen fortsatt er aktiv og venter på svar fra bruker.

Du kan overstyre denne oppførselen ved å implementere ICancelInstantiationNotification-grensesnittet og registrere det i DI-containeren:

public class MyNotificationCancellation : ICancelInstantiationNotification
{
    public bool ShouldSend(Instance instance)
    {
        // Egendefinert logikk her, f.eks.:
        // Send kun varselet hvis instansen ikke er arkivert
        return instance.Status?.IsArchived is not true;
    }
}

Registrer implementasjonen i Program.cs:

services.AddTransient<ICancelInstantiationNotification, MyNotificationCancellation>();

Standardtekster

Hvis du ikke oppgir egendefinerte tekster, brukes standardtekster.

Eksempel på mottatt e-post med standardtekst:

Emne: Nytt skjema opprettet i Altinn

Brødtekst: Testdepartementet har opprettet et nytt skjema (varsel-instansiering-ttd) for ASTROLOG NÆR med fødselsnummer 54928201018 - åpne innboksen i Altinn for å se skjemaet.

Egendefinerte tekster og tokens

Egendefinerte tekster støtter følgende tokens som erstattes dynamisk:

Hvordan utledes mottakeradresse(r)?

Altinn Notifications tar seg av dette basert på Altinn Profil for enkeltpersoner og register for organisasjoner.

I testmiljøer kan kontaktopplysninger endres for testing på https://tt02.altinn.no/ui/Profile.

For test av SMS i et testmiljø må nummeret hvitelistes. Ta kontakt dersom dette er ønskelig.

Eksempler

Enkelt eksempel på en instansopprettelse med varsel

{
  "instanceOwner": {
    "personNumber": "54928201018"
  },
  "notification": {
    "notificationChannel": 0
  }
}

Eksempel med egendefinerte tekster

{
  "instanceOwner": {
    "personNumber": "54928201018"
  },
  "notification": {
    "notificationChannel": 4,
    "customSms": {
      "senderName": "MinOrg",
      "text": {
        "nb": "$appName$ er klar for $instanceOwnerName$",
        "nn": "$appName$ er klar for $instanceOwnerName$",
        "en": "$appName$ is ready for $instanceOwnerName$"
      }
    },
    "customEmail": {
      "subject": {
        "nb": "$appName$ - ny instans opprettet",
        "nn": "$appName$ - ny instans oppretta",
        "en": "$appName$ - new instance created"
      },
      "body": {
        "nb": "Hei $instanceOwnerName$, en ny instans av $appName$ er opprettet for deg.",
        "nn": "Hei $instanceOwnerName$, ei ny instans av $appName$ er oppretta for deg.",
        "en": "Hello $instanceOwnerName$, a new instance of $appName$ has been created for you."
      }
    }
  }
}

Eksempel med planlagt sendetid og utsending utenom arbeidstid

{
  "instanceOwner": {
    "personNumber": "54928201018"
  },
  "notification": {
    "notificationChannel": 0,
    "requestedSendTime": "2025-12-01T09:00:00Z",
    "allowSendingAfterWorkHours": true
  }
}

Eksempel med påminnelser

{
  "instanceOwner": {
    "personNumber": "54928201018"
  },
  "notification": {
    "notificationChannel": 0,
    "requestedSendTime": "2025-12-01T09:00:00Z",
    "reminders": [
      {
        "sendAfterDays": 7
      },
      {
        "requestedSendTime": "2025-12-15T12:30:00Z",
        "customEmail": {
          "subject": {
            "nb": "Påminnelse: $appName$ venter på deg",
            "nn": "Påminning: $appName$ ventar på deg",
            "en": "Reminder: $appName$ is waiting for you"
          },
          "body": {
            "nb": "Hei $instanceOwnerName$, vi minner om at $appName$ fortsatt venter på svar.",
            "nn": "Hei $instanceOwnerName$, vi minner om at $appName$ framleis ventar på svar.",
            "en": "Hello $instanceOwnerName$, we would like to remind you that $appName$ is still awaiting your response."
          }
        }
      }
    ]
  }
}

Selvidentifisert bruker

ID-porten e-post

{
  "instanceOwner": {
    "externalIdentifier": "urn:altinn:person:idporten-email:jens.jensen@digdir.no"
  },
  "notification": {
    "notificationChannel": 0
  }
}

Utfaset brukernavn og passord

{
  "instanceOwner": {
    "externalIdentifier": "urn:altinn:person:legacy-selfidentified:jensjensen"
  },
  "notification": {
    "notificationChannel": 0
  }
}