canonical: https://jentic.com/apis/ibm.com/business-automation-workflow-api

# IBM Business Automation Workflow API

IBM Business Automation Workflow (BAW) is the workflow and case management engine in IBM Cloud Pak for Business Automation, used to coordinate long-running business processes such as loan approvals, claims handling, and onboarding. The REST API exposes process instances, human tasks, and case folders so external systems and agents can start, suspend, claim, reassign, and complete work without going through the BAW web client. It targets enterprise process owners who need to embed BAW operations inside larger automations or expose them to AI agents.

## For AI agents

Start, query, and act on IBM BAW process instances, human tasks, and cases - claim, reassign, suspend, resume, and complete work programmatically.

## Scope

Does not handle business-rule execution, BPMN authoring, or low-code app design - use for runtime BAW process, task, and case operations only.

## Capabilities

- Start a new process instance from a BPMN definition via /processes
- Suspend or resume a running process instance via `/process/{instanceId}/suspend` and /resume
- Claim a human task on behalf of a user via `/task/{taskId}/claim`
- Reassign a task to another user or group via `/task/{taskId}/reassign`
- Open, update, and search case folders via /cases and `/case/{caseId}`
- Run BAW search queries against processes and tasks via `/search/query`

## Use cases

### Process Instance Orchestration

Trigger BAW processes from external systems - for example, kick off an onboarding workflow when a CRM deal closes, or suspend a process when an exception is raised in another system. The API supports starting, suspending, resuming, and inspecting process instances by ID, so an agent can orchestrate long-running workflows without operating the BAW Process Portal.

Example prompt: Start a process named LoanApproval with the applicant ID and loan amount, then poll `/process/{instanceId}` until status is Completed.

### Human Task Routing

Route, claim, and reassign human tasks created by BAW processes. An agent can list outstanding tasks for a queue, claim a task on behalf of a worker, or reassign overdue work to a backup approver. This makes it possible to integrate BAW work into a unified inbox or a Slack-driven approval flow.

Example prompt: Find the oldest unclaimed task in the credit-review queue, claim it for user jdoe, then mark it complete with the approval decision.

### Case Management Integration

Open and update BAW case folders from external systems so a single case can carry documents, tasks, and process activity from CRM, ECM, and email channels. The API exposes /cases for create and list operations and `/case/{caseId}` for read and update, letting an agent maintain case state without manual data entry in the BAW UI.

Example prompt: Create a case of type ClaimsIntake with the policy number and claimant details, then attach a list of related task IDs.

### AI Agent Workflow Operations

An AI agent monitors BAW for stuck or overdue tasks and takes corrective action - reassigning tasks, suspending processes pending input, or escalating cases. Through Jentic, the agent searches by intent, loads the BAW operation schema, and executes calls against the BAW REST endpoint without owning BAW credentials directly. Typical agent integration is under an hour.

Example prompt: Search Jentic for 'reassign a BAW task', load the `/task/{taskId}/reassign` schema, and reassign every task older than 48 hours to the backup approver.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/processes` | List process instances |
| GET | `/process/{instanceId}` | Get a process instance by ID |
| POST | `/process/{instanceId}/suspend` | Suspend a running process |
| POST | `/process/{instanceId}/resume` | Resume a suspended process |
| POST | `/task/{taskId}/claim` | Claim a human task |
| POST | `/task/{taskId}/reassign` | Reassign a task to another user |
| GET | `/cases` | List case folders |
| POST | `/search/query` | Run a BAW search query |

## Key resources

- **Process Instances** — Start, suspend, resume, and inspect process instances
- **Tasks** — Claim, release, and reassign human tasks
- **Cases** — Create, read, and update case folders
- **Search** — Run saved or ad-hoc BAW queries

## Why Jentic

- **Setup:** Wiring the IBM Business Automation Workflow API by hand means configuring basic auth against your BAW server host and port and mapping its runtime process and task routes yourself. Through Jentic you install once, import the IBM Business Automation Workflow API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** BAW puts the process instance and task ids in the URL path (`/process/{instanceId}`, `/task/{taskId}`), so a rule can pin your agent to reading and searching processes and cases. You choose the operations it may call, so state changes like suspending a process instance or reassigning a task are not included unless you add them.
- **Credential handling:** Your BAW credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list running BAW processes' or 'claim a workflow task', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **IBM Operational Decision Manager API** — ODM executes business rules; BAW orchestrates the long-running processes that call those rules.
- **IBM webMethods Integration API** — webMethods integrates BAW with external SaaS systems via flow services and connectors.
- **Camunda API** — Camunda is a developer-focused BPMN/DMN engine; BAW is the IBM enterprise workflow and case platform.

## FAQ

### What authentication does the IBM Business Automation Workflow API use?

The BAW REST API uses HTTP basic authentication against a BAW user account. Through Jentic, those BAW credentials are stored in your Jentic One instance and exposed to agents only through scoped Jentic credentials - the basic auth header never appears in the agent's prompt context.

### Can I claim and reassign human tasks with the IBM BAW API?

Yes. Use POST `/task/{taskId}/claim` to claim a task on behalf of a user, POST `/task/{taskId}/release` to release it back to the queue, and POST `/task/{taskId}/reassign` to move it to another user or group. These match the actions available in the BAW Process Portal task list.

### How do I start a BAW process through Jentic?

Search Jentic for 'start a BAW process', load the /processes POST schema, and execute the call with the process definition name and the input variables. Use pip install jentic and the async search, load, and execute pattern to drive the call from Python.

### Does the IBM BAW API support case management?

Yes. The /cases and `/case/{caseId}` endpoints cover creating, listing, retrieving, and updating case folders, which is the BAW case management surface introduced as part of the Cloud Pak for Business Automation suite.

### What are the rate limits for the IBM BAW API?

BAW does not publish a fixed public rate limit; throughput depends on the deployment topology, the configured thread pool, and the underlying database. Treat 429 and 503 responses as backpressure signals and retry with exponential backoff.

### How do I search across BAW processes and tasks?

POST a query to `/search/query` with the BAW saved-search ID or an ad-hoc filter expression. The endpoint returns matching processes, tasks, or cases depending on the search definition, which is useful for building queue dashboards over the API.

### Can I limit what my agent is allowed to do with the IBM Business Automation Workflow API?

Yes. Because you run Jentic One yourself, you decide which BAW operations the agent may call, and your own rules govern the stored credentials and the endpoints it reaches. Since BAW puts the process and task IDs in the URL path, such as `/process/{instanceId}` and `/task/{taskId}`, you can pin the agent to read-only work like listing processes and running `/search/query` while withholding state changes. Operations such as suspending a process instance, claiming a task, or reassigning work stay off limits unless you explicitly grant them.