Sunday, November 26, 2017

Understanding three use case types in process modeling - not just system or business

Use cases give us a detailed understanding of a process to optimize or build into software. When use cases go bad, and they do, they take up space and no one uses them. I've been finding out as I teach them more and more, the main reason people don't use use cases is for lack of detail. So I've built more and more useful detail into the templates that I use for my classes.

Details, details

Let's take just one small entry in the metadata of the use case template: the type of the use case. The type should tell you about the context of the use case. If your analysts understand the context, there's no need to include this in the documentation. But analysts are usually given the context of a software system to be built and the context of the project that will be driving that software to be delivered and requirements come from all angles.

I was told there were two types of use cases: system and business. (I think there's a different set but that's coming.) Not enough examples of detailed business use cases with sequential tasks listed in the course of events are being produced. Maybe it's because we don't understand how to do it.

One solution to making your job more tolerable and eliminating those confusing and bothersome requirements is to ignore the complex non-system use cases. Another simplifying solution is to just grab the large scope names of the business use cases and not worry about the details. Then there's the solution that says if it's important enough to know the details of the software workflow, the business process we're planning to automate, why isn't it important to know the details of the business workflows also? Let's do that. The devil is in the details.

Two traditional types

The first and major type of use case traditionally is the system type when we design interactions around software. The trigger to the process is when someone or something chooses something from the main menu or a system hits our API. Sometimes, that main menu is a log-in part of the process that protects the value of the use case by keeping unwanted people out and those that we give access to the rights to initiate the use case.

Then there's the business type, which from a lack of detailed examples, no one does. I think the best work on doing enterprise analysis to show how UML can be used to draw diagrams that the business doesn't want to use is Eriksson and Penker's Business Modeling with UML - Business Patterns at Work (2000). These Swedes have a beautiful system that technical people can admire for completeness, details, and symbols that look just like software diagrams. But it's the business people that need to be drawing, updating, and using these diagrams and they sure don't want to spend time with UML to do that.

One of my pet peeves is the UML way to draw a business use case. The use case symbol is the ellipse, also known as an oval for the non-technical crew out there. You put the name of the use case in there leaving little space for anything else. Then you draw a diagonal line inside the oval making it look like you had a masking problem with another symbol. And if you followed UML to put the extension points in there as well, you'd have an unreadable ellipse. Let's just use a stereotype to say <<business>> so that the category is clear when there's no system boundary box in sight.

Even Erikkson and Penker don't get down to the level of detail that is important to start with on a business process. But they do a bang up job on high-level structures. The level of detail that is necessary for a system use case to be useful to build for the developer is fine-grained down to a task level that needs no other explanation.

Maybe we don't think like Swedes here in America and don't take the time at a high-level to plan our goals. We think the market is moving much too fast for that and like to do shorter-term planning. Do we see the Swedes competing well in any American market other than build-it-yourself furniture? Like how many people do you know that own a Volvo?

A pure start

Moving on to how I see the process types being divided up, they start with a set of tasks performed by a human. That is what I would call a pure business use case. This business use case 
  • starts when a trigger sets it off, 
  • moves through a set of sequential tasks,
  • ends with significant value for the business and 
  • probably has documents created to support it. 
There's value in promoting merchandise, there's value in making a sale, there's value in fulfilling a sale, and there's value in getting payment for a sale. There's even value in accepting a return for a purchased item.

There's no talk of automation in the pure business use case and if someone wants to use a tool, then that is part of the design for fulfilling the process tasks. That's what increases efficiency. The task sequence described in the pure business use case is what increases effectiveness. Both can increase value for the business.

System use cases made easy

I encourage my students to write their system use cases as pure business use cases that will be automated by the programmers. That clarifies what types of assumptions they have made about what they will be building. What if we eliminated the design constraints and changed all those "system displays a main menu" types of tasks into a business pure "system prompts for what to do"? Then the system use case turns into a pure business use case and the system role becomes a business role of some sort. I think it's better to think about how a person might handle the system functionality when writing use cases.

But this next type of use case pops up from every single student that I've ever taught and one that lets design elements creep into the use case tasks. It's expected in many industries because of what they already have accepted before the project began or in other words, elicited as a constraint. So this is called a system with constraints type.

Students always want to "submit" the data that is collected. They also want to use buttons, keyboards, mice, screens, menus and every other standard GUI option they think is normal. But in doing so, the tasks are now explicitly describing a design that must be used. When a web site is being designed, the design constraint of using a set of web languages and a web server has already been decided. Why should we follow that architecture if the requirements don't really point us in that direction?

So, not to fight the common usage of this type of use case in business, it's just easier to put a field at the top of the form to capture what the design constraints are that have already been decided to use before we capture the requirements. The requirements then have the freedom to talk about all those clicks and hovers they want. But let's call it a system process with constraints.

Distributed tasks

The last type of use case is the distributed use case, a mix of business and system tasks or different systems, and one that I've seen no documentation on. There's no UML approved designs for it and no discussion about it that I know of. But as soon as I started to do business use cases for a real scenario, it stuck its oddly shaped head up and stopped me from using the other two. I could have changed the business process to manage, but the sequence of activity is so common, it has to be dealt with by changing the way we do the use case.

Another use for the distributed use case is when you have real distributed processes that are seen as a complete goal and within the scope of development. An example might be when microservices or API calls provide less than a goal value but are integrated in working with a web page to deliver the end result. I do have a problem with creating a use case just to validate an address on the server because that is less than a business goal that a use case should end with.

