Web Service Interface

IBM Business Process Manager provides a Web service interface for accessing BPMN business processes, coaches, and related resources.

Web Service Operations for BPMN Processes

The Web service operations for BPMN Processes and related resources are defined in the XML namespace "http://webapi.lombardisoftware.com".

Name Description
AbortProcessInstance Stop a process instance
AbortProcessInstances Stop the process instances
AddComment Adds comment to specified instance
AddHelpRequest Adds help request to specified instance
AssignTask Assign a task to current user from a role to which the user belongs. This operation is only valid for tasks that are currently assigned to a role. Invoking this operation on tasks that are already assigned to the current user will result in an exception.
AssignTasks Assign multiple tasks to the current user from a role to which the user belongs. This operation is only valid for tasks that are currently assigned to a role. Invoking this operation on tasks that are already assigned to the current user will result in an exception.
ChangeProcessInstanceDueDate Change a process instance's due date
ChangeProcessInstancesDueDate Change the process instance's due dates
ChangeTaskDueDate Change the due date of a task
ChangeTaskPriority Change a task priority and, optionally, its due date
ChangeTasksDueDate Change the due date of tasks
ChangeTasksPriority Change the priority of tasks, and optionally their due dates
CompleteTask

Complete a task for an activity in a process instance. This requires that the task is not closed and is assigned to the current user or to a role to which the current user belongs. The activity implementation for this task must be an external activity or a service. For InfoPath activity implementations, use one of the operations of each SubmitInfoPathForm instead.

A successful invocation of this operation will close the task using the current user's identity and will send an asynchronous notification of the task's completion to the process engine for the process instance that is associated with the task. This operation then returns.

Some time later, the process engine will receive the notification of the task's completion and will resume execution of the process instance. It will map the outputs according to the data mappings defined in the process for the task's activity. It will then continue execution of the steps that follow the completed task's activity in the process.

If the task implementation is external activity, then the outputs are saved in the ExternalActivityData when the task is closed. If the task is subsequently accessed (for example using a History search or by using GetProcessInstance), these output values will be visible. If the output variable has the same name as an input, then its value will overwrite the input variable's value. Thus if you want to view both the input and output values for a completed external activity task, then the parameters should be uniquely named (perhaps using "In" and "Out" postfixes).

CreateDocument Creates document
DeleteDocument Deletes the document with all its revisions and assigned properties
DueDateOkForTask Check the availability of the recipients of a task using their calendars
ExecuteSearch Run a search to retrieve task or process instance related information
GetActionPermissions Get a set of action states that are associated with a list of process instances, tasks, or both
GetAdHocStartingPoints Deprecated - ad hoc events are deprecated since version 8.5.5. Use an activity that has no input wire instead of an ad hoc event. Get the list of ad hoc actions that are available on the process instance
GetAllRoles Get all roles in the system
GetAllUsers Returns all users
GetCurrentUser Get the current user
GetDocument Returns document for specific document ID
GetDocumentsForProcessInstance Returns the documents for a specific process instance ID
GetDocumentsForProperties Returns a collection of documents attached to the process instance with the given processInstanceId, and matched by given properties with given matching mode (AND/OR).
GetExposedItems Get the items exposed to the user
GetFavorites Get the favorites visible to the user
GetPriorities Get the priorities in the system
GetProcessBySystemId Get a process by its system identifier
GetProcessInstance Get a process instance
GetProcessInstancesBusinessData Get the business data for multiple process instances
GetProcessInstancesForSavedSearch Get the process instances returned by the execution of a saved search. This will temporarily alter the definition of the saved search (in memory) to organize its results by process instance and to include all of the process and process instance fields.
GetRoleByName Returns user group information for specific user group name
GetSavedSearches Get the saved searches visible to the user
GetScoreboardData Get the scoreboard data for the scoreboard
GetScoreboards Get the scoreboards visible to the user
GetSearchMetaData Returns the available search columns that can be used in searches
GetSearchMetaDataForProcess Returns the available business data search columns for a process
GetServerInfo Get information about the server including its version
GetTask Get the task. Return the task object fully populated (including the ProcessInstance element).
GetTasksForSavedSearch Get the tasks returned by the execution of a saved search. This will temporarily alter the definition of the saved search (in memory) to organize its results by task and to include all of the process, process instance, and task fields.
GetUserByName Returns user information for specific user name
GetUserConfiguration Get all the user configuration information in one call
IgnoreHelpRequest Ignores help request
ReassignTask Reassign a task back to its original role
ReassignTasks Reassign the tasks back to their original roles
ReassignTasksToRole Reassign the tasks to a role
ReassignTasksToUser Reassign the tasks to a user
ReassignTaskToRole Reassign a task to a role
ReassignTaskToUser Reassign a task to a user
RefreshGroupMembership Refresh the group membership to sync up with the external user directory by invoking this operation. Please make sure the refresh timeout is greater than the time needed for the application server to refresh its cache for searching the external user directory.
ReplyHelpRequest Replies to help request
ResumeProcessInstance Resume a process instance
ResumeProcessInstances Resume the process instances
RunFavorite Run a favorite and return a task if it exists
SendTask Send a task
StartAdHocStartingPoint Deprecated - ad hoc events are deprecated since version 8.5.5. Use an activity that has no input wire instead of an ad hoc event. Run the ad hoc action
StartExposedItem Start an exposed item and return a task if it exists
StartProcess Start a process and create a new process instance
StartProcessWithInfoPathForm Start a process and create a new process instance with the output of an InfoPath form. The process must have an InfoPath Form Start Event with an attached form that matches the submitted form data.
StartTask

