> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Access Layer Endpoints

> Nextedy RISKSHEET communicates with the Polarion server through an internal data access layer that handles grid data retrieval, linked work item lookup, and CRUD operations on risk items.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

<Note title="Internal data-access layer — not an OData API">
  Despite this page's URL, the endpoints below are **not** an OData service: there is no `$filter`, `$select`, `$metadata`, or any other OData query surface. They are the **internal data-access layer** of the Risksheet client — implementation details that may change between releases and are not a supported public API.

  If you need a programmatic, supported way to query or modify risk data, use Polarion's own APIs (SOAP, REST, scripting) against the underlying work items rather than the endpoints described here. All Risksheet data is stored as standard Polarion work items, subject to Polarion authorization.
</Note>

## Base Path

| Component            | Format                                                             |
| -------------------- | ------------------------------------------------------------------ |
| Read path            | `{baseUrl}/risksheet/data/{projectId}/{documentId}`                |
| Revision-scoped read | `{baseUrl}/risksheet/data/{projectId}/{documentId}?revision={rev}` |

The `baseUrl`, `projectId`, and `documentId` values are derived from the runtime application configuration of the current LiveDoc.

## HTTP Methods

| Method   | Operation        | Description                                                        |
| -------- | ---------------- | ------------------------------------------------------------------ |
| `GET`    | Read             | Retrieves grid rows and linked work items for the current document |
| `POST`   | Create           | Creates new work items with automatic ID generation                |
| `PATCH`  | Partial update   | Updates specific fields of existing work items                     |
| `PUT`    | Full update      | Replaces all field values on existing work items                   |
| `DELETE` | Delete or unlink | Deletes a work item or removes a task link relationship            |

## Grid Item Retrieval

Retrieves all work items displayed in the Risksheet grid for the current document.

| Parameter  | Type     | Default | Description                                                                               |
| ---------- | -------- | ------- | ----------------------------------------------------------------------------------------- |
| `revision` | `string` | `""`    | Specific revision or baseline identifier. Empty string returns the current head revision. |

<Tip title="Historical data access">
  Provide a `revision` parameter to query data from a specific revision or baseline. When a revision is set, the grid automatically switches to read-only mode.
</Tip>

## Linked Item Lookup

Used to populate autocomplete suggestions for `itemLink`, `multiItemLink`, and `taskLink` columns based on user input and column configuration.

| Parameter | Type     | Description                                                                         |
| --------- | -------- | ----------------------------------------------------------------------------------- |
| `term`    | `string` | Substring entered by the user for matching against the linked work item title or ID |
| `type`    | `string` | Polarion work item type filter (from the column's `typeProperties.linkTypes`)       |
| `query`   | `string` | Additional Lucene query constraints produced by a column's `queryFactory` function  |

For task-link columns, the `query` constraint may also come from `dataTypes.task.query` (a Lucene query that further filters task autocomplete results, per KB #48001173767).

## Work Item Creation

Creates new work items submitted from the Risksheet grid.

| Convention         | Description                                                                                                            |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `*` prefix on `id` | Marks a client-side temporary ID. The server assigns a permanent Polarion ID and returns a mapping back to the client. |

A single submission can create a master risk item together with linked downstream task items. The server maintains three ID maps so that links between newly created items resolve correctly:

* **taskIdMap** — maps temporary task-link IDs to permanent Polarion IDs
* **itemIdMap** — maps temporary single-item-link IDs to permanent IDs
* **itemLinkIdMap** — maps temporary multi-item-link IDs grouped by column ID

## Work Item Update

| Method  | Behavior                                        |
| ------- | ----------------------------------------------- |
| `PATCH` | Updates only the fields included in the request |
| `PUT`   | Replaces all field values on the work item      |

Both methods preprocess linked-item references to resolve any temporary IDs to permanent Polarion IDs before persisting changes.

## Work Item Deletion

| ID format                         | Behavior                                                                    |
| --------------------------------- | --------------------------------------------------------------------------- |
| Standard ID                       | Permanently deletes the work item                                           |
| ID ending with `;*`               | Removes a task-link relationship without deleting the work item             |
| `project;riskItemId;taskItemId;*` | Removes a task link from an item that lives in a different Polarion project |

## Cross-Project Support

The data access layer handles work items from different Polarion projects using a qualified `project/itemId` form. Project-less IDs are automatically qualified with the active project identifier when an operation crosses project boundaries.

## Transaction Management

All create, update, and delete operations are wrapped in transactions with `begin`, `commit`, and `rollback` handling. If any part of a bulk operation fails, the entire transaction is rolled back so that partial updates are never persisted.

<Note title="Data consistency">
  Risksheet does not maintain its own data store. All data lives in Polarion work items, subject to Polarion's authorization and audit infrastructure. Risksheet visualizes and edits Polarion data — it does not store data separately.
</Note>

## Multi-Item Link Payload

`multiItemLink` columns accept arrays of linked item references in the request body. Each entry can carry a temporary ID (prefixed with `*`) that is resolved during the transaction, alongside references to existing Polarion items.

## Related Pages

* [Column Type Reference](/risksheet/reference/columns/column-types) — column type definitions and behaviors
* [Data Types](/risksheet/reference/columns/data-types) — detailed data type specifications
* [Suggestion and Autocomplete API](/risksheet/reference/api/suggestion-api) — autocomplete and search endpoints
* [Query Syntax](/risksheet/reference/query-syntax) — query filter syntax reference

<LastReviewed date="2026-06-24" />