1 Introduction

International research projects most often involve some kind of software system development. Such software systems not just embody the project findings in a way that enables these findings to be used and experimented with, but their development is often a driving force for the whole project. This puts researchers of different profiles unrelated to software development into the role of software developers. Professional software development partners are often involved in order to facilitate the process of software development, but other partners often significantly contribute to various software development stages, including the actual programming.

Working versions of such software systems are needed in short time in order to make further experiments. These, in turn, reveal further requirements that need to be implemented within the system. No surprise that such research and development teams often turn to agile software development, which indeed suits well the conditions they are facing.

Thanks to intense communication and close collaboration within, preferably, colocated teams, agile software development can be very successful even with minimal actual efforts put into capturing requirements in a written form. This is why user stories, which are one-sentence “promises for a conversation between a requirements expert and a developer,” as Cockburn denoted them [5], appear to be sufficient there. Cohn also suggests that it is better that the development team and the customer discuss the details [7]. But international research project settings usually do not provide such conditions. The members of the team reside in different countries and most of the communication goes on remotely.

Related user stories are commonly grouped into so-called epics. Dalpiaz and Sturm show a simple use case and an epic whose user stories correspond very much to the steps of that use case [11]. However, typical use cases require more writing than user stories and they usually involve some level of modularization, but they create a more firm basis for the development. This is especially important for distributed teams of professional and nonprofessional software developers, who are native in different languages, and for whom the system they are developing is not a goal in itself, but rather a tool for obtaining the experimentation and evaluation results.

In this paper, we describe and generalize our recent experience of applying use case modeling to establish a firm software development basis for further exploration within an innovative tourist information system developed in a research setting of an ongoing Horizon 2020 project named Promotion of Rural Museums and Heritage Sites in the Vicinity of European Pilgrimage Routes (rurAllure).Footnote 1 The paper also exposes some software analysis artifacts that might be useful for the development of other innovative tourist information systems.

The rest of the paper is organized as follows. Section 2 explains how are use cases currently understood and misunderstood. Section 3 describes the essentials of how we applied use case modeling in the rurAllure project. Section 4 describes how and to what extent we elaborated our use case model. Section 5 describes what support models have we used. Section 6 discusses the benefits of use cases for our project.

Section 7 compares the approach proposed in this paper to related work. Section 8 concludes the paper and indicates some possibilities for further work.

2 Current (mis)understanding of use cases

Use cases are typical, goal oriented interactions of users and software systems [5]. They represent an inexpensive means of exploring what really a software system should enable.

Use cases can be seen as a way of generalizing collections of related scenarios [5], specific stories of what can happen when a user attempts to reach a particular goal. The value of collecting and analyzing scenarios has been recognized by Carroll in his scenario-based design [4, 21]. However, in use case modeling the generalization commonly happens outright, without recording the actual scenarios.

As they target interactions, use cases are most often expressed as simple sequences of steps switching the actions taken by the user and the system response towards its successful end. They may look as simple as this use case identified within the rurAllure system:

Generate a Pilgrimage Plan

A pilgrim lets the planning service generate a pilgrimage plan according to the pilgrimage plan parameters.

1. The pilgrim wants to create a pilgrimage plan.

2. The web portal prompts for the pilgrimage plan parameters: origin, destination (if different from the traditional destination of the pilgrimage route), start date (default time assumed), main mode of mobility, companions (traveling alone, in a couple, or in a group, with or without children, etc.), interests (gastronomy, architecture, literary heritage, etc.).

3. The pilgrim enters the pilgrimage plan parameters (at least origin, start date and mode of mobility).

4. The web portal gets a pilgrimage plan corresponding to the parameters from the planning service.

5. The web portal displays the pilgrimage plan as a sequence of daily pilgrimage plans and as a map.

6. The pilgrim decides to save the plan.

7. The pilgrim sets the plan accessibility (private/replicable/shared).

8. The web portal saves the changes.

9. The use case ends.

These sequences of steps are called flows of events or simply flows [16]. Sometimes, they are denoted as scenarios [5] (not to be confused with scenarios as they are perceived by Carroll [4, 21]).

Any but trivial applications of use cases requires some kind of their modularization. In the Generate a Pilgrimage Plan use case, we need to deal with the situation when no direct booking options are available. This could have been be included in the basic flow we showed, but that would certainly make the intent of the use case less comprehensible. Consequently, such modifications or extensions to basic flows are introduced in separate modules called alternative (or alternate) flows. They were introduced by Ivar Jacobson at OOPSLA 87 [13, 17], who proposed the initial use case modeling notation [14], but the idea was conceived already in 1967 [15]. This notation also enabled including (activating) a use case within another use case or extending (affecting) a use case from within another use case.

Alistair Cockburn proposed a slightly different style of writing use cases, mainly with respect to alternative flows [5]. More importantly, Cockburn distinguished between use cases as a concept and as a notation, emphasizing that the most important use cases are those targeting user goals, while also showing that the same notation can be used to capture use cases targeting summary goals and subfunction use cases [5].