Start a task for an activity in a process instance. This requires that the task is not closed and is assigned to the current user or to a role to which the current user belongs. The activity implementation for this task must be an external activity or a service.

An external application should invoke this operation when it actually starts execution of a task. A successful invocation of this operation will record the task's start time using the current user's identity.

SubmitInfoPathForm Submit an InfoPath form that is associated with a task ID and a form data.
SubmitInfoPathForms Submit several InfoPath forms. Takes two equal length arrays of task IDs and corresponding form datas.
SuspendProcessInstance Suspend a process instance
SuspendProcessInstances Suspend the process instances
SynchronizeTaskLists Synchronize task lists by passing in information describing the task lists stored on the client and receive back information about task synchronization actions to take on the client to synchronize the client's state with the current state on the server. The client should create a task list synchronization input for each saved search being synchronized with the server. This contains the saved search ID, last synchronization date, and a comma separated string listing the task IDs present (active) on the client. The implementation should create an output for each input. The task list synchronization output object will contain the saved search ID, the synchronization date, and a list of task synchronization actions. The task synchronization action specifies one of three actions: - add - update - remove Add and update actions will contain the task details. Remove actions will only contain the task ID. The client can iterate over these actions applying them to the client side storage to bring it into sync with the server.
TestConnection Test the connection to this web service by invoking this operation
UpdateDocument Creates new version of a document

AbortProcessInstance

Stop a process instance
Inputs:
processInstanceId - The process instance ID of the process instance to stop
Output:
True if the process instance was successfully stopped

AbortProcessInstances

Stop the process instances
Inputs:
processInstanceIds - The process instance IDs of the process instances to stop
Output:
The number of successfully stopped process instances

AddComment

Adds comment to specified instance
Inputs:
processInstanceId - ID of instance
comment - comment for add

AddHelpRequest

Adds help request to specified instance
Inputs:
processInstanceId - ID of instance
sendTo - who receives the request
description - description of help request

AssignTask

Assign a task to current user from a role to which the user belongs. This operation is only valid for tasks that are currently assigned to a role. Invoking this operation on tasks that are already assigned to the current user will result in an exception.
Inputs:
taskId - the ID of task that should be assigned to current user
Output:
true if task is assigned; false otherwise

AssignTasks

Assign multiple tasks to the current user from a role to which the user belongs. This operation is only valid for tasks that are currently assigned to a role. Invoking this operation on tasks that are already assigned to the current user will result in an exception.
Inputs:
taskIds - the IDs of the tasks that should be assigned to the current user
Output:
the number of successfully assigned tasks

