REST interface for BPD-related resources - Process Instances Status Overview Resource - GET Method

Use this method to retrieve the number of business process definition (BPD) instances. The optional parameters apply filters to the results.

Sample method invocation

GET /rest/bpm/wle/v1/processes/status/overview[?modifiedAfter={string}][&modifiedBefore={string}][&userFilter={string}][&searchFilter={string}][&searchFilterScope={string}][&startedByMe={boolean}]

Parameters

Optional parameters
NameValue TypeDescription
modifiedAfter string
Include only the number of BPD instances that occur on or after the specified date. The date must be in ISO8601 format such as 2011-08-04T03:12:53Z.
modifiedBefore string
Include only the number of BPD instances that occur on or before the specified date. The date must be in ISO8601 format such as 2011-08-04T03:12:53Z.
userFilter string
Include only the number of BPD instances associated with the specified user.
searchFilter string
Include only the number of BPD instances with the specified name, include only the number of BPD instances that belong to the process application with the specified short name, or include the total from both types of searches. The searchFilterScope parameter specifies which type of search to do.
searchFilterScope string
Specifies the scope of the search filter. The default value is Both.
ValueDescription
AppShortName
Include only the number of BPD instances that belong to the process application whose short name matches the searchFilter parameter.
InstanceName
Include only the number of BPD instances whosen name matches the searchFilter parameter.
Both
Include the number of BPD instances whose name matches the search filter or that belong to the process application whose short name matches the searchFilter parameter.
startedByMe boolean
You can use this optional parameter if you only want to include instances started by you. True means to include instances started by you. Default is false.

Request content

None

Response content

A number of process instances (ProcessInstanceCount complexType).

The default content type is application/json.

MIME type: application/json


Schema
{
	"status": "200",
	"data": {
		"overview": {
			"type": "object",
			"description": "The count information for each process instance status",
			"properties" : {
				"Active": {
					"type": "integer",
					"description": "The number of process instances with a status of 'Active'"
				},
				"Terminated": {
					"type": "integer",
					"description": "The number of process instances with a status of 'Terminated'"
				},
				"Did_not_Start": {
					"type": "integer",
					"description": "The number of process instances with a status of 'Did_not_Start'"
				},
				"Suspended": {
					"type": "integer",
					"description": "The number of process instances with a status of 'Suspended'"
				},
				"Completed": {
					"type": "integer",
					"description": "The number of process instances with a status of 'Completed'"
				},
				"Failed": {
					"type": "integer",
					"description": "The number of process instances with a status of 'Failed'"
				}
			}
		}
	}
}
Example content
{
    "status": "200",
    "data": {
        "overview": {
            "Terminated": 0,
            "Did_not_Start": 0,
            "Active": 0,
            "Suspended": 0,
            "Completed": 5,
            "Failed": 0
        }
    }
}

MIME type: application/xml


Schema
<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="http://rest.bpm.ibm.com/v1/data/query"
	elementFormDefault="unqualified" xmlns="http://www.w3.org/2001/XMLSchema"
	xmlns:tns="http://rest.bpm.ibm.com/v1/data/query" xmlns:cmn="http://rest.bpm.ibm.com/v1/data/common"
	xmlns:pref="http://rest.bpm.ibm.com/v1/data/root">

	<import schemaLocation="Common.xsd" namespace="http://rest.bpm.ibm.com/v1/data/common" />
	<import schemaLocation="BPMRestData.xsd" namespace="http://rest.bpm.ibm.com/v1/data/root" />

	<!-- This type is used to return a list of saved queries. -->
	<complexType name="QueryList">
		<complexContent>
			<extension base="pref:Data">
				<sequence>
					<element name="identifier" type="string" />

					<!-- This is a list of zero or more saved queries -->
					<element name="items" type="tns:QueryItem" minOccurs="0"
						maxOccurs="unbounded" />
				</sequence>
			</extension>
		</complexContent>
	</complexType>

	<!-- This type represents a single saved query. -->
	<complexType name="QueryItem">
		<sequence>

			<!-- The name of the query -->
			<element name="name" type="string" />

			<!-- The display name associated with the query; this will contain the 
				same value as the name -->
			<element name="displayName" type="string" />

			<!-- The query's description -->
			<element name="description" type="string" />

			<!-- The "kind" associated with the query; this will be set to "SAVED_SEARCH" -->
			<element name="kind" type="string" />

			<!-- The id number associated with a saved search -->
			<element name="savedSearchID" type="long" nillable="true" />

			<!-- The autorization type associated with the query; this will be set 
				to "INSTANCE_BASED" -->
			<element name="authorizationType" type="string" />

			<!-- This field indicates the type of objects are returned by this query. 
				This will be one of "PROCESS_INSTANCE", "TASK", "TASK_TEMPL". -->
			<element name="entityTypeName" type="string" />

			<!-- This field specifies the name of the attribute which serves as the 
				key for the objects returned by this query. -->
			<element name="keyAttribute" type="string" />

			<!-- not used -->
			<element name="locales" type="string" minOccurs="0"
				maxOccurs="unbounded" />

			<!-- The pre-selected sort attributes for the query. -->
			<element name="sortAttributes" type="tns:SortAttribute"
				minOccurs="0" maxOccurs="unbounded" />

			<!-- The pre-predefined size of items to be retrieved. -->
			<element name="size" type="integer" nillable="true" />
		</sequence>
	</complexType>
	
	<!-- This type is used to return the stats for rows (items) in the result 
		set that would be returned by executing a particular saved query. -->
	<complexType name="QueryStats">
		<sequence>

			<!-- The size of the result set (number of rows) -->
			<element name="total" type="integer" />
			<element name="open" type="integer" />
			<element name="onTrack" type="integer" />
			<element name="atRisk" type="integer" />
			<element name="overdue" type="integer" />