While Cockburn, as compared to Jacobson, favors even more concise step formulation, using alternative flows instead of conditional behavior (if-like statements), Overgaard and Palmkvist [26] write use cases as verbose, prose-like text and do not use step numbering at all. Coplien and Bjørnvig [10] suggest a two-column table format: one column represents the user’s actions, while the other one those taken by the system.

Practitioners pick and choose features they learned about from different sources, and possibly even introduce their own. Some features from different notations can be combined, while some are mutually exclusive [25]. Albeit use cases look like algorithms, it is important to bear in mind that they will be read by nonprogrammers, so enforcing the use of keywords and restricting their semantics may easily make them look like code, which can be harmful to their comprehensibility. On the other hand, there have been efforts to preserve use cases in code [2, 3, 9, 10, 16], so that code could be read like use cases, but this is not meant as a substitute for expressing use cases in natural language.

Dozens of approaches to how a “right” use case should be written are proposed, with more or less structuring and limitations in terms of allowed keywords and even complete phrases, often contradictory in their recommendations [24].

Speaking of use case modeling notations, UML use case diagrams cannot be left out. Attracted to use case diagrams by their graphical nature, many practitioners easily confuse them for the real thing: the text. Use case diagrams provide only an overview of use cases and cannot express their flows. Consequently, it is best to draw use case diagrams only after they have been written. Otherwise, one can easily end up with a number of use case diagrams—or one big use case diagram—with bubbles and relationships no one understands. Even worse, use case writers might feel an obligation to stick to this unfounded picture and start to make up descriptions of use cases that make no sense. Unfortunately, even very good books on use case modeling, such as the one by Overgaard and Palmkvist, mislead practitioners to start their use case modeling with use case diagrams [26].

Use cases are not a user interface specification. They are concepts of the users’ mind that can be supported by the software system and its user interface more or less thoroughly.Footnote 2 A use case can be realized over one or several user interface forms, while the same form may be involved in several use case realizations. Consequently, use cases should not mention windows, buttons, menus, labels, and other elements of a typical windows graphical user interface or any user interface in general. Having the user interface elements mentioned here and there usually does not pose a problem and this is what one can see very often in practice [5]. However, in order not to fall into the trap of confusing use cases for a user interface specification, it is best to actively abstract from any occurrence of user interface elements. For example, instead of saying a user “clicks the OK button” we can say that they “confirm the action.”

3 The rurAllure pilgrimage support system: a case for use cases

As mentioned in the introduction, rurAllure is an ongoing Horizon 2020 project on promotion of rural museums and heritage sites in the vicinity of European pilgrimage routes. The project strives at networking relevant institutions in the area rural heritage, mapping rural museums and heritage sites in the vicinity of the four selected European pilgrimage routes, developing studies of the corresponding rural heritage, and developing the corresponding pilgrimage support system. To be able to deal with these complex objectives, the project consortium, coordinated by Martín López Nores, one of the authors of this paper, involves 15 partners from 6 European countries, which form a team of social and humanities scientists and historians, museum practitioners, experts in economy and territorial development, computer scientists, designers, experts in tourism and marketing, as well as private companies and government institutions. The rurAllure also involves more than 60 associated partners (the list is growing).

While the project brings many reports, activities, established connections, etc., it is exactly this pilgrimage support system that puts everything together into something that everyone can see and interact with. High expectations of this system are not only on the side of the European Commission representatives, associated partners, and general audience, but also on the side of the consortium as such. Everyone wants to see how their work “works.” Such a reflection of their work within a functional software system then motivates the consortium to produce more of interesting results.

3.1 The process

Developing interactive systems such as this pilgrimage support system requires an agile process. Without any doubt, an agile process assumes the ability to rapidly respond to change. Despite what many people think, frantically responding to change is not the sole activity in agile software development. To be able to respond to change responsibly, there must be some common grounds around which everything spins and can safely land if necessary. These common grounds should not be unnecessarily detailed. In fact, they should be lean. This is a different approach to software development and work in general, which strives not to produce waste. One of the consequences this has is that decisions are not made until there is sufficient information to do so. This prevents from creating unnecessary artifacts: waste. In other words, a lean process is a basis for an agile process [10].

To be agile and lean requires close, direct communication among all the people involved in the process. This the lean secret: everyone, all together, from early on [10]. This is the philosophy behind the approach applied to develop a pilgrimage support system helping pilgrims to enrich their pilgrimages with rural heritage experience.

A general idea of what such a pilgrimage support system should look like was established already in the project proposal. Based on this, GVAM,Footnote 3 a company which is one of the partners in the rurAllure project, came with an initial set of graphical user interface (GUI) form wireframes, so that the project participants as the designers of the system could better imagine how it would work. As we started with the implementation immediately after expressing use cases, we did not feel the need to use any mock-up design tools to get an interactive form of the GUI. An initial idea of the system architecture was also proposed. Part of it was based on the microservice architecture, with an initial description of the services.

