API

Key features

Our API is based on GraphQL and allows you to, among others:

• Retrieve projects and project versions
• Retrieve all types of Sensus elements from the projects
• Retrieve all template data
• Add custom category items and groups
• Add template information for basic template fields

Getting access

To get access to our API, please contact contact us at info@sensus-processmanagement.com. API acccess must be part of your contract in order to access it.

Accessing the API works via JSON Web Token / JWT which can be generated by the Account Owners themselves in the Portal. After contacting Sensus for the API access you will be provided with additional information:

• API url (API_URL)

Together with the JWT (JWT) and the above information it is possible to contact our GraphQL API.

Please read the chapter "Creating a service user and JWT" to generate a JWT.

GraphQL

GraphQL is used since it provides a lot of benefits over typical REST API's for our use-case:

• The Sensus data model is very hierarchical with a lot of cross cutting links, which makes a default JSON / XML api difficult.
• GraphQL allows the API-consumer to specifically fetch the fields needed from the model
• It is strictly type based and as such it is self-documenting. By using proper tooling (like GraphQL Playground) it is possible to introspect the schema and navigate through the type hierarchy.

It is advised to read the documentation of GraphQL in order to fully understand how to use it.

Querying the API

POST Request

All the API requests are done via a POST request to the API_URL. The following headers need to be present:

• Authorization: Bearer JWT
• Content-Type: application/json
• Accept: application/json

A POST request is then performed with the following request body:

{
  "query": "QUERY",
  "operationName": "OPERATION_NAME", //optional
  "variables": "VARIABLES" // optional
}

Where QUERY is a JSON-escaped string of the GraphQL query. OPERATION_NAME is optional a different operation name is used. VARIABLES is optional and is a JSON structure with variables to be used. Please refer to the documentation of GraphQL to understand exactly how this request works.

Guids

All elements within the Sensus data model are referred to with GUIDs (or UUIDs). This guarantees an almost unique identifier for every element in our model so it will appear often in GraphQL requests and responses.

First query

To check if everything works, the following query can be run to retrieve the licenses currently available to you:

{
  "query": "{ licenses { guid, name } }"
}

This will result in a similar response:

{
  "data": {
    "licenses": [
      {
        "guid": "00000000-ffff-aaaa-bbbb-cccccccccccc", // a GUID of your license
        "name": "Your license name"
      }
    ]
  }
}

If you get a similar response, everything works correctly.

Example queries

Here are some example queries to get you started. Please note that we are only showing the GraphQL query and not the escaped version to be used in the POST request.

Get all projects and their guids

Query

query Example($licenseGuid: UUID!) {
  licenseByGuid(guid: $licenseGuid) {
    projects {
      guid
      name
    }
  }
}

Variables

{
  "licenseGuid": "your license guid"
}

Get a specific project and the version data

Query

query Example($licenseGuid: UUID!, $projectGuid: UUID!) {
  project(licenseGuid: $licenseGuid, projectGuid: $projectGuid) {
    name
    versions {
      guid
      state
      finalizeDate
    }
  }
}

Variables

{
  "licenseGuid": "your license guid",
  "projectGuid": "a project guid"
}

Get the a version of a project and get the full process tree of all processes

Query

query Example(
  $licenseGuid: UUID!
  $projectGuid: UUID!
  $projectVersionGuid: UUID!
) {
  projectVersion(
    licenseGuid: $licenseGuid
    projectGuid: $projectGuid
    projectVersionGuid: $projectVersionGuid
  ) {
    processes {
      organisations {
        guid
        totalSequence
        name
        themes {
          guid
          totalSequence
          name
          mainProcesses {
            guid
            totalSequence
            name
            processes {
              guid
              totalSequence
              name
              activities {
                guid
                totalSequence
                name
              }
            }
          }
        }
      }
    }
  }
}

Variables

{
  "licenseGuid": "your license guid",
  "projectGuid": "a project guid",
  "projectVersionGuid": "a projectversion guid"
}

Further information

The full schema is available via introspection using a GraphQL tool like GraphQL Playground. ## Assistance

Please note that any assistance in integrating the Sensus API in your own applications is not part of the contract with Sensus. If involvement is needed from Sensus to use the API, please contact us to assess the needs and possible costs involved.