OData API

​

What OData Does in Risksheet

OData serves as the structured communication protocol between the Risksheet client (the JavaScript grid running in your browser) and the server-side service layer. Every interaction with the grid — loading risk items, editing cell values, creating links, deleting rows — translates into OData requests. Think of OData as a standardized language that the grid speaks to the server. Instead of using custom, proprietary message formats, Risksheet uses the widely adopted OData protocol, which means the data exchange follows predictable patterns for queries, updates, and transactions.

​

CRUD Operations

The OData service layer supports the full set of data operations:

​

Read (GET)

Grid item retrieval loads all work items for a specific document, with optional support for viewing historical revisions or baselines. The service also supports filtered queries for linked items, using OData filter expressions like substringof for search functionality.

​

Create (POST)

New work items created in the grid are submitted via POST requests. Items with temporary IDs (prefixed with *) are mapped to permanent Polarion IDs after creation. The service supports creating master items and linked items within a single transaction.

​

Update (PATCH/PUT)

Cell edits are submitted as PATCH (partial update) or PUT (full update) requests. The service handles preprocessing of linked items, resolving any temporary IDs to their permanent Polarion equivalents before applying changes.

​

Delete (DELETE)

Deletion behavior depends on the item context:

​

Column Type Mapping

Risksheet column types map to OData EDM (Entity Data Model) primitive types for data exchange. This mapping determines how values are serialized over the wire: Any column type not in this table defaults to the String type, providing graceful degradation for custom or future column types.

​

Transaction Management

All data-modifying operations (create, update, delete) execute within server-side transactions. The transaction lifecycle follows a strict pattern:

1. Begin — A new transaction context is established.
2. Execute — All operations within the save batch are applied.
3. Commit — On success, all changes are persisted atomically.
4. Rollback — On failure, all changes are reverted to prevent partial updates.

This transactional approach ensures that complex operations — such as creating a risk item, linking it to an upstream requirement, and adding a mitigation task — either succeed completely or fail without side effects.

​

Search and Autocomplete

The OData layer powers the item suggester and autocomplete functionality in link columns. When you type into an itemLink, multiItemLink, or taskLink column, the grid sends OData queries with filter expressions to find matching work items. The search supports configurable behaviors:

• Minimum query length — Multi-item link searches require at least 3 characters before querying.
• Custom query factories — Administrators can configure query factory functions that add business logic to filter results (e.g., restricting to specific projects or work item statuses).
• Local changes integration — Autocomplete results include items created in the current session but not yet saved, allowing you to link to newly created items immediately.

​

Cross-Project Support

The OData service handles work items from different Polarion projects using an IdProject format (project/itemId). When operating across project boundaries, the system automatically qualifies project-less IDs with the appropriate project identifier. This enables cross-project risk analysis views where risk items, requirements, and mitigations span multiple projects.

​

Sorting

The grid provides intelligent sorting through the OData collection view:

• Work item IDs sort alphanumerically, ensuring that PROJECT-2 comes before PROJECT-10.
• Outline numbers sort hierarchically, so 1.2 comes before 1.10.
• Multi-item links sort by concatenated labels of all linked items.
• Configurable initial sort uses the sortBy property, with ~ prefix for descending order (e.g., ["~dueDate", "priority"]).

​

Related Topics

For details on how data synchronization works end-to-end, see Data Synchronization. To understand the architecture of the communication layers, see Architecture. For exact API endpoint documentation, see the Reference.

---

Sources

Source Code

• RisksheetDataStorage.java
• ColumnTypeManager.java
• TextEditor.ts
• MultiItemLinkEditor.ts
• CellEditorFormatter.ts