Home Documentation Workflow Management Service Workflow Integration Guides Workflow Items

Workflow Items

Last updated: April 2026

Workflow items are the live records that move through a workflow definition. This guide covers the main endpoints used to create, retrieve, update, transition, roll back, and query those items.

Base Endpoint

All workflow item endpoints are located at:

/tenant/{tenantId}/v1/Workflows/{workflowDefinitionId}/Items

Creating a Workflow Item

Use POST /tenant/{tenantId}/v1/Workflows/{workflowDefinitionId}/Items to create a new item.

POST /tenant/{tenantId}/v1/Workflows/sample-registration/Items
Authorization: Bearer {token}
Content-Type: application/json

{
  "fields": {
    "sampleId": "SAMPLE-1001",
    "sampleType": "Food",
    "receivedDate": null
  }
}

Successful creation returns 201 Created with a response containing the new item ID.

Listing Workflow Items

Use GET /tenant/{tenantId}/v1/Workflows/{workflowDefinitionId}/Items to retrieve a paginated list of items.

Pagination and Sorting

  • pageNumber: Default 1
  • pageSize: Default 20, maximum 100
  • sortField: Supports a single field or a comma-separated list
  • sortOrder: ASC or DESC, also supports comma-separated values
GET /tenant/{tenantId}/v1/Workflows/sample-registration/Items?pageNumber=1&pageSize=20&sortField=updatedAt&sortOrder=DESC
Authorization: Bearer {token}

Filtering

The filter query parameter accepts a URL-encoded JSON object. This lets you filter on stage and field values.

GET /tenant/{tenantId}/v1/Workflows/sample-registration/Items?filter=%7B%22currentStage%22%3A%22pending%22%2C%22sampleType%22%3A%22Food%22%7D
Authorization: Bearer {token}

Decoded, the filter above is:

{
  "currentStage": "pending",
  "sampleType": "Food"
}

The service also supports richer filter expressions, including:

  • Exact matches
  • Multiple currentStage values
  • Boolean combinations with $and and $or
  • Comparison operators such as $gt, $gte, $lt, $lte
  • Case-insensitive substring matching with $contains

Retrieving a Single Item

Use GET /tenant/{tenantId}/v1/Workflows/{workflowDefinitionId}/Items/{id} to fetch an item by ID.

GET /tenant/{tenantId}/v1/Workflows/sample-registration/Items/{id}
Authorization: Bearer {token}

Updating Item Fields

Use PUT /tenant/{tenantId}/v1/Workflows/{workflowDefinitionId}/Items/{id}/fields to update fields without changing stage.

PUT /tenant/{tenantId}/v1/Workflows/sample-registration/Items/{id}/fields
Authorization: Bearer {token}
Content-Type: application/json

{
  "fields": {
    "receivedDate": "2026-04-02T10:30:00Z",
    "notes": "Received in good condition"
  }
}

Update Modes

For complex fields, you can optionally control how updates are applied:

  • Arrays can usually be appended to or replaced
  • Objects can usually be merged or replaced
PUT /tenant/{tenantId}/v1/Workflows/sample-registration/Items/{id}/fields
Authorization: Bearer {token}
Content-Type: application/json

{
  "fields": {
    "measurements": [
      { "name": "temperature", "value": "5C" }
    ]
  },
  "updateModes": {
    "measurements": "replace"
  }
}

Transitioning an Item

Use POST /tenant/{tenantId}/v1/Workflows/{workflowDefinitionId}/Items/{id}/transition to move an item to its next stage.

POST /tenant/{tenantId}/v1/Workflows/sample-registration/Items/{id}/transition
Authorization: Bearer {token}
Content-Type: application/json

{
  "transitionId": "pending-to-received",
  "fields": {
    "receivedDate": "2026-04-02T10:30:00Z"
  },
  "reason": "Sample received by operations"
}

Rolling Back an Item

Use POST /tenant/{tenantId}/v1/Workflows/{workflowDefinitionId}/Items/{id}/rollback to move an item back to an earlier state when your process allows it.

You can target either a stage or a specific history entry.

POST /tenant/{tenantId}/v1/Workflows/sample-registration/Items/{id}/rollback
Authorization: Bearer {token}
Content-Type: application/json

{
  "targetStage": "pending"
}

{
  "targetHistoryId": "history-entry-id"
}

Getting Item History

Use GET /tenant/{tenantId}/v1/Workflows/{workflowDefinitionId}/Items/{id}/history to retrieve the item’s transition history.

GET /tenant/{tenantId}/v1/Workflows/sample-registration/Items/{id}/history
Authorization: Bearer {token}

Delta Change Endpoints

Administrative users can also inspect detailed change deltas for a workflow item:

  • GET /tenant/{tenantId}/v1/Workflows/{workflowDefinitionId}/Items/{id}/deltas
  • GET /tenant/{tenantId}/v1/Workflows/{workflowDefinitionId}/Items/{id}/deltas/{deltaId}

These endpoints are useful for audit-style experiences and advanced diagnostics.

Bulk Operations

Use POST /tenant/{tenantId}/v1/Workflows/{workflowDefinitionId}/Items/bulk to submit multiple inserts, updates, transitions, and deletes in one request.

POST /tenant/{tenantId}/v1/Workflows/sample-registration/Items/bulk
Authorization: Bearer {token}
Content-Type: application/json

{
  "operations": [
    {
      "fields": {
        "sampleId": "SAMPLE-2001",
        "sampleType": "Water"
      }
    },
    {
      "id": "existing-item-id",
      "fields": {
        "sampleType": "Food"
      },
      "transitionId": "pending-to-received",
      "transitionReason": "Bulk receive"
    }
  ],
  "deletes": [
    {
      "id": "item-to-delete"
    }
  ]
}

The response returns per-operation results along with total, successful, and failed counts.

Grouped Queries

Use GET /tenant/{tenantId}/v1/Workflows/{workflowDefinitionId}/Items/grouped when you want grouped counts instead of individual items.

The filter query parameter must include a groupBy array.

GET /tenant/{tenantId}/v1/Workflows/sample-registration/Items/grouped?filter=%7B%22groupBy%22%3A%5B%22currentStage%22%5D%7D
Authorization: Bearer {token}

Decoded:

{
  "groupBy": ["currentStage"]
}

This endpoint is useful for summary widgets, dashboards, and reporting views.

Typical Status Codes

  • 200 OK for reads, updates, transitions, rollback, and successful bulk requests
  • 201 Created when a new workflow item is created
  • 400 Bad Request when validation fails or the filter format is invalid
  • 401 Unauthorized when authentication is missing or invalid
  • 403 Forbidden when the caller does not have permission for the requested operation
  • 404 Not Found when the workflow definition, item, or related resource does not exist
  • 422 Unprocessable Entity when a bulk request is valid but all submitted operations fail business validation

📚 API Documentation: Visit https://workflow.agglestone.com/swagger for full schemas and optional properties.