COMBINE - Requirements model example

Product Vision and Description
Use Cases
Subsystem grouping
The Booking-Editor Use Case descriptions
The Booking-Viewer Use Case descriptions
- Use case 7b: View global schedule
  - Primary scenario
The Subscription-Editor Use Case descriptions
- Use case 12: Subscribe to notification
  - Primary scenario
The Global-Schedule-Service Use Case descriptions
The Subscription-Service Use Case descriptions

Product Vision and Description

Vision

The survey-booking tool is a web-based and highly automated tool to support the process around booking of vessel time for potential surveys.

Its main task will be:

Schedule leads and surveys
Send automatic warnings on changes and conflicts
Inform about current resource usage and potential backlog

Description

The survey-booking tool will help to administer the utilization of our vessels. It will mainly benefit three user groups; Sales, operations and marine management.

Sales will use it to book a survey or tender onto a vessel. The survey-booking tool will give an overview over the current workload and also which vessel qualifies for the job.
Sales will make booking suggestions to management, which then need to be confirmed by the global marine management.
For operations the booking tool should work as a planning aid. It will automatically warn about changes and it will have detailed job information available on-line.
Marine management will be able to use the booking tool to assess the current resource usage, confirm survey bookings and to reschedule jobs.

The survey-booking tool will be web based and automatically updated with the current progress rates from Introspection. A consequence of this approach is that there needs to be one global master schedule. In order to visualize alternative scenarios each user can create private schedules.

The main display part will look like today's vessel scheduler (see Figure 1). This display is proven and appreciated by many users.

Figure 1: Excel based vessel schedule as today

Background and Motivation

Beginning 2000 it was decided to give all business application tools a real development home at OTC. Now we are about to create a set of business application tools. The new survey-costing tool will be the main component, but this tool needs a couple of helper applications like for example the survey-booking tool.

This document specifies the requirements and high-level use cases for the survey-booking tool.

The survey-booking tool is a complete redesign of the vessel schedule.

We tried to design it as a 'light' tool, without too much intelligence. The intelligence to the system will be more a part of the survey-costing tool.

The advantage of this design is that we can deliver the survey-booking tool fairly fast.

We have the luxury of owning a good old version, the current excel based vessel schedule. This version will stand for a lot of the requirements.

It was introduced about 5 years ago by R. Walker and has been improved a couple of times. However, it is now no longer sufficient for the global Web environment.

Use Cases

What is a Use Case

With the presentations of use cases in this document we want to follow a quite widely followed model on how to engineer a project. Use cases are part of a structured approach to capture all interactions a system should do and at the same time define all interacting user groups and systems.

The use cases describe how actors interact with the system. Actors can be users or other systems, which normally extract or import information.

In this document a high level view of the use cases is presented. The main aim at this point is to assure that all use cases have been found and all actors were identified.

System Boundary model

Figure 2: Survey Booking main use cases

In bold the use cases which are of highest priority, which are the target for the first version.

Definition of actors (User groups)

Sales

The sales department is responsible for costing a survey and to initially book it on a vessel or region in case of a lead. Sales account managers, sales supervisors and sales managers are members of this group.

Operations

Operations will be responsible for the survey preparation and execution.

Operations managers, vessel supervisors and party chiefs are the main members of this group.

In addition there are several service groups which will also be included in this group:

Operational support (Technical services), personnel management, accounting.

Marine management

Marine management will be responsible to confirm the booking of surveys onto a vessel.

Regional marine management, business managers and global marine management are part of this group.

Introspection

Introspection has two tasks. For the booking and booking validation process it shall inform about vessel configurations, which it can get from the vessel descriptions.

In addition the actual progress is extracted from Introspection to keep the schedule up to date.

Administrator

A person with administrator rights is needed to keep the system updated with regards to user names and rights and vessel names.

Support

A support role is needed to promote the input of competitor information. This role needs to access the system to obtain status on what is being added and by whom.

Summary list of use cases