A brainstorming session was initiated with all the project participants being invited. It continued over a Trello board, which was used to collect usage narrative fragments as short and personalized ideas of what the system should offer to pilgrims. More pilgrimage knowledgeable partners, mainly Associazione Europea delle Vie Francigene, Mária Út Egyesület, and Fundación Uxío Novoneyra, including all project participants with individual pilgrimage experience, were opening new perspectives, while more technically oriented project participants watched over feasibility.

In parallel with collecting usage narrative fragments—and relying on them—the activity of expressing the essential ideas of what the system is and how it is going to behave in a coherent form was started. On the one hand, the basic (data) concepts were identified and related to each other. On the other hand, the system behavior was expressed in the initial set of use cases. All this was open and accessible to all the project participants for commenting and modifications using the capabilities of collaborative editing on the Synology Drive (much like Google Drive documents).

We cannot say the process was smooth. But if it were, that would mean that the communication was not frank and we should probably be afraid of what system would come out of this. There were many discrepancies, but all were dealt with in a very short time with a goal of building common understanding. All the constituent parts of analysis and design—usage narratives, domain model, use cases, architecture, and GUI design—were continuously cross-checked for consistency.

3.2 Usage narratives

Some typical system usages were explored by describing them from the perspective of imagined specific users as if they were real people in usage narratives. Usage narratives are often used—formally or informally—as precursors to use cases [5]. Personas and scenarios [8] are practically analogous to usage narratives.

The usage narratives we dealt with in rurAllure introduced the three types of users envisaged: the pilgrims (the subject of most of the narratives), the vendors who want to offer services along the routes (one narrative), and the administrators who manage the platform’s content for each route (two narratives). It is important to note that our goal was not to cover all the interactions, but to make the starting point for use cases, within which we strived for completeness.

Here is an example of a usage narrative named Using the rurAllure Website and Mobile Application:

Camille is a young French woman who is interested in European culture and trekking. She is planning her holiday vacations and is thinking about traveling a pilgrimage route somewhere in Europe. Though quite familiar with pilgrimage routes such as the Way of St. Jacques, she wants to discover new routes and places in Europe she doesn’t know that well, as she is willing to submerge herself in lesser known paths and places. Doing a quick search on her computer, she heads towards the rurAllure website, which seems to have what she is looking for.

Getting a Personalized Trip is a longer usage narrative:

Although there are featured trips available, Camille sees that there is a trip planner and she wants to give it a try, expecting to create a trip from scratch specifically tailored to her interests and preferences. Firstly, she introduces the dates she wants to travel. Although the route itself starts from Mariazell in Austria she prefers choosing Kőszeg in Hungary as the point of departure because she had been to Austria on other occasions. She defines şumuleu Ciuc (Csíksomlyó) in Romania as the destination. Then, she includes some other details: she wants to travel by bicycle and checks the tags of “history,” “nature” and “gastronomy.” Finally, she clicks the “See your plan” button.

The website now displays the proposed itinerary, which is displayed both on a map and as a sequence of daily plans connecting successive places/activities of interest. At the point of departure she is offered various bicycle rental options among the services offered, in case she wanted to rent a bike at Kőszeg. On the map, Camille finds that some segments appear with dashed lines; by passing the mouse pointer over them, she understands that those segments are detours from the official paths, that take her to visiting some places related to the selected tags of “history,” “nature” and “gastronomy.” She loves this idea, but browsing the info sheets of those places she chooses to remove one of them for not looking particularly interesting.

At some point, while browsing the successive daily plans and looking at the locations, Camille notices a list of popular places that she could visit, too, even if not related to the aforementioned tags. One of them, the Salty spa of Cozmeni, really catches her attention, so she has it added to her plan and sets it as the ending location for the corresponding day. Camille is fascinated to see that the planner updates the subsequent stages automatically!

As we can see, for usage narratives it is perfectly fine to refer to imagined user interface controls. They imagine specific situations which involve specific people. Through this, it is easier for a writer to “see” how the imagined system “looks” and “feels” as if it were already implemented.

3.3 Domain model: what the system is and the domain dictionary

While use cases describe what the system does, which tends to develop and change over time, there is an internal, more stable perspective that needs to be taken first: what the system is. This perspective is primarily about data.

Figure 1 shows the essential (application) domain concepts and how they are related to each other using the UML class diagram notation. What is displayed in the figure is the essence of the pilgrimage support system. Its main concern is around a pilgrimage plan, which is a sequence of daily pilgrimage plans. These, in turn, represent sequences of pilgrimage sites and other places/activities of interest (abbreviated as POI) related to activity or hospitality, along with timing. Some of the activity/hospitality POIs are proposed by vendors. All these, including the pilgrimage sites, are just geographical locations with accompanying information. A pilgrimage plan as such or each planned POI can be associated with narratives,Footnote 4 which are any media content offering an interpretation of the heritage found nearby.

Fig. 1
figure 1

Domain model

Full size image

This domain model looks more like a data model than a comprehensive conceptual model as proposed by Johnson and Henderson [18]. This is because our intention was not to get overwhelmed by the functionality, which was to be explored through use case modeling following this activity. The same concepts constitute the domain dictionary, which features their textual definitions (see Appendix A). A domain dictionary forms the basis for a coherent user interface vocabulary. Where the application domain is not sufficiently understood, writing use cases may help in exploring it and establishing the domain concepts.

