Filtering Entities by Workflow State

When working with Stack9 entities that have workflows, you often need to filter lists based on the current workflow step. This guide shows you how to create workflow-aware filters and the helper queries that power them.

Overview

Stack9 entities can have workflows that define different states (steps) an entity can be in. Common use cases for workflow filtering include:

• Showing only entities in specific approval stages
• Creating workflow dashboards that group entities by step
• Filtering by workflow outcome (Success/Failure)
• Building work queues based on workflow state

Workflow State Fields

Every entity with a workflow has these special fields:

• _workflow_current_step: The current workflow step name (string)
• _workflow_outcome: The workflow outcome, typically "Success" or "Failure" (string)

These fields can be used in $where conditions and filters just like any other entity field.

Creating a Workflow Filter

Step 1: Create the Helper Query

First, create a helper query that retrieves the available workflow steps for your entity. This query provides the options for your workflow filter dropdown.

Pattern: /workflow/{entity-key}/stages

The helper query fetches workflow stages from the Stack9 API. Here's the pattern used across different entities:

Example: Game Workflow Steps Query

{
  "key": "get_game_workflowstep",
  "name": "get_game_workflowstep",
  "connector": "stack9_api",
  "queryTemplate": {
    "method": "get",
    "path": "/workflow/game/stages"
  }
}

Example: Permit Workflow Steps Query

{
  "key": "get_permitworkflow_steps",
  "name": "get_permitworkflow_steps",
  "connector": "stack9_api",
  "queryTemplate": {
    "method": "get",
    "path": "/workflow/permit/stages"
  }
}

Example: Subscription Workflow Steps Query

{
  "key": "get_subscription_workflowsteps",
  "name": "get_subscription_workflowsteps",
  "connector": "stack9_api",
  "queryTemplate": {
    "method": "get",
    "path": "/workflow/subscription/stages"
  }
}

Step 2: Add the Workflow Filter to Your Query

Add a filter to your main query that uses the helper query as its data source.

Complete Example: Game List with Workflow Filter

{
  "key": "getgamelist",
  "name": "getGameList",
  "filters": [
    {
      "name": "Workflow",
      "key": "workflow",
      "typeQueryFilter": "array",
      "field": "_workflow_current_step",
      "useSubquery": false,
      "typeFilter": "MultiDropDown",
      "sequence": 1,
      "filterSectionKey": "game_details",
      "dataSource": {
        "type": "query",
        "labelProp": "label",
        "valueProp": "value",
        "query": {
          "name": "get_game_workflowstep",
          "queryKey": "get_game_workflowstep"
        }
      }
    }
  ],
  "filterSections": [
    {
      "name": "Game Details",
      "key": "game_details",
      "sequence": 1
    }
  ],
  "connector": "stack9_api",
  "queryTemplate": {
    "method": "post",
    "path": "/game/search",
    "bodyParams": "{\n  \"$select\": [\n    \"id\",\n    \"name\",\n    \"_workflow_current_step\",\n    \"_workflow_outcome\"\n  ],\n  \"$where\": { \"_is_deleted\": false},\n  \"$sort\": {\"open_dt\": \"desc\"}\n}",
    "queryParams": {
      "page": "{{page}}",
      "limit": "{{limit}}"
    }
  }
}

Understanding the Workflow Filter Configuration

Let's break down the key properties:

Filter Properties

{
  "name": "Workflow",                    // Display name shown in UI
  "key": "workflow",                      // Unique identifier for this filter
  "typeQueryFilter": "array",             // Query filter type for multiple values
  "field": "_workflow_current_step",      // The entity field to filter on
  "useSubquery": false,                   // No subquery needed for direct field
  "typeFilter": "MultiDropDown",          // UI component (multi-select dropdown)
  "sequence": 1,                          // Display order in filter list
  "filterSectionKey": "game_details"      // Groups filter under a section
}

Data Source Configuration

{
  "dataSource": {
    "type": "query",                      // Get options from a query
    "labelProp": "label",                 // Field to use for display text
    "valueProp": "value",                 // Field to use for filter value
    "query": {
      "name": "get_game_workflowstep",      // Query name
      "queryKey": "get_game_workflowstep"   // Query key
    }
  }
}

Important Notes

1. typeQueryFilter: Use "array" for multi-select filters, allowing users to select multiple workflow steps
2. field: Always use "_workflow_current_step" for the current workflow state
3. useSubquery: Set to false since workflow fields are directly on the entity
4. typeFilter: Common choices:
   • "MultiDropDown" - Multi-select dropdown (recommended)
   • "SingleDropDown" - Single selection only
   • "Checkboxes" - Show as checkboxes
   • "RadioButtons" - Show as radio buttons (single select)

API Response Format

The workflow stages endpoint returns an array of workflow steps:

[
  {
    "label": "Draft",
    "value": "Draft"
  },
  {
    "label": "Pending Approval",
    "value": "Pending Approval"
  },
  {
    "label": "Approved",
    "value": "Approved"
  },
  {
    "label": "Published",
    "value": "Published"
  }
]

Each object contains:

• label: The display name shown to users
• value: The actual workflow step name used in the filter

Filtering by Workflow Outcome

You can also filter by workflow outcome (Success/Failure):

{
  "name": "Workflow Status",
  "key": "workflow_outcome",
  "typeQueryFilter": "array",
  "field": "_workflow_outcome",
  "useSubquery": false,
  "typeFilter": "MultiDropDown",
  "sequence": 2,
  "filterSectionKey": "game_details",
  "dataSource": {
    "type": "static",
    "options": [
      {
        "label": "Success",
        "value": "Success"
      },
      {
        "label": "Failure",
        "value": "Failure"
      }
    ]
  }
}