Name	Description	Actors
1. Book tender/lead	Book a tender onto a vessel Book a lead onto an area.	Sales Management
2. Update booking status	Move unsuccessful tenders to competitor schedule, keep lead/tender status up-to-date and confirm successful tenders.	Sales
3. Ask for confirmation	Check if confirmation is necessary, ask for confirmation if necessary, notify otherwise.	"All"
4. Confirm Job	Confirm the booking which sales proposed	Management
5. Reschedule job	Move jobs in time or to another vessel.	Sales Management
6. Update work-order (SWO)	Associated with each survey is a SWO, which needs to be filled in. The SWO keeps the survey specific information	Sales Operations
7. View schedule	Get an overview over the current status and be able to extract some survey and vessel specific information. Check with access policy to determine what can be shown.	"All"
8. Automated schedule updates	Update status on current survey. Is it progressing as indicated in the booking tool?	Introspection
9. Notify	Notify users who requested notification	"All"
10. Add/remove users and rights	Administer the user's access rights and notification whishes	Administrator
11. Add/remove Vessels	Administer the active vessels	Administrator
12. Subscribe to notification	Specify the criteria's to be used for sending a notification.	"All"
13. View market‑share and forecast reports	Extract information about own and competitor vessels to calculate market-share. Calculate capacity forecast based on information on leads and bids submitted.	Management and Sales (provided access rights)
14. View competitor input report(s).	Extract information on what is being added/modified to the competitor schedule and by whom.	Support

Global quality requirements

The system must run on Netscape and preferably also on MS Internet Explorer.

Subsystem grouping

The figure below shows how the use-cases are grouped into subsystems. This grouping is based on an analysis of the usage of the system by the different actors and also by applying the COMBINE reference architecture model. These subsystems are going to be implemented as different components.

Figure 3: Survey Booking subsystem grouping use cases

The Booking-Editor

The Booking-Editor is a tool-Component and is used by the sales community. This component contains most of the use-cases for sales and supports the need to run offline. It also restricts the ability to manipulate the information to sales only as defined in a very strict access-right list.

In order to run in an offline modus we have introduced two new use-cases (15. Import global schedule, 16. Export global schedule). These use-cases will talk to a server-side business-service component called “The GlobalScheduleService”.

The Booking-Viewer

The Booking-Viewer is a tool-component used by all actors. The access-rights will be controlled by access-lists (LDAP). This component is a web-based client and gives viewer functionality only.

The Subscription-Editor

The Subscription-Editor is a tool-component used by all actors. The access-rights will be controlled by access-lists (LDAP). This component is a web-based client that gives the possibility to monitor (via email) different business-events (state-changes) in the booking schedule. The Subscription-Editor stores the information in a server-side business-service-component called “The SubscriptionService”.

The Global-Schedule-Service

The Global-schedule-service is a business-service-component that serves the Booking-Editor- and the Booking-Viewer tool-components. It contains two use-cases: 17) Synchronize and save schedule, 18) Assemble and deliver schedule. These two use-cases talks to a resource component called Activity-Info which already exists (reused) and is shown as an actor in the figure.

The Subscription-Service

The Subscription-service is a business-service component that implements the server-side functionality of the Subscription-editor. It contains two use-cases: 19) Save/Remove subscription, 20) Check for subscriptions and notify.

The Booking-Editor Use Case descriptions

Figure 4: Booking Editor use cases

Use Case 1: Book tender/lead

Primary scenario

Use case 1	Book tender/lead
Priority	1
Goal	Book tender onto a vessel or lead onto an area
Actors	Sales (initiating), Introspection (involved)
Pre-conditions	None.
Post-conditions	Global booking OK and information about who made the booking logged in database.
Façade	-
Quality requirements	-
Scenario	Book from scratch using full featured tool.
Description	Step	Action
	1	Login & authorize on online version. Use LDAP to authorize.
	2	Create new private schedule. A local setup is used to identify which regions, vessels, competitors should be included in the private schedule.
	3	Synchronize with global schedule. (use-case 15)
	4	Fill in job-form
	4.1	Client, area, time, time constraints and configuration.
	4.2	Booking status (rumor, lead, tender received, bid submitted, bid won/lost, survey running/halted, survey completed, booking cancelled) In case of lead/bid submitted, a qualifier indicating likelihood of becoming a tender/winning bid (in %) is required (0, 25, 50, 75, 100).
	4.3	Booking type (Seismic acquisition, travel, port call, yard, lay-up, test)
	5	Select vessel from list (not required for booking status rumor, lead, tender received and bid submitted). System can show a ranked list of vessels if working online (provided from Introspection based on vessel description). Ranking criteria are: Configuration, availability, area and cost
	6	Create booking in private schedule
	7	Save private schedule.
	8	Export booking to global schedule (use-case 16)
	8.1	Confirm export of changes in local schedule
	8.2	Bid base number will be given from the system and inserted into the global and private schedule
	9	Notify interested parties (Use case 9)