3.4 Essential use cases

In rurAllure, a simple and common approach based mainly on Jacobson’s notation [14, 16] was applied to keep use cases readily understandable. As mentioned in Sect. 2, at the simplest level, a use case is captured as a sequence of steps that defines the most probable, successful interaction. These form so-called basic flows.Footnote 5 They are usually preceded by a short use case description. Recall the Generate a Pilgrimage Plan use case from Sect. 2. Notice how the first step clearly expresses how the use case starts. The flow maintains the interaction switching the actions taken by the user and the system response towards its successful end. It skips the details considered unnecessary to gain the understanding of the use case.

For the rurAllure use case model, we started exactly with how the planning of pilgrimage trips should work as we saw this as the main feature of the system. No one was raising this as an issue within the initial set of GUI form wireframes, nor within the usage narratives. However, looking at everything we had, we realized we did not understand how the planning of pilgrimage trips should work, so we started guessing and exposed our idea as a use case.

As we were maintaining the use case model in a shared, collaboratively edited document in a system similar to Google documents, the project coordinator and colleagues from GVAM reacted very soon complaining that this was not supposed to be as the use case said. Interestingly, they disagreed among themselves. This is not bad, on the contrary: what happened is actually desirable. Use cases enabled us to expose the idea in a cheap model clearly and then to judge it. We were able to correct the use case arriving at the version we introduced here within the course of several iterations.

This is what we did also with other use cases. We always favored more important and challenging use cases over trivial ones, such as those related to registration or logging in. Often, we wrote only basic flows and checked to see whether we agree upon the essence of these use cases before elaborating them.

3.5 Actors

A user interacting with the system takes a particular role or plays a particular actor. The idea of an actor helps consolidate the system for different sets of use cases. Consequently, a software system looks and behaves differently for different actors.

Apart from the users, whose hierarchy is depicted in Fig. 2, parts of the system and its parts can also be perceived as actors. These are depicted in Fig. 3. In order to ensure common understanding, it is also important to provide textual definitions of actors (see Appendix B).

Fig. 2
figure 2

Users

Full size image
Fig. 3
figure 3

System actors

Full size image

The concrete actors represent actual types of users and actual parts of the system, while abstract actors and inheritance (generalization/specialization, in a correct UML parlance) are used so that we can express use cases common to several of these actors.

Services are further elaborated in Fig. 4. It is important to emphasize that this is an analytical perspective on the system, which is needed here in order to expose its essential behavior. For example, web portal stands here for the interaction carried via a web based interface.

Fig. 4
figure 4

Service actors

Full size image

The rurAllure system is actually a platform with several ways to access its functionality. From the perspective of a common user, this is always through one of the portals: the web portal or the mobile application. The scope of some use cases is limited to only one of them, while some use cases are valid for both of them. This can be expressed through the abstract Portal system actor. Consider this use case:

[PORTAL] Book an Activity or Service at a POI

A pilgrim books an activity or service offered at a POI.

Basic Flow

1. The pilgrim wants to book an activity or service offered at a POI.

2. The portal displays the direct booking options available for the activity or service (normally accompanied by pricing) provided by the booking service.

3. The pilgrim selects a booking option and confirms the selection.

4. The planning service recomputes the affected daily pilgrimage plan (and subsequent ones if necessary).

5. The portal displays the updated pilgrimage plan.

6. The booking service stores the information that the corresponding option is booked.

7. The booking service sends an email notification to the pilgrim and to the corresponding vendor.

8. The use case ends.

The scope is indicated before the use case name. We emphasize the names of the actors for their easier recognition. We kept revising this set of actors as we elaborated the use case model.

We could imagine other systems accessing the platform through its services, but this was not addressed by our use case model.

4 Elaborating the use case model

A use case model is useless if no one understands it. Moreover, use cases are written in natural language in order to be readily understandable by all stakeholders. Due to this, we were careful in introducing more advanced use case modeling features. However, we think that without using alternative flows,Footnote 6 include and extend relationships between use cases, and use cases with multiple flows, a use case model would contain so much repetition that it would be not only very difficult to establish and maintain, but also to read.

4.1 Alternative flows

Important alternative possibilities with respect to basic flows are captured in so-called alternative flows. These alter basic flows or even other flows at certain steps. Recall the Book an Activity or Service at a POI use case from Sect. 3.5 This is an alternative flow to its basic flow:

Alternative Flow: No Direct Booking Options Available

After step 1, if no direct booking options are available:

1. The portal displays the activity or service data (its name, contact information, link, etc.), if available.

2. The use case ends.

Alternative flows are simply introduced after the basic flow, and, for a given use case, we typically wrote them down only after we agreed upon its basic flow. They are named in order to make them readily understandable. It is usually not necessary to name basic flows, as their meaning is given by the name of the use case they reside in (but see Sect. 4.4).

4.2 Include

