Port Activity

Port Activity Application User manual

Introduction

This manual briefly describes different views and functionalities of Port Activity Application. Application is accessible from web with web browser. Mobile application is available from app stores. Most common functions are accessible with mobile phones. Complex functions and more rarely used functions are available only from web application.

API of application can be integrated directly to third party application and data export can be exposed to other systems as well. API documentation however is not in the scope of this document.

Web user interface

Web application contains all functions of application. Some functions are only for administrative tasks and are used only when setting up application or more complex analysis of data is required to see the actual data behind simpler user interfaces that are delivered for basic users.

Basic actions

Login

You need an username and password to be able to login into the application. Account is created within an another user that has sufficient permission within the application. User can also use specific registration code to create account.

Login

Registration

Registration for can be used to create account into the application. Use registration code to create account and fill all required information. It is not necessary to use email as username. However that you are allowed to reset your password in case of lost password you should use email as your username.

Registration with code

Reset password

There is also link to reset password. If email is used as password link to reset password is sent to that email address.

After login activity view open by default. Clicking to the top right corner of page opens a menu that can be used to navigate between sections.

Main menu

Activity

Activity view

Activity view

In activity view user see all active port calls. Port call is spliced into card and timeline. Card shows

Depending of the status of port call card also shows estimated time of arriving (ETA) or estimated time of departure in the card. Below of the card is timestamps that are related to the port calls. First blue part indicates events that happen before the vessel in the port. White part indicates events that happens within the port. Lower blue part indicates events that happens after vessel is leaving port. The green line that goes through timeline indicates the state that is currently active within the port call.

Actions that user can perform for port call in this view are visible when card view is opened. Actions depends permission that user has. Possible actions are:

Pin vessel

When vessel is pinned you see it card as yellow and small pin on top corner of card. You can pin or unpin vessel using this pin icon. When vessel is pinned user will get UI notifications from that vessel. Notification can be that new timestamp is received for that vessel or someone has send special text notification related to that ship. If user uses mobile application with smart phone all notifications are send also as push notification to her or his devices.

Pinned vessel

Add timestamp

User can add manually timestamp for a port call. However most cases adding timestamps manually is not recommended since all information should come from external datasources.

Send notification

User can send notification that relates to that specific vessel. Notification are only within this application and any one who sees it must have account wihtin this application.

Send notification (STM)

STM vessels are vessels that are connected with Port Activity Application with SeaSwim/VIS connector. When vessel is STM capable this functions is visible. When sending STM notification it means that that notification goes directly to ECDIS as a “text message” that is visible for ECDIS operator in the vessel.

Recommend time (STM)

STM vessel can also be communicated by sharing voyage plan with recommended time of arrival (RTA) with the vessel. If vessel is known as STM vessel there is also small badge indicator in card “VIS”. That basically means that vessel is sharing its voyage plan with this application. See more STM information in chapter “VIS vessels”.

Vessels view (administrative view)

Vessels views is administrative view to review all vessels within the system and review timestamps received. You can search vessels be name or IMO.

Vessels

For each vessel there is functions

Hide / Show

This hides the vessel from activity timeline. Lets say that for some reasons there is coming data from tugs that are actively coming feed timestamps from data sources but it is not something that you want to show in timeline. Then you should hide that vessel. Hidden vessel can be set back to visible by clicking “Show”.

Show timestamps

Shows every timestamp for a vessel that is received. This view is mostly used review raw data that is in system to validate that port call has is correct data.

Attach orphans timestamps

Some rare cases there is situation that IMO related timestamps is not valid for any port call yet. This function allows to manually re-scan orphan timestamps to attach those into port call. This function should be used only rarely most cases only in the beginning of setup phase when application is set up to quickly test data sources

Rebuild port calls

This rebuild all port calls for a vessel. Should be used with caution only in case that port calls are known to be build wrong eg. in the situations of changed logic to build port call.

Timestamps

When viewing timestamps for a vessels there is more functions for a single timestamp. You can

Delete timestamp

This removed timestamp from system. Let’s say that there is false timestamp coming from any data source because of human error you should be able to remove timestamp manually.

Show timestamp

Show all details for a timestamp in raw format. Eg. in some situations it is informative for an administrator to see payload of a timestamps. Payload content affects how timestamp is treated within application and what extra information there is available. This is very useful while debugging timestamps and data sources that are connected to application.

Edit timestamp start and end range

When clicked port call id you can edit port call time range. Time range defines what timestamps are included in a port call. You can change range manually but most cases you should not. If port call Master ID is set port call time range obeys port call ETA - ETD range from an external data source that provides ETA and ETD.

Edit timestamps

Inbound vessels view (STM)

