II.4 Use Cases

BPMN instead of UML

In systems analysis, activity diagrams are often used to define use case processes. However, the authors of this book consider BPMN (Business Process Model and Notation) to have a few advantages for technical processes. The use of pictograms doesn’t just make things more intuitively understandable; it is also easier to model exceptions with BPMN than with UML. (Freund & Rücker, 2014) provide an introduction to BPMN 2.0, which is the version we are using.

II.4.1 Registration Required

The user with the role of organizer must be registered in order to be able to carry out a use case. If they are not registered, the user will be asked for their email address and password. The user will only be authenticated as an organizer if an object exists in the domain class organizer whose email and password attributes match those entered. The user session will then pass the corresponding object to the organizer class for further use within the use case.

No registration is necessary to carry out the donor use cases Donate money (section II.4.9) and Display filtered donor list (section II.4.10).

The idea behind the use case Donate money is that the donation process should be kept as simple as possible – prior registration might discourage potential donors. This has implications for the production mode of the application, however, because it means that this use case has to be protected from misuse. One way of doing this would be to limit the number of donations per user session in order to protect ourselves from an attack by bots. However, to avoid overshooting the scope of the workshop, we will refrain from exploring this option in detail in this example.

Likewise, it is not desirable for us to secure the use case Display filtered donor list using compulsory registration. This is a supporting use case that is intended to motivate the donor to donate – a requirement for prior registration would be counterproductive. It is also not possible here for misuse to occur through false donations, which means that no further protection is necessary in production mode.

II.4.2 Displaying and Editing Campaigns

Fig. II-3 shows the process for the use case Display and edit campaigns. In the first step of the process, all campaigns belonging to the organizer are loaded. Using the loaded campaign objects, the My Campaigns screen (Fig. II-4) will be assembled. After that, the system will wait for a user action. For each campaign, the user can click one of the buttons “X”, “Edit”, “List donations” or “Form”. In doing this, the user will effectively select a campaign object and, depending on the button clicked, one of the following use cases will be fulfilled: Delete campaign, Edit campaign, Display donor list or Edit donation form; their respective processes are described in the following sections. The “Add campaign” button belongs to another use case (see section II.4.7), but is displayed in the same screen nevertheless.

Diagram for the use case 'Display and edit campaigns'
Fig II-3     Diagram for the use case “Display and edit campaigns”

'My Campaigns' screen
Fig II-4     “My Campaigns” screen

II.4.3 Editing Donation Forms

Fig. II-5 illustrates the process for the use case Edit donation form. In the first step, the chosen campaign object is loaded; a URL will then be generated, via which the donation form for the campaign can be accessed. If a user accesses this URL, the use case Donate money will be carried out (see section II.4.9). White (Hexcode 0xFFFFFF) will be used as the default background color for the form and black (Hexcode 0x000000) as the default text color. The color values will be encoded alongside the chosen campaign as parameters in the generated URL.

The Edit donation form screen is assembled using the generated values. The organizer can modify the appearance of the donation form in this screen before embedding it into their website, including adjustment of the text color and background color to suit their wishes. To facilitate this, the screen contains colorpicker controls, which can only return valid color values.

As soon as the user has customized the color selection, the URL of the donation form will be re-generated with the new values and shown on the screen. Next, the organizer can make further color adjustments or click the “OK” button. The latter option terminates the use case.

Diagram for the use case 'Edit donation form'
Fig. II-5      Diagram for the use case “Edit donation form”

'Edit donation form' screen
Fig. II-6     “Edit donation form” screen

II.4.4 Displaying Donor List

Fig. II-7 shows the process for the use case Display donor list. In the first step, the campaign object selected by the user is loaded. Next, all donation objects are loaded, representing the entire list of donation transactions for the campaign. Finally, this data is displayed in the Display donor list screen (see Fig. II-8) and the system waits for the user to confirm it by clicking the “OK” button.

Diagram for the use case 'Display donor list'
Fig. II-7     Diagram for the use case “Display donor list”

'Display donor list' screen
Fig. II-8     “Display donor list” screen

II.4.5 Editing a Campaign

Fig. II-9 shows the process for the use case Edit campaign. First, the campaign object chosen by the organizer is loaded. Then, the dependent use case Edit campaign data (see section II.4.8) is loaded. This can be cancelled at any point, which will cause the higher-level use case Edit campaign to be ended. However, if the use case Edit campaign data is terminated normally, the campaign data in the campaign object chosen by the organizer will be saved. This will likewise result in the use case ending.

