Workflow Client API

At the moment, this API is available in Java only.

Clients can start and interact with Workflows using the Workflow Client API. Please note that Workflows in this document always refer to a Workflow Instance.

Starting a Workflow

To start a Workflow, a client first needs to get a WorkflowReference via Grainite.newWorkflow() API. This provides the client with a Workflow ID which can then be used to start the Workflow using the WorkflowReference.start()` ``` API which takes the Application name and Workflow Method name as parameters. All further interactions between the client and the Workflow will be via the WorkflowReference.

// Sample code to start a Workflow

Grainite grainite = ...
BookingRequest req = new BookingRequest();
//...
WorkflowReference wref = grainite.newWorkflow("concierge","BookingFlow");
wref.start("bookHotel", null, Value.ofObject(req));

Once the Workflow has started, the Client can wait for the instance to complete using the WorkflowReference.waitForCompletion() API by specifying a maximum wait duration. A “null” duration means waiting forever for an instance to complete.

// wait for up to 30 secs for the workflow to complete

WorkflowStatus status = wref.waitForCompletion(Duration.ofSeconds(30));
if (status.isComplete()) {
  //...
} else {
  //...
}

Clients can start a new Workflow and wait for it to complete using the WorkflowReference.start() API before returning from the start call.

// Get the workflow reference if required

WorkflowReference wref = grainite.newWorkflow("concierge","BookingFlow");

// start the workflow, and wait for up to 30 secs for it to complete

WorkflowStatus status = wref.start("bookHotel", null, Value.ofObject(req), Duration.ofSeconds(30));

Clients can get a reference to an existing Workflow using the Grainite.getWorkflow() API. The WorkflowInfo can then be obtained from this reference. The WorkflowInfo is serializable and can be persisted. It contains the Workflow application name, Workflow table name, and Workflow ID.

// Get a reference to the Workflow info

WorkflowInfo info = wref.getInfo();
System.println("Workflow info: %s $s $s", info.getAppName(), info.getTableName(), info.getWorkflowId());

// ... store WorkflowInfo somewhere (it implements Serializable)

A previously stored WorkflowInfo can be used by the client to obtain a WorkflowReference at any time.

// obtain workflow info of previously-started workflow

WorkflowInfo info = …

// get workflow reference

WorkflowReference wref = grainite.getWorkflow(info);

Workflow Status and Result

A Workflow status can be in one of these states.

• NOTSTARTED

• RUNNING

• SUCCESS

• FAILURE

Workflow Status and the Result can be fetched using the WorkflowReference.fetchStatus() API.

WorkflowReference wref = ...
WorkflowStatus st = wref.fetchStatus();
 if (!st.isRunning() && !st.isComplete()) {
   // workflow does not exist
 } else if (!st.isComplete()) {
   // workflow is still running
 } else if (!st.isSuccess()) {
   // workflow resulted in failure
   String errorMsg = st.getFailure().desc;
 } else { // result is available
  Value result = st.getResult();
 }

Workflow progress log

A Workflow log can be fetched using the WorkflowReference.fetchLog() API.

// Sample code to fetch Workflow log

WorkflowReference wref = ...
List<String> log = wref.fetchLog();

Invoke Query and Signal methods

Clients can invoke Query and Signal methods provided by a Workflow. The invocation is synchronous, and the client invocation returns after the method have been executed. Queries and signals take a Value argument and return a Value result.

For Queries, Clients can use the WorkflowReference.query() API.

// Sample code for Queries

WorkflowReference wref = grainite.getWorkflow("concierge", "BookingFlow", workflowId);
BookingStatus status = wref.query("getBookingStatus", null).asType(BookingStatus.class);

For Signals, Clients can use the WorkflowReference.signal() API

// Sample code for Signals

wref.signal("cancelBooking", null);

Stop (Kill) a workflow

A client can stop a Workflow from executing by using the WorkflowReference.kill() API. This will immediately terminate the Workflow and compensating transactions will not be executed. When the API call returns, the Workflow status will be 'FAILURE'. Trying to stop a Workflow that has already been completed is considered a “nop”.

// Sample code to Stop(Kill) a Workflow

wref.kill("this is an emergency");