Activiti Cloud Notification Service

In order to provide a scalable notification service, we evaluated GraphQL and the integration with messaging systems such as RabbitMQ to provide reliable Subscription based mechanism where users can register interest in certain events emitted by the core building blocks. For now this endpoint is available as ACTIVITI_ADMIN role only.
GraphQL Query Endpoint
The GraphQL Query API provides single entry GraphQL query endpoint at /graphql URI with support for expressive process entity schema and type-safe query criteria expressions in order to execute flexible, fast and declarative data queries for consumer applications.
Supported HTTP Methods, Headers, and Body
Activiti GraphQL Rest Controller handles both HTTP GET and POST method requests.
GET requests
When receiving an HTTP GET request, the GraphQL query should be specified in the query parameter. For example, if we wanted to execute the following GraphQL query:
1
{
2
  ProcessInstance(processInstanceId:"1") {
3
    processInstanceId
4
    tasks {
5
      id
6
      name
7
    }
8
  }
9
}
Copied!
This request could be sent via an HTTP GET like so:
http://host/graphql?query={ProcessInstance(processInstanceId:"1"){processInstanceId,tasks{id,name}}}
Query variables can be sent as a JSON-encoded string in an additional query parameter called variables.
POST requests
A standard GraphQL POST request uses the application/json content type, and includes a JSON-encoded body of the following form:
1
{
2
  "query": "query($id: String) { ProcessInstance(processInstanceId: $id) { processInstanceId, tasks { id, name } } }",
3
  "variables": { "id": "value" }
4
}
Copied!
The field variables is optional.
In addition to the above, ActivitiQraphQLController supports the following cases:
If the application/x-www-form-urlencoded Content-Type header is present in the POST request, the GraphQL query should be specified in the query parameter string. Query variables can be sent as a JSON-encoded string in an additional query parameter called variables.
If the "application/graphql" Content-Type header is present, treat the HTTP POST body contents as the GraphQL query string.
GraphQL Query Response
Regardless of the method by which the query and variables were sent, the response is returned in the body of the request in JSON format.
1
{
2
  "data": {
3
    "ProcessInstance": {
4
      "processInstanceId": "1",
5
      "tasks": [
6
        {
7
          "id": "4",
8
          "name": "task4",
9
          "assignee": "assignee",
10
          "status": "COMPLETED",
11
        },
12
        {
13
          "id": "5",
14
          "name": "task5",
15
          "assignee": "assignee",
16
          "status": "COMPLETED",
17
        }
18
      ]
19
    }
20
  },
21
  "errors": null
22
}
Copied!
If there were no errors returned, the "errors" field will be null in the response object.
GraphQL Query Schema
Activiti GraphQL query endpoint provides schema descriptions derived from JPA entity model at runtime for the following entities: ProcessInstance, Task, ProcessVariable and TaskVariable. The schema also derives GraphQL scalar types from JPA entity model attributes to validate provided variable values against the schema.
Each entity in the query model is wrapped into two GraphQL query fields, i.e. ProcessInstance entity will have two representations in the GraphQL schema:
One that models the entity directly using singular form, i.e. ProcessInstance or Task to query single entity instance by id argument.
One that wraps the entity in a pagable query request with where criteria expression using Entity pluralized form, i.e. ProcessInstances or Tasks
For example, you can use singular query wrapper, if you need a single object as root of your query:
1
query {
2
  ProcessInstance(processInstanceId:"1") {
3
    processInstanceId
4
    tasks {
5
      id
6
      name
7
      assignee
8
      status
9
    }
10
  }
11
}
Copied!
Will return:
1
{
2
  "ProcessInstance": {
3
    "processInstanceId": "1",
4
    "tasks": [
5
      {
6
        "id": "4",
7
        "name": "task4",
8
        "assignee": "assignee",
9
        "status": "ASSIGNED"
10
      },
11
      {
12
        "id": "5",
13
        "name": "task5",
14
        "assignee": "assignee",
15
        "status": "COMPLETED"
16
      }
17
    ]
18
  }
19
}
Copied!
GraphQL Pluralized Query Wrapper with Where Criteria Expressions
This GraphtQL schema supports flexible type safe criteria expressions with familiar SQL query syntax semantics using where arguments int the select query field to use any combination of logical expressions like OR, AND, EQ, NE, GT, GE, LT, LR, IN, NIN, IS_NULL, NOT_NULL, BETWEEN, NOT_BETWEEN provided by SQL query language.
For example, the following query will find all running process instances with active tasks:
1
query {
2
  ProcessInstances(where: {
3
    status: { IN: RUNNING }
4
  }) {
5
    select {
6
      processInstanceId
7
      status
8
      tasks(where: {status: {IN: [CREATED,ASSIGNED] }}) {
9
        id
10
        name
11
        assignee
12
        status
13
      }
14
    }
15
  }
16
}
Copied!
Will return
1
{
2
  "ProcessInstances": {
3
    "select": [
4
      {
5
        "processInstanceId": "0",
6
        "status": "RUNNING",
7
        "tasks": [
8
          {
9
            "id": "1",
10
            "name": "task1",
11
            "assignee": "assignee",
12
            "status": "ASSIGNED"
13
          }
14
        ]
15
      },
16
      {
17
        "processInstanceId": "1",
18
        "status": "RUNNING",
19
        "tasks": [
20
          {
21
            "id": "5",
22
            "name": "task5",
23
            "assignee": "assignee",
24
            "status": "ASSIGNED"
25
          }
26
        ]
27
      }
28
    ]
29
  }
30
}
Copied!
GraphQL Reverse Query
You can execute an inverse query to fitler results with a join in many-to-one association.
For Example:
1
query {
2
  Tasks {
3
    select {
4
      name
5
      assignee
6
      status
7
      processInstance(where: {processInstanceId: {EQ: "1"}}) {
8
        processInstanceId
9
        status
10
      }
11
      variables {
12
        name
13
        type
14
        value
15
      }
16
    }
17
  }
18
}
Copied!
Will return result:
1
{
2
  "Tasks": {
3
    "select": [
4
      {
5
        "name": "task4",
6
        "assignee": "assignee",
7
        "status": "Running",
8
        "processInstance": {
9
          "processInstanceId": "1",
10
          "status": "RUNNING"
11
        },
12
        "variables": [
13
          {
14
            "name": "variable5",
15
            "type": "String",
16
            "value": "value5"
17
          },
18
          {
19
            "name": "variable6",
20
            "type": "String",
21
            "value": "value6"
22
          }
23
        ]
24
      },
25
      {
26
        "name": "task5",
27
        "assignee": "assignee",
28
        "status": "COMPLETED",
29
        "processInstance": {
30
          "processInstanceId": 1,
31
          "status": "RUNNING"
32
        },
33
        "variables": []
34
      }
35
    ]
36
  }
37
}
Copied!
GraphQL Paged Queries
Use plural query wrapper with Where Criteria Expressions to run complex queries with paged collection results and request total records and pages counts:
1
query {
2
  ProcessInstances(page: {start:1, limit:1}) {
3
    pages
4
    total
5
    select {
6
      processInstanceId
7
      tasks {
8
        id
9
        name
10
        assignee
11
        status
12
      }
13
    }
14
  }
15
}
Copied!
The result will be:
1
{
2
  "ProcessInstances": {
3
    "pages": 2,
4
    "total": 2,
5
    "select": [
6
      {
7
        "processInstanceId": 0,
8
        "tasks": [
9
          {
10
            "id": "2",
11
            "name": "task2",
12
            "assignee": "assignee",
13
            "status": "RUNNING"
14
          },
15
          {
16
            "id": "3",
17
            "name": "task3",
18
            "assignee": "assignee",
19
            "status": "RUNNING"
20
          },
21
          {
22
            "id": "1",
23
            "name": "task1",
24
            "assignee": "assignee",
25
            "status": "COMPLETED"
26
          }
27
        ]
28
      }
29
    ]
30
  }
31
}
Copied!
To optimize query performance, the GraphQL Query DataFetcher implementation will execute an extra query to get the total elements only if you have requested 'pages' or 'total' fields.
GraphQL Query Sorting
Sorting is supported on any field. Simply pass in an 'orderBy' argument with the value of ASC or DESC in the query field attribute. Here's an example of sorting by name for Task objects. If sort order is not specified and there is no field with default sort order provided, query data fetcher use the identity field for default sorting in order to avoid paging confusions.
For Example:
1
query {
2
  Tasks {
3
    select {
4
      id
5
      name(orderBy:DESC)
6
      assignee
7
      status
8
    }
9
  }
10
}
Copied!
Will Return:
1
{
2
  "Tasks": {
3
    "select": [
4
      {
5
        "id": "5",
6
        "name": "task5",
7
        "assignee": "assignee",
8
        "status": "Completed"
9
      },
10
      {
11
        "id": "4",
12
        "name": "task4",
13
        "assignee": "assignee",
14
        "status": "Running"
15
      },
16
      {
17
        "id": "3",
18
        "name": "task3",
19
        "assignee": "assignee",
20
        "status": "Running"
21
      },
22
      {
23
        "id": "2",
24
        "name": "task2",
25
        "assignee": "assignee",
26
        "status": "Running"
27
      },
28
      {
29
        "id": "1",
30
        "name": "task1",
31
        "assignee": "assignee",
32
        "status": "Completed"
33
      }
34
    ]
35
  }
36
}
Copied!
Variable Parameter Bindings
Just like a REST API, it is possible to pass arguments to an endpoint in a GraphQL API. By declaring the arguments in the query defintion, typechecking happens automatically. Each argument must be named with $ prefix, have a type. To use variable, simply reference it in any criteria expressions inside query statements. Each argument's value will be resolved during query execution pipeline.
1
{
2
   "query": "query($status: String!) {
3
      ProcessInstances(where: {
4
        OR: {
5
          status: { EQ: $status}
6
        }
7
      }) {
8
        select {
9
          processInstanceId
10
          status
11
          tasks(where: {status: {EQ: COMPLETED}}) {
12
            id
13
            name
14
            assignee
15
            status
16
          }
17
        }
18
      }
19
    }
