Altinn Studio User guides Development Signing Role and access package

Role and access package based signing

Follow these steps to implement role based signing in your service.

What does role/access package-based signing mean?

By role and access package based signing, we mean a service where individuals who need to sign have the right to read and sign due to a role or access package they hold. For example a CEO, accountant or auditor.

Prerequisites

If the service should send a signature receipt to the inbox of the signee, the Altinn message service (Correspondence) must be enabled.

See how to get started.

Extend the app process with signing task:

A singing task must be added to App/config/process/process.bpmn.

We recommend doing this using the Altinn Studio process editor, so that the BPMN diagram is generated, to show the apps process.

Signing normally uses two user actions. If the Altinn user interface is used by the app, these will be called by button pressen in the signing step. If only the API is used, these must be called manually via the /actions endpoint or via process next.

sign: The actual act of singing the data. Performed by the signees.
reject: If the end user sees something wrong with the singing step, they can abort the signing step. All signatures and the signee state is deleted, and runtime delegated access rights are revoked. Which process step the user is taken to after this is specified in a gateway, as exemplified below.

<bpmn:task id="SigningTask" name="Signering">
  <bpmn:extensionElements>
    <altinn:taskExtension>
      <altinn:taskType>signing</altinn:taskType>
      <altinn:actions>
        <altinn:action>sign</altinn:action>
        <altinn:action>reject</altinn:action>
      </altinn:actions>
      <altinn:signatureConfig>
        <altinn:dataTypesToSign>
          <altinn:dataType>ref-data-as-pdf</altinn:dataType>
        </altinn:dataTypesToSign>
        <altinn:signatureDataType>signatures</altinn:signatureDataType>
      </altinn:signatureConfig>
    </altinn:taskExtension>
  </bpmn:extensionElements>
  <bpmn:incoming>SequenceFlow_1oot28q</bpmn:incoming>
  <bpmn:outgoing>SequenceFlow_1if1sh9</bpmn:outgoing>
</bpmn:task>

The value of the node <altinn:signatureDataType>signatures</altinn:signatureDataType> must match the ID of the data type you configured in the previous step.

These data types should be added in the dataTypes array in App/config/applicationmetadata.json.

This data type is used to store the actual signatures that are generated when a user performs the sign action.

{
  "id": "signatures",
  "allowedContentTypes": [
      "application/json"
  ]
}

The IDs can be set to something else, but they must match the IDs entered in signatureDataType in the process step, as shown in the process task step.

Tilgangsstyring

Give read, write and alternatively sign to the instance owner. Others who should sign also need read and write.

This step needs to be done manually. Support for configuration in Altinn Studio Designer will come later. Take a look at the “Manual setup”-tab for this section for guidance.

2. Add layout-set for signing

Legg til en ny mappe under App/ui for signeringsoppgaven din. Kall den f.eks. signing.

Oppdater filen App/ui/layout-sets.json med ny sidegruppe, som har samme id som mappen du nettopp opprettet.

Din oppdaterte layout-sets.json kan se slik ut:

{
  "$schema": "https://altinncdn.no/toolkits/altinn-app-frontend/4/schemas/json/layout/layout-sets.schema.v1.json",
  "sets": [
    {
      "id": "form",
      "dataType": "model",
      "tasks": [
        "Task_1"
      ]
    },
    {
      "id": "signing",
      "dataType": "model",
      "tasks": [
        "Task_2"
      ]
    }
  ]
}

I mappen du opprettet, legg til en ny fil kalt signing.json.

Det finnes et sett med ferdige komponenter for å bygge opp layout for et signeringssteg. Vi anbefaler å bruke disse, men de er ikke obligatoriske.

SigningDocumentList:
- Lister ut dataene som blir signert på. Feks. vedlegg, xml-data eller PDF-oppsummering fra tidligere steg.
SigneeList:
- Lister ut signatarer og tilhørende signeringsstatus.
- Per nå støtter ikke denne listen å vise roller som skal signere, kun personer som har fått brukerstyrt delegert tilgang. Men i det øyeblikket en person utfører en signering vil de dukke opp, så vi kan bruke den som en “Signaturer”-liste.
SigningStatusPanel:
- Utleder status for signeringssteget og viser relevante knapper til sluttbruker, feks. “Signer”-knappen.

Dersom du ikke benytter SigningStatusPanel for å vise “Signer”-knappen, så må du legge til en egen action button med action “sign”, for å la sluttbruker signere.

Eksempel på bruk av komponentene:

{
  "$schema": "https://altinncdn.no/toolkits/altinn-app-frontend/4/schemas/json/layout/layout.schema.v1.json",
  "data": {
    "layout": [
    {
      "id": "headerSigningFounders",
      "type": "Header",
      "size": "L",
      "textResourceBindings": {
        "title": "Her kan man ha en overskrift"
      }
    },
    {
      "id": "signing-documents",
      "type": "SigningDocumentList",
      "textResourceBindings": {
        "title": "Dokumenter som skal signeres",
        "description": "Dokumenter som skal signeres beskrivelse"
      }
    },
    {
      "id": "signee-list",
      "type": "SigneeList",
      "textResourceBindings": {
        "title": "Signaturer"
      }
    },
    {
      "id": "signing-state",
      "type": "SigningStatusPanel"
    }
  ]
  }
}

Du kan overstyre teksten som vises når listen er tom, før noen har signert, ved å legge til en tekst for text resource nøkkel signee_list.no_signees i text resource filene deres.

{
  "id": "signee_list.no_signees",
  "value": "Ingen signaturer enda"
}