Adding the Flag and Query Parameter

Oct 13, 2025 by wbrum.org 52 views

Introduction

In the context of Altinn 3 instances, some dialogs are designed for API consumption only and are not suitable for graphical user interfaces (GUIs) such as Arbeidsflate. This article discusses the need to introduce a flag to indicate that a dialog should not be visible in portal GUIs, ensuring that API-only dialogs are easily filtered out and do not require human-readable content.

Description

Altinn 3 instances can be configured to hide "message box" representations, making them invisible in Altinn 2 Innboks. The Dialogporten Storage Adapter takes this configuration into account and does not create dialogs in such cases. A similar mechanism is required to flag dialogs referring to API services at other platforms, allowing them to be excluded from Arbeidsflate and similar systems.

The Need for API-Only Dialogs

A service owner has requested the ability to create dialogs that are only accessible through APIs, without being visible in Arbeidsflate. This feature is essential for service owners who do not use Altinn Studio, as it enables them to utilize the generic mechanisms provided by Dialogporten (e.g., create/updated events) while still maintaining control over their API-only dialogs.

Implementation

To address this requirement, a top-level boolean flag, "isApiOnly," can be introduced, which defaults to false. This flag will be used to filter out API-only dialogs in Arbeidsflate and similar systems. A query parameter, "IncludeApiOnly," will be added to both Service Owner (SO) and Entity User (EU) search endpoints, defaulting to true. This parameter will allow users to include or exclude API-only dialogs from search results.

Adding the Flag and Query Parameter

The following tasks are necessary to implement the API-only dialog feature:

Add a query parameter called 'IncludeApiOnly'
Add an entity and migration to support the new flag
Update all Data Transfer Objects (DTOs) to include the "isApiOnly" flag
Add documentation to explain the new feature and its usage
Add end-to-end tests to ensure the feature works as expected

Threat Modelling

Threat modelling is essential to identify potential security risks associated with introducing the API-only dialog feature. In this case, the following risks have been considered:

Unauthorized access: API-only dialogs may be vulnerable to unauthorized access if not properly secured.
Data exposure: API-only dialogs may contain sensitive data that could be exposed if not handled correctly.

Acceptance Criteria

The following acceptance criteria must be met to ensure the API-only dialog feature works as expected:

Scenario: Filtering API-Only Dialogs in Search Results

Given a request is made to search for dialogs
When the query parameter IncludeApiOnly=false is provided
Then dialogs with isApiOnly=true are excluded from the results

Scenario: Retrieving API-Only Dialogs in Search Results

Given a request is made to search for dialogs
When the query parameter IncludeApiOnly=true is provided (or omitted)
Then dialogs with isApiOnly=true are included in the results

Scenario: Creating an API-Only Dialog

Given a request is made to create a new dialog
When the isApiOnly flag is set to true
Then the dialog is stored with isApiOnly=true

Scenario: Updating an Existing Dialog to API-Only

Given an existing dialog with isApiOnly=false
When it is updated with isApiOnly=true
Then the updated dialog is stored with isApiOnly=true

Scenario: Preventing Unnecessary Content for API-Only Dialogs

Given a new dialog is created with isApiOnly=true
When no title or summary is provided
Then the request is accepted and stored without requiring human-readable content

Scenario: Migrating Existing Dialogs

Given a migration is run on an existing database
When the schema is updated
Then existing dialogs should have isApiOnly set to false by default

Q: What is an API-only dialog?

A: An API-only dialog is a dialog that is designed for API consumption only and is not suitable for graphical user interfaces (GUIs) such as Arbeidsflate.

Q: Why do we need API-only dialogs?

A: API-only dialogs are necessary for service owners who do not use Altinn Studio, as they enable them to utilize the generic mechanisms provided by Dialogporten (e.g., create/updated events) while still maintaining control over their API-only dialogs.

Q: How do I create an API-only dialog?

A: To create an API-only dialog, you need to set the isApiOnly flag to true when creating a new dialog. This will ensure that the dialog is stored with isApiOnly=true and will not be visible in Arbeidsflate and similar systems.

Q: How do I update an existing dialog to API-only?

A: To update an existing dialog to API-only, you need to set the isApiOnly flag to true when updating the dialog. This will ensure that the updated dialog is stored with isApiOnly=true and will not be visible in Arbeidsflate and similar systems.

Q: What happens if I don't provide human-readable content for an API-only dialog?

A: If you don't provide human-readable content (title and summary) for an API-only dialog, the request will be accepted and stored without requiring human-readable content.

Q: How do I filter out API-only dialogs in search results?

A: To filter out API-only dialogs in search results, you need to set the IncludeApiOnly query parameter to false when making a search request. This will ensure that dialogs with isApiOnly=true are excluded from the results.

Q: How do I include API-only dialogs in search results?

A: To include API-only dialogs in search results, you need to set the IncludeApiOnly query parameter to true when making a search request. This will ensure that dialogs with isApiOnly=true are included in the results.

Q: What happens if I don't provide the `IncludeApiOnly` query parameter?

A: If you don't provide the IncludeApiOnly query parameter, the default value of true will be used, and dialogs with isApiOnly=true will be included in the results.

Q: How do I migrate existing dialogs to API-only?

A: When migrating existing dialogs to API-only, the isApiOnly flag will be set to false by default. You need to update the dialogs manually to set the isApiOnly flag to true if you want them to be API-only.

Q: What are the security risks associated with API-only dialogs?

A: The security risks associated with API-only dialogs include unauthorized access and data exposure. It is essential to properly secure API-only dialogs to prevent these risks.

Q: How do I document the API-only dialog feature?

A: You need to update the documentation to explain the new feature and its usage. This includes explaining how to create, update, and filter API-only dialogs.

Q: How do I test the API-only dialog feature?

A: You need to add end-to-end tests to ensure the feature works as expected. This includes testing the creation, update, and filtering of API-only dialogs.