> For the complete documentation index, see [llms.txt](https://docs.rulecube.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rulecube.com/v2.5/how-to-guides/create-a-workflow.md).
# 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:
1. Start a workflow by calling it via its API as you do with rulesets.
2. The workflow executes its steps until it encounters a wait step.
3. The workflow suspends itself.
4. When you or your program interacting with the workflow are ready, you send an answer or response to the workflow via its API.
5. The workflow resumes and proceeds its remaining steps according to your answer.
6. 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.
The workflow settings screen
#### 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
1. Create a new ruleset named `LoanAssessment`.
2. Select **Version settings** from the left-side menu.
3. 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:
4. Create an input named `LoanAmount`
1. Set its **Type** to `number`
2. Check the "Add to state" checkbox.
5. Select the **State** entity and click **Add property**.
6. In the **Name** field, enter `Status`.
7. In the **Type** list, select string.
8. In the **Default value (optional)** field, enter `new`.
9. Click **Save**.
### Step 2: Add steps to the workflow
1. Select **Workflow** from the left-side menu.\
↳ Rulecube shows the **Workflow** canvas where you create the workflow by dragging en connecting steps.
2. Drag a  step to canvas.\
↳ Rulecube gives the step a default name.
3. Select the **Switch** step.\
↳ The **Switch** details section opens:\
4. In the **Step name** field, enter `Assessment check`.
5. In the **Description** field, enter `Requested loan amount larger than 100,000?`
6. 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:
7. Drag an step to the canvas and set **Step name** = `Assessment` and **Description** = `Accept or reject`.
8. Drag another step to the canvas and set **Step name** = `Accept`.
9. Connect the **Assessment check** step to the **Assessment** step.\
↳ Rulecube asks for a name for the connection, enter `true`, and click **OK**.
10. 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.
11. Drag a  step to the canvas and set **Step name** = `Wait`.
12. Connect the **Assessment** step to the **Wait** step.
13. Drag an step to the canvas and set **Step name** = `Reject`.
14. Connect the **Wait** step to the **Accept** step and name the connection `Accept`.
15. Connect the **Wait** step to the **Reject** step and name the connection `Reject`.
16. Drag an  step to the canvas.
17. 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:
18. Save the workflow.
### Step 3: Add processing to the steps
1. 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.
2. 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.
3. Select the **Assessment** step and set its **Expression** to the following code:
\
**Explanation**\
This code sets the status and creates the possible answers or responses (signals) for the assessor.
4. Select the **Accept** step and set its **Expression** to the following code:
state.Status = 'accepted';
5. Select the **Reject** step and set its **Expression** to the following code:
state.Status = 'rejected';
6. Save your workflow.
#### Summary
Let's summarize the workflow processing to be sure that things are clear:
1. The workflow starts with addressing the loan amount to the `state` object for later reference.
2. Then, the workflow checks whether the loan amount is larger than 100,000.
3. If the loan amount is less than or equal to 100,000, the loan is accepted, and the workflow finishes.
4. 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.
5. The workflow ends, and the `state` object now holds the final data.
### Step 4: Try out the workflow
1. Click **Try it out!**\
↳ The **Sandbox** page opens and now also has a **Start** **workflow** button.
2. In the **LoanAmount** field, enter `100000`.
3. 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`.
4. Now change the **LoanAmount** input to `100001`.
5. 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`.
6. Click **Reject**.\
↳ The workflow resumes, rejects the loan, and finishes:
7. 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](/v2.5/how-to-guides/ruleset-development/call-a-ruleset-from-your-software.md). Only the URL is different:
```
<>/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:
{% code lineNumbers="true" %}
```javascript
let acceptUrl = Workflow.createNextSignalUrl('Accept');
let rejectUrl = Workflow.createNextSignalUrl('Reject');
let body = `Hi,
Accept or Reject`;
Mail.send({
host: "SMTP_SERVER",
port: 587,
secure: false,
auth: {
}
}, {
from: '"SENDER_NAME" ',
to: [RECIPIENT_EMAIL_ADDRESS],
subject: 'Loan assessment',
html: body
})
```
{% endcode %}
⇨ 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.rulecube.com/v2.5/how-to-guides/create-a-workflow.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.