Diagram of the use case 'Edit a campaign'
Fig. II-9     Diagram of the use case “Edit a campaign”

II.4.6 Deleting a Campaign

Fig. II-10 shows the process for the use case Delete campaign. Firstly, the system will display a message dialog which asks the user whether they really wish to delete the campaign. Depending on their decision, the chosen campaign object will be deleted from the database, or the use case will be ended without further activity.

Diagram for the use case 'Delete campaign'
Fig. II-10     Diagram for the use case “Delete campaign”

II.4.7 Create a New Campaign

Fig. II-11 shows the process for the use case Create new campaign. This can be started by clicking on the button “Add a campaign”. The use case “Edit Campaign Data” (see section II.4.8) will be launched directly afterwards. If this is terminated normally, a new campaign object will be created using the campaign data. If the use case Edit campaign data is cancelled, however, the higher-level use case Create new campaign will be ended without a new campaign having been created.

Diagram of the use case 'Create new campaign'
Fig. II-11     Diagram of the use case “Create new campaign”

II.4.8 Editing Campaign Data

Fig. II-12 shows the process for the dependent use case Edit campaign data. This diagram has been divided into two swimlanes for better understandability. One contains the activities of the system and the other contains the activities of the user occupying the role of organizer.

First, the system generates the Edit campaign data screen. This screen organizes the various fields into two groups, which the user can edit in the order of their choosing in the tabs General (see Fig. II-13) and Bank details (see Fig. II-14). The user can change the active tab at any time with a click of the mouse.

The name of the higher-level use case will appear during runtime in place of the title “Edit campaign data”. If, for example, the higher-level use case is Create new campaign, then its name will appear: “Creating new campaign”.

If the higher-level use case already provides a campaign object, its data will be displayed on the screen.

The user can edit all attributes of the campaign object within this screen. Next, the user can either cancel the use case by clicking on the “Cancel” button or allow the use case to keep running by clicking on the “Save” button.

In the latter case, the data entered by the user will first of all be checked. If it is complete, the campaign data will be delivered to the higher-level use case. If data is missing, or if the user has entered invalid data according to the conditions of the domain class campaign (see Tab. 3-2), these will be flagged in the screen and the corresponding user message from the table of conditions will appear for each error. Following this, the user can continue editing, at which point the process will be repeated.

Diagram for the use case 'Edit campaign data'
Fig II-12     Diagram for the use case “Edit campaign data”

'Edit campaign data' screen – 'General' tab active
Fig II-13     “Edit campaign data” screen – “General” tab active

'Edit campaign data' screen – 'Bank details' tab active
Fig II-14     “Edit campaign data” screen – “Bank details” tab active

II.4.9 Donating Money

Fig. II-15 shows the process for the use case Donate money for the user role donor.

This use case is accessed via a URL generated by the use case Edit donation form (see section II.4.3). The campaign to be donated to is encoded in this URL. Therefore, as a first step, the corresponding campaign object is loaded. Next, the Donate money screen (Fig. II-16) is generated using this object and the color parameter that is also encoded in the URL.

The donor fills out the form, while the system waits for the “Donate” button to be clicked. When it is clicked, the system checks the data entered by the donor. The fields must meet the conditions stipulated for the donation class (see Tab. II-3). If this is the case, a donation object with the status IN_PROGRESS will be created using this data. The use case is then ended.

If some or all fields in the donation form are not validated, however, the non-validated fields are flagged using the conditions of the domain class and the corresponding user message is shown. The donor can then fill out the form again.

The transaction must be handed to a financial services provider, who will carry out the actual transfer. Since we are dealing here with a sample application, not a real one, we will content ourselves merely with simulating the transaction. Every five minutes, a timer will start a background job, whose purpose will be to select all transactions with the status IN_PROGRESS and change their status to TRANSFERRED.

Diagram for the use case 'Donate money'
Fig II-15     Diagram for the use case “Donate money”

'Donate money' screen
Fig II-16     “Donate money” screen

Discussion

Use the message board below to give the authors your feedback or to discuss this page’s topic with other readers (in English please!). Please don’t expect the authors to answer directly, but they might update the content of this site according to your feedback.