GraphQL API

Overview

WorkflowGen version 7.0.0 introduces the new GraphQL API, which is a modern solution to create process-driven solutions such as mobile apps, web apps, and microservices that require a powerful workflow and BPM engine.

The WorkflowGen GraphQL API is a Node.js application that runs in IIS using iisnode. It enables a high level of customization such as extending the GraphQL schema with custom types, queries or operations, or implementing new authentication methods.

You can use GraphiQL, "a graphical interactive in-browser GraphQL IDE", to test queries and operations, and to browse the schema documentation.

The GraphQL API is in Alpha phase. All of the queries and operations used by the mobile application have been implemented. The next releases will provide of the remaining User Portal and Administration Module operations.

About GraphQL

From the GraphQL website presentation:

"GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools."

GraphQL is a production-ready and an open source technology created by Facebook. In September 2016, GitHub announced its GraphQL API.

"We’ve often heard that our REST API was an inspiration for other companies; countless tutorials refer to our endpoints. Today, we’re excited to announce our biggest change to the API since we snubbed XML in favor of JSON: we’re making the GitHub API available through GraphQL."

GraphQL is a modern API solution for React, React Native, Angular 2, and Vue based applications.

Many GraphQL tutorials are available, it's available in many languages, and it has a large community.

Technical requirements

In addition to the standard WorkflowGen installation, the following components are required:

For information on the installation procedure, see the WorkflowGen Technical Guide.

Endpoints

The following endpoints are available:

  • GraphQL API: http://localhost/wfgen/graphql

  • GraphiQL IDE: http://localhost/wfgen/graphql

  • GraphQL Schema (definition language): http://localhost/wfgen/graphql/schema

The HTTP GET method is supported on queries only. The HTTP POST method is supported on queries and operations.

Using GraphiQL IDE in a web browser

You can use GraphiQL, "a graphical interactive in-browser GraphQL IDE", to test queries and operations, and to browse the schema documentation.

HTTP usage

Express-graphql is used to serve the GraphQL HTTP queries:

GraphQL will first look for each parameter in the URL's query-string: /graphql?query=query+getUser($id:ID){user(id:$id){name}}&variables={"id":"4"} If not found in the query-string, it will look in the POST request body. If the POST body has not yet been parsed, express-graphql will interpret it depending on the provided Content-Type header:

  • application/json: the POST body will be parsed as a JSON object of parameters.

  • application/x-www-form-urlencoded: this POST body will be parsed as a url-encoded string of key-value pairs.

  • application/graphql: the POST body will be parsed as GraphQL query string, which provides the query parameter.

Curl example

curl -u yourusername -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'query={
  viewer {
    userName
    lastName
    firstName
    email
  }
}' "http://localhost/wfgen/graphql"

And the result is:

{
  "data": {
    "viewer": {
      "userName": "johndoe",
      "lastName": "Doe",
      "firstName": "John",
      "email": "john.doe@acme.com"
    }
  }
}

Authentication

The following authentication methods are supported:

  • IIS Basic

  • WorkflowGen authentication

  • Custom .NET authentication modules

Note: If your WorkflowGen site is configured with Integrated Windows or Basic authentication, you must configure GraphQL with Basic authentication.

HTTPS is required to secure credentials.

The GraphQL Node.js app code inside the \wfgen\graphql folder can also be customized to accommodate many other authentication methods (such as OAuth2, JWT, etc.) thanks to node libraries such as Passport.js.

User impersonation

User impersonation is supported but not recommended, and should be used only when no other technical solutions are possible. (For example, OpenID Connect-based authentication methods allow you to use access tokens to perform API operations on the client and server sides without impersonation.)

System operations allowed users can impersonate another WorkflowGen user account by setting this account's username as the value of the x-wfgen-impersonate-username HTTP request header.

This request header can be renamed according to your naming convention. You can specify a new header name in the GraphqlImpersonateUserNameHttpHeader setting in the \wfgen\web.config file (e.g. <add key="GraphqlImpersonateUserNameHttpHeader" value="my-custom-impersonate-username" />).

To give or withdraw system operations rights to or from specific users, refer to the System operations allowed users setting in the Security section on the General tab of the Configuration Panel; alternately, you can edit the ProcessesRuntimeWebServiceAllowedUsers setting in the \wfgen\web.config\ file.

Delegation management

Some GraphQL queries and operations can be executed on behalf of another user. This is possible when a user has created a delegation in WorkflowGen. The delegatee has to specify the user ID of their delegator in the onBehalfOf argument.

List of actions to do on by the delegatee on behalf of the delegator with the user ID VXNlcjoy:

{
  viewer {
    actions(filter: {as: ASSIGNEE, status: OPEN}, onBehalfOf:"VXNlcjoy"}) {
      totalCount
      hasNextPage
      hasPreviousPage
      items {
        request {
          number
          description
        }
        number
        name
        description
        limit
        launchUrl
      }
    }
  }
}

When the onBehalfOf argument is set, it is propagated implicitly to the all the sub-queries and fields until a User type is used.