Alternative scenario A

Use case 1	Book tender/lead
Priority	1
Goal	Book tender onto a vessel or lead onto an area
Actors	Sales (initiating), Introspection (involved)
Pre-conditions	Successful online login must have been performed to generate local authorization data.
Post-conditions	Local booking created. Export to global schedule not yet performed.
Façade	-
Quality requirements	-
Scenario	Book in existing private schedule using full featured tool.
Description	Step	Action
	1	Login & authorize on offline version. Use local authorization.
	2	Open private schedule.
	3	Step 3-7 of primary scenario.

Use case 2: Update booking status

Primary scenario

Use case 2	Update booking status
Priority	1
Goal	Move unsuccessful tenders to competitor schedule, keep lead/tender status up-to-date and confirm successful tenders.
Actors	Sales
Pre-conditions	Booking exists in private schedule
Post-conditions	Global booking changes OK and information about who changed the booking status logged in database.
Façade	-
Quality requirements	-
Scenario	Update existing booking using full-featured tool.
Description	Step	Action
	1	Login & authorize on online version. Use LDAP to authorize.
	2	Open existing private schedule.
	3	If needed, synchronize with global schedule.
	4	Select actual booking
	5	Update information if necessary
	5.1	Reschedule (use-case 5)
	5.2	Update work-order (use-case 6)
	6	Change booking status (rumor, lead, tender received, bid submitted, bid won/lost, survey running, survey halted, survey completed, cancelled)
	6.1	In case of lead/bid submitted, a qualifier indicating likelihood of becoming a tender/winning bid (in 5) is required (0, 25, 50, 75, 100).
	6.2	If job was cancelled or lost, specify reason
	7	Change time, time constraints. (Use case 5)
	8	Save private schedule.
	9	Export booking changes to global schedule ( use-case 16)
	9.1	Confirm export of changes in local schedule
	9.2	Confirm overwrite if someone has updated global schedule since last synchronization.
	10	Ask for confirmation (Use case 3)
	11	Notify interested parties (Use case 9)

Alternative scenario A

Use case 2	Update booking status
Priority	1
Goal	Move unsuccessful tenders to competitor schedule, keep lead/tender status up-to-date and confirm successful tenders.
Actors	Sales
Pre-conditions	Successful online login must have been performed to generate local authorization data.
Post-conditions	Local booking created. Export to global schedule not yet performed.
Façade	-
Quality requirements	-
Scenario	Update existing booking using full-featured tool in offline modus.
Description	Step	Action
	1	Login & authorize on offline version. Use local authorization.
	2	Step 2-8 of primary scenario.

Use case 5: Reschedule jobs

Primary scenario

Use case 5	Reschedule jobs
Priority	1
Goal	Reschedule jobs and tenders, which are already listed in the booking tool
Actors	Sales
Pre-conditions	Booking exists in private schedule
Post-conditions	Global booking changes OK and information about who changed the booking status logged in database.
Façade	-
Quality requirements	-
Scenario	Reschedule existing booking using full-featured tool.
Description	Step	Action
	1	Login & authorize on online version. Use LDAP to authorize.
	2	Open existing private schedule.
	3	If needed, synchronize with global schedule.
	4	Select actual booking
	5	Update booking
	5.1	'Drag and Drop' booking to new vessel and new time or open editor and select new vessel and/or time.
	5.2	Delete job, Specify reason.
	6	Save private schedule.
	7	Export booking changes to global schedule
	7.1	Confirm export of changes in local schedule
	7.2	Confirm overwrite if someone has updated global schedule since last synchronization.
	8	Ask for confirmation (Use case 3)
	9	Notify interested parties (Use case 9)

