Create a Workflow

This guide explains how to create and exploit workflows with Rulecube.

Introduction

A workflow is a special type of ruleset that is interactive and responsive. In a regular ruleset, you provide input and start the ruleset, then it processes the input and returns the requested output. A request and return process through the ruleset's API without interaction.

In a workflow, on the other hand, you have a sequence of steps, and you can affect the step execution and interact with a step during processing. For instance, a workflow can choose which steps to execute. Or wait until it receives an answer or response to proceed. Like in this workflow:

Start a workflow by calling it via its API as you do with rulesets.
The workflow executes its steps until it encounters a wait step.
The workflow suspends itself.
When you or your program interacting with the workflow are ready, you send an answer or response to the workflow via its API.
The workflow resumes and proceeds its remaining steps according to your answer.
The workflow reaches the end and finishes.

And a practical example could be a loan application workflow that sends an email to an assessor when the requested loan exceeds a certain amount to accept or reject the loan. This workflow waits until the assessor responds, then finishes processing.

In Rulecube, a workflow combines a couple of concepts:

Data and Business rules: the basis of every Rulecube ruleset
Process: containing all workflow steps
Documents: handled and/or produced by the workflow steps
Stakeholders: the people handling the workflow

The workflow editor

The workflow editor is a drag-and-drop editor. You can drag steps from the top of the screen and drop them on the workflow canvas. You can also drag steps around the canvas to rearrange them.

Deleting a step is easy by clicking it and pressing the Delete button. You can connect steps by dragging from the small circle on the right or bottom side of a step to the small circle on the left or top side of another step. It is also possible to connect a step by choosing one of the steps from the dropdown that appears when you click on a step. The line between the steps will be drawn automatically.

Workflow settings

In the workflow settings screen, we can define Document types and Stakeholders.

Document types

The 'document types' list is a list of documents the workflow handles or produces. A workflow can only handle documents if their type is defined in this list. Each document type has a name and a description.

Stakeholders

The 'stakeholders' are the user groups with a certain role in the workflow. For example, the 'Client' stakeholder is the user group that represents the client in the workflow. The stakeholders are used to assign tasks to users in the workflow. The stakeholders are also used to determine the visibility of (part of) the workflow in the UI. You can assign tasks to the stakeholders by adding a task to a Wait step by checking the 'Create task' checkbox.

Each stakeholder has a name (you can choose any name you want, as long as it is unique for every stakeholder group) and a property called 'Roles,' in which you can select application roles. When a user has one or more of the roles selected here, he is a stakeholder group member.

Workflow state

If you create a workflow, Rulecube automatically creates an state input and an State entity for workflow control. This state object is accessible in all workflow steps and can have as many properties as you need to control workflow execution or show progress.

For example, you can have a status property that holds the different statuses for each phase in the loan application workflow, such as:

new
under review
on halt
accepted
rejected

Workflow steps

A workflow comprises connected steps that execute from the Start to the End steps. You build a workflow by dragging, connecting, and defining steps on the Workflow canvas:

And these are the available steps:

This step is added by default and is a good place to initialize your workflow and the State object.
A processing step that executes a calculation, fetches data from an external API, modifies the State object, or performs any other command that you execute in regular rules.
This step waits until it receives a response.
Based on a condition, this step selects which step or steps should be performed next.
This step splits execution into branches that are executed in parallel.
This step brings forked branches back together for further processing.
This step waits for a specific amount of time before continuing to the next step.
An Upload step is a step that waits for a file to upload to the server.
This is the place where you finish the workflow and set the final outcome.

Procedure

Let's create a workflow for the earlier-mentioned loan application process:

Step 1: Create the basic workflow

Create a new ruleset named LoanAssessment.
Select Version settings from the left-side menu.
Select the Workflow checkbox. ↳ Rulecube turns the ruleset into a workflow and adds the Workflow option to the left-hand menu, and creates the state input and the State entity:
Create an input named LoanAmount
1. Set its Type to number
2. Check the "Add to state" checkbox.
Select the State entity and click Add property.
In the Name field, enter Status.
In the Type list, select string.
In the Default value (optional) field, enter new.
Click Save.

Step 2: Add steps to the workflow

