SSN-SRS-01 11-EN 1.1 - European Maritime Safety … Requirements Specification 01_11 10-Sept-04 . SafeSeaNet ... Use Case Package “SSN Monitoring & Polling” ... National Competent

N.V. Getronics Belgium S.A.

Rue de Genèvestraat 10

1140 BRUXELLES/BRUSSEL

� (32) 2 229.91.11

EUROPEAN COMMISSION

DIRECTORATE-GENERAL FOR ENERGY AND TRANSPORT Directorate G – Unit G2 – Maritime Transport – Maritime Safety

SafeSeaNet

Software Requirements Specification

01_11

10-Sept-04

SafeSeaNet - DG TREN - Unit G2 – Maritime Transport – Maritime Safety GETRONICS BELGIUM Software Requirements Specification – version 01_11

10-Sept-04 - Page 2

Document Approval NAME DATE SIGNATURE Prepared by: W. Van Acker 10-Sep-04 Checked by: D. Veny Quality control by: P. Delmée Approved by: Yves Hardy

(DG TREN)

Distribution List COMPANY NAME FUNCTION FOR INFO / APPROVAL DG TREN Y. Hardy Project Manager Approval DG TREN G. Bergot Info DG TREN A. De Marcellus Info Getronics P. Delmée Project Manager Info

Change Control History VERSION DATE AUTHOR DESCRIPTION PARAGRAPHS 00_01 21-May-03 F. Silvestre Original issue 01_00 21-Sep-03 F. Silvestre Release iteration E1 01_10 21-Oct-03 F. Silvestre Release iteration C1 + Yves’s comments (3-Nov) 01_11 10-Sept-04 W. Van Acker

D. Veny Release iteration T3 Complete revision

Document information CREATION DATE: FILENAME: SSN-SRS-01_10-EN(1.1).doc LOCATION: NUMBER OF PAGES: 139

��133


10-Sept-04 - Page 3

CONTENTS

Changes between v.1.10 and 1.11 ........................................................................................................5 Introduction ..........................................................................................................................................6

Chapter 1: Requirements ...........................................................................................................................7 Overview ..............................................................................................................................................7 Types of Requirements.........................................................................................................................8 List of Functional Requirements ........................................................................................................12 List of Non-functional Requirements.................................................................................................15

Chapter 2: Use-Case Model .....................................................................................................................20 Overview ............................................................................................................................................20 Introduction ........................................................................................................................................21 Actor Catalog .....................................................................................................................................22 Use Case Catalog ...............................................................................................................................23

Section 2.1 - Use Case Package “SSN Notifications” ...........................................................................26 Overview ............................................................................................................................................26 Use Case “Send Notifications” ..........................................................................................................27 Use Case “Send Port Notification” ....................................................................................................32 Use Case “Send Ship Notification”....................................................................................................38 Use Case “Send Hazmat Notification”...............................................................................................43 Use Case “Send Security Notification”..............................................................................................49 Use Case “Send Alert Notification”...................................................................................................54

Section 2.2 - Use Case Package “SSN Information Requests”..............................................................60 Overview ............................................................................................................................................60 Use-Case “Get Ship Information”......................................................................................................62 Use Case “Search for a ship” .............................................................................................................63 Use Case “Get Ship’s Latest Notifications”.......................................................................................68 Use Case “Get Ship’s Voyage” ..........................................................................................................73 Use Case “Get Ship’s Cargo Manifest” .............................................................................................77 Use Case “Get Ship’s Latest Incidents” .............................................................................................83 Use Case “Get Vessel Information”...................................................................................................86 Use Case “Get Notification Details”..................................................................................................89 Use-Case “Get Port Information”.......................................................................................................98 Use-Case “Get Area Information” ...................................................................................................103

Section 2.3 - Use Case Package “SSN Statistics”................................................................................108 Overview ..........................................................................................................................................108 Use-Case “Generate Statistics” ........................................................................................................109 Use-Case “Browse Statistics” ..........................................................................................................112

Section 2.4 - Use Case Package “Location Codes Management” .......................................................115 Overview ..........................................................................................................................................115 Use-Case “Manage Location Codes” ...............................................................................................116

Section 2.5 - Use Case Package “Vessel Information Management”..................................................119 Overview ..........................................................................................................................................119 Use-Case “Manage Vessel Information” .........................................................................................120

Section 2.6 - Use Case Package “SSN Download Area”.....................................................................124 Overview ..........................................................................................................................................124 Use-Case “Download Templates”....................................................................................................125

Section 2.7 - Use Case Package “SSN User Management”.................................................................127 Overview ..........................................................................................................................................127


10-Sept-04 - Page 4

Use-Case “Manage Users” ...............................................................................................................128 Section 2.8 - Use Case Package “SSN Authorization Management” ..................................................132

Overview ..........................................................................................................................................132 Use-Case “Manage User’s Access Rights” ......................................................................................133

Section 2.9 - Use Case Package “SSN Monitoring & Polling” ...........................................................137 Overview ..........................................................................................................................................137 Use-Case “Send Polling Request”....................................................................................................138


10-Sept-04 - Page 5

Changes between v.1.10 and 1.11

Changes

Page Map / Block text Description of the changes p. 24 List of Use Cases Update block p. 29 Basic Flow Update block p. 31 Technology & Data Variations

List Update block

p. 34 Basic Flow Update block p. 40 Basic Flow Update block p. 45 Basic Flow Update block p. 51 Basic Flow Update block p. 54 Brief Description Update block p. 59 Web interface UI New screenshot p. 63 Brief Description Update block p. 67 Web interface UI New screenshot p. 71 Web interface UI New screenshot p. 80 Web interface UI New screenshot All Updated Use Case diagrams p. 101 Brief Description Update block p. 107 UC-Generate Statistics New block p. 110 UC-Browse Statistics New block p. 119 UC-Manage Vessel Info New block p. 126 UC-Manage Users New block p. 131 UC-Manage User’s Access

Rights New block

p. 136 UC-Send Polling Request New block


10-Sept-04 - Page 6

Introduction

Purpose This document aims at capturing the complete software requirements for the system.

It fully describes the external behaviour of the application(s) or subsystem(s) identified. It also describes non-functional requirements, design constraints and other factors necessary to provide a complete and comprehensive description of the requirements for the software.

References The present document makes references to the following documents:

� [1] Specific Agreement n°25 under framework contract n° DI/02450-00 – 6-Aug-03

� [2] SSN Glossary – SSN-Glossary-01_00-EN.doc

� [3] SSN XML Messaging Reference Guide V1.51.

Abbreviations � AIS – Automatic Identification System

� CRUD – Create, Read, Update and Delete

� HAZMAT – Hazardous Material

� NCA – National Competent Authority

Structure of the document

The first chapter describes the functional and non-functional requirements. The second chapter describes the use-case model comprehensively, in terms of how the model is structured into packages and what use cases and actors are in the model.


10-Sept-04 - Page 7

Chapter 1: Requirements

Overview

Introduction This chapter describes the different requirements (functional and non-functional).

Contents This chapter contains the following topics.

Topic See Page Types of Requirements 8 List of Functional Requirements 12 List of Non-functional Requirements 15

��7

��11

��14


10-Sept-04 - Page 8

Types of Requirements

Definition A requirement is defined as "a condition or capability to which a system must

conform".

Functional requirements specify actions that a system must be able to perform, without taking physical constraints into consideration. These are often best described in a use-case model and in use cases. Functional requirements thus specify the input and output behaviour of a system.

Requirements that are not functional are sometimes called non-functional requirements. Many requirements are non-functional, and describe only attributes of the system or attributes of the system environment.

FURPS+ There are a many different kinds of requirements. One way of categorizing them is

described as the FURPS+ model [GRA92], using the acronym FURPS to describe the major categories of requirements with subcategories as shown below.

� Functionality,

� Usability,

� Reliability,

� Performance and

� Supportability

The "+" in FURPS+ helps you to also remember to also include such requirements as

� design constraints,

� interface requirements and

� physical requirements.

Functionality (FUN)

Functional requirements may include:

� feature sets,

� capabilities, and

� security.

Continued on next page


10-Sept-04 - Page 9

Types of Requirements, Continued

Usability (USA) Usability requirements may include such sub-categories as:

� human factors,

� aesthetics,

� consistency in the user interface,

� online and context-sensitive help,

� wizards and agents,

� user documentation, and

� training materials.

Reliability (REL)

Reliability requirements to be considered are:

� Availability (percentage of time available, hours of use, maintenance access,…)

� frequency / severity of failure,

� recoverability,

� predictability,

� accuracy, and

� mean time between failure (MTBF).

Performance (PER)

A performance requirement imposes conditions on functional requirements. For example, for a given action, it may specify performance parameters for:

� throughput (e.g. transactions per second),

� response time,

� recovery time, or

� resource usage (memory, disk, cpu,…).



10-Sept-04 - Page 10


Supportability (SUP)

Supportability requirements may include:

� testability,

� extensibility,

� adaptability,

� maintainability,

� compatibility,

� configurability,

� serviceability,

� installability, or

� localizability (internationalization).

Design Requirement (DES)

A design requirement, often called a design constraint, specifies or constrains the design of a system.

This section should indicate any design constraints on the system being built. Design constraints represent design decisions that have been mandated and must be adhered to. Examples include software languages, software process requirements, prescribed use of developmental tools, architectural and design constraints, purchased components, class libraries, etc.

Interface Requirement (INT)

This section defines the interfaces that must be supported by the application. It should contain adequate specificity, protocols, ports and logical addresses, etc., so that the software can be developed and verified against the interface requirements.

An interface requirement may be classified into:

� User interface (user interfaces that are to be implemented by the software)

� Hardware interface (hardware interfaces that are to be supported by the software, including logical structure, physical addresses, expected behavior, etc.)

� Software interface (software interfaces to other components of the software system. These may be purchased components, components reused from another application or components being developed for subsystems outside of the scope of this project, but with which this software application must interact).





Physical Requirement (HAR)

A physical requirement specifies a physical characteristic that a system must possess; for example,

� material,

� shape,

� size, and

� weight.

This type of requirement can be used to represent hardware requirements, such as

� the physical network configurations required

Applicable Standards Requirements (STD)

This section describes by reference any applicable standards and the specific sections of any such standards that apply to the system being described. For example, this could include legal, quality and regulatory standards, industry standards for usability, interoperability, internationalization, operating system compliance, etc.



List of Functional Requirements

Introduction Functional requirements specify actions that a system must be able to perform,

without taking physical constraints into consideration. Functional requirements thus specify the input and output behaviour of a system.

As these functional requirements are best described once translated into use cases (see Use Case Model chapter), a list of these functional requirements is given below with an identification, a short description for each of them and a reference with their corresponding use cases.

List of functional requirements

Each identified functional requirement is assigned a unique key “FUN-nn” where nn is a sequence number identifying the functional requirement. The table hereafter lists all the functional requirements:

Functional

Requirement Id

Description

FUN-01 The core SSN system must support the following XML generic notification messages coming from a Member State (via their own application or the SSN Data Provider web-application):

� Port notification � Ship notification � Hazmat notification � Security notification

FUN-02 The core SSN system must support an XML alert notification message (for SAR-SITREP, POLREP, Waste Alert, Lost/found containers, Others) coming from a Member State (via their own application or the SSN Data Provider web-application).

