Role and access package based signing

Extend the app process with a signing task

A signing task must be added to App/config/process/process.bpmn, as illustrated below.

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 signing the data. Performed by the signees.
• reject: If the end user sees something wrong with the signing 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>

        <!-- We have made a default validator that can be enabled here. -->
        <!-- It will validate that the required number of signatures configured is fulfilled. -->
        <!-- (specified by the `minCount` property on the signature data type) -->
        <!-- If default validation is not enabled, custom validation of the signatures should be added. -->
        <altinn:runDefaultValidator>true</altinn:runDefaultValidator>

        <!-- Optional: If you wish to send signature receipts, -->
        <!-- insert your correspondence resource in the property below. -->
        <altinn:correspondenceResource>app-correspondence-resource</altinn:correspondenceResource>
      </altinn:signatureConfig>
    </altinn:taskExtension>
  </bpmn:extensionElements>
  <bpmn:incoming>SequenceFlow_1oot28q</bpmn:incoming>
  <bpmn:outgoing>SequenceFlow_1if1sh9</bpmn:outgoing>
</bpmn:task>

If you have chosen to send signing receipts by specifying a correspondence resource, you can find additional details regarding that configuration here.

Add data types for storing signing related data

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"
  ],
  "allowedContributors": [
      "app:owned"
  ],
  "minCount": 1,
  "actionRequiredToRead": "signature-access",
  "actionRequiredToWrite": "signature-access"
}

The value of the id property must match the value specified in the signing task definition.

It is important to set allowedContributors to "app:owned". This ensures that these data items cannot be edited via the app’s API but only by the app itself. Before version 8.6, this was misspelled allowedContributers.

We recommend placing access restrictions on the signature objects, by specifying the actionRequiredToRead and actionRequiredToWrite properties on the data type definition. If this is not something you wish to do, those properties can be removed from the configuration.

Access control

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

More information about action attributes can be found here.

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.

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-actions",
        "type": "SigningActions"
      }
    ]
  }
}

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"
}

Dette steget må gjøres manuelt. Støtte for konfigurasjon i Altinn Studio kommer senere. Se “Manuelt oppsett”-fanen for denne seksjonen for veiledning.