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

BPM AgilePoint
, , , , , , , ,
1

Filtering by custom fields in process analytics API queries returns empty results even though the custom fields contain data and work fine in the AgilePoint UI reports.

We’ve added several custom fields to our process instances (department, priority, requestType) and can see the data populated correctly in the process analytics dashboard. However, when we try to filter by these fields using the REST API, we get zero results.


GET /api/v1/analytics/processes/instances
  ?filter=customFields.department eq 'Sales'
Response: {instances: [], totalCount: 0}

Same query in UI: Returns 47 instances correctly

Standard fields (status, startDate, processName) work perfectly in API filters. It’s only the custom fields that fail. The filter syntax appears correct based on the documentation, but I’m wondering if there’s something special about how custom field metadata needs to be registered or referenced in API queries.

Has anyone successfully filtered analytics API results using custom fields? Is there a different syntax or schema reference required?

2

I ran into this exact issue last month. The problem is that custom fields need to be explicitly registered in the analytics schema before they’re available for API filtering. Just adding them to process instances isn’t enough - there’s a separate registration step in the process analytics configuration.

Check the analytics schema settings to see if your custom fields are listed there. If not, you’ll need to register them with proper data types.

3

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.

4

You can register custom fields either through the UI or via API. The registration process involves defining the field name, data type, and indexing options. Once registered, you’ll need to trigger a reindex of existing process instances for the historical data to become queryable.

The reindexing can take a while depending on how many process instances you have. For our system with about 10K instances, it took roughly 20-30 minutes to complete.

5

Thanks! I found the analytics schema configuration section. I can see the standard fields listed, but the custom fields aren’t there. Is there a specific API endpoint to register custom fields in the analytics schema, or does this have to be done through the UI? Also, do existing process instances automatically get indexed after registration, or only new ones?