GraphQL for Camunda Platform 7
APACHE-2.0 License
Camunda Platform GraphQL is a Community Extension for Camunda Platform 7 that allows you to use GraphQL to query and mutate Process Engine data in a simple way.
In your Camunda Spring Boot project add the following dependencies
Gradle
Camunda Extension GraphQL
implementation group: 'org.camunda.platform7.extension.graphql', name: 'camunda-platform-7-graphql', version: '0.5.0'
Spring Boot GraphQL Kickstart (the version 11.1.0 or higher)
implementation group: 'com.graphql-java-kickstart', name: 'graphql-spring-boot-starter', version: '11.1.0'
implementation group: 'com.graphql-java-kickstart', name: 'graphiql-spring-boot-starter', version: '11.1.0'
implementation group: 'com.graphql-java-kickstart', name: 'graphql-java-tools', version: '11.0.1'
Maven
Camunda Extension GraphQL
<dependency>
<groupId>org.camunda.platform7.extension.graphql</groupId>
<artifactId>camunda-platform-7-graphql</artifactId>
<version>0.5.0</version>
</dependency>
Spring Boot GraphQL Kickstart (the version 11.1.0 or higher)
<dependency>
<groupId>com.graphql-java-kickstart</groupId>
<artifactId>graphql-spring-boot-starter</artifactId>
<version>11.1.0</version>
</dependency>
<dependency>
<groupId>com.graphql-java-kickstart</groupId>
<artifactId>graphiql-spring-boot-starter</artifactId>
<version>11.1.0</version>
</dependency>
<dependency>
<groupId>com.graphql-java-kickstart</groupId>
<artifactId>graphql-java-tools</artifactId>
<version>11.0.1</version>
</dependency>
Use the example if necessary.
By default the GraphQL and GraphiQL are available at the uri /graphql and /graphiql respectively, this configuration and others can be change by properties. The available settings can be consulted directly in the project of Spring Boot GraphQL Kick Start
extension/src/main/resources/application.properties
:
mvn clean package
mvn clean package -Pwildfly
.war
file) from theFor WildFly you have to clone the project and build the .war
file.
See chapter Build the GraphQL server.
http://<server-name>:<PORT>/camunda-graphql/graphql/?query=
{here is your query} http://<server-name>:<PORT>/camunda-graphql/graphiql/
Beside the build-in GraphiQL you can use other GraphQL clients. Basically...
http://<server-name>:<PORT>/camunda-graphql/graphql
Examples of other GraphQL clients:
GraphQL IDE - An extensive IDE for exploring GraphQL API's Link: https://github.com/redound/graphql-ide (Windows, Mac OS X - needs npm/yarn)
Light, Electron-based Wrapper around GraphiQL
Link: https://github.com/skevy/graphiql-app
Mac User just type: brew cask install graphiql
Windows/Linux User:
npm install -g electron
electron
app-folder GraphiQL.app/Contents/Resources/app
(unzipped from above)Query Tasks:
Query Tasks using a Filter:
Query Process Instances:
Query Process Instance Variables:
Query Task Variables:
Mutation Assign a user to a task
Mutation Start a Process Instance with start variables
A GraphQL Schema defines the capabilities of a GraphQL server. It exposes all available types and directives on the server, as well as the entry points for query, mutation, and subscription operations.
We decided to use the Schema Definition Language (a GraphQL DSL) to define the Camunda GraphQL schema instead of coding it in Java. The Schema Definition Language is very easy to understand. For example this is the Type Definition of the Camunda Task:
To get an understanding of Schemas please visit:
The Camunda GraphQL Schema is comprised of several schema files located at src/main/resource/*.graphqls
.
This is an attempt to group GraphQL Type Definitions by topics
The so called Root Types serve as entry points for Queries and Mutations (in the future: Subscriptions etc.)
The Root Types schema file is src/main/resources/camunda.graphqls
For interactive GraphQL code completion, build-time validation, GraphQL Schema stiching or other fancy things any GraphQL client can use GraphQLs Introspection to retrieve the whole or parts of the Servers GraphQL Schema.
This is a possible and probably quite complete Introspection Query (from GraphQL Voyager):
query IntrospectionQuery {
__schema {
queryType { name }
mutationType { name }
subscriptionType { name }
types {
...FullType
}
directives {
name
description
locations
args {
...InputValue
}
}
}
}
fragment FullType on __Type {
kind
name
description
fields(includeDeprecated: true) {
name
description
args {
...InputValue
}
type {
...TypeRef
}
isDeprecated
deprecationReason
}
inputFields {
...InputValue
}
interfaces {
...TypeRef
}
enumValues(includeDeprecated: true) {
name
description
isDeprecated
deprecationReason
}
possibleTypes {
...TypeRef
}
}
fragment InputValue on __InputValue {
name
description
type { ...TypeRef }
defaultValue
}
fragment TypeRef on __Type {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
}
}
}
}
}
}
}
}
The response of the above Introspection Query can be pasted into tools like GraphQL Voyager as a Custom Schema and within seconds you get a graphical representation of your Schema, like so:
Awesome!
The Camunda GraphQL server supports three Authentication methods:
Properties which manage authentication are:
auth.Filter
JWT.secret
JWT.issuer
These properties can be set as
java:comp/env
E.g. if you are using Tomcat you can add them to catalina.properties.
If authentication is switched on (Basic or JWT) the Camunda GraphQL Server expects an Authorization-Header in the client request. GraphQL clients let you define these request headers, e.g. the graphiql-app has a link _Edit HTTP headers
To switch to Basic Authentication use:
auth.Filter=BASIC
For example if you have a Camunda user demo
with the password demo
your Authorization-Header must be:
Key=Authorization
Value=Basic ZGVtbzpkZW1v
(why?)
To switch to JWT you must set three properties:
auth.Filter=JWT
JWT.secret=Whatever_Random_Secret_String_You_Prefer
JWT.issuer=Usualy_The_Name_Of_Your_Company
A JWT Authorization-Header could look like this:
Key=Authorization
Value=Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjYW11bmRhIiwiZXhwIjoxNDk3NzA4NjY3LCJpYXQiOjE0OTc2MjIyNjcsInVzZXJuYW1lIjoiZGVtbyJ9.Z-7NTGsHYqsEoc98yOgeT5LD9oGnei6jDPs-FQQhqDw
Important!
The GraphQL Server can validate existing JSON Web Token presented in the Authorization-Header based on
JWT.secret
JWT.issuer
(future releases will support private/public key)
but cannot provide or issue them. There is no login functionality "out of the box"
There is no JWT provider build into Camunda GraphQL server, because that does not belong to GraphQL at all.
Workaround (in case you do not have a JWT provider)
To create valid JWTs you need a JWT provider.
A JWT provider for Camunda can be found here: https://github.com/Loydl/camunda-jwt-provider
The JWT.secret
and JWT.issuer
settings of the
To switch off authentication you simply set:
auth.Filter=NO
or delete this property, e.g. in catalina.properties put it in a comment:
#auth.Filter=xyz
(If the value of auth.Filter
is equal JWT
or BASIC
than authentication is switched on, otherwise it is switched off.)
https://forum.camunda.org/t/developing-the-camunda-graphql-extension