Process analytics API filter not working for custom fields in report queries

pablo_analyst
Tue, 03 Jun 2025 21:54:58 +0000

The empty results you’re experiencing are due to custom fields not being registered in the analytics schema metadata. Here’s the complete solution covering all three critical aspects:

1. Custom Field Registration in Analytics Schema Custom fields must be explicitly registered in the process analytics schema before they become queryable via API. Navigate to Process Analytics > Configuration > Schema Management and register each custom field:

POST /api/v1/analytics/schema/custom-fields
{
  "fieldName": "department",
  "dataType": "string",
  "indexed": true,
  "filterable": true
}
Repeat for: priority (string), requestType (string)

Key registration parameters:

indexed: true enables the field for search operations

filterable: true specifically enables API filter queries

dataType must match the actual data type used in process instances

Field names are case-sensitive in API queries

2. Correct Filter Syntax for Custom Fields Once registered, custom fields require a specific syntax path in API filter queries. The UI uses internal query optimization that differs from the REST API structure:

// Pseudocode - Custom field filter query structure:
1. Verify field registration: GET /api/v1/analytics/schema/fields
2. Locate custom field namespace in response (usually 'custom' or 'extended')
3. Build filter using full path: custom.{fieldName} operator value
4. Apply OData filter syntax: custom.department eq 'Sales'
5. Combine multiple custom filters with 'and' or 'or' operators
// Correct API query path includes namespace prefix

The correct filter syntax for your query:

GET /api/v1/analytics/processes/instances
  ?$filter=custom.department eq 'Sales'
  &$orderby=startDate desc

Note the $filter parameter (with $ prefix) and custom. namespace - these are required for proper OData query parsing.

3. Schema Metadata Synchronization After registering custom fields, existing process instance data needs to be synchronized with the analytics schema:

Trigger schema reindex: POST /api/v1/analytics/schema/reindex with payload `{“includeHistorical”: true}

Monitor reindex progress: GET /api/v1/analytics/schema/reindex-status

Reindexing time estimate: ~2-3 minutes per 1000 process instances

New process instances (created after registration) are automatically indexed

Complete Implementation Steps:

1. Register all custom fields in analytics schema (via API or UI)

2. Verify registration: GET /api/v1/analytics/schema/fields and confirm custom.department, custom.priority, custom.requestType appear in response

3. Initiate reindex of historical data if you need to query existing instances

4. Update API queries to use correct syntax: `$filter=custom.{fieldName} eq ‘value’

5. Test with simple single-field filter first, then combine multiple filters

Common Pitfalls to Avoid:

Using customFields. instead of custom. namespace (UI terminology vs API path)

Omitting the $ prefix in filter parameter (filter= instead of $filter=)

Querying before reindex completes (check reindex-status endpoint)

Data type mismatches between process definition and schema registration

Case sensitivity in field names (“Department” vs “department”)

Verification Query: After completing registration and reindex, test with:

GET /api/v1/analytics/processes/instances
  ?$filter=custom.department eq 'Sales' and status eq 'Completed'
  &$select=processInstanceId,custom.department,status
  &$top=10

This should return the same 47 instances you see in the UI. If you still get empty results, check the reindex-status endpoint to ensure synchronization completed successfully for all process instances.