Skip to main content

​
Understanding the Column Type

Upstream traceability columns use the itemLink or multiItemLink column type to display work items that are linked to each risk item through Polarion’s work item link relationships. The column binding specifies the Polarion field that stores the link reference, and the typeProperties section defines the linked item’s work item type and link role. diagram Before configuring the column, determine:
  • The work item type of the upstream item (for example, requirement, systemRequirement, hazard)
  • The link role connecting the risk item to the upstream item (for example, mitigates, verifies, relatesTo)
You can find these values in your Polarion project configuration under Administration > Work Items > Link Roles.

​
Step 2: Add a Basic Upstream Column

Open your risksheet.json configuration and add an itemLink column. Specify the binding as the Polarion field that stores the link, along with the type, work item type, and role in typeProperties: 
{
  "columns": [
    {
      "id": "sysReq",
      "header": "System Requirement",
      "type": "itemLink",
      "binding": "linkedItem",
      "level": 1,
      "typeProperties": {
        "type": "systemRequirement",
        "role": "mitigates"
      }
    }
  ]
}
This configuration displays a single linked system requirement for each risk item at level 1 of the hierarchy.
Every column id in your risksheet.json must be unique across the entire configuration. Duplicating an ID (for example, using "id": "sysReq" on two different columns) will break the sheet structure silently, causing columns to not render or data to be misaligned.

​
Step 3: Configure Multi-Item Upstream Columns

When a risk item can be linked to multiple upstream items (for example, multiple requirements tracing to one hazard), use the multiItemLink type instead: 
{
  "columns": [
    {
      "id": "requirements",
      "header": "Linked Requirements",
      "type": "multiItemLink",
      "binding": "linkedItems",
      "level": 1,
      "typeProperties": {
        "type": "requirement",
        "role": "mitigates"
      }
    }
  ]
}
The multiItemLink column displays all matching linked items within a single cell, allowing users to add and remove links to multiple upstream items.

​
Step 4: Control Item Creation from the Column

By default, upstream columns allow users to both select existing items and create new ones directly from the cell editor. To restrict the column to selection only (preventing creation of new upstream items), set canCreate to false: 
{
  "id": "hazard",
  "header": "Hazardous Situation",
  "type": "itemLink",
  "binding": "linkedItem",
  "level": 1,
  "canCreate": false,
  "typeProperties": {
    "type": "hazardousSituation",
    "role": "hasHazard"
  }
}
Set canCreate to false on upstream columns where the linked items should be pre-created in the tracker or in a separate document. This prevents users from accidentally creating upstream items from within the Risksheet, keeping item creation workflows centralized. The cell remains active for linking and unlinking existing items.

​
Step 5: Make Upstream Columns Editable

By default, upstream item columns are read-only. To allow users to edit field values of the linked upstream item directly from the Risksheet grid, explicitly set readOnly to false: 
{
  "id": "reqTitle",
  "header": "Requirement Title",
  "type": "string",
  "binding": "title",
  "level": 1,
  "readOnly": false,
  "typeProperties": {
    "type": "requirement",
    "role": "mitigates"
  }
}
All upstream item columns default to readOnly. If you add an upstream column and users report they cannot edit it, add "readOnly": false to the column definition. This is a frequent point of confusion during initial setup.

​
Step 6: Specify the Enum Type for Upstream Columns

When displaying enum fields from upstream items, you must explicitly set "type": "enum" in the column definition. While the type property is optional for main row item columns (it can be auto-detected from the Polarion field), it is mandatory for upstream and downstream linked item columns: 
{
  "id": "reqPriority",
  "header": "Priority",
  "type": "enum",
  "binding": "priority",
  "level": 1,
  "typeProperties": {
    "type": "requirement",
    "role": "mitigates"
  }
}

​
Step 7: Configure Cross-Project Upstream Items

To display upstream items from a different Polarion project, add the project parameter to the typeProperties section: 
{
  "id": "crossProjReq",
  "header": "System Requirement",
  "type": "itemLink",
  "binding": "linkedItem",
  "level": 1,
  "typeProperties": {
    "type": "systemRequirement",
    "role": "mitigates",
    "project": "SystemProject"
  }
}
The project parameter specifies the project ID where the upstream items reside. This enables cross-project traceability, where risk items in one project reference requirements or functions defined in another.
The project parameter in typeProperties only works for directly linked items. If your upstream items are linked through intermediary work items in another project (indirect links), the standard cross-project column configuration will not resolve them. Consider using serverRender with Velocity scripts for indirect cross-project link traversal.

​
Step 8: Configure the createInCurrentDocument Parameter

When upstream item creation is enabled (the default), the createInCurrentDocument parameter controls where newly created items are stored: 
{
  "id": "hazard",
  "header": "Hazard",
  "type": "itemLink",
  "binding": "linkedItem",
  "level": 1,
  "typeProperties": {
    "type": "hazard",
    "role": "hasHazard",
    "createInCurrentDocument": true
  }
}
When createInCurrentDocument is true, new upstream items are created within the current LiveDoc document. When false or omitted, new items are created in the Polarion tracker (outside any document).

​
Step 9: Build Upstream Chains with upstreamChains

When you need to automatically create links between two upstream item types that are both connected to the risk item, use the nextedy.risksheet.upstreamChains project property. This is configured at the project level, not in risksheet.json: The format is: fromType-linkRole-toType For example, to automatically link a Hazardous Situation to a Sequence of Events when both are linked to the same Risk Record: 
nextedy.risksheet.upstreamChains = situation-relatesTo-sequenceOfEvents
Multiple chains can be specified with commas: 
nextedy.risksheet.upstreamChains = harm-relatesTo-situation,situation-hasHazard-hazard
The upstreamChains property only creates links between upstream items. It never deletes existing links. If you remove an upstream item from a risk record, the chain link between the two upstream items remains intact and must be manually removed if needed.
Some upstream linkages in DFMEA templates work automatically without explicit upstreamChains configuration. If you are using a Nextedy-provided DFMEA template, test your link behavior before adding chain configuration.

​
Step 10: Use Dependent Upstream Filtering with Query Factory

To filter the options in one upstream column based on the selection in another (for example, showing only Hazardous Situations linked to the already-selected Sequence of Events), combine canCreate: false with a queryFactory: 
{
  "id": "hazSituation",
  "header": "Hazardous Situation",
  "type": "itemLink",
  "binding": "linkedItem",
  "level": 1,
  "canCreate": false,
  "queryFactory": "filterBySeqOfEvents",
  "typeProperties": {
    "type": "hazardousSituation",
    "role": "hasHazard"
  }
}
The queryFactory references a named query definition that dynamically filters available items based on the current row’s data. See Use Query Factory for details on configuring query factories.

​
Verification

After saving your risksheet.json configuration and refreshing the page, you should now see:
  • The upstream column header displayed in the grid
  • Linked upstream items showing their ID or title in each cell
  • The cell editor allowing you to search for and select existing upstream items
  • New item creation available (unless canCreate: false is set)
If the column appears but shows no data, verify that the role and type values in typeProperties match your Polarion project’s link role and work item type definitions exactly.

​
See Also