What is CRUD
So how do you handle CRUD in your use cases? Please don’t confuse CRUD with CRAP in your use cases. That’s a lot harder to deal with and requires a conversation with your subject matter experts (SMEs). 
CRUD is an acronym for Create, Read, Update and Delete. It describes the lifecycle in the maintenance of system data, whether that data is stored in a database or is file based data stored in a document management system like SharePoint.
The problem with CRUD when writing a use case is the duplication of process steps and the differing pre and post conditions between the four lifecycle stages. For instance, the steps in creating a new data entity are much the same as those involved in updating an existing record/file, but when creating a new element, the pre-condition is that the information doesn’t exist, while in an update, the pre-condition is that the element does exist. Likewise, the post condition for the Create stage is that the information has been saved while in the Delete stage, it has been removed/deleted from the repository.
Use Case Basics
Before we go too far in discussing how to handle CRUD in use cases, let’s make sure we’re all on the same page on the basic components of a use case. According to IIBA, a use case is “A description of the observable interaction between an actor (or actors) and a solution that occurs when the actor uses the system to accomplish a specific goal.” (Business Analysis Body of Knowledge (BABOK) Guide 3rd Edition, page 455.)
Note: To avoid a few comments and questions later, I’m talking about relatively low level processing here so the following describes system uses cases and not business use cases which are typically higher level. CRUD does not belong in a business use case.
Although I’m sure some of you will disagree, the use case components that I was first taught and which I still use today include:
- Use case name and brief description.
i.e. The unique ID and/or name for the use case and a one- line description of its purpose.
- Actors.
i.e. A person, organization or system that will interact with the process (use case).
- Pre-conditions.
i.e. The things that have to exist or not exist before the use case can be executed.
- Post Conditions.
i.e. The things that will exist or will not exist after the use case has finished executing normally.
- Trigger(s).
i.e. The event that initiates the use case.
- Basic Flow.
i.e. The “happy path”. The process steps that are most frequently followed that result in the defined post condition(s)
- Alternative Flow(s).
i.e. The process steps that will be followed when the process deviates from the “happy path” but still results in achieving the post condition(s).
- Exception Flow(s).
i.e. The process steps that will be followed that will NOT result in the defined post condition(s). The use of Exception Flows simplifies your Post Conditions as you don’t have to specify scenarios that rarely occur.
Option 1 – CRUD in the same document
Because of the amount of duplication between the CRUD process steps, many analysts document all four data lifecycle stages in a single use case document. I am not a fan of this option.
Although common steps in the process need only be written once in an alternative flow and then be referenced from a parent flow which could be either the Basic Flow or another higher level Alternative Flow, the pre and post conditions for each CRUD stage are different. How do we deal with this in a single use case document?
When writing a single document CRUD use case, the pre and post conditions cannot reference the state of the data entity either before or after the execution of the use case. Therefore, the use case must include steps in the Basic Flow to verify the existence of the data entity and then branch to the appropriate Alternative Flow based on whether it exists or not. (Yes, I know use cases aren’t supposed to “branch” but as an old programmer, it’s the easiest way to document these scenarios.)
At a conference I attended some years ago, a speaker had a novel method of circumventing this problem. He suggested having pre and post conditions in the alternative flows rather than the use case level to describe the system state before and after the alternative flow was triggered. The reason I don’t like this is you are deviating from the basic structure of a use case as I understand it. What he is proposing is simply combining multiple use cases into a single document with an overarching name and description. This could prove problematic depending on the requirements management tool you’re using and could be confusing to your stakeholders who are expecting a consistent format for the organization’s use cases. e.g. Conditions for a CRUD use case would be at the alternative flow level while conditions for other types of uses case would be at the use case level.
Using a single use case to document all four CRUD stages is best employed when the process is simple. Complicated processes involving multiple scenarios will result in a massive use case document that is intimidating to reviewers. Simple processes may also allow the reader to make assumptions on the state of the data entity in an alternative flow while still accomplishing the goal of our colleague who proposed pre and post conditions at the flow level. Although assumptions are usually discouraged in business analysis, some conditions can be considered self evident. For instance, if you have alternative flows titled “Create New Customer” and “Update Existing Customer”, it should be safe to assume the reader will know that the customer doesn’t exist in scenario 1 but does exist in scenario 2. Of course, this means your alternative flow naming convention must clearly define the stage of the CRUD lifecycle it describes.
Option 2 – CRUD in multiple document
Using multiple use case documents to describe your CRUD processes brings its own problems, as listed in my opening. The pre and post conditions and trigger differences are avoided, making use case purest like myself happy, however the duplication of process steps is now an issue.
The degree of concern over process step duplication depends on the level of detail in your use case. A use case step that simply says “Validate entry fields” in combination with a number of functional requirements and/or business rules documented in another location or format (e.g. Declarative “shall” statements stored in a requirements management tool database) is different than multiple steps in the flow that describes a series of validations and/or calculations performed on the data entered in that CRUD stage. No SME wants to review 30 use case statements that they have already approved in another CRUD use case. (e.g. They approved the Create use case and are now reviewing the Update use case.) This duplication also carries long term maintenance issues and the risk of differences between the same validation in different CRUD uses cases.
However, if your organization doesn’t maintain their uses cases long term (What a waste!) and they are only required for the duration of the project, duplicating steps in multiple CRUD uses cases may be advantageous as it makes reviewing the process easier for stakeholders and maintainability isn’t as much of an issue.
Option 3 – CRUD in an Include use case
The compromise between options 1 and 2 is to use an Include use case so process steps common to multiple CRUD stages are only documented once, in a single document and then referenced from a base/parent use case.
Include use cases can also be used where the result of the process steps is important to a class of stakeholders, but not the steps themselves. For instance, an Include use case is frequently used to document the steps in logging into a system. Although the log-in steps are of interest to the development team and must be addressed at some point, they’re not important to the SMEs reviewing the CRUD stage being described in the base/parent use case. Example:
1.1. Log into system. (See System Log-in Use Case)
1.2. System displays Customer Demographics page for associated customer.
In software architecture, the equivalent of an Include use case would be an external program or sub-procedure where common code is stored and then either copied into the parent program when it is compiled or referenced separately and called as a separate module or object from the mainline program. Although programmers are not bound by the existence of an Include use case to structure their code in the same way, development will typically branch off in a similar manner.
Depending on your requirements management tool, the process steps in the Include use case can also be displayed directly in the base/parent use case as if it were originally written there. This makes reviewing the combined use case easier for SMEs as it avoids flipping between different documents in order to get a complete picture of the process, while avoiding the maintenance issues described in option 2 above.
However, in the absence of a requirements management tool with this capability, the advantages offered by an Include use case are dependant on the number of process steps that are duplicated. The greater the number of duplicated steps, the greater benefits realized by using an Include use case.
Separating the CRUD data validation steps from the overall process flow also lends itself to an Agile methodology as the high level process can be defined and confirmed quickly and then more detailed analysis done on the common data validations later, in a separate iteration and documented in the Include use case.
Final thoughts (and questions)
In summary, which is the best format for dealing with CRUD in a use case? As with many things in business analysis, the answer is . . . it depends.
- Does your organization maintain requirements and use cases long term or are they discarded after the project is completed? For short term use, the simplest may be to duplicate CRUD process steps in the appropriate use cases to make it easier for stakeholders to read.
- How many steps are in the duplicated CRUD stages? If CRUD validations are documented as steps in the use case, duplicating them in multiple documents makes maintenance and reliability difficult. However, if those same validations and calculations are documented as functional requirements or business rules in a central repository and there are limited steps in the use case flow that refers to the business rules’ location, using multiple use case documents is often the easiest for reviewers to follow.
- What are the capabilities of your requirements management tool? Does it have the ability to seamlessly display an Include use case’s contents in the parent use case making the reader believe the process steps are actually documented there? If so, an Include use case is an excellent option. If you don’t have such a tool, SMEs can easily get frustrated searching for different documents and piecing together the segmented functionality themselves.
Tip: If you don’t have a requirements management tool, be generous with your use of hyperlinks to referenced documents. Stakeholders will really appreciate it if there is a link to the Include use case in the base use case so they don’t have to search for the secondary document.
- Do your stakeholders prefer seeing CRUD validations as steps in a uses case or are they comfortable with requirements and business rules in a declarative form? If they’re okay with IEEE “shall” statements, the amount of duplication between CRUD uses cases can be reduced and utilizing multiple CRUD use cases may be the best option.
- Most importantly, what are your organization’s standards for requirements, business rules and use cases? Consistency is always the preferred option as it makes stakeholders more comfortable reviewing requirement documents from different analysts.
Author: Les Mathisen, Project Analyst, Saskatchewan Crop Insurance Corp.
Les is a project manager and business analyst with a degree in Computer Technology from the Northern Alberta Institute of Technology and a certificate in Business Analysis from the University of Regina. He has his CCBA, CBAP and PBA certifications as well as PMP, PRINCE2, Agile PM Practitioner, PSM and ITIL Foundation certifications.