Skip to main content

Getting Started with Query Builder

This guide explains how to create a basic Query Builder query and get its API endpoint.

Before You Begin​

You need access to at least one published workflow. Only published workflows appear in the Query Builder workflow list.

If you plan to call the generated API from another system, you also need an API Bearer token from your administrator. Query API tokens are separate from regular OSPROV login credentials.

Accessing Query Builder​

  1. Log in to OSPROV.
  2. Open Query Builder from the sidebar menu.
  3. Review the list of existing queries and their API endpoints.
  4. Click Create to build a new query, or Edit to update an existing query.

Creating Your First Query​

Step 1: Select a Workflow​

Choose the workflow that contains the submission data you want to query.

After you select a workflow, OSPROV loads the available fields from the workflow's forms. Queries run across all versions of the selected workflow, so submissions created before and after workflow updates can be included. Draft submissions are always excluded.

Step 2: Select Data Fields​

Use the Data Fields dropdown to choose the fields that should appear in the API response.

The dropdown shows fields from the workflow's main form and supplementary forms. Field labels are shown for readability, and the field key used in API responses appears as subtext.

You can select more than one field. Each selected field appears in the Selection Criteria panel.

Step 3: Add Selection Criteria​

For each selected field, you can configure a filter or an aggregation.

  • Use a filter when you want to narrow which submissions are returned.
  • Use an aggregation when you want OSPROV to calculate a value such as a total, average, minimum, maximum, count, or distinct count.

A field should not use both at the same time. If both are configured, the aggregation takes priority and the filter is discarded when the query is saved.

Step 4: Name and Describe the Query​

Enter a Query Name. The name becomes the slug in the API endpoint URL.

For example:

My Leave Report -> my-leave-report

If you leave the name blank, OSPROV uses the workflow name as the basis. If another query already uses the same slug, OSPROV adds a suffix such as -1 or -2.

Choose the name carefully. The query name cannot be changed after saving because changing it would also change the API URL.

The Query Description is optional. Use it to explain the purpose of the query and who uses it.

Step 5: Save and Get the API URL​

Click Save Query & Get URL.

OSPROV validates that a workflow and at least one field are selected, saves the query, and displays the generated endpoint:

GET /api/query/{query-name}

You can now use this endpoint from dashboards, reports, or integrations. See Using Query APIs for authentication and request examples.

Editing an Existing Query​

To update a query:

  1. Open the Query Builder list.
  2. Click Edit next to the query.
  3. Update the field selection, filters, aggregates, or description.
  4. Click Update Query Builder.

The query name and API URL remain unchanged when editing.

Deleting a Query​

Deleting a query permanently removes it and immediately disables its API endpoint. Check whether any dashboard, report, or integration still uses the endpoint before deleting it.