Skip to main content

​
Prerequisites

  • A working Risksheet configuration with risk items displayed
  • Access to the risksheet.json configuration file (see Find Configuration Files)
  • A target work item type for tasks (e.g., task, mitigationAction, countermeasure)

​
Step 1: Define the Task Data Type

Open your risksheet.json and add a task entry under dataTypes. This tells Risksheet which work item type represents your downstream tasks and how they relate to risk items. 
{
  "dataTypes": {
    "task": {
      "type": "mitigationAction",
      "role": "mitigates",
      "isBackLink": false,
      "zoomColumn": "taskTitle",
      "showInMenu": true
    }
  }
}
PropertyPurpose
typeThe Polarion work item type ID for downstream items
roleThe link role connecting risks to tasks
isBackLinkSet true if the link is stored on the task side pointing back to the risk
zoomColumnColumn that receives focus when you create a new task
showInMenuControls whether task creation appears in the context menu

​
Step 2: Add Task Columns

Add columns to display task properties in the grid. Set the taskColumn property to identify which column holds the task identifier — this drives task creation, ID generation, and link field synchronization. 
{
  "taskColumn": "taskId",
  "columns": [
    {
      "binding": "taskId",
      "header": "Task ID",
      "type": "taskLink",
      "width": 120
    },
    {
      "binding": "taskTitle",
      "header": "Mitigation Action",
      "type": "taskAttrib",
      "width": 250
    },
    {
      "binding": "taskStatus",
      "header": "Status",
      "type": "taskAttrib",
      "width": 120
    }
  ]
}
diagram

​
Step 3: Configure Document-Scoped Task Creation

By default, new tasks are created in the Polarion project tracker. To store them within a specific document, add the createInDocument property: 
{
  "dataTypes": {
    "task": {
      "type": "mitigationAction",
      "role": "mitigates",
      "createInDocument": "Risks/Tasks"
    }
  }
}
If you omit createInDocument, all new downstream items go to the project tracker rather than a LiveDoc document. This is the most common misconfiguration reported by users. Note that chapter-level placement within a document is not supported — items are added at the document root level.
You can also control where existing tasks are loaded from using the document property: 
{
  "dataTypes": {
    "task": {
      "type": "mitigationAction",
      "role": "mitigates",
      "document": "Risks/Tasks",
      "createInDocument": "Risks/Tasks"
    }
  }
}
Risksheet supports two loading modes:
  • Link-based (default): follows work item link roles to find tasks. Best when tasks can reside anywhere in the project.
  • Document-based: uses loadTasksFromDocument to query a specific document location. Best when tasks are organized in a dedicated document.

​
Step 4: Configure Cross-Project Tasks

For tasks that reside in a different project, use the project property for a single target or projects for multiple: 
{
  "dataTypes": {
    "task": {
      "type": "mitigationAction",
      "role": "mitigates",
      "project": "MitigationProject"
    }
  }
}
For multiple target projects: 
{
  "dataTypes": {
    "task": {
      "type": "mitigationAction",
      "role": "mitigates",
      "projects": ["ProjectA", "ProjectB"]
    }
  }
}
Use project (singular) when all tasks belong to one target project. Use projects (plural array) when tasks may come from multiple projects. Mixing both is not supported. In clustered Polarion setups with separate servers, items cannot be linked across different server instances.
Prior to version 24.6.0, linking existing downstream items from another project required removing the task project column as a workaround. This issue was resolved in version 24.6.0.

​
Step 5: Control Task Editability

Use the downstreamReadonly property to prevent users from modifying task items: 
{
  "downstreamReadonly": true
}
When downstreamReadonly is true, task cells are read-only and new tasks cannot be created on those items. The canExecute check on task creation validates both grid-level readonly state and this downstream permission flag.

​
Step 6: Manage Multi-Task Behavior

Risksheet supports multiple downstream tasks per risk item. When you add a task to an item that already has tasks:
  1. The current record is cloned with task-level fields cleared
  2. A new unique task ID is generated automatically
  3. The new row is inserted immediately after all sibling tasks (grouped by systemItemId)
Tasks belonging to the same parent risk are kept together in the grid and always sorted by local ID in ascending order (e.g., TASK-1, TASK-2, TASK-10). Unresolvable work items (deleted or inaccessible) are silently filtered out.
As of version 25.9.0, when you create a new task within a group that already has tasks, values from sibling items are automatically inherited, reducing manual data entry.

​
Verification

After saving your configuration:
  1. Open the Risksheet in the configured LiveDoc document
  2. Right-click a risk item and select the option to create a new task
  3. Verify the new task row appears below the risk item with an auto-generated ID
  4. Confirm the task is created in the correct location (document or tracker)
  5. Check that the zoomColumn receives focus for immediate editing
You should now see downstream task rows linked to your risk items, with task attributes displayed in their configured columns.

​
See Also