Quick Start Guide (Workflow)

Last updated: April 2026

Welcome to the Agglestone Workflow Management Service integration guide. This quick start shows the core request flow for creating a workflow definition, creating a workflow item, updating it, and moving it through a transition.

Getting Started

The Workflow Management Service is available at your tenant-specific deployment URL and uses tenant-scoped REST endpoints:

https://workflow.agglestone.com/tenant/{tenantId}/v1/...

Replace {tenantId} in the examples below with your own tenant ID.

Authentication

Most integrations call the API with a bearer token:

Authorization: Bearer {token}

Administrative scenarios may also support API-key based access, depending on your tenant configuration. If you plan to manage workflow definitions or data types from a server-to-server integration, check whether API-key access is enabled for your tenant.

1. Create a Workflow Definition

Create a workflow definition first. This is the template that future workflow items will follow.

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

{
  "id": "sample-registration",
  "name": "Sample Registration",
  "description": "Tracks a sample from registration to completion",
  "stages": [
    {
      "id": "pending",
      "name": "Pending"
    },
    {
      "id": "received",
      "name": "Received"
    }
  ],
  "transitions": [
    {
      "id": "pending-to-received",
      "fromStage": "pending",
      "toStage": "received",
      "name": "Receive sample"
    }
  ],
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "sampleId": { "type": "string" },
      "sampleType": { "type": "string" },
      "receivedDate": { "type": "string", "format": "date-time" }
    }
  }
}

2. Create a Workflow Item

Once the definition exists, create a workflow item under that definition.

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

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

Successful creation returns 201 Created and an object containing the new item ID.

3. Retrieve the Item

Use the returned item ID to fetch the current state of the workflow item.

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

4. Update Item Fields

Update fields without changing the current stage.

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

{
  "fields": {
    "receivedDate": "2026-04-02T10:30:00Z"
  }
}

5. Transition the Item

When the item is ready to move forward, call the transition endpoint.

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

{
  "transitionId": "pending-to-received",
  "reason": "Sample arrived at the lab"
}

6. List Workflow Items

Use the list endpoint to retrieve items for a workflow definition. Pagination is supported across list endpoints in the service.

GET /tenant/{tenantId}/v1/Workflows/sample-registration/Items?pageNumber=1&pageSize=20
Authorization: Bearer {token}

Common Response Pattern

Paginated endpoints return a response in this shape:

{
  "data": [],
  "pageNumber": 1,
  "pageSize": 20,
  "totalRecords": 0
}

Agglestone Labs