Search this site

Workflow Sample

Workflow Sample
Workflow Sample

Contact

Process Execution API

Contents

  1. 1 General Information
    1. 1.1 Responses
    2. 1.2 Response Objects
    3. 1.3 Error Response Object
  2. 2 List of Operations
    1. 2.1 List Process Models that can be started
    2. 2.2 Start Process
    3. 2.3 List of My Tasks and Offered Tasks
    4. 2.4 Accept Tasks
    5. 2.5 Acquire detailed process information
    6. 2.6 Execute Tasks
  3. 3 List of Errors

General Information

Responses

The response when there are no errors is HTTP 200. When there is data to be returned, UTF-8 encoded JSON text will be included in the body of the response. For errors regarding user authentication an HTTP 401 error (Unauthorized) will be returned, and when an authenticated user does not have authorization to perform an operation an HTTP 403 error (Forbidden) will be returned. Other errors will result in an HTTP 400 response with the error details included in the body in JSON text.

Response Objects

When data is returned, the response data will be one of the following objects or a list of these objects.
 Type of Object  Explanation
 ActivityEntry  Object indicating the first Task of Process Models that can be started
 WorkitemEntry  Object indicating currently running Tasks
 ProcessInstanceEnty Object indicating Process
 ProcessDataEntry Object indicating Process Data
Below are the attributes of these objects.

ActivityEntry

 Attribute  Explanation
 id  Task ID
 nodeName  Name of Task
 processModelInfoId  Process Model ID that does not change regardless of version
 processModelId  Process Model ID given to each different version
 processModelVersion  Version number of Process Model
 processModelInfoName  Name of Process Model
 processModelActivateDatetime  Date and time this version of the Process Model was activated

Sample:
{"startableActivities":[{
    "id":2086,
    "nodeName":"Test Task",
    "processModelActivateDatetime":"2010-01-07T18:13:40+0900",
    "processModelId":2081,
    "processModelInfoId":11,
    "processModelInfoName":"Test Model",
    "processModelVersion":1 }
]}

WorkitemEntry

 Attribute  Type  Explanation
id Number Task instance ID
allocateDatetime Date Date and time the Task was allocated
allocatedQuserId Number ID of allocated user
allocatedQuserName String Name of allocated user
allocatedQgroupId Number ID of allocated organization
allocatedQgroupName String Name of allocated organization
endDatetime Date Date and time the Task was completed
nodeName String Name of Task
nodeNumber Number Task number
offerDatetime Date Date and time the Task was offered
processInstanceEndDatetime Date Date and time the Process was completed
processInstanceId Number Process ID
processInstanceIdForView String Process ID, as displayed
processInstanceInitQgroupId Number ID of organization that started Process
processInstanceInitQgroupName String Name of organization that started Process
processInstanceInitQuserId Number ID of user that started Process
processInstanceInitQuserName String Name of user that started Process
processInstanceStartDatetime Date Date and time the Process was started
processInstanceState String State of Process
processInstanceTitle String Title of Process
processModelInfoId Number Process Model ID
processModelInfoName String Name of Process Model
processModelVersion Number Version of Process Model
startDatetime Date Date and time Task execution started
state String State of Task
swimlaneType String Type of Swimlane the Task is in
timeLimitDatetime Date Deadline of Task

Sample: 

{"workitem":{
    "id":58399,
    "allocateDatetime":"2010-08-18T14:03:18+0900",
    "allocatedQgroupId":null,
    "allocatedQgroupName":null,
    "allocatedQuserId":0,
    "allocatedQuserName":"SouthPole",
    "endDatetime":null,
    "nodeName":"Activity1",
    "nodeNumber":0,
    "offerDatetime":"2010-08-18T14:03:17+0900",
    "processInstanceEndDatetime":null,
    "processInstanceId":825,
    "processInstanceIdForView":"p825",
    "processInstanceInitQgroupId":null,
    "processInstanceInitQgroupName":null,
    "processInstanceInitQuserId":0,
    "processInstanceInitQuserName":"SouthPole",
    "processInstanceStartDatetime":"2010-08-18T14:03:16+0900",
    "processInstanceState":"STARTED",
    "processInstanceTitle":null,
    "processModelInfoId":9,
    "processModelInfoName":"Test Process",
    "processModelVersion":4,
    "startDatetime":null,
    "state":"ALLOCATED",
    "swimlaneType":"NORMAL",
    "timeLimitDatetime":null　}
}

