Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I'm a beginner when it comes to writing use cases, but I searched a lot and most of the materials I found mentioned that I should concentrate on the business value to the customer when writing a use case.

example: Use case for a search page

1- User opens search page  
2- User provides the search word
3- The system presents the search results

Of course it was easy to write the use case as the system had some kind of UI that that user interacted with.

However, what if I'm writing a use case for a cron job?

I was developing a module that basically connects to a number of ftp servers to download some files then the downloaded files are parsed to generate some reports and finally these reports are uploaded to my company's ftp server.

The problem is the only business value for the whole module is the generation of the reports (i.e. The team who requested that module only cares about the reports not anything else).

This is the use case I came up with:

1- The system downloads the files from the ftp servers.
2- The system generates the reports from the files.
3- The system uploads the reports to the company's ftp server.

However as I was reading Applying UML and Patterns, 3rd released edition the author introduced a monopoly game use case as follows: use case

A whole game in just 3 steps!!! I thought since the whole purpose of the game is just the simulation then maybe that's why he didn't mention any details, and maybe I should do the same too.


So now I have exactly 3 mixed questions:

1- Should use cases focus entirely on the business value for the customer and ignore internal operations?

2- In case a cron job is invoked how to determine the business value if the customer has no interaction what so ever with the system?

3- A colleague of mine actually contradicted with my approach entirely and he insisted that I should write as much details as possible in a use case (as instead of The system downloads the files from the ftp servers it should be decomposed to the smaller functions that make this feature such as get list of servers from DB,connect to ftp server, check if there are any files, download file,delete file from ftp server,close connection). Is this correct or better?

share|improve this question

closed as not a real question by MichaelT, Martijn Pieters, Walter, Kilian Foth, World Engineer Mar 25 '13 at 0:06

It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center.If this question can be reworded to fit the rules in the help center, please edit the question.

6 Answers 6

up vote 1 down vote accepted

UML has rules but UML is not a methodology. You either adopt a methodology or use your best judgment. The answers below are based on my own judgment.

1- Should use cases focus entirely on the business value for the customer and ignore internal operations?

Use cases may be used during requirements gathering. Such use cases focus on what the customer wants and understands mostly. Use cases can also be used for design and testing. In this type of use case, you should not ignore internal operation scenarios that affect the output. Such cases are sometimes sub-cases of the ones used in requirements gathering. However, in practice, when the use case is too detailed, it becomes a process. You need to decide which tool to use for which level of detail and which audience.

2- In case a cron job is invoked how to determine the business value if the customer has no interaction what so ever with the system?

Cron jobs are invoked as a result of an event that is meaningful to the business in some context, for example end-of-accounting-period. The business gains value by receiving the report and analyzing its contents on the event the business specified in the requirements. The real value is not in the cron job firing, the real value is in making the specific report available to the customer (or at least generated) at that specific event (time).

3 - Your third question (not listed so that the answer is concise)

What you are describing is the question text for question 3 is a detailed process not a use case. You better use a UML activity diagram for that type of detail and leave the high level covered in the business use case.

share|improve this answer
    
+1 The most comprehensive answer till now :D, but just to make things clearer for me what would my use case for the cron job look like taking into account what you mentioned in the 2nd part of your answer. –  Songo May 3 '12 at 12:28
    
Thanks for your comment. I'd suggest you follow the example in the answer provided by @pgfearo. Note that your project must establish the 'value of Use Case' in your specific work. As mentioned above, Use Case can be used in different ways and does not have syntax rigor. Based on that definition, you could identify other (supporting) documentation that would cover the other facts about the system and the business. For example, the business rules governing the generation of the report is important and should be documented somewhere (other than in code) in detail. –  Emmad Kareem May 4 '12 at 2:47

Behind every use case there's a story or 'use case scenario'. You need to think about that first before breaking things down into steps and actors and so on. Also, don't forget that time can be an actor.

To start with, it shouldn't matter if the story begins and ends at points that are outside the scope of the project, it at least sets the context and it's easier to narrow things down later. Don't dwell on these 'outer limits' but at least consider them - who's using the reports, how are they using them, what happens if they're late, what happens if they don't arrive at all?

You could end up with something like:

  1. User sets timer (or asks the system admin to) to produce reports daily
  2. The timer event triggers the system
  3. The system updates the reports
  4. Next day, the user has a fresh set of reports to...
share|improve this answer
1  
+1, time is an actor –  Emmad Kareem May 3 '12 at 8:33
    
