GOTRIS Demonstration project - Final report , part 2

(1)

(2)

(3)

1

REMARKS ... 4

CONTEXT ... 4

FUNCTIONAL VIEW ... 4

PROCESS VIEW ... 4

NON-FUNCTIONAL VIEW ... 5

CONSTRAINTS ... 5

PRINCIPLES ... 5

LOGICAL VIEW ... 6

Handle Voyage Message ... 6

Handle Booking Message, including Auto-Booking of related objects ... 6

ReloadOptimizationModule_All ... 7

DispatchCalendarOptModule ... 7

ConnectionId ... 7

What is an active Gotris boat? ... 7

Handle UTIN TimeTable ... 7

INTERFACE VIEW ... 8

DESIGN VIEW ... 9

GOTRIS Application Server ... 9

Overview ... 9

Architecture of Application Server ... 11

Responsibilities of the Layers ... 12

Service Layer ... 12

Façade Layer ... 12

Domain Model Layer ... 12

Database Abstraction Layer ... 13

(4)

2

Service Layer ... 13

Façade Layer ... 14

Domain Layer ... 14

Database Abstraction Layer ... 15

Adapter Layer ... 15

Application Server Data Contracts ... 15

Application Server Service Contracts ... 15

IAis ... 16

IViva ... 16

ITrain... 17

IGotris ... 17

IAgent ... 19

Application Server Agent ... 20

Overview ... 20 Calendar Agent ... 21 GotrisBoat Agent ... 21 ObjectList Agent ... 21 Warning Agent ... 21 Viva Agent ... 21

INFRASTRUCTURE VIEW ... 21

DEPLOYMENT VIEW ... 21

Application Server ... 21 Accounts ... 21

OPERATIONAL VIEW... 21

System Parameters ... 21 Future Development ... 23 Error management ... 23 Configuration ... 24 Application Server... 24 Gotris Agent ... 25

Scheduled purge tasks in database... 26

SECURITY VIEW ... 29

DATA VIEW ... 29

Gotis Object Codes ... 29

(5)

3

Data Contracts ... 33

Gotris Data Contracts ... 33

Voyage ... 33 Passed ... 34 Manual Mode ... 34 CalendarOptModule ... 34 Booking ... 35 CalendarFrontend ... 35 Prognosis ... 36 SpeedRecommendation ... 37 PilotShipData ... 37 Warning ... 37

External Data Contracts ... 38

WeatherData (VIVA) ... 38

UTIN TimeTable Data... 39

UTIN TrainRunning Data ... 41

AIS ... 42

Database/Domain Model - Gotris ... 42

Overview ... 43

UTIN Data ... 44

Tables ... 45

Views... Fel! Bokmärket är inte definierat. Logic ... Fel! Bokmärket är inte definierat.

TECHNOLOGY SELECTION ... 46

(6)

4

Remarks

See the following link for recommendations regarding the different sections in this SAD. http://www.codingthearchitecture.com/pages/book/software-architecture-document-guidelines.html

Context

Functional View

Process View

For a complete, detailed process drawing see:

http://arbetsrum.trafikverket.local/webbplatser/ws68/gotris/Projektdokument/Arbetsdokument/Flö den/TotalFlow4.png

In below image dark blue boxes at the top represent external partners. They are Sjöfartsverket, Götebors stad, InPort, SSPA and Trafikverket. The arrows represent flow of data between all

(7)

5

Non-functional View

Constraints

The GOTRIS Project has some constraints that have direct affect on the systems architecture and design decisions.

 Biztalk version, Trafikverket currently uses Biztalk Server 2010.

 GOTRIS is a proof of concept with focus on function rather than best practices.

 The project result should be easy to distribute to an external firm for completion.

 The project has a relatively tight time frame.

 The project budget is fixed.

Principles

General architecture principles:

(8)

6

 Communication between GOTRIS parties should be done through the “fire and forget” principle.

Internal Integration principles:

 Biztalk Server (BT) has the role as public façade against external parties.

 BT is responsible for messaging and transformation.

 BT has no GOTRIS application awareness, no application specific details exists in BT.

 BT does not communicate directly to the GOTRIS database.

 The GOTRIS application (AS) holds all GOTRIS specific application logic.

 The AS is responsible for business logic and access to and from the GOTRIS database.

Logical View

Here AS logic is described in different scenarios. All messages are forwarded to other modules according to Process View, and this is not repeated here. This is the internal logic of AS.

Handle Voyage Message

1. Add the boat in the Voyage message as a new Gotris boat. a. If already exists, do nothing.

2. Delete all previous Voyages for that boat. 3. Save new Voyage from the Voyage message.

a. If Voyage is empty, nothing is saved. This boat has now an empty voyage. Note: A Voyage is defined as a list of Gotris Objects that the boat is scheduled to pass.

Handle Booking Message, including Auto-Booking of related objects

Assume object A is booked for boat C in the message. If not a boat booking, no auto booking is made. 1. If Booking has no id, a new booking is created based on message.

a. Check if there are any dependent child objects B to A.

i. If yes, check that child is not in the list of excluded objects for boat C. If in the list, abort auto-booking. (Means e.g. that C can pass under bridge without bride opening)

ii. If yes, check if there is any Prognosis on B for booked boat C. Look for closest prognosis relative to booked starttime on parent object. This will cover both upstream and downstream scenarios.

1. If yes, create an auto-booking on B for boat C based on info in Prognosis. StartTime in the booking = StartTime in the Prognosis. Endtime based on passagetime on object defined in ObjectList. iii. If no, abort auto-booking.

2. If Booking has id, and StartTime and EndTime have values, booking is updated based on message.

(9)

7 a. Delete any existing child bookings created in 1).

b. Create a new child booking using the same code as in 1).

3. If Booking has id, but both StartTime and EndTime are null, booking is deleted. a. Any child bookings are also deleted.

ReloadOptimizationModule_All

When OptModule requests a full reload,

1. ObjectList 2. Voyages 3. PilotShipData 4. Calendar

is sent in that order. 1 second sleep between send to ensure ordered delivery.

DispatchCalendarOptModule