<!-- comment out these two elements since not used by any code, so it means they are not part of 
     response since day one.
			<element name="active" type="integer" />
			<element name="completed" type="integer" />
 -->			
		</sequence>
	</complexType>

	<!-- This type is used to return the set of attributes (data columns) that 
		would be returned as the result of executing a particular saved query. -->
	<complexType name="QueryAttributes">
		<complexContent>
			<extension base="pref:Data">
				<sequence>
					<element name="identifier" type="string" />

					<!-- The name of the query associated with this set of attributes -->
					<element name="query" type="string" />

					<!-- The diplay name of the query; this is the same value as the name -->
					<element name="displayName" type="string" />

					<!-- not used -->
					<element name="description" type="string" />

					<!-- The "kind" associated with the query; this will be set to "SAVED_SEARCH" -->
					<element name="kind" type="string" />

					<!-- The autorization type associated with the query. This will be set 
						to one of: "INSTANCE_BASED", "ROLE_BASED" -->
					<element name="authorizationType" type="string" />

					<!-- This field indicates the type of objects returned by this query. 
						This will be one of "PROCESS_INSTANCE", "TASK", "TASK_TEMPL". -->
					<element name="entityTypeName" type="string" />

					<!-- This field specifies the name of the attribute which serves as 
						the key for the objects returned by this query. -->
					<element name="keyAttribute" type="string" />

					<!-- not used -->
					<element name="locales" type="string" minOccurs="0"
						maxOccurs="unbounded" />

					<!-- The pre-selected sort attributes for the query. -->
					<element name="sortAttributes" type="tns:SortAttribute"
						minOccurs="0" maxOccurs="unbounded" />

					<!-- The pre-predefined size of items to be retrieved. -->
					<element name="size" type="integer" nillable="true" />

					<!-- A list of zero or more attributes -->
					<element name="items" type="tns:QueryAttributeItem"
						minOccurs="0" maxOccurs="unbounded" />

				</sequence>
			</extension>
		</complexContent>
	</complexType>

	<!-- This type describes a single attribute that would be returned as the 
		result of executing a particular saved query. -->
	<complexType name="QueryAttributeItem">
		<sequence>

			<!-- The attribute name -->
			<element name="name" type="string" />

			<!-- A localized display name for the attribute -->
			<element name="displayName" type="string" />

			<!-- not used -->
			<element name="description" type="string" />

			<!-- The attribute's datatype -->
			<element name="type" type="string" />

			<!-- not used; set to false -->
			<element name="isArray" type="boolean" />

			<!-- The related query and attribute which provides this attributes' information -->
			<element name="sourceAttribute" type="string" />

			<!-- A string that identifies attributes with a well-known value range -->
			<element name="content" type="string" />

			<!-- The ID of the source attribute's table, as defined in the query table 
				definition -->
			<element name="sourceQueryTableIdentifier" type="string" />

			<!-- Specifies whether the attribute can be used as a sort attribute -->
			<element name="isSortable" type="boolean" minOccurs="0"
				maxOccurs="1" default="true" />

			<!-- Specifies whether the attribute can be used as a filter attribute -->
			<element name="isFilterable" type="boolean" minOccurs="0"
				maxOccurs="1" default="true" />

		</sequence>
	</complexType>


	<!-- This type is used to return the results of executing a particular saved 
		query. -->
	<complexType name="QueryResultSet">
		<complexContent>
			<extension base="pref:Data">
				<sequence>

					<!-- The key attribute associated with this set of query results. This 
						will depend on the type of objects being returned by the query, and will 
						be one of: "TASK.TKIID", "TASK_TEMPL.TKTID", "PROCESS_INSTANCE.PIID" -->
					<element name="identifier" type="string" />

					<!-- The name of the saved query for which these results were generated -->
					<element name="query" type="string" />

					<!-- This field indicates the type of objects are returned by this query. 
						This will be one of "PROCESS_INSTANCE", "TASK", "TASK_TEMPL". -->
					<element name="entityTypeName" type="string" />

					<!-- The list of attributes (columns) returned by this query -->
					<element name="attributeInfo" type="tns:AttributeInfo"
						minOccurs="0" maxOccurs="unbounded" />

					<!-- The offset value that was specified on the original request. This 
						value represents the index (within the overall query result set) of the first 
						item being returned. -->
					<element name="offset" type="integer" />

					<!-- The number of items being returned -->
					<element name="size" type="integer" />

					<!-- The number of items requested in the original request -->
					<element name="requestedSize" type="integer" />

					<!-- Total number of results -->
					<element name="totalCount" type="integer" />
					<!-- True if total number of results exceeds a search limit and is actually 
						unknown -->
					<element name="countLimitExceeded" type="boolean" />
					<!-- Specifies the search limit used if any or 0 if it's not set -->
					<element name="countLimit" type="integer" />


					<!-- The set of results returned by this query. This is represented 
						as a list of zero or more "items", where each item represents a row in the 
						result set. Each item is represented by a Map, where the Map contains the 
						various columns of data associated with that item (row). -->
					<element name="items" type="cmn:Map" minOccurs="0"
						maxOccurs="unbounded" />
						
					<element name="stats" type="tns:QueryStats" />
				</sequence>
			</extension>
		</complexContent>
	</complexType>

	<!-- This type contains the information for a single attribute that is returned 
		as the result of executing a saved query. -->
	<complexType name="AttributeInfo">
		<sequence>

			<!-- The name of the attribute -->
			<element name="name" type="string" />

			<!-- The datatype of the attribute -->
			<element name="type" type="string" />

			<!-- A string that identifies attributes with a well-known value range -->
			<element name="content" type="string" />

			<!-- not used; set to false -->
			<element name="isArray" type="boolean" />

			<!-- The related query and attribute which provides this attributes' information -->
			<element name="sourceAttribute" type="string" />

			<!-- The ID of the source attribute's table, as defined in the query table 
				definition -->
			<element name="sourceQueryTableIdentifier" type="string" />
		</sequence>
	</complexType>

	<!-- This type is used to return the number of rows (items) in the result 
		set that would be returned by executing a particular saved query. -->
	<complexType name="QueryResultSetCount">
		<complexContent>
			<extension base="pref:Data">
				<sequence>

					<!-- The size of the result set (number of rows) -->
					<element name="count" type="integer" />
				</sequence>
			</extension>
		</complexContent>
	</complexType>
	
	<!-- A container used to describe a sort attribute by its name and sort 
		order. -->
	<complexType name="SortAttribute">
		<sequence>
			<element name="name" type="string" />
			<element name="sourceAttribute" type="string" />
			<element name="sortOrder" type="string" /> <!-- ASC, DESC -->
		</sequence>
	</complexType>
	
	<complexType name="ProcessInstanceCount">
		<complexContent>
			<extension base="pref:Data">
				<sequence>
					<element name="overview" type="cmn:Map"/>
				</sequence>
			</extension>
		</complexContent>
	</complexType>	
