Workflow Definitions

Workflow definitions are the templates that describe how a process behaves. They define stages, transitions, field rules, validation requirements, and the shape of the workflow data itself.

Authentication Requirements

Workflow definition management is typically an administrative operation. In most integrations, you should call these endpoints with a bearer token that represents an administrator for the tenant.

Base Endpoint

All workflow definition endpoints are located at:

/tenant/{tenantId}/v1/Workflows

Creating a Workflow Definition

Use POST /tenant/{tenantId}/v1/Workflows to create a new workflow definition.

curl -X POST "https://workflow.agglestone.com/tenant/your-tenant-id/v1/Workflows" 
  -H "Authorization: Bearer YOUR_TOKEN" 
  -H "Content-Type: application/json" 
  -d @sample-workflow-definition.json

const response = await fetch(
  `https://workflow.agglestone.com/tenant/${tenantId}/v1/Workflows`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(workflowDefinition)
  }
);

const createdDefinition = await response.json();

The response returns the created workflow definition, including its current version.

Listing Workflow Definitions

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

Query Parameters

• pageNumber: Page number, default 1
• pageSize: Page size, default 20, maximum 100
• activeOnly: When true, returns only active definitions. Default is true

GET /tenant/{tenantId}/v1/Workflows?pageNumber=1&pageSize=20&activeOnly=true
Authorization: Bearer {token}

The response contains lightweight list items with fields such as id, name, description, isActive, and version.

Retrieving a Single Workflow Definition

Use GET /tenant/{tenantId}/v1/Workflows/{id} to fetch the current live definition by ID.

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

Retrieving Definition Versions

The service supports definition versioning. Use these endpoints when you need to inspect version history:

• GET /tenant/{tenantId}/v1/Workflows/{id}/versions
• GET /tenant/{tenantId}/v1/Workflows/{id}/versions/{version}

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

GET /tenant/{tenantId}/v1/Workflows/sample-registration/versions/2
Authorization: Bearer {token}

Updating a Workflow Definition

Use PUT /tenant/{tenantId}/v1/Workflows/{id} to replace the current definition with an updated version.

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

{
  "id": "sample-registration",
  "name": "Sample Registration",
  "description": "Updated description",
  "stages": [],
  "transitions": []
}

When an update is accepted, the service returns the updated workflow definition.

Deleting a Workflow Definition

Use DELETE /tenant/{tenantId}/v1/Workflows/{id} to remove a definition from active use.

DELETE /tenant/{tenantId}/v1/Workflows/sample-registration
Authorization: Bearer {token}

Successful deletion returns 204 No Content.

Best Practices

• Use stable definition IDs because workflow items are created under a specific definition ID
• Treat workflow definition updates as controlled changes and validate them in a lower environment first
• Keep field names consistent because item queries, filters, and grouped reports often depend on them
• Use the Swagger UI to inspect the exact schema for advanced workflow definition features

📚 API Documentation: For full request and response schemas, visit https://workflow.agglestone.com/swagger.