ChangeProcessInstanceDueDate

Change a process instance's due date
Inputs:
processInstanceId - The process instance ID of the process instance to change
dueDate - New due date of the process instance
Output:
True if the due date was successfully changed

ChangeProcessInstancesDueDate

Change the process instance's due dates
Inputs:
processInstanceIds - The process instance IDs of the process instances to change
dueDate - New due date of the process instances
Output:
The number of successfully changed process instances

ChangeTaskDueDate

Change the due date of a task
Inputs:
taskId - the ID of the task to change
dueDate - the new due date of the task
Output:
true if the task due date was successfully changed; false otherwise

ChangeTaskPriority

Change a task priority and, optionally, its due date
Inputs:
taskId - the ID of the task to change
priorityId - the ID of the new priority
changeDueDate - if true, then update the due date based the new priority
Output:
true if the task priority was successfully changed; false otherwise

ChangeTasksDueDate

Change the due date of tasks
Inputs:
taskIds - the IDs of the tasks to change
dueDate - the new due date of the tasks
Output:
the number of successfully changed tasks

ChangeTasksPriority

Change the priority of tasks, and optionally their due dates
Inputs:
taskIds - the IDs of the tasks to change
priorityId - the ID of the new priority
changeDueDate - if true, then update the due date based the new priority
Output:
the number of successfully changed tasks

CompleteTask

Complete a task for an activity in a process instance. This requires that the task is not closed and is assigned to the current user or to a role to which the current user belongs. The activity implementation for this task must be an external activity or a service. For InfoPath activity implementations, use one of the operations of each SubmitInfoPathForm instead.

A successful invocation of this operation will close the task using the current user's identity and will send an asynchronous notification of the task's completion to the process engine for the process instance that is associated with the task. This operation then returns.

Some time later, the process engine will receive the notification of the task's completion and will resume execution of the process instance. It will map the outputs according to the data mappings defined in the process for the task's activity. It will then continue execution of the steps that follow the completed task's activity in the process.

If the task implementation is external activity, then the outputs are saved in the ExternalActivityData when the task is closed. If the task is subsequently accessed (for example using a History search or by using GetProcessInstance), these output values will be visible. If the output variable has the same name as an input, then its value will overwrite the input variable's value. Thus if you want to view both the input and output values for a completed external activity task, then the parameters should be uniquely named (perhaps using "In" and "Out" postfixes).

Inputs:
taskId - The task ID of the task to complete
Output:
True if the task was successfully completed

CreateDocument

Creates document
Inputs:
document - document for adding

DeleteDocument

Deletes the document with all its revisions and assigned properties
Inputs:
parentId - the ID of document which has to be deleted.

DueDateOkForTask

Check the availability of the recipients of a task using their calendars
Inputs:
taskId - the ID of the task to check
dueDate - the due date to check
Output:
true if recipients recipient of a task are available for the due date; false otherwise

ExecuteSearch

Run a search to retrieve task or process instance related information
Output:
The search results

GetActionPermissions

Get a set of action states that are associated with a list of process instances, tasks, or both
Inputs:
processInstanceIds - the array of process instance IDs
taskIds - the array of task IDs
Output:
the action permissions

GetAdHocStartingPoints

Deprecated - ad hoc events are deprecated since version 8.5.5. Use an activity that has no input wire instead of an ad hoc event. Get the list of ad hoc actions that are available on the process instance
Inputs:
processInstanceId - process instance to get ad hoc starting points for
Output:
The list of available starting points

GetAllRoles

Get all roles in the system
Output:
The roles

GetAllUsers

Returns all users
Output:
collection of User objects

GetCurrentUser

Get the current user
Output:
The current user

GetDocument

Returns document for specific document ID
Inputs:
documentId - document ID

GetDocumentsForProcessInstance

Returns the documents for a specific process instance ID
Inputs:
Output:
the Documents