+1 for The timer event triggers the system :D I have been struggling to compose such a sentence that actually makes sense. Then what do you propose for describing 'how' the system does the use case? Right now After getting the list of features from my customer I generate a use case diagram then write a scenario for each use case. It seems to separate What from How I'll need something like a flow diagram right? –  Songo May 3 '12 at 11:55
    
When you start describing How, a sequence diagram might be useful - but keep each diagram very simple –  pgfearo May 5 '12 at 16:12

In my understanding the usecase (or userstory) should concentrate on what is requiered. (for example a customer in a web-shop can search for a product by brandname)

in your examples you concentrate on how the requirement can be implemented. (i.e. steps needed to implement the usecase).

to answer you question

 > Writing a Killer use case for a cron job

A Cronjob is a technical implementation detail that does not have a businessvalue of its own.

the killer use case would be: "if the webshop crashes most of its data can be restored from the backup within 10 minutes"

One implementation detail of this usecase would be that there is a cron job that backs-up the data every 10 minutes.

share|improve this answer
    
+1 I agree with you that I'm concentrating more on the HOW, but what's your suggestion for describing how should the system operate? –  Songo May 3 '12 at 12:23
1  
I think the HOW (includig cron jobs) belong to Business_modeling or UML Behavior_diagrams and not to use cases –  k3b May 3 '12 at 13:55
    
Aha! I see now. Thanks for the links. –  Songo May 3 '12 at 14:16

When writing "batch" use cases I have always found they read better if the define the "Scheduler" as an actor. In your case the "Scheduler" is "cron" but in the great tradition of use cases "Scheduler" is generic and free of implementation details. Also in your case create an Actor "The Other System" or whatever to represent the ftp server. So:-

  1. Scheduler - requests Sales report generation.
  2. System - requests Widet Sales data from Widgets Server.
  3. Wdiget server - sends files.
  4. System - generates Widget Sales reports.
  5. System - sends reports to Widgets server
  6. Use case ends.

Remember use cases are about the interaction of the proposed system with anyone or anything else. Interactions within the "System" should never appear in use cases.

share|improve this answer
    
Interactions within the "System" should never appear in use cases. What if the system validates the file? or a password validation in a log in system? should that be mentioned in the use case or not? it is done internally in the system. –  Songo May 4 '12 at 16:48
    
@songo: "System validates password" -- never "system reads /etc/myapp/passwords.txt", that is an implementation detail. "System sends validation request to LDAP server" is OK though as the LDAP server is a separate entity and NFRs may specify use of a particular single singnon infrastructure. –  James Anderson May 5 '12 at 2:15
2- In case a cron job is invoked how to determine the business value if the customer
has no interaction what so ever with the system?

Get to the why. Why are you doing this cron-job? Is someone else downloading these reports by hand every day and sorting them out in excell?

Then you can describe your value for the business as: "saves 2 hours of work every day which translates in savings of about $10k/year."

(edit)

(i.e. The team who requested that module only cares about the reports not anything else).

The requesting team should prove the business value, not you. You can give an estimate of what the costs of the technical implementation are going to be. Then the guy in charge can make a decision whether or not to go through with it.

share|improve this answer
    
That's a good point,but just to make things clearer for me what should my use case for the cron job look like? –  Songo May 3 '12 at 12:30

Here's a 'real' use case I'm probably going to implement

I have a Google Spreadsheet that I track equipment repairs on. It contains various information (ex serial number, repair request number, etc). This report is just for internal tracking purposes but at the beginning of each month a snapshot of the current state needs to be taken and consolidated into a report.

The system is setup to cover two purposes. First, to repair/replace all gear that is damaged or non-functional. Second, to maintain detailed records of what broke, and how long it took to fix it so the cumulative data can be taken into perspective when the next generation of gear is specified.

The bad part about this setup is, the reports are generated manually which requires a lot of copying/pasting and the potential for human error.

To solve the problem, the algorithm is simple. Loop through the items in the listing and copy them into the proper section (based on type) excluding all that contain a return date (the date it was given back and closed out).

To implement this, Google Apps Scripting now is capable of running scheduled jobs. The code would run once a month, generate the report document, and email a link for the document to the FSR for final inspection before being forwarded up the chain.

This would save an estimated 4 hours of work/month for 4 FSRs. Altogether that makes 192 hr/yr in 'real' savings. The greatest benefit is, the computer generated reports scale much better than human interaction does.

I assumed 4 FSRs but the increase in throughput may open opportunities to pick up more work in the future. To give another member the same capability is as easy as copying the status template.

share|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.