Inbound vessels view shows all vessels that are leaving to your port from any other port that has installed this application. Lets say that there is Port of Gävle and Port of Rauma and both have installed and registered Port activity application with SeaSWIM/VIS. If vessels leaves Rauma to Gävle then Port Activity Application of Rauma send information to Port Activity Application of Gävle about estimated time of departure (ETD). This is simple list view to show ETDs from any other ports.

Other ports view (STM)

This view shows what other port activity applications, or ports, are communicating with this application. Be default all port to port communication is allowed yet you can disable messages from another port.

VIS vessels view (STM)

This is administrative view for all VIS/STM vessel related communications. More about STM vessel can be read from [STM https://www.seatrafficmanagement.info/projects/stm-validation/

VIS vessels

Here is all known vessels and ports with STM capabilities listed. You can use SeaSWIM/VIS raw functions to communicate with vessel. Basic users should however use function in activity view for that communication. In this view administrator can

Poll VIS service

Poll VIS service to fetch all latest data sent to this application

View VIS service configuration

See how VIS is configured for this application (how this application is connected and basically who you are in terms of VIS)

VIS configuration

Find VIS service

Find VIS services by IMO or service id

VIS configuration

Notifications
Show VIS notifications from other systems
Sent TXT

View sent text message from this application

Recv TXT

View Received text messages for this VIS instance

Sent VP

View sent voyage plans from this application

Recv VP

View received voyage plans from this application

Send TXT

Sent TXT message to another STM/VIS service

VIS send text message

Send RTA

Send RTA for another STM/VIS vessel. Send RTA modifies received voyage plan (VP) so that planned route is within recommended time in a certain point near by port (usually outer port area). Voyage plan is send back to vessel. If new voyage plan is ok for vessel it can activate it. New voyage plan is send back to PAA and new timestamp is generated into system from that voyage plan. You can send also range for recommended time of arrival.

Port call timesheets

Timesheets

If port call timesheets view you can search vessels and see all port calls. For each port call you can

View all timestamps collected to that port call (+ sign)
View final timesheet

View timesheet in web or print it or download it as CSV file

There is also links to see all timestamps and all port calls

You can manually close port call

Sometimes application receives timestamps that indicates a port call. However port call could be cancelled. From cancelled port call some data sources fails to give information about cancel and port call will never finish since there is no further activity for it. In such cases you should just close port call manually.

Re-scan port call

Many port call extra data are collected from payloads received within timestamps. Re-scan is done automatically when new timestamp are received. However if new version of application is installed or there is doubt that timestamps are changed within port call you may want to run re-scan for it. Data collected form timestamp payloads are

Logistics

Logistics module is separate part of application. This tracks truck traffic within a gate in the port. Logistics are not linked to vessel traffic yet in any manner. It simple truck gate monitoring.

Logistics

Notifications

Notifications are simple text messages within application. Notification can be related to a vessel or to be generic port related message. You see messages in notifications view. To send vessel related notification open timeline card of vessel and use “Send notification” button. From this view you can only send port related notification.

Notifications

Users, registration and registration codes

Users

Users

In users view you can search and view all users. You can also

Add new user
Edit user data

Edit user role, name and change password

Edit user

Delete user

User is marked as removed and data is anonymised within system. All manually added timestamps and notifications remains in the system.

Registration codes

Registration codes

Registration code is special code that can be used to register into the application. So there is two ways to get account into the application

Registration code defines user role that user gets by default. With this view you can

Add new codes
Enable/disable code
Delete code
Access control

Access control

There are several roles within system. For each role has permission. Permission name more or less describes what user can do. Eg. if user belongs to role “second administrator” he can do most of things that “administrator” role gives permissions but not manage admin user or manage translations.

Roles are static within system but permission for each roles can be altered.

String translations

Translations

Almost all texts in application can be altered. There is default text that is key for that translation. Translation is used in user interfaces when given. Only one translation is supported currently. This allows different ports to use their own terminology for all texts and timestamps. Timestamp naming follows by default IALA S-211 standard. However it is more convenient ports to use shortening for these. Eg. in screenshot above “Actual Arrival Vessel AnchorageArea” is simple translated to “ATA Anchorage”.

API

API keys

API keys

In this view you can

Add API key

This creates new API key with a given name. Api key is always bound as a user within the system since all data changes in the system are tracked on user level.

Enable/disable API key

If API key is disabled it can’t be used to make API calls.

API keys are keys that permits doing REST API calls to the system. Eg. external data sources can post data into the system using API key and doing a simple post into the system:

curl 'https://your.port.com/agent/rest/timestamps' \
-XPOST \
-H 'Accept: application/json, text/plain, */*' \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Authorization: ApiKey xxx' \
-H 'Connection: keep-alive' \
--data-binary '{"imo": "9295347", "vessel_name": "ADVANTAGE PARK", "time_type": "Estimated", "state": "Departure_Vessel_Berth", "time": "2020-10-16T01:00:00.867Z", "payload": {"from_port":"FIHKI", "to_port": "SEGVX", "next_port":"FIRAU"}}'

This is actually base to whole application that there are several data sources that posts timestamps into the system. Those timestamps then forms port calls that are displayed in the activity timeline.

API key priorities

API keys

API keys can be priorities on timestamp level. If multiple data sources post same timestamps and some system gives more accurate or important data then lower priority data source can’t override higher priority source timestamps. If timestamp needs to have priory set in this view to allow receiving timestamps into the application.

Modules

Modules

In modules view you can enable or disable modules that are available in system. This document covers only Activity Module, Logistics Module and Queue. Modules are build functionalities that enabled and disabled certain function in system. Eg. if logistics module is disabled it is not visible in UI and also API calls related to that module are disabled.

Queue

Queue module allows giving predefined time slots for vessels that are coming into the port. All nominated vessels gets automatically best possible time slots that are available in the port. Procedure is

Consignee make nomination for a vessel for a certain time range and for a certain berths

Berths

Berths

In this all port berths are defined. In this view you can

Add new berth
Edit berth
Delete berth
Make berth nominatable

Queue - Just-In-Time-Arrival

Queue

Queue view show status of queue. For each slot request there is visible

There is also status of slot request and berth name in list. Also statuses green “ok”, yellow “warning” and red “late” are displayed in this view to indicate current status of how vessel is meeting JIT ETA.

Nominations

Nominations

In this view you see all nominations made for vessels. This view is for any one with consignee permission where consignee sees his own nominations. You can

Add new nomination

Add nomination

Edit nomination
Delete nomination
Admin nominations

Admin nomination

This view is for administrators to view all nominations. Administrator can add, edit or delete all nominations.

Slot requests

Slot requests

In this view is list af all slot request and related information. Slot request are communicated with JIT-ETA form by vessels that are arriving to port. Slot request has following information:

Possible statuses and descriptions

Berth reservations

Berth reservations

In this view you see reservations per bert. Port can add berth blocks to block reservations for specific time into that berth.

Just-In-Time Web Form

Queue system requires that vessels inform their ETA with JIT Web Form. Web form default location is in URL https://yourappdomain.com/agent/eta/. Vessel fills up data and sends it and there is nomination for that vessel you will get email to confirm your request. Email is send into that email address given into field “E-mail address of person in charge”.

Empty form

Empty form

Example of filled form

Filled form

After send you will see confirmation

Form confirmed

Slot email

Form view to confirm and specify JIT ETA to given RTA window

Confirm RTA

Filled JIT ETA and confirmation message

Filled JIT ETA and confirmation message

And email confirmation of slot

Email confirmation of slot

Now vessel has confirmed slot and has place in queue to berth.

Sign out

Signs user out from application. When using shared computer sign out should be always performed since session time to live is days.

Mobile user interface

Separate mobile application are available for each port that is implemented this application. While writing this there are Port Activity Gävle and Port Activity Rauma applications for ready to install from Apple Store for iOS mart phones and from Play Store for Android smart phones. After installation of application is ready to use. Mobile application have only limited subset on functionality compared to web application. For basic users mobile application is main platform to use. All basic functionality required for port actors are there. You can follow port activity, follow logistics and use notifications for communication.

Login, registration and forgot password

Login, registration and forgot password work similar as in web version. Layout is just different.

Mobile login Mobile registration Mobile password

Activity

Mobile activity cards Mobile timeline Mobile activity actions

Activity view show first only card for each port call. Clicking card opens timeline of port call. When timeline is opened there is more functions on card. You can

Pin/Unpin vessel

When vessel is pinned you get notifications in to UI of changes for that vessel. If application is background in your smart phones you get push notification that is displayed on your smart phone. How push notifications are displayed in your phone depends on smart phone itself (iOS vs. Android vs. version of platform) and notification settings. There are many reasons why you may not get push notification to your smart phone. Eg. in case of low battery mode in Android platforms getting push notifications is disabled.

Ship information

Mobile ship information

Here you see briefly more vessel related information.

Add new timestamp

If you have enough permission you also can add timestamps manually

Mobile manual timestamp adding

Send notification

Notification related to vessel can send in this view

Mobile send notification

Queue

Mobile queue

Queue view show status of queue. For each slot request there is visible

There is also status of slot request and berth name in list. Also statuses green “ok”, yellow “warning” and red “late” are displayed in this view to indicate current status of how vessel is meeting JIT ETA.

Logistics

Mobile logistics

Logistics view shows similarly trucks passing gate as in web version. There are no other functionalities in logistics view.