canonical: https://jentic.com/apis/oracle.com/oracle-bpm-suite-api

# Oracle BPM Suite REST API

The Oracle BPM Suite REST API exposes process definitions, running process instances, and human tasks in Oracle BPM Suite 12c so that external systems can drive workflows without using the SOA suite's web console. It supports starting and inspecting process instances, suspending and resuming them, and acting on human tasks including comments and attachments. The surface targets enterprise teams that already run Oracle BPM and want to integrate it with self-service portals, RPA bots, or AI agents.

## For AI agents

Start, inspect, suspend, and resume Oracle BPM 12c process instances and act on human tasks, attachments, and comments over REST.

## Scope

Does not handle BPMN process modelling, SOA composite deployment, or BAM analytics - use for runtime process and human task operations only.

## Capabilities

- List process definitions deployed to Oracle BPM Suite
- Start a new process instance from a deployed process definition
- Suspend or resume a running BPM process instance
- Retrieve the human task list for the authenticated user
- Add comments and attachments to an in-flight human task
- Inspect process instance status and audit trail

## Use cases

### Self-Service Process Initiation

Let a customer-facing portal kick off long-running Oracle BPM processes - credit applications, supplier onboarding, claims intake - without exposing the BPM web console. The REST API accepts a process definition id and a payload, returning the new process instance id that the portal can track.

Example prompt: POST `/4.0/processes/{processDefId}/instances` with the application payload and store the returned instance id

### Human Task Triage in External Tools

Surface Oracle BPM human tasks inside Microsoft Teams, Slack, or a custom inbox so approvers act on them without logging into the BPM workspace. The `/4.0/tasks` endpoints return tasks for the authenticated user, and the task action endpoints let the integration approve or update them in place.

Example prompt: GET `/4.0/tasks` for the user, post the list to the chat tool, then POST a task action when the user clicks approve

### Process Instance Pause for Investigation

Operations and audit teams can pause a running BPM process instance while they investigate a discrepancy - a misrouted invoice, a flagged customer, a contract under review - and resume it once the issue is resolved. The suspend and resume endpoints work directly against the instance id.

Example prompt: POST `/4.0/processes/instances/{instanceId}/suspend`, then later POST .../resume after audit sign-off

### Agent-Driven BPM Operations via Jentic

An AI assistant for operations leads can list open human tasks, add comments, and start new BPM process instances on demand. Through Jentic the agent works against the BPM REST API without holding raw Basic Auth credentials, using natural-language intents that map to the right endpoints.

Example prompt: Search Jentic for 'list my BPM human tasks', load the GET `/4.0/tasks` operation, and execute on behalf of the user

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/4.0/processes` | List process definitions |
| POST | `/4.0/processes/{processDefId}/instances` | Start a process instance |
| POST | `/4.0/processes/instances/{instanceId}/suspend` | Suspend a running instance |
| POST | `/4.0/processes/instances/{instanceId}/resume` | Resume a suspended instance |
| GET | `/4.0/tasks` | List human tasks for the user |
| GET | `/4.0/tasks/{taskId}` | Get a specific task |

## Key resources

- **Processes** — Process definitions deployed to BPM Suite
- **Process Instances** — Running and historical instances of those definitions
- **Tasks** — Human tasks assigned to users or groups
- **Task Actions** — Approve, reject, claim, or update human tasks
- **Task Comments** — Comments attached to a task by participants
- **Task Attachments** — Files attached to a task

## Why Jentic

- **Setup:** Wiring the Oracle BPM Suite REST API by hand means building the Basic Auth header from a WebLogic username and password, pointing at your own host and port, and keeping the process-instance and human-task routes straight. Through Jentic you install once, import the Oracle BPM Suite REST API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** BPM Suite puts the instance and task ids in the URL path (`/4.0/processes/instances/{instanceId}/...`, `/4.0/tasks/{taskId}`), so a rule can pin your agent to reading one task. You choose the operations it may call, so actions like suspending or resuming a process instance are not included unless you add them.
- **Credential handling:** Your BPM Suite Basic Auth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. The WebLogic username and password never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'start a BPM process instance' or 'list my human tasks', and Jentic returns the matching operation with its parameter schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Camunda Platform REST API** — Open-source BPMN process engine with a similar process and task REST surface
- **Kissflow API** — SaaS workflow and process automation platform with a hosted task model
- **ServiceNow Now Platform API** — ITSM and workflow platform commonly used alongside Oracle BPM for ticket-driven processes

## FAQ

### What authentication does the Oracle BPM Suite REST API use?

HTTP Basic Auth against the BPM Suite weblogic server. The credential is the BPM user the integration runs as. Through Jentic, the username and password are stored encrypted in the vault and the agent gets a scoped session - the raw credentials never enter the model context.

### Can I start and pause process instances with the BPM Suite API?

Yes. POST `/4.0/processes/{processDefId}/instances` starts a new instance from a deployed process definition. POST `/4.0/processes/instances/{instanceId}/suspend` pauses a running instance and the matching /resume endpoint brings it back online.

### How do I act on human tasks through the BPM Suite API?

GET `/4.0/tasks` returns the human task list for the authenticated user and GET `/4.0/tasks/{taskId}` returns a specific task. The Task Actions, Task Comments, and Task Attachments tag groups in the spec cover approving, commenting, and attaching files to those tasks.

### What are the rate limits for the Oracle BPM Suite REST API?

Rate limits are not declared in the spec because BPM Suite is typically deployed on customer-managed WebLogic infrastructure. Practical limits depend on the cluster sizing and the underlying SOA Suite tuning rather than a vendor-imposed quota.

### How do I list BPM human tasks through Jentic?

Install the SDK with pip install jentic, then search for 'list my BPM human tasks'. Jentic returns the GET `/4.0/tasks` operation with its schema; load it and execute. Run it through Jentic One, the self-hosted execution layer.

### Can I limit what my agent is allowed to do with the Oracle BPM Suite REST API?

Yes. Jentic One is self-hosted, so your own rules decide which operations and credentials your agent may use. Because BPM Suite puts the instance and task ids in the URL path, such as `/4.0/processes/instances/{instanceId}` and `/4.0/tasks/{taskId}`, a rule can pin the agent to reading a single task or listing tasks through GET `/4.0/tasks` while leaving state-changing calls out. You choose the operations it may call, so actions like starting a process instance or suspending and resuming one are not available to the agent unless you add them.