Introduction
The OSPROV Query Builder lets you create reusable queries for workflow submission data without writing code. You select a published workflow, choose the fields you want to return, add filters or aggregation calculations, and save the query to generate a secure API endpoint.
This manual will guide you through creating, managing, previewing, and using Query Builder APIs in OSPROV.
What Is Query Builder?
Query Builder is a reporting and integration tool for workflow submissions. It helps you:
- Extract selected fields from workflow submissions
- Filter submissions by text, number, date range, or empty values
- Calculate totals, averages, minimums, maximums, counts, and distinct counts
- Save the query as a stable API endpoint
- Use the API response in dashboards, reports, and external systems
Queries run against a single published workflow at a time. They include submissions from all versions of that workflow and exclude draft submissions.
Key Features
| Feature | Details |
|---|---|
| Visual Query Setup | Select a workflow, choose fields, and configure criteria through the Query Builder form |
| Field Selection | Use fields from the workflow's main form and supplementary forms |
| Filtering | Filter by text matching, numeric comparisons, date ranges, and null checks |
| Aggregation | Calculate sum, avg, min, max, count, and count_distinct values |
| API Endpoint | Every saved query gets a GET /api/query/{query-name} endpoint |
| Preview | View saved query output while editing a query |
| Runtime Overrides | Replace saved filters or aggregates with URL parameters when calling the API |
Common Use Cases
Management Reports
Create reports for approved submissions, department-level activity, budget requests, or other workflow data that managers need to review.
KPI Monitoring
Use aggregations to calculate totals, averages, or counts from matching submissions.
Dashboard Integration
Connect the generated API endpoint to external dashboard or reporting tools that can consume JSON data.
Audit and Compliance
Find submissions that match a specific field value, date range, or processing scenario.
Application Integration
Use the query API to pass workflow submission data to another system, such as HR, finance, ERP, or internal reporting tools.
Important Limits
Query Builder is designed for saved JSON API queries. It does not currently provide:
| Feature | Current Behavior |
|---|---|
| File Export | CSV, Excel, and JSON file export are not available from Query Builder |
| Pagination | The API returns the full filtered result set in one response |
| Group By | Group-by reporting is not implemented |
| Cross-Workflow Queries | Each query targets one workflow |
| Real-Time Streaming | Results are calculated when the API is called |
What's in This Section
- Getting Started - Create your first query and generate an API endpoint
- Building Queries - Understand fields, filters, aggregations, preview, and saving rules
- Using Query APIs - Authenticate API calls and override saved filters or aggregates
- Advanced Usage and Limitations - Runtime overrides, performance behavior, and current limits
- Best Practices - Recommendations for stable names, large workflows, and secure API use
- Troubleshooting - Common issues and how to resolve them