IBM BAW Tips Q&A - Recent questions and answers in REST API

Answered: Are REST API connections thread safe and how can concurrency be handled in IBM BPM?

Sun, 06 Sep 2026 13:24:33 +0000

Two different questions hide in there:

Are REST calls from BPM thread safe? Yes - every service execution runs on its own thread with its own BPMRESTRequest / HttpURLConnection objects; nothing is shared between concurrent executions unless you put it into a static Java field or a shared business object. Java integrations must be written thread safe (no mutable statics; connection pools instead of a shared connection), because the same class serves parallel executions.

How is concurrency handled?

Inbound (clients calling BPM's REST API): concurrent calls are served by the WebContainer thread pool; the engine serialises conflicting work on the same instance with row locks - two clients finishing the same task at the same time: one succeeds, the other gets an error (task already completed / CWTBG0019E optimistic lock) - handle it by re-reading. Idempotency is your job: use a business key (the request id) to detect duplicate starts.
Outbound (BPM calling REST services): the number of parallel calls equals the number of parallel service executions (thread pools: WebContainer for coach-triggered services, event manager for system tasks / UCAs); cap it with the event manager thread pool and with the external system's rate limits (a retry with back-off in a wrapper service, or an API gateway in front). Connection reuse: HttpURLConnection keeps alive per JVM; long-running or slow endpoints need explicit timeouts, otherwise threads pile up.
Transactions: an outbound REST call is not transactional; if the BPD step fails after the call, the call is not rolled back - make the target idempotent (PUT with a key, or check-before-create) so that retry of the failed step is safe.
Same instance, parallel branches: two branches calling REST and writing the same variable - by-value mapping means the last one to complete wins; write to different variables and merge.

// wrapper with timeout and retry with back-off (server-side script)
function callWithRetry(fn, attempts) {
  for (var i = 1; ; i++) {
    try { return fn(); }
    catch (e) { if (i >= attempts || !/timed out|503|429/i.test(String(e))) throw e; java.lang.Thread.sleep(500 * Math.pow(2, i)); }
  }
}
tw.local.result = callWithRetry(function () { var c = new java.net.URL(tw.local.url).openConnection(); c.setConnectTimeout(5000); c.setReadTimeout(20000); /* ... */ return read(c); }, 4);

References

Answered: How can Business Data be Updated using REST API?

Sun, 06 Sep 2026 13:22:36 +0000

"Business data" here means the process instance's variables (and the exposed business data that the search index shows). Update them with the process variables resource of the classic REST API, or the task data actions while a task is open:

# 1. instance variables (any running instance; full replacement of each variable you name)
PUT /rest/bpm/wle/v1/process/2072.123/variables
Content-Type: application/json
BPMCSRFToken: <token>
{ "order": { "number": "ORD-42", "status": "APPROVED", "customer": { "id": "c1", "name": "Ana Perez" } }, "approver": "jdoe" }

# read first (to modify in place)
GET /rest/bpm/wle/v1/process/2072.123?parts=data
# 2. task data (a task's input/output variables; updates the instance when the task completes)
PUT /rest/bpm/wle/v1/task/2078.456?action=setData&params={"order":{...}}&parts=data
# 3. complete a task with output data in one call
PUT /rest/bpm/wle/v1/task/2078.456?action=finish&params={"decision":"APPROVED","comment":"ok"}
# 4. BAW 21+ Process REST v2: the instance's "actions" list shows set_data when the caller may change data (see /bpm/docs of your level for the call)

The exposed business data used by searches (the "business data" columns in Process Portal) is updated automatically by the engine when the underlying variable changes through any of these calls - there is no separate API for it. Rules: send whole variables (the engine does not merge partial objects), keep types consistent with the business object, and obtain the CSRF token first on BAW 20+ / CP4BA. Server-side from a script the same is BPMRESTRequest (question 3127); inside the flow use data mapping (question 3160).

References

Answered: How can we upload a document to document store using REST API?

Sun, 06 Sep 2026 13:21:58 +0000

The BPM document store accepts uploads through the classic REST API as a multipart request; the document is attached to a process instance (or stays unattached) and can carry properties:

# upload (multipart/form-data): file part + metadata as query parameters
curl -k -u user:pw -H "BPMCSRFToken: $TOKEN" \
  -F "file=@invoice.pdf;type=application/pdf" \
  "https://host:9443/rest/bpm/wle/v1/document?name=invoice.pdf&processInstanceId=2072.123&documentType=INVOICE&properties=%7B%22vendor%22%3A%22Acme%22%7D"
# response: { "data": { "id": "2074.987", "name": "invoice.pdf", "mimeType": "application/pdf", "size": 12345, "url": "/rest/bpm/wle/v1/document/2074.987/content" } }

# download
GET /rest/bpm/wle/v1/document/2074.987/content
# list the documents of an instance
GET /rest/bpm/wle/v1/process/2072.123?parts=documents
# update content (new version) / delete
POST /rest/bpm/wle/v1/document/2074.987?action=update  (multipart file)      DELETE /rest/bpm/wle/v1/document/2074.987

// browser (coach view): upload a File object from an <input type=file> to the current instance
var fd = new FormData(); fd.append("file", input.files[0]);
var xhr = new XMLHttpRequest();
xhr.open("POST", base + "/rest/bpm/wle/v1/document?name=" + encodeURIComponent(input.files[0].name) + "&processInstanceId=" + piid, true);
xhr.setRequestHeader("BPMCSRFToken", token);
xhr.onload = function () { if (xhr.status === 200) ${DocList}.refresh(); };
xhr.send(fd);

Notes: parameter names vary slightly by release (processInstanceId vs parentId on 8.5.0; check the REST API tester /bpmrest-ui of your level), the document store must be enabled (it is by default), size limits come from the web container's maximum post size (raise it for large files), and for ECM (FileNet) the equivalent is the CMIS AtomPub / browser binding of the content server, not the BPM document resource. In service flows use tw.system.createDocument instead of REST (question 104).

References

Answered: How to update complex variables in REST API set data?

Sun, 06 Sep 2026 13:18:54 +0000

The classic setData actions take the variables as a JSON object in the params query parameter; complex variables are nested JSON - the whole object is replaced with what you send, so include every field you want to keep:

# task data (the task's variables)
PUT /rest/bpm/wle/v1/task/2078.456?action=setData&params={"order":{"number":"ORD-42","customer":{"id":"c1","name":"Ana"},"lines":[{"item":"A","qty":2},{"item":"B","qty":1}]},"comment":"updated"}&parts=data
BPMCSRFToken: <token>

# process instance variables (same JSON shape, one entry per variable name)
PUT /rest/bpm/wle/v1/process/2072.123/variables
Content-Type: application/json
{ "order": { "number": "ORD-42", "customer": { "id": "c1", "name": "Ana" }, "lines": [ { "item": "A", "qty": 2 } ] } }

Rules that avoid the usual errors:

URL-encode the params value (encodeURIComponent(JSON.stringify(obj))); very large objects exceed URL limits - use the process variables resource with a body, or a service flow.
Field names must match the business object definition exactly (case-sensitive); unknown fields are ignored, missing fields become null / default - read the current data first (GET .../task/{id}?parts=data), modify in place, send back.
Dates as ISO strings ("2025-06-01T10:00:00Z"), decimals as numbers, lists as arrays, business objects as objects; null clears a field.
The task must be in a state that allows data changes (received / claimed, not closed); process variables can be set on running instances.

// JavaScript client example (browser or Node)
var vars = JSON.parse(await (await fetch(base + "/rest/bpm/wle/v1/task/" + id + "?parts=data")).text()).data.data.variables;
vars.order.customer.name = "Ana Perez";
await fetch(base + "/rest/bpm/wle/v1/task/" + id + "?action=setData&params=" + encodeURIComponent(JSON.stringify(vars)) + "&parts=none", { method: "PUT", headers: { BPMCSRFToken: token } });

References

Answered: How can we move tokens using REST APIs as part of production troubleshooting?

Sun, 06 Sep 2026 13:17:10 +0000

Token moves are the surgical way to unstick or reroute a running instance in production; the REST API does it with two calls (find the token, move it):

# 1. where is the instance? tokens + steps
GET /rest/bpm/wle/v1/process/2072.1234?parts=executionTree,diagram
# executionTree.root.children -> [{ "tokenId": "6", "name": "Wait for approval", "flowObjectId": "8d1f...", "createdTaskIDs": ["2078.99"] }]
# diagram.step -> [{ "ID": "8d1f...", "name": "Wait for approval", "type": "intermediateEvent" }, { "ID": "c2a0...", "name": "Ship order", "type": "activity" }, ...]

# 2. move token 6 to "Ship order" and resume the instance
POST /rest/bpm/wle/v1/process/2072.1234?action=moveToken&tokenId=6&target=c2a0...&resume=true&parts=none
BPMCSRFToken: <token>          (BAW 20+ / CP4BA; obtain with POST /rest/bpm/wle/v1/system/login)

# variants
POST ...?action=deleteToken&tokenId=6&resume=true          # remove a token (e.g. a duplicate parallel branch)
PUT  /rest/bpm/wle/v1/process/2072.1234?action=suspend        # suspend first when several changes are needed, resume after
PUT  /rest/bpm/wle/v1/process/2072.1234?action=retry          # for Failed instances: retry the failed step instead of moving

Rules for production: (1) suspend the instance, move, set variables if the target step needs data (PUT /process/{piid}/variables), resume; (2) the open task of the old position is closed by the engine when its token leaves (the user sees it disappear) - tell them; (3) moving into a sub-process or a parallel branch needs the target node inside the right scope - the diagram's step list includes nested steps; moving into a multi-instance activity is not supported; (4) record every move (instance, from, to, reason, who) - the instance's comments API is a good place (the instance comment action of the Process REST API); (5) the same operations exist in Process Admin > Process Inspector (Move / Delete token) and in the JavaScript API (TWProcessInstance.moveToken), and on CP4BA through the same classic REST resource. Operations tooling built on this (a "Tokens" dashboard) pays for itself quickly.

References

Answered: There is REST Services support in 8.5.7 can someone provide more light on this ability?

Sun, 06 Sep 2026 13:06:09 +0000

IBM BPM 8.5.7 brought REST in two directions:

1. Consuming REST services - the new External Service of type REST: import a Swagger 2.0 (JSON / YAML) definition (file or URL), pick the operations, and BPM generates business objects for the schemas and a service you call from a service flow with typed input / output; the host comes from a Server definition (Process App Settings > Servers, type REST server) so that every environment points to its own endpoint, with basic authentication or none; TLS through the cell truststore. Before 8.5.7 the only options were a Java integration or a script with Java's HTTP client (still valid for APIs without Swagger).

// after importing the Swagger "Customer API" with operation getCustomer
// service flow: External Service step "getCustomer" -> input tw.local.id, output tw.local.customer (generated BO "Customer")
tw.local.id = tw.local.order.customerId;
// (step)  ->  tw.local.customer.name, tw.local.customer.creditLimit
if (tw.local.customer.creditLimit < tw.local.order.total) tw.local.needsApproval = true;

2. Exposing BPM as REST - the BPM REST API (/rest/bpm/wle/v1) already existed; 8.5.7 extended it (task actions, search query API PUT /search/query, exposed items) and shipped the REST API tester (/bpmrest-ui) to try calls. Any service flow can be run through POST /rest/bpm/wle/v1/service/{id}?action=start, which is how external applications call BPM logic; there is no "publish my service as a REST resource with my own path" feature - that came much later (Workflow REST v2 in BAW 21 for standard resources; custom paths still need an API gateway in front).

Limitations of the 8.5.7 REST integration worth knowing: Swagger 2.0 only, JSON bodies only, no OAuth (basic or none - use a gateway or a Java integration for tokens), one Server per external service, and generated business object names taken from the Swagger definitions (rename clashes before importing - question 2992).

References

Answered: Why user preference data is not coming in REST call of User details

Sun, 06 Sep 2026 11:53:52 +0000

GET /rest/bpm/wle/v1/user/{name} returns the user attributes (id, full name, e-mail, memberships); preferences are a different data set and come back only when you ask for them:

GET /rest/bpm/wle/v1/user/{userName}?parts=all                 -> "userPreferences" object included
GET /rest/bpm/wle/v1/user/{userName}?parts=userPreferences,memberships
GET /rest/bpm/wle/v1/user/{userName}?includeInternalMemberships=true&refreshUser=true&parts=all   // refresh from the registry first

Typical answer (BPM 8.5.7 / BAW):

{ "status": "200", "data": { "userName": "jdoe", "fullName": "John Doe", "emailAddress": "jdoe@example.com",
   "userPreferences": { "Task Email Notification": "true", "Email Address": "jdoe@example.com", "Locale": "en_US", "Send Task Email Notifications": "false" }, ... } }

If the object is empty although parts=all is used: the user has never saved preferences (Process Portal > Preferences stores them on first change; the REST API does not synthesise defaults), or the call was made for a different user than the one logged in without administrator rights - preferences of other users need the tw_admins role. Set them with PUT /rest/bpm/wle/v1/user/{name}?action=setPreference&key=Email%20Address&value=....

References

Process REST API - user resource (parts, setPreference)

Answered: How to use BPM REST API in script with BPMREStRequest()?

Sun, 06 Sep 2026 11:40:39 +0000

BPMRESTRequest is the server-side JavaScript helper (System Data toolkit) that calls the BPM REST API from a script with the identity of the running service. Minimal working example for your task lookup:

// script task in a service flow (server side)
var req = new BPMRESTRequest();
req.restServiceName = "";            // leave empty for the local server (or the name of a "Server" of type REST defined in the process app)
req.method = "GET";
req.resource = "/task/" + tw.local.taskId;   // relative to /rest/bpm/wle/v1
req.parameters = { "parts": "data" };
var response = tw.system.invokeREST(req);
if (response.httpStatusCode == 200) {
  var json = JSON.parse(response.content);
  tw.local.taskData = json.data.data.variables;    // the task variables
  tw.local.subject  = json.data.subject;
} else {
  throw new Error("REST " + response.httpStatusCode + ": " + response.content);
}

For calls that change something (assign, finish, setData) use req.method = "PUT" and pass the query parameters in req.parameters; a JSON body goes into req.body with req.contentType = "application/json". The CSRF token is added by the server for local calls, so nothing extra is needed there; for a remote BPM server define a Server of type "REST" in the process app settings (host, port, user) and put its name in restServiceName.

Two alternatives when BPMRESTRequest is not what you need: the JavaScript API is direct and faster inside the same server (tw.system.findTaskByID(tw.local.taskId) then .subject, .processInstance, .status), and on BAW 20+ the OOB REST external service (import the BAW Swagger) gives you typed business objects.

References

Answered: Inside CSHS exposed as Dashboard, while click on close button, redirect to the Work Portal.

Mon, 20 May 2019 02:37:18 +0000

If you are using any CSHS as a dashboard then why u create a button in that. and if button is required then u can change the end state mapping of a coach.

Answered: how extract user details along with the groups using rest api in ibm bpm 8.5.6

Mon, 05 Nov 2018 19:42:08 +0000

/rest/bpm/wle/v1/users?includeTaskExperts=true&sort=true&includeInternalMemberships=true&refreshUser=false&parts=all

should provide you that information

Answered: How can we find the bpdid for Intermendiate Message Events(IME) and Decision Gateways for moving tokens?

Sun, 17 Sep 2017 19:06:26 +0000

simple way is to open bpd in pd then you can see the id

Answered: How can we update Complex Variables for Tasks using REST API ?

Sun, 17 Sep 2017 04:26:20 +0000

You can use the "Set Data" under Tasks REST API call

Answered: How can we update Complex Variables for BPD Instances using REST API ?

Sun, 17 Sep 2017 04:25:05 +0000

You can use "current state" REST call with only data option checked to get the json format of the variables and then name the necessary changes to json and then update using "Update Instance Variables" REST API Call

Answered: Is it possible to use REST APIs in Coaches/Coach Views without need to login?

Sun, 17 Sep 2017 04:21:46 +0000

Yes you can do an ajax call if the rest apis are also on the same server (which most commonly they are) and the calls will be performed in the security context of the logged in user and there will not be a need to authenticate again.

Answered: Can we make REST API calls from server scripts or service ?

Sat, 21 May 2016 15:42:29 +0000

Technically possible from server scripts using live connect ,however it is tedious.From the services use HTTP connector to make server side REST API calls(available from SYSDATA toolkit).

--Mahesh

Answered: How to create users using REST API?

Sat, 21 May 2016 03:04:17 +0000

You can use the method described at the following link, which uses WebSphere CLI to import the users

http://awesomedeveloper.blogspot.in/2013/03/creating-lot-of-users-on-websphere.html?cm_mc_uid=15200844713514633392557&cm_mc_sid_50200000=1463811754

We have built a WebSphere Virtual Member Manager based Java Toolkit which can be used to create users even in federated repositories, we will be releasing it soon for reference and community use.