README.md

Scaffolding a Use Case with a Use Case Templates Repository

Besides the practical use case writing style guide introduced in here, we also developed a use case templates repository, where commonly used use cases are archived for reuse in different domain contexts. These use case templates are not meant to constrain the way a use case is written but to provide a starting point for requirements engineers. Think of them as intermediate good or semi-finished products, which need to be completed by requirements engineers to obtain a full-fledged use case specification.

An easy-to-copy-and-paste version of this repository is available at Google Docs. A real project's use case specification following the style guide and using the templates repository is available at here. Feel free to provide feedback.

Note: A <whatever> as postulated by Alistair Cockburn represents an important business object. A requirements engineer only needs to substitute a concrete business object for <whatever>. Text enclosed in square brackets ''[]" and displayed in italics is included to provide guidance to the author and should be deleted before publishing the use case.

Table of contents

1. Find <whatever> s
2. View a <whatever>
3. Create a <whatever>
4. Change a <whatever>
5. Delete a <whatever>
6. Generate a <report type> report

1. Find <whatever> s

UC ID and Name:	UC-01: Find <whatever>s
Created By:		Date Created:
Primary Actor:	User	Secondary Actors:
Trigger:	The User indicates to find <whatever>s.
Description:	The User wants to find <whatever>s which match specific criteria, so that she can decide what to do next or other <rationale of this use case>.
Preconditions:	PRE-1. The User is logged into the System.
Postconditions:	POST-1. A list of matching <whatever>s is returned and displayed to the User. It is possible that the list is empty.
Main Success Scenario:	The User indicates to find <whatever>s. The System asks the User to enter search values according to the "Search criteria" defined in the Associated Information of this use case. The User enters one or more search values and confirms that she has finished entering. The System finds all <whatever>s that match the provided search criteria values. The System displays the matching <whatever>s according to the "Search results display strategy" and the "Sort criteria" defined in the Associated Information of this use case. Use case ends.
Extensions:	4a. No matching <whatever>s are found: 4a1. The System alerts the User that no matching <whatever>s are found. 4a2. The User either chooses to UC-03: create a <whatever> or chooses to terminate the use case or chooses to return to step 2 of the normal flow. 5a. The User chooses to select a different set of properties to display the matching <whatever>s: 5a1. The System displays the current "Search results display strategy." 5a2. The User enters a customized "Search results display strategy," confirms that she has finished entering, and returns to step 5 of the normal flow. 5b. The User chooses to re-sort the search results: 5b1. The User re-sorts the search result according to the "Sort criteria" defined in the Associated Information of this use case and returns to step 5 of the normal flow.
Priority:	High
Frequency of Use:	Approximately *** user, average of *** usages per week.
Business Rules:
Associated Information:	Search criteria (aka search fields, search attributes/properties, search details, searchable qualities): Search property name Data type Validation rule Security/access concerns Reference to glossary First name String Required Last name String Required Phone number String Required, (999) 999-9999 format Physical address String Required, valid US address format (street, suite/room/floor, city, state, postal code) Email String Required, valid email Search results display strategy (specify which properties to display for each matching <whatever>): TBD Sort criteria: TBD
Related Use Cases:	The User can perform other actions after this use case. After this use case succeeds, the User may select any of the displayed <whatever>s and take any of the following actions on the selected item: UC-02: View a <whatever> UC-03: Create a <whatever> UC-04: Change a <whatever> UC-05: Delete a <whatever>
Assumptions:
Open Issues:

See examples that adopt this template: Use Case 6: Spirit Director/SuperFrog Student finds appearance requests and Use Case 15: Spirit Director finds SuperFrog Students.

⬆ back to top

2. View a <whatever>