Frontend always sends 3 bookings for each booking, grouped by a connectionId. 1. Safety margin before bridge.

2. Passage time.

3. Safety margin after bridge.

OptModule does not want extra bookings 1 and 3. When AS generates the Calendar to OptModule 1 and 3 are stripped off.

ConnectionId

This concept was an early design idea that has now been abandoned. It was thought to group many bookings, but it now only used as a temporary ID internally in Frontend. The AS just echoes this field back to Frontend with no other actions.

What is an active Gotris boat?

1. Boat is defined in GOTRIS_Boat table.

2. At least 1 object is not passed in the current Voyage for that boat.

Handle UTIN TimeTable

1. Get A-stations of bridge definition. 2. Get B-stations of bridge definition. 3. Loop over all timetables in message.

(10)

8 a. Look for A.

b. If A if found, look for B

i. If A + B are found, insert one row in MESSAGE_UTIN_TimeTable, taking data from message.

(11)

9

Design View

GOTRIS Application Server

Overview

The Application Server (AS) is responsible for all system-wide business logic in GOTRIS regarding messaging. The AS owns the GOTRIS database. AS is marked with blue color in the image above. It consists of two separate Windows Services. One is implemented as a WCF service

(GOTRIS.Nav.WCF) which listens for messages from external modules and processes business logic, and one is implemented as a worker process doing active cyclic tasks in the background

(GOTRIS.Nav.Agent).

GOTRIS.Nav.WCF

IVIVA IAIS IGotris ITrain

IAgent GOTRIS.Module.Utin IUtin GOTRIS.Nav.AGENT RT Temp Trainbookings

Components and interfaces

BTS WS

(12)

10 AS has the following public interfaces for getting data input:

Interface Description

IViva Weather data

IAIS Ship position data (AIS)

IGotris Data from other GOTRIS modules ITrain Train data from UTIN module

IAgent Messages from background worker agent

(13)

11 Application Server Agent” for further details.

Architecture of Application Server

The AS is designed according to the principles of Responsibility Driven Design (RDD), which stipulates that all classes in the application can be put into one of six roles of responsibility. The roles are:

Role Responsibility

Controller Major responsibility for a fundamental business logic process.

Interfacer Responsibility for understanding both sides of an interface between two systems.

Service Provider/Helper Responsibility for having expert knowledge of a specific limited area, e.g. encryption.

Information holder Responsibility for containing data and operating on that data only. Relayer Responsibility for relaying messages from one part of a system to

another. E.g. internal software communication infrastructure as the publisher/subscriber pattern.

Structurer Responsibility for structuring other classes. In AS the first four roles have been used.

RT

Database Abstraction Layer (DAL)

Service Layer(AS boundary)

Facade Layer

Inbound interface

Domain Model Layer

Biztalk Application server BusinessLogic Adapter Layer Outbound interface Domain Controllers Helpers Information Holders Interfacers Interfacers Interfacers Structurers Relayers Interfacers AS Internal Architecture

(14)

12 In the Service Layer we find interfacers between the external world and the internal business logic. The classes here understand how to receive messages to the GOTRIS.Nav.WCF Windows Service and forward them to the façade layer of the business logic.

In the Façade Layer of the business logic we find interfacers between data formats. On one side the data contracts coming from the outside world, and on the other side the internal representation of that data within the business logic.

In the Domain Model Layer we find all roles. Here the actual GOTRIS domain is modeled. Business rules are implemented and the GOTRIS concepts are modeled.

In the Database Abstraction Layer we find interfacers understanding on one side the Domain Model and on the other side how that model is implemented in a relational database.

Responsibilities of the Layers

Service Layer

The responsibility of this layer is to act as an infrastructure bridge between the external world and the domain model.

One implementation of a service layer can be to translate calls to a webserver-hosted WCF service into calls to the domain model. This service is a .svc-file published by IIS.

Another implementation can be to translate calls to a WindowsService-hosted WCF service into calls to the domain model. This service is a plain C# file (.cs).

Thus, by implementing another service layer, the AS can easily be hosted in different hosting technologies.

No other code should exist here other than infrastructure-bridging code. Façade Layer

The responsibility of this layer is to act as a data transforming bridge between the external world and the domain model.

The external world use generally defined data contracts that all agree on, on a system-wide basis. The internals of the domain model use another version of the data, which decouples it from the external world and makes it insensitive for changes of those system-wide data contracts. It is the responsibility of the Façade Layer to map between the two.

No other code should exist here other than DataContract-mapping code and calls to the domain-model.

Domain Model Layer

The responsibility of this layer is to act as a model of the Gotris domain. Here all Gotris businesslogic takes place. We find things such as TrainBookings, BoatBookings, Warnings, AisMessages etc.

(15)

13 Database Abstraction Layer

The responsibility of this layer is to act as a bridge to the relational database world. Persistance of domain objects is handled here.

No other code should exist here other than calls to the database. Write operations to store domain objects, and read operations to read back those objects and deliver them to the domain layer.

Application Server Layers - Walkthrough

Here a fundamental code example is shown how an incoming AIS message is handled. All other messages are handled in a similar way.

Service Layer

An AIS message is received by the service layer. The message is in the form of a data contract known by all modules in GOTRIS.

The message is forwarded to the business logic façade.

Note the attribute InstanceContextMode.PerCall which is tailored for maximum performance. A new

instance of the service class will be created for each call. This is optimal for multi-core, multithreaded CPUs.

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerCall)]

public class AisService : IAis

