(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Kanban Board

Overview

• The Dynamic Kanban Board is a visual workflow management tool.
• It displays tasks or items in columns based on their status.
• Teams can track progress by moving items between stages.
• It supports drag-and-drop, creation, editing, and deletion of items.
• It is useful for Agile project management and task tracking.

Specs

Tokens

Structure

• The Kanban board is organized into vertical columns that represent workflow stages.
• Columns are generated dynamically from the board datasource.
• Each column contains Kanban Items, which represent tasks or work items.
• Kanban Items are allocated to columns based on their status field.

(Configured in General Properties)

• displayName – Sets the display name of the component shown in the structure panel.

(Configured in Column Properties)

• elements – Defines the columns that make up the Kanban board based on status values from the data source. This is automatically populated from the status data source and configured via the column configuration options. The component generates appropriate KanbanColumn components for each status.

Datasource Board

(Configured in Datasource)

• id – Specifies a unique identifier for the component used for programmatic access. For example, "sprint-tasks-kanban" enables targeted manipulation of this specific Kanban board component.
• getStatusesDataSourceId – Specifies the data source ID for retrieving the list of status columns for the Kanban board. For example, "api/workflow/statuses" would fetch the available workflow states like "To Do", "In Progress", and "Done".
• getStatusesHttpRequestParametersMap – Configures HTTP parameters for fetching status data, including query parameters and path parameters.
• statusesStatusField – Specifies which field from the status data source should be used as the status identifier.
• statusesTitleField – Specifies which field from the status data source should be used as the display name for column headers.

Datasource Kanban Items

(Configured in Datasource)

• getKanbanItemDataSourceId – Specifies the data source ID for retrieving Kanban items or tasks. For example, "api/tasks" would fetch all work items to be displayed on the board.
• getKanbanItemsHttpRequestParametersMap – Configures HTTP parameters for fetching Kanban items, including query parameters and path parameters.
• kanbanItemKeyField – Defines the field used to uniquely identify each Kanban item.

Data Allocation

(Configured in Datasource)

• kanbanItemsStatusField – Specifies which field from the Kanban item data source contains the status value.
• kanbanItemTitleTemplate – Defines the template for displaying the title of each Kanban item.
• kanbanItemSubtitleTemplate – Defines the template for displaying a subtitle on each Kanban item.
• kanbanItemDescriptionTemplate – Defines the template for displaying a description on each Kanban item.

Styling

(Configured in Visibility Properties)

• displayConditions – Defines conditions for displaying the component based on context values or expressions.

(Configured in Visual Properties)

• title – Title text displayed at the top of the Kanban board.
• kanbanTitleTranslations – Localized text for multiple languages.
• iconsRules – Defines custom icons to be displayed on Kanban items based on specified conditions.
• paddingClass – Configures the padding space around the Kanban board using CSS classes.

Pagination

(Configured in Datasource)

• statusPagination – Activates server-side pagination for the status data source.
• statusPaginationPageSize – Sets the number of statuses to load per page.
• kanbanItemPagination – Activates server-side pagination for the Kanban items data source.
• kanbanItemPaginationPageSize – Sets the number of Kanban items to load per page.

Actions & Variants

(Configured in Events)

• events – Configures the events that the component can trigger and respond to:
• ON_INIT (Events) – Triggered when the component is initialized.
• ON_DESTROY (Events) – Triggered when the component is removed from the DOM.

(Configured in Datasource Properties)

• allowUpdating – Enables item updating functionality.

• updateKanbanItemDataSourceId – Data source ID for updating Kanban items.

• updateKanbanItemHttpRequestParametersMap – Parameters for update requests.

• allowAdding – Enables item creation functionality.

• addDialog – Dialog used for adding new Kanban items.

• allowDeleting – Enables item deletion functionality.

• deleteKanbanItemDataSourceId – Data source ID for deleting Kanban items.

• deleteKanbanItemHttpRequestParametersMap – Parameters for delete requests.

• deleteConfirmation – Requires confirmation before item deletion.

Tests

(Configured in Testing Hooks)

• dataTestId – Sets the testing hook ID for automated testing.
• enableAsHotspot – Enables the component as a guided tour hotspot.
• guidedTourHotSpotTitle – Sets the title for the guided tour hotspot.
• guidedTourHotSpotDescription – Sets the description for the guided tour hotspot.

Authorization

(Configured in Authorization)

• visibilityPolicySetId – Determines the visibility of the component based on specified policy sets.

Links

• Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=14730-37787&t=ExcQFUXKvr1QdxTm-1

Guidelines

Technical Documentation for Backend Developers

The component requires two main data sources:

1. Status Data Source: Provides the columns for the Kanban board

   [
     {
       "status": "to-do",
       "titleTranslations": {
         "en-US": "To Do",
         "de-DE": "Zu erledigen"
       }
     },
     {
       "status": "in-progress",
       "titleTranslations": {
         "en-US": "In Progress",
         "de-DE": "In Bearbeitung"
       }
     },
     {
       "status": "done",
       "titleTranslations": {
         "en-US": "Done",
         "de-DE": "Erledigt"
       }
     }
   ]
   

2. Kanban Items Data Source: Provides the items to be displayed on the board

   [
     {
       "id": "task-1",
       "title": "Create user authentication",
       "description": "Implement login and registration functionality",
       "status": "to-do",
       "assignee": {
         "id": "user-1",
         "name": "Alice Smith"
       },
       "priority": 8
     },
     {
       "id": "task-2",
       "title": "Design database schema",
       "description": "Create ERD and define relationships",
       "status": "in-progress",
       "assignee": {
         "id": "user-2",
         "name": "Bob Johnson"
       },
       "priority": 7
     }
   ]
   

API Endpoints

The component interacts with several endpoints:

1. Get Statuses: Fetches the available statuses for the board columns
2. Get Kanban Items: Fetches all items to be displayed on the board
3. Update Kanban Item: Updates an item's properties (particularly status when dragged between columns)
4. Create Kanban Item: Creates a new item
5. Delete Kanban Item: Removes an item from the board

When using pagination, the component expects responses in the following format:

{
  "content": [
    /* array of items */
  ],
  "totalElements": 42,
  "totalPages": 3,
  "number": 0,
  "size": 20,
  "first": true,
  "last": false,
  "empty": false
}

The component maps field names as specified in the configuration, making it adaptable to various API response formats.

Usage

• Use the board to visualize work items by status.
• Choose it when users need to move items between stages via drag-and-drop.

Sizing & Layout

• Keep column headers short and scannable.
• Make cards concise using title, subtitle, and description templates.
• Add spacing around the board only through its padding control.

States & Feedback

• Use conditional icons on cards to communicate states (e.g., priority, blocked) rather than color alone.
• Require a confirmation step before deletions.

Interactions & Events

• Run setup on initialization (e.g., prefetch) and release resources on destruction using lifecycle events.
• Use the built-in dialogs to create and edit items when enabled.

Visibility & Authorization

• Show or hide the board based on contextual display rules (e.g., selected project).
• Apply policy-based visibility so unauthorized users do not see the board.

Content & Localization

• Provide a localized board title; keep it short and task-focused.
• Localize on-card text by feeding localized fields through the templates.
• Expose stable identifiers for authoring and test automation without affecting user-facing text.

Dos & Don’ts

Accessibility

• Provide a concise, localized board title so assistive tech announces meaningful context.
  • Keep card content short and structured using title/subtitle/description templates.
• Convey state with icons triggered by rules (avoid color-only meaning).
• Include a confirmation step for destructive actions.
• Keep interactions predictable via lifecycle initialization/cleanup.
• Provide stable testing hooks/identifiers for automated checks.
• Reduce cognitive load on large boards using pagination for statuses and items.
• Hide irrelevant or unauthorized content using the board’s visibility controls.