Global identifiers

Each GraphQL type has an id: ID! field. This ID is global and is unique for all WorkflowGen objects.

You can use the node(id:ID!) query to retrieve a WorkflowGen object by its ID.

{
  node(id: "UHJvY2VzczoxNQ==") {
    id
    ... on Request {
      number
      requester {
        lastName
      }
    }
    ... on Action {
      limit
      assignee {
        id
        company
      }
    }
    ... on User {
      userName
      email
    }
  }
}

GraphQL operations

You can copy/paste these queries directly in the GraphiQL IDE. See the Using GraphiQL IDE in a web browser section above for more information.

Using Curl

curl -u yourusername -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'query={
  viewer {
    userName
    lastName
    firstName
    email
  }
}' "http://localhost/wfgen/graphql"

And the result is:

{
  "data": {
    "viewer": {
      "userName": "johndoe",
      "lastName": "Doe",
      "firstName": "John",
      "email": "john.doe@acme.com"
    }
  }
}

Viewer basic info (the authenticated user)

{
  viewer {
    userName
    lastName
    firstName
    email
  }
}

My actions to do

{
  viewer {
    actions(filter: {as: ASSIGNEE, status: OPEN}) {
      totalCount
      hasNextPage
      hasPreviousPage
      items {
        request {
          number
          description
        }
        number
        name
        description
        limit
        launchUrl
      }
    }
  }
}

Fetch a request by its number

{
  request(number: 273) {
    description
    requester {
      lastName
      userName
      company
    }
    process {
      name
      version
    }
  }
}

Create a new request

Note: To create a new request from the GraphQL API, make sure that sub-process mode is enabled with public access on the target process. (See the Process form section in the WorkflowGen Administration Guide for more information.)

Request payload:

mutation {
  createRequest(input: {processName: "2_LEVELS_APPROVAL", processVersion: 1}) {
    request {
      id
      name
      number
    }
  }
}

Response payload:

{
  "data": {
    "createRequest": {
      "request": {
        "id": "UmVxdWVzdDoxNQ==",
        "name": "2_LEVELS_APPROVAL #15",
        "number": 15
      }
    }
  }
}

A parameter's array can be included in the createRequest operation payload. Be aware that a data with the same name and data type must previously exist in the process for each parameter in the array to store the parameter's value. The following example shows how to send parameters corresponding to the four supported data types (TEXT, NUMERIC, DATETIME, and FILE).

Request payload:

mutation {
  createRequest(input: {processName: "SR", processVersion: 1, parameters: [{name: "TEXT", textValue: "My text parameter"}, {name: "NUMERIC", numericValue: 5}, {name: "DATE", dateTimeValue: "2017-02-23T20:46:00Z"}, {name: "FILE", fileValue: {name: "TestFile.txt", contentType: "text/plain", size: 616, url: "file:///c:/TestFile.txt", updatedAt: "2017-02-21T15:06:38Z"}}]}) {
    request {
      id
      name
      number
    }
  }
}

Response payload:

{
  "data": {
    "createRequest": {
      "request": {
        "id": "UmVxdWVzdDoxNg==",
        "name": "2_LEVELS_APPROVAL #16",
        "number": 16
      }
    }
  }
}

Cancel a request

You can cancel a request by using the request number or the request ID.

Request payload:

mutation {
  cancelRequest(input: {number: 15}) {
    request {
      id
      name
      number
      status
    }
  }
}

Response payload:

{
  "data": {
    "cancelRequest": {
      "request": {
        "id": "UmVxdWVzdDoxNQ==",
        "name": "SR #15",
        "number": 15,
        "status": "CLOSED"
      }
    }
  }
}

Complete an action

To complete an action, provide the request number and the action number, or the action ID.

Request payload:

mutation {
  completeAction(input: {requestNumber: 16, number: 1}) {
    action {
      id
        status
    }
  }
}

Response payload:

{
  "data": {
    "completeAction": {
      "action": {
        "id": "QWN0aW9uOjE2LS0tMQ==",
        "status": "CLOSED"
      }
    }
  }
}

To complete an action, a parameter array can be included in the request payload arguments.

Request payload:

mutation {
  completeAction(input: {requestNumber: 20, number: 1, parameters: [{name: "NEW_PARAMETER", textValue: "My parameter"}]}) {
    action {
      id
        status
    }
  }
}

Response payload:

{
  "data": {
    "completeAction": {
      "action": {
        "id": "QWN0aW9uOjIwLS0tMQ==",
        "status": "CLOSED"
      }
    }
  }
}

Cancel an action