GetDocumentsForProperties

Returns a collection of documents attached to the process instance with the given processInstanceId, and matched by given properties with given matching mode (AND/OR).
Inputs:
properties - the properties Map [Property Name -> Property Value], these properties will be used for documents matching.
Output:
the Documents that satisfied given matching parameters

GetExposedItems

Get the items exposed to the user
Output:
The favorites

GetFavorites

Get the favorites visible to the user
Output:
The favorites

GetPriorities

Get the priorities in the system
Output:
The priorities

GetProcessBySystemId

Get a process by its system identifier
Inputs:
processAppAcronym - The acronym of the process application
processSystemId - The System ID of the process to find
Output:
The process

GetProcessInstance

Get a process instance
Inputs:
processInstanceId - The process instance ID of the process to get
Output:
The process instance

GetProcessInstancesBusinessData

Get the business data for multiple process instances
Inputs:
processInstanceIds - The process instance IDs of the process instances
Output:
The business data for each of the process instances

GetProcessInstancesForSavedSearch

Get the process instances returned by the execution of a saved search. This will temporarily alter the definition of the saved search (in memory) to organize its results by process instance and to include all of the process and process instance fields.
Inputs:
savedSearchId - The saved search ID of the saved search to run
Output:
The process instances

GetRoleByName

Returns user group information for specific user group name
Inputs:
roleName - the user group name
Output:
the user group information

GetSavedSearches

Get the saved searches visible to the user
Output:
The saved searches

GetScoreboardData

Get the scoreboard data for the scoreboard
Inputs:
scoreboardId - ID of the scoreboard
Output:
The scoreboard data

GetScoreboards

Get the scoreboards visible to the user
Output:
The scoreboards

GetSearchMetaData

Returns the available search columns that can be used in searches
Output:
collection of SearchColumn objects

GetSearchMetaDataForProcess

Returns the available business data search columns for a process
Inputs:
process - The process to get search meta data for
Output:
collection of SearchColumn objects

GetServerInfo

Get information about the server including its version
Output:
The server information

GetTask

Get the task. Return the task object fully populated (including the ProcessInstance element).
Inputs:
taskId - ID of task
Output:
The task object

GetTasksForSavedSearch

Get the tasks returned by the execution of a saved search. This will temporarily alter the definition of the saved search (in memory) to organize its results by task and to include all of the process, process instance, and task fields.
Inputs:
savedSearchId - The saved search ID of the saved search to run
Output:
The tasks

GetUserByName

Returns user information for specific user name
Inputs:
userName - user name
Output:
user information

GetUserConfiguration

Get all the user configuration information in one call
Output:
The user configuration information

IgnoreHelpRequest

Ignores help request
Inputs:
helpRequestId - ID of comment
description - description of why request is ignored

ReassignTask

Reassign a task back to its original role
Inputs:
taskId - the ID of the task to reassign
Output:
true if the task was successfully reassigned; false otherwise

ReassignTasks

Reassign the tasks back to their original roles
Inputs:
taskIds - the IDs of the tasks to reassign
Output:
the number of successfully reassigned tasks

ReassignTasksToRole

Reassign the tasks to a role
Inputs:
taskIds - the IDs of the tasks to reassign
roleId - the ID of the role
Output:
the number of successfully reassigned tasks

ReassignTasksToUser

Reassign the tasks to a user
Inputs:
taskIds - the IDs of the tasks to reassign
userId - the ID of the user
Output:
the number of successfully reassigned tasks

ReassignTaskToRole

Reassign a task to a role
Inputs:
taskId - the ID of the task to reassign
roleId - the ID of the role
Output:
true if the task was successfully reassigned; false otherwise

ReassignTaskToUser

Reassign a task to a user
Inputs:
taskId - The task ID of the task to reassign
userId - The user ID of the user
Output:
True if the task was successfully reassigned

RefreshGroupMembership

Refresh the group membership to sync up with the external user directory by invoking this operation. Please make sure the refresh timeout is greater than the time needed for the application server to refresh its cache for searching the external user directory.
Inputs:
refreshTimeout - Time in seconds to complete the operation
Output:
true if the operation succeeded; false otherwise

