This article contains the following sections that can help you gain deeper insight into how pipelines work:
- Introduction to states and transitions
- What actions can I perform based on my current state?
- Button mode a.k.a. Dummies mode
- How pipeline states are mapped to internal states
Introduction to states and transitions
A pipeline is a Finite State Machine (FSM) with two-level variance and one-level feedback. For technical information about how this works, see State diagram.
Unlike with flow charts, where you would need to learn, understand, and work with twelve different symbols, in pipelines, there are only two symbols; States and Transitions. Even though these two entities (called nodes) are vastly different from each other, they are sometimes confused with each other.
States reflect a single property of an element. In an FSM, each node can be in only one state at a time.
States can be anything; they can represent common lifecycle stages like Approved, Declined, or Archived, or even more complex ones, such as Sent by taxi to manager, Awaiting raid by IRS, and Stamped.
There was once a small car in Thailand that was in a state called Sat on by Elephant. Funnily, this is common in downtown Bangkok, where elephants share roads, get tired, and sit on cars.
This is an illustration of the idea that a state can be anything that you want it to be.
A state is an adjective, and a Transition is the verb (action) that connects two states.
A state is a WHAT?. A transition is a HOW?.
What actions can I perform based on my current state?
In pipelines, there is always a collection of future states just one hop away from the current state of every node (element or object). This is important information, and is what the UI displays at any given time. Your current view of a running pipeline is only this small subset (of the larger pipeline) that shows where you can go next.
You are given a choice of what you want to do next (or where you want to go). Once you have made a choice, the UI changes and displays the next set of steps you can take based on your choice.
For example, if your current state is 6 transitions away from another state, the UI does not display this information, as you may never actually get there. However, the UI displays the options available for your next transition.
As different users might perform different job roles, Yomly filters the pipeline subset and displays only states associated with no specific audience (i.e., available for Everyone) and the ones assigned to audiences of which you are a member. Therefore, at all times, as a user, you can only view the future states that you are permitted to see. Different users can see a different UI depending on what they are allowed to do at that specific time.
Button mode or Dummies mode
Consider the example of a basic pipeline with a single approver that governs expense reimbursements.
This example explains the details of implementing a very basic pipeline. Complex pipelines are simply increments to the same implementation.
Remember, a pipeline is simply a collection of states joined by transitions. Therefore, conceptually, a complex pipeline is really just a collection of smaller unit level pipelines.
In Edit mode, just above the pipeline editor in the right corner, the Show buttons for actions toggle button is displayed.
This option enables or disables button mode, which is better known as Dummies mode.
As a platform admin, when configuring a pipeline, we recommend that you turn on Dummies (button) mode. This is because, in this mode, in the UI, the collapsible action button is replaced with a button grid that displays all actions you can perform based on your current position in the pipeline. This mode helps users to perform tasks in your pipeline easily without technical know-how.
Example: Dummies mode in expense reimbursement
When Dummies (button) mode is enabled, the UI displays the following for an expense request:
-
After creating the request in Expenses but before submitting it for approval:
Feature UI Description Expenses The following image illustrates the buttons displayed in an expense request when it is initially created:
Only the Send for Approval button (that indicates the next transition) is displayed.
This is because, in the pipeline, there is only one possible place to go from the initial state; Submitted.
The button displays the name of the transition. This is because transitions indicate actions required to get to the next state (which, in this case, is Submitted).
Tasks The following image illustrates the buttons displayed initially in an expense request when it is opened in Tasks:
Similar to Expenses, only the Send for Approval button is displayed. -
After sending the request for approval:
Feature UI Description Expenses The following image illustrates the buttons displayed in an expense request after it is sent for approval:
The Approve and Decline buttons, which indicate possible transitions, are displayed.
Tasks The following image illustrates the buttons displayed in an expense request sent for approval when it is opened in Tasks:
Similar to Expenses, buttons that indicate permitted actions (Approve and Decline) are displayed.
Why do expense requests and their related tasks display different information in some cases?
Expense requests and their related tasks might display different information because the tasks use data containers to display custom information about the expense requests.
As a platform admin, you can associate a data container with the task related to any stage of the expense request approval workflow when configuring the respective state of the expense reimbursement pipeline.
You can choose how simple or complex you want the content (that the data container displays) to be.
For example, you can add a Yellowfin dashboard, an iframe to an external website, or a document built using the Yomly document editor to a data container.
A huge advantage of turning on Dummies mode is that the UI displays buttons that represent only the actions that you can perform. If you are not permitted to perform an action at any point, the button is simply not displayed. The UI also never displays disabled buttons, as they can be confusing.
How pipeline states are mapped to internal states
Although you can create any number of states for an entity, Yomly also has certain internal states. If you want to represent your new states internally, you must have a mechanism to map these two kinds of states. This role is played by the State action script field.
When editing a state, this field is available in the Script tab in the Edit state dialogue.
The state action script is executed on entry to the state.
You can use the full power of the scripting engine to achieve your requirements using this field. You can update the database, send a report, and more. Mostly, though, we use the state action script to set internal states to the subset that Yomly knows about.
Example: Mapping states and statuses in Expenses
The following internal states in Yomly correspond to the following statuses of expense requests:
| Internal state | Status |
|---|---|
| OFF | |
| RUNNING | |
| COMPLETED | |
| DECLINED |
Statuses are displayed as tags in the UI.
The following image illustrates how statuses of expense requests are represented on the Expense Requests page in Expenses:
To map a state that you have created to an internal state (and therefore, move it to the corresponding status), you can enter the following state action scripts:
The status corresponds to the Initial State of the pipeline.
Status:
Internal state: RUNNING
State action script:
const eid = context.data.id;
let status = "RUNNING";
await ehr.sql("UPDATE ExpenseRequests SET status='" + status + "' WHERE expenseRequestId=" + eid);
Status:
Internal state: COMPLETED
State action script:
const eid = context.data.id;
let status = "COMPLETED";
await ehr.sql("UPDATE ExpenseRequests SET status='" + status + "' WHERE expenseRequestId=" + eid);
Status:
Internal state: DECLINED
State action script:
const eid = context.data.id;
let status = "DECLINED";
await ehr.sql("UPDATE ExpenseRequests SET status='" + status + "' WHERE expenseRequestId=" + eid);
Comments
For the last section, we should show a table with internal states and the corresponding tag in the UX:
OFF -> Draft
RUNNING -> Pending approval
COMPLETED -> Approved
DECLINED -> Declined
Please sign in to leave a comment.