A use case can include another use case, which means that this use case is activated at a certain point, with the control returned to the including use case once the included use cases is completed. Consider the Remove a Featured Pilgrimage Plan, which includes the Find a Pilgrimage Plan in its step 2:

[WEB PORTAL] Remove a Featured Pilgrimage Plan

An administrator removes a featured pilgrimage plan.

Basic Flow

1. The administrator wants to remove a featured pilgrimage plan.

2. The Find a Pilgrimage Plan use case is activated with the search restricted to featured pilgrimage plans.

3. The administrator selects a pilgrimage plan.

4. The web portal prompts the corresponding route administrator whether the pilgrimage plan should be removed.

5. The web portal removes the pilgrimage plan completely.

6. The administrator can cancel the operation at any time.

7. The use case ends.

As shown in this example, the activation can be made with a particular setting invoked (“with the search restricted to featured pilgrimage plans”).

Not specifically related to the include relationship, observe step 6 of the use case, which enables to cancel the operation at any time. This step could have been included anywhere or even outside the flow. However, including it in the flow keeps it within the sight. Consequently, flows are only partially ordered sequences of steps.

An included use case itself can also include other use cases:

[WEB PORTAL] Find a Pilgrimage Plan

A user searches for a pilgrimage plan created by some pilgrim.

Basic Flow:

1. The user wants to remove a featured pilgrimage plan.

2. The Find a Pilgrimage Plan use case is activated with the search restricted to featured pilgrimage plan.

3. The user selects a pilgrimage plan.

4. The web portal prompts the route administrator whether the pilgrimage plan should be removed.

5. The web portal removes the pilgrimage plan completely.

6. The user can cancel the operation at any time.

7. The use case ends.

An include clause may be a conditional. Here is a more verbose with a multiple conditional include clauses and an include clause in an alternative flow:

[WEB PORTAL] Adopt a Pilgrimage Plan

A pilgrim adopts as their own a featured pilgrimage plan or a replicable pilgrimage plan created by another pilgrim.

Basic Flow

1. The pilgrim wants to adopt a pilgrimage plan.

2. The pilgrim selects an appropriate pilgrimage plan among the featured pilgrimage plans, in which case the Find a featured pilgrimage plan use case is activated, or replicable pilgrimage plans (created by other pilgrims), in which case the Find a pilgrimage plan use case is activated.

3. The pilgrim enters the pilgrimage plan parameters to adapt the selected pilgrimage plan: the origin (possibly extending or shortening the adopted plan at the beginning), start date, mode of mobility, etc.

4. The web portal gets from the planning service a pilgrimage plan adapted according to the parameters.

5. The pilgrim sets the plan accessibility (private/replicable/shared).

6. The pilgrim confirms the changes.

7. The web portal saves the pilgrimage plan as a new pilgrimage plan owned by the pilgrim.

8. The use case ends.

Alternative Flow: The Pilgrim is Not Logged In

After step 4, if the pilgrim is not logged in:

1. The Log In use case is activated.

2. In case of a successful log in, the use case continues with step 5 of the basic flow. Otherwise, the pilgrim is prompted to cancel the operation.

3. If the pilgrim confirms canceling the operation, the use case ends. Otherwise, the use case continues with step 1 of this flow.

4.3 Extend

Some use cases are intended only to extend or alter other use cases, just like alternative flows do to the basic flow within one use case. Consequently, such extension use cases contain no basic flows, but only alternative flows. These external alternative flows alter other use cases at certain labelled steps or ranges of steps known as extension points. Consider this use case:

[PORTAL] Extend a Pilgrimage Plan by POIs

A pilgrim extends a pilgrimage plan by POIs. If activated from the mobile application, the use case redirects to the web portal.

Basic Flow

1. The pilgrim wants to extend daily pilgrimage plans by adding POIs. 2. The web portal displays the pilgrimage plans that the pilgrim owns. 3. The pilgrim selects a daily pilgrimage plan within one of the pilgrimage plans. 4. The web portal displays the selected daily pilgrimage plan. 5. The pilgrim selects a POI and indicates whether another POI is to be added before or after this location. 6. The web portal displays the list of available POIs provided by the recommendation service. 7. The pilgrim can view the details of any of the POIs from the list. 8. The pilgrim selects one POI to be added to the daily pilgrimage plan. 9. The planning service recomputes the daily pilgrimage plan and subsequent ones if the POI exceeds one day. 10. The web portal displays the updated daily pilgrimage plan. 11. Steps 5–10 can be repeated. The pilgrim can remove any POIs that have been added within this use case. 12. The pilgrim can cancel the changes at any time, in which case the use case ends without saving the changes. 13. The pilgrim confirms the changes. 14. The web portal saves the changes. 15. The use case ends.

Extension Points

Displaying a Pilgrimage Plan: steps 4–6

Displaying the Details of a POI: step 7

This use case extends the Extend a Pilgrimage Plan by POIs use case and several other use cases:

[PORTAL] Rate a POI

A pilgrim rates a POI.

Alternative Flow: Rate a POI

