Summary

You can associate application use cases and requirements with the application's processes, directly within the system itself. Unlike external documentation and requirements repositories which can become disconnected from the developing application and stale over time, dynamic linking between the application and the use cases and requirements in the system allows the application to evolve without losing the ability to reference what was originally conceived and desired from the application. Because these associations are made directly in the system, you can:

• Generate up-to-date use case and requirement lists and matrix reports
• Gain insight into the application from a use case and requirements point of view
• Generate application documentation that includes the use case and requirement information (using the Application Document wizard)

Note: This article describes working with use cases and requirements in Version 6.2. For information about working with use cases and requirements in Version 6.1, see DCO 6.1 — Working with Application Use Cases and DCO 6.1 — Working with Application Requirements.

Suggested Approach

• About application use cases
• About application requirements
• Specifying use cases and requirements while creating an application profile
• Specifying information in the Details window
• Working with use cases and requirements in the generated application:
  • Working with use case rules
  • Linking use cases
  • Working with requirement rules
  • Linking requirements
• Creating reports about use cases and requirements
• Generating use case documentation

About application use cases

Application use cases describe, using business language, the steps required to process and resolve work in an application. You associate use cases with a work type's processes, subprocesses, and the individual process steps.

Usually, you specify application use cases when you create the application profile and discovery mapsfor the application using the Application Profiler. For a given discovery map, you can associate a specified use case with:

• Individual steps in the process, including any subprocesses
• The starting screen of the process
• The overall process

Those use cases specified at the process and subprocess level are typically described as comprehensive use cases. Like the traditional UML use case, such use cases usually describe the business process for a single work type from beginning to end.

Those use cases specified at the level of the starting screen or individual process steps are typically referred to as atomic use cases. These describe the smaller, more granular steps taken within the comprehensive use case. Because they are atomic, they can be reused to ensure consistency across other processes in an application, and make it easier to update processing steps when you need to implement a change.

Atomic use cases:

• Specify one or more actors
• Specify a single event or method that triggers it; think of it as one short process in a comprehensive use case
• Do not involve a change of ownership during the steps of the atomic use case
• Correspond to one particular step or series of steps within a screen flow type of process, or within a single flow action in the processing of a work type
• Describe the processes to be performed including the steps involved in completing the use case, applicable edits, and the expected behaviors and outcomes
• Provide enough business detail so that a developer can implement it and a user can test it
• Take only a few minutes to enter

The challenge in defining uses cases is how to approach breaking down a comprehensive and complicated work flow into these atomic units. This example shows how a comprehensive use case is broken down to identify and describe six smaller atomic use cases for a single work type.

About application requirements

Application requirements describe, using business language, the project and processing needs that must be met for processing work and data in the application. Think of requirements as an inventory of events, conditions, or functions that must be satisfied and tracked in a development project. They also provide benchmarks against which the application can be tested. Typically, you associate requirements with a corresponding use case, which itself is associated with the relevant processes, subprocesses, and process steps.

A good requirement:

• Describes the need in business terms so that it is easily understood by the implementation team
• Has an identified category type (such as "Enterprise standard" or "Business rule") and level of importance to the application
• Indicates its current implementation state (such as Open or Withdrawn)

Requirements are typically categorized according to the following requirement types:

Specifying use cases and requirements while creating an application profile

When using the Application Profiler to create an application profile, you can specify use cases and requirements either on the Create Processes step or the Project Explorerstep.

On the Create Processes step

Use the Discovery Map view of the Create Processes step of the Application Profiler to specify use cases for the following areas of a process:

For	How	Example
The overall process	Next to the Starting Process drop-down list that displays the name of the process, select Options > Define > Use case for process.
The process's starting screen	Next to the Starting Process drop-down list that displays the name of the process, select Options > Define > Use case for starting screen.
A step in the map	Double-click the step (shape)

For each of the three areas, the Details window opens for you to specify the details. The following image is the Details window for the Select Hardware step of the example Onboarding profile's Equipment Request process. (For more details about the example Onboarding profile, see DCO 6.2 — Creating Application Profiles and Discovery Maps.)

On the Project Explorer step

The Project Explorer step is typically used for entering use cases and requirements when those use cases and requirements are already specified in another source (such as an Excel file) and you want to import them from that source into the application profile.

To enter one use case:

Select the work type name in the list and click Add Use Case. The Details window opens for you to specify the use case's details.

To import a set of use cases defined in a Microsoft Excel file format:

Use the Use Cases tab on the Project Explorer step to import a set of requirements.

1. If the use cases are not already in the appropriate Excel file structure, save a copy of the template file with the appropriate structure to your local system by clicking Download Template and Save.

   Note: If there are use cases already specified and displayed on the Use Cases tab of the Project Explorer step, the downloaded Excel file contains the information about those use cases.