20
  ",
21
   "variables":{"status":"RUNNING"}
22
}
Copied!
GraphQL Query Performance
The Activiti GraphQL Data Fetcher implementation will build dynamic JPA fetch graph in order to minimize the number of queries executed against database in order to avoid 1+N lazy loading problems.
How to demo Activiti GraphQL Query API
The GraphiQL app browser can be used for simple testing. It provides schema documentation browser and query builder with auto-completion support, as well as parameter bindings.
Then, navigate to http://host/notifications/graphiql to load GraphiQL browser. Use hradmin or testadmin user to login.
The collapsed Docs panel can opened by clicking on the button in the upper right corner to expose current test schema models.
You can run GraphQL queries in the left pannel. Type the query and hit the run button. The results should come up in the middle panel. If your query has variables, there is a minimized panel at the bottom left. Simply click on this to expand, and type in your variables as a JSON string with quoted keys.
GraphQL Subscription API
Activiti Notifications GraphQL Query endpoint provides a universal mechanism to execute declarative queries using a complete and understandable schema description of the process instance, task and variable data that gives users the power to ask for exactly what they need in the shape they want. However, often times users want to get pushed updates from the server when data they care about changes. To support that, we are introducing support for GraphQL Subscriptions that offers real-time data updates with subscriptions and push data notifications in near real-time over WebSockets.
How it works
Notifications Service GraphQL Subscriptions implementation leverages Spring’s WebSocket Message Broker to provide real-time full duplex communication between client application and backend Notification service.
The root of GraphQL Subscription type provides engineEvents query field to subscribe to ProcessEngineNotification type:
1
type Subscription {
2
  engineEvents (
3
      serviceName : String, 
4
      appName : String, 
5
      processDefinitionKey : String,
6
      processInstanceId : String,
7
      businessKey : String 
8
  ) : ProcessEngineNotification
9
}
Copied!
The ProcessEngineNotification type provides data fiels to specify any combination of EVENT_TYPES you may want to receive as part of the notifcation payload:
1
type ProcessEngineNotification {
2
    serviceName : String
3
    appName : String 
4
    processDefinitionKey : String 
5
    processInstanceId : String 
6
    businessKey : String 
7
    PROCESS_STARTED : [PROCESS_STARTED]
8
    PROCESS_COMPLETED : [PROCESS_COMPLETED]
9
    PROCESS_CREATED : [PROCESS_CREATED]
10
    PROCESS_CANCELLED : [PROCESS_CANCELLED]
11
    PROCESS_RESUMED : [PROCESS_RESUMED]
12
    PROCESS_SUSPENDED : [PROCESS_SUSPENDED]
13
    ACTIVITY_STARTED : [ACTIVITY_STARTED]
14
    ACTIVITY_CANCELLED : [ACTIVITY_CANCELLED]
15
    ACTIVITY_COMPLETED : [ACTIVITY_COMPLETED]
16
    VARIABLE_CREATED : [VARIABLE_CREATED]
17
    VARIABLE_UPDATED : [VARIABLE_UPDATED]
18
    VARIABLE_DELETED : [VARIABLE_DELETED]
19
    SEQUENCE_FLOW_TAKEN : [SEQUENCE_FLOW_TAKEN]
20
    TASK_CREATED : [TASK_CREATED]
21
    TASK_COMPLETED : [TASK_COMPLETED]
22
    TASK_ASSIGNED : [TASK_ASSIGNED]
23
    TASK_ACTIVATED : [TASK_ACTIVATED]
24
    TASK_SUSPENDED : [TASK_SUSPENDED]
25
    TASK_CANCELLED : [TASK_CANCELLED]
26
    INTEGRATION_REQUESTED : [INTEGRATION_REQUESTED]
27
    INTEGRATION_RESULT_RECEIVED : [INTEGRATION_RESULT_RECEIVED]
28
    TASK_CANDIDATE_USER_ADDED: [TASK_CANDIDATE_USER_ADDED]
29
    TASK_CANDIDATE_USER_REMOVED: [TASK_CANDIDATE_USER_REMOVED]
30
    TASK_CANDIDATE_GROUP_ADDED: [TASK_CANDIDATE_GROUP_ADDED]
31
    TASK_CANDIDATE_GROUP_REMOVED: [TASK_CANDIDATE_GROUP_REMOVED]
32
}
Copied!
Each EVENT_TYPE defines its own unique attributes, i.e. PROCESS_STARTER event type defines the following fields:
1
type PROCESS_STARTED {
2
    serviceName : String
3
    serviceFullName : String
4
    serviceVersion : String
5
    serviceType : String
6
    appName : String
7
    appVersion : String
8
    entityId : String
9
​
10
    id : String
11
    timestamp : Long
12
    entity : ProcessInstanceType
13
    eventType : String
14
​
15
    nestedProcessDefinitionId : String
16
    nestedProcessInstanceId : String    
17
}
Copied!
It also contains embedded entity field of type ProcessInstanceType having the following attributes:
1
type ProcessInstanceType {
2
    id : String
3
    parentId : String
4
    name : String
5
    description : String
6
    processDefinitionId : String
7
    processDefinitionKey : String
8
    processDefinitionVersion : Long
9
    businessKey: String
10
    initiator : String
11
    startDate : String
12
    status : String
13
}
Copied!
Activiti Cloud Audit Service
Activiti Cloud Modeling
Last modified 4mo ago
Copy link
Contents
GraphQL Query Endpoint
Supported HTTP Methods, Headers, and Body
GraphQL Query Schema
GraphQL Pluralized Query Wrapper with Where Criteria Expressions
GraphQL Reverse Query
GraphQL Paged Queries
GraphQL Query Sorting
Variable Parameter Bindings
GraphQL Query Performance
How to demo Activiti GraphQL Query API
GraphQL Subscription API
How it works