After the Displaying the Details of a POI extension point in the Extend a Pilgrimage Plan by POIs use case, the Choosing a Hospitality POI extension point in the End Up a Daily Pilgrimage Plan with Accommodations use case, or the Displaying the Details of a POI extension point in the Make a Detour from a Daily Pilgrimage Plan use case:

1. The portal provides a possibility to rate the POI whose details are being displayed with up to five stars. 2. The pilgrim can rate the POI or reject to do so. 3. The use continues with the next step.

An extension use case may as well extend only one use case:

[WEB PORTAL] Recommend POIs

The recommendation service recommends POIs to extend a pilgrimage plan with.

Alternative Flow: Recommend POIs

Instead of the Displaying a Pilgrimage Plan extension point of the Extend Daily Pilgrimage Plans by POIs use case:

1. The web portal displays recommended POIs provided by the recommendation service for the whole pilgrimage plan.

This is useful if the presence of such behavior needs to be stressed or it is assumed it could extend other use cases as the model grows. Otherwise, the alternative flow occurring in it could be simply put into the extended use case.

Although the same extension point can be addressed by several use cases, most often, extension points are introduced for the purposes of making an extension by one specific use case. This is so in our model, too, i.e., one extension point is addressed by one use case only. This might make a false impression that extension points as such modify or participate in modifying the behavior of the extended use case. Of course, this is not so. Furthermore, raw step numbers can be used instead. However, labeled extension points are more convenient when it comes to renumbering steps in the use case being extended.

4.4 Use cases with multiple basic flows

To reduce the number of use cases, a use case can group several related basic flows each of which could have been considered a separate use case. Usually, this strategy is applied when these use cases resemble so-called CRUD (create–read–update–delete) operations. Here is an example:

[WEB PORTAL] Manage POIs

An administrator adds, updates, or removes a POI.

Basic Flow: Add a POI

1. The administrator wants to add a POI.

2. The web portal prompts for the POI data.

3. The administrator provides the POI data, including indicating whether it is active (available for selection in the pilgrimage plans).

4. The web portal saves the POI.

5. The use case ends.

Basic Flow: Update a POI

1. The administrator wants to update a POI.

2. The Find a POI use case is activated.

3. The web portal displays the POI data and prompts for changes.

4. The administrator provides the POI data, including indicating whether it is active (available for selection in the pilgrimage plans).

5. The web portal saves the POI.

6. The use case ends.

Basic Flow: Remove a POI

1. The administrator wants to remove a POI. 2. The Find a POI use case is activated. 3. The web portal displays the POI data and prompts for confirming removing it. 4. The administrator confirms removing the POI. Alternatively, the administrator can cancel the operation, in which case the use case ends. 5. The web portal disables providing the POI for inclusion in any subsequent pilgrimage plans and suppresses displaying its details. 6. The use case ends.

4.5 What was not used and why

Although preconditions show how use cases are sequentially dependent [6], we did not include them in our model relying these can be easily devised by the reader. For example, it is obvious that a user has to be logged in in order to take some actions whose consequences are associated with a particular user or that a pilgrimage plan has to exist before being modified, etc.

Postconditions are comprehensible from the use case flows, so we did not include them in our model either. Introducing them separately might be beneficial for a quick understanding what a use case brings. However, in all but trivial use cases, postconditions cannot be expressed that concisely as they have to express both minimal guarantees (if a use case fails) and success guarantees [5].

A use case included by other use cases should not contain the information on how it is activated (in the first step), nor should it declare that it has ended (in the last step). This kind of flow is known as a subflow in Jacobson’s notation [16]. Cockburn’s notation [5] does not recognize this concept. To be formally correct with use cases that are both included in some other use cases and that can be activated on their own, which is often the case with search and find use cases, the core behavior would have to be introduced in a subflow, while there should also be a basic flow there that would include the activation and end steps and the activation of the subflow in between the two. However, a use case model is not to be executed by a machine, but to be read by people, so we decided not to use subflows in our model.

While inheritance between use cases can improve their modularity and decrease the repetition of the actual steps, it obscures the meaning of the inheriting use cases. The readers are forced to read the use cases these use cases inherit from. It is possible for the base use cases to be completely abstract, i.e., to have nothing but names. They can be used to better structure use case diagrams by reducing the number of edges as actors participating in a number of use cases derived from a common base use case will be connected only to this use case. However, for the reasons explained in Sect. 2, use case diagrams were not of a great concern to us as we were focusing on use case text as such. Consequently, we decided not to use inheritance between use cases.

5 Supporting the use case model by other models

We supported our use case model by class diagrams, use case diagrams, and sequence diagrams in order to make it more comprehensible.

5.1 Class diagrams

As described in Sect. 3.5, we used class diagrams to model actors. In their essence, these are inheritance hierarchies. No other relationships are used. No attributes, nor operations were introduced in the classes that represent actors.

5.2 Use case diagrams

Use case diagrams are useful for showing how use cases are related by explicit relationships and how they are grouped according to the subject. We identified ten subjects in the rurAllure system, which include getting an initial pilgrimage plan, extending and adjusting pilgrimage plans, adding services and narratives, sharing pilgrimage plans, or following pilgrimage plans, and drew a use case diagram for each of them. Figure 5 shows an example.