2. On your local system, open the saved template file, enter the information about the use cases, and save the file (either to the same file name or to a new file name).
3. Import the use cases by clicking Import and selecting the saved file on your local system. The system refreshes the Project Explorer step. Expand the corresponding work type to see its imported use cases.

To import a set of requirements defined in a Microsoft Excel file format:

Use the Requirements tab on the Project Explorer step to import a set of requirements.

1. If the requirements are not already in the appropriate Excel file structure, save a copy of the template file with the appropriate structure to your local system by clicking Download Template and Save.

   Note: If there are requirements already specified and displayed on the Requirements tab of the Project Explorer step, the downloaded Excel file contains the information about those requirements.

2. On your local system, open the saved template file, enter the requirements information, and save the file (either to the same file name or to a new file name).
3. Import the requirements by clicking Import and selecting the saved file on your local system. The system refreshes the Project Explorer step. Expand the corresponding work type to see its imported use cases.

Specifying information in the Details window

The Details window consists of tabs on which you enter the information about the use case, including its associated requirements. When adding a new use case, the system provides a default name, which you can change in this window. After entering information, click OKto save the information.

The following list provides short descriptions of what sort of information to enter on each tab. For more in-depth details of how to use the fields and controls on each tab, click the window's Help icon ( ).

Details tab

Use this tab to provide standard details about the use case, such as which actors process the work performed in this use case, who in the organization are subject matter experts for this use case, and pre-conditions and post-conditions. When this use case is for a process step, use the Shape field to select the flow shape that this use case represents. The shape you select is reflected in the color of the step in the discovery map. For example, the Automated Step choice results in a yellow step in the discovery map:

Description tab

Use this tab to provide free-form details that describe the steps involved in completing this use case, such as what the system displays, applicable edits and choices, and expected behavior.

You can enter the description either directly in the rich-text area field on this tab, or use Microsoft Word to capture the content. A typical approach for the rich-text area is to use it as a scratch pad for quickly capturing information. Then to further the use case details, click to use the Edit in Word feature and work on the description in Microsoft Word. Upon clicking , Word opens and loads the text from the rich-text area (if any). When you save in Word, the description is saved as a document file attached to the use case, and you use the Edit in Word feature for subsequent updates to the information.

Example: Description tab for Select Hardware use case

Requirements tab

Use this tab to create and manage a list of requirements associated with this use case. Click next to a requirement to display the rich text field for entering a description of the requirement.

Best practice tip: Typically the name you enter for a requirement starts with the same letter as the work item prefix, followed by a numeric, and then a short description. For example, if the work item prefix is ER-, a requirement for calculating cost would be ER002_Calculate_Cost.

Example: Requirements tab for Approve use case

Attachments tab

Use this tab to attach files to the use case and manage the attachments. Typically, use case attachments contain reference materials related to the use case such as Word files, UML diagrams, PowerPoint presentations, informal sketches, or files from external systems.

Use the Browse button to locate a file on your local system or network to attach, and then click Upload File to attach the file to this use case. After clicking Upload File, the system lists the file on the Attachments tab.

If the file is of Microsoft Word format (DOC or DOCX file types), the system displays the Use as Description? checkbox for the attachment. If you select this checkbox for an attachment, the contents of the attached DOC or DOCX file replaces any description entered on the Description tab of the Details window. Only one attachment can be used as the use case description at a time.

Select the Include in Document? checkbox to specify that system should include the contents of the attachment in a generated document whenever the use case is included (for example, when running the Application Document wizard).

Example: Attachments tab for Select Hardware use case

Comments tab

Typically, this tab is a location for collecting review comments from team members and stakeholders about the use case. These comments can provide a view into the evolution of the use case. You can view existing comments and post comments. The most recent comment is displayed at the top.

Example: Comments tab for Select Hardware use case

Working with use cases and requirements in the generated application

When the application is generated by the Application Accelerator, the system generates rules for the specified use cases and requirements. Because these rules are keyed to the application, you can continue to add, copy, version, and reuse them throughout the project's development lifecycle. By updating the use cases and requirements within the application itself during development, and adding new ones as the project progresses, you can use them to reflect the ongoing evolution of the implementation and keep your project team up to date as changes occur.

Using the Application - Work Types & Use Cases landing page

To work with an application's use cases and their associated requirements, you can use the Work Types & Use Cases gadget on the Application Overview landing page by clicking > Application > Overview > Work Types & Use Cases. The use cases are organized by work type, similar to the Project Explorer step in the Application Profiler.

Double-click a use case to open a window in which you can view and optionally update its information. The use case's associated requirements are listed on the Requirements tab of the window:

Using the Edit window's fields and controls is the same as using the Details window's fields and controls from the discovery map in the Application Profiler and Application Accelerator. For descriptions of what sort of information to enter on each tab, see Specifying information in the Details window.