{

public void HandleMessage(AIS data) {

Facade.Instance().AIS.HandleMessage(data); }

(16)

14 Façade Layer

In the Façade Layer the data contract is translated to the internal representation of an AIS message. A Helper is used which is responsible for having expert knowledge of how to translate data contracts to internal business classes.

Domain Layer

In the Domain Layer we find the AisController. The AisController is responsible for understanding the business logic for handling an AIS message. The AIS is always forwarded to Frontend. If the AIS is coming from a GOTRIS ship it is forwarded to Optimization Module and saved to DB, else it is ignored.

/// <summary>

/// BusinessLogic for handling an AIS message.

/// </summary>

/// <param name="xml"></param>

public void HandleMessage(AISMessage ais) { try { ForwardMessageToFrontEnd(ais); if (IsGotrisShip(ais)) { ForwardMessageToOptimizationModule(ais); SaveAisMessageToDb(ais); } }

catch (Exception ex) {

ErrorHandler.HandleError(ex); }

}

public void HandleMessage(DataContracts.AIS.AIS data) {

try

{

//Some logging excluded for readability...

InfoHolders.AISMessage ais = _helper.Translate(data); new AisController().HandleMessage(ais);

}

ErrorHandler.HandleError(ex); }

(17)

15 Database Abstraction Layer

Here a stored procedure is called by an Interfacer called AisControllerDB understanding how the Domain Model classes are persisted in the database.

Adapter Layer

In the Adapter layer we send data to the outside world. Here we find Interfacers understanding how to map between the internals of the AS to the data contracts known by all modules in GOTRIS, and how to send it. Here we have an Interfacer specifically designed to communicate with Biztalk, BiztalkInterfacer. It translates the AIS to the data contract format and sends it to Biztalk using a service reference to a Biztalk webservice.

Application Server Data Contracts

The AS shares data contracts with Biztalk and all other Gotris modules. See section “Gotris Data Contracts”.

Application Server Service Contracts

The AS has the following public interfaces for communication with the outside world. Note the attribute [XmlSerializerFormat] which was needed to make Biztalk understand hot to call the WCF

service.

public void SendAISToFrontEnd(AISMessage ais) {

try

{

_logger.Debug("Forwarding AIS to FrontEnd..."); GuardProxyFrontendOpen_AIS();

//Map datacontract

Biztalk_Frontend_AIS.AIS data = _helper.Translate_Biztalk_Frontend_AIS(ais); //Call Biztalk

_proxyFrontend_ais.HandleAisMessage(data); _logger.Debug("Forwarding AIS to FrontEnd OK."); }

_logger.Debug("Error forwarding AIS to Frontend", ex); ErrorHandler.HandleError(ex);

} }

public void SaveAisMessage(AISMessage ais) {

List<SqlParameter> pp = new List<SqlParameter>();

pp.Add(new SqlParameter("@BoatId", ais.BoatId.CheckNull())); pp.Add(new SqlParameter("@Longitude", ais.Longitude.CheckNull())); pp.Add(new SqlParameter("@Latitude", ais.Latitude.CheckNull())); pp.Add(new SqlParameter("@AisRaw", ais.Xml));

ExecuteStoredProcedureNonQuery(DBEnum.RT, "AIS_AddShipPosition", pp); }

(18)

16 IAis

The IAis interface is the entry point for AIS data into AS. It has one single method taking an AIS data contract message.

IViva

The IViva interface is the entry point for VIVA (weather) data into AS. It has one single method taking a VIVA data contract message.