Fig. 5
figure 5

The use case diagram of the extending and adjusting pilgrimage plans subject

Full size image

As we explained in Sect. 2, use case diagrams should be used as an overview of already written use cases, and not as the starting point for use case modeling. It is easy to draw meaningless use case diagrams no one will argue against, but this is not so with the actual text of use cases.

5.3 Sequence diagrams

We introduced sequence diagrams only for the most complicated use cases, such as Adopt a Pilgrimage Plan, whose sequence diagram is depicted in Fig. 6. We did not go beyond the use case description, i.e., the sequence diagrams we created are purely analytical. Lifelines refer to the human and system actors as they are conceived in the use case description. Messages are based on the steps. Combined fragments are used to express decisions or loops.

Fig. 6
figure 6

The sequence diagram of the Adopt a Pilgrimage Plan use case

Full size image

6 Aftermath

The use case model of the rurAllure system comprises forty use cases. The hierarchies of user and system actors are captured in three class diagrams. The use cases are visually supported by ten use case diagrams accompanied by five sequence diagrams expressing the most complicated use cases. In addition to this, the domain concepts the use cases rely on are captured in the domain model and defined in the domain dictionary. Three quarters of use cases have been implemented at least to some extent. Often, even significant changes were introduced. Consequently, the role of our use case model was not to strictly prescribe how things will be implemented and then to stick to this model as a contract, which is the role use case models often play in waterfall-like software development, but to create a tangible idea of the system which can be worked with further.

6.1 Impressions

The use cases started to be useful for us from the moment we started writing them. They provoked so intense communication over the collaboratively edited document on the Synology Drive, in addition to which we exchanged dozens of e-mails, held many remote meetings in different settings, and talked face-to-face at joint meetings we had an opportunity to have so far. Through this, the use case model helped consolidate the system architecture. It demonstrated how the rurAllure system will be accessed by users and how the services will be used.

Our impression is that the developers considered the use case model as something assumed. However, two developers shared their thoughts with us on how useful the use case model was for them:

For developers, the most important thing is to have the objectives of each functionality perfectly defined, especially in a project as large as rurAllure, with so many teams working with totally different points of view. A clear description gives us a calm atmosphere to structure and design each new functionality. The use cases have allowed us from settling tireless discussions between different teams to prioritizing several upcoming implementations. In the end, the development of a platform translates into implementing functionalities that complete the use cases. The more use cases a functionality touches, the higher priority its release should have.

However, the most important moment has been during the design phase of each of our microservices. The initial design is the most critical point, as it is done when the project is still too young, but at the same time, it is the basis on which the final functionality will be created. Without clear and concise use cases, this could have neve been done.

The perception of the use case model by nontechnical project participants is probably best captured in the thoughts one of them shared with us:

When I read the section devoted to use cases, it was, in my view, really well explained and it does help to understand what the system is supposed to do, both the text (with each step of the basic flow) and the accompanying graphics. At first, I sometimes found a bit difficult to understand how some use cases were linked to others and even I sometimes wondered about the order in which they were presented, especially when a use case in directly related to another one in the basic flow (as, I guess, it was easy to see in my review comments), but overall I found this section very useful.

I do not have a particular example to highlight. In fact, I would say that reading all of them (not only some) is what better helped me to have a much more clear idea of what the system was expected to do at the point when the D3.1 [deliverable containing the use case model] was created, that is, in an early phase of the project, when deeply explaining and understanding how everything is supposed to do in more advanced stages of the development is more important.

6.2 Recommendations

Recapping the process we applied, we may give the following recommendations for applying use case modeling in similar settings:

  • Write the most important use cases first

  • Start writing use cases even if you are not sure about them; disagreements should be exposed at this stage

  • Start with basic flows

  • Select a reasonably expressive yet comprehensible notation

  • Not everyone needs to participate in writing use cases (this might be only one or two persons), but everyone should be able to see them being created

  • GUI form wireframes may be useful for GUI design, but are not a supplement for use cases; GUI should reflect use cases, of course, but to design GUI without having a clear idea of use cases and then force developers to decipher use cases from wireframe forms might lead to big misunderstandings

  • Keep use cases free from user interface notions; with this, the same use case remains valid for different realizations in a mobile application or web application, etc.

We did not update the use case model. It served its purpose and updating it wouldn’t be lean [10].

Use cases aim at capturing the most important interactions of a human actor with the system. In this, they uncover some of the system structure and how its parts interact with each other. However, unless they are associated with code or directly represented within it [2, 3, 10], this is always limited. Thus, our use cases deal with the services the rurAllure system offers, but they do not cover the details of these services. For example, they do not cover the accessibility aspects, which are the responsibility of the planning service, such as feasible daily distances, mobility impairments, feasibility of the detours, the condition of the paths, etc.

While GUI form wireframes, such as the one depicted in Fig. 7, were designed before we started writing use cases, associating them with use cases helped validate their purpose and better understand them. The GUI form wireframe in the figure is related to these use cases: Generate a Pilgrimage Plan, Adopt a Pilgrimage Plan, Register as a Pilgrim, Log In, and Update my Account.