ProcessInstanceEntry

 Attribute  Type  Explanation
processInstanceId Number Process ID
processInstanceIdForView String Process ID, as displayed
processInstanceInitQgroupId Number ID of organization that started Process
processInstanceInitQgroupName String Name of organization that started Process
processInstanceInitQuserId Number ID of user that started Process
processInstanceInitQuserName String Name of user that started Process
processInstanceStartDatetime Date Date and time the Process was started
processInstanceEndDatetime Date Date and time the Process was ended
processInstanceState String State of Process
processInstanceTitle String Title of Process
processModelInfoId Number Process Model ID
processModelInfoName String Name of Process Model
processModelVersion Number Version of Process Model
data Object Object that stores Process Data
Property Name is Process Data Definition Number
About its value, refer ProcessDataEntry below

ProcessDataEntry

 Attribute  Type  Explanation
id Number Process Data ID
processDataDefinitionNumber Number Definition Number of Process Data
dataType String Data type
subType String Sub-Data type Only used in specific dataType
value String Value
Up to dataType, it can be object
viewOrder Number Display order

Error Response Object

When error response is returned as JSON text, an ErrorEntry sequence is always sent under the name "errors." ErrorEntry attributes are listed below. For details on error types, see the [List of Errors] section.

ErrorEntry

 Attribute  Type  Explanation
 errorCode  String  Error code
 type  String  Error type
 input  String  Input that caused error

Sample: Error response

{"errors":[{"errorCode":"20002","input":"foo@questetra.com","type":"QuserDoesNotExist"}]}

List of Operations

Operations that can be handled by Start Process API are listed below. Replace <ContextRoot> in the URLs with the Questetra BPM Suite context root you are connecting to.
 Operation  URL
 List Process Models that can be started  <ContextRoot>/API/PE/ProcessModel/list
 Start Process  <ContextRoot>/API/PE/ProcessInstance/start
 List My Tasks  <ContextRoot>/API/PE/Workitem/listAllocated 
 List Offered Tasks  <ContextRoot>/API/PE/Workitem/listOffered
 Accept Tasks  <ContextRoot>/API/PE/Workitem/batchAccept
 Acquire Detail  <ContextRoot>/API/PE/ProcessInstance/view

List Process Models that can be started

This returns a list of Process Models that an authenticated user can start.

Parameter

None

Response

 Object  Explanation
 startableActivities  ActivityEntry list of Process Models that can be started

Possible Errors

None

Start Process

This starts a Process with the authorization of an authenticated user.

Parameter

 Parameter names  Explanation
 activityId *  ID of first Task in Process to be started.
 id attribute value of ActivityEntry

Response

 Object  Explanation
 workitem  WorkitemEntry that indicates the first Task of the started Process

Possible Errors

  • InvalidActivityId
  • InstanceNumberExceeding
  • UserNumberExceeding
  • OverQuota

List of My Tasks and Offered Tasks

This acquires a list of My Tasks or Offered Tasks.

Parameter

None

Response

 Object  Explanation
 count  Number of Tasks
 workitems  List of Tasks
 WorkitemEntry list

Sample:

{"count":2,
 "workitems":[
     {
         //WorkitemEntry
         "id":58399,
         "allocateDatetime":"2010-08-18T14:03:18+0900",
         ...
     }, {
         //WorkitemEntry
         "id":58400,
         "allocateDatetime":"2010-08-18T14:03:18+0900",
         ...
     }
 ]
}