namespace GOTRIS.Nav.BusinessLogic.ServiceContracts {

[ServiceContract] [XmlSerializerFormat] public interface IViva

{

[OperationContract]

void HandleMessage(DataContracts.VIVA.Stations data); } } namespace GOTRIS.Nav.BusinessLogic.ServiceContracts { [ServiceContract] [XmlSerializerFormat] public interface IAis

{

[OperationContract]

void HandleMessage(DataContracts.AIS.AIS data); }

(19)

17 ITrain

The ITrain interface is used to import train bookings on bridges. GetBridgeDef() can be called to get the list of bridges to handle. GetInterval() can be called to get the interval in which to rebuild train bookings. HandleTrainBookings() is called to send the actual list of TrainBookings.

Currently the external UTIN module is plugged into this interface. However any module can be used in the future to handle train traffic over bridges, as long as it is plugged into the ITrain interface. IGotris

IGotris is the main interface for all Gotris system-wide communication. Here the Gotris message types (Data Contracts) are implemented. It is exclusively called by Biztalk which is the public integration layer in the system.

/// <summary>

/// This interface is designed for communication with Biztalk.

/// All other Gotris modules use this interface, via Biztalk,

/// and is the main interface for system-wide Gotris communication.

/// The parameters in the methods are C# versions of XSD-schemas

/// known to Biztalk.

/// The C# code has been generated by the XSD.EXE tool, based

/// on the Biztalk schemas.

/// </summary>

[ServiceContract(Namespace="GOTRIS")] [XmlSerializerFormat]

public interface IGotris

{

/// <summary>

/// Imports a Voyage message.

/// <summary>

/// This interface handles train bookings on bridges.

/// </summary>

[ServiceContract] public interface ITrain

{

/// <summary>

/// Returns a list of bridges to handle train passages for.

/// </summary>

/// <returns></returns>

[OperationContract]

List<Bridge> GetBridgeDef(); /// <summary>

/// Returns how often to rebuild train bookings for defined bridges (seconds).

/// </summary>

/// <returns></returns>

[OperationContract] int GetInterval(); /// <summary>

/// Imports a list of TrainBookings for defined bridges.

/// </summary>

/// <param name="trainBookings"></param>

[OperationContract]

void HandleTrainBookings(List<TrainBooking> trainBookings); }

(20)

18

/// Defines a route for a boat through a number of Gotris objects.

/// </summary>

/// <param name="data"></param>

[OperationContract]

void HandleVoyage(DataContracts.Voyage.Voyage data); /// <summary>

/// Imports a Passed message.

/// Defines that a boat has passed a Gotris object.

/// </summary>

[OperationContract]

void HandlePassed(DataContracts.Passed.Passed data); /// <summary>

/// Imports a Prognosis message.

/// Defines calculated arrival times for a boat to certain Gotris objects.

/// </summary>

[OperationContract]

void HandlePrognosis(DataContracts.Prognosis.Prognoses data); /// <summary>

/// Imports a speed recommendation message.

/// Defines a recommended speed for a boat to arrive at

/// a Gotris object on prognosted time.

/// </summary>

[OperationContract]

void HandleSpeedRecommendation(SpeedRec data); /// <summary>

/// Imports a manual mode message.

/// Defines that a boat shall not be part of the Gotris system,

/// until next Voyage message.

/// </summary>

[OperationContract]

void HandleManualMode(DataContracts.ManualMode.ManualMode data); /// <summary>

/// Imports a booking message.

/// Defines a booked time slot on a Gotris object.

/// </summary>

[OperationContract]

void HandleBooking(DataContracts.Booking.Bookings data); /// <summary>

/// Imports a pilot ship data message.

/// Defines basic data for a boat, as e.g. max/min speeds.

/// </summary>

[OperationContract]

void HandlePilotShipdata(PilotShipData data); /// <summary>

/// Reloads Optimization module with new data.

/// The parameter can be any of the values

/// in <see cref="OptimizationModuleReloadTypes"/>.

/// </summary>

/// <param name="messageType"></param>

[OperationContract]

void ReloadOptimizationModule(ReloadOptModule data); /// <summary>

/// Reloads Frontend with new data. Currently not used.

/// </summary>

/// <param name="messageType"></param>

[OperationContract]

void ReloadFrontend(string messageType); }

(21)

19 IAgent

The IAgent interface is used for triggering events or doing cyclic tasks in the AS. See more details regarding the responsibilities of the AS Agent below.

/// <summary>

/// This interface is called by the Application Server Agent.

/// It contains methods for notifications of changed data or

/// for cyclically sending push-based data.

/// </summary>

[ServiceContract] public interface IAgent

{

/// <summary>

/// Notifies that there are changes to the ObjectList,

/// changed after [lastUpdate]

/// </summary>

/// <param name="lastUpdate">Timestamp of previous update</param>

[OperationContract]

void GotrisObjectsUpdated(DateTime lastUpdate); /// <summary>

/// Requests new weatherdata from [stations]

/// </summary>

/// <param name="stations">List of VIVA weather stations to get

/// weather data from</param>

[OperationContract]

void DispatchVIVARequest(List<VIVAStation> stations); /// <summary>

/// Dispatches a list of warnings that a boat is too close to

/// an object without being booked.

/// </summary>

/// <param name="warning"></param>

[OperationContract]

void DispatchWarning(List<Warning> warnings); /// <summary>

/// Pushes calendar to Frontend

/// </summary>

[OperationContract]

void DispatchCalendarFrontend(); /// <summary>

/// Pushes calendar to OptModule

/// </summary>

[OperationContract]

void DispatchCalendarOptimizationModule(); /// <summary>

/// Imports an updated list of Gotris boats.

/// A Gotris boat is actively part of the Gotris system.

/// </summary>

[OperationContract]

void GotrisBoatsUpdated(List<GotrisBoat> boats); }

(22)

20

Application Server Agent

Overview

The AS Agent’s main responsibility is to do work in the background, as opposed to the WCF component of the AS which is responsible for processing real-time data.

The AS Agent has the following tasks running in the background:

Task Description

CalendarAgent Sends calendar to Frontend and Optimization modules at cyclic intervals (data push).

GotrisBoatAgent Keeps track of active Gotris boats.

ObjectListAgent Sends the GOTRIS objectlist to Optimization module and Frontend, if there are any changes to it (triggered-based push).

WarningAgent Sends warnings to frontend according to a warning algorithm. Based on Prognosis and Bookings (triggered-based push).

VivaAgent Triggers a request to fetch new weatherdata (VIVA) at cyclic intervals (triggered-based data pull).

The AS Agent application is structured in a number of Agents controlled by an AgentController:

The Agents run on separate threads, independently of each other.

Each Agent communicates with the Gotris system using the IAgent interface as described above. The agents use some system parameters. There is no need to reboot the agent if a system parameter changes. It will use the new value automatically.

Some agents run cyclically on timer. If it is needed to force these agents to run immediately, the agent service can be rebooted.

(23)

21 Calendar Agent

Runs on timer and requests a send of Calendars to Optimization Module and Frontend, by calling IAgent.DispatchCalendarFrontend() and IAgent.DispatchCalendarOptimizationModule().

GotrisBoat Agent

Runs on timer and sends a list of boats currently active in the Gotris system, by calling

GotrisBoatsUpdated(List<GotrisBoat> boats).

ObjectList Agent

Monitors table Gotis_Object and looks for changes. If a change is detected, a notification is made by calling GotrisObjectsUpdated(DateTime lastUpdate). The Gotris ObjectList will be communicated to the rest of Gotris system.

Warning Agent

Runs on timer and checks Bookings against Prognosis’. If there is a Prognosis on an Object but no Booking, Warning messages are sent by calling IAgent.DispatchWarning(List<Warning> warnings)

Viva Agent

Runs on timer and requests retrieval of new weather data for defined weather stations, by calling

DispatchVIVARequest(List<VIVAStation> stations).

Infrastructure View

Deployment View

Application Server

Accounts

All AS services run on the buildt-in account “Local System”. No dedicated accounts are needed. See also “Driftmall Gotris” here:

http://arbetsrum.trafikverket.local/webbplatser/ws68/gotris/Projektdokument/Arbetsdokument/dri ftmall.docx

Operational View

System Parameters

The following parameters are defined in table GOTRIS_SystemParameter, and control the behavior of the system. Some parameters are dynamic and they are maintained by the system. Others are static and are only maintained by people.

Id # Description Type Datatype Default

(24)

22 Time-window in which train bookings are rebuilt

frequently. See also #7 and #10

2 UTIN_MIN_VALID_SLOTTIME_MINUTES

Minimum time-slot for a bridge opening. Less than this value is not usable. [NOT USED, 2013-09-17]

Static Int 15

3 AGENT_VIVA_GET_INTERVAL_SECONDS

How often to get VIVA updates

Static Int 60

4 AGENT_OBJECT_LIST_GET_INTERVAL_SECONDS

How often to check if objectlist is updated

Static Int 60

5 AGENT_OBJECT_LIST_LAST_UPDATE

Last time object updates were found

Dynamic DateTime -

6 AGENT_WARNING_INTERVAL_SECONDS

How often to check for warnings

Static Int 60

7 AGENT_TRAIN_REBUILD_INTERVAL_SECONDS

How often to rebuild train bookings. The train data flows in realtime, and the agent takes a snapshop in this interval, creating train bookings. Either partial or full rebuild. See #1 and #10.

Static Int 3600

(1 hour)

8 AGENT_CALENDAR_PUSH_INTERVAL_SECONDS

How often to send calendar to Frontend and Optimization Module

Static Int 60

9 GOTRIS_LAST_FULL_TRAIN_BOOKING_REBUILD

Last time all trainbookings were rebuilt

Dynamic DateTime -

10 GOTRIS_FULL_TRAIN_BOOKING_REBUILD_INTERV

AL_MINUTES

How often a full rebuild of all known train bookings takes place. In between this interval a partial rebuild is made. See also #1 and #7.

Static Int 360

(6 hours)

11 AGENT_GOTRIS_BOAT_INTERVAL_SECONDS

How often agent checks for active gotris boats in DB

Static Int 60

12 DEFAULT_PILOT_SHIP_DATA_MIN_SPEED

Default data if no previous data exists

Static Decimal 5

13 DEFAULT_PILOT_SHIP_DATA_COMFORT_SPEED

14 DEFAULT_PILOT_SHIP_DATA_MAX_SPEED

15 VALID_AUTO_BOOK_MARGIN_MINUTES

Reasonable window when auto-booking related objects, based on prognosis. Time between parent booking and child prognosis must be less than this value, else no child booking is made.

Static Int 60

16 USE_TRAIN_DYNAMICS

Shall realtime data from trains on deviations from planned timetable be used?

Static Bool (1 or 0) 1

17 MINIMUM_MINUTES_BEFORE_BRIDGE_PASSAGE

_REAL_TIME_DEVIATION

Minimum amount of minutes before a bridge passage, when we consider a realtime train report to be valid

(25)

23

Future Development

It is recommended that all future development demands a checkin in TFS with a comment. External documentation quickly becomes obsolete, so the best is to keep the code self-documented in TFS and in the code itself.

Error management

All errors are logged in the eventlog of the server. Application Server example:

(26)

24

Configuration

Application Server

The AS use log4net for logging. See

http://logging.apache.org/log4net/release/manual/configuration.html for how to configure it. AS use WCF for service infrastructure. See http://msdn.microsoft.com/en-us/library/dd456779.aspx for documentation of this big framework. The key configuration is regarding IP-addresses to servers and connection strings to databases. This is defined in app.config (GOTRIS.Nav.WCF.config) and ConnectionStrings.config:

Example: Set port for AisService to 8080.

<service name="GOTRIS.Nav.WCF.Services.AisService"

behaviorConfiguration="Default_Service_Behaviour"> <host>

(27)

25

<add baseAddress="http://localhost:8080/AIS" />

</baseAddresses> </host>

<endpoint address="/basic"

binding="basicHttpBinding"

bindingConfiguration="basicConfig"

contract="GOTRIS.Nav.BusinessLogic.ServiceContracts.IAis" /> <endpoint address="/basic/mex"

binding="mexHttpBinding"

contract="IMetadataExchange" /> </service>

Example: Set address to Biztalk’s service for sending AIS to SSPA.

<endpoint

address="http://trv8169.trafikverket.local/GOTRISBTS/SSPA/Internal/AIS/SSPASndService.svc"

binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_ITwoWayAsyncVoid"

contract="Biztalk_SSPA_AIS.SSPASndService" /> <endpoint

address="http://trv8169.trafikverket.local/GOTRISBTS/FrontEndService/FrontEndOLService.svc"

binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_ITwoWayAsyncVoid"

contract="Biztalk_Frontend_Objectlist.FrontEndOLService" />

Example: Set connection string to the Nav database, set to server trv8167:

<add name="RT" connectionString="Data Source=trv8167;Initial

Catalog=GOTRIS_NAV_RT;user=gotris_nav;password=gotris_nav" providerName="System.Data.SqlClient"/>

Gotris Agent

The different agents can be enabled/disabled by setting the following properties in

GOTRIS.Nav.Agent.exe.config. The agent service needs to be restarted for the changes to take effect.

<GOTRIS.Nav.Agent.Properties.Settings>

</setting>

</setting>

</setting>

(28)

26

</setting>

</GOTRIS.Nav.Agent.Properties.Settings> </applicationSettings>

Scheduled purge tasks in database

On Navet Side

There is a continuous flow of data coming into the database. To avoid the database size from becoming of extreme size, the historical data is purged in different intervals.

The SqlServer Agent job GOTRIS_PurgeOldData is scheduled to run once per day. See table below for details.

Table History saved (days) Comment

Message_Prognosis 7 Very large amounts of Prognosis

can be sent. 3M in 6 days during test.

Message_Ais 7 Only AIS for Gotris boats are

saved.

Message_Booking 30 Bookings are made manually by

humans, apart from train bookings.

Message_ManualMode 30 -

Message_Passed 30 -

Message_PilotShipData 365 Old shipdata is used to send

default values when a new voyage is created for that boat.

Message_SpeedRecommendation 90 -

Message_Utin_TimeTable 40 -

(29)

27 Data in these steps is moved to a new database: GOTRIS_NAV_HIST:

To export data to disk from GOTRIS_NAV_HIST the following Maintenanceplan is run. It is run in two steps:

1. Backup to disk (bak.file)

(30)

28 The backup files are stored here, with unique timestamped names:

Operative personnel can update settings in:

1. Job GOTRIS_NAV_RT_PurgeOldData to control when data is moved from RT till HIST. a. Each step controls how many days of data are saved.

2. Maintenanceplan GOTRIS_NAV_HIST_Export to control how often data is exported to disk. a. Each .bak file will contain 1 atomic increment of historical data.

(31)

29

On Viktoria Side

On Viktoria an ImportService is installed. It performs the following steps:

1. Downloads bak files from FTP (optional) 2. Restores bak to temp database

3. Inserts data to target hist database Settings as follows:

<?xml version="1.0" encoding="utf-8"?> <Settings>

<ConnectionString>Data Source=SQL_SERVER;Initial Catalog=master;user=sa;password =PASSWORD;Connection Timeout=10</ConnectionString>

<FtpServerPollIntervalSeconds>60</FtpServerPollIntervalSeconds> <FtpFolderPollIntervalSeconds>20</FtpFolderPollIntervalSeconds> <FtpServerIp>IP_TO_FTP_SERVER</FtpServerIp>

<FtpUserName>FTP_USER</FtpUserName> <FtpPassword>FTP_PASSWORD</FtpPassword>

<FtpRemoteFolder>/FPT_ROOT/FOLDER</FtpRemoteFolder> <FtpLocalFolder>LOCAL_PATH</FtpLocalFolder>

<PathToTempFtpDownloadFolder>G:\FtpDownloads</PathToTempFtpDownloadFolder> <PathToBackupFiles>G:\Backup</PathToBackupFiles>

<PathToImportedFolder>G:\Imported</PathToImportedFolder> <PathToTempDatabaseFiles>C:\Temp</PathToTempDatabaseFiles> <GotrisNavDbName>GOTRIS_NAV_HIST</GotrisNavDbName>

<GotrisNavLogName>GOTRIS_NAV_HIST_LOG</GotrisNavLogName> <GotrisHistDbName>GOTRIS_NAV_HIST</GotrisHistDbName>

<PathToGotrisHistDataFile>C:\MyDataPath\GOTRIS_NAV_HIST_TEST.mdf</PathToGotrisHi stDataFile>

<PathToGotrisHistLogFile>C:\MyLogPath\GOTRIS_NAV_HIST_TEST_1.ldf</PathToGotrisHi stLogFile>

<FtpThreadEnabled>False</FtpThreadEnabled>

Security View

Data View

Gotris Object Codes

(32)

30

SE299 Gotenius varv Hamn

SE262 Kaj 259 Saltkajen Hamn

SE259 Kaj 262 Ahlsell Hamn

SEAGB Agnesberg Skrotfrag Hamn

SESUR Surte Hamn

SEBOH Bohus Eka Hamn

SENOL Nol Perstorps brygga Hamn

SELDO Lödöse Hamn

SELED Lilla Edet Hamn

SETRO Trollhättan Stallbacka Hamn

SEVGN Vargön Hamn

SEVAN Vänersborg Stadskaj Hamn

SESKO Skattkärr Hamn

SELDK Lidköping Hamn

SEHON Hönsäter Hamn

SEOTT Otterbäcken Hamn

SEKHN Kristinehamn Hamn

SEKSD Karlstad Hamn

SESHO Skoghall Hamn

SEGRU Gruvön Hamn

SEAMA Åmål Hamn

MARIEHOLM Marieholmsbron Järnvägsbro

JVGTROLL Jvgsbron Trollhättan Järnvägsbro

JVGVBORG Jvgsbron Vborg Järnvägsbro

GBGGPS Gothenburg Pilot South Lotspåstigningsplats

VBGPN Vandersborg Pilot North Lotspåstigningsplats

WEATHER70 Dalbobron Mätstation

WEATHER72 Torshamnen GBG Hamn Mätstation

WEATHER73 Stallbackabron Mätstation

WEATHER74 Åkerström Mätstation

WEATHER75 Göta Mätstation

WEATHER76 Älvänge Mätstation

WEATHER77 Brinkebergskulle Övre Mätstation

WEATHER78 Brinkebergskulle Nedre Mätstation

WEATHER79 Lilla Edet Övre Mätstation

WEATHER80 Lilla Edet Nedre Mätstation

WEATHER84 Karet GBG Hamn Mätstation

WEATHER91 Vargön Mätstation

WEATHER92 Trollhättan Mätstation

WEATHER93 Lilla Edet Ström Mätstation

MOTE19 Vassbotten Mötesplats

MOTE1 Norr gamla vattenintaget Mötesplats

MOTE2 Syd Agnesberg Mötesplats

MOTE3 Norr Angeredsbron Mötesplats

(33)

31

MOTE5 Skårdal Mötesplats

MOTE6 Norr Jordfallsbron - Syd Haj Mötesplats

MOTE7 Norr Haj - Syd Ladugårdsholmen Mötesplats

MOTE8 Syd Lödöse - Syd Bränna fyr Mötesplats

MOTE9 Ödegärdet Mötesplats

MOTE10 Norr Göta Mötesplats

MOTE11 Hägers / Fuxerna Mötesplats

MOTE12 Norr Ströms sluss - Intagan Mötesplats

MOTE13 Holmenbryggan Mötesplats

MOTE14 Höljan Mötesplats

MOTE15 Åkerssjö Mötesplats

MOTE16 Stadskajen Mötesplats

MOTE17 Malöga - Bommen Mötesplats

MOTE18 Norr Brinkebergskulle sluss Mötesplats

BRINKEBERG Brinkebergskulle Sluss

TROLLH2 Sluss nr2 Sluss

TROLLHSLT Slusstrappan Sluss

LILLAEDETS Lilla Edet sluss Sluss

GOTA GötaÄlvbron Vägbro

JORDFALL Jordfallsbron Vägbro

LILLAEDET Lilla Edetbron Vägbro

KLAFFBRON Klaffbron Vägbro

GROPBRON Gropbron Vägbro

DALBOBRON Dalbobron Vägbro

SPEED1 Hastighetsbegränsning1 Hastighetsbegränsning

(34)

32

Gotris Objects

ColumnName Datatype Comment Nullable

Id int Internal AS id No

ObjectCode string External id No

Name string Human readable name No

ObjectTypeId int Id of ObjectType, e.g.

bridge, port, speedlimitarea etc.

No

ParentObjectId Int Reference to parent

object if this object is dependent on another object.

Yes

Lat1 decimal Entry latitude Yes

Long1 Decimal Entry longitude Yes

Lat2 Decimal Exit latitude Yes

Long2 Decimal Exit longitude Yes

Gotref1 Decimal Entry GOTREF. 1-dim

projection of lat/long. Used by optimization

(35)

33 module. The

geographical shape of the river is seen as one straight line. Each position can be defined with one single

number.

Gotref2 Decimal Exit GOTREF Yes

DemandsBooking Bool Must object be

booked?

No

AheadTimeMinutes Int Minutes before bridge

opening that a booking must be made.

Yes

OpeningMarginMinutes Int Time to open object for boat.

Yes

ClosingMarginMinutes Int Time to close object

after boat.

Yes

PassageTime Int Passage time for object Yes

SpeedLimit Decimal Max speed in the

defined geographical area of this object.

No

Data Contracts

Here follows a list of all Data Contracts in the system. Each Data Contract has a description of the fields along with an example XML message.

Gotris Data Contracts

Voyage

Field Datatype Comment Mandatory

BoatId String Yes

ObjectCode String Yes

ArrTime DateTime Yes

DepTime DateTime Yes

Dnggoods Bool Dangerous goods Yes

Example:

<?xml version="1.0" encoding="utf-16"?>

<Voyage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<ObjectCode>SESUR</ObjectCode>

<Arrtime>2013-08-27T10:00:00+02:00</Arrtime> <Deptime>2013-08-27T16:00:00+02:00</Deptime> <Dnggoods>false</Dnggoods>

</Object> </Objects> </Voyage>

(36)

34 Passed

BoatId String Yes

Timestamp DateTime Yes

Example

<Passed xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<BoatId xmlns="http://gotris.Voyage">256708000</BoatId> <ObjectCode>SESUR</ObjectCode>

Manual Mode

ShipId String Yes

Timestamp DateTime Yes

TriggeredBy String Yes

Reason String Yes

Example

<ManualMode xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://gotris.manualmode"> <ShipId>12345</ShipId>

<Reason>Test meddelande</Reason> </ManualMode>

CalendarOptModule

Start DateTime Yes

End DateTime Yes

BoatId String Yes

Example:

<Calendar xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <Bookings xmlns="gotris.calendar.optimization"> <Booking>

<ObjectCode>JVGTROLL</ObjectCode> <ShipId>12376000</ShipId>

(37)

35

<ObjectCode>JVGTROLL</ObjectCode> <ShipId>0</ShipId> <StartTime>2013-09-10T13:11:00+02:00</StartTime> <EndTime>2013-09-10T13:27:00+02:00</EndTime> </Booking> --- </Bookings> Booking

BookingId Int No

From DateTime Yes

To DateTime Yes

BoatId String Yes

Freetext String Yes

ConnectionId Int Connects many

bookings into a group

Yes

BookingType String Yes

Example

<Bookings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://gotris/inport/booking"> <Booking>

<ObjectCode>MARIEHOLM</ObjectCode>

<FreeText>AS UNIT TEST</FreeText> <Confirmed>false</Confirmed>

<BookingType>Maintenance</BookingType> </Booking>

</Bookings>

CalendarFrontend

BookingId Int Yes

(38)

36

To DateTime Yes

BoatId String Yes

Freetext String

ConnectionId Int Connects many bookings

BookingType String Yes

TrainBookingType String  DefaultTimeTable

 PlannedNewTimeTable  UnplannedDeviation

Yes

(trainbookings only)

TrainId String Yes

TrainDeviationMinutesFromTimetable Int Yes

Example

<calendar xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <Bookings xmlns="gotris.calendar.frontend"> <Trains>

<Booking type="TrainPassage"> <BookingId>626621</BookingId> <ObjectCode>JVGTROLL</ObjectCode> <From>2013-11-15T07:16:00Z</From> <To>2013-11-15T07:22:00Z</To>

<TrainBookingType>DefaultTimeTable</TrainBookingType> <TrainId>3227</TrainId>

<Booking type="TrainPassage"> <BookingId>626641</BookingId> <ObjectCode>MARIEHOLM</ObjectCode> <From>2013-11-15T07:17:00Z</From> <To>2013-11-15T07:20:00Z</To>

<TrainBookingType>DefaultTimeTable</TrainBookingType> <TrainId>3228</TrainId> <DeviationMinutesFromTimeTable>0</DeviationMinutesFromTimeTable> </Booking> </Trains> </Bookings> Prognosis

BoatId String Yes

Start DateTime Yes

End DateTime Yes

Meeting Bool Is there a prognosted

meeting of two ships on this ObjectCode?

Yes

Example

<ArrayOfPrognosesPrognosis xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <PrognosesPrognosis>

(39)

37

</Object> <Object>

<StartTime>2013-08-29T14:27:57Z</StartTime> <EndTime>2013-08-29T14:28:27Z</EndTime> <Meeting>False</Meeting>

</Object> </PrognosisList> </PrognosesPrognosis> </ArrayOfPrognosesPrognosis>

SpeedRecommendation

BoatId String Yes

Speed Decimal

Example

<SpeedRec xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://gotris.speedrecommendation"> <ShipId>Test_Vessel</ShipId>

PilotShipData

BoatId String Yes

ComfortableSpeed Decimal Yes

DeepFront Decimal Yes

DeepStern Decimal Yes

MaxSpeed Decimal Yes

MinSpeed Decimal Yes

UId String UserId Yes

ExcludedBridges String[] No

Example

<PilotShipData xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://gotris/inport/pilotshipdata"> <ShipId>220018000</ShipId> <DeepFront>5</DeepFront> <DeepStern>5</DeepStern> <MaxSpeed>12</MaxSpeed> <MinSpeed>3</MinSpeed> <ComfortableSpeed>11</ComfortableSpeed> <UId>Admin</UId>

</PilotShipData>

Warning

BoatId String Yes

(40)

38 Example

<Warning xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://gotris.warning"> <BoatId>Test_Vessel</BoatId>

<ObjectCode>MARIEHOLM</ObjectCode> </Warning>

External Data Contracts

External data contracts coming from fixed external sources outside Gotris.

WeatherData (VIVA)

StationId int Yes

Name String Yes

Flux Decimal No

Sight Int No

Waterlevel Int No

Average Wind Decimal No

Gust Wind Decimal No

The weatherdata is retrieved from a REST service here (exemple station 44): http://sjovviva.cloudapp.net/vivadatarest.svc/vivastation/44

Example

<ArrayOfStation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <Station>

<Name>Medelvind</Name> <Value>Värde Saknas</Value> <Heading>0.00</Heading> <Unit>!</Unit>

<Name>Lufttryck</Name> <Value>Värde Saknas</Value> <Heading>0.00</Heading> <Unit>!</Unit>

<Name>Fuktighet</Name> <Value>Värde Saknas</Value>

(41)

39

<Name>Lufttemperatur</Name> <Value>Värde Saknas</Value> <Heading>0.00</Heading> <Unit>!</Unit>

<Name>Vattentemperatur</Name> <Value>Värde Saknas</Value> <Heading>0.00</Heading> <Unit>!</Unit>

UTIN TimeTable Data

UTIN TimeTable data is complex and only a few fields are used in Gotris.

MessageNumber Int MessageId Yes

MessageStatus Int 1=Import, 3=delete Yes

StationId string Only if LocationSubsidiaryTypeCode = 05. 05 = “station”.

Yes

TrainId Int TrainIdent/PathIdent _Yes

RouteId Int A train route.

TrainBusinessIdent/PathIdent

Yes

DepartureTimeAtLocation DateTime Yes

Example <BVTimeTable xmlns="urn:BVTAF"> <MessageHeader> <MessageStatus>1</MessageStatus> <MessageReference> <MessageType MessageTypeCode="0" /> <MessageNumber>640</MessageNumber> <MessageDateTime>2013-03-13T00:02:59.013</MessageDateTime> </MessageReference> <Sender>10001</Sender> <Recipient>11013</Recipient> </MessageHeader> <TrainTimeTable> <TrainBusinessIdent> <PathIdent>013261</PathIdent> <ScheduledDepartureDateTime>2013-03-14T16:41:00</ScheduledDepartureDateTime> <PathDepartureLocation>

(42)

40

(43)

41 UTIN TrainRunning Data

NOTE: This message is not used any more. Implementation is still there, but the messages are ignored.

The TrainRunning data is less complex, and the concepts are the same as in TimeTable.

MessageNumber Int MessageId YES

MessageStatus Int 1=Import, 3=delete YES

TrainDelayAgainstBooked DateTime Deviation in minutes against scheduled timetable. Can be negative if train is early.

YES StationId String Only if LocationSubsidiaryTypeCode = 05.

05 = “station”.

YES

TrainId Int TrainIdent/PathIdent _YES

TimeAtLocation DateTime Time when train reported the deviation YES

Example <BVTrainRunningInformation xmlns="urn:BVTAF"> <MessageHeader> <MessageStatus>1</MessageStatus> <MessageReference> <MessageType MessageTypeCode="0" /> <MessageNumber>118579</MessageNumber> <MessageDateTime>2013-03-05T12:15:00.933</MessageDateTime> </MessageReference> <Sender>10001</Sender> <Recipient>11013</Recipient> </MessageHeader> <TrainIdent> <PathIdent>3836</PathIdent> <ScheduledDepartureDateTime>2013-03-05T07:45:00</ScheduledDepartureDateTime> <PathDepartureLocation> <CountryCode>SE</CountryCode> <LocationPrimaryCode>99999</LocationPrimaryCode> <LocationSubsidiaryCode LocationSubsidiaryTypeCode="05">G</LocationSubsidiaryCode> </PathDepartureLocation> </TrainIdent> <TrainLocationReport> <LocationIdent> <CountryCode>SE</CountryCode> <LocationPrimaryCode>99999</LocationPrimaryCode> <LocationSubsidiaryCode LocationSubsidiaryTypeCode="05">Thn</LocationSubsidiaryCode> </LocationIdent> <TrainLocationStatusReport> <TrainLocationStatus>04</TrainLocationStatus> <TimeAtLocation>2013-03-05T12:15:00</TimeAtLocation> <TrainDelayAgainstBooked>0005</TrainDelayAgainstBooked> </TrainLocationStatusReport> </TrainLocationReport> </BVTrainRunningInformation>

(44)

42 AIS

The AIS data has many fields, but only a few are used in Gotris. There are 3 types of AIS data used, AIS1, AIS2 and AIS3. AIS5 contains the name of the boat, but it is not used. Impossible to filter only Gotris geographical region. Will get all Sweden with AIS5.

Biztalk defines one (1) format for all 3 AIS types (a superset). Only the following fields are used:

MMSI Int BoatId Yes

X Decimal Longitude Yes

Y Decimal Latitude Yes

Example:

<AIS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns="http://trafikverket.se/gotris/ais2"> <Msg> <cog>25.2000007629</cog> <id>1</id> <mmsi>265504650</mmsi> <nav_status>0</nav_status> <position_accuracy>1</position_accuracy> <raim>false</raim>

<repeat_indicator>0</repeat_indicator> <rot>-731.386474609</rot>

<rot_over_range>true</rot_over_range> <slot_number>448</slot_number> <slot_timeout>4</slot_timeout> <sog>0.0</sog> <spare>0</spare> <special_manoeuvre>0</special_manoeuvre> <sync_state>1</sync_state> <timestamp>11</timestamp> <true_heading>511</true_heading> <x>12.8528833389</x> <y>56.6598014832</y> </Msg> </AIS>

GOTRIS Demonstration project - Final report , part 2

Table of Contents

REMARKS ... 4

CONTEXT ... 4

FUNCTIONAL VIEW ... 4

PROCESS VIEW ... 4

NON-FUNCTIONAL VIEW ... 5

CONSTRAINTS ... 5

PRINCIPLES ... 5

LOGICAL VIEW ... 6

INTERFACE VIEW ... 8

DESIGN VIEW ... 9

INFRASTRUCTURE VIEW ... 21

DEPLOYMENT VIEW ... 21

OPERATIONAL VIEW... 21

SECURITY VIEW ... 29

DATA VIEW ... 29

TECHNOLOGY SELECTION ... 46

Remarks

Context

Functional View

Process View

Non-functional View

Constraints

Principles

Logical View

Handle Voyage Message

Handle Booking Message, including Auto-Booking of related objects

ReloadOptimizationModule_All

DispatchCalendarOptModule

ConnectionId

What is an active Gotris boat?

Handle UTIN TimeTable

Design View

GOTRIS Application Server

Components and interfaces

Infrastructure View

Deployment View

Application Server

Operational View

System Parameters

Future Development

Error management

Configuration

Gotris Agent

Scheduled purge tasks in database

Security View

Data View

Gotris Object Codes

Gotris Objects

Data Contracts