</schema>
Example content
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bpm:ResponseData xmlns:bpm="http://rest.bpm.ibm.com/v1/data"
	xmlns:ex="http://rest.bpm.ibm.com/v1/data/exception" xmlns:soc="http://rest.bpm.ibm.com/v1/data/social"
	xmlns:sys="http://rest.bpm.ibm.com/v1/data/system" xmlns:ug="http://rest.bpm.ibm.com/v1/data/usergroup">
	<status>200</status>
	<data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xmlns:qry="http://rest.bpm.ibm.com/v1/data/query" xsi:type="qry:ProcessInstanceCount">
		<overview>
			<item key="Completed">
				<value xmlns:ns9="http://www.w3.org/2001/XMLSchema" xsi:type="ns9:long">5</value>
			</item>
			<item key="Active">
				<value xmlns:ns9="http://www.w3.org/2001/XMLSchema" xsi:type="ns9:long">0</value>
			</item>
			<item key="Failed">
				<value xmlns:ns9="http://www.w3.org/2001/XMLSchema" xsi:type="ns9:long">0</value>
			</item>
			<item key="Terminated">
				<value xmlns:ns9="http://www.w3.org/2001/XMLSchema" xsi:type="ns9:long">0</value>
			</item>
			<item key="Did_not_Start">
				<value xmlns:ns9="http://www.w3.org/2001/XMLSchema" xsi:type="ns9:long">0</value>
			</item>
			<item key="Suspended">
				<value xmlns:ns9="http://www.w3.org/2001/XMLSchema" xsi:type="ns9:long">0</value>
			</item>
		</overview>
	</data>