Select Workflow from the left-side menu. ↳ Rulecube shows the Workflow canvas where you create the workflow by dragging en connecting steps.
Drag a step to canvas. ↳ Rulecube gives the step a default name.
Select the Switch step. ↳ The Switch details section opens:
In the Step name field, enter Assessment check.
In the Description field, enter Requested loan amount larger than 100,000?
Connect the Start step to the Assessment check step by clicking on the little circle in the Start step, holding your mouse, and dropping on the left circle of the Assessment check step. ↳ Rulecube adds a dotted blue line between the steps to indicate that they are connected:
Drag an step to the canvas and set Step name = Assessment and Description = Accept or reject.
Drag another step to the canvas and set Step name = Accept.
Connect the Assessment check step to the Assessment step. ↳ Rulecube asks for a name for the connection, enter true, and click OK.
Connect the Assessment check step to the Accept step. ↳ Rulecube asks for a name for the connection, enter false, and click OK. And now, the Assessment check (switch) step has proceedings for whether its condition is true or false.
Drag a step to the canvas and set Step name = Wait.
Connect the Assessment step to the Wait step.
Drag an step to the canvas and set Step name = Reject.
Connect the Wait step to the Accept step and name the connection Accept.
Connect the Wait step to the Reject step and name the connection Reject.
Drag an step to the canvas.
Connect the Accept step and the Reject step to the End step. ↳ Maybe you have to rearrange the steps, but your workflow canvas should look like this:
Save the workflow.

Step 3: Add processing to the steps

Select the Start step and set its Expression to the following code:
```
state.LoanAmount = LoanAmount;
return;
```
Explanation This initializes the workflow by addressing the value of the LoanAmount input to the LoanAmount property of the state object, which makes the LoanAmount input value available in the workflow.
Select the Assessment check step and set its Expression to the following code:
```
return state.LoanAmount > 100000
```
Explanation This code checks whether the loan amount is larger than 100,000 and results in either true or false.
Select the Assessment step and set its Expression to the following code:
```
state.Status = 'under review';

Workflow.createNextSignalUrl('Accept');
Workflow.createNextSignalUrl('Reject');

return;
```
Explanation This code sets the status and creates the possible answers or responses (signals) for the assessor.
Select the Accept step and set its Expression to the following code:
```
state.Status = 'accepted';
```
Select the Reject step and set its Expression to the following code:
```
state.Status = 'rejected';
```
Save your workflow.

Summary

Let's summarize the workflow processing to be sure that things are clear:

The workflow starts with addressing the loan amount to the state object for later reference.
Then, the workflow checks whether the loan amount is larger than 100,000.
If the loan amount is less than or equal to 100,000, the loan is accepted, and the workflow finishes.
If the loan amount is larger than 100,000:
1. The workflow creates responses for the assessor.
2. Then waits for the response.
3. If the assessor accepts the loan, the acceptance is processed, and the workflow finishes.
4. If the assessor rejects the loan, the rejection is processed, and the workflow finishes.
The workflow ends, and the state object now holds the final data.

Step 4: Try out the workflow

Click Try it out! ↳ The Sandbox page opens and now also has a Start workflow button.
In the LoanAmount field, enter 100000.
Click Start workflow. ↳ The workflow runs, and the Result section shows the State object and the execution Log:
Because the loan amount was equal to 100,000, the loan was accepted as shown by the value of State.Status.
Now change the LoanAmount input to 100001.
Click Restart. ↳ The workflow starts but suspends itself after a while as an indication that it is waiting:
And in the Log, you'll see the available signals (responses) for the assessor:
Furthermore, the State object indicates that the Status is under review.
Click Reject. ↳ The workflow resumes, rejects the loan, and finishes:
Restart the workflow again, and this time, select the Accept signal from the Log to execute the acceptance route for the assessor.

Step 5: Call the workflow via its API

Basically, calling a workflow works the same as calling a ruleset. Only the URL is different:

<<Your rulecube URL>>/api/workflow/start

Some additional inspiration

The above procedure creates only basic signals for the assessor. In practice, you could include the signals (as URLs) in an e-mail so that the recipient can respond to them, thus completing the workflow. Then, the Expression for the Assessment step could look something like this:

let acceptUrl = Workflow.createNextSignalUrl('Accept');
let rejectUrl = Workflow.createNextSignalUrl('Reject');

let body = `Hi,
<br>
<a href="${acceptUrl}">Accept</a> or <a href="${rejectUrl}">Reject</a>`;

Mail.send({
    host: "SMTP_SERVER",
    port: 587,
    secure: false,
    auth: {

    }
}, {
    from: '"SENDER_NAME" <SENDER_EMAIL_ADDRESS>',
    to: [RECIPIENT_EMAIL_ADDRESS],
    subject: 'Loan assessment',
    html: body
})

⇨ Replace and add the values and parameters that apply to your situation.

With this, the Assessment step sends an email to the assessor. Until the assessor responds by clicking Accept or Reject in the email, the workflow waits and suspends itself. And when the assessor responds, the workflow resumes.

PreviousDebugging your Ruleset NextWorkflow step types

Last updated 1 year ago