In the case of tools for drawing diagrams, for example, the UML tool, storyboards can be expressed using class diagrams and activity diagrams. However, the UML diagrams created aren’t intuitively understood. It’s not easy to imagine screens and flows from the diagrams, especially for stakeholders who aren’t familiar with UML. It also doesn’t satisfy the requirements of interactive storyboarding and easy maintenance.

A tool that supports all the features needed is J-CASE Tag Library. J-CASE takes a different approach than the other tools. First we create JSP files that describe use cases and screens. It generates documents with use case style and UML diagrams for use cases and navigation maps. Compared to other GUI tools, we can call J-CASE a tool for developers. If you have expertise in JSP, you’ll understand how to use the tags, and realize it can extend custom codes using other tag libraries.

In general, you may think we shouldn’t use code for writing storyboards. However, I need to emphasize that there’s an advantage in writing them with JSP in the analysis and design phase. My experience is that developers typically find conflicts and missing requirements, even though we’ve spent time reviewing the requirements and specification documents. That’s because programming languages are limited in expressions and require more precision than natural language. When developers can’t translate the requirements that are written in natural language into code, they recognize that something is wrong or missing. Since J-CASE requires us to write some code, we can also get similar recognitions when writing JSPs for storyboards.

Create Use Case and Action JSPs
Let’s start to create a use case and storyboard using J-CASE tags. As a sample use case, I’ll use a “Log In” use case available for download on the J-CASE Web site. Before creating the storyboards, core scenarios have to be captured in use cases. Figure 2 shows the use case description of the “Log In” use case.

J-CASE expresses the use case using two kinds of JSP: Use Case JSP and Action JSP (see Figure 3). Main; alternative flows (flows of events) are described in Action JSPs, and the rest of the information, such as use case ID, name, Brief Description, and Actor, is described in Use Case JSP.

In the Use Case JSP, use case information except flows of events is described using a <jc:useCase> tag. Use Case ID, name, actor, and the link to the first Action JSP are specified in the attributes of the tag.

Other additional information (Brief Description and Actor) is added using a <jc:desc> tag in the body of the <jc:useCase>. Listing 1 represents use case information of the “Log In” use case.

The Use Case JSP is converted into a Use Case Frame as shown in Figure 4. By clicking the link labeled “[UC01] Log in” you can start experiencing the use case.

In the Action JSP, actions performed by actors are described using <jc:actions> and <jc:action> tags. Each <jc:action> represents an event that the actor (end user or system) can take on the page, and the flow of events is represented by making links between Action JSPs. Listing 2 shows two actions that the user may take on the login page.

The first action represents the event of Main Flow Step 2 in Figure 2, and the second one is Alternative Flow 1 Step 1. The Action JSP is converted as in Figure 5.

Generate Use Case Document
Once you create all Use Case and Action JSPs, you can execute a <jc:generateUseCase> tag to generate a use case document from the JSPs. The tag requires input and output attributes. The path of the Use Case JSP is specified in the input, and the HTML path of the use case document to be generated is specified in the output (see Listing 3).

Refer to Figure 2 again. It’s the use case HTML generated by the <jc:generateUseCase> tag.

Visualize the Use Case
Screens, system processes, and so on aren’t typically mentioned in use cases to focus on capturing core requirements. Now that the “Log In” use case is created, it’s time to describe the screens and processes.

To visualize the pages, J-CASE provides <jc:screen>, <jc:dialog>, etc. For example, the login form can be specified using HTML code in the <jc:screen> tag as shown in Listing 4. The <jc:screen> tag is displayed as shown in Figure 6.

A dialog to ask the user for a “Yes” or “No” can be represented using the <jc:dialog> tag shown in Listing 5. The code generates the dialog frame shown in Figure 7 when accessing the JSP.

The logic of the system process can be defined as a Java method in a JSP declaration tag (<%! %>). In a JSP that represents a login process, you can define, for example, the authenticate method shown in Listing 6, which authenticates the user by checking the credential parameter.

The method annotated with @JCaseProcess is automatically executed when the page is loaded, and you can see the execution results using the <jc:processResults> tag. In case authentication fails, you’ll see the process results as shown in Figure 8.

Generate Storyboard Document
After adding screens and processes on the JSPs, you can execute the <jc:generateUseCase> tag again to generate the storyboard document. When you access the JSP, including the <jc:generateUseCase>, the storyboard.html shown in Figure 9 is generated. You’ll also see the screens and process results you added on it this time.

Generate UML Diagrams
The <jc:generateUseCase> tag also accepts useCaseDiagram and navigationMap attributes, which generate XML files of the UML diagrams. If you execute <jc:generateUseCase> with those attributes as shown Listing 8, XML files that can be edited with EclipseUML are also generated.

Figure 10 shows the use case diagram of the “Log In” use case. Figure 11 shows the navigation map that represents navigation among pages (JSPs). With these diagrams, we can verify if there are any conflicts or redundancies in defined use cases and flows.

Conclusion
Storyboarding is a technique to bridge a considerable gap between use cases and the specifications required for actual implementation. While writing storyboards, you’ll find conflicts, redundancy, and omissions in the use cases. Visualized screens and flows also give us a better understanding. To get the benefits, it’s important to choose the right storyboard tool according to the requirements of your project.

This article recommends using a tool that supports creating interactive storyboarding, and introduces the J-CASE Tag Library. It helps you refine use cases and define better specifications.

Resource

• J-CASE Homepage