Build your own Low-Code Business Applications with SpiffWorkflow.
NOTE: The code in this article is a few years old now and slightly out of date. While the explanations and overview here are still accurate, our QuickStart guide is a now a better place to get acquainted with how to best use the library.
Part 1: Let’s rent us some ducks.
Introduction
In this first of multiple articles, I will walk you through building your first low-code application in SpiffWorkflow. We’ll draw a diagram, write a little code, and run a real program.
Over the full series of articles, I’m going to walk you through the process of managing change in a business application with the SpiffWorkflow library, and try to explain a little of what we at Sartography learned as we did something similar, contributed to a great open source library, and solved a very difficult problem of our own.
There is an old adage from the brilliant Gang of Four that states “Encapsulate the part that changes”. This lovely succinct little saying is core to dozen’s of the most important design principles in software development. Many things change. Great architecture assures that those changes don’t touch every square inch of the code.
When writing business applications, the things that change can feel tremendously challenging to isolate.
“Julie is leaving the bouncy room rental company, we can’t fill her roll yet, so Doug will take over ordering replacement balls, and poor Richard will be handling the pee problems. Please change the set-up tear-down checklist — but just for the Tuesdays and Wednesdays when Julie was working, Annette’s team is still fine. Oh and by the way, we are going to start renting ducks, is that a problem for the ‘code’?”.
I’ve been trying to write applications to support businesses for far too many days of my life. And while there is always a bit of pee, most everything else seems to change. It is exceedingly rare to correctly distill out what will change in business software. The ones that get it right are bathed in enormous success. But it all smells of long iteration, and gallons of luck. While no methodology will make bad ideas work, we can create software that will make it easier than ever to evolve our applications from supporting a bad idea, to supporting a good one.
If I can distill out the methodology I’m proposing here into one line, it would be this: Your clients are the architects of their business, so business software is nothing but a tool to allow them to perform that architectural effort.
Let’s Rent Some Ducks
Let me introduce you to Francis and Pat. Francis and Pat decided to start a duck rental service, and share their love of ducks with the world while making a comfortable living. We’ll be sticking with this pair through a series of articles, while building a software application that will see them through a number of transitions.
Let’s imagine Francis walks into our initial meeting to discuss the software they need for the new company. Francis might say…
I think everyone needs a good solid Duck from time to time! Ducks can cuddle and ward off evil aquatic life. They make peaceful bedtime companions. The can scare off criminals (break in to an apartment, see a duck, and it will forever shift your point of view) Ducks are smart, highly trainable, and are great at parties.
Unfortunately, not everyone is ready for a full time duck. I want to create a place where you can rent a duck for a reasonable period of time. Of course, not everyone is duck safe. I only want to send real ducks to responsible people. We’ll have to carefully vet our clients!
After a lengthy discussion with Francis, we start to see a simple process take shape. She needs to manage an inventory of ducks, match ducks to clients, schedule deliveries and pickups, and a few other things. One might imagine someone drawing a picture on the white board that included the section below — where we try to handle making sure ducks go to good people …
Step 1: Draw a picture
I frequently draw pictures with clients, especially at the beginning of a projet. It creates a shared vision and invites collaboration and contributions. When people contribute, they start to take ownership, this is critical when writing software you actually want people to use.
This diagram is special. It is a BPMN diagram, and SpiffWorkflow is a BPMN interpreter, that can execute these diagrams. We’ll talk more about this in a minute.
Granted, our first meeting would hopefully produce a more complex picture than this one, but it’s a start. And starting simple is very comforting, isn’t it? BPMN is a VERY robust diagramming language, while remaining comfortable to view and understand as you learn it. Something I think it shares with the Python programming language.
Step 2: Write some code, but leave the diagram in charge.
Once you have a picture, the next step would usually be to code it up. Taking the concepts and business needs and writing them into software. But we are not going to codify this diagram. We are going to encapsulate the part that changes. What’s going to change IS the diagram. Francis is going to keep refining ideas, and coming up with new strategies until the business is a success. Let’s write a bit of python to load up the diagram, and allow it to drive our software.
A: Use SpiffWorkflow to Load the diagram
That’s about all the code we need to load, interpret, and execute a BPMN diagram.
Line 4: Creates an instance of a parser. Here we use the BpmnDmnParser, but SpiffWorkflow provides a number of built in parsers, as well as the ability to add your own. We will dig into the creation of a custom parser in a later article.
Line 5: Loads the BPMN diagram. A given workflow might be made of many files, we will show more of this in a later article.
Line 6: Creates a Workflow Specification. You can think of a specification like a Class, but you need to instantiate that Class to get a working Object.
Line 7: Instantiate an instance of the spec, which will give us a real running workflow.
Line 8: Will run through the diagram until it hits a point that requires some interaction from a real person. At which point it will pause.
If want to deal with these pauses, these user interactions, we can add a bit more code:
In the lines above we handle one possible type of user interaction, where we need someone to answer some questions. We can then loop back over, doing all the “engine steps” or non-user interactions in-between, until we complete the diagram. So where do those questions get defined?
Step 3: Draw a little more, let’s find out what the customer is looking for ….
“Interview The Client” … This is the first square in the diagram. Maybe the interview takes place on a website, and the client completes a brief questionnaire.
Let’s start there as it seems likely, and easy to implement.
For this we’ll make the first step a User Task (a task a human being must take part in). A user task tells SpiffWorkflow it needs to wait until we tell it to continue. Nothing more. From there the implementation is up to us. BPMN.js will allow us to define details for a basic web form, and we can capitalize on this. As you see to the right we can use the web form to define a number of details. All of this is encoded into the diagram.
This produces some custom XML content in the Camunda namespace which SpiffWorkflow can parse. But really, you could modify BPMN.io to generate any XML you can imagine, and you can create a custom parser in SpiffWorkflow to read that XML and do anything you need. Using Camunda’s form builder is a quick way to get started. We will revisit this in a later article and show some other alternatives.
Step 4: Write some code — let’s make those questions work, or really, any set of questions work.
The step above generated some XML that tells us what questions we need to ask. We just need to write a little code to actually ask those questions and get the responses. Here we will ask these questions at the command line just as a demonstration. With a few more steps, you could render an HTML form or really, wherever your heart desires.
Now, when we reach a user task, we can loop through the questions defined for that user task, and gather information from a real person.
Step 5: Duck Worthiness
So let’s say we asked two questions in our initial forms:
- What kinds of ducks to you like? (variety)
– Mallards
– Wood Ducks
– Dead Ducks - Do you like finding random feathers and eggs in your house? (tolerant)
– Yes
– No
If someone says they like dead ducks, that is a pretty good indicator that our ducks won’t be safe with them. If they hate finding feathers and eggs in their house, they might not be emotionally ready for the responsibility of handing a duck. So we can use these indicators to make a decision.
We can safely assume after the [Interview Client] task is completed that we have two variables in our data: variety and tolerant. Now we can add in a simple script task that can make a calculation. Here we can inject some python back into the diagram. A short, simple script that can make a judgement call on the character of our client’s customer.
Script tasks can execute Python to make calculations, transform data, and potentially make calls out to other services to perform tasks like sending an email, or making an external API call. This code is embedded directly in the BPMN diagrams. You can add this through the editor, but just so you see how the pieces fit together, here is the resulting XML:
Step 6: Remember, Leave the diagram in control
Tasks that do not require end user interactions are executed automatically by SpiffWorkflow. So once the questions are answered, SpiffWorkflow will execute the Script Task above, then handle the “exclusive gateway” (shown to the left). Gateways allow our diagrams to show branching conditional logic that can drastically alter the way our application will work. It is an architecture tool for our clients. They have all the power to change the way the system behaves, and the behavior is fully encapsulated within the diagram.
The gateway is controlled by writing a bit of Python, each path out of the gateway contains a Boolean expression. You can have as many paths out of the gateway as you need, but at least one of them needs to evaluate as true. You can also define a default path.
Try it out!
The full code for this article is available in our SpiffyDuck GitHub Repository.
Prerequisites:
- Python3
- git
Directions:
Play around! Try making some changes to the diagram. Try adding some additional questions and use these to make a more refined judgment call on the duck-compatibility. Perhaps there is a third option, and some folks should be directed to duck therapy class where they can learn to stop hating on ducks, and embrace their inner quack.
In Conclusion
You’ve learned that by shifting the architectural control of your business application to the diagram, you allow your business clients a whole new level of autonomy. They now have as strong a voice in the direction of the software as they do in other aspects of their business. This is critical, particularly at the beginning of a new endeavor when fundamental changes in direction are the norm.
You also learned a little about the tools available in the BPMN standard: The User Task, the Script Task, and the Exclusive Gateway. There are dozens more, which we will cover in upcoming articles, but these three are fundamental. Understanding them, and how information flows between them is key to moving forward.
Finally, you have learned the little bit of python you need to know in order to load, parse, and execute these diagrams using SpiffWorkflow. Ideally SpiffWorkflow falls into the background, and you spend your time building tools and components, while your client refines their ideas in BPMN diagrams. SpiffWorkflow and the BPMN standard offer you a new way to interact with your clients that makes software development feel more collaborative than ever before.
