Serverless Workflow Specification - Java SDK
Provides the Java API/SPI and Model Validation for the Serverless Workflow Specification
With the SDK you can:
- Parse workflow JSON and YAML definitions
- Programmatically build workflow definitions
- Validate workflow definitions (both schema and workflow integrity validation)
- Generate workflow diagram (SVG)
Serverless Workflow Java SDK is not a workflow runtime implementation but can be used by Java runtime implementations to parse and validate workflow definitions as well as generate the workflow diagram (SVG).
Status
| Latest Releases | Conformance to spec version |
|---|---|
| 2.0.0.Final | v0.6 |
| 1.0.3.Final | v0.5 |
Getting Started
Building locally
To build project and run tests locally:
git clone https://github.com/serverlessworkflow/sdk-java.git
mvn clean install
To use it in your projects you can:
Maven projects:
a) Add the following repository to your pom.xml repositories section:
<repository>
<id>oss.sonatype.org-snapshot</id>
<url>http://oss.sonatype.org/content/repositories/snapshots</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>b) Add the following dependencies to your pom.xml dependencies section:
<dependency>
<groupId>io.serverlessworkflow</groupId>
<artifactId>serverlessworkflow-api</artifactId>
<version>3.0.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>io.serverlessworkflow</groupId>
<artifactId>serverlessworkflow-spi</artifactId>
<version>3.0.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>io.serverlessworkflow</groupId>
<artifactId>serverlessworkflow-validation</artifactId>
<version>3.0.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>io.serverlessworkflow</groupId>
<artifactId>serverlessworkflow-diagram</artifactId>
<version>3.0.0-SNAPSHOT</version>
</dependency>Gradle projects:
a) Add the following repositories to your build.gradle repositories section:
maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
b) Add the following dependencies to your build.gradle dependencies section:
implementation("io.serverlessworkflow:serverlessworkflow-api:3.0.0-SNAPSHOT")
implementation("io.serverlessworkflow:serverlessworkflow-spi:3.0.0-SNAPSHOT")
implementation("io.serverlessworkflow:serverlessworkflow-validation:3.0.0-SNAPSHOT")
implementation("io.serverlessworkflow:serverlessworkflow-diagram:3.0.0-SNAPSHOT")
How to Use
Creating from JSON/YAML source
You can create a Workflow instance from JSON/YAML source:
Let's say you have a simple YAML based workflow definition:
id: greeting
version: '1.0'
name: Greeting Workflow
start: Greet
description: Greet Someone
functions:
- name: greetingFunction
operation: file://myapis/greetingapis.json#greeting
states:
- name: Greet
type: operation
actions:
- functionRef:
refName: greetingFunction
arguments:
name: "${ .greet.name }"
actionDataFilter:
results: "${ .payload.greeting }"
stateDataFilter:
output: "${ .greeting }"
end: trueTo parse it and create a Workflow intance you can do:
Workflow workflow = Workflow.fromSource(source);where 'source' is the above mentioned YAML definition.
The fromSource static method can take in definitions in both JSON and YAML formats.
Once you have the Workflow instance you can use its API to inspect it, for example:
assertNotNull(workflow);
assertEquals("greeting", workflow.getId());
assertEquals("Greeting Workflow", workflow.getName());
assertNotNull(workflow.getFunctions());
assertEquals(1, workflow.getFunctions().size());
assertEquals("greetingFunction", workflow.getFunctions().get(0).getName());
assertNotNull(workflow.getStates());
assertEquals(1, workflow.getStates().size());
assertTrue(workflow.getStates().get(0) instanceof OperationState);
OperationState operationState = (OperationState) workflow.getStates().get(0);
assertEquals("Greet", operationState.getName());
assertEquals(DefaultState.Type.OPERATION, operationState.getType());
...Using builder API
You can also programmatically create Workflow instances, for example:
Workflow workflow = new Workflow()
.withId("test-workflow")
.withName("test-workflow-name")
.withVersion("1.0")
.withStart(new Start().withStateName("MyDelayState"))
.withFunctions(new Functions(Arrays.asList(
new FunctionDefinition().withName("testFunction")
.withOperation("testSwaggerDef#testOperationId")))
)
.withStates(Arrays.asList(
new DelayState().withName("MyDelayState").withType(DELAY)
.withTimeDelay("PT1M")
.withEnd(
new End().withTerminate(true)
)
)
);This will create a test workflow that defines an event, a function and a single Delay State.
You can use the workflow instance to get its JSON/YAML definition as well:
assertNotNull(Workflow.toJson(testWorkflow));
assertNotNull(Workflow.toYaml(testWorkflow));Using Workflow Validation
Validation allows you to perform Json Schema validation against the JSON/YAML workflow definitions.
Once you have a Workflow instance, you can also run integrity checks.
You can validate a Workflow JSON/YAML definition to get validation errors:
WorkflowValidator workflowValidator = new WorkflowValidatorImpl();
List<ValidationError> validationErrors = workflowValidator.setSource("WORKFLOW_MODEL_JSON/YAML").validate();Where WORKFLOW_MODEL_JSON/YAML is the actual workflow model JSON or YAML definition.
Or you can just check if it is valid (without getting specific errors):
WorkflowValidator workflowValidator = new WorkflowValidatorImpl();
boolean isValidWorkflow = workflowValidator.setSource("WORKFLOW_MODEL_JSON/YAML").isValid();If you build your Workflow programmatically, you can validate it as well:
Workflow workflow = new Workflow()
.withId("test-workflow")
.withVersion("1.0")
.withStart(new Start().withStateName("MyDelayState"))
.withStates(Arrays.asList(
new DelayState().withName("MyDelayState").withType(DefaultState.Type.DELAY)
.withTimeDelay("PT1M")
.withEnd(
new End().withTerminate(true)
)
));
);
WorkflowValidator workflowValidator = new WorkflowValidatorImpl();
List<ValidationError> validationErrors = workflowValidator.setWorkflow(workflow).validate();Building Workflow Diagram
Given a valid workflow definition (JSON/YAML) or a Workflow object you can build the workflow diagram SVG. The generated diagram SVG uses PlantUML state diagram visualization and can be embedded inside your tooling or web pages, or any SVG viewer.
You can build the workflow diagram SVG with the following code:
Workflow workflow = Workflow.fromSource(source);
WorkflowDiagram workflowDiagram = new WorkflowDiagramImpl();
workflowDiagram.setWorkflow(workflow);
String diagramSVG = workflowDiagram.getSvgDiagram();diagramSVG includes the diagram SVG source which you can then decide to save to a file,
print, or process further.
By default the diagram legend is now shown. If you want to enable it you can do:
Workflow workflow = Workflow.fromSource(source);
WorkflowDiagram workflowDiagram = new WorkflowDiagramImpl();
workflowDiagram.setWorkflow(workflow)
.showLegend(true);
String diagramSVG = workflowDiagram.getSvgDiagram();Here are some generated diagrams from the specification examples (with legend enabled):
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent