Skip to content

Commit

Permalink
first round of documentation for changes in v8 (#1245)
Browse files Browse the repository at this point in the history 
* first round of documentation for changes in v8

* added signing documentation

* add norwegian docs for process

* translated changelog

* Move process documentation and add serveraction docs

* updated documentation for actions (process and server)

* Moved server actions below a new page grouping the differnt types of actions.

* Added information about access control of actions

* Update content/app/development/process/actions/process-actions/_index.nb.md

Co-authored-by: Vemund Gaukstad <[email protected]>

* Minor fixes after feedback

* Fix broken links

* One more broken link

---------

Co-authored-by: Vemund Gaukstad <[email protected]>
Co-authored-by: Ronny Birkeli <[email protected]>
  • Loading branch information
@RonnyB71 @tjololo
3 people authored Jan 22, 2024
1 parent a5ea1f2 commit f2f5131
Show file tree
Hide file tree
Showing 23 changed files with 2,265 additions and 53 deletions.
53 changes: 0 additions & 53 deletions content/app-template/processhandling/_index.md
View file

This file was deleted.

37 changes: 37 additions & 0 deletions content/app/development/process/_index.en.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
title: Process handling
description: The Application template supports defining a business process for the digital service.
tags: [altinn-apps, process, bpmn]
weight: 60
aliases:
- /app-template/processhandling
---

The template follows the [BPMN 2.0 standard.](https://www.bpmn.org/)

## Supported process elements


* [__Process tasks__](tasks) _tasks that require users or systems to perform actions before the process continues_


* [__Flow control__](flowcontrol) _controls navigation through a process with gateways_

## Process Examples

![Simple process](process1.drawio.svg "A process with data task")

![Simple process](process2.drawio.svg "A process with data and confirmation tasks")

![Simple process](process3.drawio.svg "A process with data, confirmation, and feedback task")

![Simple process](process4.drawio.svg "A process with data and confirmations and optional confirmation")

![Simple process](process5.drawio.svg "A process with data and confirmation and optional confirmation with options to go back to the data task")


## Process configuration

In Altinn Studio, the App developer can configure the process.

[Read our development handbook for details.](../../../../app/development/configuration/process/)
32 changes: 32 additions & 0 deletions content/app/development/process/_index.nb.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
title: Prosess handling
description: Applikasjons templaten støtter å definere en foretnings prosess for digitale tjenester
tags: [altinn-apps, process, bpmn]
weight: 60
---

Malen følger [BPMN 2.0-standarden](https://www.bpmn.org/).

## Støttede prosesselementer

* [__Prosessoppgaver__](tasks) _oppgaver som lar brukerne utføre handlinger før prosessen fortsetter_

* [__Flytkontroll__](flowcontrol) _kontrollerer navigasjonen gjennom en prosess med gateways_

## Prosesseksempler

![Enkel prosess](process1.drawio.svg "En prosess med en dataoppgave")

![Enkel prosess](process2.drawio.svg "En prosess med data- og bekreftelsesoppgaver")

![Enkel prosess](process3.drawio.svg "En prosess med data-, bekreftelses- og tilbakemeldingsoppgave")

![Enkel prosess](process4.drawio.svg "En prosess med data og bekreftelser og valgfri bekreftelse")

![Enkel prosess](process5.drawio.svg "En prosess med data og bekreftelse og valgfri bekreftelse med mulighet til å gå tilbake til dataoppgaven")

## Konfigurasjon av prosessen

I Altinn Studio kan apputvikleren konfigurere prosessen.

[Les vår utviklerhåndbok for detaljer.](../../../../app/development/configuration/process/)
17 changes: 17 additions & 0 deletions content/app/development/process/actions/_index.en.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
title: Actions
description:
tags: [altinn-apps, process, bpmn, gateway, action, acitons]
weight: 30
toc: false
---

Actions are used to define what a user can do in a task. Actions are defined in the process file (BPMN) and have authorization rules attached to them defined in the policy file (XACML) to controll who can execute them.

We have two types of actions:
1. **Server actions**
Arbitrary code that can be executed on the server as part of the process. These actions are typically used to help the user fill out the form by prefilling data, perform calculations, call external api's etc. They will typically update the data model, return the updated model to the client and update the UI. You can also tell the client what to do after a successful execution, for instance navigate to the next page.
1. **Process actions**
Process actions are somewhat similar to server actions, but they will move the process to the next step on successful execution. We have a number of predefined process actions, like "write", "confirm", "sign" and "reject". You can also define your own process actions.

{{<children />}}
15 changes: 15 additions & 0 deletions content/app/development/process/actions/_index.nb.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
title: Handlinger
description:
tags: [altinn-apper, prosess, bpmn, gateway, handling, handlinger]
weight: 30
toc: false
---

Handlinger brukes til å definere hva en bruker kan gjøre i en oppgave. Handlinger er definert i prosessen (BPMN) og har i tillegg tilgangsregler som styrer hvem som kan utføre de definert i tilgangskontrollfilen (XACML). Vi har to typer handlinger:
1. **Serverhandlinger**
Vilkårlig kode som kan utføres på serveren som en del av prosessen. Disse handlingene brukes vanligvis til å hjelpe brukeren med å fylle ut skjemaet ved å forhåndsutfylle data, utføre beregninger, kalle eksterne API-er, osv. De vil vanligvis oppdatere datamodellen, returnere den oppdaterte modellen til klienten og oppdatere brukergrensesnittet. Du kan også fortelle klienten hva den skal gjøre etter en vellykket utførelse, for eksempel navigere til neste side.
2. **Prosesshandlinger**
Prosesshandlinger ligner på serverhandlinger, men de vil flytte prosessen til neste trinn ved vellykket utførelse. Vi har en rekke forhåndsdefinerte prosesshandlinger, som "skriv", "bekreft", "signer" og "avvis". Du kan også definere dine egne prosesshandlinger.

{{<children />}}
174 changes: 174 additions & 0 deletions content/app/development/process/actions/process-actions/_index.en.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
---
title: Process actions
description: Extended authorization, custom logic for process actions
tags: [altinn-apps, process, bpmn, gateway, action, acitons]
weight: 30
toc: true
---

In version 8 of the app nugets actions in tasks were introduced. This makes it possible for developers to associate ActionButtons in the UI with UserActions in the backend.
It is possible to authorize each action in a task separately in the policy file.

## Actions with special altinn logic connected to them

### write
Default action that is performed when a data or feedback task is submitted. This is also the permission a user needs to update data in the application.

### confirm
Default action that is performed when a confirmation task i submitted

### sign
Action that generates a signature object based on the configuration of the task see [Signature](../../tasks/signing)

### reject
Action to use when moving back from one task to another. Performing action reject will ensure data elements in the target task is unlocked.

## Custom actions and custom logic when action is performed

### Custom action in task
To add actions to a task you have to modify the `App/config/process/process.bpmn` file and add the wanted action to the task.

Example of a process where Task_1 has the actions _demo_ and _custom_ defined:

```xml {hl_lines=["15-27"]}
<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions id="Definitions_1eqx4ru"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
xmlns:di="http://www.omg.org/spec/DD/20100524/DI"
targetNamespace="http://bpmn.io/schema/bpmn"
xmlns:altinn="http://altinn.no/process">
<bpmn:process id="Process_1rq9ej8" isExecutable="false">
<bpmn:startEvent id="StartEvent">
<bpmn:outgoing>Flow1</bpmn:outgoing>
</bpmn:startEvent>
<bpmn:sequenceFlow id="Flow1" sourceRef="StartEvent" targetRef="Task1" />
<bpmn:task id="Task_1" name="Utfylling">
<bpmn:incoming>Flow1</bpmn:incoming>
<bpmn:outgoing>Flow2</bpmn:outgoing>
<bpmn:extensionElements>
<altinn:taskExtension>
<altinn:taskType>data</altinn:taskType>
<altinn:actions>
<altinn:action>demo</altinn:action>
<altinn:action type="processAction">custom</altinn:action>
</altinn:actions>
</altinn:taskExtension>
</bpmn:extensionElements>
</bpmn:task>
<bpmn:sequenceFlow id="Flow2" sourceRef="Task1" targetRef="EndEvent" />
<bpmn:endEvent id="EndEvent">
<bpmn:incoming>Flow2</bpmn:incoming>
</bpmn:endEvent>
</bpmn:process>
</bpmn:definitions>
```

The type attribute that is defined for the _custom_ action (processAction) is the default value so the type for demo is also processAction.

### Define necessary authorization policies

Users needs to be granted the right to perform the action _custom_ and _demo_ when moving out of _Task1_

This is defined in policy.xml:

```xml
<!-- Beginning of policy.xml definition omitted for brevity -->
<xacml:Rule RuleId="urn:altinn:example:ruleid:2" Effect="Permit">
<xacml:Description>Rule that defines that user with role DAGL can execute myServerAction for
[ORG]/[APP] when it is in Task_1
</xacml:Description>
<xacml:Target>
<xacml:AnyOf>
<xacml:AllOf>
<xacml:Match MatchId="urn:oasis:names:tc:xacml:3.0:function:string-equal-ignore-case">
<xacml:AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">DAGL</xacml:AttributeValue>
<xacml:AttributeDesignator AttributeId="urn:altinn:rolecode"
Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject"
DataType="http://www.w3.org/2001/XMLSchema#string"
MustBePresent="false"/>
</xacml:Match>
</xacml:AllOf>
</xacml:AnyOf>
<xacml:AnyOf>
<xacml:AllOf>
<xacml:Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
<xacml:AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">[ORG]</xacml:AttributeValue>
<xacml:AttributeDesignator AttributeId="urn:altinn:org"
Category="urn:oasis:names:tc:xacml:3.0:attribute-category:resource"
DataType="http://www.w3.org/2001/XMLSchema#string"
MustBePresent="false"/>
</xacml:Match>
<xacml:Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
<xacml:AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">[APP]</xacml:AttributeValue>
<xacml:AttributeDesignator AttributeId="urn:altinn:app"
Category="urn:oasis:names:tc:xacml:3.0:attribute-category:resource"
DataType="http://www.w3.org/2001/XMLSchema#string"
MustBePresent="false"/>
</xacml:Match>
<xacml:Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
<xacml:AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">Task_1</xacml:AttributeValue>
<xacml:AttributeDesignator AttributeId="urn:altinn:task"
Category="urn:oasis:names:tc:xacml:3.0:attribute-category:resource"
DataType="http://www.w3.org/2001/XMLSchema#string"
MustBePresent="false"/>
</xacml:Match>
</xacml:AllOf>
</xacml:AnyOf>
<xacml:AnyOf>
<xacml:AllOf>
<xacml:Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
<xacml:AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">custom</xacml:AttributeValue>
<xacml:AttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id"
Category="urn:oasis:names:tc:xacml:3.0:attribute-category:action"
DataType="http://www.w3.org/2001/XMLSchema#string"
MustBePresent="false"/>
</xacml:Match>
</xacml:AllOf>
</xacml:AnyOf>
</xacml:Target>
</xacml:Rule>
<!-- End of policy.xml definition omitted for brevity -->
```

### Writing the custom code and registering it as a service

The custom code assosiated with a process action is executed before the process is moved to the next task.

To write custom logic create a new class that implements `Altinn.App.Core.Models.UserAction.IUserAction`.

This interface requires you to define an `Id` and an implementation of `public async Task<UserActionResult> HandleAction(UserActionContext context)`. The id provided is used to match the C# implementation with the action specified in the process file.

A very simple implementation of the _custom_ action that only logs the users userId and the instanceId can be implemented as this:

```
using System.Threading.Tasks;
using Altinn.App.Core.Features;
using Altinn.App.Core.Models.UserAction;
using Microsoft.Extensions.Logging;
namespace Altinn.App.Actions;
public class MyDemoAction: IUserAction
{
private readonly ILogger<MyDemoAction> _logger;
public MyDemoAction(ILogger<MyDemoAction> logger)
{
_logger = logger;
}
public string Id => "demo";
public async Task<UserActionResult> HandleAction(UserActionContext context)
{
await Task.CompletedTask;
_logger.LogInformation("UserId: {userId}, InstanceId: {instanceId}", context.UserId, context.Instance.Id);
return UserActionResult.SuccessResult();
}
}
```

If the action retuns a `UserActionResult` with the field success set to true the process is moved to the next task. Otherwise the process will not be moved and the api will return an error to the user.
Loading

0 comments on commit f2f5131

Please sign in to comment.