FUN-03 The core SSN system must support XML request messages coming from a Member State (via their own application or the SSN Data Provider web-application) and corresponding XML response messages to: � Search for a ship (based on IMO#) in order to get the list of

its latest notifications � Get a Port notification reporting for a given ship � Get a Ship notification reporting for a given ship � Get the details of a ship’s voyage � Get the cargo manifest for a given ship � Get a Hazmat notification reporting for a given ship � Get a Security notification reporting for a given ship � Get an Incident notification reporting for a given ship (or

when the ship is not identified).




List of Functional Requirements, Continued

List of functional requirements (continued)

Functional Requirement

Id

Description

FUN-04 The core SSN system must support XML request messages coming from a Member State (via their own application or the SSN Data Provider web-application) and corresponding XML response messages to: � Get the list of latest incidents for a given ship.

FUN-05 The core SSN system must support XML request messages coming from a Member State (via their own application or the SSN Data Provider web-application) and corresponding XML response messages to: � Search for a Port (based on user’s access rights) and get the

latest ETA notifications for vessels bound to a given port. FUN-06 The core SSN system must support XML request messages

coming from a Member State (via their own application or the SSN Data Provider web-application) and corresponding XML response messages to: � Search for a geographical area (based on user’s access

rights) and get a report of all the Alert notifications per incident type, vessel and area.

FUN-07 The core SSN system must provide default document templates to be downloaded for the generic and alert messages.

FUN-08 The SSN Data Provider web application must provide a default web interface to interact with the core SSN system. The web interface must provide the user interface for sending the above mentioned notifications and for requesting the information as described above.

FUN-09 The SSN Data Provider web application must allow the user to send email notification (with eventual attachments) to one or more CAs.

FUN-10 The SSN Data Provider web application must identify the user through a user name and password.

FUN-11 The core SSN system must provide a monitoring service to monitor the core SSN system.

FUN-12 The core SSN system must provide a polling service to assert the availability of the Member States systems.

FUN-13 The core SSN system must log all the activities (exchange of messages) to be able to provide statistics.

FUN-14 The system must allow the SSN and National NCA administrators to extract statistics of use, standard delay of reply by member/period, percentage of unsuccessful transaction,... .




List of Functional Requirements, Continued

List of functional requirements (continued)

Functional Requirement

Id

Description

FUN-15 The system must provide the management of users along with their roles and their access rights to the different messages (CRUD).

FUN-16 The system must provide the management of location codes (upload of existing locodes data + CRUD) and vessels (update vessel information from notifications data).

FUN-17 The system must be able to include new members in the network through simple administrative tasks.

FUN-18 The system must be highly automatic to relieve the users of as many repetitive and tedious tasks as possible.

FUN-19 The system must provide at application level a full security and encryption policy compatible with the level of security required in such situation. The use of HTTPS and digital certificates is proposed as mechanism for exchanging messages between the NCA applications and the core SSN system. User name & password will be used to authenticate users connected via the SSN Data Provider web application.



List of Non-functional Requirements

Introduction Non-functional requirements describe only attributes of the system or attributes of

the system environment.

Each identified non-functional requirement is assigned a unique key “XXX-nn” where XXX identifies the type of requirement (e.g. PER for performance requirement) and nn is a sequence number identifying the non-functional requirement.

Usability requirements

The table hereafter lists all the non-functional “usability” requirements:

Usability

Requirement Id Description

USA-01 The system must guide users through an interface based on end user concepts.

USA-02 The system must be easy to learn and does not obstruct the thematic understanding of the users.

USA-03 The system must make it easy to correct mistakes. USA-04 A “User Guide” manual for the end-users must be produced,

describing the way to use the different functionalities embedded in the web user interfaces developed for the Member States.

USA-05 A “Pilot Group” document must also be produced aiming at explaining the different procedures to follow for the Member States belonging to the pilot group.

USA-06 A “SSN XML Messaging Reference Guide” describing the final version of the specifications of the structure and the flow of the messages exchanged between the core SSN system and the different Member States (NCAs).

USA-07 A “SSN Network & Security Reference Guide” describing the security mechanisms and procedures to follow to set up the necessary infrastructure based on the security requirements and the network procedures to use TESTA-II.

USA-08 English is the only supported language for the web interface and the XML messages.

Reliability requirements

The table hereafter lists all the non-functional “reliability” requirements:

Reliability


REL-01 The system is to be designed as a robust and dependable operational system which is tolerant to operator errors and which will recover cleanly from power cuts or other disasters.




List of Non-functional Requirements, Continued

Reliability requirements (continued)

Reliability Requirement Id

Description

REL-02 The system must function reliably, with few or no interruptions in its first operational year and fewer still thereafter.

REL-03 The system must give stable and reproducible results. REL-04 Requests shall automatically fail over from non-working

components to working components. Moreover, the session state shall be protected to ensure that any failures that do occur (e.g., a server crash) can be fully masked from the user and the application.

REL-05 Users should not have to deal with the intricacies of replication, request routing, load balancing, and fail over. They shall transparently deploy application components without modification on a clustered application server.

Performance requirements

The table hereafter lists all the non-functional “performance” requirements:

Performance


PER-01 The system should be able to cover more than one contact point per country depending on the administrative organisation adopted by each country and able to work in a multi hierarchical environment. Nevertheless, most of the countries agree to have a single point of contact (SPOC).

PER-02 There will be no restriction in time or place for the use of the software built from the specifications produced under this contract.

PER-03 The system must be able to establish and keep the dialog with the Members systems despite the various technical environments and technologies used on their sites.

PER-04 The system will be designed so that background tasks can continue while the user performs foreground tasks.

PER-05 The system will be used 24x7 by operators under pressure to produce results rapidly. The system must respond rapidly to user requests irrespective of any background tasks. Such high-availability (24x7) is also required from the Member States systems to ensure acceptable response time (less than 1 minute) to enforcement authorities requests.

PER-06 System administrators shall be able to add easily and dynamically to the configuration, as needed, to meet increasing user demand. In addition, the overall request load is distributed among the servers so that resources remain fully utilized.





Supportability requirements

The table hereafter lists all the non-functional “supportability” requirements:

Supportability


SUP-01 The system should be able to support other types of messages such as alert messages (SITREP, POLREP,…).

SUP-02 The system must be maintainable and extensible. SUP-03 The system must be designed so that it can migrate to

upgraded hardware or new versions of the operating systems involved.

SUP-04 The system must be able to migrate to other type of network than the one proposed by TESTA-II.

Design requirements

The table hereafter lists all the non-functional “design” requirements:

Design


DES-01 The system must be designed and documented with the expectation that its operational lifetime will be many years.

DES-02 Each Member of this network will organise its data about maritime activities with no constraints or recommendations on operating system and/or technology used. The system will be able to dialog with these environments or specify a generic interface to dialog with the Member’s applications.

DES-03 The core SSN system application must be developed using DI’s recommended software, i.e.: � BEA WebLogic Server 7.0 SP2 as application server

(while others more recent versions of this product are yet provided by BEA, the use of the 7th version is mandatory as it is the only one homologated by the client)

� The system will be developed in Java, using the JDK 1.3_06. While others more recent JDK versions are available, this version of JDK is the only one supported by BEA WebLogic 7.0 SP2.

� Oracle 9i as database

� SUN Solaris as operating system (for both application & database servers)

DES-04 The system must use Internet standards like XML, HTTPS, HTML.

DES-05 The core SSN system must be designed to handle the exchange of XML messages asynchronously.





Design requirements (continued)

Design Requirement Id

Description

DES-06 While the core system will be developed in Java, taking advantage of the J2EE specifications in order to provide a standard and portable middleware, no assumption may be done concerning the technology used by the user legacy applications. Accordingly, the only available protocol at the user site is considered to be HTTP 1.1 and no Web Services, J2EE or RMI/IIOP clients will be supported by the core system.

DES-07 The system has to be as scalable as possible, meaning that all the software components needs to be loosely coupled, in order to isolate them and to insure the possibility of their deployment on different application servers, running eventually on different hosts.

DES-08 The system will extensively use OpenSource products, like log4j, castor, JUnit, cactus, struts, etc. in order to fulfil the lack by the JDK of these functionalities.

DES-09 As far as J2EE is concerned, the core system needs to be as portable as possible. Accordingly, it is supposed to be able to run with other J2EE compliant application servers and its dependences to BEA WebLogic 7.0 must be minimized. However, as far as the Oracle 9i Data Server is concerned, the system will not provide any particular degree of portability towards other data servers.

Interface requirements

The table hereafter lists all the non-functional “interface” requirements:

Interface


INT-01 The system must use the network facilities supplied by the TESTA-II network.

INT-02 The algorithms in the software will be based on existing techniques and no research will be required to develop new algorithms under this contract.

INT-03 Most of the functionality of the new software shall depend on pre-existing or commercially available software.





Interface requirements (continued)

Interface Requirement Id

Description

INT-04 The Data Provider web-based application must be able to give access (via another window) to the SIRENAC and EQUASIS sites via Internet.

INT-05 The core SSN system must be able to support EDI messages (along with XML/EDI and EDI/XML conversion) dealing with Hazmat information. No longer a requirement since the EC has decided not to support EDIFACT but only XML (26-Sep-2003).

Physical requirements

The table hereafter lists all the non-functional “physical” requirements:

Physical


HAR-01 -

Applicable Standards Requirements

The table hereafter lists all the non-functional “applicable standards” requirements:

Applicable Standards

Requirement Id

Description

STD-01 All date and time information must be in UTC format.



Chapter 2: Use-Case Model

Overview

Introduction This chapter describes the use-case model comprehensively, in terms of how the

model is structured into packages and what use cases and actors are in the model.

Contents This chapter contains the following topics:

Topic See Page Introduction 21 Actor Catalog 22 Use Case Catalog 23 Use Case Package “SSN Notifications” 26 Use Case Package “SSN Information Requests” 60 Use Case Package “SSN Statistics” 108 Use Case Package “Location Codes Management” 115 Use Case Package “Vessel Information Management” 119 Use Case Package “SSN Download Area” 124 Use Case Package “SSN User Management” 127 Use Case Package “SSN Authorization Management” 132 Use Case Package “SSN Monitoring & Polling” 137

��20

��21

��22

��116

��120

��125

��128

��133

��138



Introduction

What’s a Use-Case Model ?

A use-case model is a model of the system's intended functions and its surroundings. It serves as a contract between the customer, the users and the system developers on the functionality of the system, which allows :

� Customers and users to validate that the system will become what they expected.

� System developers to build what is expected.

The same use-case model is used in system analysis, design, implementation, and testing.

The use-case model consists of use cases and actors.

What’s an Actor ?

An actor defines a coherent set of roles that users of the system can play when interacting with it. A user can either be an individual or an external system.

What’s a Use Case ?

A use case defines a set of use-case instances, where each instance is a sequence of actions a system performs that yields an observable result of value to a particular actor. Each use case in the model is described in detail, showing step-by-step how the system interacts with the actors, and what the system does in the use case. Use cases function as a unifying thread throughout the software lifecycle.



Actor Catalog

Introduction This map describes the list of identified actors.

List of actors The following figure describes the different actors:

SafeSeaNet - List of Actors

SSN Administrator

NCA Administrator

The SSN Administrator is in charge of administering the whole SSN services in terms of configuration, performance, logging, monitoring, user management, locode management,...

The NCA Administrator is the single person of contact regarding SafeSeaNet in a country (NCA). He may manage the web users belonging to his country and have access to the statistics generated by SSN for his country.

SSN Web User

NCA Application

The NCA Application is the application (that NCA should implement) that will interact (exchange of XML/EDI messages) with the SSN system, by sending notifications to SSN and/or requesting information from SSN and/or providing information to SSN.

The SSN Web User is a person who's using the supplied SSN browser-based web interface for sending notifications to SSN and/or requesting information from SSN. The SSN Web user typically works for a Local Competent Authority (LCA) or a National Competent Authority (NCA).

SIReNaC System

Equasis System

The SIRENAC system provides a web interface for getting information on vessels. SafeSeaNet will provide SIRENAC information about vessels through its default web interface.

The Equasis system provides a web interface for getting information on vessels. SafeSeaNet will provide Equasis information about vessels through its default web interface.



Use Case Catalog

Introduction This map describes the list of identified use cases. For clarity reasons, use cases are

organized as packages. The description of each of the use cases packages is given in the next sections.

Use Case Model Diagram

The following figure outlines the major actors and use cases of the SafeSeaNet system:

Get SSN Information

(from SSN Information Requests)

SSN Web User

(from Actors)

Send Notificat ions

(from SSN Notifications)

Get Noti fication Details

(from Notifications Details)

NCA Appl ication

(from Actors)

Send Polling Request

(from M onitoring & Polling )

Download Templates

(from SSN Download Area)

NCA Adm inistrator

(from Actors)Browse Statistics

(from SSN Statistics)

Manage Location Codes

(from Location Codes Manageme...

Manage Users' Access Rights

(from SSN Authorization Manageme...

Monitor the sy stem

(from M onitoring & Polling )

Manage Users

(from SSN User Management)

SSN Adm inistrator

(from Actors)

M anage Vessel Inform ation

(from Vessel Information Manageme...

Figure 1 – Use Case Model Diagram




Use Case Catalog, Continued

List of Use Case Packages

For organizational purposes, use cases are gathered in packages. The list of the SSN Use Case Packages is outlined in the following diagram:

SSN Notifications SSN Information Requests

SSN Statistics

SSN User Management

Location Codes Management

Monitoring & Polling

SSN Authorization Management

Vessel Information Management

SSN Download Area

Figure 2 – List of Use Case Packages

List of Use Cases

The table hereafter lists all the use cases along with their assigned id:

The UC Package… Contains the following Use Cases… SSN Notifications � Send Notifications

� Send Port Notification � Send Ship Notification � Send Hazmat Notification � Send Security Notification � Send Alert Notification � Send Email




Use Case Catalog, Continued

List of Use Cases (continued)

The UC Package… Contains the following Use Cases… SSN Information Requests

� Get Ship Information � Search for a ship � Get Ship’s Latest Notifications � Get Ship’s Voyage � Get Ship’s Cargo Manifest � Get Ship’s Latest Incidents � Get Vessel Information � Get Notification Details � Get Latest Port Notification Details � Get Latest Ship Notification Details � Get Latest Hazmat Notification Details � Get Latest Security Notification Details � Get Alert Notification Details � Get Port Information (latest ETA) � Get Area Information (list of incidents)

SSN Statistics � Browse Statistics � Generate Statistics

Location Codes Management

� Manage Location Codes

Vessel Informat ion Management

� Manage Vessel Information

SSN Download Area � Download Templates SSN Authorization Management

� Manage User’s access rights

SSN User Management � Manage Users Monitoring & Polling � Send Polling Request



Section 2.1 - Use Case Package “SSN Notifications”

Overview

Introduction This section describes the use cases related to the “SSN Notifications” package. The

following diagram lists the use cases of this package:

SSN Web user

NCA appl ication

Send Email

Send Noti fication Login

Send Alert Notification Send Port Noti fication Send Ship Notification Send Hazmat Noti fication Send Securi ty Noti fication

Send AIS Noti fication Send MRS Notification

Figure 3 –Use Case Package “SSN Notifications”

Contents This section contains the following topics:

Topic See Page Use Case “Send Notifications” 27 Use Case “Send Port Notification” 32 Use Case “Send Ship Notification” 38 Use Case “Send Hazmat Notification” 43 Use Case “Send Security Notification” 49 Use Case “Send Alert Notification” 54 Use Case “Send Email”



Use Case “Send Notifications”

Brief Description

The SSN Web user (via the supplied web interface) or the NCA application (via the XML interface) notifies the central SSN system that they own some kind of information. This abstract use case consists of sending different types of notifications to the central SSN system:

� A port notification

� A ship notification

� An Hazmat notification

� A security notification

� An alert notification A notification is sent by a "data provider" and aims at telling SSN that this "data provider" owns a particular type of information, so that, when a "data requester" asks to SSN for the detailed information about this notification, SSN knows where it's located and how to get it from.

Two interfaces should be provided:

� A web interface enabling a "data provider" user to type in the notification data in a web form and submit it to the central SSN system. This web application (called NCA simulation system) will internally use the XML interface for sending the notification to the core SSN system.

� An XML interface enabling a "data provider" application to send the notification data in XML to the central SSN system.

Primary Actor � SSN Web user

� NCA Application

Preconditions The actors have access to the SafeSeaNet central system.

Postconditions The sent notification is recorded in the SSN index database.

Stakeholders and Interests

This abstract use case is one of the major use cases as it enables the different Member States to share information by telling the central SSN system they own some kind of information about a ship:

� The LCA and/or NCA may indicate they own some kind of information about a ship.

� The central SSN system will store the location of the information and then be able to answer to queries coming from other LCA or NCA.




Use Case “Send Notifications”, Continued

Activity diagram

The following activity diagram outlines the different steps of this use case:

Log on the SSN Web Application

Select the Notif ication ty pe

Submit the IMO# or MMSI#

Submit the Notif ication data

View conf irmation

Send XML Notif ication to SSN

Check SSN Receipt (ACK or NACK)

Check the user name/password

Check the IMO# and MMSI# in SSN DB

Send XML Notif ication to SSN

Check SSN Receipt (ACK or NACK)

Process the Notif ication

MS2SSN_<SSN_Tx_Type>_Not

MS2SSN_<SSN_Tx_Type>_Not

SSN_Receipt

SSN_Receipt

<SSN_Tx_Ty pe> can either be:------------------------------------------Port (Port Notif ication)Ship (Ship Notif ication)Hazmat (Hazmat Notif ication)Security (Security Notif ication)Alert (Alert Notif ication)

SSN Core SystemNCA Simulation ApplicationNCA ApplicationSSN Web User

Figure 4 –“Send Notifications” activity diagram

Basic Flow SafeSeaNet should supply a default browser-based web interface and an XML

interface (for EAI). The XML interface will be used by NCA application but also by the default SSN web application when processing requests coming from the web interface.

Step Action

1 The SSN web user gets connected to the SSN browser-based web application. From the home page, he selects “Notify SafeSeaNet”. The SSN Web application asks him to type in his username and password.

2 The SSN web user types in his user name and password. The SSN Web application verifies the credentials and, if successful, displays the “Notify SafeSeaNet” menu customized according to his access rights.

3 The SSN Web user selects one type of notification and the SSN Web application displays the web form corresponding to the selected notification type. As this use case is an abstract use case, the description of the different web forms will be given in the specialized use cases.





Basic Flow (continued)

Step Action 4 The SSN Web user types in the IMO number or the MMSI number and

submits it to the SSN Web application, which, in turn, sends it to the SSN system. The SSN system searches for the IMO number or MMSI number in its central DB and sends back the IMO#, MMSI#, the call sign and the ship name (more info may be returned like whether the vessel is banned or not). These information are displayed back in the web form in editable format.

5 The SSN Web user checks the returned information, updates it if needed, fills in the fields corresponding to the selected notification type and submits it to the SSN Web application.

6 The SSN web application prepares the corresponding XML message and sends it to the SSN core system. If the user was the NCA application, its involvement in the use case starts here by preparing the corresponding XML message and sending it to the SSN core system.

7 The SSN core system will check the validity of the XML message, check that the caller has the right for sending such notification, then update its Vessel Information database with the vessel information supplied in the notification, then store the notification in its Index database and return an ACK to the caller (HTTP 202 closing the HTTPS connection).

8 The SSN Web application displays back the result (ACK or NACK) to the SSN Web user. The NCA application should process the ACK or NACK accordingly.

9 The SSN Web user has the opportunity to send an email in order to warn someone else (or some other authorities). He may then fill in the displayed web form, insert a file attachment and click on the “Send” buttons). The SSN web application will build and send the email (using a mail server).

Alternative Flow

More complex alternatives are described here below, referred to in the Basic Flow subsection.

Step Action 3a What if the web user has no right at all?

Answer: in the case of the web interface, a message will be displayed to the web user stating she’s not entitled to send such notification and that she should get in touch with her NCA for further information. In case of the XML interface, “AccessDenied” will be returned as StatusCode.

7a What if the XML message is not valid? Answer: in the case of the web interface, a message will be displayed indicating which field is invalid. The validity of the web form’s fields should be checked with client-side Javascript. In case of the XML interface, “InvalidFormat” will be returned as StatusCode with the reason (if given by the XML parser) as StatusMessage.



7b What if the credentials given in the XML message are not correct? Answer: same as 3a.





Technology and Data Variations List

� SSN will manage its own database of vessels. This database will be updated every time a notification is received with the vessel information transmitted in the notification: � If the sender does not know the IMO# the notification is stored under the

provided MMSI# on the condition that the MMSI# is recognized. If not, system will warn sender that a new vessel will be created (if using the Web UI), or the new vessel will be created automatically (if using the XML interface).

� If the sender does not know the MMSI# the notification is stored under the provided IMO# on the condition that the IMO# is recognized. If not, system will warn sender that a new vessel will be created (if using the Web UI), or the new vessel will be created automatically (if using the XML interface).

� If the sender knows IMO# and MMSI# but MMSI# is different than the one linked with the IMO#, a vessel update will take place.

� If the sender knows IMO# and MMSI# but IMO# is different than the one linked with the MMSI#, the vessel is not updated. If another vessel exists with the correct IMO# but another MMSI# then we trigger the previous case.

� Recording who and when the creation/modification has been made is also important.

�

Open issues � How to get initial information (IMO#, MMSI#, Call sign, ship name) about

vessels? Answer: DG TREN will provide a list (Excel file) of all the vessels currently identified in the European seas. This list will be initially uploaded in the SSN database.

� Should the notifications be sent synchronously (e.g. as web services) or asynchronously (with an extra XML message for the acknowledgement)? Answer: every notification should be sent synchronously (acknowledgement is the HTTP 202 return code).

� Where should date & time of the notification be computed? On the client side (what about time synchronization) or on the web application server (when sent via the browser-based web interface) or on the SSN system? Answer: on the web application server (for web interface) and on the NCA application server (if XML interface).

Extension Points

� Use Case “Send Port Notification”

� Use Case “Send Ship Notification”

� Use Case “Send Hazmat Notification”

� Use Case “Send Security Notification”

� Use Case “Send Alert Notification”



Use Case “Send Port Notification”

Brief Description

The SSN Web user (via the supplied web interface) or the NCA application (via the XML interface) notifies the central SSN system that a vessel is bound for a port.

The parent use case is Use Case “Send Notifications”.

A port notification should be sent by the next port of call of a ship when the master of a vessel warns this port that it's gonna be the ship's next port of call.

When the master of a ship changes his mind (e.g. he will no longer call in the port), he must warn the port that the ship will no longer call in the port. Then, this port must send a port notification to SSN telling the next port of call is unknown (unless the master of the vessel did mention it). This is indeed a cancellation of the previous port notification and merely consists of a new port notification (with next port of call more likely ‘unknown’).

Please note that the port notification is the only one conveying all its details in the notification. Therefore, SSN becomes also the owner of the information. Upon request from a data requester, there's no need for SSN to request the details from the original data provider.


� NCA Application




Same as parent use case Use Case “Send Notifications”.




Use Case “Send Port Notification”, Continued

Basic Flow This use case inherits from its parent Use Case “Send Notifications”. The following

symbols are used in the flow of events to indicate how each activity relates to the parent’s use case one:

� [In] � means nth activity inherited and unchanged

� [Sn] � means nth activity inherited and specialized

� [N] � means new activity

Step Action 1 The SSN web user gets connected to the SSN Web application. From the

home page, he selects “Notify SafeSeaNet”. The SSN Web application asks him to type in his username and password. [I1]

2 The SSN web user types in his user name and password. The SSN Web application verifies the credentials and, if successful, displays the “Notify SafeSeaNet” menu customized according to his access rights. [I2]

3 The SSN Web user selects “Port notification” from the menu and the SSN Web application displays the web form corresponding to the selected notification type. Prior to sending the notification, the SSN Web user should first check the vessel information corresponding to the IMO number used for the notification. [S3]

4 The SSN Web user types in the IMO# or MMSI# and submits it to the SSN Web application, which, in turn, sends it to the SSN system. The SSN system searches for the IMO# or MMSI# in its central DB and sends back the MMSI number, the call sign and the ship name (more info may be returned like whether the vessel is banned or not). These information are displayed back in the web form in editable format. [I4]

5 The SSN Web user checks the returned information, updates it if needed, fills in the fields corresponding to the selected notification type and submits it to the SSN Web application. [S5] The web form for the port notification type consists of: � Vessel Static Information:

� IMO number � MMSI number � Call sign � Ship name

� Vessel Dynamic Information: � Next port of call (list of all location codes) � mandatory � ETA � mandatory (if next port of call known) � ETD � mandatory (if next port of call known) � The total number of persons aboard � mandatory � Date/time of notification (current date & time – not editable)






Step Action 6 The SSN web application prepares the corresponding XML message

(MS2SSN_Port_Not.xml) and sends it to the SSN system. If the user was the NCA application, its involvement in the use case starts here by preparing the corresponding XML message (MS2SSN_Port_Not.xml) and sending it to the SSN system. [S6]

7 The SSN system will check the validity of the XML message (MS2SSN_Port_Not.xml), check that the caller has the right for sending such notification, then update its Vessel Information database with the vessel information supplied in the notification, then store the notification in its Index database and return an ACK to the caller (HTTP 202 closing the HTTPS connection). [S7]

8 The SSN Web application displays back the result (ACK or NACK) to the SSN Web user. The NCA application should process the ACK or NACK accordingly. [I8]

9 The SSN Web user has the opportunity to send an email in order to warn someone else (or some other authorities) about the incident. He may then fill in the displayed web form, insert a file attachment and click on the “Send” buttons). The SSN web application will build and send the email (using a mail server). [I9].

Alternative Flow



Answer: see p.29 7a What if the XML message is invalid

Answer: see p.29 7b What if the credentials given in the XML message are not correct?

Answer: see p.29

Special Requirements

Requirement

Id Description



STD-01 According to the Traffic Monitoring Directive based on Notification, prior to entry into ports of the Member States, the operator, agent or master of a ship bound for a port of a Member State shall notify the information to the port authority: � At least twenty-four hours in advance;

� At the latest, at the time the ship leaves the previous port, if the voyage time is less than 24 hours






-

Assumptions � The given port notification data are in fact all the data of a port notification.

Therefore, when a data requester wants to have detailed information about the latest port notification, SSN will not forward the request to the data provider but merely return the data it has stored in its database at notification time.

Open issues � How to get initial data for the location codes (keeping only maritime related

ones)? Answer: DG TREN will ask the MS to send the location codes of their entities involved in SafeSeaNet. These locodes will be initially uploaded in the SSN database.

� Should ETD also be part of the notification? Answer: Yes

Extension Points

-

XML interface Please refer to the “MS2SSN_Port_Not.xml” message in the XML Messaging

Reference Guide [3].





Web interface UI

The following screen shows the first screen for this notification:

The following screen shows the main screen for this notification (after successful search result):

A last screen is then displayed with the following message “Your notification has been sent successfuly” when the notification has been sent successfully.



Use Case “Send Ship Notification”

Brief Description

This abstract use case consists of sending a ship notification to the SSN system (see Use Case “Send Notifications” parent use case for more details about the notification concept).

A ship notification aims at giving some information about the current position of a vessel (longitude/latitude), its next port of call, its ETA, the total number of persons on board and how the detailed information about this ship notification can be requested by SSN (fax, file, xml) when a vessel enters and leaves an area controlled by a coastal station or a port authority.

A ship notification can be of 2 types: MRS or AIS.

AIS Notification

AIS notifications are based on AIS messages transmitted automatically from the vessels to AIS stations (every 6 seconds). As SSN is NOT aimed at monitoring the vessels traffic, there's no need of sending AIS notification every time an AIS message is received. AIS notifications should be sent when a ship enters and leaves an area controlled by a coastal station or port authority. Please note that the AIS system is not yet installed and available to all EU countries (target: 2008).

As this AIS message is transmitted automatically (without manual intervention), its notification will be sent by a NCA application via the XML interface.

MRS Notification

MRS notifications are based on messages transmitted via radio frequency from the master of a vessel to a coastal station or a port authority. MRS notifications should be sent when a ship enters and leaves an area controlled by a coastal station or port authority.


� NCA Application








Use Case “Send Ship Notification”, Continued









3 The SSN Web user selects “Ship – MRS notification” from the menu and the SSN Web application displays the web form corresponding to the selected notification type. Prior to sending the notification, the SSN Web user should first check the vessel information corresponding to the IMO number used for the notification. [S3]

4 The SSN Web user types in the IMO# or MMSI# and submits it to the SSN Web application, which, in turn, sends it to the SSN system. The SSN system searches for the IMO# or MMSI# in its central DB and sends back the MMSI number, the call sign and the ship name. These information are displayed back in the web form in editable format. [I4]



� Vessel Dynamic Information: � Next port of call (list of all location codes) � mandatory � ETA � mandatory (if next port of call known) � The total number of persons aboard � mandatory � Date/time of notification (current date & time – not editable) � Ship’s position (longitude/latitude)

� Notifications details (either document on a web server or XML or phone/fax).






Step Action 6 The SSN web application prepares the corresponding XML message

(MS2SSN_Ship_Not.xml) and sends it to the SSN system. If the user was the NCA application, its involvement in the use case starts here by preparing the corresponding XML message (MS2SSN_Ship_Not.xml) and sending it to the SSN system. [S6]

7 The SSN system will check the validity of the XML message (MS2SSN_Ship_Not.xml), check that the caller has the right for sending such notification, then update its Vessel Information database with the vessel information supplied in the notification, then store the notification in its Index database and return an ACK to the caller (HTTP 202 closing the HTTPS connection). [S7]



Alternative Flow



Answer: see p.29 7a What if the XML message is invalid?


Answer: see p.29


Requirement

Id Description

�






� Longitude and latitude should be given in degree, minutes, seconds (default for MRS) or 1/10000th of minutes (default for AIS).

Assumptions � The url eventually specified as notification details must be accessible from the

central SSN server (domain name recognized by DI data center).



Extension Points

-

XML interface Please refer to the “MS2SSN_Ship_Not.xml” message in the XML Messaging






Web interface UI

The initial screen (ship search) is the same as for the “port notification” (see p.37).

The following screen shows the first main screen for this notification (after successful search result):

The following screen shows the 2nd main screen for this notification:




Use Case “Send Hazmat Notification”

Brief Description

This use case consists of sending a Hazmat notification to SSN.


Hazmat notification aims at warning SSN that a vessel carries hazardous material (dangerous goods). In the notification, the data provider mentions how the detailed information about the Hazmat message can be requested (phone/fax, url or via xml interface) but also how the cargo manifest can be downloaded from (phone/fax or url).


� NCA Application
















Use Case “Send Hazmat Notification”, Continued


Step Action 3 The SSN Web user selects “Hazmat notification” from the menu and

the SSN Web application displays the web form corresponding to the selected notification type. Prior to sending the notification, the SSN Web user should first check the vessel information corresponding to the IMO number used for the notification. [S3]




� Vessel Dynamic Information: � Next port of call (list of all location codes) � mandatory � ETA � mandatory (if next port of call known) � ETD � mandatory (if next port of call known) � The total number of persons aboard � mandatory � Date/time of notification (current date & time – not editable)

� Hazmat notifications details (either document on a web server or XML or phone/fax).

� Cargo manifest details (either document on a web server or XML or phone/fax). Phone/fax by default.

6 The SSN web application prepares the corresponding XML message (MS2SSN_Hazmat_Not.xml) and sends it to the SSN system. If the user was the NCA application, its involvement in the use case starts here by preparing the corresponding XML message (MS2SSN_ Hazmat _Not.xml) and sending it to the SSN system. [S6]

7 The SSN system will check the validity of the XML message (MS2SSN_ Hazmat_Not.xml), check that the caller has the right for sending such notification, then update its Vessel Information database with the vessel information supplied in the notification, then store the notification in its Index database and return an ACK to the caller (HTTP 202 closing the HTTPS connection). [S7]






Step Action 8 The SSN Web application displays back the result (ACK or NACK) to

the SSN Web user. The NCA application should process the ACK or NACK accordingly. [I8]


Alternative Flow





Answer: see p.29


Requirement

Id Description

�


-







Extension Points

-





XML interface Please refer to the “MS2SSN_Hazmat_Not.xml” message in the XML Messaging


Web interface UI


The following screen shows the first main screen for this notification (after successful search result):





Web interface UI (continued)

The following screen shows the 2nd main screen for this notification:




Use Case “Send Security Notification”

Brief Description

This use case consists of sending a security notification to SSN.


A security notification is not yet well defined. A separate task force (out of the scope of this project) will analyse and define the exact contents of this message.

But the principle is the same as for the other notification. The data provider will send this notification to warn SSN that it owns some detailed information about the security related to a specific ship.

In the notification, the data provider mentions how the detailed information about the notification can be requested (phone/fax, url or via xml interface).


� NCA Application















Use Case “Send Security Notification”, Continued


Step Action 2 The SSN web user types in his user name and password. The SSN Web

application verifies the credentials and, if successful, displays the “Notify SafeSeaNet” menu customized according to his access rights. [I2]

3 The SSN Web user selects “Security notification” from the menu and the SSN Web application displays the web form corresponding to the selected notification type. Prior to sending the notification, the SSN Web user should first check the vessel information corresponding to the IMO number used for the notification. [S3]




� Date/time of notification (current date & time – not editable)


6 The SSN web application prepares the corresponding XML message (MS2SSN_Security_Not.xml) and sends it to the SSN system. If the user was the NCA application, its involvement in the use case starts here by preparing the corresponding XML message (MS2SSN_Security_Not.xml) and sending it to the SSN system. [S6]

7 The SSN system will check the validity of the XML message (MS2SSN_Security_Not.xml), check that the caller has the right for sending such notification, then update its Vessel Information database with the vessel information supplied in the notification, then store the notification in its Index database and return an ACK to the caller (HTTP 202 closing the HTTPS connection). [S7]









Alternative Flow





Answer: see p.29


Requirement

Id Description

�


-



Open issues -

Extension Points

-

XML interface Please refer to the “MS2SSN_Security_Not.xml” message in the XML Messaging






Web interface UI


The following screen shows the main screen for this notification (after successful search result):




Use Case “Send Alert Notification”

Brief Description

This use case consists of sending an alert notification to SSN.


Alert notification aims at telling SSN that the data provider owns details about an incident. This incident can be of different types:

� SITREP

� POLREP

� Lost/found containers

� Waste

� Others An alert notification can make reference to a ship (based on its IMO# or MMSI#) or not (when ship not identified). In the latter case, the alert is not assigned to a ship but only to the data provider sending the alert notification.

In the notification, the data provider mentions how the detailed information about the incident can be requested (phone/fax, url or via xml interface).


� NCA Application








Use Case “Send Alert Notification”, Continued









3a If the SSN Web user selects “Alert – Ship Identified notification” from the menu, the SSN Web application displays the web form corresponding to the selected notification type. Prior to sending the notification, the SSN Web user should first check the vessel information corresponding to the IMO number used for the notification. [S3]

4a The SSN Web user types in the IMO# or MMSI# and submits it to the SSN Web application, which, in turn, sends it to the SSN system. The SSN system searches for the IMO# or MMSI# in its central DB and sends back the MMSI number, the call sign and the ship name. These information are displayed back in the web form in editable format. [I4]

5a The SSN Web user checks the returned information, updates it if needed, fills in the fields corresponding to the selected notification type and submits it to the SSN Web application. [S5] The web form for the port notification type consists of: � Vessel Static Information:




3b 4b

If the SSN Web user selects “Alert – Ship Not Identified notification” from the menu, the SSN Web application displays the web form corresponding to the selected notification type. In that case, as the ship is not identified, the web form displays the default contact details of the authority the SSN Web user belongs to. [S3]






Step Action 5b The SSN Web user checks the returned information, updates it if needed,

fills in the fields corresponding to the selected notification type and submits it to the SSN Web application. [S5] The web form for the port notification type consists of: � Contact Details Information:

� Maritime Authority name � mandatory � Locode number � mandatory � Phone � mandatory � Fax � mandatory � email



6 The SSN web application prepares the corresponding XML message (MS2SSN_Alert_Not.xml) and sends it to the SSN system. If the user was the NCA application, its involvement in the use case starts here by preparing the corresponding XML message (MS2SSN_Alert_Not.xml) and sending it to the SSN system. [S6]

7 The SSN system will check the validity of the XML message (MS2SSN_Alert_Not.xml), check that the caller has the right for sending such notification, then update its Vessel Information database with the vessel information supplied in the notification, then store the notification in its Index database and return an ACK to the caller (HTTP 202 closing the HTTPS connection). [S7]







Alternative Flow


Step Action 3c What if the web user has no right at all?

Answer: see p.29 7a What if the XML message is invalid?


Answer: see p.29 9b What if the email can’t be sent?


Requirement

Id Description

�


-



� A mail server must be accessible so that SSN can send the emails requested using the browser-based interface.

� Every authority accessing SSN will be defined in the SSN configuration with, among others, their contact details (name, phone, fax, locode, email).

Open issues -

Extension Points

-

XML interface Please refer to the “MS2SSN_Alert_Not.xml” message in the XML Messaging






Web interface UI

If the ship is identified, the initial screen (ship search) is the same as for the “port notification” (see p.37). The following screen shows the main screen for this notification when the ship is identified (after successful search result):

The following screen shows the main screen for this notification when the ship is not identified:






A last screen is then displayed with the following message “Your notification has been sent successfuly” when the notification has been sent successfully along with a button for sending an email.

If the SSN web user clicks on this button, the following screen is displayed:

A last screen is then displayed with the following message “Your email has been sent successfuly” when the email has been sent successfully.



Section 2.2 - Use Case Package “SSN Information Requests”

Overview

Introduction This section describes the use cases related to the “SSN Information Requests”

package. The following diagram gives a high-level view of the use cases of this package:

Login

(from Included Use Cases)

SSN Web User

(f rom Actors)

Get Ship Information

(from Ship Reporting)

Get Port Information

(from Port Reporting)

Get Area Information

(from Area Reporting)

NCA Application

(f rom Actors)

Get SSN Information

Figure 5 –Use Case Package “SSN Information Requests”

The “Get SSN Information” use case is the global one encompassing all the functionalities related to the information that may be asked to SafeSeaNet.

This abstract use case consists of allowing the SSN web user (using the default browser-based web interface) to request different kinds of information about the different notifications previously sent to SSN by the data providers, and also information about a specific vessel. The requested information is of 3 types:

� Ship search

� Port Search

� Area Search

Please refer to the corresponding use cases for more details.

Please note that the current of the published XML interface will only allow to request the details of a given notification whereas the web interface will offer other functionalities based on the notifications collected by the central index server (e.g. ship's voyage history based on last ship notifications, list of ships bound to a port based on port, ship & hazmat notifications,....).




Overview, Continued


Topic See Page Use-Case “Get Ship Information” 62 Use Case “Search for a ship” 63 Use Case “Get Ship’s Latest Notifications” 68 Use Case “Get Ship’s Voyage” 73 Use Case “Get Ship’s Cargo Manifest” 77 Use Case “Get Ship’s Latest Incidents” 83 Use Case “Get Vessel Information” 86 Use Case “Get Notification Details” 89 Use-Case “Get Port Information” 98 Use-Case “Get Area Information” 103

��64

��69

��102



Use-Case “Get Ship Information”

Brief Description

This abstract use case consists of enabling the SSN web user to get access to different kinds of information related to a ship:

� ship search

� ship's latest notifications

� ship's voyage history

� ship's cargo manifest

� ship's latest incidents

� ship's information on Sirenac

� ship's information on Equasis

Please refer to the corresponding use cases for more details.

Use Case Diagram

SSN Web user Get Ship Information

Get Ship Latest Notifications

Get (Ship) Voyage History

Search Ship

Get Vessel Info

Get Incident History

NCA application Get Notification Detail

Get Hazmat Notification Detail Get Port Notification Detai l Get Ship Noti fication Detail

Get Security Noti fication Detail Get Alert Notificatio n Detai l

Get Cargo Manifest

Figure 6 –“ Get Ship Information” Use Case Diagram


This abstract use case is one of the major use cases as it enables the different Member States to get different kinds of information about a ship based on the different notifications received by SafeSeaNet and on the information provided by external sites like Equasis and Sirenac.



Use Case “Search for a ship”

Brief Description

This use case enables the SSN Web user to select the ship for which he'd like to get more information, based on the following criteria: IMO#, MMSI#, Call sign and ship name.

SSN will look into its own DB of ships and return the result of the query :

� None, one or more than one ships are returned. In case none are found, a status message is presented that no ships match the search criteria. In case one or more ships are found, a list of ships is displayed. If the SSN Web user selects a ship from the list, the previously selected sub-function (latest notifications, voyage history, cargo manifest or latest incidents) is displayed with the data corresponding to the selected ship.

Once a ship is selected, it becomes the default one for the other use cases related to the Use-Case “Get Ship Information” unless another is selected (via this use case or when selecting an IMO# in other use cases (e.g. Use-Case “Get Port Information” or Use-Case “Get Area Information”).

The parent use case is Use-Case “Get Ship Information”.


Preconditions The actor has access to the SafeSeaNet browser-based web application, has selected

“Find Information” from the main menu, has entered her credentials (user name/password) and has selected “Ship search” and one of its sub-functions among:

� ship's latest notifications (by default)

� ship's voyage history

� ship's latest incidents

� vessel information on third–party websites like Sirenac en Equasis

Postconditions The list of ships corresponding to the search criteria is displayed and the actor may

select one ship.


Same as Use-Case “Get Ship Information”




Use Case “Search for a ship”, Continued

Basic Flow The basic flow for this use case is the following:

Step Action 1 The SSN web user is logged on the SSN Web application and has

selected Find Information/Ship Search (as explained in the preconditions). The ship search web form is displayed with the following criteria: � IMO number � MMSI number � Call sign � Ship name The SSN web user can type in any criteria. Wildcard is only allowed for the ship name. The SSN Web submits the search form to the SSN Web application, which, in turn, sends it to the SSN system. The SSN system searches for vessels corresponding to the given search criteria in its central DB and sends back the result (IMO#, MMSI#, Call sign and ship name) sorted by ship name (ascending).

2a If the result consists of more than 1 vessel, the SSN web application displays the list to the SSN web user. The SSN web user can then ask for a new search or select a vessel from the list in order to get the information corresponding to the previously selected sub-function (latest notification, voyage history,…) for that vessel (refer to following use cases for more details).

2b If the result is empty (no ship found), a message is displayed to the SSN web user.

Alternative Flow


Step Action 2d What if any error (network,…) between the web application and the SSN

core system? Answer: the corresponding StatusCode value should be returned (Timeout or ServerError). In the case of the web interface, a message indicating the kind of problem should be displayed.






Requirement

Id Description

�


� The communication between the SSN Web application and the SSN core system regarding this functionality will be implemented as XML messages. These XML messages will be used internally in this 1st version but will be ready for publication in a next SSN version.

� SSN will manage its own database of vessels. As mentioned earlier (see Use Case “Send Notifications”), this database will be updated every time a notification is received with the vessel information transmitted in the notification. Obviously, an initial upload of vessels information must be carried out.

Assumptions � The maximum of vessels is defined in the SafeSeaNet properties config file.



Extension Points

�

XML interface The XML interface will be used internally between the SSN Web application

and the SSN core system and is not published in the XML Messaging Reference Guide [3].

This interface should consist of 2 messages:

MS2SSN_ShipSearch_Req: request sent by the data requester Header: equivalent to the other MS2SSN_..._Req message Body:

SearchCriteria: 1 occurrence IMO# MMSI# CallSign ShipName (wildcard allowed)





XML interface (continued)

� SSN2MS_ShipSearch_Res: response sent by SSN core system � Header: equivalent to the other SSN2MS_..._Res message with StatusCode:

OK or NotFound (if no ship matching the search criteria) � � Body:

o SearchCriteria: 1 occurrence (same as MS2SSN_ShipSearch_Req)

� IMONumber � MMSINumber � CallSign � ShipName

1. ShipSearchResult: 0..1 occurrence � VesselIdentification: 1..20 occurrences

• IMONumber • MMSINumber • CallSign • ShipName

Web interface UI

The initial screen is the following:


��





The following screen shows the “hit list” screen displayed when more than the search result contains more than one vessel:



Use Case “Get Ship’s Latest Notifications”

Brief Description

This use case enables the SSN Web user to get the list of the latest notifications (port, ship, hazmat & security) received by SSN for the selected ship. This information is based on the data stored by the central SSN index server. There is no need for requesting information to any data provider.




“Find Information” from the main menu, has entered her credentials (user name/password) and has selected “Ship search” and “ship's latest notifications” as sub-function. A ship has also been selected (via ship search or when clicking on an IMO# in another list).

Postconditions The list of the latest notifications for the selected vessel is displayed.




Step Action 1 The SSN web user is logged on the SSN Web application, has selected

Find Information/Ship Search (as explained in the preconditions), has already selected a ship and has selected “latest notifications” from the menu.

2 The SSN web application builds and sends the MS2SSN_ShipLatestNot_Req.xml message to the SSN core system, which will search in its index server for the 5 latest ports, the latest ship, the latest hazmat and the latest security notifications received for the selected vessel. The core SSN system will send back the SSN2MS_ShipLatestNot_Res.xml response to the SSN web application which, in turn, displays the result to the SSN Web user: � Notification type � Notification origin (locode) � Notification date & time � Remarks

3 The SSN Web user can sort the columns of the table or ask for getting the details of a notification (see Use Case “Get Notification Details”).




Use Case “Get Ship’s Latest Notifications”, Continued

Alternative Flow


Step Action 2a What if there is not any notification for the given vessel?

Answer: A status message is presented indicating no notifications are found for the vessel.

2b What if any error (network,…) between the web application and the SSN core system? Answer: see p.64


Requirement

Id Description

�


�

Assumptions -

Open issues � In order to mention “DG on board” for the Hazmat notification, that information

must be given at notification time (DG on board: Y/N) which is not the case up to now. Should we update the XML and Web interface to do so?

Extension Points

� Get Port Notification Details

� Get Ship Notification Details

� Get Hazmat Notification Details

� Get Security Notification Details


��65




XML interface The XML interface will be used internally between the SSN Web application and the

SSN core system and is not published in the XML Messaging Reference Guide [3].


� MS2SSN_ShipLatestNot_Req: request sent by the data requester � Header: equivalent to the other MS2SSN_..._Req message � Body:

2. SearchCriteria: 1 occurrence 3. IMONumber 4. MMSINumber

� SSN2MS_ShipLatestNot_Res: response sent by SSN core system

� Header: equivalent to the other SSN2MS_..._Res message � Body:

o SearchCriteria: 1. occurrence � IMONumber � MMSINumber

o ShipLatestNotResult: 0..1 occurrence � PortNotSummary: 0..5 occurrence

• From (mandatory) • SentAt (Mandatory) • NextPortOfCall • ETA

� AISNotSummary: 0..1 occurrence (choice with MRS…)

• From (mandatory) • SentAt (Mandatory) • NextPortOfCall • ETA • ShipPosition (mandatory)

o Longitude (mandatory) o Latitude (mandatory) o Timestamp(mandatory)

� MRSNotSummary: 0..1 occurrence (choice with AIS…)

• From (mandatory) • SentAt (Mandatory) • NextPortOfCall • ETA • ShipPosition (mandatory)

o Longitude (mandatory) o Latitude (mandatory)

� HazmatNotSummary: 0..1 occurrence • From (mandatory) • SentAt (Mandatory) • NextPortOfCall • ETA

��

��








� SecurityNotSummary: 0..1 occurrence • From (mandatory) • SentAt (Mandatory)

Web interface UI

The following screen gives an example of a list of the latest notifications for a given vessel (without any security notification):



Use Case “Get Ship’s Voyage”

Brief Description

This use case enables the SSN Web user to get the voyage history of the selected ship. This voyage history is based on the information stored by the central index server (the last 5 or 10 ship notifications received for the selected ship). The default view of this voyage history is a table sorted by default from the latest to the oldest notification. Another view could be to show the voyage history on a map in a separate window - using a special web cartography software like ESRI ArcIMS.




“Find Information” from the main menu, has entered her credentials (user name/password) and has selected “Ship search” and “ship's voyage history” as sub-function. A ship has also been selected (via ship search or when clicking on an IMO# in another list).

Postconditions The voyage history of the selected vessel is displayed.





Find Information/Ship Search (as explained in the preconditions), has already selected a ship and has selected “voyage history” from the menu.

2 The SSN web application builds and sends the MS2SSN_ShipVoyage_Req.xml message to the SSN core system, which will search in its index server for the latest ship notifications received for the selected vessel (configured through SafeSeaNet configuration file). The core SSN system will send back the SSN2MS_ShipVoyage_Res.xml response to the SSN web application which, in turn, will display the result to the SSN Web user: � Notification origin (locode) � Notification type (AIS/MRS) � Next port of call � ETA � Ship’s position (longitude/latitude) � Notification date & time




Use Case “Get Ship’s Voyage”, Continued


Step Action 3 The SSN Web user can sort the columns of the table or ask for getting

the details of the latest ship notification (see Use Case “Get Notification Details”).

Alernative Flow More complex alternatives are described here below, referred to in the Basic Flow

subsection.

Step Action 2a What if there is not any ship notification for the given vessel?

Answer: A status message will indicate that there’s no ship notification for the given vessel.



Requirement

Id Description

�



� The possibility to display the ship’s voyage on a map is still under investigation (using ArcIMS from ESRI).

Assumptions � The ship’s position must have been given in the ship notifications.

Open issues -

Extension Points

� Get Ship Notification Details


��65







� MS2SSN_ShipVoyage_Req: request sent by the data requester � Header: equivalent to the other MS2SSN_..._Req message � Body:

5. SearchCriteria: 1 occurrence 6. IMONumber 7. MMSINumber

� SSN2MS_ShipVoyage_Res: response sent by SSN core system


o SearchCriteria: 1 occurrence � IMONumber � MMSINumber � ShipVoyageResult: 1 occurrence

• AISNotSummary: 0..n occurrences o From (mandatory) o SentAt (Mandatory) o NextPortOfCall o ETA o ShipPosition (mandatory)

� Longitude (mandatory) � Latitude (mandatory) � Timestamp(mandatory)

• MRSNotSummary: 0..n occurrences o From (mandatory) o SentAt (Mandatory) o NextPortOfCall o ETA o ShipPosition (mandatory)

� Longitude (mandatory) � Latitude (mandatory)


��




Web interface UI

The following screen gives an example of a ship’s voyage history:



Use Case “Get Ship’s Cargo Manifest”

Brief Description

This use case enables the SSN Web user to view the latest cargo manifest (if any) of the selected ship. The cargo manifest can be made accessible either as an electronic version on a web server or upon request via phone/fax. Such availability has been notified in the Hazmat notification.

Upon request, SSN will look in its index server whether the existence of the cargo manifest has been previously notified (via a Hazmat notification). If so, two scenarios are possible depending on its availability:

� If the url of the cargo manifest has been given in the Hazmat notification, SSN will return that information to the SSN Web user. Then, the SSN Web user can ask SSN to download the cargo manifest (DOC, HTML, TXT, PDF or XML) from its web location and sent it back for display to the browser-based web application.

� If phone/fax has been given in the Hazmat notification, SSN will merely return that information to the SSN Web user.




“Find Information” from the main menu, has entered her credentials (user name/password), has selected “Ship search”, has accessed Hazmat Details and selects “Cargo Manifest” as sub-function.

Postconditions The information about how to get the cargo manifest is returned. If it is available on

a web server and the SSN web user asks to get it, it will be downloaded by SSN and displayed in the SSN Web user’s browser in its native format.






Use Case “Get Ship’s Cargo Manifest”, Continued



Find Information/Ship Search (as explained in the preconditions), has already selected a ship, obtained Hazmat Notifications and Hazmat Notification details and has selected Cargo Manifest details from within the Hazmat Notification Details.

2 The SSN web application builds and sends the MS2SSN_CargoManifest_Req.xml message to the SSN core system, which will search in its index server for determining how to get the cargo manifest (based on the latest Hazmat notification – if any) for the selected vessel. The core SSN system will send back the SSN2MS_CargoManifest_Res.xml response to the SSN web application which, in turn, will display the result to the SSN Web user: � Notification date & time � Notification type (sitrep, polrep, waste,…) � Notification origin (locode)

3a If the cargo manifest is available from a web server, the SSN system will download it (based on the url given in the Hazmat notification). Once downloaded, it will send back the SSN2MS_CargoManifest_Res.xml response (including the downloaded file base64-encoded) to the SSN web application. The SSN Web application will decode the base64-encoded stream of characters in order to recreate the file. The SSN Web application will then display the size and the type of the cargo manifest and provide a link to display it in another window.

3b If the cargo manifest can only be asked by phone/fax, the SSN system will send back the SSN2MS_CargoManifest_Res.xml response to the SSN web application which, in turn, will display the result to the SSN Web user: � Phone

� Fax 3c If there’s no cargo manifest available (e.g. no hazmat notification), the

SSN system will send back the SSN2MS_CargoManifest_Res.xml response to the SSN web application which, in turn, will display a message indicating the cargo manifest is not available.

Alternative Flow




Step Action 2a What if the file is of a unsupported format?

Answer: it’s the responsibility of the MS to provide a file in the supported format (pdf, doc, html, xml or txt). The same principle applies to the fact that the file must be in English. In other words, SSN will merely display the information it receives from the MS (good or bad). On the web interface, a status message will indicate that an error occurred during file download.

Step Action 2b What if any error (network,…) between the web application and the SSN

core system or between the SSN core system and the web server? Answer: see p.64


Requirement

Id Description

�



Assumptions � The url of the cargo manifest given in the Hazmat notification must be

accessible from the SSN core system.

� For security reasons, the local web server (at the Member State) must be configured to serve HTTPS requests (2 way SSL) only coming from the SSN core system.

Open issues -

Extension Points

-


��65







� MS2SSN_CargoManifest_Req: request sent by the data requester � Header: equivalent to the other MS2SSN_..._Req message � Body:

SearchCriteria: 1 occurrence IMONumber MMSINumber

� SSN2MS_CargoManifest_Res: response sent by SSN core system


o SearchCriteria: 1 occurrence � IMONumber � MMSINumber

o ManifestDetails: 0..1 occurrence � VesselIdentification:1 occurence

• IMONumber • MMSINumber • CallSign • ShipName

� Base64Details: choice with ContactDetails • DocType • Base64Content

� ContactDetails: choice with Base64Details • Fax (mandatory) • Phone (mandatory) • LoCode (mandatory) • EMail • LastName • FirstName





Web interface UI

The following screen gives an example of a cargo manifest available as a file from a web server:




When the SSN web user clicks on the link, the downloaded cargo manifest will be displayed in its native format in a separate window. Here’s an example of an XML version:



Use Case “Get Ship’s Latest Incidents”

Brief Description

This use case enables the SSN Web user to get the list of all incidents (alert notifications) reported for the selected vessel. This list is a table sorted by default from the latest to the oldest received alert notification. All these information are queried from the central SSN index server.




“Find Information” from the main menu, has entered her credentials (user name/password) and has selected “Ship search” and “ship's latest incidents” as sub-function. A ship has also been selected (via ship search or when clicking on an IMO# in another list).

Postconditions The list of the latest incidents notified for the selected vessel is returned.





Find Information/Ship Search (as explained in the preconditions), has already selected a ship and has selected “latest incidents” from the menu.

2 The SSN web application builds and sends the MS2SSN_ShipLatest Incidents_Req.xml message to the SSN core system, which will search in its index server for the latest alert notifications received for the selected vessel. The core SSN system will send back the SSN2MS_ShipLatestIncidents_Res.xml response to the SSN web application which, in turn, will display the result to the SSN Web user: � Notification date & time � Notification type (sitrep, polrep, waste,…) � Notification origin (locode)

3 The SSN Web user can sort the columns of the table or ask for getting the details of the notifications (see Use Case “Get Notification Details”).




Use Case “Get Ship’s Latest Incidents”, Continued

Alternative Flow


Step Action 2a What if there is not any alert notification for the given vessel?

Answer: a message indicating there’s no incident notified will be displayed.



Requirement

Id Description

�



Assumptions -

Open issues � What’s the maximum number of incidents that should be displayed in the list?

Extension Points

� Get Alert Notification Details


��65



Use Case “Get Ship’s Latest Incidents”, Continued




� MS2SSN_ShipLatestIncidents_Req: request sent by the data requester � Header: equivalent to the other MS2SSN_..._Req message � Body:

SearchCriteria: 1 occurrence IMONumber MMSINumber

� SSN2MS_ShipLatestIncidents_Res: response sent by SSN core system


o SearchCriteria: 1 occurrence � IMONumber � MMSINumber � ShipLatestIncidentsResult: 0..1 occurrence

• IncidentNotSummary: 0..n occurrences o From (locode) o SentAt o IncidentType (sitrep, polrep,

waste,…)

Web interface UI

The following screen gives an example of the list of the latest incidents for a given vessel:



Use Case “Get Vessel Information”

Brief Description

This use enables the SSN Web user to view in a separate window the selected ship information from the requested external web site (either Sirenac or Equasis). If no ship was selected before, the home page of the requested external web site (either Sirenac or Equasis) will be shown.

Please note that access to Sirenac is still under negotiation between DG TREN and Sirenac.




“Find Information” from the main menu, has entered her credentials (user name/password) and has selected “Ship search” and “Sirenac” or “Equasis” as sub-function.

Postconditions Information from Sirenac or Equasis is displayed in a separate window.


Same as Use-Case “Get Ship Information”.



Find Information/Ship Search (as explained in the preconditions), and has selected “Sirenac” or “Equasis” from the menu.

2a If the SSN Web user has previously selected a ship (via ship search or by clicking on an IMO# in another table), then the selected vessel information available on Sirenac or Equasis is displayed in a separate window. The SSN Web user can then browse the Sirenac or Equasis site in this separate window.

2b If no ship has been selected before by the SSN Web user, then the default page on Sirenac or Equasis is displayed in a separate window. The SSN Web user can then browse the Sirenac or Equasis site in this separate window.




Use Case “Get Vessel Information”, Continued

Alternative Flow


Step Action 2c What if the access to Sirenac or Equasis is made unavailable (for any

reason such as network problem, login problem,…)?


Requirement

Id Description

�


-

Assumptions � As the access to Sirenac or Equasis will be made via an url containing some

parameters for identifying SSN (user account and password) and for identifying a vessel, any change to the structure of this url must be given in advance by Sirenac or Equasis to the SSN administrator.

� As the access to Sirenac or Equasis will be made via an url containing some parameters for identifying SSN (user account and password), such information should be hidden to the SSN Web user.

Open issues � What are the parameters to specify in the url in order to grant access to Sirenac

and Equasis, and to a particular vessel information?

Extension Points

-

XML interface -




Use Case “Get Vessel Information”, Continued

Web interface UI

The separate window displaying a selected vessel information from Sirenac will look as follows:

The separate window displaying a selected vessel information from Equasis will look as follows:



Use Case “Get Notification Details”

Brief Description

This abstract use case consists of requesting from the data provider the detailed information about a given notification and returning it to the data requester (e.g. for display in the browser-based web application).

Two interfaces should be provided:

� A web interface enabling a web data requester user (SSN Web user) to ask SSN for the detailed information of a given notification. This web application (called NCA simulation system) will internally use the XML interface for requesting the notification details to the core SSN system.

� An XML interface enabling a data requester application to ask SSN for the detailed information of a given notification.

Getting the details of a notification will always be carried out by the core SSN system (on behalf of a data requester’s request) in 3 different ways depending on the capabilities of the data provider and what has been specified at notification time:

� If the data provider does not have any application server (talking XML) nor web server to serve detailed information, then Phone/Fax have been sent to SSN at notification time. In that case, the details of the notification returned by SSN (in the SSN2MS_..._Res.xml message) merely consist of the given phone & fax numbers and the location code of the data provider.

� If the data provider does not have an application server (talking XML) but has a local (national) web server where it may store documents (in pdf, doc,... format) corresponding to the detailed notification, then the url and the type of the document have been sent to SSN at notification time. In that case, SSN will download the document from its url and return it base64-encoded in the SSN2MS_..._Res.xml message. Note that the document must have been created and stored on the web server prior to sending the notification. Note that the domain name given in the url (https://<domain_name>/xyz/abc.doc) must be known and accessible from the SafeSeaNet server (as SSN will try to download it on behalf of a data requester's request).

� If the data provider has implemented the SSN XML Messaging specifications for the corresponding notification type, then it has mentioned it at notification time. In that case, then SSN will ask the data provider for the notification details using the appropriate XML messages.


� NCA Application




Use Case “Get Notification Details”, Continued

Use case Diagram

SSN Web user Get Ship Information


Get (Ship) Voyage History

Search Ship

Get Vessel Info

Get Incident History

NCA appl ication Get Notification Detail

Get Hazmat Notification Detai l Get Port Notification Detai l Get Ship Notification Detail

Get Security Noti fication Detail Get Alert Noti ficatio n Detail

Get Cargo Manifest

Figure 7 –“ Get Notification Details” Use Case Diagram


“Find Information” from the main menu, has entered her credentials (user name/password) and has selected one of the functions/sub-functions (ship/port/area search) that displays a list of notifications with a link/button to ask for their details.

Postconditions The details of the requested notification are returned.


Same as Use-Case “Get Ship Information”.





Activity Diagram

The following activity diagram outlines the process for getting the details of a notification:

Send the request to SSN

Wait for the SSN response

Process the SSN response

<SSN_Tx_Type> can either be:-------------------------------------------------Port (Port Notification Details)Ship (Ship Notification Details)Hazmat (Hazmat Notification Details)Security (Security Notification Details)Alert (Alert Notification Details)

Please note that this NCA application (data requester) could also be the SSN default browser-based web application interacting between the SSN web user and the SSN core system.

Process the request

MS2SSN_<SSN_Tx_Type>_Req

Send the request to Provider

Wait for the Provider's response

Process the Provider's response

Send the SSN response to Requester

Download from Provider's web server

Get Phone/Fax from Index Server

Process the SSN request

SSN2MS_<SSN_Tx_Type>_Req

Send the Provider's response to SSN

<SSN_Tx_Type> can either be:-------------------------------------------------Ship (Ship Notification Details)Hazmat (Hazmat Notification Details)Security (Security Notification Details)Alert (Alert Notification Details)

SSN2MS_<SSN_Tx_Type>_Res

MS2SSN_<SSN_Tx_Type>_...

XML

Url

Phone/Fax

NCA Application (Prov ider)SafeSeaNetNCA Application (Requester)

Figure 8 –“Get Notification Details” activity diagram

Specialized use cases

This abstract use case is specialized by several use cases (based on the different notification type) which basic description is given in the following table:

Use Case Description

Get Port Notification Details

This use case consists of requesting, for a given ship, the details of the latest port notification received by SSN. As the details of a port notification are yet contained in the notification, SSN will get the latest port notification for the given ship from its index server and sent it back to the data requester to the data requester application (e.g. for display in the browser-based web application).





Specialized use cases (continued)

Use Case Description Get Ship Notification Details

This use case consists of requesting, for a given ship, the details of the latest ship notification received by SSN. As the details of a ship notification (AIS or MRS) are held by the data provider, SSN will look in its index server to know how to get the details from the data provider (phone/fax, download or via XML interface) and return the details accordingly (see parent use case for more details) to the data requester application (e.g. for display in the browser-based web application). In the special case of an AIS notification, the data provider should always return to the SSN's request the details of the most up-to-date AIS notification and not the details of the last AIS notification it sent to SSN (maybe 2 hours ago).

Get Hazmat Notification Details

This use case consists of requesting, for a given ship, the details of the latest Hazmat notification received by SSN. As the details of an Hazmat notification are held by the data provider, SSN will look in its index server to know how to get the details from the data provider (phone/fax, download or via XML interface) and return the details accordingly (see parent use case for more details) to the data requester application (e.g. for display in the browser-based web application). As details are provided, the user can asks for cargo manifest information from this point on.

Get Security Notification Details

This use case consists of requesting, for a given ship, the details of the latest Security notification received by SSN. As the details of an Security notification are held by the data provider, SSN will look in its index server to know how to get the details from the data provider (phone/fax, download or via XML interface) and return the details accordingly (see parent use case for more details) to the data requester application (e.g. for display in the browser-based web application).

Get Alert Notification Details

This use case consists of requesting, for a given alert, the details of this alert notification received by SSN. As the details of an Alert notification are held by the data provider, SSN will look in its index server to know how to get the details from the data provider (phone/fax, download or via XML interface) and return the details accordingly (see parent use case for more details) to the data requester application (e.g. for display in the browser-based web application). Note that the identification of an alert notification is based on the combination of the following elements: Locode having sent the alert notification + incident type (sitrep, polrep, waste, lost/found containers, others) + notification date & time (UTC format). Taking into account the size of the XML information (and the effort it would take for the Member States to develop them), the European Commission recommends in a first step that the Member States (data provider) should make their alert messages available as Word documents (.doc) on a web server and not in XML (using the MS2SSN_Alert_Res.xml message).

Get Cargo Manifest See Use Case “Get Ship’s Cargo Manifest”





Basic Flow SafeSeaNet should supply a default browser-based web interface and an XML

interface (for EAI). The XML interface will be used by NCA application but also by the default SSN web application when processing requests coming from the web interface.

Step Action

1 The SSN web user clicks on the link/button in order to get the details of a particular notification (port, ship, hazmat, security, alert).

2 The SSN web application prepares the corresponding XML message (MS2SSN_..._Req.xml) and sends it to the SSN core system. If the user was the NCA application, its involvement in the use case starts here by preparing the corresponding XML message (MS2SSN_..._Req.xml) and sending it to the SSN core system.

3 The SSN core system returns an ACK to the caller (HTTP 202 closing the HTTPS connection). Then, it will check the validity of the XML message, check that the caller has the right for requesting the details of that notification, then checks how the details of the notification can be requested (phone/fax, download from a web server or via XML interface).

4a If the details can only be requested via phone/fax, the SSN core system returns the phone/fax numbers in the corresponding XML message (SSN2MS_..._Res.xml) to the data requester, which should return an ACK to SSN (HTTP 202 closing the HTTPS connection).

4b If the details consist of a file on a web server, the SSN core system will download the file from the given url, base64-encode it in the corresponding XML message (SSN2MS_..._Res.xml) and send this XML message to the data requester (up to the data requester to base64-decode the stream of characters to recreate the file) which should return an ACK to SSN (HTTP 202 closing the HTTPS connection).

4c If the details can only be requested via the XML interface, the SSN core system builds and sends the corresponding XML message (SSN2MS_..._Req.xml) to the data provider. The data provider returns an ACK to the caller (HTTP 202 closing the HTTPS connection). Then, it processes the SSN request, builds and sends the corresponding XML response (MS2SSN_..._Res.xml) to the SSN core system. The SSN core system returns an ACK to the data provider (HTTP 202 closing the HTTPS connection). Then, it will check the validity of the XML response, correlate to the initial request, build and send the corresponding XML response (SSN2MS_..._Res.xml) to the data requester which should return an ACK to SSN (HTTP 202 closing the HTTPS connection).

5 The SSN Web user will always see the details of the requested notification in a separate window.





Alternative Flow


Step Action 2a What if any error (network,…) between the web application and the SSN

core system? Answer: see p.64

3a What if the requested notification doesn’t exist? Answer: in the case of the web interface, a message will be displayed indicating that the notification details cannot be found. In the case of the XML interface, NotFound will be returned as StatusCode.

4b1 What if the file doesn’t exist on the web server? Answer: in the case of the web interface, a message will be displayed indicating that the notification details cannot be found. In the case of the XML interface, NotFound will be returned as StatusCode.


Requirement

Id Description

�


�

Assumptions � The url of the file containing the notification details must be accessible from the

SSN core system.

� For security reasons, the local web server (at the Member State) must be configured to serve HTTPS requests (2-way SSL) only coming from the SSN core system.

� These files should be created in either of the following formats: pdf, doc, html, xml, txt. The Web user must have the corresponding viewer (Acrobat Reader,…) installed in her browser.

Open issues -

Extension Points

-


��65




XML interface Please refer to the “Get Notification Details” chapter in the XML Messaging


Web interface UI

The details of a Port notification (retrieved using the XML interface) could be the following:

The details of a Ship (AIS) notification (retrieved using the XML interface) could be the following:






The details of a Ship (MRS) notification (retrieved using the XML interface) could be the following:

The details of a Hazmat notification (retrieved using the XML interface) could be the following:






The details of a Security notification (retrieved using the XML interface) could be the following:

The details of an Alert notification (downloaded as a file) could be the following:



Use-Case “Get Port Information”

Brief Description

This use case enables the SSN web user to get the list of all vessels bound to a specific port (based on previously received port, ship and hazmat notifications). The information displayed highly depends on the user's access right (only Port Authorities, Port State Control and National Competent Authorities may have access to this function):

� Port Authorities may only see all the ships going to call their port.

� NCA may see the vessels bound for all ports within its country. Therefore, a combo box will also give the possibility to select a specific National port in order to get the list of all vessels going to call that specific port.

The list of notifications having mentioned the port as next port of call is displayed for each vessel bound for the corresponding port. The details of these notifications can also be requested.

Use Case Diagram

SSN Web user Get Port Info Get User Data

Get Latest ETA Notifications


Figure 9 –“ Get Port Information” Use Case Diagram



“Find Information” from the main menu, has entered her credentials (user name/password) and has selected “Port search”.

Postconditions The list of all vessels going to call the ports the user is allowed to see (depending on

her access rights) is displayed.


This use case is one of the major use cases as it enables the different port authorities (and NCAs) to get the list of all vessels going to call their port(s) in the coming hours/days.




Step Action

1 The SSN web user is logged on the SSN Web application and has selected Find Information/Port Search (as explained in the preconditions).

2 The SSN web application builds and sends the MS2SSN_PortSearch_Req.xml message to the SSN core system, which will check the validity of the XML message, check whether the SSN Web user has the required access rights. If so, it will search in its index server for the list of all ports the SSN Web user has access to. Based on that list of ports, it will search in its index server the list of all vessels going to call the port(s) (based on the latest port, hazmat and ship notifications having mentioned this port as next port of call). The core SSN system will send back the SSN2MS_PortSearch_Res.xml response to the SSN web application which, in turn, will display the result to the SSN Web user.

3 The SSN Web user can sort the columns of the table, expand or collapse the information for a vessel, click on an IMO# to go to the ship search functionalities for the selected vessel (see Use-Case “Get Ship Information”). Depending on the user’s access rights, the SSN Web user can also select another port from the combo box to view the list corresponding to that selected port. or ask for getting the details of the notifications (see Use Case “Get Notification Details”).

Alternative Flow


Step Action


Requirement

Id Description



10-Sept-04 - Page 100

Use-Case “Get Port Information”, Continued


-

Open issues -

Extension Points

-




� MS2SSN_PortSearch_Req: request sent by the data requester � Header: equivalent to the other MS2SSN_..._Req message � Body:

SearchCriteria: 1 occurrence LoCode (mandatory):

location code of the port for which information is requested. Should be the locode of the Web user (except if NCA). If empty: return information about all the ports belonging to the NCA (only allowed if the Web user is a NCA).

� SSN2MS_PortSearch_Res: response sent by SSN core system


o SearchCriteria: 1 occurrence � LoCode

o PortSearchResult: 0..1 occurrence � Port: 1..n occurrences

• AnnouncedVessel: 0..n occurences o IMONumber (mandatory) o ShipName (mandatory) o NextPortOfCallNotifications: 1 occ.

� PortNotSummary: 0..1 occ. � AISNotSummary: 0..1 occ. � MRSNotSummary: 0..1 occ. � HazmatNotSummary: 0..1

occ.

See p.70 for more details about <xxx>NotSummary elements. ��71


10-Sept-04 - Page 101



10-Sept-04 - Page 102

Use-Case “Get Port Information”, Continued

Web interface UI

The following screen is an example of a list of vessels going to call Belgian ports and returned to the SSN Belgian NCA user (who has access to all the Belgian ports):


The following screen is an example of a list of vessels going to call the port of Antwerp and returned to the SSN Web user defined as port authority of Antwerp (who has only access to her port of Antwerp):


10-Sept-04 - Page 103

Use-Case “Get Area Information”

Brief Description

This use case enables the SSN Web user to get, per geographical area and incident type, the lists of all notified incidents (based on previously received alert notifications):

� A first list gives all the notified incidents per identified vessel.

� A second list gives all the notified incidents for non identified vessels.

The information displayed highly depends on the user's access rights (only Coastal Stations and National Competent Authorities may have access to this function) and their location in geographical areas. For instance, a French user may see the list of incidents notified in the "North Sea and Channel", "Atlantic" and "Western Mediterranean Sea" areas. A Swedish user may only see the list for the "Baltic" area.

Geographical areas are:

� Baltic: Finland, Sweden, Germany, Denmark and Poland, Lithuania, Latvia, Estonia

� North Sea and Channel: Sweden, Denmark, Norway, UK, Germany, Netherlands, Belgium, France

� Atlantic: UK, Ireland, France, Spain, Portugal

� Western Mediterranean Sea: Spain, France, Italy and Malta

� Eastern Mediterranean Sea: Italy, Greece, Cyprus and Malta

� European Union: All Member States

Use Case Diagram

SSN Web user Get Area Info Get User Data

Get Alert Notifications for Area(s)

Get Alert Notification DetailGet Ship Latest Notifications

Figure 10 –“ Get Area Information” Use Case Diagram




10-Sept-04 - Page 104

Use-Case “Get Area Information”, Continued


“Find Information” from the main menu, has entered her credentials (user name/password) and has selected “Area search”.

Postconditions The selected list of incidents (identified or non identified vessels) per geographical

area is displayed to the SSN Web user (depending on her access rights).


This use case is one of the major use cases as it enables the different actors (essentially coastal stations and NCAs) to get the list of all incidents notified per geographical areas.


Step Action

1 The SSN web user is logged on the SSN Web application and has selected Find Information/Area Search (as explained in the preconditions) and has selected an incident type for either “identified ships” or “non identified ships”

2 The SSN web application builds and sends the MS2SSN_AreaSearch_Req.xml message to the SSN core system, which will check the validity of the XML message, check whether the SSN Web user has the required access rights. If so, it will search in its index server for the list of all areas the SSN Web user has access to. Based on that list of areas, it will search in its index server the list of all incidents of the selected type (related to ships or not depending on the selected function) and sort it per geographical area (based on the alert notifications). The core SSN system will send back the SSN2MS_AreaSearch_Res.xml response to the SSN web application which, in turn, will display the result to the SSN Web user.

3 The SSN Web user can sort the columns of the table, expand or collapse the information for a vessel, click on an IMO# to go to the ship search functionalities for the selected vessel (see Use-Case “Get Ship Information”), ask for getting the details of an alert notification (see Use Case “Get Notification Details”).

Alternative Flow


Step Action 2a What if the SSN Web user has not the appropriate access rights?



10-Sept-04 - Page 105



-

Requirement

Id Description


-

Open issues -

Extension Points

-




� MS2SSN_AreaSearch_Req: request sent by the data requester � Header: equivalent to the other MS2SSN_..._Req message � Body:

8. SearchCriteria: 1 occurrence 9. IncidentType (sitrep, polrep, waste,…) 10. ShipIdentified (Yes; No)


��


10-Sept-04 - Page 106



� SSN2MS_AreaSearch_Res: response sent by SSN core system � Header: equivalent to the other SSN2MS_..._Res message � Body:

o SearchCriteria: 1 occurrence � LoCode

o AreaSearchResult: 0..1 occurrence � Area: 1..n occurrences

• AreaName (mandatory) • ShipIdentified: 1..n occ.

o IMONumber o ShipName o IncidentNotSummary: 1 occ.

� From (mandatory) � SentAt (mandatory) � IncidentType (mandatory)

• ShipNotIdentified: 1..n occ. o ContactIdentification: 1 occ.

� LoCode (mandatory) � Phone (mandatory) � Fax (mandatory) � EMail � MaritimeAuthority

(mandatory) o IncidentNotSummary: 1 occ.

� From (mandatory) � SentAt (mandatory) � IncidentType (mandatory)



10-Sept-04 - Page 107


Web interface UI

The following screen is an example of a list of notified SITREP incidents for identified ships returned to a French user (who has access to North Sea and Channel, Atlantic and Western Mediterranean Sea areas:

The following screen is an example of a list of notified POLREP incidents for not identified ships returned to a Norwegian user (who has only access to the Baltic area):


10-Sept-04 - Page 108

Section 2.3 - Use Case Package “SSN Statistics”

Overview

Introduction This section describes the use cases related to the “SSN Statistics” package. The

following diagram lists the use cases of this package:

NCA Administrator

(f rom Actors)

SSN Administrator

(f rom Actors)

Login

(from Included Use Cases)

Generate Statistics

Browse Statistics

SSN Database

(f rom Actors)

Figure 11 –Use Case Package “SSN Statistics”


Topic See Page Use-Case “Generate Statistics” 109 Use-Case “Browse Statistics” 112

��113


10-Sept-04 - Page 109

Use-Case “Generate Statistics”

Brief Description

This use case consists of generating (weekly, monthly and/or yearly basis) some usage statistics for every SSN user, for a Member State (gathering the usage statistics of all SSN users belonging to the Member State), for the SSN Administrator (gathering the usage statistics for all SSN users & Member States).

Such usage statistics should be made available as a web-based interface.

The usage statistics should give information about:

� Amount of notifications sent over a time period (start and end-date), for a country, by a particular authority (locode), for an authority type and for a notification type.

� Amount of requests sent over a time period (start and end-date), for a country, by a particular authority (locode), for an authority type and for a notification type.

� Amount of notifications for each country, for each authority, for each authority type and each notification type. Graphically presented according to criteria like:

o grouped by country

o grouped by message type

o grouped by authority type

o for each country, grouped by message type

o for each message type, grouped by country

o for each authority type, grouped by country

� Amount of requests for each country, for each authority, for each authority type and each notification type. Graphically presented according to criteria like:






� for each authority type, grouped by country

Primary Actor � SSN core system

Preconditions User should have enough access rights

Postconditions Statistics are generated.



10-Sept-04 - Page 110

Use-Case “Generate Statistics”, Continued


Statistics are a major measurement tool for identifying potential problems, assessing the overall usage of the system.


Step Action

1 Generation of statistics is on-demand through the SSN Management Console interface.

Alternative Flow

Step Action


Requirement

Id Description


-

Assumptions -

Open issues � Should usage statistics be provided to any SSN Web user or only to NCA-typed

one and SSN Administrator? Answer: the usage of statistics should only be limited to the NCA and the SSN Administrator (EMSA).



10-Sept-04 - Page 111

Use-Case “Generate Statistics”, Continued

Extension Points

- Browse Statistics


10-Sept-04 - Page 112

Use-Case “Browse Statistics”

Brief Description

This use case consists of allowing a SSN Web user to browse, via a secure Web interface, the usage statistics report corresponding to her privileges.

The SSN Management Console which is only accessible to NCA Admin and EMSA staff has the ability to view and generate statistics (on-demand).

What can be viewed are statistics generated and presented according criteria described in the Use Case: Generate Statistics.

� Amount of notifications sent over a time period (start and end-date), for a country, by a particular authority (locode), for an authority type and for a notification type.

� Amount of requests sent over a time period (start and end-date), for a country, by a particular authority (locode), for an authority type and for a notification type.

� Amount of notifications for each country, for each authority, for each authority type and each notification type. Graphically presented according to criteria like:







� Amount of requests for each country, for each authority, for each authority type and each notification type. Graphically presented according to criteria like:







Primary Actor � NCA Admin, EMSA Staff

Preconditions The Web user has access to the SSN browser-based web interface.

Postconditions Statisctics are presented and available for printing.


10-Sept-04 - Page 113


Statistics are a major measurement tool for identifying potential problems, assessing the overall usage of the system,… .


Step Action

1 NCA Admin or EMSA staff member logs on and is recognized as such. SSN Management Console provides access to the appropriate menu items.

2 NCA Admin or EMSA staff member selects statistics type (notifications, requests, notification summary or request summary)

3a For notifications and requests SSN Management Console presents a start and end date field and 4 criteria fields called Country, Authority, Authority Type, and Notification Type. Default value for each of those 4 fields is All, meaning no limitations in the search request. The amount of options in the Country and Authority fields will be limited for NCA Admins.

3b For notification summary and request summary SSN Management Console presents the results immediately in table and graphical form.

4a After entering the criteria fields the NCA Admin or EMSA staff member can generate the statistics or press reset to re-enter his criteria.

5a SSN Management Console executes the query and presents the results in table form.

6 NCA Admin or EMSA staff member can restart by entering new search criteria or by selecting a new statistics type.

Alternative Flow

Step Action 5b SSN Management Console executes query and no results are presented. 6b NCA Admin or EMSA staff member changes criteria and restart his

query.


Requirement

Id Description



10-Sept-04 - Page 114

Use-Case “Browse Statistics”, Continued


-

Assumptions -

Open issues � Should usage statistics be provided to any SSN Web user or only to NCA-typed

one and SSN Administrator? Answer: see p.110

Extension Points

-

��111


10-Sept-04 - Page 115

Section 2.4 - Use Case Package “Location Codes Management”

Overview

Introduction This section describes the use cases related to the “Location Codes Management”

package. The following diagram lists the use cases of this package:

Search a LoCode

Add a LoCode

Remove a LoCode

Edit a LoCode

Manage Location CodesSSN Administrator

(from Actors)

Figure 12 –Use Case Package “Location Codes Management”


Topic See Page Use-Case “Manage Location Codes” 116

��117


10-Sept-04 - Page 116

Use-Case “Manage Location Codes”

Brief Description

This CRUD use case enables the SSN Administrator to manage the list of location codes involved in SafeSeaNet. Such management consists of searching, editing, adding or removing location codes in the SSN database.

A location code is a standard way for representing locations in transportation sectors (rail, maritime,…). It consists of a 2 letter country code (according to ISO 3166) followed by a three letter city code. Some examples are:

Location Code Description

BEANR Antwerpen (Belgium) BEZEE Zeebrugge (Belgium) FRDKK Dunkerque (France) FRLEH Le Havre (France) LVRIX Riga (Latvia)

NLAMS Amsterdam (Netherlands) NLRTM Rotterdam (Netherlands) PTLIS Lisboa (Portugal)

Primary Actor � SSN Administrator

Preconditions The SSN Administrator has access to the SSN Management Console web interface

for managing the location codes (add, remove, edit, search).

Postconditions The SSN Administrator has managed the location codes.


Location codes are used to identify the location of any user or authority involved in SafeSeaNet as well as the next port of call for vessels.

Basic Flow

Step Action

1 EMSA staff member logs on and is recognized as such. SSN Management Console provides access to the appropriate menu items.

2a EMSA staff member selects create Location 2b EMSA staff member selects search/update Location 3a SSN Management Console presents the required fields to create a new

location code like Country, Authority Code, Authority Name, Latitude, Longitude, phone and fax. Besides latitude and longitude are fields are mandatory.

3b SSN Management Console presents the Country list box.


10-Sept-04 - Page 117

4a EMSA staff member select country. SSN Management Console presents the already existing location codes so the user does not create twice the same location code.

4b EMSA staff member selects the country for which he wants to obtain the existing location codes

5a EMSA staff member enters all mandatory fields and clicks on create location code.

5b EMSA staff member clicks on reset. All fields are cleared. 5c SSN Management Console presents the existing location codes and city

name. 6a SSN Management Console creates new location code and informs the

user at the bottom of the screen that the location code is added. 6b EMSA staff member selects the location code he wants to modify 7 SSN management Console present all relevant fields of the location and

greys out those that are not editable. It is not possible to delete an existing location code, but it is possible to de-activate a location code.

8a EMSA staff member makes modifications and saves changes. 8b EMSA staff member makes modifications but resets them. 9a SSN Management Console indicates that changes are stored.

Alternative Flow

Step Action 1b EMSA staff member has no access rights or uses wrong user id and/or

password. SSN Management Console informs user that he is not recognized by the system.

4c EMSA staff member creates new Location but enters existing location information in fields. SSN Management Console will inform EMSA staff member at saving of the location information that the location already exists. No new location will be created.


Requirement

Id Description


-

Assumptions � The Member States should provide their list of location codes (and geographical

coordinates in terms of latitude and longitude) involved in SSN. The list of all gathered location codes will be the official list supported by SafeSeaNet.


10-Sept-04 - Page 118

Open issues � Should SSN only use the location codes related to the EC or should it support other locodes from countries next to the EC, like Russia, North Africa,…)?

� What about the location codes of the new Member States (EC enlargement)?

Extension Points

-

Object Model The following diagram outlines the structure of the information around the “location

codes” concept:

LocationCode

LoCode : stringCountryCode : stringCityCode : stringCityName : stringLongitude : longLatitude : long

CountryCode

CountryCode : stringCountryName : string

10..n

'UNKWN' is a special location code that needs to be def ined. It's gonna be used to indicate the next port of call is unknown.Country Code: 'UN' (Country Name: 'Unknown')City Name: 'KWN' (City Name: 'Unknown')

Web interface UI


10-Sept-04 - Page 119

Section 2.5 - Use Case Package “Vessel Information Management”

Overview

Introduction This section describes the use cases related to the “Vessel Information Management”


Add a Vessel Information Edit a Vessel Inform ation

Get Vessel Information

(from Ship Reporting)

Search a Vessel

Remove a Vessel Information

Manage Vessel InformationSSN Administrator

(from Actors)

Figure 13 –Use Case Package “Vessel Information Management”


Topic See Page Use-Case “Manage Vessel Information” 120

��121


10-Sept-04 - Page 120

Use-Case “Manage Vessel Information”

Brief Description

This CRUD use case enables the SSN Administrator to manage the list of vessels involved in SafeSeaNet. Such management consists of searching, editing, adding or deactivating vessel information in the SSN database.

SSN will manage its own database of vessels. An initial upload will be carried out based on an Excel file containing the list of all the vessels currently identified in the European seas (to be provided by DG TREN). This database will be updated every time a notification is received with the vessel information transmitted in the notification:

� If the sender does not know the IMO# the notification is stored under the provided MMSI# on the condition that the MMSI# is recognized. If not, system will warn sender that a new vessel will be created (if using the Web UI), or the new vessel will be created automatically (if using the XML interface). Such a vessel will be considered incomplete.

� If the sender does not know the MMSI# the notification is stored under the provided IMO# on the condition that the IMO# is recognized. If not, system will warn sender that a new vessel will be created (if using the Web UI), or the new vessel will be created automatically (if using the XML interface). Such a vessel will be considered incomplete.

� If the sender knows IMO# and MMSI# but MMSI# is different than the one linked with the IMO#, a vessel update will take place.

� If the sender knows IMO# and MMSI# but IMO# is different than the one linked with the MMSI#, the vessel is not updated. If another vessel exists with the correct IMO# but another MMSI# then we trigger the previous case.

Searching and updating of vessels can be simplified by selecting the incomplete vessel checkbox.


Preconditions The SSN Administrator has access to the SSN internal web application for managing

the vessel information (add, remove, edit, search).

Postconditions The SSN Administrator has managed the vessel information.


It’s not the SSN objective to collect all the information about all the vessels sailing on the European seas (other external systems like Lloyds database, Equasis, Sirenac do exist for that). Nevertheless, SSN needs to maintain some basic information about the vessels in order to provide them to the SSN Web user as visual check prior to sending a notification (see Use Case “Send Notifications”).



10-Sept-04 - Page 121

Use-Case “Manage Vessel Information”, Continued

Basic Flow

Step Action

1 EMSA staff member logs on and is recognized as such. SSN Management Console provides access to the appropriate menu items.

2a EMSA staff member selects Create Vessel 2b EMSA staff member selects Search/Update Vessel 3a SSN Management Console presents four vessel fields: IMO, MMSI,

Ship Name and Call Sign where only the first is mandatory. 3b SSN Management Console presents four search fields: IMO, MMSI,

Ship Name and Call Sign with 3 additional checkboxes to narrow down the search: incomplete vessels, banned vessels, active vessels.

4a EMSA staff member enters vessel information and creates the vessel or selects reset to delete the just entered information.

4b EMSA staff member enters search criteria with or without wildcard and with or without activated checkboxes. EMSA staff member clicks search button on resets on entered information.

5a SSN Management Console informs user that the vessel is created. 5b SSN Management Console presents the vessels found. 6b EMSA staff member select the vessel to update. 7b SSN Management Console presents the four vessel fields with latest

modification date and modifier. The latter two and IMO are greyed out. 8b EMSA staff member modifies the presented data; (de)activates the

vessel, or makes it a banned vessel. He updates the vessel or undoes his changes through reset.

9b SSN Management Console informs the user that the vessel is updated.

Alternative Flow



5c SSN Management Console informs that the newly created vessel already exists and no new vessel is created.

9c SSN Management Console informs that the update vessel matches an exiting vessel and no change is made.


Requirement

Id Description


10-Sept-04 - Page 122


-

Assumptions -



Extension Points

-



10-Sept-04 - Page 123

Use-Case “Manage Vessel Information”, Continued

Object Model The following diagram outlines the structure of the information around the “vessel

information” concept:

Vessel

IMONumber : stringMMSINumber : stringCal lSign : stringShipName : stringLastModifiedAt : DateTimeLastModifiedBy : string

VesselHistory

IMONumber : stringMMSINumber : stringCal lSign : stringShipName : stringArchivedAt : DateTimeLastModifiedAt : DateTimeLastModifiedBy : string

1 0..n

VesselHistory is used to archive the current vessel information of a given IMO# or MMSI# when it is modified by a notification.

The idea is to issue a daily report of all vessels for which information has been modified through notifications. The SSN Administrator (EMSA) will check these modifications and eventually correct them.

Web interface UI


10-Sept-04 - Page 124

Section 2.6 - Use Case Package “SSN Download Area”

Overview

Introduction This section describes the use cases related to the “SSN Download Area” package.

The following diagram lists the use cases of this package:

NCA Administrator

(f rom Actors)

SSN Web User

(f rom Actors)

Download Templates

Figure 14 –Use Case Package “SSN Download Area”


Topic See Page Use-Case “Download Templates” 125

��126


10-Sept-04 - Page 125

Use-Case “Download Templates”

Brief Description

This use case aims at providing the SSN Web users with default template documents (Word format) corresponding to the different notifications details and alert notifications details.


Preconditions The actor has access to the SSN browser-based web interface.

Postconditions The actor has downloaded the requested document.


The templates for the different notification details are useful for the different Member States having not yet implemented the XML interface so that they can create documents corresponding to the notification details and store them on a local web server (accessible for download from the central SSN system on behalf of a data requester’s request – see Use Case “Get Notification Details”).

Basic Flow The basic flow is the following:

Step Action

1 The SSN web user clicks on the “Download templates” button in the home page or in the main menu. The web page providing links to the different “Word” templates is displayed.

2 The SSN Web user clicks on the link of the document he’d like to download. The browser asks him to either open or save the document. He should choose ‘Save’ to download and save the document on his workstation.


Requirement

Id Description


-



10-Sept-04 - Page 126

Use-Case “Download Templates”, Continued

Assumptions � The templates will be only supplied in MS Word format and in English.

Open issues � Should these links be provided via HTTPS or HTTP?

Extension Points

-

XML interface None.

Web interface UI

The screen displaying the links to the different “Word” templates is the following:


10-Sept-04 - Page 127

Section 2.7 - Use Case Package “SSN User Management”

Overview

Introduction This section describes the use cases related to the “SSN User Management” package.

The following diagram lists the use cases of this package:

Add a New User

Search for a User

Edit User Information

Remove a User

Manage UsersSSN Administrator

(from Actors)

Figure 15 –Use Case Package “SSN User Management”


Topic See Page Use-Case “Manage Users” 128

��129


10-Sept-04 - Page 128

Use-Case “Manage Users”

Brief Description

This CRUD use case enables the SSN and NCA Administrators to manage the list of users allowed to interact with SafeSeaNet. Such management consists of searching, editing, adding or removing users in the SSN database.

A SSN user stands for a Member State’s authority located at a given location code and playing a single SSN role (except for the SSN Administrator who will be an EMSA representative).

The NCAs of the Member States (via the NCA Administrators) should be able to manage their own users via a web interface (add, edit, delete, change password). The SSN Administrator may manage any user for any Member State.

The information collected is extended to include role, location, data provider and data requester url, phone and fax and network connection type (internet or TestA).


� NCA Administrator

Preconditions The SSN or NCA Administrator has access to the SSN internal web application for

managing the users (add, remove, edit, search).

Postconditions The SSN or NCA Administrator has managed the users.


For security reasons, only the SSN and NCA Administrators will be allowed to manage the users in the SSN database. Every NCA Administrator may only manage users for her Member State. The SSN Administrator may manage any user.

Basic Flow

Step Action


2a NCA Admin selects Create User. SSN Management Console presents user fields with a limited set of location codes to choose from (limited to the NCA’s country) and a limited set of roles to choose from (no SSN Admin, or full access rights)

2b EMSA staff member selects Create User. SSN Management Console presents user fields with a complete list of location codes and list of roles.

2c NCA Admin or EMSA staff member selects Search/Update User. SSN Management Console presents user search fields: userid, last name, first name, phone, fax, email, location code and role.


10-Sept-04 - Page 129

3a NCA Admin or EMSA staff member enters a value in all mandatory fields. Selecting Create User will create the new user, selecting Reset will undo all information entered so far.

3b NCA Admin or EMSA staff member enters search criteria and clicks Search to start looking for users, or clicks reset to undo all entered search criteria.

4a SSN Management Console checks if all mandatory fields are filled in and confirms the creation of the new user.

4b SSN Management Console presents the users found matching the search criteria. An NCA Admin will only obtain users he is managing; an EMSA staff member is not restrained by country.

5b NCA Admin or EMSA staff member selects the user he wants to update. SSN Management Console presents the user details.

6b NCA Admin or EMSA staff member enters new data in the user fields or (de)activates the user in question. Afterwards he selects Update User or enters Reset to undo his latest changes.

7b SSN Management Console checks if all mandatory fields are filled in and confirms the update of the user.

Alternative Flow



4c SSN Management Console detects missing information and informs the user. No user creation is made.

4d SSN Management Console has not found any user matching the search criteria. NCA Admin or EMSA staff have to perform a new search.

7c SSN Management Console detects missing information and informs the user. No user update is made.



10-Sept-04 - Page 130

Use-Case “Manage Users”, Continued


-

Assumptions -

Open issues � Should the userid be the concatenation of the locode and the role played by the

user (e.g. BEZEENCA for Belgian NCA based in Zeebrugge) or something totally different? Answer: the user id must be the concatenation of the Locode and the role played by the user (e.g. BEZEENCA for Belgian NCA based in Zeebrugge), it is mandatory, nothing else could be accepted.

� What about changing the password? Shouldn’t this be allowed via the browser-based web interface? Answer: The NCA should be allowed to change the user's password via the browser-based web user interface.

Extension Points

-

Object Model The following diagram outlines the structure of the information around the “user &

role” concept:

LocationCode

LoCode : stringCountryCode : stringCityCode : stringCityName : stringLongitude : longLatitude : long

SSNRole

RoleId : stringRoleName : string

The f ollowing roles should be supported:POR: Port AuthorityCST: Coastal StationPSC: Port State ControlNCA: National Competent AuthorityOTH: Others (???)ADM: Administrator (SSN Admin only )

SSNUser

UserId : stringRoleId : stringLoCode : stringLastName : stringFirstName : stringPassword : string

0..n 1

0..n

1



10-Sept-04 - Page 131

Use-Case “Manage Users”, Continued

Web interface UI


10-Sept-04 - Page 132

Section 2.8 - Use Case Package “SSN Authorization Management”

Overview

Introduction This section describes the use cases related to the “SSN Authorization Management”


Set a User's access rights Edit a User's Access Rights

Manage Users' Access RightsSSN Administrator

(from Actors)

Figure 16 –Use Case Package “SSN Authorization Management”


Topic See Page Use-Case “Manage User’s Access Rights” 133

��134


10-Sept-04 - Page 133

Use-Case “Manage User’s Access Rights”

Brief Description

This CRUD use case enables the SSN and NCA Administrators to manage the user’s access rights. Such management consists of setting or editing the user’s access rights.

User’s access rights consist of defining whether a user may or not have access to some SSN functionalities (provided via the XML or web-based interface).

The NCAs of the Member States (via the NCA Administrators) should be able to manage the access rights of their own users via a web interface (add, edit). The SSN Administrator may manage access rights for any user for any Member State.

Access rights are grouped according to major activities like:

• Search

• Administration

• Send Notifications

• Notifications Details

Default settings are defined according to pre-defined roles, meaning each role corresponds with a default value for each of the access rights. Each NCA Admin can decide for himself to minimize the access rights for a particular role. NCA Admin or EMSA staff member can decide to introduce a new role with its own default

Access Rights The following table gives an overview of the default access rights based on the SSN

roles:

Port Search

Port Ship Hazmat Security Port Hazmat Security Latest Notif. Voyage Cargo Manifest Latest Incidents

Roles

SIT

RE

P

PO

LRE

P

Was

te

L/F

Con

tain

ers

Oth

ers

MR

S

AIS

SIT

RE

P

PO

LRE

P

Was

te

L/F

Con

tain

ers

Oth

ers

POR Y Y Y Y Y Y Y Y Y Y¹ Y¹ Y¹ Y¹ Y³ N N Y N N ? ? Y¹ ? Y¹CST Y Y Y Y Y Y Y Y Y Y Y Y Y Y³ Y Y Y Y Y ? ? ? ? Y/NPSC Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y ? ? ? ? YNCA Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y ? ? ? ? YADM Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y YOTH N² N² N² N² N² N² N² N² N² Y Y Y N Y Y Y Y Y Y ? Y N ? Y

Information Requests (Web only)Ship Search

Send Notifications (Web/XML)

Alert

Information Requests (Web/XML)

ShipNotification Details

Alert

³ To be confirmed (such authoritiesmay have not yet been defined).

? What are the allowed access rights ??? Especially for the Port Authorities (POR), what kind of ship information may they see and may NOT see (depending on next port of call???) ?

¹ If the Port Authority is the next port of call

² The granting of an access right would have to be decided on a case by case basis, depending notably on the relevance of the information for the authority or body concerned, and taking into account protection of confidentiality.


Preconditions The SSN or NCA Administrator has access to the SSN internal web application for

managing the user’s access rights (add, edit).

Postconditions The SSN or NCA Administrator has managed the user’s access rights and roles.


10-Sept-04 - Page 134


For security reasons, only the SSN or NCA Administrators will be allowed to manage the user’s access rights in the SSN database, Every NCA Administrator may only manage user’s access rights for the users of her Member State. The SSN Administrator may manage any user’s access rights for any user.



10-Sept-04 - Page 135

Use-Case “Manage User’s Access Rights”, Continued

Basic Flow

Step Action


2a NCA Admin or EMSA staff member selects Create Role. SSN Management Console presents fields for role creation and the complete list of access rights.

2b NCA Admin or EMSA staff member selects Search/Update Role. SSN Management Console presents list of existing roles and role description. For each role selected the corresponding access rights are presented.

3a NCA Admin or EMSA staff member enters role information and access rights. Selects Create Role to create the new role or selects Reset to undo latest input.

3b NCA Admin or EMSA staff member modifies access rights for a selected role. Selects Update Role to save modifications or selects Reset to undo latest input.

4a SSN Management Console informs the user that the new role has been created.

4b SSN Management Console informs the user that the access right changes have been saved.

Alternative Flow




� Each role (POR, CST, PSC, NCA, ADM) is assigned a default set of access rights. This default set of access rights stands for the maximum privileges allowed for the role. When a user is created, it’s assigned a role. Then, the default access rights for the assigned role is granted to the user. The SSN or NCA administrators may modify these access rights by removing some privileges but NEVER by setting the privileges above the default ones defined for the role played by the user.

� Setting the access rights higher than the default values requires the creation of a new role.

Open issues -


10-Sept-04 - Page 136

Extension Points

-

Object Model

Web interface UI


10-Sept-04 - Page 137

Section 2.9 - Use Case Package “SSN Monitoring & Polling”

Overview

Introduction This section describes the use cases related to the “SSN Monitoring & Polling”


NCA Application

(from Actors)

Send Polling Request

Figure 17 –Use Case Package “SSN Monitoring & Polling”


Topic See Page Use-Case “Send Polling Request” 138

��139


10-Sept-04 - Page 138

Use-Case “Send Polling Request”

Brief Description

This use case consists of sending, at regular interval, a polling request to the NCA applications in order to check whether they are still alive.

A polling request is an action that sends a pre-defined XML message to a Data Provider URL. The list of Data Provider URL is stored in the database.


Preconditions Triggers are defined to send such polling request at regular basis. This is

configurable through the polling configuration file.

Postconditions The polling results (Ok or Failed) are logged in the database.


Checking at regular interval that the Member States systems are still alive allows reacting proactively to some failures.

Basic Flow

Step Action

1 SSN Administrator launches the polling process 2 This process will retrieve the list of Data provider URL from the

database 3 Based on the list, the polling process will try to send a pre-defined XML

message to each Data provider URL (or one after the other) 4 Each result (Ok or Failed) is stored in the database with the

corresponding request time and Data Provider URL 5a The process will automatically be re-launched after a period of time

defined in its configuration file. 5b SSN Administrator stops the process

Alernative Flow

Step Action



10-Sept-04 - Page 139

Requirement Id

Description


-

Assumptions -

Open issues � Should a new XML message be defined or could an existing one be used for the

polling request?

Extension Points

-

Documents

SSN-SRS-01 11-EN 1.1 - European Maritime Safety … Requirements Specification 01_11 10-Sept-04 . SafeSeaNet ... Use Case Package “SSN Monitoring & Polling” ... National Competent