To cancel an action, provide the request number and the action number, or the action ID. The following conditions must be met:

  • The viewer and the user (if they don't share the same identity, as in delegation mode) must have access to the request.

  • The action must be open.

  • The action must have a cancel or default exception defined in the transition.

  • The viewer is:

    • an administrator or process folder manager OR

    • a supervisor with cancellation rights OR

    • the action assignee.

Request payload:

mutation {
  cancelAction(input: {requestNumber: 21, number: 1}) {
    action {
      id
        status
    }
  }
}

Response payload:

{
  "data": {
    "cancelAction": {
      "action": {
        "id": "QWN0aW9uOjIxLS0tMQ==",
        "status": "CLOSED"
      }
    }
  }
}

Assign an action

To assign an action, provide the request number and the action number, or the action ID; you must also provide the assigneeUserName or the assigneeId.

Request payload:

mutation {
  assignAction(input: {requestNumber: 22, number: 1, assigneeId: "VXNlcjox"}) {
    action {
      id
      assignee {
        id
      }
    }
  }
}

Response payload:

{
  "data": {
    "assignAction": {
      "action": {
        "id": "QWN0aW9uOjIyLS0tMQ==",
        "assignee": {
          "id": "VXNlcjox"
        }
      }
    }
  }
}

Cancel an action assignment

To cancel an action assignment, you should provide the request number and the action number, or the action ID.

Request payload:

mutation {
  cancelActionAssignment(input: {requestNumber: 22, number: 1}) {
    action {
      id
      assignee {
        id
      }
    }
  }
}

Response payload:

{
  "data": {
    "cancelActionAssignment": {
      "action": {
        "id": "QWN0aW9uOjIyLS0tMQ==",
        "assignee": null
      }
    }
  }
}

Update request dataset

A request dataset context can be updated by adding a parameter array. In this case a request number or a request ID should be provided.

Request payload:

mutation {
  updateRequestDataset(input: {number: 22, parameters: {name: "TEXT", textValue: "My text parameter"}}) {
    dataset {
      items {
        name
        textValue
      }
    }
  }
}

Response payload:

{
  "data": {
    "updateRequestDataset": {
      "dataset": {
        "items": [
          {
            "name": "TEXT",
            "textValue": "My text parameter"
          }
        ]
      }
    }
  }
}

Pagination

The GraphQL API supports page number based pagination. You can set a page number and a size; otherwise, the default values are:

  • 1 for the page number

  • 30 for the page size

The maximum value for the page size is 100. You can change this setting in the GraphqlMaxPageSize key in the /wfgen/web.config file.

The result contains:

  • totalCount: The total number of items

  • hasPreviousPage

  • hasNextPage

  • items: The list of items in the requested page

{
  viewer {
    requests(page: {number: 2, size: 20}, filter: {as: REQUESTER, status: OPEN}, orderBy: {field: NUMBER, direction: DESC}) {
      totalCount
      hasNextPage
      hasPreviousPage
      items {
        id
        number
        requester {
          userName
        }
      }
    }
  }
}

To retrieve the total count without the list of items, you just need to set the page number to 0:

{
  viewer {
    requests(page: {number: 0}, filter: {as: REQUESTER, status: OPEN}) {
      totalCount
      hasNextPage
      hasPreviousPage
    }
  }     
}

viewerAsMember field usage

The viewerAsMember field is a Boolean parameter that determines if the viewer has standard user access scope, even if they have an administrator or a process folder manager profile. It can be used by the user(userName:"XXX").requests, user(userName:"XXX").comments, and user(userName:"XXX").actions queries when an administrator or a process folder manager tries to access another user's requests, comments, or actions with a standard user scope.

In the following payload example, an administrator would be able to access Jane Doe's requests, comments, and actions with a standard user access scope:

{
  user(userName: "jane_doe") {
    requests(viewerAsMember: true) {
      totalCount
      hasPreviousPage
      hasNextPage
      items {
        id
        number
      }
    }
    actions(viewerAsMember: true) {
      totalCount
      hasPreviousPage
      hasNextPage
      items {
        id
        number
        request {
          number
        }
      }
    }
    comments(viewerAsMember: true) {
      totalCount
      hasPreviousPage
      hasNextPage
      items {
        id
        subject {
          id
        }
        message
        author {
          id
        }
      }
    }
  }
}

Logs

All HTTP queries are logged by IIS as other ASP.NET web apps. Node.js application logs are available in the \wfgen\graphql\iisnode\ folder. You can adjust the iisnode log file management in the \wfgen\graphql\web.config file.

Debug mode

A debug mode can be enabled by setting the GraphqlDebugEnabled key to Y in the \wfgen\web.config file.

In debug mode, some extensions are added to the GraphQL response, and additional error messages are logged in the \wfgen\graphql\iisnode\ folder.

Known limitations of the Alpha release

The actions and requests queries don't support all argument combinations.

You must specify additional arguments (such as filter: { as: REQUESTER }).

In this example the requests and actions queries return empty lists:

{
  viewer {
    requests {
      totalCount
      hasNextPage
      hasPreviousPage
    }
    actions {
      totalCount
      hasNextPage
      hasPreviousPage
    }
  }
}

GraphQL desktop client

If you need to work in GraphQL without an internet connection, you can use the Altair GraphQL Client for offline access.

PreviousOverviewNextWeb Services API

Last updated