UC ID and Name:	UC-02: View a <whatever>
Created By:		Date Created:
Primary Actor:	User	Secondary Actors:
Trigger:	The User indicates to view the details of a <whatever>.
Description:	The User wants to view the details of a <whatever>, so that she can get a better idea of <whatever> or other <rationale of this use case>.
Preconditions:	PRE-1. The User is logged into the System. PRE-2. The User has the "view" privilege. See the Business Rules of this use case.
Postconditions:	POST-1. The details of the specified <whatever> are displayed to the User.
Main Success Scenario:	The User indicates to view the details of a <whatever>. The User finds a list of <whatever>s through UC-01: Find <whatever>s. The User views the list and chooses to view the details of one specific <whatever>. The System retrieves and displays the details of this <whatever> according to the "Details" defined in the Associated Information and the "Security/access concerns" defined in the Business Rules of this use case. The User views the details of this <whatever>. Use case ends.
Extensions:
Priority:	High
Frequency of Use:	Approximately *** user, average of *** usages per week.
Business Rules:	Security/access concerns TBD
Associated Information:	Property name Data type Editability Security/access concerns Reference to glossary
Related Use Cases:	UC-01: Find <whatever>s The User can perform other actions after this use case. After this use case succeeds, the User may take any of the following actions on this <whatever>: UC-04: Change a <whatever> UC-05: Delete a <whatever> UC-: View a <whatever2> UC-: View a <whatever3>
Assumptions:
Open Issues:

See examples that adopt this template: Use Case 7: Spirit Director/SuperFrog Student views an appearance request and Use Case 16: Spirit Director views a SuperFrog Student account.

⬆ back to top

3. Create a <whatever>

UC ID and Name:	UC-03: Create a <whatever>
Created By:		Date Created:
Primary Actor:	User	Secondary Actors:
Trigger:	The User indicates to create a new <whatever>.
Description:	The User wants to create a new <whatever>, so that <rationale of this use case>.
Preconditions:	PRE-1. The User is logged into the System. PRE-2. The User has the "create" privilege. See the Business Rules of this use case. PRE-3. If this <whatever> is a dependent object, in other words, cannot exist by itself, the dependency object must exist first.
Postconditions:	POST-1. The new <whatever> is stored in the System.
Main Success Scenario:	The User indicates to create a new <whatever>. The System asks the User to enter the details of this new <whatever> according to the "Details" defined in the Associated Information of this use case. The User enters the details of this new <whatever> and confirms that she has finished. The System validates the User's inputs according to the "Details" defined in the Associated Information of this use case. The System validates that the creation of the new <whatever> will not duplicate any existing <whatever> according to the "Duplication detection rules" defined in the Associated Information of this use case. The System displays the details of the new <whatever> and asks the User to confirm the creation. The User either confirms the creation (continues the normal flow) or chooses to modify the details (return to step 3). The System saves the new <whatever> and informs the User that this <whatever> has been created. The System notifies relevant actors about the creation of the <whatever> according to the "Notification" defined in the Associated Information of this use case. Use case ends.
Extensions:	4a. Input validation rule violation: 4a1. The System alerts the User that an input validation rule is violated and displays the nature and location of the error. 4a2. The User corrects the mistake and returns to step 4 of the normal flow. 5a. The System finds possible duplicates from the existing <whatever>s: 5a1. The System alerts the User that the <whatever> she is trying to create already exists in the System. 5a2. <Specify how to handle it here>. 5a3. The User either chooses to correct the mistake and return to step 4 of the normal flow or chooses to terminate the use case.
Priority:	High
Frequency of Use:	Approximately *** user, average of *** usages per week.
Business Rules:	Security/access concerns TBD
Associated Information:	Property name Data type Editability Validatoin rule Effect of change Reference to glossary Column "Effect of change" shows consequences of modification other than saving. Duplication detection rules: Identifiers (A set of properties to prevent duplicate creation) Notification: Specify who to notify and what format A basic set of commonly used constraints: Checks that the input is not empty (empty means trimmed input length is 0). Date: Checks whether the input date is in a predefined format Checks whether the input date is in the future Checks whether the input date is in the present or in the future Checks whether the input date is in the past Checks whether the input date is in the past or in the present Checks whether the input date is in between a date range Numeric value: Checks whether the input value is less than or equal to the specified maximum Checks whether the input value is higher than or equal to the specified minimum Checks whether the input value is a number having up to certain number of digits and certain number of fractional digits Checks whether the input value is strictly positive. Zero values are considered invalid Checks whether the input value is positive or zero Checks whether the input value is strictly negative. Zero values are considered invalid Checks whether the input value is negative or zero Checks whether the input value is between min and max (inclusive) Text: Checks whether the specified character sequence's length is between min and max (inclusive) Checks whether the specified character sequence is a valid email address Checks whether the specified character sequence is a valid phone number Checks whether the specified string matches the provided regular expression The User shall be able to cancel the use case at any time prior to submitting it.
Related Use Cases:	The User may first choose to UC-01: Find <whatever>s but cannot find any, then decide to create one.
Assumptions:
Open Issues:

See examples that adopt this template: Use Case 1: Customer requests a SuperFrog appearance and Use Case 13: Spirit Director creates account for a new SuperFrog Student.

⬆ back to top

4. Change a <whatever>

UC ID and Name:	UC-04: Change a <whatever>
Created By:		Date Created:
Primary Actor:	User	Secondary Actors:
Trigger:	The User indicates to change the details of an existing <whatever>.
Description:	The User wants to change the details of an existing <whatever>, so that <rationale of this use case>.
Preconditions:	PRE-1. The User is logged into the System. PRE-2. The User has the "change" privilege. See the Business Rules of this use case. PRE-3. <whatever> can be changed after the creation.
Postconditions:	POST-1. Changes made to the <whatever> are stored in the System.
Main Success Scenario:	The User indicates to change the details of an existing <whatever>. The User views the details of this <whatever> through UC-02: View a <whatever>. The User chooses to change the details of this <whatever>. The System asks the User to make changes to this <whatever> where allowed according to the "Details" defined in the Associated Information and the "Security/access concerns" defined in the Business Rules of this use case. The User makes changes to this <whatever> until she confirms that she has finished changing. The System validates the User's changes and alerts warning messages according to the "Details" defined in the Associated Information of this use case. The User acknowledges the warnings and chooses to continue. The System displays the updated details of this <whatever> and alerts the User to confirm the change. The User either confirms the change (continues the normal flow) or chooses to continue to change the details (return to step 5). The System saves the changes, carries out the effect of change according to the "Details" defined in the Associated Information of this use case, and informs the User that this <whatever> has been changed. The System notifies relevant actors about the change of <whatever> according to the "Notification" defined in the Associated Information of this use case. Use case ends.
Extensions:	6a. Input validation rule violation: 6a1. The System alerts the User that an input validation rule is violated and displays the nature and location of the error. 6a2. The User corrects the mistake and returns to step 6 of the normal flow.
Priority:	High
Frequency of Use:	Approximately *** user, average of *** usages per week.
Business Rules:	Security/access concerns TBD
Associated Information:	Property name Data type Editability Validatoin rule Effect of change Warning Reference to glossary Column "Effect of change" shows consequences of modification other than saving. Notification: Specify who to notify and what format A basic set of commonly used constraints: Checks that the input is not empty (empty means trimmed input length is 0). Date: Checks whether the input date is in a predefined format Checks whether the input date is in the future Checks whether the input date is in the present or in the future Checks whether the input date is in the past Checks whether the input date is in the past or in the present Checks whether the input date is in between a date range Numeric value: Checks whether the input value is less than or equal to the specified maximum Checks whether the input value is higher than or equal to the specified minimum Checks whether the input value is a number having up to certain number of digits and certain number of fractional digits Checks whether the input value is strictly positive. Zero values are considered invalid Checks whether the input value is positive or zero Checks whether the input value is strictly negative. Zero values are considered invalid Checks whether the input value is negative or zero Checks whether the input value is between min and max (inclusive) Text: Checks whether the specified character sequence's length is between min and max (inclusive) Checks whether the specified character sequence is a valid email address Checks whether the specified character sequence is a valid phone number Checks whether the specified string matches the provided regular expression The User shall be able to cancel the use case at any time prior to submitting it.
Related Use Cases:	The User may first choose to UC-02: View a <whatever>, then decide to change one. [If the "Details" table contains an item which itself is a complex object (e.g., list), refer to UC: change an appearance. Similarly, in UC: change an appearance, refer to the UC: change a SuperFrog Student. So a user may not change the detailed appearance in this use case, if a user wants to do that, she will need to go to UC-04: change an appearance.]
Assumptions:
Open Issues:

See examples that adopt this template: Use Case 2: Customer edits request details, Use Case 8: Spirit Director edits basic information of a request, and Use Case 20: SuperFrog Student edits profile information.

⬆ back to top

5. Delete a <whatever>

UC ID and Name:	UC-05: Delete a <whatever>
Created By:		Date Created:
Primary Actor:	User	Secondary Actors:
Trigger:	The User indicates to delete an existing <whatever>.
Description:	The User wants to delete an existing <whatever>, so that <rationale of this use case>.
Preconditions:	PRE-1. The User is logged into the System. PRE-2. The User has the "delete" privilege. See the Business Rules of this use case. PRE-3. <whatever> can be deleted after the creation.
Postconditions:	POST-1. The <whatever> is deleted from the System according to the "Deletion strategy" defined in the Associated Information of this use case.
Main Success Scenario:	The User indicates to delete an existing <whatever>. The User views the details of this <whatever> through UC-02: View a <whatever>. The User chooses to delete this <whatever>. The System validates that the deletion can be carried out according to the "Data integrity and deletion rules" and the "Referring objects handling strategy" defined in the Associated Information of this use case. The System alerts the User of the consequences of this deletion according to the "Data integrity and deletion rules" defined in the Associated Information of this use case, warns the User about the deletion, and asks the User to confirm. The User confirms the deletion. The System deletes the <whatever> according to the "Deletion strategy" and the "Referring objects handling strategy" defined in the Associated Information of this use case and alerts the User that this <whatever> has been deleted. The System notifies relevant actors about the deletion of <whatever> according to the "Notification" defined in the Associated Information of this use case. Use case ends.
Extensions:	4a. Data integrity and deletion rule violation: 4a1. The System alerts the User that a deletion rule is violated and displays the nature of the violation. 4a2. The System prompts possible actions to resolve the violation. 4a3. Use case terminates.
Priority:	High
Frequency of Use:	Approximately *** user, average of *** usages per week.
Business Rules:	Security/access concerns TBD
Associated Information:	Deletion strategy: [ Physical delete: permanently remove the business domain object from the System (cannot be recovered) Move deleted object including any related objects that are being deleted along with it from the System to an archive or audit database Logic delete: mark a business domain object as "deleted" but still keep it in the live system, the deleted object will not be visible or available to all normal functions and users. Logically, "deleted" objects are not supposed to be "recovered" i.e., they will never be used again. Only special administrative users with privileged access can view them (Langlands, 2010) ] Referring objects handling strategy: Specify what action to take in respect of the related objects of <whatever> In case of composition: Dependent objects are deleted along with <whatever>, aka cascading deletion The User needs to first delete dependent objects and then resume this use case In case of regular association: TBD [Violation is more serious than warning. Violation will prevent the deletion and just terminate the use case, while the user can choose to ignore a warning and continue the use case. Please also list alert messages for each violation and warning.] Data integrity and deletion rules: Violation 1: <Detailed violation rule> See Business Rules of this use case Violation 2: <Detailed violation rule> See Business Rules of this use case ... Referring objects handling strategy: Warning 1: Dependent objects will be deleted along with <whatever>. Warning 2: Due to deletion, the referring objects will be left in limbo. ... Notification: Specify who to notify and what format The User shall be able to cancel the use case at any time prior to submitting it.
Related Use Cases:	The User may first choose to UC-02: View a <whatever>, then decide to delete one.
Assumptions:
Open Issues:

⬆ back to top

6. Generate a <report type> report

UC ID and Name:	UC-06: Generate a <report type> report
Created By:		Date Created:
Primary Actor:	User [Users who will generate the report or use it to make decisions]	Secondary Actors:	Report recipient(s) [Users who will generate the report or use it to make decisions]
Trigger:	The User indicates to generate a <report type> report (on demand). [If automatically, specify the triggering conditions or events and frequency (daily, weekly, monthly etc.) here.]
Description:	The User wants to run a <report type> report, so that <purpose or business intent of the report: e.g., what business decisions will be made using information in the report, and by whom>.
Preconditions:	PRE-1. The User is logged into the System. PRE-2. The User has the "generate report" privilege. See the Business Rules of this use case.
Postconditions:	POST-1. The details of the report are returned and displayed to the User.
Main Success Scenario:	The User indicates to generate a <report type> report. The System asks the User to provide configurable report generating parameters according to the "Report generating parameters" defined in the Associated Information of this use case. The User enters the required parameters and confirms that she has finished entering. The System validates the input parameters according to the "Report generating parameters" defined in the Associated Information of this use case. The System generates the <report type> report according to the "Report generating algorithm" defined in the Associated Information of this use case and displays to the User according to the "Report generating parameters" defined in Associated Information of this use case. The System delivers the generated report according to the specified report disposition in the specified format in the "Report generating parameters" defined in the Associated Information of this use case. Use case ends.
Extensions:	4a. Input validation rule violation: 4b1. The System alerts the User that an input validation rule is violated and displays the nature and location of the error. 4b2. The User corrects the mistake and returns to step 4 of the normal flow. 5a. No data is returned: 5b1. The System alerts the User that no data is available in the generated report. 5b2. The User either chooses to return to step 3 of the normal flow or chooses to terminate the use case. 6a. The User chooses to "Save report generating parameters" for future reuse: 6a1. The System asks the User to enter a name for the current set of report generating parameters. 6a2. The User enters a name. 6a3. The System saves the name and the current set report generating parameters. 6a4. Use case resumes at the step of interruption.
Priority:	High
Frequency of Use:	Approximately *** user, average of *** usages per week.
Business Rules:	Security/access concerns [Specify any limitations regarding which individuals, groups, or organizations are permitted to generate or view the report or which data they are permitted to select for inclusion. Identify any relevant business rules concerning security.]
Associated Information:	Report generating parameters: Report title Data source: The applications, files, databases, or data warehouses from which data will be extracted Data selection criteria (logic for what data to select and what to exclude) Columns/fields/properties to include Filter criteria used to restrict the report query prior to running the report Report visualization (table, charts, graph) Sorting criteria Pagination criteria if table visualization is selected Disposition of the report after it is generated. The options available will be displayed in the System, sent to a recipient, downloaded to local disk, printed, stored somewhere for future retrieval. Format of the generated report. The options available will be PDF, CSV, RTF, and HTML. Report generating algorithm: [Specify how the report is generated based on user's input parameter. Specify calculations or other transformations that are performed to generate the data displayed.]
Related Use Cases:
Assumptions:	If the job is too large, the System prompts the User to select to run the report immediately or to schedule a time for it to run. The System will display a projected run time, based on historical run times.
Open Issues:

See examples that adopt this template: Use Case 18: Spirit Director generates TCU Honorarium (Payment for services) Request Forms and Use Case 19: Spirit Director generates a SuperFrog Students performance report.

⬆ back to top