Fig. 7
figure 7

Specific route portal home interface wireframe

Full size image

6.3 Beyond original use cases

The meaningfulness of the proposed tourist experiences is largely embedded in the notions of featured trips and narratives. The use cases do not provide insight into how they should be designed; rather, we are gaining experience in the pilot elaborations of selected routes about what makes an interesting trip for different audiences, how narratives can weave together multiple bits of information cohesively, etc.

In the current state of development, we are going beyond the originally assumed ways to use the rurAllure system. For example, accessibility experiments were conducted with blind people, with a featured trip and a narrative that contained 3D-printed materials that helped the travelers discover the geology of the place (namely, the thermal area of Bagno Vignoni, in the Tuscany region of Italy, found along the Via Francigena). This is not a failure of the use cases. On the contrary, the use case model helped us get quickly to a consistent implementation of the system that can be experimented with further in different ways.

6.4 Threats to validity

From the point of view of construct validity, we can say that the setting in which we applied our approach was a real setting, and not an artificially constructed one.

Not having implemented all use cases and changes in their implementation might indicate that the approach is not fully valid, which represents a threat to internal validity. However, the vast majority of use cases has been implemented. Furthermore, understanding of use cases evolves over time and the authors were actually involved in this for the rurAllure project. The decision not to implement some uses cases was based on project priorities and resources, and not on irrelevance or low quality of use case descriptions.

The approach and recommendations reported here have been applied only within one project setting. However, the project setting was fairly complex and it is reasonable to expect that the approach and recommendations are valid for similar settings.

We did not actually try to run the project without employing our approach, so we cannot know whether it really helps. This represents a threat to conclusion validity. However, this is not completely true. The project proposal writing and initial discussions within the consortium left an impression of a consensus over what has to be implemented. But—as we started with use case modeling—disagreements started to arise, and use cases helped sort them out (see Sect. 3.4).

7 Related work

In his short retrospective on use cases published in 2004 [15], Jacobson says:

I am still reluctant to suggest that system analysts describe use cases in a more formal way than simple text. Avoid trying to specify the internals of each use case with diagrams such as activity diagrams or state charts, although it is good to describe the interactions between a use case and actors with sequence diagrams or activity diagrams with swimlanes.

What we did is pretty much in line with Jacobson’s viewpoint. It is worthwhile to note that we didn’t know about this retrospective at the time of creating our use case model.

Bispo et al. [1] identified 13 different strategies for use case modeling published in 39 papers between 2008 and 2018. These include using ontologies, antipattern identification, role playing, natural language processing, scenario patterns, using business process notations, domain specific languages, use case fragments, means of distributed communication, visual mental models, visual languages, reverse engineering, and automatic use case diagram layout. The category we can identify with to some extent is the one based on the use of the means of distributed communication. However, our strategy for use case modeling is probably best denoted as lean: only as much of use case modeling as it is needed to explore and understand what needs to be done.

Tiwari and Gupta [24] identified twenty different use case templates in the papers published between 1992 and 2014. The way we wrote our use cases is closest to what Jacobson and Cockburn proposed. According to Tiwari and Gupta [24], Jacobson’s notation is the most cited one, while Cockburn’s is the third most cited. The second one is Kruchten’s, which is similar to these two, apart from introducing keywords [24].

The implementation of the uses cases discussed in this paper ran practically in use case slices, just as recommended by Jacobson et al. [17], although not in a formal manner. Nevertheless, we can confirm that we treated the most important functionality in most important use cases first and that we worked in parallel on multiple use cases.

Apart from Jacobson et al. [17], several other authors reported achieving good results with applying use case modeling in agile software development [12, 19, 20, 22], also in synergy with user stories [23], but they are not as specific as we are as to what to apply and how to apply it from all the possibilities that use case modeling offers. Furthermore, we found no papers dealing with applying use case modeling in research settings.

8 Conclusions and further work

With so much confusion around use case modeling, software developers may be reluctant to apply it. However, use cases are easy to apply and have great benefits even in research settings with nonprofessional software developers involved. We report on our experience on this within an innovative tourist information system developed in a research setting of an ongoing Horizon 2020 project named Promotion of Rural Museums and Heritage Sites in the Vicinity of European Pilgrimage Routes (rurAllure). The resulting use case model comprises forty use cases supported by class diagrams, use case diagrams, sequence diagrams, as well as by the domain model and dictionary. Three quarters of use cases have been implemented at least to some extent. Based on this, we provide a set of recommendations for applying use case modeling in similar settings.

The paper also exposes the domain model and dictionary along with selected use cases and the hierarchy of user and system actors, which may be useful as such or as a stimulus for the development of other innovative tourist information systems.

Writing use cases provoked intense communication, which helped consolidate the system architecture. The use cases helped validate and better understand the GUI form wireframes designed beforehand and get quickly to a consistent implementation of the system that can be experimented with further in different ways. Finally, the forthcoming extensive system and user experience testing will be guided by the use case model.