Data Model and Work Items - Nextedy Documentation

This page builds the mental model you need before touching configuration. It explains the two-entity data model, the distinction between the actual Polarion entities and the visual hierarchy you see in the grid, and the role of the risk item as the central aggregation point that ties context, classification, and mitigations together.

All Data Lives in Polarion

The first and most important idea: there is no Risksheet database. When you save a cell, the value is written to a Polarion work item field. When you create a row, a new Polarion work item is created. When you link a risk to a mitigation, a Polarion link is created using a configured link role. When you open a baseline, you are reading Polarion’s revision history. This has practical consequences:

Authorization is enforced by Polarion. If a user cannot edit a field in the Polarion tracker, they cannot edit it in Risksheet either.
Audit and history come from Polarion. Every change to a work item is captured in Polarion’s revision history; Risksheet does not maintain a parallel log.
Search and reporting use Polarion’s search index. Risk items found through Risksheet are the same items found through Polarion queries, LiveReports, or third-party tools.
Mandatory fields are intentionally NOT enforced inside Risksheet. By design, you can leave required fields blank during analysis and have Polarion’s workflow validation catch them when the document moves to a later status. To make required columns visible during entry, use a cell decorator to color them — see Styling and Formatting.

Think of Risksheet as a spreadsheet view onto Polarion. The spreadsheet has no value of its own without the underlying work items, and editing the spreadsheet is identical to editing the work items directly.

The Two-Entity Data Model

Risksheet’s data model has exactly two entity types, regardless of methodology or industry. Every Risksheet you will ever see is built from these two types of Polarion work items:

Risk items — the main rows of the grid. Configured under dataTypes.risk. Typical work item types: failure modes (Failure Mode and Effects Analysis, FMEA), hazards (Hazard Analysis and Risk Assessment, HARA), threats (Threat Analysis and Risk Assessment, TARA, or STRIDE), risk records, or — in non-risk use cases — requirements.
Task items — downstream linked work items, one or more per risk item. Configured under dataTypes.task. Typical work item types: mitigations, safety requirements, controls, countermeasures, or test cases.

The names “risk” and “task” are naming conventions inside the configuration. They are NOT constraints on what kind of work items you can use. A Risksheet configured with dataTypes.risk.type: requirement and dataTypes.task.type: testcase becomes a requirements traceability matrix. The grid does not care — it simply renders one type of work item as the main row and another as the downstream relationship.

Every configuration property under dataTypes.risk and dataTypes.task defines a small contract with Polarion: which work item type to use, which link role connects them, which work item types are eligible as upstream references, and so on. See Configuration Reference for the full list.

The Risk Item as Central Aggregation Point

The risk item is the keystone of Risksheet’s data model. It is the row that ties together everything you want to express about a single failure, hazard, threat, or other risk concept. Read each risk item from left to right and it tells a complete story:

Context — where this risk lives. Upstream link columns (itemLink, multiItemLink) point back to the function, system, component, or requirement that the risk applies to. Context columns answer “what is this risk a risk of?”
Risk attributes — the description of the failure itself. Editable Polarion fields on the risk work item: failure mode title, cause, effect of failure, hazard description.
Classification — how the risk is rated before mitigation. Severity, occurrence, and detection are scored using rating scales backed by Polarion enumerations. A formula then computes an initial classification — for example, an initial Risk Priority Number (RPN), an Automotive Safety Integrity Level (ASIL) grade, or a 2D risk matrix cell.
Mitigations — what is being done about it. Task items link from the risk row, each typically representing a mitigation, control, safety requirement, or countermeasure. The task item itself is a separate Polarion work item with its own owner, status, and traceability.
Residual risk — how the risk is rated AFTER mitigation. New severity, new occurrence, new detection — same columns conceptually, but stored in different fields and producing a “new RPN” or “final classification”.

The risk item is, in effect, a mapping table: it joins upstream context to downstream mitigations and records the before/after classification of the risk along the way. This is why almost every Risksheet column ultimately attaches to the risk item or to one of its task children — the grid is a flattened, navigable view of that mapping.

