OData Reporting Service V5

Professional Business

Overview

The Gruntify Reporting Service v5 is the current, production-ready implementation of OData reporting for Gruntify workspaces. This service provides a comprehensive, standards-compliant interface for querying workspace data through OData 4.0.

Important Versioning Clarification: The version number "v5" refers to the Gruntify Reporting Service version, not the OData standard version. Gruntify Reporting Service v5 implements the OData 4.0 standard as defined by OASIS. This distinction is important when reviewing OData specifications and documentation.

Deprecation Notice

The previous Gruntify Reporting Service v4.3 is now deprecated and will be retired in a future release. If you are currently using v4.3, plan to migrate your reports and integrations to v5. See the Migrating from v4.3 section for guidance.

Service Root URL

To access the Gruntify Reporting Service v5, use the following URL structure:

Where:

• {{gruntify-reporting-server}} — The reporting server URL for your instance, found in Gruntify under Settings > Workspace

• {{workspace}} — Your workspace identifier

Example:

Authentication

Gruntify Reporting Service v5 uses Basic Authentication with your Gruntify user credentials.

When making requests, include the Authorization header with base64-encoded credentials (this is done for you when using tools like Power BI or Excel):

Entity URLs

The v5 service exposes the following entity sets. Use these URLs to query data from your workspace.

Example queries:

Schema Overview

The Gruntify Reporting Service v5 schema represents workspace entities in a normalized, relational structure designed for reporting and analytics. Below is a diagram of the complete v5 schema:

Open

Key Characteristics

• Flatter Entity Structure — Entities expose more fields at the top level, reducing the need for deeply nested object navigation

• Navigation Properties — Relationships between entities are expressed through OData navigation properties, enabling efficient joins without manual key matching

• Comprehensive Entity Coverage — All major workspace data types are represented, including new entities introduced in v5

Key Schema Changes from v4.3

If you are migrating from Gruntify Reporting Service v4.3, be aware of the following structural and functional changes:

Entity Flattening

Entities in v5 have a flatter structure than v4.3. More fields are exposed at the top level, reducing the number of nested objects:

v4.3 Example (nested):

v5 Example (flatter):

You can still navigate the full Job Template entity using the navigation property:

Navigation Properties

Navigation properties allow you to expand related entities directly in OData queries, without manual joins. Common navigation properties include:

• Jobs → jobTemplate, assets, photoMetadata, checkedInHistory, media

• Requests → assets, regions, photoMetadata, media

• Users → teams, accreditations, regions

• Assets → photoMetadata, media

Example:

New Entities

v5 introduces or substantially revises the following entities:

• Trips — Work trip records with associated requests and jobs

• Equipment — Equipment inventory and assignments

• PhotoMetadata — Detailed metadata for photos, available as a navigation property on Requests, Jobs, and Assets

Form Data Handling

Form data in v5 is available in two formats:

1. Structured Format (formData) — An OpenType property containing form field values as key-value pairs, useful for direct access to specific fields

   "formData": { "TextField-8ubq": "Sample Text", "Segmented-hv5u": "Yes" }

2. Flat Format (flatFormData) — An array of objects with controlId, path, and value, useful for aggregation and filtering

   "flatFormData": [ { "controlId": "TextField-8ubq", "path": "TextField-8ubq", "stringValue": "Sample Text" }, { "controlId": "Segmented-hv5u", "path": "Segmented-hv5u", "stringValue": "Yes" } ]

Location Data

Location data in v5 uses the NetTopologySuite Point type with the following properties:

• x — Longitude coordinate

• y — Latitude coordinate

• z — Altitude (where available)

• srid — Spatial reference system identifier

Additional convenience fields include:

• wktGeometry — Well-Known Text representation of the geometry

• geoJsonGeometry — GeoJSON representation of the geometry

Example:

Query Feature Support

• $count — Supported on most entity sets to retrieve record counts

• $orderby — Now supported in v5 (was not available in v4.3). Some properties are non-sortable, including navigation properties and complex types

Query Options

The Gruntify Reporting Service v5 supports the following OData query options:

Filtering ($filter)

The $filter option is supported with the following operators:

• eq — Equals

• gt — Greater than

• ge — Greater than or equal

• lt — Less than

• le — Less than or equal

• and — Logical AND

• or — Logical OR

Important Limitation: Form data cannot be filtered directly on the formData property when querying Assets, Jobs, or Requests. To filter on form data, use flatFormData:

Sorting ($orderby)

Sorting is supported in v5 and was not available in v4.3. Specify fields to sort by, with optional asc (default) or desc:

Non-sortable properties include:

• Navigation properties (e.g., jobTemplate)

• Complex types (e.g., formData, location)

Paging ($top and $skip)

Use $top to limit the number of records returned and $skip to offset results:

Counting ($count)

To retrieve the count of records without fetching the full dataset:

To include a count with your query results, append ?$count=true:

Projection ($select)

Use $select to retrieve only specific fields, reducing payload size and improving performance:

Expansion ($expand)

Use $expand to retrieve related entities through navigation properties:

Expansion can be combined with $select to project specific fields on related entities:

Paging

For large datasets, pagination is essential to avoid timeouts and excessive data transfer. Follow this guidance:

1. Set a page size using $top (recommended: 100-200 records per page)

2. Use the returned @odata.nextLink to fetch subsequent pages

3. Stop when there is no @odata.nextLink in the response

Example

Initial request:

Response (partial):

Use the @odata.nextLink URL to fetch the next page:

When there are no more records, the response will not include @odata.nextLink:

Migrating from v4.3

If you have existing reports or integrations using Gruntify Reporting Service v4.3, follow these migration steps:

Step 1: Update Service Root URL

Change the version segment in your OData URL from v4.3 to v5:

Before:

After:

Step 2: Review Field References

The v5 schema is flatter than v4.3. Update field references to use top-level properties where available:

Before (v4.3, nested):

After (v5, flatter):

Step 3: Leverage Navigation Properties

Instead of manually joining entities by ID, use navigation properties to simplify your queries:

Before (v4.3 manual join):

After (v5 with navigation):

Step 4: Test Sorting and Filtering

v5 supports $orderby and more sophisticated filtering. Review your existing reports and consider applying sorting or improved filters where beneficial.

Related Content