Orchestration Engine

Conceptual Overview

Many business applications such as a booking application or payment processing application are multi-step, involving interactions with multiple entities. These entities may fail or be unavailable requiring retries, waits, and sleeps. These applications require developers to implement short running (few seconds to minutes) or long-running transactions (several days to years) which are managed as Workflows within an Orchestration framework.

Granite’s Converged Streaming Application Platform allows developers to build real-time streaming applications with ease and to write Workflows that implement data management patterns (e.g. SAGA), using the integrated Orchestration engine. These workflows can be developed in Java language leveraging the GrainiteClient and GrainContext APIs provided by Grainite.

The components of the Grainite Workflow Orchestration engine are

  1. Workflows

  2. Activities

  3. Queries

  4. Signals


A workflow’s primary function is to orchestrate interactions with other entities. A Workflow execution state consists of local and instance variables. The Workflow execution state is automatically durable and reentrant in Grainite and is provided as a platform guarantee to the developer. This allows recovery from a failure to be transparent to the developer without worrying about losing state or having to repeat any work. A Workflow is never interrupted in Grainite, and its execution state is never lost.

Workflows have the following subcomponents:

  • Workflow Definition - Workflow defined in the application configuration file

  • Workflow Table - Durably stores Workflow execution state

  • Workflow Class - This is a user-provided pojo (plain old java object) class instantiated when a Workflow Instance is created. Workflow methods can execute as long as needed to complete a task.

  • Workflow Method - Implements the Workflow logic, which is written in a normal straight-line, single-threaded fashion.

  • Workflow Instance - An Instance gets created in the Workflow table when a Grainite Client starts a Workflow.

  • Workflow ID - A unique ID that is the key to the Workflow instance

  • Workflow Commands - GX tool provides helpful commands to query the status of Workflows in execution. Run gx workflow –help for additional information.

  • Workflow ClientAPI - Workflow APIs that are part of LibGrainite, that allow Clients to interact with Grainite Orchestration Engine.

  • Workflow State - Execution state that consists of local variables of the workflow method, and instance variables of the pojo. The execution state is automatically durable and is never lost. This state is stored in the workflow instance.

  • Workflow Completion - A workflow completes when the Workflow method exits. This can be a result of successful execution (success) or because of an exception (failure).


Workflows interact with entities using Activities. Activities include grain queries, grain updates, grain invocations, appending events to topics, user-developed interactions (e.g. HTTP calls), and interactions with other Workflows.

Activities can be configured for retries with specified delays and maximum duration. The retries can be beneficial when interacting with external entities where availability may be a concern.

Activity execution in Grainite is asynchronous and each workflow can have multiple Activities which execute in parallel. Workflow can start Activities and later wait for their completion. Grainite uses a Promise(s) to track the successful completion or failure of Activities. In addition to awaiting activity completion, the Workflow can simultaneously wait for a duration to elapse or a condition to be met.

There are various types of Activities in Grainite

  • GrainOp - Call an action on a grain

  • TopicAppend - Append to a topic

  • Function - Any interaction with an external data source

  • Workflow - Start/query/signal another Workflow


Queries allow clients to get the Workflow state. Since the state of a Workflow is constantly changing, Queries make it easier to expose the internal state of a Workflow execution to the external world. Grainite Client can invoke the query method via the GrainiteClient APIs. Queries are guaranteed to return the most recent state of a Workflow execution. Queries are Synchronous read-only methods provided by the Workflow developer. They cannot alter the state of the Workflow execution.


Signals can be used to modify the Workflow execution state. Workflows await conditions for their execution and Signals allow you to modify those conditions and modify the state. Grainite Client can invoke the Signals method via the GrainiteClient APIs.

Queries and signals execute only when the Workflow method is in a waiting state (ie, inside an await call). It is guaranteed that the Workflow, Query, or Signal methods will never execute concurrently. Thus, so long as the Workflow state is consistent when the Workflow method enters an Await, Signals and Queries will only see a consistent state. So long as the Workflow state is consistent when a signal method completes, the Workflow method will only see a consistent state.

Last updated