Region of the row	Typical columns	Backed by
Context	Item, function, system reference	Upstream links (itemLink, multiItemLink)
Risk attributes	Failure mode, cause, effect	Polarion fields on the risk work item
Initial classification	severity, occurrence, detection, RPN	rating fields + a formula
Mitigations	Mitigation actions, controls, owners	Task items (downstream links)
Residual risk	new severity, new occurrence, new detection, new RPN	rating fields + a formula

Two Senses of “Level”: Data Model vs Visual

The word “level” appears twice in the Risksheet vocabulary, with two very different meanings. Confusing them is the single most common source of misunderstanding when a new configuration does not behave as expected.

Data model levels (always exactly two)

In the data model, there are only two levels: risk items and task items. Both are real Polarion work items. Both are governed by Polarion permissions, workflows, and history. You cannot add a third data model level — the engine does not support it.

Visual levels (one, two, three, or more — configured by you)

The grid you see can present a hierarchy that looks much deeper than two levels. A typical Design FMEA shows Item → Failure mode → Cause → Effect, which feels like four levels. A Functional Hazard Assessment shows Function → Failure condition → Detail, which feels like three. None of these are extra entities in Polarion. They are produced by cell merging. The mechanism is the levels array in the sheet configuration. Each entry defines one visual level, and each column declares which level it belongs to through its level property. When consecutive rows have the same value in a level’s control column, the cells in that column are merged vertically, producing the visual appearance of a parent row spanning multiple child rows.

levels:
  - name: Item
    controlColumn: item
    zoomColumn: item
  - name: Failure mode
    controlColumn: failureMode
    zoomColumn: failureMode
  - name: Cause
    controlColumn: systemItemId
    zoomColumn: causes

Every level entry must have three properties:

Property	Type	Purpose
`name`	string	Display name in the navigation and zoom menu (for example, “Item”, “Failure mode”, “Detail”)
`controlColumn`	string	Column ID whose value drives cell merging — rows with the same value get merged for this level
`zoomColumn`	string	Column ID used as the target when a user uses zoom or drill-down navigation

How columns connect to levels

The column level property is a one-based integer that points into the levels array:

level: 1 corresponds to the first entry in levels (the outermost grouping)
level: 2 corresponds to the second entry
level: 3 corresponds to the third entry

Columns that share the same level number get identical cell merging behavior — that is the practical meaning of “same level”. They merge wherever the control column of that level has the same value across rows. Task columns (those bound to task.* fields) have no level assigned; they merge by parent risk item plus task ID, which is built-in.

Because they share a control column. A level says: “merge cells in any column at this level wherever this control column’s value is identical in consecutive rows.” If you put both “Item” and “Item description” at level 1 with controlColumn: item, they will both merge into the same blocks. This is intentional — it produces the appearance of a parent-row whose attributes span all child rows beneath it.

Common misconceptions

“Adding a level adds a new work item type.” No. Levels are display configuration. The data still has two entity types (risk and task) regardless of how many visual levels you define.
“Risksheet aggregates items from multiple documents.” No. A Risksheet is a visualization of a single LiveDoc. It cannot pull work items from other documents based on naming patterns or document hierarchy. If you need cross-document analysis, use a Polarion query, a LiveReport, or branching.

Visibility and Levels

Defining visual levels is only half of how a row appears in the grid. The other half is visibility: which Polarion work items actually flow into the level at all. Risksheet applies a layered set of filters before any cell merging happens, and understanding that pipeline prevents the most common “why is this item missing?” or “why can’t I edit this?” questions.

What determines whether an item appears

When you open a Risksheet, it loads the risk- and task-type work items that already exist in its LiveDoc — an existing document opens pre-populated with its items, not as a blank grid. From that set, not every work item is necessarily rendered: visibility is the combined result of type filtering, status filtering, permission checks, and level membership. Type filtering. The dataTypes configuration defines which work item types are allowed at each tier:

dataTypes.risk.type — work item types displayed as risk items (the main grid rows). Multiple types can be specified as comma-separated values.
dataTypes.task.type — work item types displayed as task/mitigation items (the downstream linked rows). Multiple types can also be specified as comma-separated values.

Work items whose type does not match either risk.type or task.type are excluded from the grid entirely. This is the most fundamental visibility filter. Rejected status filtering. Work items with a status matching the configured rejectedStatus (default: rejected) are automatically hidden from the grid. The system applies separate rejected-status rules for risk items and task items. This enables a soft-delete pattern: instead of permanently deleting a risk item, change its workflow status to the rejected one and it disappears from the grid while remaining available for audit and traceability in Polarion.

Rather than permanently deleting risk items, configure rejectedStatus and move unwanted items into that status. They remain in Polarion for history and traceability but no longer clutter the active risk analysis view.

Permission-based filtering. Risksheet respects Polarion’s security model. Work items the current user lacks read permission for are silently excluded from results — the user simply does not see items they cannot access. This is especially important in regulated environments where role-based access to risk data is mandated. Unresolvable item filtering. Work items that are corrupted, deleted at the repository level, or otherwise unresolvable are automatically excluded to prevent grid errors. This is a defensive mechanism that handles data quality issues silently.

Upstream, downstream, and indirectly linked items

Levels are fundamentally about relationships between work items, and the terminology used in Risksheet maps directly to the direction of traceability links:

Upstream items are work items the current row links TO (for example, a failure mode links to a system requirement). They appear in upstream traceability columns, typically configured as itemLink or multiItemLink column types.
Downstream items are work items that link FROM the current row (for example, mitigation tasks linked to a failure mode via the task role). They appear in task-level columns at the bottom of the hierarchy.

A common source of confusion is the difference between items that are directly linked to a risk item and items that are linked through an intermediary. If a failure mode (Level 2) links to a requirement (Level 1), and that requirement links to a system function, the system function is an indirect link — it is not directly connected to the failure mode. Standard Risksheet columns can only display directly linked work items. To show items connected through upstream relationships, there are two options:

Server render columns — Use Velocity scripts to traverse indirect links and render the results as read-only HTML. See Server Render Columns for the Velocity patterns.
upstreamChains — A configuration property (format: fromType-linkRole-toType) that automatically builds transitive link chains. This creates actual Polarion links, making the indirect relationships editable. Note that upstreamChains only creates links; it never deletes them.

Users frequently expect that configuring a Level 2 column will automatically show items linked through Level 1 items. This is not how levels work. Each level displays items that are directly linked to the current row’s work item. Indirect links require explicit configuration via server render or upstreamChains.

Cross-project item visibility

Risksheet supports displaying work items from other Polarion projects. This is configured via the project parameter in the typeProperties section of a column or data type definition. When a project ID is specified, Risksheet loads items from that project instead of (or in addition to) the current one. Cross-project visibility has well-defined limits:

It works for directly linked items only. Indirect links through intermediary work items in other projects require additional configuration, typically server render columns with cross-project Velocity queries.
The user must have read permissions in the target project. Items the user cannot access are filtered out.
Workflow status dropdowns correctly load actions for the source project using the project!workItemId format, enabling status editing for cross-project items.

The read-only boundary

Not every visible item is editable. Several factors can make work items or individual columns read-only:

Condition	Effect
`readonly: true` in root configuration	Entire grid is read-only
`downstreamReadonly: true`	Downstream linked items (tasks) from other documents cannot be edited
`reviewer: true`	Reviewer mode restricts editing and shows review-specific controls
Historical revision viewing	Viewing a non-current revision forces read-only mode automatically
Column has `serverRender`	Column is always read-only
Column has `formula`	Column is read-only by default
System fields (`id`, `status`, `type`, `project`, `outlineNumber`)	Always read-only regardless of configuration
Permission restrictions	Columns where the user lacks write permission are read-only

The casing differs by level and both are correct. The root-level grid flag is lowercase readonly (readonly: true makes the whole grid read-only). The column-level property is camelCase readOnly (set on an individual column definition). They are deliberately different keys at their respective levels — neither should be “corrected” to match the other.

Newly created work items (identified by IDs starting with *) have limited functionality until saved. Status dropdowns are disabled for new items because workflow actions only apply to items that exist in Polarion. Save the item first; workflow transitions become available afterwards.

Cell merging revisited

