Skip to content

Rest API

Jump to bottom
Marco Rietveld edited this page Oct 24, 2013 · 77 revisions

Table of Contents

URL layout

The following schema lays out the current REST API available via kie-remote:

http://server.address:port/{application-id}/rest/
  runtime
    {id: [a-zA-Z0-9-:\\.]+}              // {deploymentId}
      execute                            * execute the given command [POST] 
      process
        {id: [a-zA-Z0-9-:\\.]+}          // {process definition id}
          start                          * start process [POST] 
                                           - accepts query map parameters
        instance
          {id: [0-9]+}                   * process instance details (// {process instance id}) [GET]
            signal                       * signal event [POST] 
                                           - accepts query map parameters
            abort                        * abort process instance [POST]
            variables                    * get variables from process instance [GET]
        signal                           * signal event [POST] 
                                           - accepts query map parameters
        workitem
          {id: [0-9]+}                   * work item details (// {work item id}) [GET]
            complete                     * complete work item [POST]
                                           - accepts query map parameters
            abort                        * abort work item [POST]
        history
          clear                          * clear/delete all (process/variable/node) instance logs [POST]
          instances                      * get all process instance logs [GET]
            {id: [0-9]+}                 * get process instance log (// {process instance id}) [GET]
              child                      * get all child process instance logs [GET]
              node                       * get all node instance logs [GET]
                {id: [a-zA-Z0-9-:\\.]+}  // {node id}
                                         * get node instance log [GET] 
              variable                   * get all variable instances [GET]
                {id: [a-zA-Z0-9-:\\.]+}  // {variable id}
                                         * get variable instance log [GET] 
          process
            {id: [a-zA-Z0-9-:\\.]+}      * get process instance logs (// {process id}) [GET]
          variable
            {id: [a-zA-Z0-9-:\\.]+}      * get variable instance log with this name (// {variable id}) [GET]
              instances                  * get process instance(s) in which variable is used [GET]
              value    
                {id: [a-zA-Z0-9-:\\.]+}  * get variable instance log with this name and value (// {variable value}) [GET]
                  instances              * get process instance(s) for which variable has this name and value [GET]
                  

        withvars                         // The following operations return process instance 
                                         // as well as process variable information
          process
            {id: [a-zA-Z0-9-:\\.]+}      // {process definition id}
              start                      * start process [POST] 
                                           - accepts query map parameters
            instance
              {id: [0-9]+}               * process instance details (// {process instance id}) [GET]
                signal                   * signal event [POST] 
                                           - accepts query map parameters
  
  task
    execute                              * execute the given (task) command [POST] 
    content
      {id: [0-9]+}                       * return the (JAXB) content [GET]
    query                                * query tasks (list of JAXB TaskSummary instances returned) [GET] 
    {id: [0-9]+}                         * return (JAXB representation of the) task // {task id} [GET]
        activate                         * activate task (taskId as query param.. ) [POST] 
        claim                            * claim task [POST]
        claimnextavailable               * claim next available task [POST]
        complete                         * complete task [POST]
                                           - accepts query map parameters
        delegate                         * delegate task [POST]
                                           - takes a "targetEntityId" query parameter
        exit                             * exit task [POST]
        fail                             * fail task [POST]
        forward                          * forward task [POST]
                                           - takes a "targetEntityId" query parameter
        release                          * release task [POST]
        resume                           * resume task [POST]
        skip                             * skip task [POST]
        start                            * start task [POST]
        stop                             * stop task [POST]
        suspend                          * suspend task [POST]
        nominate                         * nominate task [POST]
                                           - takes "user" and "group" parameters
           
        content                          * return (a JAXB representation of the) task content [GET]

Additional explanation

Execute operations

While there is a runtime/{id}/execute and a task/execute method, both will take all types of commands. This is possible because execute takes a JaxbCommandsRequest object, which contains a list of (org.kie.api.command.)Command objects. The JaxbCommandsRequest has fields to store the proper deploymentId and processInstanceId information.

Of course, if you send a command that needs this information (deploymentId, for example) and don't fill it in, this will fail.

Object parameters

While REST obviously only takes Strings as input parameters, using the following notation for query parameters will mean that the string is translated into a different type of object:

  • \d+ : Long
  • \d+i : Integer
  • \d+l : Long

Query map parameters

If you're interacting with a REST API call that would normally (when interacting the same operation on a local KieSession instance) take a Map<String, Object> instance, you can submit key-value pairs to the operation by passing a query param whose name starts with "`map_.".

For example, if you pass the query parameter "map_kEy=vAlue", then a Map<String, Object> will be created that contains the key value pair { "kEy" => "vAlue" }. "query map parameters" also use the "object parameter" syntax, so the following:

map_age=5000

will be translated into the key-value pair

{ "age" => Long.parseLong("5000") }

The following operations take query map parameters:

/runtime/{deploymentId}/process/{processDefId}/start
/runtime/{deploymentId}/workitem/{processItemId}/complete
/runtime/{deploymentId}/withvars/process/{processDefId}/start
/task/{taskId}/complete
/task/{taskId}/fail

Accessing "Per Process Instance" Runtimes

When working with the KIE Workbench, Red Hat JBoss BPM Suite, or jBPM Console, there are 3 different types of deployments possible:

  • Singleton
  • Per Process Instance
  • Per Request

These refer to how the KieSession (in which a jBPM process may be run) is handled.

If you've setup your deployment to be a Singleton or Per Request deployment, then you won't need additional parameters to interact with your deployment via the REST API.

However, if you've setup your deployment to be a Per Process Instance deployment, the REST API will need to know the process instance id in order to retrieve the KieSession instance. For some operations, the process instance is already part of the URL, such as this GET operation:

/runtime/{deploymentId}/process/instnce/{processInstanceId}

However, for those operations for which the processInstanceId is not part of the URL, you will need to add a runtimeProcInstId query parameter to the URL in order to successfully complete the REST operation. For example:

/runtime/{deploymentId}/workitem/12/abort?runtimeProcInstId=5

In the above case, the REST operation aborts work item 12 associated with process instance 5.

The following operations require the runtimeProcInstId parameter when using a Per Process Instance strategy with a deployment:

/runtime/{deploymentId}/process/signal
/runtime/{deploymentId}/process/workitem/{workItemId}
/runtime/{deploymentId}/process/workitem/{workItemId}/complete
/runtime/{deploymentId}/process/workitem/{workItemId}/abort
/runtime/{deploymentId}/history/variable/{variableId}/instances
/runtime/{deploymentId}/history/variable/{variableId}/value/{value}/instances

Pagination

All operations which return a list of items can be provided with parameters in order to "paginate" the results. Pagination means that the results can be divided into a number of pages, each of which contains the same number of items. If user needs results 10 to (and including) 19, then the user can request the operation be paginated with page 2 and page size 10.

The first page is page 1, not page 0!

The following methods will take query parameters in order to paginate the results of the operation:

/task/query
/runtime/{deploymentId}/history/instance
/runtime/{deploymentId}/history/instance/{procInstid}
/runtime/{deploymentId}/history/instance/{procInstId}/child
/runtime/{deploymentId}/history/instance/{procInstId}/node
/runtime/{deploymentId}/history/instance/{procInstId}/node/{nodeId}
/runtime/{deploymentId}/history/variable/{variableId}
/runtime/{deploymentId}/history/variable/{variableId}/instances
/runtime/{deploymentId}/history/variable/{variableId}/value/{value}
/runtime/{deploymentId}/history/variable/{variableId}/value/{value}/instances
/runtime/{deploymentId}/history/process/{id: [a-zA-Z0-9-:\\.]+}

Pagination parameters can be given using the following parameters:

page        This the page number requested. The default value is 1. 
p           This is a synonym for the above "page" parameter.
pageSize    This is the number of elements per page to return. The default value is 10.
s           This is a synonym for the above "pageSize" parameter.

If both a parameter and it's synonym are included in an URL, the longer version of the parameter will be used instead of the shorter version.

For example, if you include "page=3&p=8" in your url, then page number 3 will be returned.

When no pagination parameters (see above) are included, the results will be paginated as folows:

  • "Pages" will contain 10 items per page.
  • The first page (e.g. the first 10 items), will be shown.

Runtime operations

History Variable operations

There are 4 operations available to query history and process instances based on variable information:

/runtime/{deploymentId}/history/variable/{variableId}
/runtime/{deploymentId}/history/variable/{variableId}/instances
/runtime/{deploymentId}/history/variable/{variableId}/value/{value}
/runtime/{deploymentId}/history/variable/{variableId}/value/{value}/instances

All 4 of these operations also take an additional query parameter: activeProcesses.

If activeProcesses is set to true, then the operation will only return results based on active process instances. If activeProcesses is not set, or set to anything else, the results will be based on all processes instances, active or not.

Task operations

The Query operation

// MARCO: needs update (2013-10-21): rewrite to match new GetTasksByVariousFieldsCommand
// MARCO: update jbpm-human-task documentation

  • The /task/query GET rest call takes the following query parameters:

    • workItemId
    • taskId
    • businessAdministrator
    • potentialOwner
    • taskOwner
    • processInstanceId
    • status and
    • union

  • At the moment, although the name of a parameter is interpreted regardless of case, please make sure use the appropriate case for the values of the parameters.

Examples

First a few examples that show how the query operation works with various query parameters:

  • This retrieves the task summaries of all tasks that have a work item id of 3, 4, or 5.

    http://server:port/rest/task/query?workItemId=3&workItemId=4&workItemId=5

  • This will retrieve any task summaries for which the task id is 27 and the work item id is 11.

    http://server:port/rest/task/query?workItemId=11&taskId=27

  • This will retrieve any task summaries for which the task id is 27 or the work item id is 11. Note that the union parameter is being used here so that the union of the two queries (the work item id query and the task id query) is returned.

    http://server:port/rest/task/query?workItemId=11&taskId=27&union=true

  • This will retrieve any task summaries for which the status is Created and the potential owner of the task is Bob. Note that the letter case for the status parameter value is case insensitve.

    http://server:port/rest/task/query?status=creAted&potentialOwner=Bob

  • This will return any task summaries for which the status is Created and the potential owner of the task is bob. Note that the potential owner parameter is case sensitive. bob is not the same user id as Bob!

    http://server:port/rest/task/query?status=created&potentialOwner=bob

  • This will return the intersection of the following 3 queries:

    • Task summaries for which the process instance id is 201

    • Task summaries for which the potential owner is bob

    • Task summaries for which the status is Created or Ready.

      http://server:port/rest/task/query?status=created&status=ready&potentialOwner=bob&processInstanceId=201

    • So, this means that the following task summaries would be included:

      • process instance id = 201, potential owner bob, status Ready
      • process instance id = 201, potential owner bob, status Created

    • And the following task summaries will not be included:

      • process instance id = 183, potential owner bob, status Created
      • process instance id = 201, potential owner mary, status Ready
      • process instance id = 201, potential owner mary, status Complete

Explanation

  • The available (case insensitive) values for the status parameter are the following :

      Created, Ready, Reserved, InProgress, Suspended, Completed, Failed, Error, Exited, Obsolete

    These values correspond to the values of the enum org.kie.api.task.model.Status.

Retrieving Task Content

The task/content/{contentId: \\d+} and task/{taskId: \\d+}/content operations both return the serialized content associated with a task.

Content associated with a task is stored in the human-task database schema in serialized form. Whether the content is a string (with xml content) or a (hash-)map with several different key-value pairs, this content is serialized using the protobuf based algorithm that jbpm uses. This serialization process is normally carried out by the static methods in the org.jbpm.services.task.utils.ContentMarshallerHelper class.

However, clients that call the rest operations may not necessarily have access to this class, which is why the any objects present in the task content are first deserialized using the ContentMarshallerHelper class and then serialized using the normal Java serialization mechanism.

However, there are limits on what can be returned by these rest operations. Only the following objects can be returned by the task content operations:

  • Task content can be returned by get task content rest operations if the content is one of two types of objects:
    • An instance of a class that implements the Serializable interface.
    • An instance of a Map<String, Object>, which only contains values that implement the Serializable interface.
  • Furthermore, for all instances of the Serializable interface mentioned above, these instances must also: - NOT be an instance of a local class, an anonymous class or an array of a local or anonymous class - be present in the class path of the server
Clone this wiki locally