</bpm:ResponseData>

MIME type: application/x-javascript

Error Response content

Detailed error information.

The default content type is application/json.

MIME type: application/json


Schema
{  "description": "WLE Error Response", 
   "type": "object",
   "properties":
   {  "status": {"type": "string",
         "description": "The status of the previous API call."
      },
      "exceptionType": {"type": "string",
         "description": "The classname associated with the exception."
      },
      "errorNumber": {"type": "string",
         "description": "Message ID of the exception."
      },
      "errorMessage": {"type": "string",
         "description": "Message text of the exception."
      },
      "errorMessageParameters": {"type": ["string"], "optional": true,
         "description":"Message text parameters of the exception."
      },
      "programmersDetails": {"type": "object", "optional": true,
         "description":"Additional exception details, for example, a stack trace."
      }
   }
} 

MIME type: application/xml


Schema
<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="http://rest.bpm.ibm.com/v1/data/exception"
	elementFormDefault="unqualified" xmlns="http://www.w3.org/2001/XMLSchema"
	xmlns:tns="http://rest.bpm.ibm.com/v1/data/exception"
	xmlns:dat="http://rest.bpm.ibm.com/v1/data/root">

    <import schemaLocation="BPMRestData.xsd" namespace="http://rest.bpm.ibm.com/v1/data/root" />
    
    <!--
	This type represents an error response.
    -->    
    <element name="RestRuntimeException">
	<complexType>
	    <sequence>
		<element name="status" type="string"/>
		<element name="Data" type="tns:ExceptionData">
    		</element>
	    </sequence>
	</complexType>
    </element>

    <!-- 
	 This type contains detailed error information associated with an exception.
    -->
    <complexType name="ExceptionData">
	<sequence>
	    <element name="status" type="string"/>

	    <!-- This specifies the java class name of the exception -->
	    <element name="exceptionType" type="string"/>

	    <!-- The message ID of the error message -->
	    <element name="errorNumber" type="string" minOccurs="0"/>

	    <!-- The complete error message -->
	    <element name="errorMessage" type="string"/>

	    <!-- The list of strings inserted into the error message -->
	    <element name="errorMessageParameters" type="string" minOccurs="0" maxOccurs="unbounded"/>

	    <!-- 
		 The stacktrace associated with the exception.
		 Note that this will be omitted unless the "server-stacktrace-enabled" property
		 is enabled in the server's 100Custom.xml file.
	    -->     
	    <element name="programmersDetails" type="string"></element>
	    
	    <!-- Prior responses.  Set if a bulk command was used -->
	    <element name="responses" type="dat:BulkCommandResponses" minOccurs="0"></element>

            <element name="errorData" type="tns:ErrorData" minOccurs="0" />
	</sequence>
    </complexType>

    <complexType name="ErrorData">
        <sequence>
            <element name="code" type="string" />
            <element name="data" type="string" minOccurs="0" />
        </sequence>
    </complexType>
    
</schema>

MIME type: application/x-javascript

Status codes

The method returns one of the following status codes:
CodeDescription
200 OK
The request was successfully completed.
400 Bad Request
The parameters are not valid or they are missing.
401 Unauthorized
The caller is not authorized for this request.
406 Not Acceptable
The requested content type or content encoding is not supported.
406 Not AcceptableThe requested content type or content encoding is not supported.
500 Internal Server Error
A severe problem has occurred.

Available since

8.5.6

Parent Topic: Process Instances Status Overview Resource