Work Items

Create work item with embedded task payload

post

Creates a work item (GitHub Issue or Azure DevOps Work Item) with an embedded task payload for IssueOps automation.

How It Works

Provider Detection: The provider is determined by the project's configuration.workItems.provider setting
Authentication: The user's Personal Access Token (PAT) is used from the authToken field (required)
Payload Embedding: The task payload is embedded in the work item body for later extraction by automation

Prerequisites

1. Project Configuration

The project must have workItems.provider configured:

# Set via CLI
sfp server project update -r flxbl-io/sf-core \
  -p configuration.workItems \
  -v '{"provider": "azure-devops"}'

# Or via API
PATCH /projects/flxbl-io%2Fsf-core
{
  "property": "configuration.workItems",
  "value": { "provider": "azure-devops" }
}

2. Authentication - User PAT Required

The authToken field is mandatory. Work items are created using the user's Personal Access Token (PAT) to ensure proper attribution and audit trail.

Why PAT is Required:

Work items show the actual user as the creator
Clear audit trail of who initiated each request
Proper attribution for compliance and tracking

PAT Requirements:

GitHub: Token with repo (private) or public_repo (public) scope
Azure DevOps: PAT with "Work Items: Read & Write" scope

Note: Server-stored credentials (service principal or stored PAT) are not used for work item creation to ensure proper user attribution.

Valid Task Types

Task Type

Description

request-elevated-privileges

Request temporary elevated access

request-freeze-users

Freeze users in an environment

request-unfreeze-users

Unfreeze users in an environment

request-sandbox-create

Create a new sandbox

request-sandbox-refresh

Refresh sandbox from source

request-sandbox-delete

Delete a sandbox

install-packages

Install managed/unlocked packages

install-artifacts

Install build artifacts

create-patch-branch

Create a patch branch

run-apex-tests

Execute Apex tests

Flow Triggering

When triggerFlow: true is set, the endpoint will:

Create the work item as usual
Trigger the associated Windmill flow with the payload
Pass the created work item as the callback destination for flow notifications
Return both work item details and flow trigger results

This enables end-to-end IssueOps automation where creating a work item immediately kicks off the associated workflow.

Payload Embedding

The payload is embedded in the work item body in a format that can be extracted by automation:

GitHub: Embedded as HTML comment 
Azure DevOps: Embedded in collapsible section (Azure strips HTML comments)

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

projectIdentifierstringRequired

Project identifier as registered in sfp server. Must match the project's workItems.provider configuration.

Example: flxbl-io/sf-core

titlestringRequired

Work item title. Use a descriptive prefix like [Request] for IssueOps workflows.

Example: [Request] Provision Scratch Org for Development

bodystringOptional

Work item body/description. The task payload will be appended to this.

Example: Please provision a new scratch org for the development team. Duration: 7 days

payloadobjectRequired

Task payload with id matching a registered task type. Valid types:

request-elevated-privileges - Request temporary elevated access
request-freeze-users - Freeze users in an environment
request-unfreeze-users - Unfreeze users
request-sandbox-create - Create a new sandbox
request-sandbox-refresh - Refresh sandbox from source
request-sandbox-delete - Delete a sandbox
install-packages - Install managed/unlocked packages
install-artifacts - Install build artifacts
create-patch-branch - Create a patch branch
run-apex-tests - Execute Apex tests
request-a-release-to-release-envs - Request release deployment to environments (orchestrator)
execute-release - Execute release to a single environment

Example: {"id":"request-sandbox-create","env":"dev","duration":"7"}

authTokenstringRequired

Personal Access Token (PAT) for authentication. Required for proper user attribution.

Why PAT is Required: Work items are created on behalf of the actual user for proper audit trail. When using a PAT, the work item shows the user as the creator, making it clear who initiated the request. Using server-stored credentials would attribute all work items to the integration service account.

GitHub: Token with repo (private) or public_repo (public) scope Azure DevOps: PAT with "Work Items: Read & Write" scope

Example: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

labelsstring[]Optional

Labels/tags to apply to the work item. Used for filtering and automation triggers.

Example: ["issueops","sandbox","automation"]

assigneesstring[]Optional

Assignees for the work item.

GitHub: Array of GitHub usernames Azure DevOps: Array of email addresses

Example: ["john-doe"]

milestonestringOptional

GitHub only: Milestone number or title to associate with the issue

Example: Sprint 23

workItemTypestringOptional

Azure DevOps only: Work item type. Common types depend on the process template:

Basic: Issue, Epic, Task
Agile: Bug, User Story, Task, Epic
Scrum: Bug, Product Backlog Item, Task, Epic

Example: Task

areaPathstringOptional

Azure DevOps only: Area path for categorization. Use backslashes to separate hierarchy.

Example: sf-core\Team Alpha

iterationPathstringOptional

Azure DevOps only: Iteration path for sprint assignment. Use backslashes to separate hierarchy.

Example: sf-core\Sprint 23

prioritynumber · min: 1 · max: 4Optional

Azure DevOps only: Priority level (1 = highest, 4 = lowest)