Possible Errors

None

Accept Tasks

This accepts Tasks that are being offered.

Parameter

 Parameter names  Explanation
 workitemIds *  ID of Task to accept.
 id attribute value of WorkitemEntry
 Multiple Tasks can be accepted at once. In this case, please specify parameters and Task IDs for each Task.

Response

 Object  Explanation
 results  Object that stores info on whether Task is accepted successfully or not.
 Schema is as below.

 Attribute  Type  Explanation
 success  boolean  Whether Task is accepted successfully or not. Success is "true."
 workitemId  Number  Task ID
 workitem
 WorkitemEntry that stores Task information.
 If Task is not accepted successfully, this object may be lacking.
 error
 Error response object.
 Only if Task is not accepted successfully.
* With this API, there are no objects with "null" value.

Sample:

{"results":[
    {
        "success":true,
        "workitemId":58399,
        "workitem":{
            "id":58399,
            "offerDatetime":"2010-08-18T14:03:17+0900",
            "nodeName":"Activity1",
            "nodeNumber":0,
            "processInstanceId":825,
            "processInstanceIdForView":"p825",
            "processInstanceInitQgroupId":1,
            "processInstanceInitQgroupName":"Org",
            "processInstanceInitQuserId":0,
            "processInstanceInitQuserName":"SouthPole",
            "processInstanceStartDatetime":"2010-08-18T14:03:16+0900",
            "processInstanceState":"STARTED",
            "processInstanceTitle":"",
            "processModelInfoId":9,
            "processModelInfoName":"www Japanese",
            "processModelVersion":4,
            "startDatetime":null,
            "state":"ALLOCATED",
            "swimlaneType":"NORMAL"
    }, {
        "success":false,
        "workitemId":58400,
        "error":{
            "errorCode":"40003",
            "type":"WorkitemDoesNotExist"
        }
    }
]}

Possible Errors

Errors that may occur in list of results in case of normal response.
  • NeedToAcceptOtherWorkitems
  • WorkitemIsNotOffered
  • WorkitemStatusAlreadyChanged
  • WorkitemDoesNotExist
Errors that may occur in case of error response.
  • InvalidId

Acquire detailed process information

Acquire detailed process information  Detailed process information incudes process Data  Included only process data authenticated user has permission

Available Version

7.4.0

Parameter

 Name Parameter  Explanation
 processInstanceId *  Process ID
 Attribute value of processInstanceId of WorkitemEntry

Response

 Object  Explanation
 processInstance  ProcessInstanceEntry

Possible Errors

  • InvalidProcessInstanceId
  • ProcessInstanceDoesNotExist

Execute Tasks

List of Errors

 Error type  Error code  Explanation
 InvalidId  10001  An invalid ID was specified. ID should be between 0 and 9223372036854775807
 InvalidActivityId  10011  An invalid activityId was specified. activityId should be between 0 and 9223372036854775807
 InvalidProcessInstanceId  10014  An invalid processInstanceIdwas specified. processInstanceIdshould be between 0 and 9223372036854775807
 ActivityDoesNotExist  20012  The specified task does not exist.
 ProcessInstanceDoesNotExist  20016  The specified process does not exist.
 InstanceNumberExceeding  30004  The operation will result in the number of Processes exceeding the allowed limit.
 UserNumberExceeding  30005  Processes cannot be started when the number of users exceeds the allowed limit.
 OverQuota  30007  Too many Processes were started in a short period of time.
 NeedToAcceptOtherWorkitems  40000  There are other Tasks that need to be accepted together.
 WorkitemIsNotOffered  40001  This Task is not offered to you.
 WorkitemStatusAlreadyChanged  40002  Tried to accept a Task that is not in the "Offered" state.
 WorkitemDoesNotExist  40003  Task does not exist.