Alternative scenario A

Use case 5	Reschedule jobs
Priority	1
Goal	Reschedule jobs and tenders, which are already listed in the booking tool
Actors	Sales
Pre-conditions	Successful online login must have been performed to generate local authorization data.
Post-conditions	Local booking created. Export to global schedule not yet performed.
Façade	-
Quality requirements	-
Scenario	Reschedule existing booking using full-featured tool in offline modus.
Description	Step	Action
	1	Login & authorize on offline version. Use local authorization.
	2	Step 2-6 of primary scenario.

Use case 7a: View local schedule

Primary scenario

Use case 7a	View local schedule
Priority	1, 2 (step 4)
Goal	View, print the schedule
Actors	Sales
Pre-conditions	None.
Post-conditions	-
Façade	-
Quality requirements	-
Scenario	View local schedule
Description	Step	Action
	1	Login & authorize on online version. Use LDAP to authorize.
	2	Create a new private schedule. A local setup is used to identify which regions, vessels, competitors should be included in the private schedule.
	3	Synchronize with global schedule.
	4	Print schedule
	4.1	Standard view of current schedule
	4.2	Standard print of history schedules (per year)
	4.3	Free Selection of start and end time and vessels.

Use case 15: Import from global schedule

Primary scenario

Use case 15	Import from global schedule
Priority	1
Goal	Create a local schedule by importing from global schedule.
Actors	Sales
Pre-conditions	None.
Post-conditions	Local schedule created with selected global data.
Façade	-
Quality requirements	-
Scenario	Create a fresh local schedule by importing from global schedule
Description	Step	Action
	1	Login & authorize on online version. Use LDAP to authorize.
	2	Create an empty local schedule.
	3	Select data to import.

Use case 16: Export to global schedule

Primary scenario

Use case 16	Export to global schedule
Priority	1
Goal	Export local bookings to global schedule.
Actors	Sales
Pre-conditions	None.
Post-conditions	Exported booking stored in global schedule.
Façade	-
Quality requirements	-
Scenario	Export local bookings to global schedule.
Description	Step	Action
	1	Login & authorize on online version. Use LDAP to authorize.
	2	Open local schedule to export.
	3	Select bookings to export.
	4	If conflicts, choose:
	4.a1	Override and export.
	4.b1	Reschedule jobs.
	5	Notify interested parties (Use case 9)

The Booking-Viewer Use Case descriptions

Figure 5: Booking Viewer use cases

Use case 7b: View global schedule

Primary scenario

Use case 7b	View global schedule
Priority	1
Goal	View, print the schedule
Actors	Marine management, Operations, Sales
Pre-conditions	None.
Post-conditions	-
Façade	-
Quality requirements	-
Scenario	View global schedule using lightweight tool.
Description	Step	Action
	1	Login & authorize on online version. Use LDAP to authorize.
	2	Specify which regions, vessels, competitors should be included.
	3	Print schedule
	3.1	Standard view of current schedule
	3.2	Standard print of history schedules (per year)
	3.3	Free Selection of start and end time and vessels.

The Subscription-Editor Use Case descriptions

Figure 6: Subscription Editor use cases

Use case 12: Subscribe to notification

Primary scenario

Use case 12	Subscribe to notification
Priority	1
Goal	User shall be able to view and modify list of subscriptions, and submit a updated list of selected subscriptions to the system. This list shall be stored in the systems subscription database. The updated list of subscriptions shall take effect immediately after the submission has been confirmed to the user.
Actors	User (Sales people, Marine Management)
Pre-conditions	The subscription system must be up running and the user must have access to this service. The administrator must have created the list with available subscriptions.
Post-conditions	The updated list of subscriptions must be stored in the DB and the user must receive an acknowledgement in the client tool.
Façade	-
Quality requirements	Only authorized persons must be allowed to use this service Client tool must be cross-platform compliant.
Scenario	-
Description	Step	Action
	1	Login & authenticate
	2	Retrieve all available subscriptions
	3	Retrieve user's subscriptions and displays them.
	4	View subscriptions
	4.a1	Remove subscriptions
	4.a2	Submit updated subscription list
	4.b1	Add subscriptions, selected from available subscriptions
	4.b2	Submit updated subscription list