To create a use case from the Work Types & Use Cases gadget: Right-click the work type or another use case for that work type and select Add Use Case from the context menu. Then specify the information in the Edit window that opens.

You can create requirements in the associated use case's Requirements tab.

Using the Application Explorer

Another method of working with the application's use cases and requirements is to open the individual rules using the Designer Studio's Application Explorer. In the Application Explorer, the underlying use case rules and requirement rules appear in the Application Definition category (as Application Use Case rules and Application Requirement rules):

Note: When you create an implementation (for example, when using the New Framework and Implementation choice), the requirement rules are stored in the implementation layer, instead of the framework layer.

From the Application Explorer, you can open a use case rule or requirement rule by selecting its name:

To create a new use case from the Application Explorer: Right-click the Application Use Case category and select New from the context menu. In the New window, specify the application name, work type, and a name for the use case and click Create. In the rule form that opens, specify the information about the use case and click to save the rule.

To create a new requirement from the Application Explorer: Right-click the Application Requirement category and select New from the context menu. In the New window, specify the application name and a name for the requirement and click Create. In the rule form that opens, specify the information about the requirement and click to save the rule.

Working with use case rules

A use case rule consists of tabs, in which the information about the use case is specified. The following list provides short descriptions of what sort of information to enter on each tab. For more in-depth details of how to use the fields and controls on each tab of the rule form, see the help topic About Application Use Case rules in your system's Developer Help.

Details

Like the Details tab in the Details window, use this tab to specify standard details about the overall use case, such as the type of process step, associated business objectives, actors, and what development state the use case is currently in (such as whether its development is deferred or pending information).

Description

Like the Description tab in the Details window, use this tab to provide free-form details that describe the steps involved in completing this use case, such as what the system displays, applicable edits and choices, and expected behavior. The Open In Word feature on this tab has the same behavior as it does in the Description tab in the Details window.

Requirements

Similar to the Requirements tab in the Details window, use this tab to associate a list of requirement rules with this use case. In this tab, the associations are a series of links to the requirement rules in the system.

Attachments

Similar to the Attachments tab in the Details window, use this tab to attach files to the use case and manage the attachments. Typically, these files are supporting collateral for the use case or its implementation. On this rule form tab, click Edit Attachments to add an attachment or modify an existing one. In the Attachments window that opens, provide a name (label) for the attached file, browse to its location on your local system, and click Add to add the attachment to the list. Then click Apply in the Attachments window to apply the updated list to the Attachmentstab.

The Include in Documentation? and Use as Description? checkboxes on the Attachments tab have the same behavior as their counterparts in the Attachments tab in the Details window.

Comments

Like the Comments tab in the Details window, use this tab to collect review comments from team members and stakeholders about the use case. The most recent comment is at the top.

Implementation

Use this tab to associate the use case to the rules for the work type's starting process, the process's components, and any individual activities that are configured to implement the use case during the development cycle.

Best Practice: Associating the use case with the rules within the system creates a comprehensive view of the relationship between the use case (which holds the details of the desired implementation) and the rules that implement the application and process the work.

The IN FLOW CONTEXT section lists links to the flow rules and underlying rules for the flow shapes associated with the use case. For example, if the properties panel for a connector shape in a process specifies this use case, a link to the underlying flow action rule for that connector shape appears in this list. You cannot add to or modify these links from the use case rule form.

The WITHOUT FLOW CONTEXT section lists activities that are associated with the use case. You can add to or modify the links in this section using the Edit Links button.

History

Common to rule forms in the system, use this tab to provide a description and rule usage information.

Linking use cases

By linking use cases to application and flow rules, you can create a comprehensive view within the system itself of the relationships between the use cases and the overall application and processing of work.

Linking to applications

Use cases are linked with an application when they are created in the application — either by the Application Accelerator's generation process or manually when you create a use case rule using the New rule method. You can view an application's list of associated use cases either on the Work Types & Use Cases gadget of the Application — Overview landing page or on the Use Cases tab of the application's Application rule.

Use cases listed in an application's Application rule:

Sort the list in one of the columns by clicking the column heading.

To open one of the use cases, select its row.

Linking to processes

The flow rule for a process links to use cases from:

• The steps in the discovery map on its Diagram tab
• The property panels of any Connector, Utility, Integrator, Subprocess, and Start shapes (and when editing a flow with Microsoft Visio, the Spinoff shape)
• Its Use Cases tab

Multiple shapes, subprocesses, and flows in the application can link to the same use case. If a use case is entered for a discovery map step on the Create Processes step of the Application Profiler or Application Accelerator, when the system generates the application, that use case is automatically set in the property panel for the flow diagram shape that corresponds to the step.

You can link a use case to a shape by opening the shape's property panel and selecting the use case in the Use Case field. Because the Use Case field's SmartPrompt lets you see and select from the list of all use cases linked to the application, you can reuse use cases that are already in the application.