The distributed use case does a step or two in one system, existing or to be developed, and then does a business activity or a different system's task, like talking to a person to acquire information. Then it cycles. The process is distributed over two activity flows. Think of ordering at a fast-food restaurant. There the actor initiates the food order and uses an automated system for the customer as an agent or proxy because it is too complex. The process goes like this: the actor-agent
  1. greets the customer (business task)
  2. opens a new order (system task)
  3. asks the customer for their item to order (business task)
  4. selects the item, enters the quantity, checks for additional questions or restrictions (system task)
  5. gets needed data from the customer (business task)
  6. enters extra information (system task)
  7. informs the customer of information (business task)
  8. confirms end of order with customer (business task)
  9. sends order to be processed (system task)
  10. tells customer the total of the order, how to pick up their order and says goodbye
An extension point for optional multiple item order which is clumsily handled by trying to show a loop is better handled by adding the extension point at #8 and sending them back to #3 as an option for the extension "Add another item to order."

Now the problem is how to diagram that. I propose using two ellipses with  <<system>> and <<business>> stereotypes and showing the dependency of the system to the business use case with an <<include>>. The business use case with acknowledge its dependency with a use case name that has a system usage in it. Here's how it would look:

The diagram also shows that it is possible to do an entirely business use case to take an order and then later, do an entirely system use case to create the order.

Course of events layout

You might think this distribution would cause some confusion in the course of events. There are some issues. But the first thing to do is to label the actor correctly, the one whose only job is to initiate the use case, and then add those other supporting roles, aka "supporting actors", as the customer and the system.

Maybe a two column layout would be better to separate what the business use case has different from the steps in the system use case. That way you wouldn't have to duplicate the system use case as a distinct use case when it copies the steps from the business use case. Or just make sure you put what use cases are included at the top in the metadata and manually keep them in sync.

But for now, this reorganization of use case types massively helps my ability to model real life business use cases and I hope helps those who would like to document their business processes. Having an understanding that the use case starts with pure business functionality clarifies what a basic use case is about. Then as we automate some portions or all of it, the type of the use case changes and clarifies how to model it.

Thursday, May 25, 2017

A static new web site - Zurb's Foundation with Panini

I've been meaning to update my personal web site over the last ten years but just never got around to it. The web evolved. My site has been through basic html, custom php, custom JSP and Java filters, and one attempt at using a CSS framework called Semantic UI. The defining moment of need for change was when my web host was attacked by hackers in a DDOS attack lasting over a week.


It wasn't something I could spend a lot of time maintaining so spinning up Spring, WordPress or another unreasonably complex framework that I didn't need wasn't the answer. I had several basic requirements:

  1. Very low and easy maintenance
  2. High data use for link pages
  3. Cutting edge technology I can teach
    • CSS transpiler
    • JavaScript transpiler if possible
    • CSS/JS framework
A few requirements were worth noting as negative requirements:
  • No need for security
  • No need for tracking state
  • No need to collect data


The client-side frameworks getting all the buzz like Google's Angular and Facebook's React were slanted towards developing mobile sites and that was not where I was going since it adds so much complexity to the site. I had thought more along the lines of a serverless architecture but it looks like that is more bleeding edge. But it was simple. Or it will be at least in a few years.

I love that the WebAssembly team is moving along with a new game demo and no need to use Google Canary, but will have to face committees and meetings for probably another five to fifty years. But the end product will be a compiled client for browsers based on client-side frameworks just beginning to explore that territory.

The other framework style I decided to investigate was the static site generator. I could have static data files, static pages in template form and generate the pages as I had updates. No server side language. It's the perfect development workflow when you have no need for complex forms which is typical of a marketing site or a blog.

Jekyll was the big contender but I didn't want to deal with Ruby. Hexo seemed like a possibility but it uses ejs templating which seems so dated. I liked mustache styled templates after teaching and trying all sorts of templating styles. But I was running in circles investigating the various popular frameworks at StaticGen which ranks them and allows me to compare them easily, No solution yet.

So the next strategy was to ignore that and look at my CSS framework. It was going to be either Twitter Bootstrap or Zurb Foundation. I've had enough problems in class with getting around Bootstrap's site and using a simple template that it wasn't my first choice. And the fact that it's harder to read and has fewer JavaScript components than Foundation was why I decided on Zurb.


The thing I never noticed was that Zurb's developers use their own static site generator (they say flat file generator) called Panini with Foundation to build all their web sites. I like anyone who eats their own dog food. It's simple and uses Handlebars templating, SCSS, and either JSON or YAML formats for data. I installed it with Foundation's CLI and after two days of learning Handlebars and YAML, I was hooked. The Foundation CSS and JavaScript isn't that important to structure the site and will be added more in the future.

My pages are just simple combinations of cards for now. On a partial (included) page component, I have two Handlebars loops producing multiple cards with multiple links on them. Logic in Handlebars lets me work with data optionally. 

The responsive flow of the HTML5 multiple columns is simple and not based on any grid. I'll be refactoring the style attributes out of there eventually so I can use better SCSS style management and using much more of the CSS from Foundation but for now the default styling is adequate.

The partial page that holds the card component is only just a shell that declares the right data file and itself is included in a basic page layout template. The data is inserted when I build the file. Panini spins up a development server with BrowserSync to update the pages as I change the html (but not the data so far, I think I can tweak that though. Update - Kevin Ball of Zurb made the change to the Gulp file which takes care of this. Thanks for being very responsive!)

And the YAML data is easily understood, updated, and the schema customized just like a NoSQL style database. It has minimal delimiters and uses indentation for nesting. If you are off by one space, though, you will get some odd error messages when you try to view the page.

The final Gulp build combines all the CSS in one file, and all the JavaScript in one file so there will be minimal downloads and also does image compression.

It's a slick set of tools made as easy as possible for the flexibility that you get. I might be tacking on some JavaScript code to log sites that don't respond or collect other data especially from forms. I'd have to combine this with my local site and regenerate it again. But for now, it's fun again. Hopefully, this will last another ten years.