When multiple Level 2 items share the same Level 1 parent, the Level 1 columns merge vertically to span all child rows. This produces the characteristic FMEA layout where a single failure mode description spans multiple cause/effect pairs. The controlColumn property on each level determines which column drives the merge grouping: rows with the same value in the control column at a given level are merged. The visual result is a grid where:

Level 1 columns span multiple rows, showing the parent item data once.
Level 2 columns show one row per child item.
Task-level columns show one row per downstream linked item within each Level 2 group.

The context menu (right-click on a grid cell) provides options for creating new items at different levels. The menu dynamically generates options from the levels array where showInMenu is true. Only levels configured for menu visibility appear as creation options. The context menu also provides:

Open Row Item — navigates to the current row’s work item in Polarion’s item editor.
Open [Column] Item — opens the linked work item for that column; the menu label embeds the column name (for example Open Item/Func Item).
Open Task Item — opens a task work item; the menu label uses the task type name from dataTypes.task.name if configured.
Remove Row Item — removes the selected row (only in editable grids).
New Level Items — creates new work items at the selected level (only in editable grids).

A practical mental model for levels

Think of levels as a telescope with adjustable zoom:

Level 1 is the widest view — top-tier items (system functions, hazards, or failure modes depending on your structure).
Level 2 zooms in to the children of each Level 1 item — causes, effects, or sub-failure modes.
Task level zooms to the finest detail — mitigation tasks, verification activities, or design changes linked to specific Level 2 items.

Each column in the grid is assigned to exactly one zoom level. When you look at a row, the Level 1 columns show data from the Level 1 parent, the Level 2 columns show data from the Level 2 item, and the task columns show data from the downstream linked task. All three coexist in the same visual row, but they represent data from different work items connected by links. The levels configuration in risksheet.json tells Risksheet how many zoom levels exist and which column drives the grouping at each level. The dataTypes configuration tells Risksheet which work item types belong to which tier and which link roles connect them.

Where Data Lives: Fields, Links, and Configuration

When the grid renders, three different sources of data flow into the cells you see:

Cell source	What it is	Where it lives
Field value	A column whose `bindings` matches a Polarion field reads that field’s value	Polarion work item field
Linked field value	A column with `bindings: linkedItem.fieldId` reads from an upstream or downstream linked item	Different Polarion work item, reached via link role
Formula result	A column with a `formula` runs JavaScript to compute the value from other cells in the same row	Computed at display time, optionally stored back to a field

Columns declare these mappings using the bindings property (note: plural — bindings, not binding). Examples:

columns:
  - id: title
    header: Failure mode
    bindings: title
    type: string
    level: 2
  - id: sev
    header: Severity
    bindings: severityRating
    type: rating:severityEnum
    level: 2
  - id: hazard
    header: Hazard
    bindings: hazard.title
    type: string
    level: 1
  - id: rpn
    header: RPN
    formula: commonRpn
    type: int
    readOnly: true
    level: 2

Three binding patterns are possible:

bindings: title — a direct field on the risk work item.
bindings: hazard.title — a field on a linked item. Read-only by default because the value belongs to a different work item.
bindings: task.$item — the entire task work item, used by server-rendered columns that need full Velocity access.

For an enum or rating column, you also declare the enum identifier in the column type:

- id: severity
  header: Severity
  bindings: severityRating
  type: rating:severityEnum
- id: detectionMethod
  header: Detection methods
  bindings: detectionMethods
  type: multiEnum:detectionMethodsEnum

The enum identifier (severityEnum, detectionMethodsEnum) points to a Polarion enumeration defined in Administration → Enumerations, not to something inside the sheet configuration. Risksheet asks the server to load the enumeration values at runtime; this is why custom rating scales are configured in Polarion administration first, then referenced from the column.

The exact set of column types that can appear in your project depends on the field types defined for the configured work item types. Risksheet auto-detects the column type from the Polarion field type when type is omitted, but explicit declaration is recommended for clarity and to override defaults.

Linking: Upstream Context and Downstream Mitigations

The two main link directions create the “left side” and “right side” of the risk item story. Upstream links (left side) attach a risk to its context. They are configured on individual columns through typeProperties:

- id: hazard
  header: Hazard
  bindings: hazard
  type: itemLink
  typeProperties:
    linkRole: relates_to
    linkTypes: hazard
    document: 02 - Risk Management File/Harms Library
  level: 1

The configuration above tells Risksheet that the “Hazard” column links to existing work items of type hazard from a shared library document. New entries created inline (if canCreate allows) go to that document. Downstream links (right side) attach a risk to its mitigations. They are configured under dataTypes.task:

dataTypes:
  task:
    type: mitigation
    role: mitigates
    name: Mitigation
    zoomColumn: mitigationTitle

A single risk row can have many task rows beneath it; the grid renders each task as a “child” row visually grouped with its parent risk. The link itself is a normal Polarion link with the configured role. For deeper explanations of these mechanics, see Traceability and Linking. For the configuration reference, see Configuration Reference.

What About Required Fields, Branching, and Cross-Document References?

A few behaviors that surprise new users — all consequences of “data lives in Polarion”:

Required Polarion fields are not enforced during entry. This is by design. Risksheet keeps the entry surface fast and forgiving; required-field validation belongs to a later workflow status, or to a visual highlight applied through a cell decorator.
Read-only branches. When a document is branched, the branched copy shows the original risk items as read-only references by default. If editableReferencedWorkItems is enabled at the project level, those referenced items become editable in the branch. There is currently no way to reference individual risks across non-branched documents — branching is the supported mechanism for shared risk content.
One document per Risksheet. Risksheet is the visualization of a single LiveDoc. It does not aggregate items across multiple documents based on filename suffixes, document hierarchy, or query results. If a workflow needs cross-document analysis, the answer is either to combine the source documents, use Polarion queries, or open multiple Risksheets side-by-side.

How This Shapes Your Configuration Decisions

If you keep the two-entity / two-sense-of-level model in mind, several configuration decisions become clearer:

Choose the risk work item type carefully. Whatever you put under dataTypes.risk.type becomes the row, the search target, the access control unit, and the audit subject. Switching types later is expensive.
Pick task work item types intentionally. Each task type carries its own custom fields, workflow, and link roles. Multiple downstream types are supported (comma-separated in dataTypes.task.type since recent versions), but each adds complexity.
Use levels for visual structure, not data structure. If you find yourself wishing for a “third data model level”, you are probably looking for either a deeper visual hierarchy (add to levels) or an upstream library (add an itemLink column with typeProperties.document).
Use views, not extra documents, for different perspectives. Saved views let the same underlying data appear with different column subsets for identify-failures vs initial-ranking vs final-assessment stages.

For practical guidance on putting this model to work, see Column Configuration, Risk Management, and Configuration Hierarchy.

​All Data Lives in Polarion

​The Two-Entity Data Model

​The Risk Item as Central Aggregation Point

​Two Senses of “Level”: Data Model vs Visual

​Data model levels (always exactly two)

​Visual levels (one, two, three, or more — configured by you)

​How columns connect to levels

​Common misconceptions

​Visibility and Levels

​What determines whether an item appears

​Upstream, downstream, and indirectly linked items

​Cross-project item visibility

​The read-only boundary

​Cell merging revisited

​Context menu and item creation

​A practical mental model for levels

​Where Data Lives: Fields, Links, and Configuration

​Linking: Upstream Context and Downstream Mitigations

​What About Required Fields, Branching, and Cross-Document References?

​How This Shapes Your Configuration Decisions

All Data Lives in Polarion

The Two-Entity Data Model

The Risk Item as Central Aggregation Point

Two Senses of “Level”: Data Model vs Visual

Data model levels (always exactly two)

Visual levels (one, two, three, or more — configured by you)

How columns connect to levels

Common misconceptions

Visibility and Levels

What determines whether an item appears

Upstream, downstream, and indirectly linked items

Cross-project item visibility

The read-only boundary

Cell merging revisited

Context menu and item creation

A practical mental model for levels

Where Data Lives: Fields, Links, and Configuration

Linking: Upstream Context and Downstream Mitigations

What About Required Fields, Branching, and Cross-Document References?

How This Shapes Your Configuration Decisions