Example: 2

organizationUrlstringOptional

Azure DevOps only: Organization URL.

Optional if configured in project settings. The server first checks the project's configuration.workItems.organizationUrl. Only provide this to override the project configuration or if not configured at the project level.

Configure at project level via:

PATCH /projects/{identifier}
{ "property": "configuration.workItems", "value": { "organizationUrl": "https://dev.azure.com/org", "project": "proj" } }

Example: https://dev.azure.com/flxbl-io

projectstringOptional

Azure DevOps only: Project name within the organization.

Optional if configured in project settings. The server first checks the project's configuration.workItems.project. Only provide this to override the project configuration or if not configured at the project level.

Example: sf-core

triggerFlowbooleanOptional

Controls whether to trigger the Windmill flow immediately after creating the work item.

When to set triggerFlow: true:

You want to trigger the flow immediately without waiting for webhook events
The work item is being created programmatically (e.g., from a UI or automation)
You don't have IssueOps webhooks configured for label-based triggering

When to set triggerFlow: false (default):

You're using the IssueOps pattern where GitHub/Azure DevOps webhooks trigger flows based on labels
You want manual control over when the flow starts (e.g., after review)
The work item is for tracking purposes only

When true:

The flow is triggered synchronously after work item creation
The work item becomes the callback destination for flow notifications
The response includes flowExecution details with the execution ID

When false (default):

Only the work item is created
Flow must be triggered separately (via webhook, label, or manual API call)

Default: falseExample: true

Responses

201

Work item created successfully

application/json

400

Invalid request - bad task type or missing required fields

application/json

401

Authentication failed - invalid or expired token

application/json

403

Forbidden - Requires role: owner, application

404

Project not found

application/json

post

/sfp/api/work-items/with-payload

POST /sfp/api/work-items/with-payload HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 320

{
  "projectIdentifier": "flxbl-io/sf-core",
  "title": "[Request] Create Developer Sandbox",
  "body": "Requesting a new developer sandbox for sprint work.",
  "payload": {
    "id": "request-sandbox-create",
    "env": "dev",
    "duration": "14",
    "sourceSandbox": "production"
  },
  "labels": [
    "sandbox",
    "automation"
  ],
  "authToken": "your-personal-access-token"
}

{
  "id": "12345",
  "key": "42",
  "url": "https://github.com/flxbl-io/sf-core/issues/42",
  "platform": "github",
  "createdAt": "2025-01-20T12:00:00.000Z",
  "flowExecution": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "taskType": "request-a-release-to-release-envs",
    "status": "running",
    "triggeredAt": "2025-01-20T12:00:01.000Z"
  }
}

Update a work item

patch

Update a work item on the specified platform.

Supported Platforms

Platform

Requirements

github

Requires projectIdentifier (owner/repo format)

azure-devops

Uses configured integration credentials

jira

Not yet implemented

Available Updates

title: Update the work item title
body: Update the description/body
state: Change the state (e.g., "open", "closed" for GitHub)
labels: Set labels/tags
assignees: Set assignees

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

platformstring · enumRequired

Platform where the work item exists

Possible values:

idstringRequired

Work item ID or key

Responses

200

Work item updated successfully

No content

400

Invalid request or platform not supported

403

Forbidden - Requires role: owner, application

404

Work item not found

patch

/sfp/api/work-items/{platform}/{id}

PATCH /sfp/api/work-items/{platform}/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Close a work item

post

Close a work item on the specified platform.

Supported Platforms

Platform

Close Behavior

github

Sets issue state to "closed". Optional comment.

azure-devops

Sets state to "Closed" with optional reason.

jira

Not yet implemented

Options

comment: Add a comment when closing
reason: Close reason (Azure DevOps only: "Completed", "Resolved", "Removed", etc.)

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

platformstring · enumRequired

Platform where the work item exists

Possible values:

idstringRequired

Work item ID or key

Responses

200

Work item closed successfully

No content

400

Invalid request or platform not supported

403

Forbidden - Requires role: owner, application

404

Work item not found

post

/sfp/api/work-items/{platform}/{id}/close

POST /sfp/api/work-items/{platform}/{id}/close HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get work item by ID

get

Fetch a work item by its ID. The platform is automatically determined from the project's configuration.workItems.provider setting.

ID Formats by Platform

Platform

ID Format

Example

jira

Project key + number

DP-6, PROJ-123

github

Issue number

42, 123

azure-devops

Work item ID

456, 789

Prerequisites

The project must have workItems.provider configured:

sfp server project update -r owner/repo \
  -p configuration.workItems \
  -v '{"provider": "jira"}'

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Work item ID or key

Example: {"value":"DP-6","summary":"Jira issue key"}

Query parameters

projectIdentifierstringRequired

Project identifier (e.g., owner/repo)

Example: flxbl-io/sf-core

Responses

200

Work item retrieved successfully

application/json

ResponseanyExample:

{"id":"10042","key":"DP-6","title":"Implement user authentication","description":"Add OAuth 2.0 authentication flow","type":"story","status":"In Progress","priority":"High","assignee":{"id":"user123","name":"John Doe","email":"[email protected]","avatarUrl":"https://example.com/avatar.png"},"reporter":{"id":"user456","name":"Jane Smith","email":"[email protected]"},"labels":["backend","security"],"createdAt":"2025-01-10T08:00:00.000Z","updatedAt":"2025-01-11T14:30:00.000Z","platform":"jira","url":"https://flxbl-demo.atlassian.net/browse/DP-6","parent":{"id":"10040","key":"DP-1","title":"Authentication Epic"},"customFields":{"projectKey":"DP","projectName":"Demo Project","issueTypeId":"10001","statusId":"3"}}

403

Forbidden - Requires role: owner, member, application

404

Work item or project not found

application/json

get

/sfp/api/work-items/{id}

GET /sfp/api/work-items/{id}?projectIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "10042",
  "key": "DP-6",
  "title": "Implement user authentication",
  "description": "Add OAuth 2.0 authentication flow",
  "type": "story",
  "status": "In Progress",
  "priority": "High",
  "assignee": {
    "id": "user123",
    "name": "John Doe",
    "email": "[email protected]",
    "avatarUrl": "https://example.com/avatar.png"
  },
  "reporter": {
    "id": "user456",
    "name": "Jane Smith",
    "email": "[email protected]"
  },
  "labels": [
    "backend",
    "security"
  ],
  "createdAt": "2025-01-10T08:00:00.000Z",
  "updatedAt": "2025-01-11T14:30:00.000Z",
  "platform": "jira",
  "url": "https://flxbl-demo.atlassian.net/browse/DP-6",
  "parent": {
    "id": "10040",
    "key": "DP-1",
    "title": "Authentication Epic"
  },
  "customFields": {
    "projectKey": "DP",
    "projectName": "Demo Project",
    "issueTypeId": "10001",
    "statusId": "3"
  }
}

List work items

get

List work items with optional filters. The platform is automatically determined from the project's configuration.workItems.provider setting.

Prerequisites

The project must have workItems.provider configured. Optionally configure boards to filter by specific boards/projects:

# Configure provider and boards (Jira project keys)
sfp server project update -r owner/repo \
  -p configuration.workItems \
  -v '{"provider": "jira", "boards": ["DP", "PROJ"]}'

# Configure provider and boards (Azure DevOps area paths)
sfp server project update -r owner/repo \
  -p configuration.workItems \
  -v '{"provider": "azure-devops", "boards": ["MyProject\\Team1"]}'

Filter Examples

# List work items (uses boards from project config)
GET /work-items?projectIdentifier=owner/repo

# Filter by status
GET /work-items?projectIdentifier=owner/repo&status=In Progress

# Filter by assignee
GET /work-items?projectIdentifier=owner/repo&assignee=john.doe

# Filter by type with limit
GET /work-items?projectIdentifier=owner/repo&type=bug&maxResults=10

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

projectIdentifierstringRequired

Project identifier (e.g., owner/repo)

Example: flxbl-io/sf-core

statusstringOptional

Filter by work item status (e.g., "To Do", "In Progress", "Done")

Example: In Progress

assigneestringOptional

Filter by assignee username or email

Example: john.doe

typestringOptional

Filter by work item type (e.g., "bug", "story", "task", "epic")

Example: story

maxResultsnumberOptional

Maximum number of results to return (1-100, default: 50)

Example: 50

Responses

200

Work items retrieved successfully

application/json

403

Forbidden - Requires role: owner, member, application

get

/sfp/api/work-items

GET /sfp/api/work-items?projectIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "10042",
    "key": "DP-6",
    "title": "Implement user authentication",
    "type": "story",
    "status": "In Progress",
    "priority": "High",
    "platform": "jira",
    "url": "https://example.atlassian.net/browse/DP-6"
  },
  {
    "id": "10043",
    "key": "DP-7",
    "title": "Add password reset functionality",
    "type": "story",
    "status": "To Do",
    "priority": "Medium",
    "platform": "jira",
    "url": "https://example.atlassian.net/browse/DP-7"
  }
]

Last updated 6 hours ago

Good morning

hashtagCreate work item with embedded task payload

hashtagHow It Works

hashtagPrerequisites

hashtag1. Project Configuration

hashtag2. Authentication - User PAT Required

hashtagValid Task Types

hashtagFlow Triggering

hashtagPayload Embedding

hashtagUpdate a work item

hashtagSupported Platforms

hashtagAvailable Updates

hashtagClose a work item

hashtagSupported Platforms

hashtagOptions

hashtagGet work item by ID

hashtagID Formats by Platform

hashtagPrerequisites

hashtagList work items

hashtagPrerequisites

hashtagFilter Examples

Create work item with embedded task payload

How It Works

Prerequisites

1. Project Configuration

2. Authentication - User PAT Required

Valid Task Types

Flow Triggering

Payload Embedding

Update a work item

Supported Platforms

Available Updates

Close a work item

Supported Platforms

Options

Get work item by ID

ID Formats by Platform

Prerequisites

List work items

Prerequisites

Filter Examples