The Global-Schedule-Service Use Case descriptions

Figure 7: Global Schedule Service use cases

Use case 10: Add/remove users & rights

Primary scenario

Use case 10	Add/remove users & rights
Priority	1
Goal	To administer users and user privileges
Actors	Administrator
Pre-conditions	None.
Post-conditions	-
Façade	-
Quality requirements	-
Scenario	-
Description	Step	Action
	1	Login & authorize (LDAP)
	2	Create/remove users and assign roles
	3	Assign/remove rights to user.

Use case 11: Add/remove vessels

Primary scenario

Use case 11	Add/remove vessels
Priority	1
Goal	To administer available vessels (incl. competitor vessels)
Actors	Administrator
Pre-conditions	None.
Post-conditions	-
Façade	-
Quality requirements	-
Scenario	-
Description	Step	Action
	1	Login & authorize (LDAP)
	2	Create/remove Seismic companies
	3	Create/remove Vessels or move vessel between different seismic companies.

Use case 17: Synchronize and save schedule

Primary scenario

Use case 17	Synchronize and save schedule
Priority	1
Goal	Check Store schedule in global database
Actors	Booking Editor
Pre-conditions
Post-conditions	Schedule will be stored in database
Façade	-
Quality requirements	-
Scenario	-
Description	Step	Action
	1	Save schedule in database if no modification conflicts
	2	If modification conflicts, ask BookingEditor for forced saving or cancel
	2.1	If forced save, email owner of original data

Use case 18: Assemble and deliver schedule

Primary scenario

Use case 18	Assemble and deliver schedule
Priority	1
Goal	Deliver the schedule
Actors	BookingEditor & BookingViewer
Pre-conditions
Post-conditions
Façade	-
Quality requirements	-
Scenario	-
Description	Step	Action
	1	Assemble the schedule based on regions,vessels and time-interval specified
	2	Deliver to BookingEditor & Viewer

The Subscription-Service Use Case descriptions

Figure 8: Subscription Service use cases

Use case 19: Check for subscriptions & notify

Primary scenario

Use case 19	Check for subscriptions & notify
Priority	1
Goal	When certain topics are changed different user groups need to be notified based on what they have "subscribed to". Notifications should be ranked according to severity. Changes in the Survey booking database shall be reported to the notification service. This service shall send a mail notification to all users who has subscriptions, which matches the reported database change. After the submission has been confirmed to the user.
Actors	Notifier (GlobalScheduleService), SubscriptionInfo, EmailServer
Pre-conditions	Email changes in the booking schedule to interested parties according to notification policies set up by the individual or group. The subscription system must be up running and mail service must be available.
Post-conditions	-
Façade	-
Quality requirements	If the update is done when the system is up running the changes must take effect at the next incoming request after the file is saved.
Scenario	-
Description	Step	Action
	1	GlobalScheduleService reports database change.
	2	Retrieve all subscriptions from subscription database.
	3	Search through all subscriptions too see if they match the reported data change.
	4	Subscription does not match, continue search
	4.1	Subscription matches data change.
	4.2	Send mail to user about the change.

Use case 20: Update list of available subscriptions

Primary scenario

Use case 20	Update list of available subscriptions
Priority	1
Goal	When demands for new subscription types come in the Administrator must be able to add these new subscriptions types in an easy way.
Actors	Administrator
Pre-conditions	-
Post-conditions	-
Façade	-
Quality requirements	If the update is done when the system is up running the changes must take effect at the next incoming request after the file is saved.
Scenario	-
Description	Step	Action
	1	A new subscription type must be added.
	2	The Administrator uses a text-editor to update a text-file which contains the configuration.

Use case 21: Save/remove subscriptions

Primary scenario

Use case 21	Save/remove subscriptions
Priority	1
Goal	Save or remove subscription from database
Actors	SubscriptionEditor
Pre-conditions	-
Post-conditions	-
Façade	-
Quality requirements	-
Scenario	-
Description	Step	Action
	1	Save or remove subscription data in the database for a specific user