On the flow rule's Use Cases tab, the linked use cases are categorized according to what they are used for:

• For Entire Flow — The overall process's use case.
• For Flow-Wide Local Actions - Use cases associated with the local actions specified on the flow rule's Design tab.
• For Flow Components - Use cases that are associated with the various processing components of the flow. The use cases listed in this category are specified in the property panels of the shapes in the flow's diagram.

For more details about the flow rule form and where use cases are specified for the process and its components, see the Flow rule's help topics in your system's Developer Help.

Working with requirement rules

A requirement rule consists of tabs, in which the information about the requirement is specified. The following list provides short descriptions of what sort of information to enter on each tab. For more in-depth details of how to use the fields and controls on each tab of the rule form, see the help topic About Application Requirement rules in your system's Developer Help.

Definition

Similar to the Requirements tab in the Details window, use this tab to specify a description of the requirement, as well as standard details such as its type (category), importance, and what development state the requirement is currently in (such as whether its development is deferred or complete).

Implementation

Use this tab to display and optionally delete requirement links to application, flow, and use case rules in the system.

Attachments

Use this tab to attach files to the requirement and manage the attachments. Typically, these files are supporting collateral for the requirement or its implementation. On this rule form tab, click Edit Attachments to add an attachment or modify an existing one. In the Attachments window that opens, provide a name (label) for the attached file, browse to its location on your local system, and click Add to add the attachment to the list. Then click Apply in the Attachments window to apply the updated list to the Attachments tab.

History

Common to rule forms in the system, use this tab to provide a description and rule usage information.

Linking requirements

By linking requirements to use cases, application rules, and flow rules, you create a comprehensive view within the system itself of the requirements and their relationships to those items. This view can communicate to you and your team how a single requirement can be linked to multiple rules and applications, to establish an ongoing pattern of standardization of design and reuse across projects and their resulting applications. If a requirement is updated at any point in time, the change is recorded and rippled through all rules linked to the requirement.

Each of the rule forms for the three items (applications, use cases, and flows) has a Requirements tab, in which you can view and update its list of linked-to requirements. For details on using the Requirements tab in the rule forms, see the Developer Help topics for that rule type.

Example of the Requirements tab in the Flow rule form:

To add or update links to requirements on this tab, click Edit.

Creating reports about use cases and requirements

The following table describes the standard reports that are available for use cases and requirements.

Example of a Use Case List report:

From the report's display window, you can click Export to Excel to export the listed information to a Microsoft Excel spreadsheet.

Generating use case documentation

With the Application Document wizard, you can create a formatted document that captures the application's use case information, and optionally the use cases' associated requirements, directly from the system itself. The wizard generates a Microsoft Word document that you can save to your local system and optionally update with additional edits.

To generate use case documentation for an application:

1. If the application is not already the in-context application in the Designer Studio, switch to the application by clicking the next to the name of the in-context application and using the Switch Application choice to switch to the application that has the use cases you want to document. The in-context application is the application displayed in the Designer Studio header bar.

1. Start the Application Document wizard by selecting > Application > Tools > Document.
2. On the first step of the wizard (the Select step), select the application name in the Select an Application list. The available choices are the in-context application and the applications it is built on, if any.
3. Select Use Case Document in the Select a Templatefield.

   The system refreshes the wizard's Select step to display a list of the use cases in the selected application. Select the checkboxes next to the use cases you want included in the output document. To select all use cases, select the uppermost checkbox (in the column header).

Note: If a use case rule has Microsoft Word attachments specified with the Include in Document? checkbox selected, the generated document includes the contents of the attachments.

Tip: To work with the list more easily (for example, when there are hundreds of use cases), filter the set of displayed use cases using column filters. To use a column filter, click the down arrow to the right of the column header, select those values that you want displayed, and click Apply. The screen refreshes to only show entries that match the items specified in the filter. For example, by clicking the down arrow for the Work Type column, you can select to display only those use cases for a particular work type.

1. Optional: Select the Include Linked Requirements checkbox to include information about the use cases' linked-to requirements in the output document.
2. Click Document Now.

When the system starts generating the output document, it launches Microsoft Word on your local system in a separate window, and then loads the rule information, images, and other text information (according to the current wizard settings) into that window. When the content has finished loading into Microsoft Word, you can review and edit it, and save a local copy.

For information about more of the features of the Application Document wizard, including how to add custom chapters to the output document, see DCO 6.2 — Using the Application Document Wizard. To exit the wizard after generating an output document, click Close.

Additional information

DCO 6.2 — Creating Application Profiles and Discovery Maps

DCO 6.2 — Using the Application Accelerator

DCO 6.2 — Using the Application Document Wizard

DCO 6.1 — Working with Application Use Cases

DCO 6.1 — Working with Application Requirements