Welcome back to another exciting article in the systems integration 101 series. In this article we are going to walk through the first step of the systems integration process, creating use cases.
Over the years I've created tons of systems integration use cases. I like to think I've come up with a pretty good process for detailing out use cases that works quite well. In today's article I am going to walk you through just that.
Summary of Lesson #2
Use cases are where the magic happens, I've seen so many folks jump right into data mapping or systems mapping and they skip the use case. Folks, if this is you, stop right now! You're just making things much worse for yourself in the long run.
Use cases are a vital part of the systems integration process. So much so, that I would say if you had to do one thing, and only one thing, that you should do use cases.
Why do I say that? With use cases you will identify the who, what, when, how, and why of your task(s). Without these key questions answered you risk missing a set of functionality or a system that is key to the whole integration.
I am speaking from experience here!
In today's article we are going to discuss how to write a use case:
- How to write a use case
- Identifying the primary actors (the who)
- Creating the main success scenario (the how)
- Defining the goal of the use case (the why)
Now, throughout this article I may use terms that are new to you, that's ok! I simply want you to be exposed to the terminology that those outside the BAS world may use. This will help you immensely as you start to engage folks outside your work department.
Lesson #2: How to Create a Systems Integration Use Case
Da, da, da....
Well, that was weird, making a trumpet noise announcing the start of the article doesn't work quite as well in text..
How to create a systems integration use case.
We in the BAS world tend to have a bad habit. We like to do things are way and often do not look outside our industry for new methods and approaches. The use case is a perfect example of this.
How many times have you seen use cases formatted according to the CSI MasterFormat. Sure all the parts and pieces are there, but at the end of the day, most of these glimmering pieces of structural perfection are... junk.
They are about as useful as me at an art show, sorry art lovers, I don't get art, never will.
So, why don't we suspend disbelief for a moment and assume that we in the BAS world can do use cases a different way, and by different way I mean the way the rest of the world "does" them.
What are the pieces of a use case?
If you remember our scenario in our first article we are going to tie two BAS together into a single user interface. This use case scenario is surprisingly common in today's BAS world.
Our first step to creating this use case is to identify a few key things.
- What systems or people are involved?
- What does success look like?
- What is the goal of the use case?
What systems are involved?
If you remember earlier in the article I mentioned some unfamiliar terms. One of those terms was the term actor. I want you to think of a use case a play. The use case is going to tell the actors what do at certain points in the process.
So at this point you may be thinking an actor is a person, you're partially correct. An actor, according to most use case documentation, defines a role played by a user or system that interacts with the subject.
Logically that brings us to our next question. What is a subject?
A subject is the system or systems that should perform a task based on the use case scenario.
Ok, so time for our first question. Who are our actors and who are our subjects? I want you to take a second and think this through, a lot of people mess up here and its important to identify the correct actors and subjects up front.
So, pause for a second look a way from the screen and think through who your actors and subjects are. Remember we are thinking through the use case of two BAS tying into a single user interface.
Ok you done?
Great, so your list probably looks something like this.
Actor(s): BAS 1, BAS 2, Technician, Supervisor, Common User
System(s): New BAS Graphical User Interface (GUI)
At this point we have our actors and systems identified now we need to determine how to put these pieces together.
How do you put these pieces together?
This part is often called your narrative. It is the narrative that will form your use case and will tell how the different actors communicate with the system.
We know that we want a user to be able to use the new GUI to be able to access both BAS. Do you know what we call that? We call that our main success scenario (MSS). Our MSS is our success criteria.
A use case should have one MSS.
If you write a use case and you have more than one MSS you are most likely combining use cases. It is critically important that you separate your use cases to focus on one MSS.
You see, systems integration is complicated enough, the idea is that your use cases will be built for a single purpose. That way when you create the integrations you can segment your use cases. This will allow you to troubleshoot, code, and support your use cases individually.
So then, how many use cases do we have with the single GUI scenario. Off the top of my head I can think of several.
- User Logs into the single GUI
- User logs out of the single GUI
- User modifies data in the single GUI
- User runs reports in the single GUI
Now you may be thinking, oh come on Phil, it's a simple integrated BAS GUI. I'd caution you to pause anytime you start to think this way. You need to think through each scenario.
For example, if the new GUI needs a login, which login does it use?
Does it use BAS 1's credentials or BAS 2?
Does the new GUI log user actions?
If so where?
How does it tie to IT systems?
And those are just the set of questions for the first scenario.
So, lets build out a use case.
Building the Use Case
Building out a use case isn't very hard. In this scenario we are going to build out two use cases:
- User logs into the single GUI
- User modifies data in the single GUI
User logs into the single GUI UC#1
Actors: BAS Technician, BAS 1 and BAS 2
Systems: Single GUI, BAS User Databases
Main Success Scenario: User Logs Into Single GUI
Description: The BAS Technician will be prompted for a login at the single GUI. The user can use his/her login credentials from BAS 1 or BAS 2. Upon the GUI authenticating with BAS 1 or BAS 2 the user will be granted access to the application.
User modifies data in the single GUI UC#2
Actors: BAS Technician, BAS 1 and BAS 2
Systems: Single GUI
Main Success Scenario: User modifies data in the single GUI
Description: Once the BAS technician is logged into the single GUI (see use case 1 user logs into the single gui), the user will be able to access BAS point data and modify that data. The single GUI will confirm and log any data modifications.
Ok, this use case has something glaringly wrong with it. Can you tell me what that is? I'll give you a hint, it occurs in the last sentence.
Give up? Well, here is the problem. Use case #2 is actually two use cases. The modification use case is good, but at the end of the use case I added confirm and log any data modifications.
Now at first glance this may not seem like a big deal. It actually may seem like I am splitting hairs and being anal retentive. However, do you know how the single GUI will log data modifications?
Will it log them in BAS 1's database?
How will the confirmation happen?
Do you see how this could lead to finger-pointing at a job site?
The BAS technician for BAS #1 says "It wasn't my job to log any data modifications, your use case clearly says the new GUI will log data modifications."
In the BAS techs defense the use case does say that, but is that what you want?
I will leave you to ponder that question.
Finalizing the use case
With our use cases mapped out we should now be ready to move onto our next step.
Wait! Stop!
We aren't ready yet! Do you know why? Because we haven't gotten our stakeholders buy-in.
Stakeholder, there's a hundred-dollar word for you! A stakeholder is a person who can be impacted by the use case. To often I've seen, cause I would never do this right :-D, people go and create use cases that are absolutely beautiful.
And these use cases float their beautiful selves right to the garbage can! This happens because the use case creator did not take the time to meet with stakeholders in order to get "buy-in".
In order to avoid a ton of headache after the fact I encourage you to meet with your stakeholders in order to ensure that your use cases have their "buy-in".
Conclusion
So, there you have it, use cases! You've got to do them!
Now if you recall, I said there are multiple use cases for our integration. I'm going to challenge you here.
The way you get better at use cases is by writing them. So, here is what I want you to do.
In the comments section below, think through the use cases that our single GUI integration could have. I want you to post a use case in the comments. Use the format we followed in this article and over the next few weeks I will hop in and review your use case and provide feedback!
Until next week!