Advanced: Combining Workflow Filters with Other Conditions

You can combine workflow filters with date ranges, text search, and other filters:

{
  "filters": [
    {
      "name": "Workflow",
      "key": "workflow",
      "typeQueryFilter": "array",
      "field": "_workflow_current_step",
      "typeFilter": "MultiDropDown",
      "sequence": 1,
      "dataSource": {
        "type": "query",
        "labelProp": "label",
        "valueProp": "value",
        "query": {
          "name": "get_game_workflowstep",
          "queryKey": "get_game_workflowstep"
        }
      }
    },
    {
      "name": "Open Date",
      "key": "open_dt",
      "typeQueryFilter": "between",
      "field": "open_dt",
      "useSubquery": false,
      "typeFilter": "DateRangeValue",
      "sequence": 2
    }
  ]
}

This allows users to filter games by both workflow step AND open date range.

Workflow Filters in Related Entities

If you need to filter by workflow state of a related entity (using a subquery), set useSubquery: true:

{
  "name": "Permit Workflow",
  "key": "permit_workflow",
  "typeQueryFilter": "array",
  "field": "game_permits.permit._workflow_current_step",
  "useSubquery": true,                   // Required for related entities
  "typeFilter": "MultiDropDown",
  "sequence": 1,
  "filterSectionKey": "related_permits",
  "dataSource": {
    "type": "query",
    "labelProp": "label",
    "valueProp": "value",
    "query": {
      "name": "get_permit_workflowsteps",
      "queryKey": "get_permit_workflowsteps"
    }
  }
}

Notice:

• field uses the full path: "game_permits.permit._workflow_current_step"
• useSubquery is true because we're filtering on a related entity
• The helper query targets the related entity's workflow (permit, not game)

Best Practices

1. Use Consistent Naming

Follow the established naming conventions:

• Helper query key: get{entity}workflowstep(s) (lowercase)
• Helper query name: get{Entity}WorkflowStep(s) (PascalCase)
• Filter key: workflow (lowercase)
• Filter name: Workflow (display name)

2. Position Strategically

Place workflow filters early in the sequence (typically sequence: 1) as they're often the primary way users want to filter entities.

3. Group Related Filters

Use filterSectionKey to group workflow filters logically:

{
  "filterSections": [
    {
      "name": "Game Details",
      "key": "game_details",
      "sequence": 1
    },
    {
      "name": "Related Permits",
      "key": "related_permits",
      "sequence": 2,
      "collapsed": true
    }
  ]
}

4. Include Workflow Fields in Select

Always include workflow fields in your $select clause:

{
  "$select": [
    "id",
    "name",
    "_workflow_current_step",
    "_workflow_outcome"
  ]
}

5. Consider Performance

For large datasets:

• Use appropriate indexes on workflow fields
• Consider using SingleDropDown instead of MultiDropDown if multiple selections aren't needed
• Combine with other filters (like date ranges) to reduce result sets

Common Use Cases

Use Case 1: Work Queue Dashboards

Filter entities by workflow step to create work queues:

{
  "filters": [
    {
      "name": "Workflow",
      "key": "workflow",
      "field": "_workflow_current_step",
      "typeFilter": "MultiDropDown",
      "dataSource": {
        "type": "query",
        "query": {
          "name": "get_game_workflowstep",
          "queryKey": "get_game_workflowstep"
        }
      }
    }
  ]
}

Use Case 2: Approval Queue

Show only entities pending approval:

{
  "$where": {
    "_workflow_current_step": "Pending Approval",
    "_is_deleted": false
  }
}

Use Case 3: Failed Workflow Items

Find all entities with failed workflows:

{
  "$where": {
    "_workflow_outcome": "Failure",
    "_is_deleted": false
  }
}

Troubleshooting

Filter Not Showing Options

Problem: The workflow filter dropdown is empty.

Solutions:

• Verify the helper query is correctly defined in query-library
• Check that the entity has a workflow definition
• Ensure the API path /workflow/{entity-key}/stages is correct
• Verify labelProp and valueProp match the API response fields

Filter Not Applying

Problem: Selecting workflow steps doesn't filter the results.

Solutions:

• Verify field is set to "_workflow_current_step"
• Check typeQueryFilter is "array" for multi-select
• Ensure useSubquery is correctly set (false for direct fields, true for related entities)
• Verify the entity field path is correct

Related Entity Filter Not Working

Problem: Filtering by related entity workflow doesn't work.

Solutions:

• Set useSubquery: true
• Use full field path: "related_entities.entity._workflow_current_step"
• Ensure the related entity is included in $withRelated
• Verify the helper query targets the correct entity type

Summary

To create a workflow filter for Stack9 entities:

1. Create a helper query that calls /workflow/{entity-key}/stages

   • Use naming convention: get_{entity}_workflowstep(s)

2. Add the filter to your main query

   • Field: "_workflow_current_step"
   • TypeQueryFilter: "array"
   • TypeFilter: "MultiDropDown"
   • DataSource: Reference your helper query

3. Configure properly for your use case

   • Use useSubquery: false for direct entity fields
   • Use useSubquery: true for related entity fields
   • Position strategically with sequence
   • Group logically with filterSectionKey

Workflow filters provide a powerful way to organize and manage entities through their lifecycle, making it easy for users to focus on entities at specific stages of the workflow process.