ReplyHelpRequest

Replies to help request
Inputs:
helpRequestId - ID of help request to reply
description - description of reply to help request

ResumeProcessInstance

Resume a process instance
Inputs:
processInstanceId - The process instance ID of the process instance to resume
Output:
True if the process instance was successfully resumed

ResumeProcessInstances

Resume the process instances
Inputs:
processInstanceIds - The process instance IDs of the process instances to resume
Output:
The number of successfully resumed process instances

RunFavorite

Run a favorite and return a task if it exists
Inputs:
favoriteI - d
Output:
The task to run. It can be null if there is no task for the current user.

SendTask

Send a task
Inputs:
sendTaskInfo - The information describing the task to send
Output:
The sent task

StartAdHocStartingPoint

Deprecated - ad hoc events are deprecated since version 8.5.5. Use an activity that has no input wire instead of an ad hoc event. Run the ad hoc action
Inputs:
processInstanceId - process instance for which to start ad hoc starting point
startingPointName - ad hoc starting point name
Output:
The list of new task IDs

StartExposedItem

Start an exposed item and return a task if it exists
Inputs:
exposedItemI - d
Output:
The task to run. It can be null if there is no task for the current user.

StartProcess

Start a process and create a new process instance
Inputs:
process - The process to start
inputs - The input variables to use when starting the process
Output:
The started process instance

StartProcessWithInfoPathForm

Start a process and create a new process instance with the output of an InfoPath form. The process must have an InfoPath Form Start Event with an attached form that matches the submitted form data.
Inputs:
process - The process to start
formId - The form ID of the InfoPath form to create the form data
formData - The InfoPath form data to use to start the process
Output:
The started process instance

StartTask

Start a task for an activity in a process instance. This requires that the task is not closed and is assigned to the current user or to a role to which the current user belongs. The activity implementation for this task must be an external activity or a service.

An external application should invoke this operation when it actually starts execution of a task. A successful invocation of this operation will record the task's start time using the current user's identity.

Inputs:
taskId - The task ID of the task to be started
Output:
True if the task was successfully started

SubmitInfoPathForm

Submit an InfoPath form that is associated with a task ID and a form data.
Inputs:
taskId - the task ID
formData - the form data
Output:
true if the InfoPath form was successfully submitted; false otherwise

SubmitInfoPathForms

Submit several InfoPath forms. Takes two equal length arrays of task IDs and corresponding form datas.
Inputs:
taskIds - the array of task IDs
formDatas - the array of InfoPath form datas
Output:
true if the InfoPath forms were successfully submitted; false otherwise

SuspendProcessInstance

Suspend a process instance
Inputs:
processInstanceId - The process instance ID of the process instance to suspend
Output:
True if the process instance was successfully suspended

SuspendProcessInstances

Suspend the process instances
Inputs:
processInstanceIds - The process instance IDs of the process instances to suspend
Output:
The number of successfully suspended process instances

SynchronizeTaskLists

Synchronize task lists by passing in information describing the task lists stored on the client and receive back information about task synchronization actions to take on the client to synchronize the client's state with the current state on the server. The client should create a task list synchronization input for each saved search being synchronized with the server. This contains the saved search ID, last synchronization date, and a comma separated string listing the task IDs present (active) on the client. The implementation should create an output for each input. The task list synchronization output object will contain the saved search ID, the synchronization date, and a list of task synchronization actions. The task synchronization action specifies one of three actions: - add - update - remove Add and update actions will contain the task details. Remove actions will only contain the task ID. The client can iterate over these actions applying them to the client side storage to bring it into sync with the server.
Inputs:
taskListSyncInputs - a list of task list synchronization inputs
Output:
The task list synchronization outputs

TestConnection

Test the connection to this web service by invoking this operation
Output:
true if the connection succeeded; false otherwise

UpdateDocument

Creates new version of a document
Inputs:
document - document for updating

Parent Topic: Web Service API